ฉันจะเขียนไฟล์ __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- ถ้า "นำเข้าแพคเกจ" หมายถึงการเรียงลำดับของการเรียน, ฟังก์ชั่นอื่น ๆ ที่กำหนดไว้โดยตรงเป็นส่วนหนึ่งของแพคเกจแล้วฉันจะ lexically คัดลอกเนื้อหาของblah.pyเป็นแพคเกจของ__init__.pyแทนและลบblah.py( การคูณไฟล์ต้นฉบับนั้นทำได้ไม่ดีเลย)

หากคุณยืนยันในการสนับสนุนimport *สำนวน (eek) ดังนั้นการใช้__all__(โดยย่อรายการรายชื่อให้มากที่สุดเท่าที่คุณสามารถนำมาใช้ได้) อาจช่วยควบคุมความเสียหายได้ โดยทั่วไปเนมสเปซและการนำเข้าที่ชัดเจนเป็นสิ่งที่ดีและฉันขอแนะนำให้ทบทวนวิธีการใด ๆ โดยอาศัยแนวคิดใดแนวคิดหนึ่งหรือทั้งสองอย่าง -!

คุณ__init__.pyควรจะมีdocstring

แม้ว่าฟังก์ชั่นทั้งหมดจะมีการใช้งานในโมดูลและแพ็คเกจย่อย docstring แพ็กเกจของคุณเป็นสถานที่ในการเริ่มต้นเอกสาร ตัวอย่างเช่นพิจารณาแพ็คเกจงูemailใหญ่ เอกสารประกอบแพ็กเกจเป็นการแนะนำที่อธิบายถึงวัตถุประสงค์เบื้องหลังและส่วนประกอบต่างๆภายในแพ็คเกจทำงานร่วมกันอย่างไร หากคุณสร้างเอกสารโดยอัตโนมัติจาก docstrings โดยใช้สฟิงซ์หรือแพคเกจอื่น docstring แพคเกจเป็นสถานที่ที่เหมาะสมที่จะอธิบายการแนะนำดังกล่าว

สำหรับเนื้อหาอื่น ๆ โปรดดูคำตอบที่ดีเยี่ยมโดยfirecrowและอเล็กซ์เทล