Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #11073 > unrolled thread

__all__

Back to article view | Back to comp.lang.python

Contents

  __all__ Ethan Furman <ethan@stoneleaf.us> - 2011-08-09 09:34 -0700
    Re: __all__ Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-08-10 02:57 +1000
      Re: __all__ Ethan Furman <ethan@stoneleaf.us> - 2011-08-12 13:15 -0700

#11073 — __all__

Greetings!

Does anyone know/recall the original purpose of __all__?

I had thought it was primarily to specify what would be imported when 
`from ... import *` was executed, such as for tk;  today, it seems it is 
also used to specify the API for the module, and so the help() subsystem 
will only provide details for those items found in __all__.

The issue I'm having with this is that there are roughly a dozen items I 
would like to make available via the `import *` mechanism in my dbf 
module, and another dozen that, while part of the public API, don't need 
to be available via an `import *`.

History lessons, as well as ideas, welcomed!

~Ethan~

[toc] | [next] | [standalone]

#11074

Ethan Furman wrote:

> Greetings!
> 
> Does anyone know/recall the original purpose of __all__?

To customise the names available for `from ... import *`:

http://docs.python.org/whatsnew/2.1.html#other-changes-and-fixes


> I had thought it was primarily to specify what would be imported when
> `from ... import *` was executed, such as for tk;  

Yes, that was the original use. If __all__ is not defined, Python will
import everything that doesn't start with an underscore.


> today, it seems it is 
> also used to specify the API for the module, and so the help() subsystem
> will only provide details for those items found in __all__.

The two meanings are assumed to be synonymous: names in the public API
should be importable with *, and importable names should be in the public
API. You can't specify "this can be imported with *, but isn't public"
or "this is public, but not importable with *".

http://docs.python.org/reference/simple_stmts.html#index-1090


Also, the behaviour of __all__ with packages may be slightly different:

http://docs.python.org/tutorial/modules.html#index-1134

 
> The issue I'm having with this is that there are roughly a dozen items I
> would like to make available via the `import *` mechanism in my dbf
> module, and another dozen that, while part of the public API, don't need
> to be available via an `import *`.

You have to choose both, or neither, but you can't have just one.



-- 
Steven

[toc] | [prev] | [next] | [standalone]

#11301

Paul Woolcock wrote:
> The gurus will have to correct me if this is not an accepted practice, 
> but I know some projects (Fabric is the one that comes to mind) will 
> define a submodule specifically for the 'from blah import *' situation. 
> The submodule would be called "api", or something like that, so you can 
> do: 'from mymodule.api import *' to separate the items you want to 
> include in your public api, while still keeping other names importable 
> by 'import blah'

Have I said lately how much I *love* Python?  Programming is fun again!

Thanks, Paul, that was the clue I needed.  Had to do some thinking since 
dbf is back to a single module, and no longer a package... here's what I 
came up with:

-------------------------------------------------------------
class fake_module(object):
     def __init__(self, name, *args):
         self.name = name
         self.__all__ = []
         for func in args:
             name = func.__name__
             self.__dict__[name] = func
             self.__all__.append(name)
     def register(self):
         sys.modules["%s.%s" % (__name__, self.name)] = self
-------------------------------------------------------------

then in my module (towards the bottom since I have to have all my 
functions/classes written that I want to include) I can have

fake_module('api', class1, class2, func1, exception1).register()

Now somebody else who wants to include the classes, exceptions, etc, 
that make up the primary part of the dbf module can do

from dbf.api import *

but

help(dbf)

will continue to list all the other public utility stuff (defined in 
dbf.__all__) normally.

Thanks to all!

~Ethan~

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web