API di un pacchetto in python. In __init__.py?

Question

Ho scritto un pacchetto python che consiste di diversi file .py che contengono classi e così via. Voglio esporlo al cliente usando il modello "Facciata". Quindi non voglio che i client imparino tutte le classi interne ma solo i metodi esposti da questa interfaccia API.

La domanda è: dove inserisco questa API? Definisco un file api.py all'interno del pacchetto o posso inserire questa API nello __init__.py del pacchetto?

spiego meglio con un esempio

<my_module>\ 
    __init__.py 
    core.py 
    submodule1.py 
    submodule2.py 
    util.py 
    ........ 

così dove metto l'API pubblica di?

Answer 1

La scelta più comune è usare __init__.py - vale la pena di passare a un modulo a sé stante (o più) solo se è abbastanza complesso da giustificarlo (quindi non sarebbe molto di una facciata ;-) o, cosa più importante, se si forniscono API alternative (una semplificata con funzionalità ridotte ma una maggiore facilità d'uso, e una ricca/complessa, per esempio), nel qual caso l'utilizzo di moduli separati mantiene le cose meglio organizzate.

Per comunicare per confezionare gli utenti che stanno non dovrebbe importare altri moduli direttamente, assicurati di nominare le "moduli di implementazione interne private" con un leader sottolineatura: _core.py, non core.py, e così via . Questa convenzione viene sempre utilizzata in Python per separare le API pubbliche dai dettagli di implementazione interni e vale la pena (davvero piccola) di implementarla!

Answer 2

Il file __init__.py è un luogo accettabile per inserire l'API pubblica o un pacchetto, con gli altri moduli al suo interno che forniscono l'implementazione.

Answer 3

Ci sono svantaggi a portare gli api in __init__.py:

• v'è il pericolo di causare dipendenze ciclabili
• non è un posto più ovvio per cercare durante la navigazione una base di codice

Mettere l'api in un modulo dedicato come api.py eleva questi problemi. Inoltre, ci sono vantaggi come:

• si può offrire un altro api successivamente in un secondo modulo (semplificato, caso diverso utilizzo ecc)
• grandi progetti Python come Enthought traits.api e Trac trac.api uso questo schema