This is just an ugly/hygiene thing. Since we've never advertised the submodules as the API, we should be able to fix this by moving main.py to e.g. __main__.py.

I'm afraid that just because we don't advertise it doesn't mean it isn't used.  On the other hand, the split into submodules is relatively recent, so maybe we could get away with it without a deprecation cycle.  I'd like other developers opinions on that.

Numba subclasses unittest.main in order to add custom CLI options.
I agree the current unittest scheme is horrible, just we should find a way that's backwards-compatible.

One way would be to have an _main.py and have main.py "import *" (or equivalent) from it. We can't get rid of unittest.main being an alias for TestProgram - that's been around forever.

See also  https://github.com/testing-cabal/mock/issues/250

The modules seem to have existed since at least Python 3.2, so I think a proper DeprecationWarning is necessary for just one release.

The trick is going to be unittest.main since it seems code in the wild relies on it at least partially existing and Michael thinks it should stick around in some form or another. If the desire is there to limit the API for unittest.main compared to what it is now, either people have to go with stuff disappearing on users that get moved out to _main, or you have to do a somewhat evil import hack and turn unittest.main into an object with attributes which raise a DeprecationWarning for those objects you want to relocate and not for those you want to leave in place.

So unittest.main, the symbol, needs to exist.

What currently references unittest.main, the module, today?

AFAICT its only accessible vis sys.modules['unittest.main'] because of the shadowing.

Ah, I see my misunderstanding; when Antoine said "Numba subclasses unittest.main" I wasn't thinking and thought he meant something in unitest.main the module, not the unittest.main alias for unittest.main.TestProgram which is exposed as unitest.__init__.main (yeah, that name clash is nasty).

Then the unittest.main module can be treated like any other module in terms of deprecation and doesn't need any special-casing. Sorry about the mix-up on my end. So I say rename the modules to _*, add the deprecation to the old names in 3.6, and then remove the modules in 3.7.

Or deprecate in 3.5 if Larry will let you.