Python Language
Créer des paquets Python

Remarques

introduction

Chaque paquet nécessite un fichier setup.py qui décrit le paquet.

Considérez la structure de répertoires suivante pour un package simple:

+-- package_name
|       |
|       +-- __init__.py
|       
+-- setup.py

Le __init__.py ne contient que la ligne def foo(): return 100 .

Le setup.py suivant définira le package:

from setuptools import setup


setup(
    name='package_name',                    # package name
    version='0.1',                          # version
    description='Package Description',      # short description
    url='http://example.com',               # package URL
    install_requires=[],                    # list of packages this package depends
                                            # on.
    packages=['package_name'],              # List of module names that installing
                                            # this package will provide.
)

virtualenv est idéal pour tester les installations de paquets sans modifier vos autres environnements Python:

$ virtualenv .virtualenv
...
$ source .virtualenv/bin/activate
$ python setup.py install
running install
...
Installed .../package_name-0.1-....egg
...
$ python
>>> import package_name
>>> package_name.foo() 
100

Téléchargement vers PyPI

Une fois que votre setup.py est entièrement fonctionnel (voir Introduction ), il est très facile de télécharger votre paquet vers PyPI .

Configurer un fichier .pypirc

Ce fichier stocke les identifiants et les mots de passe pour authentifier vos comptes. Il est généralement stocké dans votre répertoire personnel.

# .pypirc file

[distutils]
index-servers =
  pypi
  pypitest

[pypi]
repository=https://pypi.python.org/pypi
username=your_username
password=your_password

[pypitest]
repository=https://testpypi.python.org/pypi
username=your_username
password=your_password

Il est plus sûr d'utiliser la twine pour le téléchargement de paquets, alors assurez-vous qu'elle est installée.

$ pip install twine

S'inscrire et télécharger sur testpypi (facultatif)

Remarque : PyPI n'autorise pas le remplacement des paquets téléchargés . Il est donc prudent de tester d'abord votre déploiement sur un serveur de test dédié, par exemple, testpypi. Cette option sera discutée. Envisagez un système de gestion des versions pour votre package avant de le télécharger, comme le contrôle de version du calendrier ou le contrôle de version sémantique .

Connectez-vous ou créez un nouveau compte sur testpypi . L'inscription n'est requise que la première fois, bien que l'enregistrement plus d'une fois ne soit pas dangereux.

$ python setup.py register -r pypitest

Dans le répertoire racine de votre package:

$ twine upload dist/* -r pypitest

Votre paquet devrait maintenant être accessible via votre compte.

Essai

Créez un environnement virtuel de test. Essayez d' pip install votre paquet à partir de testpypi ou de PyPI.

# Using virtualenv
$ mkdir testenv
$ cd testenv
$ virtualenv .virtualenv
...
$ source .virtualenv/bin/activate
# Test from testpypi
(.virtualenv)  pip install --verbose --extra-index-url https://testpypi.python.org/pypi package_name
...
# Or test from PyPI
(.virtualenv) $ pip install package_name
...

(.virtualenv) $ python
Python 3.5.1 (default, Jan 27 2016, 19:16:39)
[GCC 4.2.1 Compatible Apple LLVM 7.0.2 (clang-700.1.81)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import package_name
>>> package_name.foo()
100

En cas de succès, votre paquet est le moins importable. Vous pourriez également envisager de tester votre API avant votre téléchargement final sur PyPI. Si votre paquet a échoué pendant le test, ne vous inquiétez pas. Vous pouvez toujours résoudre le problème, re-télécharger sur testpypi et tester à nouveau.

Enregistrer et télécharger sur PyPI

Assurez-vous que la twine est installée:

$ pip install twine

Connectez-vous ou créez un nouveau compte sur PyPI .

$ python setup.py register -r pypi
$ twine upload dist/*

C'est tout! Votre colis est maintenant en ligne .

Si vous découvrez un bogue, téléchargez simplement une nouvelle version de votre paquet.

Documentation

N'oubliez pas d'inclure au moins une sorte de documentation pour votre paquet. PyPi prend comme langage de formatage par défaut reStructuredText .

Readme

Si votre paquet ne contient pas une grande documentation, incluez ce qui peut aider les autres utilisateurs dans le fichier README.rst . Lorsque le fichier est prêt, il en faut un autre pour que PyPi le montre.

Créez le fichier setup.cfg et insérez-y ces deux lignes:

[metadata]
description-file = README.rst

Notez que si vous essayez de placer le fichier Markdown dans votre paquet, PyPi le lira comme un fichier texte pur sans aucune mise en forme.

Licence

Il est souvent plus que bienvenu de placer un fichier LICENSE.txt dans votre package avec l'une des licences OpenSource pour indiquer aux utilisateurs s'ils peuvent utiliser votre package par exemple dans des projets commerciaux ou si votre code est utilisable avec leur licence.

De manière plus lisible, certaines licences sont expliquées chez TL; DR .

Rendre le package exécutable

Si votre paquet n'est pas seulement une bibliothèque, mais un morceau de code pouvant être utilisé soit comme une vitrine, soit comme une application autonome lorsque votre paquet est installé, placez ce morceau de code dans le fichier __main__.py .

Placez le __main__.py dans le dossier package_name . De cette façon, vous pourrez l'exécuter directement depuis la console:

python -m package_name

S'il n'y a pas de fichier __main__.py disponible, le paquet ne sera pas exécuté avec cette commande et cette erreur sera imprimée:

python: aucun module nommé package_name.__main__; 'nom_package' est un package et ne peut pas être directement exécuté.