consider creating selene.api.__init__.py with all usually used selene pre-imports

[yashaka]

the idea is described as "option 3" in https://www.reddit.com/r/Python/comments/1bbbwk/whats_your_opinion_on_what_to_include_in_init_py/

Here are the main quotes:

122
What's your opinion on what to include in init.py ? (self.Python)
submitted 3 years ago * by barisumog
I'm new to packaging and publishing on PyPI. I've been searching for information about the best practices about modules and namespaces, and using init.py to manipulate them. Yet I haven't been able to find a generally accepted approach.

Considering a package with multiple modules (and possibly sub-packages), there seems to be 3 different approaches:

Leave the init.py blank. This enforces explicit imports and thus clear namespaces. I've read Alex Martelli post in favor of this option on various questions at Stack Overflow. The cons are, the user of the package has to import seperate modules and call them with the dot notation.

Import all modules in init.py. The user doesn't have to do multiple imports. The cons are explicit vs implicit, and also as Martelli puts it (paraphrased), "if that's how your package works, maybe it should all go in a single module anyway".

Import key functions from various modules directly into the package namespace. If you restructure modules, you still have the option to keep the same API for end users. Cons, it dirties the namespace, and very implicit / hacky.

[–]reostra 37 points 3 years ago
I tend toward option 3 for my own work. For me, it's about declaring a 'public' API for the module, e.g.

stuff/
init.py
bigstuff.py
privateStuff.py
And init.py would have:

from bigstuff import Stuffinator, Stuffinatrix
This essentially says that stuff.Stuffinator and stuff.Stuffinatrix are the only parts of the module intended for public use. While there's nothing stopping people from doing an 'import stuff.bigstuff.Stuffometer' or 'import stuff.privateStuff.HiddenStuff', they'll at least know they're peeking behind the curtain at that point. Rather than being implicit, I find it's rather explicit.

[–]zzzeeksqlalchemy mako 6 points 3 years ago
Option 3 is definitely how this should work, here's why. You start out with your library having a package "foo" and a module "bar". Users make use of things inside of "bar" like, from foo.bar import x, y, z. Then one day, "bar" starts getting really big, the implementations for things become more complex and broken out, features are added. The way you deal with this is by making bar.py into a package, and the init.py inside of bar/ essentially replaces bar.py. Your users see no change in API, and there's no need for them to learn exactly which submodule inside the new bar package they need to use (nor should there be, as things can keep changing many more times - it wouldn't be correct to expose the userbase to each of those changes when it's entirely unnecessary).

There's nothing hacky about this at all, it's how init.py is meant to be used, and to those saying "explicit is better than implicit" I'd counter with "practicality beats purity" and "flat is better than nested", not to mention a foolish consistency is the hobgoblin of little minds.