7

I use __init__.py to run checks when I do from myprojects.something import blabla.

Today I started using pyzmq and I wanted to see what's going on behind the scenes. So I browsed the code in github and I find (for me) some strange usage of __init__.py there that I cannot explain myself.

For example zmq/core/__init__.py. What's the point of adding in zmq.core.__all__ the __all__'s value of zmq.core.constants, zmq.core.error, zmq.core.message, etc.?

In zmq/__init__.py I see at the end

__all__ = ['get_includes'] + core.__all__

where get_includes is a function which basically returns a list with the directory of the module and the utils directory in the parent directory.

What's the point of that? What has __init.py__ achieved by doing that?

1 Answer 1

14

The __all__ is for when someone does from module import * as documented here.

The only solution is for the package author to provide an explicit index of the package. The import statement uses the following convention: if a package’s __init__.py code defines a list named __all__, it is taken to be the list of module names that should be imported when from package import * is encountered. It is up to the package author to keep this list up-to-date when a new version of the package is released. Package authors may also decide not to support it, if they don’t see a use for importing * from their package. For example, the file sounds/effects/__init__.py could contain the following code:

__all__ = ["echo", "surround", "reverse"]

This would mean that from sound.effects import * would import the three named submodules of the sound package.

One use for __all__ is a tool for package builders to allow them to structure their package in a way that works for them while making it convenient for users. Specifically in the case of pyzmq, it lets you write code such as:

import zmq
print zmq.zmq_version()

Rather than having to use the full dotted module name:

print zmq.core.version.zmq_version()

The package designers of pyzmq are using __all__ to promote namespace elements from nested modules up to the top level of their namespace so the user isn't bothered by the structure of their package.

4
  • I've read this part of the documentation before asking here. But this still does not answer my question. Perhaps I should ask in another way: I though that the reason for using from bla import ble was that you had controll over your namespace, meaning that you decide which symbols you add to your namesapce.
    – Pablo
    Commented Sep 21, 2012 at 0:43
  • As in contrast of C where using #include might cause collision with already defined functions, variables etc. you should only import the symbols you really need. I though I read somewhere in the python documentation that using from bla import * was not a good habit. If so, then why bother defining __ all__ at all? And how does __all__ = ['get_includes'] + core.__all__ get evaluated when doing a import *?
    – Pablo
    Commented Sep 21, 2012 at 0:44
  • 1
    from bla import * is not a good habit to be in, but there are some modules for which that is generally safe. I routinely do from math import *. The documentation of those modules often points out that they are designed to be used that way and they support niceties like all to make it a bit easier. But from x import * is stil something to be used with caution and only with packages where you know it won't cause a problem. Commented Sep 21, 2012 at 16:00
  • @John Gaines Jr: your last edit make a lot of sense. I asked myself why I was able to use zmq.REQ even though REQ is defined in core.constants. Thanks for sharing that.
    – Pablo
    Commented Sep 21, 2012 at 22:36

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.