Comment écrire des fichiers __init__.py de package correct / correct

Mon colis a la structure suivante:

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

Je ne sais pas comment les __init__.pyfichiers doivent être correctement écrits.
Le __init__.py #1ressemble à:

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

Mais à quoi devrait par exemple __init__.py #2ressembler? Le mien est:

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

Quand faut-il l' __all__utiliser?

__all__est très bon - il aide à guider les instructions d'importation sans importer automatiquement les modules http://docs.python.org/tutorial/modules.html#importing-from-a-package

en utilisant __all__et import *est redondant, seul __all__est nécessaire

Je pense que l'une des raisons les plus puissantes à utiliser import *dans un __init__.pypour importer des packages est de pouvoir refactoriser un script qui s'est développé en plusieurs scripts sans casser une application existante. Mais si vous concevez un package depuis le début. Je pense qu'il est préférable de laisser les __init__.pyfichiers vides.

par exemple:

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

puis l'application grandit et maintenant c'est un dossier entier

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

alors le script init peut 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

afin qu'un script écrit pour faire ce qui suit ne se casse pas pendant le changement:

from foo import fooFactory, tallFoo, shortFoo

Mes propres __init__.pyfichiers sont vides le plus souvent. En particulier, je n'ai jamais fait from blah import *partie de __init__.py- si "importer le package" signifie obtenir toutes sortes de classes, fonctions, etc. définies directement dans le cadre du package, alors je copierais lexicalement le contenu de blah.pydans le package à la __init__.pyplace et supprimerais blah.py( la multiplication des fichiers sources ne sert à rien ici).

Si vous insistez pour soutenir les import *idiomes (eek), alors utiliser __all__(avec une liste de noms aussi minuscule que vous pouvez vous en faire) peut aider à contrôler les dégâts. En général, les espaces de noms et les importations explicites sont de bonnes choses, et je suggère fortement de reconsidérer toute approche basée sur le contournement systématique de l'un ou des deux concepts! -)

Votre __init__.pydevrait avoir un docstring .

Bien que toutes les fonctionnalités soient implémentées dans des modules et des sous-packages, votre package docstring est l'endroit pour documenter où commencer. Par exemple, considérons le package pythonemail . La documentation du package est une introduction décrivant l'objectif, le contexte et la manière dont les différents composants du package fonctionnent ensemble. Si vous générez automatiquement de la documentation à partir de docstrings en utilisant sphinx ou un autre package, le package docstring est exactement le bon endroit pour décrire une telle introduction.

Pour tout autre contenu, consultez les excellentes réponses de Firecrow et Alex Martelli .