Conventions and requirements for a python module

[Michael Torrie]

On 10/11/2016 08:29 AM, Michael Felt wrote:
>  From reading the python source, and other projects I am looking to 
> patch I see that there is often a file __init__.py, sometimes empty 
> (only comments), sometimes not.
> 
> I have tried looking in what I hope are the "regular" places such as: 
> https://docs.python.org, readthedocs (it took 454 seconds to build 
> something - what did it build, and where do I get it? I was assuming it 
> was "latest documentation" and I even tried the old, no-longer 
> maintained, wiki.
> 
> A search for __init__.py, except for on https://packaging.python.org/ 
> that talks about a setup command to extract the version from __init__.py 
> - I have not been able to find anything on "standards" for packages that 
> are more than a single .py file.
> 
> Probably, I am not looking correctly - however, I do hope someone also 
> notices that finding this is not straight forward for a novice in 
> python. Had I lacked curiosity I would have given up, moved on. Instead 
> - this email.

Yes all this is in the docs:
https://docs.python.org/3/tutorial/modules.html#packages

Also there are links that show up when searching google for "python
packages":
http://www.learnpython.org/en/Modules_and_Packages
http://docs.python-guide.org/en/latest/writing/structure/#packages

Packages are convenient for organizing code. Typically I put code into
__init__.py to organize the package's symbols. In other words whatever
symbols get imported when the package is imported are defined here.
Sometimes I'll import things from sub-modules from within __init__.py
and name and organize them.  Sometimes submodules are left on their own
to be imported separately.  Though the notation "from foo import *" is
discouraged, if a programmer is wont to do that, the package can limit
the damage somewhat by defining the __all__ variable.