python_packaging_example

Exemple d'emballage Python

Table des matières

• Instructions pratiques
• Arrière-plan
• Niveau élevé
• Emballage des projets Python
  • Construire le forfait
  • Téléchargement du package sur TestPy
  • Téléchargement du package sur PYPI
  • Mise à jour manuelle du package
• GitHub Actions CI / CD Workflows
  • Installation
  • Téléchargement sur TestPyPi via s'engager à Master
  • Téléchargement sur PyPi via le marquage
• Exécution de Pytest dans GitHub CI / CD

---

Instructions pratiques

• Pour mettre en place de nouveaux projets et faire des sorties, consultez les versions CI / CD et PYPI

Arrière-plan

Il s'agit d'un exemple de travail qui utilise un flux de travail CI / CD GitHub Actions pour tester, créer et télécharger un package Python sur TestPyPi et PYPI.

J'ai créé cet exemple de package en travaillant via ces guides;

• Emballage des projets Python
• Publication des versions de distribution de packages en utilisant des actions GitHub CI / CD Workflows
• Pytest avec des actions github

Le reste de la lecture décrit pour mettre en place un nouveau projet de la même manière.

Lors de la configuration;

• Tester et télécharger sur TestPyPi se produit lorsque le numéro de version du package est mis à jour et un engagement est fait à la branche maîtresse
• Tester et télécharger sur PYPI se produit lorsqu'un commit est tagué
• Le package peut être installé à l'aide de pip install example-package-grumbit

---

Niveau élevé

À un niveau élevé, le processus de configuration de l'emballage du projet GitHub CI / CD, y compris Pytesting, ressemble à ceci;

1. Configurez la structure des fichiers selon cet exemple, mais laissez de côté ./.github/workflows/publish-to-test-pypi.yml pour l'instant.
2. Faire fonctionner les emballages locaux
3. Obtenez un téléchargement sur TestPyt Working
4. Obtenez un téléchargement sur PYPI Working
5. Ajouter ./.github/workflows/publish-to-test-pypi.yml et obtenez un gitub ci / cd

---

Emballage des projets Python

Construire le forfait

• Les métadonnées du package sont configurées dans ./pyproject.toml
• Une fois configuré, il peut être construit avec;

 cd < pacakges directory >
python3 -m venv .venv # Create the venv if it doesn't exist yet
source .venv/bin/activate
python3 -m pip install --upgrade pip setuptools wheel pip-tools pytest # Install the tools needed for the build tool
python3 -m pip install --upgrade build # Install the build tool itself
python3 -m build # build the package

Téléchargement du package sur TestPy

• Téléchargez le package pour les tests en utilisant;

python3 -m pip install --upgrade twine # Install the twine upload tool
python3 -m twine upload --repository testpypi dist/ * # Upload to TestPyPi
    # When prompted, the username is __token__ and the password is the TestPyPi global scope API token

• Ayant téléchargé le package, un jeton API spécifique à un package doit être configuré et enregistré dans TestPy

• Vérifier que le package peut être téléchargé et utilisé dans un nouveau venv ;

 cd < some new tmp directory >
python3 -m venv .venv 
source .venv/bin/activate
package_name= " example-package-grumBit "
python3 -m pip install --index-url https://test.pypi.org/simple/ --pre ${package_name}  # Check the package can be installed
python3 -c " from example_package_grumbit import example; print(example.add_one(1)) " # Check package functions

Téléchargement du package sur PYPI

python3 -m twine upload dist/ * # Upload to PyPi
    # When prompted, the username is __token__ and the password is the PyPi global scope API token

• Ayant téléchargé le package, un jeton API spécifique à un package doit être configuré et enregistré dans PYPI

Mise à jour manuelle du package

• Chaque fois que le package est mis à jour, sa version doit être mise à jour dans la section [project] de ./pyproject.toml, il doit être reconstruit et téléchargé;

vs ./pyproject.toml
python3 -m build # build the package
python3 -m twine check dist/ * # check the package can be uploaded
python3 -m twine upload --repository testpypi dist/ * # test uploading using TestPyPi
python3 -m twine upload dist/ * # Upload to PyPi

---

GitHub Actions CI / CD Workflows

Installation

• Si le projet n'est pas déjà synchronisé à GitHub, exécutez;

 cd " <the project's directory> "
repo_name= " <the new repo's name> "
gh repo create " ${repo_name} " --private
git init
git add --all
git commit -m " init "
git branch -M master
git remote add origin [email protected]:grumBit/ ${repo_name} .git
git push -u origin master

• Si la branche par défaut n'est pas master , modifiez-la sur github ou modifiez .github/workflows/publish-to-test-pypi.yml .

• Ajoutez les jetons API TestPyPi et PYPI au repo

• Ouvrez le dépôt sur GitHub à l'aide de gh browse . Dans le navigateur, cliquez sur Settings -> Secrets -> Actions . Ensuite, ajoutez deux nouveaux secrets appelés PYPI_API_TOKEN et TEST_PYPI_API_TOKEN

• Créer et configurer .github / workflows / Publish-to-test-PyPi.yml Workflow Définition

  • NB: Cet exemple de package de package publish-to-test-pypi.yml a déjà les pièces nécessaires pour les tests automobiles inclus (voir ci-dessous)

Téléchargement sur TestPyPi via s'engager à Master

• Chaque fois qu'un engagement est fait à la branche master , le GitHub CI / CD s'exécutera.
  • NB: Pour que l'emballage puisse réussir, la version doit être mise à jour dans ./pyproject.toml.
• Tous les engins à maîtriser seront téléchargés sur TestPyPi

Téléchargement sur PyPi via le marquage

• Mettre une balise sur un engagement et le pousser provoquera l'exécution de GitHub CI / CD et créera une version PYPI.

• Utilisez ce qui suit pour marquer le dernier engagement (IE HEAD ) avec la version actuellement configurée dans ./pyproject.toml ;

version_tag=v $( cat ./pyproject.toml | egrep " ^version " | cut -d ' " ' -f2 )
version_tag_info= " Some release info "
git tag -a " ${version_tag} " -m " ${version_tag_info} "
git push --tag

• Utilisez ce qui suit pour marquer un engagement antérieur;

version_tag= " vX.X.X "
version_tag_info= " Some release info "
commit_sha= " 16fb0fd "
git tag -a " ${version_tag} " " ${commit_sha} " -m " ${version_tag_info} "
git push --tag

---

Exécution de Pytest dans GitHub CI / CD

• Les étapes de workflow dans le guide GitHub CI / CD n'incluaient pas l'exécution de Pytests. Pour faire en sorte que PyTest exécute les dépendances des packages devait être installée, puis PyTest Run avant l'étape de construction en utilisant ces étapes supplémentaires;

    - name : Install requirements
      run : >-
        python -m
        pip install
        --requirement requirements.txt
    - name : Run tests
      run : >-
        python -m
        pytest

• Selon la structure du répertoire dans le guide des projets d'emballage, j'ai mis les tests dans une hiérarchie distincte à la source. Cela signifiait que __init__.py devait ajouter au src/ et tests/ répertoire comme celui-ci;
  • NB: Je ne suis pas sûr à 100% de cette structuration. Il suit le guide et signifie que le code de test n'est pas emballé, cependant, je pense que c'est moins pratique que l'intégration test/ dossiers dans le src/ Tree. ./pyproject.toml peut être configuré pour que test/ dossiers intégrés soient exclus, mais je suis allé avec la "norme" pour l'instant.

packaging_tutorial/
├── src/
│   ├── __init__.py
│   └── example_package_grumbit/
│       ├── __init__.py
│       └── example.py
└── tests/
    ├── __init__.py
    └── example_package_grumbit/
        ├── __init__.py
        └── test_example.py