• # Python Build Reasonableness

    Posté par (site web personnel) . En réponse au journal Quelques bonnes pratiques Python pour 2019. Évalué à 4. Dernière modification le 03 avril 2019 à 05:32.

    Pour éviter de passer du temps à réaliser des tâches répétitives à chaque version, l'équipe de OpenStack les a automatisées dans un script qui est devenu en 2010, le module pbr pour Python Build Reasonableness (avec sagesse). Ce module a énormément évolué en s'adaptant aux évolutions de Python sur dix ans (150 contributeurs).

    Installation

    sudo apt install python3-pbr # v4.2.0 (Ubuntu 18.10)
# ou une version bien plus récente:
python3 -m pip install --user pbr # v5.1.3

    Fonctionnalités

    • Récupère automatiquement la version à partir du tag Git et la passe à setuptools (setup.py) ;
    • Réplique les dépendances du fichier requirements.txt vers setuptools (install_requires) ;
    • Maintient la liste des AUTHORS à partir du git log ;
    • Génère le ChangeLog en cherchant les mots feature, api-break, deprecation et bugfix dans le git log ;
    • Délègue à reno la gestion des Release Notes ;
    • Gère le fichier MANIFEST.in ;
    • (削除) Lance les tests via tox (削除ここまで) (déprécié) ;
    • Lance sphinx pour produire la documentation.

    Avant

    ├── nom_du_module_python/
├── AUTHORS
├── CHANGES
├── LICENSE
├── MANIFEST.in
├── README.md
├── RELEASENOTES.txt
├── requirements.txt # dependance_1 dependance_2...
└── setup.py
 ║
 ╚═╡ from setuptools import setup, find_packages
 │ from os import path
 │
 │ setup(
 │ name = "nom_du_module_python",
 │ version = "1.0.0",
 │ author = "Michel Martin",
 │ author_email = "m.martin@example.com",
 │ description = "Une courte description",
 │ long_description = open(path.join(path.dirname(__file__), 'README.md'), encoding='utf-8').read()
 │ long_description_content_type = "text/markdown",
 │ license = "AGPL",
 │ packages = find_packages(exclude=["test.*"]),
 │ install_requires = ["dependance_1", "dependance_2", "dependance_3", "dependance_4"],
 │ )

    Après

    ├── nom_du_module_python/
├── LICENSE
├── README.md
├── requirements.txt
├── setup.cfg
│ ║
│ ╚═╡ [metadata]
│ │ name = nom_du_module_python
│ │ description = Une courte description
│ │ description-file = README.md
│ │ author = Michel Martin
│ │ author-email = m.martin@example.com
│ │ license = AGPL
│
└── setup.py
 ║
 ╚═╡ from setuptools import setup
 │
 │ setup(
 │ setup_requires = ["pbr"],
 │ pbr = True,
 │ )

    Bon, c'est vrai, depuis setuptools-30.3.0 (déc. 2016) on peut remplacer setup.py par setup.cfg. Cependant, le Python Packaging Authority recommande d'utiliser principalement le setup.py. Néanmoins, des projets comme tox utilisent principalement setup.cfg.

    Distinction entre install_requires et requirements.txt

    Le module pbr permet d'éviter de gérer en double la liste des dépendances : pbr spécifie le paramètre install_requires à partir du fichier requirements.txt. Mais, sémantiquement, ces deux listes ont deux objectifs différents :

    • Le paramètre install_requires du fichier setup.py (ou setup.cfg) est inséré dans le livrable et ne précise pas toujours la version des dépendances, du moins l'intervalle des versions pour lequel le livrable est censé être compatible ;
    • Le fichier requirements.txt est fourni à pip pour installer des versions précises pour lesquelles l'application a été validée.

    De plus, requirements.txt peut contenir des arguments de la ligne de commande pip comme --index-url https://pypi.python.org/simple/ afin d'indiquer explicitement à partir de quel dépôt télécharger les dépendances. Les développeurs utilisent souvent ce fichier pour avoir les mêmes dépendances et éviter de perdre du temps avec une incompatibilité absconse.

    En résumé, install_requires définit les dépendances compatibles (pour la livraison) et requirements.txt spécifie les versions validées (pour le déploiement). Pour plus de détail sur cette sémantique, lire le coup de gueule de Donald Stufft (2013, en anglais). Lire aussi la documentation officielle (en anglais).

    Cependant, dans la pratique, ces deux listes sont souvent gérées de la même façon, donc autant mutualiser les efforts. :-)

    Futur

    Actuellement, pbr n'est pas encore compatible avec le fichier pyproject.toml (PEP-517 et PEP-518) et ne prend pas en charge les alternatives à setuptools comme flit et poetry (découplage entre empaquetage et installation). Mais les développements sont prévus d'après la description du module :

    As Metadata 2.0 and other modern Python packaging PEPs come out, PBR aims to support them as quickly as possible.

    Commentaire sous licence Creative Commons Zero CC0 1.0 Universal (Public Domain Dedication)