¿Cómo escribo archivos de paquete __init__.py buenos / correctos

Mi paquete tiene la siguiente estructura:

mobilescouter/
    __init__.py #1
    mapper/
        __init__.py  #2
        lxml/
            __init__.py #3
            vehiclemapper.py
            vehiclefeaturemapper.py
            vehiclefeaturesetmapper.py
        ...
        basemapper.py
   vehicle/
        __init__.py #4
        vehicle.py
        vehiclefeature.py
        vehiclefeaturemapper.py
   ...

No estoy seguro de cómo se __init__.pydeben escribir correctamente los archivos.
El se __init__.py #1parece a:

__all__ = ['mapper', 'vehicle']
import mapper
import vehicle

Pero, ¿cómo debería ser, por ejemplo __init__.py #2? El mio es:

__all__ = ['basemapper', 'lxml']
from basemaper import *
import lxml

¿Cuándo se debe __all__usar?

__all__es muy bueno: ayuda a guiar las declaraciones de importación sin importar automáticamente los módulos http://docs.python.org/tutorial/modules.html#importing-from-a-package

usando __all__y import *es redundante, solo __all__es necesario

Creo que una de las razones más poderosas para usar import *en la __init__.pyimportación de paquetes es poder refactorizar un script que se ha convertido en múltiples scripts sin romper una aplicación existente. Pero si está diseñando un paquete desde el principio. Creo que es mejor dejar los __init__.pyarchivos vacíos.

por ejemplo:

foo.py - contains classes related to foo such as fooFactory, tallFoo, shortFoo

entonces la aplicación crece y ahora es una carpeta completa

foo/
    __init__.py
    foofactories.py
    tallFoos.py
    shortfoos.py
    mediumfoos.py
    santaslittlehelperfoo.py
    superawsomefoo.py
    anotherfoo.py

entonces el guión de inicio puede decir

__all__ = ['foofactories', 'tallFoos', 'shortfoos', 'medumfoos',
           'santaslittlehelperfoo', 'superawsomefoo', 'anotherfoo']
# deprecated to keep older scripts who import this from breaking
from foo.foofactories import fooFactory
from foo.tallfoos import tallFoo
from foo.shortfoos import shortFoo

para que un script escrito para hacer lo siguiente no se rompa durante el cambio:

from foo import fooFactory, tallFoo, shortFoo

Mis propios __init__.pyarchivos están vacíos la mayoría de las veces. En particular, nunca tengo un from blah import *como parte de __init__.py: si "importar el paquete" significa obtener todo tipo de clases, funciones, etc., definidas directamente como parte del paquete, entonces copiaría léxicamente el contenido del blah.pypaquete __init__.pyy lo eliminaría blah.py( la multiplicación de los archivos fuente no sirve de nada aquí).

Si insiste en apoyar las import *expresiones idiomáticas (eek), usar __all__(con una lista de nombres tan minúscula como pueda tener) puede ayudar a controlar el daño. En general, los espacios de nombres y las importaciones explícitas son cosas buenas , ¡y sugiero que reconsidere cualquier enfoque basado en omitir sistemáticamente uno o ambos conceptos! -)

Su __init__.pydebe tener una cadena de documentación .

Aunque toda la funcionalidad se implementa en módulos y subpaquetes, la cadena de documentación de su paquete es el lugar para documentar dónde comenzar. Por ejemplo, considere el paquete pythonemail . La documentación del paquete es una introducción que describe el propósito, los antecedentes y cómo los diversos componentes dentro del paquete funcionan juntos. Si genera automáticamente documentación de cadenas de documentos utilizando sphinx u otro paquete, la cadena de documentos del paquete es exactamente el lugar adecuado para describir dicha introducción.

Para cualquier otro contenido, vea las excelentes respuestas de firecrow y Alex Martelli .