Esistono regole per nominare i pacchetti Python a modulo singolo?

Question

Se il nome che do al modulo solitario in un pacchetto Python corrisponde al nome del pacchetto?

Per esempio se ho un pacchetto con un unico modulo con la struttura

super-duper/ 
    super/ 
     __init.py___ 
     mycode.py 
     ... 

posso creare un pacchetto super-duper su Cheese Shop, che, una volta installato, avrà due cartelle in site-packages con nomi che non lo fanno partita:

super/ 
super_duper-1.2.3.dist-info/ 

il che significa che per importare il mio progetto che uso

import super 

piuttosto che il nome del pacchetto attuale (super_duper)

questo sembra essere contro la pratica comune (a giudicare dalle cartelle per i primi di ogni altro pacchetto che vedo in site-packages) che seguono il modello

same_name/ 
same_name-1.2.3.dist-info/ 

per la Pacchetto PyPi same-name.

Devo invece (sempre) strutturare i miei progetti in modo da

super-duper/ 
    super_duper/ 
     __init.py___ 
     mycode.py 
     ... 

per garantire che il nome del pacchetto e il modulo nome di importazione "partita":

import super_duper 

C'è una buona pratica rilevante o regola che dovrei seguire?

Answer 1

La risposta breve alla tua domanda è: (. Che dovrebbe essere pacchetti più diffusa) sì, è generalmente una buona pratica per avere il nome del modulo corrisponde al nome del pacchetto per i pacchetti singoli moduli

Il la risposta leggermente più lunga è che le convenzioni di denominazione sono sempre politiche. Il metodo generalmente accettato per la definizione degli standard linguistici in Python è un processo chiamato "Python Enhancement Proposals" (PEP). I PEP sono governati da un corpo di editor PEP e sono publicly indexed per la revisione e il commento.

Allo stato attuale, non v'è una sola (accettato e implementato) PEP "Active" Sono a conoscenza di che copre le convenzioni modulo di denominazione, che è PEP 8:

I moduli dovrebbero avere nomi brevi e all-in minuscolo . I caratteri di sottolineatura possono essere utilizzati nel nome del modulo se migliora la leggibilità.I pacchetti Python dovrebbero anche avere nomi brevi, tutti minuscoli, anche se l'uso dei caratteri di sottolineatura è sconsigliato.

Tuttavia, c'è un'altra proposta ancora in fase di redazione chiamato PEP 423 che consiglia esattamente quello che stato nel tuo post:

distribuire solo un unico pacchetto (o solo un modulo) per progetto, e l'uso nome del pacchetto (o modulo) come nome del progetto.

• Evita la possibile confusione tra nome del progetto e pacchetto distribuito o nome del modulo.

• Rende coerente il nome.

• È esplicito: quando si vede il nome del progetto, indovina il nome del pacchetto/modulo e viceversa.

• Limita anche le interferenze implicite tra i nomi di pacchetti/moduli. Utilizzando un singolo nome, quando si registra un nome di progetto in PyPI, si esegue anche una verifica della disponibilità del nome del modulo/modulo di base .

È importante notare che questo PEP è ancora in uno stato "passivi", che significa che ha non ratificati dalla redazione PEP, ed è bloccato da un'altra proposta (in particolare l'attuazione un aggiornamento della sintassi dei metadati del modulo in PEP 440). Tuttavia, dal momento che la proposta originale del 423 non è stata elaborata alcuna norma concorrente, e gran parte del contenuto sembra essere abbastanza incontrovertibile, quindi mi aspetterei che venga accettata in futuro senza troppi cambiamenti importanti.

Answer 2

Hai l'idea giusta. la convenzione che ho visto usare il più delle volte, e che ha funzionato bene per me è:

/superduper 
    /superduper 
     __init__.py 
     code.py 
    /.git 
    setup.py 
    README.rst 

troverete che la maggior parte sviluppatori Python preferiscono tutto minuscolo, senza caratteri speciali per i nomi dei moduli (setuptools, pexpect, matplotlib, ecc.).
La cartella del progetto di primo livello deve corrispondere anche al nome del repository git, in modo che non cambi quando si esegue il clone.

il mio miglior consiglio, è dare un'occhiata alla fonte da alcuni progetti ben consolidati e imitare ciò che hanno fatto.

Answer 3

Da PEP 8:

Override Principio

nomi che sono visibili all'utente come parti pubbliche della API dovrebbero seguire le convenzioni che riflettono l'uso piuttosto che di attuazione.

confezione e la denominazione dei moduli

moduli dovrebbero avere nomi brevi e tutto in minuscolo. I caratteri di sottolineatura possono essere utilizzati nel nome del modulo se migliora la leggibilità. I pacchetti Python dovrebbero anche avere nomi brevi, tutti minuscoli, sebbene l'uso dei caratteri di sottolineatura sia scoraggiato.

L'unica cosa che sembra riguardare la tua domanda è che i caratteri di sottolineatura nei nomi dei pacchetti sono scoraggiati.

Al momento non ci sono altre persone politicamente esposte nelle opere per affrontare alcune delle incongruenze nella confezione Python in generale (426, 423), ma fino a quando questi sono risolti vorrei andare con ciò che rende più senso sotto PEP 20. Se lo standard super è sufficiente a trasmettere ciò che viene importato, sarei propenso a seguirlo (anche se, in questo caso, perché non utilizzarlo anche per il nome del pacchetto PyPi?).

Non credo che la convenzione imponga loro di essere la stessa cosa, ma in pratica cercano entrambi di raggiungere lo stesso obiettivo, finendo così nella stessa misura nella maggior parte dei casi.

Answer 4

Non ci sono linee guida di cui sono a conoscenza che richiedono che il nome del progetto corrisponda al pacchetto o al modulo installato. C'è un deferred draft PEP-423 Naming conventions and recipes related to packaging, ma questo è effettivamente abbandonato (uno pending update non è mai stato applicato).

Tu dici hai guardato, ma probabilmente perso alcuni esempi esistenti in cui il nome del progetto e del pacchetto contenuti non coincidono:

• Il BeautifulSoup project utilizza beautifulsoup4 per il nome del progetto in PyPI, che installa il pacchetto bs4 .

• Il dateutil Python package è disponibile su PyPI come python-dateutil. La prefissazione dei nomi dei progetti PyPI con python- è abbastanza comune, ho contato 1512 pacchetti di questo tipo su PyPI oggi.

• Il Viivakoodi project è un fork di pyBarcode. Il loro viivakoodi PyPI project installa un pacchetto barcode in site-packages. Un altro progetto di fork di questo tipo è Pillow, che è un fork della libreria di immagini Python. È disponibile su PyPI under that name ma il pacchetto installa il pacchetto PIL.

Detto questo, personalmente lo preferisco per il nome del progetto PyPI e il pacchetto contenuto da abbinare; riduce la confusione. L'eccezione più notevole è rappresentata dalle forcelle di progetto in cui lo scopo è mantenere il vecchio nome del pacchetto per facilitare la migrazione.