Come scrivo i file __init__.py del pacchetto corretto / corretto

Il mio pacchetto ha la seguente struttura:

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

Non sono sicuro di come i __init__.pyfile debbano essere scritti correttamente.
Gli __init__.py #1assomiglia:

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

Ma come dovrebbe __init__.py #2apparire ad esempio ? Il mio è:

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

Quando dovrebbe essere __all__usato?

__all__è molto buono - aiuta a guidare le dichiarazioni di importazione senza importare automaticamente i moduli http://docs.python.org/tutorial/modules.html#importing-from-a-package

utilizzando __all__ed import *è ridondante, __all__è necessario solo

Penso che uno dei motivi più potenti da utilizzare import *in un __init__.pypacchetto di importazione sia quello di essere in grado di refactoring uno script che è cresciuto in più script senza rompere un'applicazione esistente. Ma se stai progettando un pacchetto dall'inizio. Penso che sia meglio lasciare i __init__.pyfile vuoti.

per esempio:

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

quindi l'app cresce e ora è un'intera cartella

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

allora lo script init può dire

__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

in modo che uno script scritto per eseguire le seguenti operazioni non si interrompa durante la modifica:

from foo import fooFactory, tallFoo, shortFoo

I miei __init__.pyfile sono vuoti il ​​più delle volte. In particolare, non ho mai avuto una from blah import *parte di __init__.py- se "importare il pacchetto" significa ottenere tutti i tipi di classi, funzioni, ecc. Direttamente definiti come parte del pacchetto, quindi copierei lessicamente il contenuto del blah.pypacchetto __init__.pyinvece di rimuovere blah.py( la moltiplicazione dei file sorgente non va bene qui).

Se insisti nel sostenere gli import *idiomi (eek), usare __all__(con una minuscola lista di nomi che puoi farci avere) può aiutare a controllare i danni. In generale, gli spazi dei nomi e le importazioni esplicite sono buone cose e suggerisco vivamente di riconsiderare qualsiasi approccio basato sul bypass sistematico di uno o entrambi i concetti! -)

Il tuo __init__.pydovrebbe avere un docstring .

Sebbene tutte le funzionalità siano implementate in moduli e pacchetti secondari, il docstring del pacchetto è il luogo in cui documentare da dove iniziare. Ad esempio, considera il pacchetto pythonemail . La documentazione del pacchetto è un'introduzione che descrive lo scopo, lo sfondo e il modo in cui i vari componenti all'interno del pacchetto lavorano insieme. Se generi automaticamente documentazione da docstring usando sphinx o un altro pacchetto, il docstring del pacchetto è esattamente il posto giusto per descrivere una simile introduzione.

Per qualsiasi altro contenuto, vedere le risposte eccellenti di firecrow e Alex Martelli .