Add poetry instructions
This commit is contained in:
parent
633352fe4c
commit
3dd773d6d8
Binary file not shown.
After Width: | Height: | Size: 53 KiB |
|
@ -35,11 +35,14 @@ Dans les étapes ci-dessous, nous épinglerons une version LTS afin de nous assu
|
||||||
ne occuperons pas pendant les 3 prochaines années).
|
ne occuperons pas pendant les 3 prochaines années).
|
||||||
|
|
||||||
|
|
||||||
==== Environnement virtuel
|
==== Environnements virtuels
|
||||||
|
|
||||||
Depuis la version 3.5 de Python, le module `venv` est https://docs.python.org/3/library/venv.html[la manière recommandée] pour créer un environnement virtuel.
|
.https://xkcd.com/1987
|
||||||
|
image::images/xkcd-1987.png[]
|
||||||
|
|
||||||
NOTE: Il existe plusieurs autres modules permettant d'arriver au même résultat, avec quelques avantages et inconvénients pour chacun d'entre eux. Le plus prometteur d'entre eux est https://python-poetry.org/[Poetry], qui dispose d'une interface en ligne de commande plus propre et plus moderne que ce que PIP propose.
|
Un des reproches que l'on peut faire au langage concerne sa versatilité: il est possible de réaliser beaucoup de choses, mais celles-ci ne sont pas toujours simples ou directes.
|
||||||
|
Pour quelqu'un qui débarquererait, la quantité d'options différentes peut paraître rebutante.
|
||||||
|
Nous pensons notamment aux environnements virtuels: ils sont géniaux à utiliser, mais on est passé par virtualenv (l'ancêtre), virtualenvwrapper (sa version améliorée et plus ergonomique), `venv` (la version intégrée depuis la version 3.3 de l'interpréteur, et https://docs.python.org/3/library/venv.html[la manière recommandée] de créer un environnement depuis la 3.5).
|
||||||
|
|
||||||
Pour créer un nouvel environnement, vous aurez donc besoin:
|
Pour créer un nouvel environnement, vous aurez donc besoin:
|
||||||
|
|
||||||
|
@ -47,7 +50,59 @@ Pour créer un nouvel environnement, vous aurez donc besoin:
|
||||||
. D'un terminal - voir le point <<../environment/_index.adoc#un-terminal,Un terminal>>
|
. D'un terminal - voir le point <<../environment/_index.adoc#un-terminal,Un terminal>>
|
||||||
|
|
||||||
|
|
||||||
|
NOTE: Il existe plusieurs autres modules permettant d'arriver au même résultat, avec quelques avantages et inconvénients pour chacun d'entre eux. Le plus prometteur d'entre eux est https://python-poetry.org/[Poetry], qui dispose d'une interface en ligne de commande plus propre et plus moderne que ce que PIP propose.
|
||||||
|
|
||||||
|
Poetry se propose de gérer le projet au travers d'un fichier pyproject.toml. TOML (du nom de son géniteur, Tom Preston-Werner, légèrement CEO de GitHub à ses heures), se place comme alternative aux formats comme JSON, YAML ou INI.
|
||||||
|
|
||||||
|
[source,bash]
|
||||||
|
----
|
||||||
|
La commande poetry new <project> créera une structure par défaut relativement compréhensible:
|
||||||
|
|
||||||
|
$ poetry new django-gecko
|
||||||
|
$ tree django-gecko/
|
||||||
|
django-gecko/
|
||||||
|
├── django_gecko
|
||||||
|
│ └── __init__.py
|
||||||
|
├── pyproject.toml
|
||||||
|
├── README.rst
|
||||||
|
└── tests
|
||||||
|
├── __init__.py
|
||||||
|
└── test_django_gecko.py
|
||||||
|
|
||||||
|
2 directories, 5 files
|
||||||
|
----
|
||||||
|
|
||||||
|
Ceci signifie que nous avons directement (et de manière standard):
|
||||||
|
|
||||||
|
* Un répertoire django-gecko, qui porte le nom de l'application que vous venez de créer
|
||||||
|
* Un répertoires tests, libellé selon les standards de pytest
|
||||||
|
* Un fichier README.rst (qui ne contient encore rien)
|
||||||
|
* Un fichier pyproject.toml, qui contient ceci:
|
||||||
|
|
||||||
|
[source,toml]
|
||||||
|
----
|
||||||
|
[tool.poetry]
|
||||||
|
name = "django-gecko"
|
||||||
|
version = "0.1.0"
|
||||||
|
description = ""
|
||||||
|
authors = ["... <...@grimbox.be>"]
|
||||||
|
|
||||||
|
[tool.poetry.dependencies]
|
||||||
|
python = "^3.9"
|
||||||
|
|
||||||
|
[tool.poetry.dev-dependencies]
|
||||||
|
pytest = "^5.2"
|
||||||
|
|
||||||
|
[build-system]
|
||||||
|
requires = ["poetry-core>=1.0.0"]
|
||||||
|
build-backend = "poetry.core.masonry.api"
|
||||||
|
----
|
||||||
|
|
||||||
|
La commande `poetry init` permet de générer interactivement les fichiers nécessaires à son intégration dans un projet existant.
|
||||||
|
|
||||||
|
|
||||||
NOTE: J'ai pour habitude de conserver mes projets dans un répertoire `~/Sources/` et mes environnements virtuels dans un répertoire `~/.venvs/`.
|
NOTE: J'ai pour habitude de conserver mes projets dans un répertoire `~/Sources/` et mes environnements virtuels dans un répertoire `~/.venvs/`.
|
||||||
|
|
||||||
Cette séparation évite que l'environnement virtuel ne se trouve dans le même répertoire que les sources, ou ne soit accidentellement envoyé vers le système de gestion de versions.
|
Cette séparation évite que l'environnement virtuel ne se trouve dans le même répertoire que les sources, ou ne soit accidentellement envoyé vers le système de gestion de versions.
|
||||||
Elle évite également de rendre ce répertoire "visible" - il ne s'agit au fond que d'un paramètre de configuration lié uniquement à votre environnement de développement; les environnements virtuels étant disposables, il n'est pas conseillé de trop les lier au projet qui l'utilise comme base.
|
Elle évite également de rendre ce répertoire "visible" - il ne s'agit au fond que d'un paramètre de configuration lié uniquement à votre environnement de développement; les environnements virtuels étant disposables, il n'est pas conseillé de trop les lier au projet qui l'utilise comme base.
|
||||||
Dans la suite de ce chapitre, je considérerai ces mêmes répertoires, mais n'hésitez pas à les modifier.
|
Dans la suite de ce chapitre, je considérerai ces mêmes répertoires, mais n'hésitez pas à les modifier.
|
||||||
|
@ -95,6 +150,106 @@ Cette technique fonctionnera autant pour un poste de développement que sur les
|
||||||
|
|
||||||
NOTE: Par la suite, nous considérerons que l'environnement virtuel est toujours activé, même si `gwift-env` n'est pas indiqué.
|
NOTE: Par la suite, nous considérerons que l'environnement virtuel est toujours activé, même si `gwift-env` n'est pas indiqué.
|
||||||
|
|
||||||
|
a manière recommandée pour la gestion des dépendances consiste à les épingler dans un fichier requirements.txt, placé à la racine du projet. Ce fichier reprend, ligne par ligne, chaque dépendance et la version nécessaire. Cet épinglage est cependant relativement basique, dans la mesure où les opérateurs disponibles sont ==, <= et >=.
|
||||||
|
|
||||||
|
Poetry propose un épinglage basé sur SemVer. Les contraintes qui peuvent être appliquées aux dépendances sont plus touffues que ce que proposent pip -r, avec la présence du curseur ^, qui ne modifiera pas le nombre différent de zéro le plus à gauche:
|
||||||
|
|
||||||
|
^1.2.3 (où le nombre en question est 1) pourra proposer une mise à jour jusqu'à la version juste avant la version 2.0.0
|
||||||
|
^0.2.3 pourra être mise à jour jusqu'à la version juste avant 0.3.0.
|
||||||
|
...
|
||||||
|
|
||||||
|
L'avantage est donc que l'on spécifie une version majeure - mineure - patchée, et que l'on pourra spécifier accepter toute mise à jour jusqu'à la prochaine version majeure - mineure patchée (non incluse 😉).
|
||||||
|
|
||||||
|
Une bonne pratique consiste également, tout comme pour npm, à intégrer le fichier de lock (poetry.lock) dans le dépôt de sources: de cette manière, seules les dépendances testées (et intégrées) seront considérées sur tous les environnements de déploiement.
|
||||||
|
|
||||||
|
Il est alors nécessaire de passer par une action manuelle (poetry update) pour mettre à jour le fichier de verrou, et assurer une mise à jour en sécurité (seules les dépendances testées sont prises en compte) et de qualité (tous les environnements utilisent la même version d'une dépendance).
|
||||||
|
|
||||||
|
L'ajout d'une nouvelle dépendance à un projet se réalise grâce à la commande `poetry add <dep>`:
|
||||||
|
|
||||||
|
[source,shell]
|
||||||
|
----
|
||||||
|
$ poetry add django
|
||||||
|
Using version ^3.2.3 for Django
|
||||||
|
|
||||||
|
Updating dependencies
|
||||||
|
Resolving dependencies... (5.1s)
|
||||||
|
|
||||||
|
Writing lock file
|
||||||
|
|
||||||
|
Package operations: 8 installs, 1 update, 0 removals
|
||||||
|
|
||||||
|
• Installing pyparsing (2.4.7)
|
||||||
|
• Installing attrs (21.2.0)
|
||||||
|
• Installing more-itertools (8.8.0)
|
||||||
|
• Installing packaging (20.9)
|
||||||
|
• Installing pluggy (0.13.1)
|
||||||
|
• Installing py (1.10.0)
|
||||||
|
• Installing wcwidth (0.2.5)
|
||||||
|
• Updating django (3.2 -> 3.2.3)
|
||||||
|
• Installing pytest (5.4.3)
|
||||||
|
|
||||||
|
----
|
||||||
|
|
||||||
|
Elle est ensuite ajoutée à notre fichier `pyproject.toml`:
|
||||||
|
|
||||||
|
[source,toml]
|
||||||
|
----
|
||||||
|
[...]
|
||||||
|
|
||||||
|
[tool.poetry.dependencies]
|
||||||
|
python = "^3.9"
|
||||||
|
Django = "^3.2.3"
|
||||||
|
|
||||||
|
[...]
|
||||||
|
----
|
||||||
|
|
||||||
|
Et contrairement à `pip`, pas besoin de savoir s'il faut pointer vers un fichier (`-r`) ou un dépôt VCS (`-e`), puisque Poetry va tout essayer, [dans un certain ordre](https://python-poetry.org/docs/cli/#add).
|
||||||
|
L'avantage également (et cela m'arrive encore souvent, ce qui fait hurler le runner de Gitlab), c'est qu'il n'est plus nécessaire de penser à épingler la dépendance que l'on vient d'installer parmi les fichiers de requirements, puisqu'elles s'y ajoutent automatiquement grâce à la commande `add`.
|
||||||
|
|
||||||
|
==== Python packaging made easy
|
||||||
|
|
||||||
|
Cette partie dépasse mes compétences et connaissances, dans la mesure où je n'ai jamais rien packagé ni publié sur [pypi.org](pypi.org).
|
||||||
|
Ce n'est pas l'envie qui manque, mais les idées et la nécessité 😉.
|
||||||
|
Ceci dit, Poetry propose un ensemble de règles et une préconfiguration qui (doivent) énormément facilite(r) la mise à disposition de librairies sur Pypi - et rien que ça, devrait ouvrir une partie de l'écosystème.
|
||||||
|
|
||||||
|
Les chapitres 7 et 8 de [Expert Python Programming - Third Edtion](#), écrit par Michal Jaworski et Tarek Ziadé en parlent très bien:
|
||||||
|
|
||||||
|
> Python packaging can be a bit overwhelming at first.
|
||||||
|
> The main reason for that is the confusion about proper tools for creating Python packages.
|
||||||
|
> Anyway, once you create your first package, you will se that this is as hard as it looks.
|
||||||
|
> Also, knowing propre, state-of-the-art packaging helps a lot.
|
||||||
|
|
||||||
|
En gros, c'est ardu-au-début-mais-plus-trop-après.
|
||||||
|
Et c'est heureusement suivi et documenté par la PyPA (*https://github.com/pypa[Python Packaging Authority]*).
|
||||||
|
|
||||||
|
Les étapes sont les suivantes:
|
||||||
|
|
||||||
|
1. Utiliser setuptools pour définir les projets et créer les distributions sources,
|
||||||
|
2. Utiliser **wheels** pour créer les paquets,
|
||||||
|
3. Passer par **twine** pour envoyer ces paquets vers PyPI
|
||||||
|
4. Définir un ensemble d'actions (voire, de plugins nécessaires - lien avec le VCS, etc.) dans le fichier `setup.py`, et définir les propriétés du projet ou de la librairie dans le fichier `setup.cfg`.
|
||||||
|
|
||||||
|
Avec Poetry, deux commandes suffisent (théoriquement - puisque je n'ai pas essayé 🤪): `poetry build` et `poetry publish`:
|
||||||
|
|
||||||
|
[source,shell]
|
||||||
|
----
|
||||||
|
$ poetry build
|
||||||
|
Building geco (0.1.0)
|
||||||
|
- Building sdist
|
||||||
|
- Built geco-0.1.0.tar.gz
|
||||||
|
- Building wheel
|
||||||
|
- Built geco-0.1.0-py3-none-any.whl
|
||||||
|
|
||||||
|
$ tree dist/
|
||||||
|
dist/
|
||||||
|
├── geco-0.1.0-py3-none-any.whl
|
||||||
|
└── geco-0.1.0.tar.gz
|
||||||
|
|
||||||
|
0 directories, 2 files
|
||||||
|
----
|
||||||
|
|
||||||
|
Ce qui est quand même 'achement plus simple que d'appréhender tout un écosystème.
|
||||||
|
|
||||||
|
|
||||||
==== Gestion des dépendances, installation de Django et création d'un nouveau projet
|
==== Gestion des dépendances, installation de Django et création d'un nouveau projet
|
||||||
|
|
||||||
|
@ -571,4 +726,4 @@ La https://docs.djangoproject.com/en/stable/ref/django-admin/#startproject[docum
|
||||||
[source,bash]
|
[source,bash]
|
||||||
----
|
----
|
||||||
django-admin.py startproject --template=https://[...].zip <my_project>
|
django-admin.py startproject --template=https://[...].zip <my_project>
|
||||||
----
|
----
|
||||||
|
|
Loading…
Reference in New Issue