using __init__.py

I am having difficulty understanding the usage scenarios or design goals of python's __init__.py files in my projects.

Assume that I have 'model' directory (refers as a package) which contains the following files

1. __init__.py
2. meta.py
3. solrmodel.py
4. mongomodel.py
5. samodel.py

I found two ways of using __init__.py:

1. I have common a definition which needs to be used in solrmodel.py, mongomodel.py, samodel.py. Can I use __init__.py as a base/common definition for all the *model.py classes? This means that I have to import model/__init__.py.

2. Or, the __init__.py shall have imported definitions of solrmodel.py, mongomodel.py, samodel.py in its own and it allows the easy import of classes or function like this:

   # file: __init__.py
   
   from mongomodel import *
   from solrmodel import *
   from samodel import *
   

   (I am aware that import * is not recommended and I just used it as a convention)

I could not decide between above two scenarios. Are there more usage scenarios for __init__.py and can you explain the usage?

Solution 1:

The vast majority of the __init__.py files I write are empty, because many packages don't have anything to initialize.

One example in which I may want initialization is when at package-load time I want to read in a bunch of data once and for all (from files, a DB, or the web, say) -- in which case it's much nicer to put that reading in a private function in the package's __init__.py rather than have a separate "initialization module" and redundantly import that module from every single real module in the package (uselessly repetitive and error-prone: that's obviously a case in which relying on the language's guarantee that the package's __init__.py is loaded once before any module in the package is obviously much more Pythonic!).

For other concrete and authoritative expressions of opinion, look at the different approaches taken in the various packages that are part of Python's standard library.

Solution 2:

The contents of __init__.py are imported when you import a module within the package.

You're overlooking a third scenario, which is to put the common parts in a separate module and then have the other modules import that, leaving __init__.py for things that will be used outside the package. This is the practice I usually follow.