Bagaimana cara menulis file __init__.py paket yang baik / benar

Paket saya memiliki struktur berikut:

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

Saya tidak yakin bagaimana __init__.pyfile harus ditulis dengan benar.
The __init__.py #1terlihat seperti:

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

Tetapi bagaimana seharusnya misalnya __init__.py #2terlihat seperti? Punya saya:

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

Kapan sebaiknya __all__digunakan?

__all__sangat baik - ini membantu memandu pernyataan impor tanpa secara otomatis mengimpor modul http://docs.python.org/tutorial/modules.html#importing-from-a-package

menggunakan __all__dan import *berlebihan, hanya __all__diperlukan

Saya pikir salah satu alasan paling kuat untuk digunakan import *dalam __init__.pymengimpor paket adalah untuk dapat membuat ulang skrip yang telah berkembang menjadi banyak skrip tanpa merusak aplikasi yang ada. Tetapi jika Anda merancang paket dari awal. Saya pikir yang terbaik adalah membiarkan __init__.pyfile kosong.

sebagai contoh:

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

lalu aplikasi tumbuh dan sekarang menjadi seluruh folder

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

maka skrip init dapat mengatakan

__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

sehingga skrip yang ditulis untuk melakukan hal berikut tidak rusak selama perubahan:

from foo import fooFactory, tallFoo, shortFoo

__init__.pyFile saya sendiri kosong lebih sering daripada tidak. Secara khusus, saya tidak pernah memiliki from blah import *sebagai bagian dari __init__.py- jika "mengimpor paket" berarti mendapatkan semua jenis kelas, fungsi dll yang didefinisikan langsung sebagai bagian dari paket, maka saya akan secara leksikal menyalin konten blah.pyke dalam paket __init__.pysebagai gantinya dan menghapus blah.py( perbanyakan file sumber tidak ada gunanya di sini).

Jika Anda bersikeras mendukung import *idiom (eek), kemudian menggunakan __all__(dengan sangat kecil daftar nama yang dapat Anda bawa sendiri) dapat membantu untuk pengendalian kerusakan. Secara umum, ruang nama dan impor eksplisit adalah hal yang baik , dan saya sangat menyarankan untuk mempertimbangkan kembali setiap pendekatan berdasarkan secara sistematis melewati salah satu atau kedua konsep! -)

Anda __init__.pyharus memiliki docstring .

Meskipun semua fungsi diimplementasikan dalam modul dan subpackages, paket dokumentasi Anda adalah tempat untuk mendokumentasikan tempat untuk memulai. Sebagai contoh, pertimbangkan paket pythonemail . Dokumentasi paket adalah pengantar yang menjelaskan tujuan, latar belakang, dan bagaimana berbagai komponen dalam paket bekerja bersama. Jika Anda secara otomatis membuat dokumentasi dari dokumen menggunakan sphinx atau paket lain, paket dokumentasi tersebut adalah tempat yang tepat untuk menggambarkan pengantar tersebut.

Untuk konten lain, lihat jawaban yang sangat bagus dari firecrow dan Alex Martelli .