Dettagli su come distribuire moduli Python

Premessa

Ieri ho confezionato e caricato la mia libreria di elaborazione dei file VASP su PyPI, ora è possibile installare VASPy direttamente tramite pip e easy_install (e benvenuti a stelle e partecipazione, cari studenti di chimica computazionale che utilizzano VASP),

Indirizzo GotHub di VASPy:https://github.com/PytLab/VASPy
Indirizzo PyPI di VASPy:https://pypi.python.org/pypi/vaspy/

Poiché la mia memoria non è molto buona, temo di dimenticarmi tutto dopo un po', quindi qui, mentre è ancora caldo, utilizzerò il mio programma VASPy come esempio per fare una sommarizzazione della confezione e del caricamento di Python.

Struttura dei file del pacchetto VASPy

Prima di tutto, scrivere l'intera struttura dei file del pacchetto VASPy, il contenuto successivo è illustrato a questo esempio:

VASPy/
├── LICENSE
├── MANIFEST
├── MANIFEST.in
├── README.rst
├── requirements.txt
├── scripts
│  ├── change_incar_parameters.py
│  ├── create_inputs.py
│  └── ...
├── setup.cfg
├── setup.py
├── tests
│  ├── incar_test.py
│  ├── __init__.py
│  ├── oszicar_test.py
│  ├── outcar_test.py
│  ├── testdata
│  │  ├── CONTCAR
│  │  ├── DOS_SUM
│  │  ├── ELFCAR
│  │  └── ...
│  └── ...
└── vaspy
  ├── __init__.py
  ├── iter.py
  ├── matstudio.py
  └── ...
4 directory, 54 file

Strumenti per il pacchettamento e l'installazione di pacchetti di terze parti

In questo caso, dobbiamo utilizzare strumenti come setuptools e pip per il pacchettamento, il rilascio e l'installazione del nostro pacchetto. Se è necessario costruire un pacchetto wheel, è necessario anche installare il modulo wheel. Se la versione di python è >= 2.7.9 o >= 3.4, setuptools e pip sono già installati, potrebbe essere necessario aggiornarli alla versione più recente

pip install -U pip setuptools

Puoi utilizzare strumenti di gestione dei pacchetti, ad esempio

yum install pip
sudo apt-get install pip

Installato tramite lo script get-pip.py, se viene rilevato che wheel e setuptools non sono installati, verranno installati automaticamente

python get-pip.py

Non parlerò molto dei strumenti specifici di installazione e della loro introduzione, puoi consultare le richieste per l'installazione dei pacchetti

Il ruolo dei diversi file nel pacchetto

setup.py

Questo file è il file più importante per il pacchettamento dell'intero progetto, poiché contiene due funzionalità principali:

La funzione setup(), i parametri di questa funzione specificano come configurare il proprio progetto.
Strumenti di riga di comando, inclusi il pacchettamento, il test e il rilascio. Puoi vedere i comandi di seguito;

python setup.py --help-commands

setup.cfg

Questo file contiene alcuni parametri predefiniti per la costruzione, come il parametro --universal quando si costruisce bdist_wheel

[bdist_wheel]
universal=1

In questo modo, ogni volta che pacchettizzerai, verrà utilizzato automaticamente il parametro --universal, con un effetto simile a:

python setup.py bdist_wheel --universal

README.rst

Questo inizialmente è stato scritto in markdown, dopo averlo pacchettizzato e pubblicato su PyPI, ho scoperto che PyPI non supporta la renderizzazione di markdown, la pagina era incautamente confusa, quindi ho riscritto tutto usando la sintassi di reStructuredText. Dopo tutto, la sintassi dei linguaggi di markup è abbastanza intuitiva, se non altro si può sempre copiare un modello e fare come un pipistrello.
Le regole di sintassi di reStructureText possono essere consultate nel documento ufficiale: Quick reStructuredText

In realtà, c'è un altro metodo che consiste nell'utilizzare pandoc per convertire markdown in formato rst, un modo comodo è utilizzare il modulo pyandoc per convertire automaticamente in formato rst al momento del rilascio.
Il metodo specifico può essere consultato: Use Markdown README's in Python modules

MANIFEST.in

Questo file, durante il pacchettamento, informa setuptools di quali file devono essere pacchettizzati in modo aggiuntivo, ad esempio, nel mio VASPy ho incluso i file di dati di test dei test unitari utilizzando questo file per includerli. Naturalmente, README, LICENSE e altri possono essere pacchettizzati insieme utilizzando questo strumento.
Di seguito è riportato il mio contenuto di MANIFEST.in:

include README.rst
include requirements.txt
include LICENSE
recursive-include scripts *
recursive-include tests *

Le regole di sintassi specifiche possono essere consultate: The MANIFEST.in template

vaspy/

Questa cartella è il pacchetto in cui si trova il codice sorgente di vaspy.

tests/

Questa cartella è anche un sottopacchetto che contiene script di test unitari, per poter utilizzare python setup.py test per i test unitari, è stato aggiunto __init__.py per renderla un pacchetto.

parametri di setup()

In questo articolo verranno descritti solo alcuni dei parametri che utilizzo, per l'uso specifico degli altri parametri fare riferimento a:https://docs.python.org/3/distutils/setupscript.html

name

versions = "vaspy"

È il nome del progetto completo, che verrà utilizzato insieme al numero di versione durante il pacchettamento.

version

from vaspy import __version__
version = __version__

description

È una descrizione breve del progetto, generalmente in una frase, e verrà visualizzata sotto il nome del progetto su PyPI.

long_description

È una descrizione lunga, equivalente a una presentazione concisa del progetto, se questa stringa è in formato rst, PyPI la renderà automaticamente in HTML per la visualizzazione. È possibile leggere direttamente il contenuto di README.rst.

url

Collegamento al pacchetto, di solito un link su GitHub o su readthedocs.

packages

Elenco dei pacchetti da includere, setuptools fornisce find_packages() per trovare i pacchetti nella directory di root, una funzione che distutil non ha.

setup_requires

Questo parametro definisce altre dipendenze necessarie per l'installazione e il funzionamento corretto di VASPy (le più basilari), che vengono installate utilizzando pip.
Per informazioni sulla differenza tra questo parametro e requirements.txt, consultare: install_requires vs Files di richieste

classifier

Questo parametro fornisce una serie di categorie, che su PyPI vengono inserite in directory diverse per classificare i progetti.
Per i nomi e le regole specifiche delle categories, consultare:https://pypi.python.org/pypi?%3Aaction=list_classifiers

test_suite

Questo parametro ci aiuta a usare

python setup.py test

Per eseguire test unitari, non è più necessario scrivere uno script separato come run_tests.py per eseguire i test unitari.
La spiegazione ufficiale di questo parametro:

Un nome per una sottoclasse di unittest.TestCase (o un pacchetto o modulo che contiene uno o più di essi, o un metodo di tale sottoclasse), o che nomina una funzione che può essere chiamata senza argomenti e che restituisce un unittest.TestSuite. Se la suite denominata è un modulo e il modulo ha una funzione additional_tests(), questa viene chiamata e i risultati vengono aggiunti ai test da eseguire. Se la suite denominata è un pacchetto, qualsiasi sottomodulo e sottopacchetto vengono aggiunti ricorsivamente al test suite complessivo.

Quindi questo parametro può accettare vari tipi di parametri:

Ricezione di una sottoclasse di unittest.TestCase, possiamo scrivere tutti i test unitari in un caso di test, importarlo e passarlo a test_suite.
Ricezione di un oggetto funzione, questo oggetto funzione non ha parametri e restituisce un unittest.TestSuite. Così possiamo scrivere una funzione separatamente, combinare molti casi di test in un suite e restituirlo, quindi possiamo importare la funzione e passarla a test_suite.

Il nome del modulo e del pacchetto, uso questo metodo, i miei test precedenti erano separati in molti script, in questo modo posso aggiungere un __init__.py per trasformarlo in un pacchetto, passare il nome del pacchetto a test_suite, setuptools eseguirà magicamente tutti i test sotto questo pacchetto, quindi quando aggiungerò nuovi script di test in futuro, aggiungerò direttamente nuovi script senza dover modificare altro.

Effetto di esecuzione:

zjshao@SHAO-PC:/mnt/d/Dropbox/Code/CentOS_code/VASPy$ python setup.py test
esecuzione di test
esecuzione di egg_info
creazione di vaspy.egg-info
scrittura di vaspy.egg-info/PKG-INFO
scrittura dei nomi di livello superiore in vaspy.egg-info/top_level.txt
scrittura dei dependency_links in vaspy.egg-info/dependency_links.txt
scrittura del file manifest 'vaspy.egg-info/SOURCES.txt'
lettura del file manifest 'vaspy.egg-info/SOURCES.txt'
lettura del modello manifest 'MANIFEST.in'
scrittura del file manifest 'vaspy.egg-info/SOURCES.txt'
esecuzione di build_ext
test_compare (tests.incar_test.InCarTest)
Assicurati che possiamo confrontare correttamente due oggetti InCar. ... ok
test_eq (tests.incar_test.InCarTest)
Test __eq__() function. ... ok
...
Alcuni output sono stati omessi
----------------------------------------------------------------------
Ran 22 tests in 3.574s
OK

Pubblica il proprio pacchetto python

1. Prima vai a registrarti su PyPI

2. Configura ~/.pypirc come segue:

[distutils]
index-servers =
  pypi
  pypitest
[pypi]
username:ShaoZhengjiang
password:mypassword
[pypitest]
username:ShaoZhengjiang
password:mypassword

3. Poi registra e carica il proprio pacchetto sul server di test

pypi fornisce un server di test, possiamo fare test su questo server di test.

python setup.py register -r pypitest

Poi

python setup.py sdist upload -r pypitest

Se tutto va bene, non dovremmo ottenere alcun errore.

4. Carica su PyPI

Se il test sopra è stato successo, possiamo registrare e caricare il pacchetto seguendo gli stessi passaggi.

python setup.py register -r pypi
python setup.py sdist upload -r pypi

Ok, possiamo procedere a PyPI dopo di chehttps://pypi.python.org/pypi/vaspy/Vediamo i nostri pacchetti.