Python Academy · Aula

Versionamento e metadados

Gerencie os metadados do pacote

Versionamento e metadados é uma aula grátis de Python Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Python Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Python Academy inclui 4 aulas no total.

Por que os metadados são importantes

Metadados são todas as informações sobre seu pacote, exceto o código: versão, descrição, licença, autor e links. O PyPI os utiliza para exibir seu projeto, e o pip os utiliza para resolver dependências.

Bons metadados tornam seu pacote confiável e instalável.

Versionamento semântico

A convenção é MAJOR.MINOR.PATCH:

MAJOR: alterações incompatíveis
MINOR: novos recursos compatíveis com versões anteriores
PATCH: correções de erros compatíveis com versões anteriores

Os usuários dependem disso para saber se uma atualização é segura.

version = '2.4.1'
major, minor, patch = version.split('.')
print('Major', major, 'Minor', minor, 'Patch', patch)
print('Bug fix -> bump patch to', major + '.' + minor + '.' + str(int(patch) + 1))

Escolhendo a próxima versão

Decidir o bump segue regras: você quebrou a interface de programação, adicionou um recurso ou apenas corrigiu um erro? Codificar essa regra torna os lançamentos consistentes.

def bump(version, kind):
    major, minor, patch = (int(x) for x in version.split('.'))
    if kind == 'major':
        return str(major + 1) + '.0.0'
    if kind == 'minor':
        return str(major) + '.' + str(minor + 1) + '.0'
    return str(major) + '.' + str(minor) + '.' + str(patch + 1)

print(bump('1.2.3', 'minor'))
print(bump('1.2.3', 'major'))

Versões de pré-lançamento e desenvolvimento

Python permite sufixos: 1.0.0a1 (alfa), 1.0.0b2 (beta), 1.0.0rc1 (candidata a lançamento) e 1.0.0.dev3. O pip trata essas versões como anteriores à versão final 1.0.0, para que os testadores possam optar por elas sem afetar os usuários comuns.

Fonte única da verdade

Mantenha a versão em um único lugar. Declare-a estaticamente em pyproject.toml ou marque-a como dynamic e leia-a do código (ou de uma etiqueta) por meio de ferramentas como setuptools-scm. Duas cópias inevitavelmente se afastam uma da outra.

Descrição e README

Uma description curta aparece nos resultados de pesquisa. A descrição longa vem do seu readme (geralmente README.md) e é exibida como a página do projeto no PyPI. Aponte para ela com readme = 'README.md'.

Um README claro é a melhor forma de apresentar seu pacote.

Licença

Declare uma licença para que os usuários saibam quais são seus direitos. Projetos modernos usam uma expressão SPDX, como license = 'MIT'. Sem uma licença, todos os direitos ficam reservados, o que desestimula a adoção.

popular = ['MIT', 'Apache-2.0', 'BSD-3-Clause', 'GPL-3.0-only']
for lic in popular:
    print('SPDX:', lic)

Classificadores

classifiers são etiquetas padronizadas da lista do PyPI, como 'Programming Language :: Python :: 3.11' ou 'Development Status :: 4 - Beta'. Eles alimentam os filtros do PyPI e indicam o nível de maturidade e as versões compatíveis.

Endereços do projeto

Em [project.urls], adicione links como Página inicial, Documentação, Código-fonte e Registro de alterações. Eles aparecem em uma barra lateral no PyPI e ajudam os usuários a encontrar seu repositório e sua documentação.

urls = {
    'Homepage': 'https://example.com',
    'Source': 'https://github.com/me/mytool',
    'Issues': 'https://github.com/me/mytool/issues',
}
for label, link in urls.items():
    print(label.ljust(10), link)

Palavras-chave para descoberta

O campo keywords é uma lista de termos curtos que ajudam os usuários a encontrar seu pacote nas pesquisas. Escolha palavras que as pessoas realmente digitariam, como ['cli', 'automation', 'excel'], em vez de termos genéricos usados apenas para preencher espaço.

Junto com os classificadores, as palavras-chave melhoram a visibilidade do seu projeto.

Um registro de alterações

Mantenha um CHANGELOG que registre o que mudou em cada versão. Os usuários o consultam antes de atualizar para conhecer novos recursos e alterações incompatíveis. Vinculá-lo em [project.urls] permite acessá-lo com um clique a partir da página do PyPI.

Um bom registro de alterações transforma um número de versão em uma história que os usuários podem acompanhar.

Verificação rápida

Teste seus conhecimentos sobre versionamento.

Recapitulação

Você gerenciou os metadados do pacote:

Versionamento semântico MAJOR.MINOR.PATCH, além de sufixos de pré-lançamento
Mantenha a versão em uma fonte única da verdade
Forneça description, uma descrição longa no README e uma license
Adicione classifiers e [project.urls] para que o PyPI exiba bem seu projeto

Perguntas Frequentes

A aula “Versionamento e metadados” é grátis?

Sim — o texto completo de “Versionamento e metadados” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Python Academy, atualize para CoddyKit PRO. O curso de Python Academy inclui 4 aulas no total.

O que vou aprender em “Versionamento e metadados”?

Gerencie os metadados do pacote Você pratica Python Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Python Academy?

Nenhuma experiência prévia é necessária. Python Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “Versionamento e metadados”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Python Academy?

Sim. Cada aula de Python Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Python Academy