How to use __init__.py in (sub-)modules to define namespaces?

Question

my question is about writing Python (3.x) packages and (sub-)modules and the correct usage of __init__.py files to declare namespaces.
I used to code in C++, so I like to use a lot of separate files to organize projects. For example, (imo) if a module contains several classes, each of these should be in a separate file.

As I am inexperienced developing in Python, it is hard to formulate my thoughts in a simple question. So let's consider the following small python package as an example.

Directory layout

dir
 |
 +-- example
 |    |
 |    +-- script.py
 |
 +-- package
      |
      +-- __init__.py
      |
      +-- foo.py
      |
      +-- subpackage
           |
           +-- __init__.py
           |
           +-- bar.py

Let's have a look at the files.

File Content

package/foo.py:

def foo:
    print('foo')

package/subpackage/bar.py:

def bar:
    print('bar')

The following example/script.py works fine.

import sys
sys.path.insert(0, '..')

import package
import package.subpackage


package.foo.foo()
package.subpackage.bar.bar()

I don't like to use package.foo.foo() / package.subpackage.bar.bar() and would like to use package.foo() / package.subpackage.bar().

And I don't want to use from package.subpackage.bar import bar, as I don't want to mix the namespace of subpackage into script.

Solution

I used the __init__.py files to achieve that.

package/__init__.py:

from package.foo import foo

package/subpackage/__init__.py:

from package.subpackage.bar import bar

Questions

• Is this a good python-like way to define namespaces? Or is there a better / common way to organize the file-system of a package in python. (I did not find a proper tutorial/example for this.)

• In file package/subpackage/__init__.py, why does it have to be:

  from package.subpackage.bar import bar

  and not:

  from subpackage.bar import bar?

This would result in the error:

Traceback (most recent call last):
File "script.py", line x, in <module>
import package.subpackage
File "..\package\subpackage\__init__.py", line x, in <module>
from subpackage.bar import bar
ImportError: No module named 'subpackage'

Answer 1

Is this a good python-like way to define namespaces? Or is there a better / common way to organize the file-system of a package in python. (I did not find a proper tutorial/example for this.)

This is an okay way to setup a Python package. Only okay and not 'good' because of the contents of foo.py and bar.py.

I don't like to use package.foo.foo() / package.subpackage.bar.bar() and would like to use package.foo() / package.subpackage.bar().

In this case, you can't. And not mixing the name spaces is good reason to not do from package.subpackage.bar import bar.

It would have been better if def foo(): ... and def bar(): ... were directly in __init__.py. That way, you could have done package.foo() and package.subpackage.bar(). It could also have been done by using __all__ in init but import * is also not considered good.

Or, the foo and bar packages should have had more in it like foo.function1, foo.other_func, bar.drink, etc. which gives it more human-friendly understandable organisation.

Examples and references are not within scope for good StackOverflow questions but here are some, for a well thought-out question:

• Structuring Your Project — The Hitchhiker's Guide to Python
• The Pythonic way of organizing modules and packages
• How to organize a Python Project?