python_packaging_example

Ejemplo de envasado de Python

Tabla de contenido

• Instrucciones sobre cómo hacer
• Fondo
• Alto nivel
• Embalaje de proyectos de Python
  • Construyendo el paquete
  • Subir el paquete a TestPypi
  • Subiendo el paquete a Pypi
  • Actualizando manualmente el paquete
• Github Actions CI/CD Flojos de trabajo
  • Configuración
  • Subir a TestPyPi a través de Compromed to Master
  • Subiendo a PyPi a través del etiquetado
• Ejecutando Pytest en Github CI/CD

---

Instrucciones sobre cómo hacer

• Para configurar nuevos proyectos y hacer lanzamientos, consulte los lanzamientos de CI/CD y PYPI

Fondo

Este es un ejemplo de trabajo que utiliza un flujo de trabajo de GitHub Actions CI/CD para probar, construir y cargar un paquete Python para TestPypi y Pypi.

Creé este paquete de ejemplo trabajando a través de estas guías;

• Embalaje de proyectos de Python
• Publicación de versiones de distribución de paquetes utilizando flujos de trabajo de GitHub Actions CI/CD
• Pytest con acciones de Github

El resto del ReadMe describe establecer un nuevo proyecto de la misma manera.

Cuando se configura;

• La prueba y la carga a TestPypi ocurre cuando se actualiza el número de versión del paquete y se hace una confirmación en la rama maestra
• La prueba y la carga a PYPI ocurre cuando se etiqueta una confirmación
• El paquete se puede instalar utilizando pip install example-package-grumbit

---

Alto nivel

En un alto nivel, el proceso para configurar el embalaje del proyecto GitHub CI/CD, incluido Pytesting, se ve así;

1. Configure la estructura del archivo según este paquete de ejemplo, pero déjelo de lado ./.github/workflows/publish-to-test-pypi.yml por ahora.
2. Hacer que el embalaje local funcione
3. Obtenga la carga al trabajo de TestPypi
4. Obtenga subida a Pypi Working
5. Agregue ./.github/workflows/publish-to-test-pypi.yml y obtenga github ci/cd funcione

---

Embalaje de proyectos de Python

Construyendo el paquete

• Los metadatos del paquete están configurados en ./pyproject.toml
• Una vez configurado, se puede construir con;

 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

Subir el paquete a TestPypi

• Cargue el paquete para probar el uso;

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

• Habiendo subido el paquete, se debe configurar y guardar un token API específico de paquete en TestPypi

• Verifique que el paquete se pueda descargar y usar en un nuevo 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

Subiendo el paquete a 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

• Habiendo subido el paquete, se debe configurar y guardar un token de API específico de paquete en PYPI

Actualizando manualmente el paquete

• Cada vez que se actualiza el paquete, su versión debe actualizarse en la sección [project] de ./pyproject.toml, entonces debe volver a construir y cargar;

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 Flojos de trabajo

Configuración

• Si el proyecto no se ha sincronizado hasta GitHub, ejecute;

 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 rama predeterminada no es master , cámbiela en GitHub o cambie .github/workflows/publish-to-test-pypi.yml .

• Agregue los tokens Testpypi y Pypi API al repositorio

• Abra el repositorio en GitHub usando gh browse . En el navegador, haga clic en Settings -> Secrets -> Actions . Luego agregue dos nuevos secretos llamados PYPI_API_TOKEN y TEST_PYPI_API_TOKEN , con los tokens API creados después de cargar los paquetes anteriores

• Crear y configurar .Github/Workflows/Publish-to-test-pypi.yml Workflow Definición

  • NB: publish-to-test-pypi.yml de este paquete de ejemplo ya tiene las piezas necesarias para la prueba automática incluida (ver más abajo)

Subir a TestPyPi a través de Compromed to Master

• Cada vez que se realiza una confirmación en la rama master , se ejecutará el GitHub CI/CD.
  • NB: Para que el embalaje tenga éxito, la versión debe actualizarse en ./pyproject.toml.
• Todos los compromisos con el maestro se subirán a TestPyPi

Subiendo a PyPi a través del etiquetado

• Poner una etiqueta en una confirmación y presionarla hará que se ejecute Github CI/CD y cree una versión PYPI.

• Use lo siguiente para etiquetar el último compromiso (IE HEAD ) con la versión actualmente configurada en ./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

• Use lo siguiente para etiquetar una confirmación anterior;

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

---

Ejecutando Pytest en Github CI/CD

• Los pasos de flujo de trabajo en la guía GitHub CI/CD no incluyeron ejecutar pytests. Para que Pytest ejecute las dependencias de los paquetes necesarios para instalarse y luego se ejecuta Pytest antes del paso de compilación utilizando estos pasos adicionales;

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

• Según la estructura del directorio en la Guía de proyectos de embalaje, puse las pruebas en una jerarquía separada a la fuente. Esto significaba __init__.py necesario para agregar al src/ y tests/ directorio como este;
  • NB: No estoy 100% seguro de esta estructuración. Sigue la guía y significa que el código de prueba no está empaquetado, sin embargo, creo que es menos conveniente que test/ carpetas de incrustación dentro del src/ árbol. ./pyproject.toml se puede configurar para que se excluyan test/ carpetas integradas, pero he ido con el "estándar" por ahora.

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