Як написати гарний / правильний пакет __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

тоді сценарій init може сказати

__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 . Документація щодо пакета - це вступ, що описує мету, передумови та спосіб взаємодії різних компонентів у пакеті. Якщо ви автоматично генеруєте документацію з docstrings, використовуючи сфінкс або інший пакет, docstring пакету є саме правильним місцем для опису такого вступу.

Будь-який інший вміст дивіться у відмінні відповіді firecrow та Alex Martelli .