Le partage du code et la collaboration sur les logiciels libres ont transformé le développement des logiciels. Ils ont permis aux développeurs de créer des applications plus complexes avec des équipes plus réduites en utilisant des paquets et des bibliothèques existants.

Dans l’écosystème Python, la plupart des paquets sont enregistrés sur le Python Package Index (PyPI). Grâce à cet index, les développeurs peuvent partager leur code sous forme de paquets pour d’autres développeurs. Pour créer votre propre paquetage et le télécharger sur PyPI, vous aurez besoin d’un fichier pyproject.toml. Cet article est un guide sur le fonctionnement de ce fichier.

Qu’est-ce que pyproject.toml ?

Avant de voir ce qu’est ce fichier, il faut d’abord comprendre le vide qu’il tente de combler. Lorsque vous téléchargez un paquet sur PyPI, il devient installable à l’aide de pip. Par exemple, si votre paquet s’appelle example-package après l’avoir téléchargé sur PyPI, il sera installable à l’aide de la commande :

pip install exemple-paquet

Lorsque vous publiez des paquets dans le Python Package Index, vous téléchargez un fichier .whl. Mais lorsque vous écrivez du code, vous écrivez principalement des fichiers .py, alors comment générer un fichier .whl? Vous utilisez un outil de construction tel que setuptools ou poetry.

Cet outil prendra votre code source et le convertira en un fichier .whl qui pourra être téléchargé. Comme indiqué précédemment, il existe plusieurs outils que vous pouvez utiliser pour générer un fichier . whl. Pour spécifier l’outil que vous voulez que Python utilise, vous l’écrivez dans le fichier pyproject.tom l.

Par conséquent, le fichier pyproject.toml est un fichier qui spécifie comment votre projet Python doit être construit dans un paquetage. En outre, vous pouvez fournir des informations supplémentaires, telles que les métadonnées de votre paquetage, qui seront affichées sur la liste de votre paquetage sur PyPI.

Le processus de construction de Python

Pour lancer l’outil de construction, vous utilisez la commande, 

python -m build

Mais avant cela, vous devez l’installer

python -m pip install build

Lorsque vous exécutez la commande build dans un projet qui contient un fichier pyproject.toml, de nouveaux fichiers et répertoires sont créés. Ceux-ci incluent le dossier dist, qui contient deux fichiers, un fichier d’archive compressé appelé sdist et un fichier .whl que vous distribuez ensuite sur PyPI.

Comment générer un paquetage Python ?

Pour vous aider à consolider ce que nous venons d’apprendre, voici un exemple de génération d’un paquetage Python.

#1. Créez un projet d’exemple

Pour commencer, créez un paquetage simple avec la structure de dossier suivante

exemple_paquet/
├─ example_package/
│ ├─ example_module.py
│ ├─ __init__.py
├─ pyproject.toml
├─ setup.cfg
├─ README.md

Le répertoire racine du projet s’appelle example_package. C’est là que se trouve l’ensemble de notre base de code. À l’intérieur de la racine du projet, nous avons trois fichiers et un répertoire. Leur contenu est expliqué ci-dessous :

pyproject.toml

Ce fichier contient des informations sur les outils de construction à utiliser lors de la construction de votre projet. Pour cet exemple simple, voici ce qu’il contient :

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

Dans ce cas, nous déclarons setuptools.build_meta comme notre backend de construction. Mais setuptools .build_meta est contenu dans le paquetage setuptools, donc d’abord, nous le listons comme une exigence dans notre liste d’exigences. Nous discuterons des autres options que vous pouvez spécifier plus tard dans cet article.

README.md

Contient des informations sur votre paquetage. Il sera affiché comme documentation sur la page de votre paquet sur PyPI. Vous pouvez écrire n’importe quoi dans ce fichier.

setup.cfg

Le fichier setup.cf g contient les métadonnées du projet, comme le nom du paquet et la version actuelle. Pour l’instant, ajoutez le code suivant au contenu du fichier setup .cfg:

<x>[metadata]</x>
name = example-package
version = 1.0.0

projet-exemple

Notre répertoire racine contient un autre répertoire portant le même nom. C’est dans ce répertoire que se trouve notre code source. À des fins de démonstration, j’ai inclus deux fichiers :

  • example_module.py – Il contient une fonction fictive. Vous pouvez faire de même.
  • __init__.py – Il fait du répertoire un paquetage qui peut être importé. Il peut être vide.

#2. Exécutez la commande Build

Maintenant, vous pouvez lancer la commande build dans le répertoire racine du projet.

python -m build

Si vous ne l’avez pas fait, assurez-vous d’installer l’outil en utilisant ce qui suit :

pip install build

Vous devriez obtenir une sortie qui ressemble à ceci :

Screenshot-from-2023-06-01-01-05-54-1

Comme vous pouvez le voir, la dernière ligne vous indique que l’outil a construit example-package-1.0.0.tar.gz et example-package-1.0.0-py3-none-any-whl. Lorsque vous listerez le contenu de votre répertoire à l’aide de la commande ls ci-dessous, vous devriez voir de nouveaux fichiers.

ls

La sortie devrait être la suivante :

dist example_package example_package.egg-info pyproject.toml README.md setup.cfg
Screenshot-from-2023-06-01-01-27-15

Si vous listez le contenu de votre répertoire dist, vous devriez trouver le fichier .whl et le fichier tar.gz.

$ ls dist
example_package-1.0.0-py3-none-any.whl
example-package-1.0.0.tar.gz
Screenshot-from-2023-06-01-01-29-24

Contenu du fichier pyproject.toml

Dans notre exemple simple, nous n’avons spécifié que le système de construction de notre projet Python. Cependant, vous pouvez ajouter plus d’informations à votre fichier pyproject.toml. Voici quelques-unes des options les plus courantes.

métadonnées

Au lieu de spécifier des métadonnées dans le fichier setup.cfg, vous pouvez les écrire dans votre fichier pyproject.toml. Ces informations seront utilisées lors de la création d’une liste pour votre paquet dans l’index des paquets.

De plus, vous pouvez spécifier les dépendances de votre paquet et leurs versions afin qu’elles soient installées lors de l’installation de votre paquet. 

[projet]
name = "hello-world"
version = "1.0.0"
description = "Mon premier paquetage Python"
requires-python = ">=3.8"
keywords = ["python", "premier-projet"]
auteurs = [
    {nom = "John Doe", email = "john@example.com"},
]
dépendances = [
    "requests",
    "gidgethub[httpx]>4.0.0",
]

outil.

Vous pouvez également utiliser tool.<nom_de_l ‘outil> où est le nom de l’outil pour fournir différentes options de configuration pour les outils que vous utilisez.

Cela n’est possible qu’avec les outils qui prennent en charge la configuration à l’aide de cette méthode. Par exemple, vous pouvez transmettre des options de configuration à Black, un générateur de code.

[tool.black]
longueur de ligne = 88
version-cible = ["py38", "py39"]

Exemple de fichier

En rassemblant ce que nous avons appris, voici un exemple de fichier pyproject.toml :

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

<x>[metadata]</x>
name = "mon-projet"
version = "1.0.0"
description = "Un exemple de projet"
author = "Votre nom"
author_email = "your.email@example.com"
license = "MIT"
keywords = ["sample", "project"]

[options]
python_requires = ">=3.6"

[outil.noir]
longueur de ligne = 88
include = "\\N-.pyi?$"
exclude = '''
/(
  \N- \N- git
  | \N- hg
  | \.mypy_cache
  | \.tox
  | \NVenv
  | _build
  | buck-out
  | build
  | dist
)/
'''

[tool.blackd]
port = 45484
hôte = "localhost"

Pour plus d’informations, lisez cette page.

Avantages de pyproject.toml

✅ Il fournit un moyen standard de gérer les dépendances pour les projets Python. Les dépendances
et d’autres métadonnées pertinentes des projets peuvent être spécifiées de manière déclarative.

✅ Il fournit également un moyen de spécifier d’autres métadonnées dans vos projets, telles que les auteurs, la licence et l’URL GitHub, parmi d’autres attributs utiles.

✅ Il s’adapte à différents systèmes de construction et il est facile de changer de système de construction.

Le mot de la fin

pyproject.toml est un standard utile qui permet d’éviter les inconvénients de l’utilisation de setup.py. Il est surtout utile lorsque vous créez des paquets à distribuer. Pour la plupart des nouveaux projets, vous devriez utiliser pyproject.toml au lieu de setup.py.

Découvrez ensuite comment vérifier la version de Python sous Windows, Linux et macOS.