python_packaging_example

Exemplo de embalagem Python

Índice

• Instruções de instruções
• Fundo
• Alto nível
• Embalagem de projetos python
  • Construindo o pacote
  • Enviando o pacote para testpi
  • Enviando o pacote para Pypi
  • Atualizando manualmente o pacote
• Ações do Github CI/CD Fluxos de trabalho
  • Configurar
  • Upload para TestPyPi
  • Upload para PyPi via marcação
• Pytest em execução no Github CI/CD

---

Instruções de instruções

• Para configurar novos projetos e fazer lançamentos, consulte as versões CI/CD e Pypi

Fundo

Este é um exemplo de funcionamento que usa um fluxo de trabalho do GitHub Ações CI/CD para testar, criar e fazer upload de um pacote Python para testpi e Pypi.

Criei este pacote de exemplo trabalhando nesses guias;

• Embalagem de projetos python
• Publicação de lançamentos de distribuição de pacotes usando os fluxos de trabalho do GitHub Ações CI/CD
• Pytest com ações do github

O restante do ReadMe descreve para configurar um novo projeto da mesma maneira.

Quando configurado;

• O teste e o upload para testpiPi ocorre quando o número da versão do pacote é atualizado e uma confirmação é feita para a filial mestre
• Teste e upload para Pypi ocorre quando uma confirmação é marcada
• O pacote pode ser instalado usando pip install example-package-grumbit

---

Alto nível

Em um nível alto, o processo de configuração da embalagem do projeto Github CI/CD, incluindo pytesting, se parece com isso;

1. Configure a estrutura do arquivo conforme este pacote de exemplo, mas deixe de fora ./.github/workflows/publish-to-test-pypi.yml por enquanto.
2. Faça a embalagem local funcionando
3. Envie o upload para testpipi funcionando
4. Envie o upload para Pypi trabalhando
5. Adicione em ./.github/workflows/publish-to-test-pypi.yml e obtenha o github CI/CD

---

Embalagem de projetos python

Construindo o pacote

• Os metadados do pacote estão configurados em ./pyproject.toml
• Uma vez configurado, ele pode ser construído;

 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

Enviando o pacote para testpi

• Carregue o pacote para teste usando;

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

• Depois de carregar o pacote, um token de API específico do pacote deve ser configurado e salvo no testpypi

• Verifique se o pacote pode ser baixado e usado em um novo 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

Enviando o pacote para 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

• Depois de carregar o pacote, um token de API específico do pacote deve ser configurado e salvo em Pypi

Atualizando manualmente o pacote

• Cada vez que o pacote é atualizado, sua versão deve ser atualizada na seção [project] do ./pyProject.toml, então ele precisa ser reconstruído e carregado;

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

---

Ações do Github CI/CD Fluxos de trabalho

Configurar

• Se o projeto ainda não estiver sincronizado com o Github, execute;

 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

• Se a filial padrão não for master , altere-a no github ou altere .github/workflows/publish-to-test-pypi.yml .

• Adicione os tokens TestPypi e Pypi API ao repo

• Abra o repositório no Github usando gh browse . No navegador, clique em Settings -> Secrets -> Actions . Em seguida, adicione dois novos segredos chamados PYPI_API_TOKEN e TEST_PYPI_API_TOKEN , com os tokens da API criados após o upload dos pacotes acima

• Crie e configure .github/workflows/publicish to test-pypi.yml Workflow Definição

  • NB: publish-to-test-pypi.yml deste pacote deste pacote já possui as peças necessárias para o teste automático incluído (veja abaixo)

Upload para TestPyPi

• Toda vez que uma confirmação é feita para a filial master , o Github CI/CD será executado.
  • NB: Para que a embalagem tenha sucesso, a versão deve ser atualizada em ./pyProject.toml.
• Todos os compromissos com mestre serão enviados para TestPyPi

Upload para PyPi via marcação

• Colocar uma etiqueta em uma confirmação e empurrá -la fará com que o Github CI/CD seja executado e crie uma liberação do PyPI.

• Use o seguinte para marcar o último comprometimento (ou HEAD ) com a versão atualmente configurada em ./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 o seguinte para marcar uma confirmação 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

---

Pytest em execução no Github CI/CD

• As etapas do fluxo de trabalho no guia do Github CI/CD não incluíram a execução de pytests. Para fazer com que o pytest execute as dependências dos pacotes necessários para ser instalado e, em seguida, o Pytest Run antes da etapa de construção usando essas etapas adicionais;

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

• De acordo com a estrutura do diretório no guia de projetos de embalagem, coloquei os testes em uma hierarquia separada na fonte. Isso significava __init__.py necessário para adicionar ao src/ e aos tests/ diretório como este;
  • NB: Não tenho 100% de certeza sobre essa estruturação. Ele segue o guia e significa que o código de teste não está empacotado, no entanto, acho que é menos conveniente do que incorporar test/ pastas na src/ árvore. ./pyproject.toml pode ser configurado para que test/ pastas incorporado seja excluído, mas eu fui com o "padrão" por enquanto.

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