diff --git a/recherche-des-bonnes-pratiques-de-packaging.qmd b/recherche-des-bonnes-pratiques-de-packaging.qmd
index fe64c33e80ded4f4a32d663041f88b65ddca6ea4..9abc65ed7046aed80ce9aff955d878c76022940a 100644
--- a/recherche-des-bonnes-pratiques-de-packaging.qmd
+++ b/recherche-des-bonnes-pratiques-de-packaging.qmd
@@ -72,14 +72,17 @@ logiciels plus que les prototypes.
## Bases et packaging
-Informer sur :
+Comprendre et identifier les bonnes pratiques de packaging Python à employer et
+informer sur :
-- structure des identifiants de version Python
+- structure d'un package
+- pyproject.toml
+- identifiants de version Python
- git tag
-- forges
-- Python Package Index
-
-Comprendre et identifier les bonnes pratiques de packaging Python actuelles.
+- forges (GitHub, GitLab)
+- Python Package Index (PyPI)
+- frontends
+- backends ... et outils de workflow
::: {.notes}
Disparités :
@@ -87,6 +90,17 @@ Disparités :
- des plateformes utilisées : GitHub, GitLab ou autre
- des machines et des OS
- des niveaux
+
+Je n'avais moi-même pas les idées claires sur tous ces éléments et j'ai cherché
+à mieux comprendre, dissiper les flous (ce n'est pas encore tout à fait le
+cas).
+
+Il y a une page Guides > [Tool recommendations](https://packaging.python.org/en/latest/guides/tool-recommendations/)
+dans le PyPA Python Packaging User Guide. Les outils comme hatch (et non
+hatchling), flit, pdm et poetry sont désignés comme des "workflow tools".
+
+J'ai beaucoup appris mais j'ai l'impression de savoir peu, d'avoir encore des
+manques.
:::
# Difficultés
@@ -111,7 +125,7 @@ Le terme **package** recouvre 2 usages différents ^[[Distribution package vs. i
Pour permettre de faire des imports entre fichiers sans faire de package, on
trouve encore des ressources qui présentent l'utilisation de `sys.path.insert` :
-```Python
+```python
# Pour importer des modules depuis un autre répertoire, vous pouvez utiliser le code suivant :
import sys
@@ -270,10 +284,10 @@ https://quarto.org/docs/presentations/revealjs/#slide-backgrounds
- [L'enfer des paquets Python](https://www.stella.coop/blog/00003-l-enfer-des-paquets-python-le-sac-de-noeuds), *7 articles*, 2020
- L’installation et la distribution de paquets Python, *4 articles* ([1/4](https://linuxfr.org/news/l-installation-et-la-distribution-de-paquets-python-1-4), [2/4](https://linuxfr.org/news/l-installation-et-la-distribution-de-paquets-python-2-4), …), 2023
-La vidéo de la présentation "Python Packaging" de Florian Strzelecki au [BreizhCamp du 30 avril 2024](https://www.youtube.com/watch?v=16EXAKxPfes&t=1221s)
+Vidéo de la présentation "Python Packaging" de Florian Strzelecki au [BreizhCamp du 30 avril 2024](https://www.youtube.com/watch?v=16EXAKxPfes&t=1221s)
-L'[historique du packaging](https://www.pypa.io/en/latest/history/) présenté
-par la Python Packaging Authority.
+[Historique du packaging](https://www.pypa.io/en/latest/history/) présenté par
+la Python Packaging Authority.
::: {.notes}
- L'enfer des paquets Python : Guillaumen et Lucie / Stella / CourtBouillon ?
@@ -283,15 +297,14 @@ par la Python Packaging Authority.
## Python Packaging Authority
-La [Python Packaging Authority](https://www.pypa.io/en/latest/) (PyPA) est un groupe de travail, créé en 2012 ^[Lire [La création de la Python Packaging Authority (PyPA)](https://linuxfr.org/news/l-installation-et-la-distribution-de-paquets-python-1-4#toc-la-cr%C3%A9ation-de-la-python-packaging-authority-pypa)], qui :
+La [Python Packaging Authority](https://www.pypa.io/en/latest/) (PyPA) est un groupe de travail, créé en 2012 ^[Lire [la création de la Python Packaging Authority (PyPA)](https://linuxfr.org/news/l-installation-et-la-distribution-de-paquets-python-1-4#toc-la-cr%C3%A9ation-de-la-python-packaging-authority-pypa)], qui :
- maintient un [ensemble de logiciels de packaging](https://packaging.python.org/en/latest/key_projects/#pypa-projects)
- sur son [Organisation GitHub](https://github.com/pypa)
+ sur son organisation GitHub ^[<https://github.com/pypa>]
- maintient un [ensemble de spécifications](https://www.pypa.io/en/latest/specifications/)
- destinée à faciliter l'interopérabilité des outils de packaging
-- développe un ensemble de documentations sur le packaging dans le [Python Packaging User Guide](https://packaging.python.org/)
-- anime les [discussions sur le packaging](https://discuss.python.org/c/packaging/14)
- sur le forum de la communauté Python
+ destinées à faciliter l'**interopérabilité des outils de packaging**
+- développe un ensemble de **documentations** sur le packaging dans le [Python Packaging User Guide](https://packaging.python.org/)
+- anime les **discussions** sur le packaging sur le forum de la communauté Python ^[<https://discuss.python.org/c/packaging/14>]
::: {.notes}
The Python Packaging Authority is a working group that maintains a core set of
@@ -300,21 +313,30 @@ software projects used in Python packaging.
The PyPA publishes the Python Packaging User Guide, which is the authoritative
resource on how to package, publish, and install Python projects using current
tools.
+
+La documentation s'est beaucoup améliorée en 6 mois, on trouve de nouvelles
+pages qui apporte des informations complémentaires et que je vais consulter
+avec grand intérêt.
:::
## Scientific Python Packaging
-2 autres guides intéressants sont apparus courant 2023 pour donner des
-informations sur le packaging Python aux projets scientifiques :
+Deux autres guides sont apparus en 2023 pour les **projets scientifiques** :
-- [Scientific Python Library Development Guide](https://learn.scientific-python.org/development/)
- [Python package structure information](https://www.pyopensci.org/python-package-guide/package-structure-code/intro.html)
-
-Au délà de l'aide pour packager et documenter son projet, [pyOpenSci](https://www.pyopensci.org/),
-met en place du **peer review** sur les logiciels scientifiques. ^[Sa fondatrice a fait une
-présentation intéressante à PyCon US 2024 [Friends don’t let friends package alone](https://www.pyopensci.org/blog/python-packaging-friends-dont-let-friends-package-alone.html)]
+ - [pyOpenSci](https://www.pyopensci.org/) met en place du **peer review** sur les logiciels scientifiques
+ ^[[Parteneriat pyOpenSci avec JOSS](https://www.pyopensci.org/software-peer-review/partners/joss.html), *Journal of Open Source Software*]
+ ^[Propose une checklist : [Does Your Package Meet Packaging Requirements?](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html#does-your-package-meet-packaging-requirements)]
+- [Scientific Python Library Development Guide](https://learn.scientific-python.org/development/)
+ - Le « Scientific Python Library Development Guide » propose des templates de projet
+ ^[[Templates de projet](https://learn.scientific-python.org/development/) pour [Cookiecutter](https://cookiecutter.readthedocs.io/), [Copier](https://copier.readthedocs.io/) et [cruft](https://cruft.github.io/cruft/)]
::: {.notes}
+2 autres guides intéressants sont apparus courant 2023 pour donner des
+informations / bonnes pratiques sur le packaging Python aux **projets scientifiques** :
+
+Au délà de l'aide pour packager et documenter son projet, pyOpenSci …
+
**Présentations et articles de blog**
De nombreux articles de blog et présentations sont parues pour présenter des
@@ -323,16 +345,209 @@ comparatifs => voir slide "Tableaux comparatifs de backends"
- [An unbiased evaluation of environment management and packaging tools](https://alpopkes.com/posts/python/packaging_tools/), Anna-Lena Pop, 2023
:::
-# Bonnes pratiques - Structure
+# Processus minimal
+
+## Étapes
-# Python Package Index
+Le processus minimal est très bien illustré par [Leah Wasser](https://www.leahwasser.com/)
+dans sa présentation à la PyCon US 2024 :
+
+1. Créer la structure du package
+2. Ajouter le code source
+3. Ajouter les métadonnées au `pyproject.toml`
+4. Installer le package avec `pip install`
+
+::: aside
+- Présentation PyCon US 2024 : [Friends don’t let friends package alone](https://www.pyopensci.org/blog/python-packaging-friends-dont-let-friends-package-alone.html#fundamentals-first), et avec plus de détails sur PyOPenSci : [Python package structure information](https://www.pyopensci.org/python-package-guide/package-structure-code/intro.html)
+- Voir aussi : [The Packaging Flow](https://packaging.python.org/en/latest/flow/) du "Python Packaging User Guide", et avec plus de détails dans [Packaging Python Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+- Ainsi que : [Tutorials packaging](https://learn.scientific-python.org/development/tutorials/packaging/) du "Scientific Python Development Guide"
+:::
+
+::: {.notes}
+- Reprend le shéma mais avec les étapes 1. et 2. inversées : <https://www.pyopensci.org/python-package-guide/tutorials/installable-code.html>
+:::
+
+## Structure du package
+
+Exemple de projet minimal ^[Comme décrit dans le [Tutorial Packaging](https://learn.scientific-python.org/development/tutorials/packaging/) du « Scientific Python Development Guide »]
+avec une structure **src layout** ^[PyPA : [src layout vs flat layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/)]
+^[PyOpenSci : [Python Package Structure for Scientific Python Projects](https://www.pyopensci.org/python-package-guide/package-structure-code/python-package-structure.html)] :
+
+```bash
+hello_pyconfr_2024
+├── pyproject.toml
+└── src
+ └── hello_pyconfr
+ ├── greetings.py
+ └── __init__.py
+```
+
+Un code source basique :
+
+```python
+def greet():
+ print("Hello PyConFR 2024")
+```
+
+::: {.notes}
+structure "src layout" qui est recommandée actuellement
+
+Ressources PyPA :
+
+- Remplacement des PEP, exemples
+ - [PEP 621](https://peps.python.org/pep-0621/) et [PEP 518](https://peps.python.org/pep-0518/) => [pyproject.toml specification](https://packaging.python.org/en/latest/specifications/pyproject-toml/)
+ - [PEP 566](https://peps.python.org/pep-0566/) => [Core metadata specifications](https://packaging.python.org/en/latest/specifications/core-metadata/)
+ - on ne voit pas clairement quelles sont les **métadonnées obligatoires**
+ - les specifications PyPA sont dans une arborescence, il faut savoir à quelle catégorie elles appartiennent pour les voir, pas de vision "à plat"
+ - plus d'information de redirection sur la PEP 518
+
+- [Names and normalization](https://packaging.python.org/en/latest/specifications/name-normalization/#name-normalization)
+- Guides > Building and Publishing > [Writing your pyproject.toml](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/#writing-pyproject-toml)
+- Discussions > [Distribution package vs. import package](https://packaging.python.org/en/latest/discussions/distribution-package-vs-import-package/)
+:::
+
+## Métadonnées
+
+Fichier de métadonnées, `pyproject.toml`, réduit au strict minimum
+^[Dépend du backend, [Flit](https://flit.pypa.io/) requiert la métadonnée "description"] :
+
+```toml
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hello_pyconfr"
+version = "0.1.0"
+```
+
+## Installation
+
+```bash
+$ pip install -e .
+```
+
+**editable install** ^[Local project installs : <https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs>] :
+le flag `-e` permet d'installer le package localement pour continuer à le
+développer et à le tester sans avoir à le ré-installer.
+
+```python
+>>> from hello_pyconfr.greetings import greet
+>>> greet()
+Hello PyConFR 2024
+```
+
+<br>
+
+::: {.callout-warning}
+1. Cette expérience a été réalisée dans un environnement virtuel
+2. On ne développement sans gestionnaire de version
+:::
+
+
+::: {.notes}
+Warning évident mais ça va mieux en le disant
+:::
+
+# pyproject.toml
+
+# identifiants de version Python
+
+# git tag
+
+# forges (GitHub, GitLab)
+
+# PyPI
+
+## Python Package Index
[PyPI](https://pypi.org/)
-## Page N
+# frontends
+
+# backends … et outils de workflow
+
+## uv
+
+- Annonce uv 0.3.0 : <https://astral.sh/blog/uv-unified-python-packaging>
+
+- <https://simonwillison.net/2024/Sep/8/uv-under-discussion-on-mastodon/>, cité par PythonBytes n°403
+- <https://simonwillison.net/2024/Aug/20/uv-unified-python-packaging/>
+
+- <https://andrich.me/2024/10/two-weeks-with-uv/>
+
+# Templates de projet
+
+
+## Cookiecutter
+
+Templates de projet ^[« Scientific Python Library Development Guide » : <https://learn.scientific-python.org/development/>]
+pour [Cookiecutter](https://cookiecutter.readthedocs.io/), [Copier](https://copier.readthedocs.io/) et [cruft](https://cruft.github.io/cruft/)
+
+```bash
+$ cookiecutter gh:scientific-python/cookie
+You've downloaded /home/fconil/.cookiecutters/cookie before. Is it okay to delete and re-download it? [y/n] (y): y
+ [1/9] The name of your project (package): hello_pyconfr
+ [2/9] The name of your (GitHub?) org (org): fconil
+ [3/9] The url to your GitHub or GitLab repository (https://github.com/fconil/hello_pyconfr):
+ [4/9] Your name (My Name): Françoise CONIL
+ [5/9] Your email (me@email.com): fcodvpt@gmail.com
+ [6/9] A short description of your project (A great package.): Test cookiecutter and scientific-python templates for Python packaging
+ [7/9] Select a license
+ 1 - BSD
+ 2 - Apache
+ 3 - MIT
+ Choose from [1/2/3] (1): 1
+ [8/9] Choose a build backend
+ 1 - Hatchling - Pure Python (recommended)
+ 2 - Flit-core - Pure Python (minimal)
+ 3 - PDM-backend - Pure Python
+ 4 - Poetry - Pure Python
+ 5 - Setuptools with pyproject.toml - Pure Python
+ 6 - Setuptools with setup.py - Pure Python
+ 7 - Setuptools and pybind11 - Compiled C++
+ 8 - Scikit-build-core - Compiled C++ (recommended)
+ 9 - Meson-python - Compiled C++ (also good)
+ 10 - Maturin - Compiled Rust (recommended)
+ Choose from [1/2/3/4/5/6/7/8/9/10] (1): 1
+ [9/9] Use version control for versioning [y/n] (y): y
+```
-::: {.incremental}
-- point 1
-- point 2
-- point 3
+::: {.notes}
+~/Progs/python/cookiecutter/README.2024-10-08.rst
+~/Progs/python/cookiecutter/experiment-packaging_2024/hello_pyconfr/
:::
+
+## Arborescence résultante
+
+```
+$ tree -a hello_pyconfr/
+hello_pyconfr/
+├── docs
+│ ├── conf.py
+│ └── index.md
+├── .git_archival.txt
+├── .gitattributes
+├── .github
+│ ├── CONTRIBUTING.md
+│ ├── dependabot.yml
+│ ├── release.yml
+│ └── workflows
+│ ├── cd.yml
+│ └── ci.yml
+├── .gitignore
+├── LICENSE
+├── noxfile.py
+├── .pre-commit-config.yaml
+├── pyproject.toml
+├── README.md
+├── .readthedocs.yaml
+├── src
+│ └── hello_pyconfr
+│ ├── __init__.py
+│ ├── py.typed
+│ └── _version.pyi
+└── tests
+ └── test_package.py
+```
+