Documentação / Publicação: SDK Python (pilot-status)

Publicação: SDK Python (pilot-status)

Entrar

Publicação: SDK Python (pilot-status)

Este guia descreve como publicar o SDK Python que vive em:

  • packages/sdk-python/

O pacote publicado no PyPI é pilot-status.

Link:

  • https://pypi.org/project/pilot-status/

Pré-requisitos

  • Acesso de publish no PyPI para o projeto pilot-status
  • Python >= 3.10
  • Para publicar via GitHub Actions (recomendado): PyPI configurado com Trusted Publisher (OIDC) para este repositório
  • Para publicar manualmente (opcional): build + twine e credenciais/token do PyPI

O que vai para o PyPI

  • O build gera:
    • dist/*.whl (wheel)
    • dist/*.tar.gz (sdist)
  • A versão vem do pyproject.toml ([project].version)

Publicação via GitHub Actions (recomendado)

Este repositório já possui workflow de publicação:

  • .github/workflows/publish-pypi.yml

Ele publica quando você cria uma tag no formato:

  • sdk-python-v* (ex.: sdk-python-v0.1.2)

O workflow valida que a versão da tag é igual à versão do pyproject.toml e então faz build + publish via OIDC (sem token do PyPI no GitHub).

1) Atualize a versão

Edite packages/sdk-python/pyproject.toml e incremente:

  • [project].version

Commit e faça push.

2) Crie e envie a tag de release

No repositório raiz:

git tag sdk-python-v0.1.2
git push origin sdk-python-v0.1.2

Isso dispara o workflow e publica no PyPI.

3) Publicação manual do workflow (workflow_dispatch)

O workflow também pode ser executado manualmente pelo GitHub Actions.

Obs.: quando executado sem tag, a etapa de verificação de versão (tag vs pyproject.toml) não roda. Na prática, prefira o fluxo por tag para evitar publicar uma versão errada.

Passo a passo (manual)

1) Atualize a versão

Edite packages/sdk-python/pyproject.toml e incremente:

  • [project].version

2) Prepare o ambiente de build

Execute dentro de packages/sdk-python/:

python -m pip install -U pip
python -m pip install -U build twine

3) Rode testes (se aplicável)

Se você tiver um ambiente/runner para os testes:

python -m pytest

Obs.: o repositório possui testes em packages/sdk-python/tests/.

4) Gere os artefatos

Limpe builds anteriores e gere sdist + wheel:

rm -rf dist build
python -m build

5) Valide o pacote antes de publicar

python -m twine check dist/*

6) Publique no PyPI

Opção A (login interativo):

python -m twine upload dist/*

Opção B (token, recomendado):

TWINE_USERNAME=__token__ TWINE_PASSWORD="$PYPI_TOKEN" python -m twine upload dist/*

Verificações pós-publicação

  • Instalar num ambiente limpo:
python -m pip install -U pilot-status
  • Confirmar a versão instalada:
python -c "import pilot_status; print(pilot_status.__package__)"

Teste local sem publicar

Opção A (instalação editável):

python -m pip install -e .

Opção B (instalar wheel local):

python -m build
python -m pip install dist/*.whl

Observações (boas práticas)

  • Sempre publique com dist/ gerado a partir de um working tree limpo (reduz risco de artefatos errados).
  • Se mudar contratos/formatos de payload, atualize README.md e faça bump de versão coerente com SemVer.