Incremental é um gerenciador de versões CalVer que oferece suporte ao futuro.
A documentação da API pode ser encontrada aqui. Segue documentação narrativa.
Conteúdo
Teoria da Operação
Início rápido
Usando ferramentas de configuração
Usando Hatchling
Usando setup.py
Inicialize o projeto
Integração de tempo de execução
Versões incrementais
Atualizando
Versões Indeterminadas
Um número de versão tem o formato YY.MM.PATCH.
Se o seu projeto se chama "Shrubbery", seu código é encontrado em shrubbery/ ou src/shrubbery/ .
Incremental armazena o número da versão do seu projeto em {src/}shrubbery/_version.py .
Para atualizar a versão, execute incremental update Shrubbery , passando --rc e/ou --patch conforme apropriado (veja Atualização, abaixo).
Alterar a versão também atualiza quaisquer versões indeterminadas em sua base de código, como "Shrubbery NEXT", para que você possa fazer referência ao próximo lançamento na documentação. É assim que a Incremental apoia o futuro.
Adicione Incremental ao seu pyproject.toml :
[build-system]requires = ["setuptools","incremental>=24.7.2", # ← Adicionar incremental como uma dependência de compilação]build-backend = "setuptools.build_meta"[project]name = "<projectname>"dynamic = ["versão"] # ← Marque a versão dynamicdependencies = ["incremental>=24.7.2", # ← Depende de incremental em runtime]# ...[tool.incremental] # ← Ativar o plugin setuptools do Incremental
Tudo bem se a tabela [tool.incremental] estiver vazia, mas deve estar presente.
Remova qualquer [project] version = entrada e qualquer [tool.setuptools.dynamic] version = entrada.
Em seguida, inicialize o projeto.
Se você estiver usando o Hatchling para empacotar seu projeto, ative o plugin Hatchling do Incremental alterando seu pyproject.toml :
[build-system]requires = ["hatchling","incremental>=24.7.2", # ← Adicionar incremental como uma dependência de build]build-backend = "hatchling.build"[project]name = "<projectname>"dynamic = ["versão"] # ← Marcar a versão dynamicdependencies = ["incremental>=24.7.2", # ← Depender de incremental em tempo de execução]# ...[tool.hatch.version]source = "incremental" # ← Ativar o plugin Hatchling do Incremental
Incremental pode ser configurado normalmente em uma tabela opcional [tool.incremental] .
O comando hatch version reportará a versão gerenciada por Incremental. Use o comando incremental update para alterar a versão (não há suporte para configurá-la com hatch version ).
Em seguida, inicialize o projeto.
setup.py Incremental pode ser usado em setup.py em vez de pyproject.toml . Adicione isto à sua chamada setup() , removendo quaisquer outros argumentos de controle de versão:
setup(use_incremental=True,setup_requires=['incremental'],install_requires=['incremental'], # juntamente com quaisquer outras dependências de instalação... }
Em seguida, inicialize o projeto.
Instale o Incremental em seu ambiente local com pipx install incremental . Em seguida, execute incremental update <projectname> --create . Ele criará um arquivo em seu pacote chamado _version.py assim:
da importação incremental Version__version__ = Version("<projectname>", 24, 1, 0)__all__ = ["__version__"]As instalações subsequentes do seu projeto usarão Incremental para controle de versão.
Você pode expor o incremental.Version de _version.py na API do seu pacote. Para fazer isso, adicione ao __init__.py do seu pacote raiz:
de ._versão importar __versão__
Observação
Fornecer um atributo __version__ está saindo de moda após a introdução de importlib.metadata.version() no Python 3.6, que pode recuperar a versão de um pacote instalado.
Se você não expor esse objeto publicamente, nem utilizá-lo em seu pacote, não haverá necessidade de depender do Incremental em tempo de execução. Você pode removê-lo da matriz de dependencies do seu projeto (ou, em setup.py , de install_requires ).
incremental.Version é uma classe que representa uma versão de um determinado projeto. É composto pelos seguintes elementos (que são fornecidos durante a instanciação):
package (obrigatório), o nome do pacote que esta Version representa.
major , minor , micro (todos obrigatórios), o XYZ da Version do seu projeto.
release_candidate (opcional), definido como 0 ou superior para marcar esta Version como candidata a lançamento (às vezes também chamada de "pré-lançamento").
post (opcional), defina como 0 ou superior para marcar esta Version como pós-lançamento.
dev (opcional), defina como 0 ou superior para marcar esta Version como uma versão de desenvolvimento.
Você pode extrair uma string de versão compatível com PEP-440 usando o método .public() , que retorna uma str contendo a versão completa. Esta é a versão que você deve fornecer aos usuários ou usar publicamente. Um exemplo de saída seria "13.2.0" , "17.1.2dev1" ou "18.8.0rc2" .
Chamar repr() com uma Version fornecerá uma representação do código-fonte Python dele, e chamar str() em uma Version produz uma string como '[Incremental, version 16.10.1]' .
Incremental inclui uma ferramenta para automatizar a atualização da versão do seu projeto que usa Incremental, chamada incremental . Ele atualiza o arquivo _version.py e atualiza automaticamente alguns usos de versões incrementais de uma versão indeterminada para a atual. Requer click do PyPI.
incremental update <projectname> realizará atualizações nesse pacote. Os comandos que podem ser dados depois determinam qual será a próxima versão.
--newversion=<version> , para definir a versão do projeto para uma versão totalmente especificada (como 1.2.3 ou 17.1.0dev1).
--rc , para definir a versão do projeto como <year-2000>.<month>.0rc1 se a versão atual não for uma candidata a lançamento, ou aumentar o número da candidata a lançamento em 1, se for.
--dev , para definir o número da versão de desenvolvimento do projeto como 0, se não for uma versão de desenvolvimento, ou aumentar o número da versão de desenvolvimento em 1, se for.
--patch , para incrementar o número do patch da versão. Isso também redefinirá o número do release candidate, passando --rc ao mesmo tempo para incrementar o número do patch e torná-lo um release candidate.
--post , para definir o número de pós-lançamento do projeto como 0, se não for um pós-lançamento, ou aumentar o número de pós-lançamento em 1, se for. Isso também redefinirá o candidato a lançamento e os números de lançamento de desenvolvimento.
Se você não fornecer argumentos, o número do release candidate será removido, tornando-o um "lançamento completo".
Incremental suporta versões "indeterminadas", como substituto para a próxima versão "completa". Isto pode ser usado quando a versão que será exibida ao usuário final é desconhecida (por exemplo, "introduzida em" ou "obsoleta em"). Incremental oferece suporte às seguintes versões indeterminadas:
Version("<projectname>", "NEXT", 0, 0)
<projectname> NEXT
Quando você executa incremental update <projectname> --rc , eles serão atualizados para versões reais (assumindo que a versão final de destino seja 17.1.0):
Version("<projectname>", 17, 1, 0, release_candidate=1)
<projectname> 17.1.0rc1
Assim que a versão final for feita, ela se tornará:
Version("<projectname>", 17, 1, 0)
<projectname> 17.1.0
