Como eu escrevo arquivos __init__.py de pacote corretos / corretos

Meu pacote tem a seguinte estrutura:

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
   ...

Não tenho certeza de como os __init__.pyarquivos devem ser escritos corretamente.
Os __init__.py #1parece:

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

Mas como deve ser, por exemplo __init__.py #2? O meu é:

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

Quando deve ser __all__usado?

__all__é muito bom - ajuda a orientar as instruções de importação sem importar automaticamente os módulos http://docs.python.org/tutorial/modules.html#importing-from-a-package

usando __all__e import *é redundante, apenas __all__é necessário

Eu acho que uma das razões mais poderosas para usar import *em um __init__.pypacote para importar é poder refatorar um script que cresceu em vários scripts sem quebrar um aplicativo existente. Mas se você estiver projetando um pacote desde o início. Eu acho que é melhor deixar os __init__.pyarquivos vazios.

por exemplo:

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

então o aplicativo cresce e agora é uma pasta inteira

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

então o script init pode dizer

__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 um script escrito para fazer o seguinte não seja interrompido durante a alteração:

from foo import fooFactory, tallFoo, shortFoo

Meus próprios __init__.pyarquivos estão vazios com mais frequência do que não. Em particular, eu nunca tenho um from blah import *como parte __init__.py- se "importar o pacote" significa obter todos os tipos de classes, funções etc definidas diretamente como parte do pacote, então eu copiava lexicamente o conteúdo do conteúdo blah.pypara o pacote __init__.pye o removia blah.py( a multiplicação dos arquivos de origem não serve aqui).

Se você insistir em apoiar os import *idiomas (eek), usar __all__(com uma lista tão minúscula de nomes quanto possível) pode ajudar a controlar os danos. Em geral, namespaces e importações explícitas são boas , e eu sugiro reconsiderar qualquer abordagem baseada em ignorar sistematicamente um ou ambos os conceitos! -)

Você __init__.pydeve ter uma doutrina .

Embora toda a funcionalidade seja implementada em módulos e subpacotes, a documentação do pacote é o local para documentar por onde começar. Por exemplo, considere o pacote pythonemail . A documentação do pacote é uma introdução que descreve a finalidade, os antecedentes e como os vários componentes do pacote funcionam juntos. Se você gerar automaticamente a documentação a partir de docstrings usando sphinx ou outro pacote, a docstring do pacote é exatamente o lugar certo para descrever essa introdução.

Para qualquer outro conteúdo, veja as excelentes respostas de firecrow e Alex Martelli .