Jak napisać dobry / poprawny pakiet __init__.py

Mój pakiet ma następującą strukturę:

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

Nie jestem pewien, jak __init__.pypliki powinny być poprawnie zapisane.
Do __init__.py #1wygląda następująco:

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

Ale jak na przykład powinien __init__.py #2wyglądać? Mój jest:

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

Kiedy należy __all__stosować?

__all__jest bardzo dobry - pomaga poprowadzić instrukcje importowania bez automatycznego importowania modułów http://docs.python.org/tutorial/modules.html#importing-from-a-package

użyciu __all__i import *jest zbędny, tylko __all__jest potrzebna

Myślę, że jednym z najpotężniejszych powodów do użycia import *w __init__.pycelu importowania pakietów jest możliwość refaktoryzacji skryptu, który rozrósł się do wielu skryptów bez zrywania istniejącej aplikacji. Ale jeśli projektujesz pakiet od samego początku. Myślę, że najlepiej zostawić __init__.pypliki puste.

na przykład:

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

wtedy aplikacja rośnie, a teraz jest to cały folder

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

wtedy skrypt init może powiedzieć

__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

aby skrypt napisany w celu wykonania następujących czynności nie ulegał awarii podczas zmiany:

from foo import fooFactory, tallFoo, shortFoo

Moje własne __init__.pypliki są puste częściej niż nie. W szczególności nigdy nie mam tego from blah import *jako część __init__.py- jeśli „importowanie pakietu” oznacza uzyskanie wszelkiego rodzaju klas, funkcji itp. Zdefiniowanych bezpośrednio jako część pakietu, to zamiast tego skopiowałbym leksykalnie zawartość blah.pypakietu __init__.pyi usunął blah.py( zwielokrotnienie plików źródłowych tutaj nie ma znaczenia).

Jeśli nalegasz na wspieranie import *idiomów (eek), to użycie __all__(z tak niewielką listą imion, jak tylko możesz się w nich znaleźć) może pomóc w kontrolowaniu szkód. Ogólnie rzecz biorąc, przestrzenie nazw i jawne importowanie to dobre rzeczy i zdecydowanie sugeruję ponowne rozważenie każdego podejścia opartego na systematycznym pomijaniu jednego lub obu pojęć! -)

Twój __init__.pypowinien mieć docstring .

Mimo że cała funkcjonalność jest zaimplementowana w modułach i podpakietach, dokumentowanie pakietu jest miejscem, w którym można rozpocząć dokumentowanie. Rozważmy na przykład pakiet pythonemail . Dokumentacja pakietu jest wstępem opisującym cel, tło oraz sposób współpracy różnych komponentów w pakiecie. Jeśli automatycznie generujesz dokumentację z dokumentów w postaci sfinksa lub innego pakietu, dokumentacja pakietu jest właściwym miejscem do opisania takiego wprowadzenia.

W przypadku innych treści zobacz doskonałe odpowiedzi firecrow i Alex Martelli .