良い/正しいパッケージ__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持つべきドキュメンテーション文字列を。

すべての機能はモジュールとサブパッケージに実装されていますが、パッケージのdocstringは、どこから開始するかを文書化する場所です。たとえば、python emailパッケージを考えてみましょう。パッケージのドキュメントは、目的、背景、およびパッケージ内のさまざまなコンポーネントがどのように連携するかを説明する概要です。sphinxまたは別のパッケージを使用してdocstringからドキュメントを自動的に生成する場合、パッケージdocstringは、そのような概要を説明するのにぴったりの場所です。

その他のコンテンツについては、firecrowとAlex Martelliによる優れた回答を参照してください。