example_pypi_package
v0.1.0
Este é um exemplo de pacote Pypi (Python Package Index) configurado com testes automatizados e fluxo de trabalho de publicação de pacotes usando ações GitHub CI/CD. É feito principalmente para usuários do Github + Vs Code (Windows / Mac / Linux) que estão prestes a escrever e publicar seu primeiro pacote PyPI. O pacote pode servir como um iniciador / clichê / demonstração e o tutorial pode fornecer uma explicação rápida e concisa para resolver alguns problemas pequenos, mas irritantes, que você pode encontrar, como confusão de nomes de pacote / módulo e problemas de configuração de teste de código.
Este pacote de exemplo é inspirado por / baseado no projeto oficial do projeto Pypa / SampleProject, mas este pacote:
master ou ramo main e é publicado ao criar uma versãoPYTHONPATH , para que os arquivos de teste não tenham erros de linha e possam ser executados com pytest no código VS(Clique no botão acima para usar este pacote de exemplo como um modelo para o seu novo repositório do Github, isso inicializará um novo repositório e meus compromissos não estarão no seu histórico de git)
(Se você não usar o Github, pode baixar o arquivo do pacote de exemplo)
Muitos usam o mesmo pacote e nome do módulo, você definitivamente pode fazer isso. Mas este pacote de exemplo e os nomes de seu módulo são diferentes: example_pypi_package e examplepy .
Aberto example_pypi_package Pasta com código do Visual Studio, Ctrl + Shift + F (Windows / Linux) ou CMD + Shift + F (macOS) para encontrar todas as ocorrências de ambos os nomes e substituí -los pelo seu pacote e nomes do módulo. Lembre -se também de alterar o nome da pasta SRC/Expletypy .
Simplesmente e de maneira grosseira, o nome do pacote é usado no pip install <PACKAGENAME> e o nome do módulo é usado na import <MODULENAME> . Ambos os nomes devem consistir em letras básicas minúsculas (AZ). Eles podem ter sublinhados ( _ ) se você realmente precisar deles. Hífen -minus ( - ) não deve ser usado.
Você também precisará garantir que o URL "https://pypi.org/project/example-pypi-package/" (substitua example-pypi-package pelo nome do seu pacote, com tudo _ se - ) não está ocupado.
Os sublinhados ( _ ) podem ser usados, mas esse uso é desencorajado. Os números podem ser usados se o nome não começar com um número, mas esse uso também for desencorajado.
Nome Começando com um número e/ou contendo hifen -minus ( - ) não deve ser usado: Embora tecnicamente legal, esse nome causa muito problema - os usuários precisam usar importlib para importá -lo.
Não se deixe enganar pelo URL "pypi.org/project/example-pypi-package/" e pelo nome "exemplo-pypi-package" no pypi.org. Pypi.org e PIP System convertem todos _ para - e use o último no comando do site / no pip , mas o nome real ainda está com _ , que os usuários devem usar ao importar o pacote.
Também há namespace para usar se você precisar de sub-pacotes.
Faça as alterações necessárias no setup.py .
O número da versão do pacote __version__ está no src/exemplopy/__ init__.py . Você pode querer mudar isso.
O pacote de exemplo foi projetado para ser compatível com Python 3.6, 3.7, 3.8, 3.9 e será testado em relação a essas versões. Se você precisar alterar o intervalo de versão, deve alterar:
classifiers , python_requires em setup.pyenvlist em tox.inimatrix: python: in .github/workflows/test.yml Se você planeja fazer o upload para o TestPypi, que é um playground de Pypi para fins de teste, altere twine upload --repository pypi dist/* para twine upload --repository testpypi dist/* no arquivo .github/workflows/release.yml .
Pip é um gerente de pacotes Python. Você já possui PIP se usar o Python 3.4 e a versão posterior que o inclui por padrão. Leia isso para saber como verificar se o PIP está instalado. Leia isso se precisar instalá -lo.
O Código do Visual Studio é o editor de código mais popular hoje, nosso pacote de exemplo está configurado para trabalhar com o código VS.
Instale vs extensão de código "python".
"Python" vs Extensão de código sugerirá que você instale o Pylint. Além disso, o pacote de exemplo está configurado para usar o Pytest com o código VS + Extensões Python; portanto, instale o Pylint e o Pytest:
pip install pylint pytest(É provável que você seja solicitado a instalá -los, se for esse o caso, você não precisa digitar e executar o comando)
O conteúdo do vscode.env agora é PYTHONPATH=/;src/;${PYTHONPATH} o que é bom para o Windows. Se você usa Linux ou MacOS, precisará alterá -lo para PYTHONPATH=/:src/:${PYTHONPATH} (substituindo ; por : . Se o caminho não estiver definido corretamente, você verá erros de linha nos arquivos de teste e o pytest não poderá executar testes/teste _*. Arquivos py corretamente.
Feche e reabra vs código. Agora você pode clicar no ícone do frasco de laboratório no menu esquerdo e executar todos os testes lá, com pytest. O Pytest parece melhor do que a estrutura mais importante, ele suporta unittest o que você pode continuar usando import unittest em seus arquivos de teste.
O pacote de exemplo também possui um arquivo .editorConfig . Você pode instalar vs extensão de código "EditorConfig para o código VS" que usa o arquivo. Com a configuração atual, a ferramenta EditorConfig pode usar automaticamente espaços (4 espaços para .py, 2 para outros) para indentação, definir a codificação LF UTF-8 , final das linhas, aparar os espaços de branco à direita em arquivos não markdown, etc.
No código VS, você pode acessar o arquivo -> Preferências -> Configurações, digitar "Provedor de formatação Python" na caixa de pesquisa e escolher uma das três ferramentas de formatação de código Python (AutoPep8, Black e Yapf), você será solicitado a instalá -lo. Os atalhos para a formatação de um arquivo de código são Shift + Alt + F (Windows); Shift + Opção (Alt) + F (MacOS); Ctrl + Shift + I (Linux).
Na SRC/ EXEMPLEPY/ ( examplepy , deve ter sido substituído pela pasta do nome do módulo), Renomeie o módulo1.py e escreva seu código nele. Adicione mais arquivos .py do módulo, se necessário.
Em testes/ pasta, renomeie test_module1.py (para testar _*. Py ) e escreva seu código de teste de unidade (com o unittest). Adicione mais testes _*. Arquivos Py, se necessário.
Instale o Tox e execute -o:
pip install tox
tox Em nossa configuração, o Tox executa uma verificação da distribuição de origem usando o manifest-me-mais (o que exige que seu repositório seja iniciante ( git init ) e adicionado ( git add . No entanto, você não precisa instalar o Manifest e o Pytest, o Tox os instalará em um ambiente separado.
Os testes automatizados são executados contra várias versões do Python, mas na sua máquina, você pode estar usando apenas uma versão do Python, se for o Python 3.9, depois execute:
tox -e py39 Se você adicionar mais arquivos ao diretório raiz ( exemplo_pypi_package/ ), precisará adicionar seu arquivo à lista check-manifest --ignore em tox.ini .
Instale ou atualize setuptools e wheel :
python -m pip install --user --upgrade setuptools wheel (Se python3 for o comando da sua máquina, altere python para python3 no comando acima ou adicione um alias python=python3 para ~/.bashrc ou ~/.bash_aliases arquivo se você usar o bash no linux)
dist No diretório example_pypi_package , execute o seguinte comando, a fim de gerar versão de produção para distribuição de origem (SDIST) na pasta dist :
python setup.py sdist bdist_wheelOpcionalmente, você pode instalar a versão distida do seu pacote localmente antes de fazer o upload para Pypi ou TestPypi:
pip install dist/example_pypi_package-0.1.0.tar.gz(Pode ser necessário desinstalar o pacote existente primeiro:
pip uninstall example_pypi_package Pode haver vários pacotes instalados com o mesmo nome, então execute pip uninstall várias vezes até que não diga mais pacote para remover.)
Registre uma conta no Pypi, vá para as configurações da conta § Tokens de API, "Adicionar token da API". O token Pypi só aparece uma vez, copie -o em algum lugar. Se você perdeu, exclua o antigo e adicione um novo token.
(Registre uma conta testpypi se você estiver enviando para o testpypi)
Na página do seu recém -criado ou existente do Github Repo, Clique em Configurações -> Segredos -> Novo repositório segredo , o nome deve ser PYPI_API_TOKEN e o valor deve ser o seu token Pypi (que começa com pypi- ).
O pacote de exemplo tem testes e upload automatizados (publicação) já configurados com ações do GitHub:
git push ou uma solicitação de tração é enviada em sua filial master ou main , o pacote é testado automaticamente nas versões Python desejadas com ações do GitHub. Depois que seu pacote for publicado no Pypi, acesse https://pypi.org/project/example-pypi-package/ ( _ se - ). Copie o comando na página, execute -o para baixar e instalar seu pacote no Pypi. (ou test.pypi.org se você usar isso)
Se você deseja modificar a descrição / leitura do seu pacote no Pypi.org, você deve publicar uma nova versão.
Instale ou atualize o barbante:
python -m pip install --user --upgrade twineCrie um arquivo .pypirc no seu diretório $ home ( ~ ), seu conteúdo deve ser:
[pypi]
username = __token__
password = <PyPI token> (Use [testpypi] em vez de [pypi] se você estiver enviando para o testpypi)
Substitua <PyPI token> pelo seu token Pypi real (que começa com pypi- ).
(Se você não criar manualmente $ home/.pypirc , você será solicitado a um nome de usuário (que deve ser __token__ ) e senha (que deve ser seu token Pypi) quando você executar o Twine)
Execute o barbante para fazer upload de todos os arquivos sob a pasta Dist :
python -m twine upload --repository pypi dist/ * pypi use testpypi
Quando você terminar de desenvolver uma versão mais recente do seu pacote, faça as seguintes coisas.
Modifique o número da versão __version__ em src ExempliPy__init __. Py .
Exclua todas as versões antigas no dist .
Execute o seguinte comando novamente para regenerar o Dist :
python setup.py sdist bdist_wheelExecute o seguinte comando novamente para fazer upload do Dist :
python -m twine upload --repository pypi dist/ * (Use testpypi em vez de pypi , se necessário)
BTW, se você deseja publicar o pacote TypeScript (JavaScript) no Registro NPM, acesse Exemplo de pacote TypeScript pronto para ser publicado no NPM para 2021.
