Conheça o Hatch#

Nossos tutoriais de empacotamento Python usam o Hatch. Embora existam muitas ferramentas excelentes de empacotamento, escolhemos o Hatch porque:

  1. É uma ferramenta ponta a ponta que suporta a maioria das etapas necessárias para criar um pacote Python de qualidade. Iniciantes terão menos ferramentas para aprender se usarem o Hatch.

  2. Ele suporta diferentes opções de backend de construção caso você precise compilar código em outras linguagens.

  3. Como comunidade, a pyOpenSci decidiu que o Hatch é uma ferramenta amigável que suporta muitos casos de uso diferentes do Python científico.

Neste tutorial, você instalará e conhecerá um pouco mais o Hatch antes de começar a usá-lo.

Você precisa de duas coisas para concluir este tutorial com sucesso:

  1. Você precisa ter o Python instalado.

  2. Você precisa ter o Hatch instalado.

Importante

Se você ainda não tiver o Python instalado no seu computador, o Hatch fará isso por você quando você instalar o Hatch.

Instalar o Hatch#

Para começar, siga as instruções específicas do seu sistema operacional abaixo para instalar o Hatch.

Siga as instruções aqui.

  • Baixe o instalador GUI mais recente para MAC hatch-universal.pkg.

  • Execute o instalador e siga as instruções de instalação.

  • Se o seu terminal estiver aberto, reinicie-o.

  • No seu navegador, baixe o arquivo .msi correto para o seu sistema: hatch-x64.msi

  • Execute o arquivo instalador baixado e siga as instruções na tela.

Sugerimos que você instale o Hatch usando pipx no Linux. No entanto, se preferir outro método, consulte a documentação de instalação do Hatch para outras opções.

# First install pipx
> apt install pipx
# Then install hatch using pipx
> pipx install hatch

Dica

O Hatch também pode ser instalado diretamente usando pip ou conda. Recomendamos que você siga as instruções acima, pois descobrimos que os instaladores do Hatch para Windows e Mac são os mais fáceis e eficientes.

Nossos usuários Linux tiveram sucesso instalando o Hatch com pipx se já usam apt install.

Ambas as abordagens (usar um instalador gráfico no Windows/Mac e pipx) garantem que você tenha o Hatch instalado globalmente. Uma instalação global significa que o Hatch fica disponível em todos os seus ambientes Python no computador.

Verifique se o Hatch foi instalado corretamente#

Depois de concluir as instruções de instalação acima, abra o terminal e verifique se o Hatch foi instalado corretamente usando o comando abaixo:

hatch --version
# Hatch, version 1.9.4

Observe que o número de versão exibido por hatch --version provavelmente será diferente do mostrado acima neste tutorial.

Configurar o Hatch#

Depois de instalar o Hatch, você pode personalizar sua configuração. Isso inclui definir o nome padrão e a configuração de cada pacote que você criar. Embora esta etapa não seja obrigatória, recomendamos que você a faça.

O Hatch armazena sua configuração em um arquivo config.toml.

Embora você possa atualizar o arquivo config.toml pela linha de comando, pode ser mais fácil visualizá-lo e editá-lo em um editor de texto se for a primeira vez que o usa.

Etapa 1: Abrir e editar seu arquivo config.toml#

Para abrir o arquivo de configuração no explorador de arquivos, execute o seguinte comando no shell:

hatch config explore

Isso abrirá uma janela de diretório que permite clicar duas vezes no arquivo e abri-lo no seu editor de texto favorito.

Você também pode obter a localização do arquivo de configuração do Hatch executando o seguinte comando no shell:

hatch config find
# hatch config --help will show you all the options for config.

Etapa 2 - atualize seu e-mail e nome#

Com o arquivo aberto, atualize a tabela [template] do arquivo config.toml com seu nome e e-mail. Essas informações serão usadas em quaisquer arquivos de metadata pyproject.toml que você criar usando o Hatch.

[template]
name = "firstName LastName"
email = "your-email@your-domain.org"

Etapa 3#

Em seguida, defina tests como false na tabela [template.plugins.default].

Embora testes sejam importantes, definir a configuração de tests no Hatch como true criará um arquivo pyproject.toml mais complexo. Você não precisará usar esse recurso nesta série de tutoriais para iniciantes, mas o apresentaremos em tutoriais posteriores.

Seu arquivo config.toml deve ficar parecido com o exemplo abaixo.

mode = "local"
project = ""
shell = ""

[dirs]
project = []
python = "isolated"
data = "/Users/your/path/Application Support/hatch"
cache = "/Users/your/path/Library/Caches/hatch"

[dirs.env]

[projects]

[publish.index]
repo = "main"

[template]
name = "Leah Wasser"
email = "leah@pyopensci.org"

[template.licenses]
headers = true
default = [
    "MIT",
]

[template.plugins.default]
tests = false
ci = false
src-layout = true

[terminal.styles]

Observe também que a opção de license padrão é MIT. Embora abordemos license com mais detalhes em uma lição posterior, a license MIT é a permissive license recomendada por choosealicense.com e, por isso, a usaremos nesta série de tutoriais.

Você pode, claro, escolher outra license.

Etapa 4: Feche o arquivo de configuração e execute hatch config show#

Depois de concluir as etapas acima, execute o seguinte comando no shell.

hatch config show

hatch config show exibirá o conteúdo do seu arquivo config.toml no shell. Verifique os valores e confirme que seu nome e e-mail estão definidos. Certifique-se também de que tests=false.

Recursos do Hatch#

O Hatch oferece um conjunto de recursos que facilitam a criação, publicação e manutenção do seu pacote Python.

Comparação com outras ferramentas

Comparamos o Hatch a várias outras ferramentas populares de empacotamento do ecossistema, incluindo flit, pdm e poetry. Saiba mais aqui

Mais sobre o Hatch aqui

Alguns recursos que o Hatch oferece

  1. Ele converterá metadata armazenada em um arquivo setup.py ou setup.cfg para um arquivo pyproject.toml para você (consulte Migrating setup.py to pyproject.toml using Hatch)

  2. Ele ajudará armazenando informações de configuração para publicação no PyPI depois que você as informar uma vez.

Use hatch -h para ver todos os comandos disponíveis.

Próximos passos#

Na próxima lição você aprenderá como empacotar e tornar seu código instalável usando o Hatch.