Как мне написать хорошие / правильные файлы пакета __init__.py

Моя посылка имеет следующую структуру:

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

Я не уверен, как __init__.pyфайлы должны быть правильно написаны.
В __init__.py #1выглядит следующим образом :

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

Но как, например, должно __init__.py #2выглядеть? Мой это:

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

Когда следует __all__использовать?

__all__это очень хорошо - это помогает направлять операторы импорта без автоматического импорта модулей http://docs.python.org/tutorial/modules.html#importing-from-a-package

использование __all__и import *является избыточным, __all__требуется только

Я думаю, что одной из наиболее веских причин для использования import *в __init__.pyимпорте пакетов является возможность рефакторинга сценария, который вырос в несколько сценариев, не нарушая существующее приложение. Но если вы разрабатываете пакет с самого начала. Я думаю, что лучше оставить __init__.pyфайлы пустыми.

например:

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

то приложение растет и теперь это целая папка

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

тогда скрипт инициализации может сказать

__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

чтобы сценарий, написанный для выполнения следующих действий, не прерывался во время изменения:

from foo import fooFactory, tallFoo, shortFoo

Мои собственные __init__.pyфайлы чаще всего пусты. В частности, у меня никогда не было from blah import *части __init__.py- если «импорт пакета» означает получение всех видов классов, функций и т. Д., Определенных непосредственно как часть пакета, то я бы вместо этого скопировал содержимое blah.pyв пакет __init__.pyи удалил blah.py( умножение исходных файлов здесь не годится).

Если вы настаиваете на поддержке import *идиом (eek), то использование __all__(с минимальным списком имен, который вы можете себе представить) может помочь в контроле за ущербом. В общем, пространства имен и явный импорт - это хорошо , и я настоятельно рекомендую пересмотреть любой подход, основанный на систематическом обходе одного или обоих понятий! -)

У тебя __init__.pyдолжна быть документальная строка .

Хотя вся функциональность реализована в модулях и подпакетах, строка документации вашего пакета - это то место, где нужно документировать, с чего начать. Например, рассмотрим пакет pythonemail . Документация пакета представляет собой введение, описывающее цель, фон и то, как различные компоненты в пакете работают вместе. Если вы автоматически генерируете документацию из строк документации, используя sphinx или другой пакет, пакет документации doc является именно тем местом, где можно описать такое введение.

Для любого другого контента, посмотрите отличные ответы от Firecrow и Alex Martelli .