Use ambientes Hatch com seu pacote puro Python#
Sobre esta lição
Em uma lição anterior, você aprendeu a criar um pacote Python usando o copier template da pyOpenSci. Nesta lição, você aprenderá a gerenciar e usar os ambientes Hatch configurados no O que você precisa para completar esta lição
Para completar esta lição, você precisará de um Python environment local e shell no seu computador. Você precisará ter criado um pacote usando nosso copier template da pyOpenSci. Você também deve ter Hatch instalado.
Se estiver usando Windows ou não estiver familiarizado com Shell, pode querer conferir a Carpentries shell lesson. Usuários do Windows provavelmente precisarão configurar uma ferramenta como GitBash para qualquer passo relacionado a Shell e git.
Boas-vindas ao seu novo pacote! Esta página ajudará você a começar a usar Hatch para executar testes, fazer o build e verificar seu pacote e construir sua documentação.
Para começar, dê uma olhada no arquivo pyproject.toml no diretório do seu pacote. Este arquivo contém a configuração do seu pacote e é escrito no formato TOML. Aqui vai o TL&DR:
Cada seção
[]no arquivo toml é chamada de tabela.Você pode aninhar tabelas com colchetes duplos assim
[[]]Tabelas contêm informações sobre algo que você quer configurar.
Dica
Você pode configurar o Hatch para usar UV por padrão para gerenciamento de ambiente. UV é um gerenciador de pacotes construído em Rust. É rápido e acelerará significativamente a criação de ambientes.
Para usar UV com Hatch, configure o Hatch na seção «tools» do seu arquivo pyproject.toml.
[tool.hatch.envs.default]
installer = "uv"
Usando Hatch para desenvolver, fazer o build, e manter seu pacote Python puro#
No template de pacote Python da pyOpenSci, configuramos definições deHatch environment. Você notará na parte inferior do arquivo uma seção hatch environment, que se parece com isto:
########################################
# Hatch Environments
########################################
Hatch permite que você configure e execute ambientes e scripts de forma semelhante a uma ferramenta de workflow como tox ou nox.
Dica
Hatch usa venv por padrão para gerenciar ambientes. Porém, você pode configurá-lo para usar outras ferramentas de ambiente, como conda ou mamba.
Leia a documentação do Hatch para saber mais sobre ambientes.
Abaixo está o ambiente Hatch usado para fazer o build e testar seu pacote. Sempre que você vir: tool.hatch.envs.test, isso informa ao Hatch:
«Ei, Hatch, esta é a definição de um ambiente.
testé o nome do ambiente que quero que você crie.»
Então tool.hatch.envs.build criará um ambiente chamado build.
Abaixo da «declaração» do ambiente, você pode ver a definição do que deve estar nesse ambiente.
Um ambiente Hatch para fazer o build do seu pacote#
Abaixo está uma definição de ambiente Hatch que você encontrará no arquivo pyproject.toml do seu novo projeto. Ela está configurada para fazer o build dos arquivos de distribuição do seu pacote (distribuição fonte (sdist) e Wheel (.whl)).
Observe que a definição do ambiente declara duas dependências: pip e twine, que o ambiente precisa para executar com sucesso. Esta declaração é semelhante a declarar dependencies para o seu pacote no topo do seu pyproject.toml.
[tool.hatch.envs.build]
description = """Test the installation the package."""
dependencies = [
"pip",
"twine",
]
detached = true
Hatch instalará seu pacote em modo editável por padrão
Observe a flag detached = True na parte inferior do ambiente. Por padrão, o Hatch instalará seu pacote em modo editável em qualquer ambiente que criar. detached=True informa para não instalar seu pacote no ambiente.
Hatch scripts#
Hatch suporta a definição de comandos Script (Hatch) que executam em ambientes Hatch específicos.
Acima, você definiu um novo ambiente chamado “build” que o Hatch criará como um ambiente virtual (venv). Como detached = True nesse ambiente, o Hatch não instalará seu pacote nele.
Você pode então usar esse ambiente para executar «scripts». A definição abaixo informa ao Hatch para executar os seguintes scripts no ambiente build.
[tool.hatch.envs.build.scripts]
Você define este scripts para executar usando a seguinte sintaxe, onde:
tool.hatch: Alerta o Hatch de que esta tabela é para o Hatch usarenvs.build: Use o ambiente build definido.scripts: Defina quais scripts executar. Neste caso, o Hatch executará shell scripts.
Abaixo está a tabela build.scripts que define 3 comandos shell a serem executados:
pip check# verifica suas dependencieshatch build --clean# faz o build dos arquivos de distribuição do seu pacote.twine check dist/*# usa twine para verificar se o sdist (source distribution) do seu pacote está ok.
# This table installs the command hatch run install:check, which will build and check your package.
[tool.hatch.envs.build.scripts]
check = [
"pip check",
"hatch build {args:--clean}",
"twine check dist/*",
]
detached = true
Dica
Hatch, por padrão, instalará seu pacote em modo editável em qualquer ambiente virtual (venv) que criar. Se detached=True estiver definido, ele pulará essa etapa.
Executando o build script#
Você pode executar o build script e fazer o build do seu pacote assim:
hatch run build:check
Esta etapa atualiza o ambiente build e então faz o build e verifica as distribuições de saída do seu pacote.
Você pode entrar no ambiente build no seu shell para conferir:
$ hatch shell build
Se executar pip list no ambiente, o twine estará lá:
$ pip list
Para sair do ambiente, use:
$ deactivate
Hatch, testes, e ambientes matriz#
É sempre útil executar seus testes nas versões do Python que você espera que seus usuários estejam usando. Nesta seção, você explorará a configuração do ambiente de teste no pacote template da pyOpenSci.
Abaixo, você vê a tabela do ambiente Hatch test.
Semelhante ao ambiente build acima, o ambiente abaixo define as dependencies que o Hatch precisa instalar no ambiente de teste (necessárias para executar seus testes).
[tool.hatch.envs.test]
description = """Run the test suite."""
dependencies = [
"pytest",
"pytest-cov",
"pytest-raises",
"pytest-randomly",
"pytest-xdist",
]
Seu ambiente de teste tem uma matriz associada a ele#
Se o ambiente tiver uma matriz associada, isso informa ao Hatch para executar os testes em diferentes versões do Python. Abaixo, você está executando testes nas versões 3.10 a 3.13.
Dica
Hatch, por padrão, instalará Python usando UV tanto quando você instala o Hatch quanto quando declara um ambiente matriz como o abaixo
[[tool.hatch.envs.test.matrix]]
python = ["3.10", "3.11", "3.12", "3.13"]
No seu projeto, se executar hatch shell test, verá a saída abaixo. Isso significa que, como há uma matriz de versões do Python para escolher, você precisa selecionar o ambiente com a versão do Python que deseja usar.
➜ hatch shell test
Environment `test` defines a matrix, choose one of the following instead:
test.py3.10
test.py3.11
test.py3.12
test.py3.13
Escolha o ambiente de teste Python que deseja usar e entre nele, assim (isso abrirá o Python 3.13):
$ hatch shell test.py3.13
Para sair do ambiente, use:
$ deactivate
Hatch scripts para testes#
Na mesma seção de testes, você verá uma seção tool.hatch.envs.test.scripts. Semelhante ao que você viu acima com as etapas de build, é aqui que o «script» para executar seus testes é definido.
Observe que abaixo o script tem um script chamado run. E esse scriptexecuta pytest com um conjunto de argumentos, incluindo geração de code coverage.
[tool.hatch.envs.test.scripts]
run = "pytest {args:--cov=greatproject --cov-report=term-missing}"
Para executar este script no seu terminal, use a sintaxe:
hatch run test:run
Lembrete
hatch run: isso chama o Hatch e informa que ele executará um comandotest:rundefine o ambiente em que você quer que execute (test) neste caso, e o script é definido comorun
Se você tiver uma matriz configurada para testes, ela instalará a versão necessária do Python usando UV e executará seus testes em cada versão do ambiente Python. Neste caso, como há quatro versões do Python no ambiente, seus testes serão executados quatro vezes, uma em cada versão do Python listada na tabela matrix.
@lwasser ➜ /workspaces/pyopensci-scipy25-create-python-package (main) $ hatch run test:run
──────────────────────────────────────────────────────────────────────── test.py3.10 ────────────────────────────────────────────────────────────────────────
==================================================================== test session starts ====================================================================
platform linux -- Python 3.10.16, pytest-8.4.1, pluggy-1.6.0
Using --randomly-seed=1490740387
rootdir: /workspaces/pyopensci-scipy25-create-python-package
configfile: pyproject.toml
testpaths: tests
plugins: xdist-3.8.0, randomly-3.16.0, raises-0.11, cov-6.2.1
collected 2 items
tests/system/test_import.py . [ 50%]
tests/unit/test_example.py . [100%
****************** SOME OUTPUT IS INTENTIONALLY DELETED ********************
====================================================================== tests coverage =======================================================================
_____________________________________________________ coverage: platform linux, python 3.11.12-final-0 ______________________________________________________
Name Stmts Miss Branch BrPart Cover Missing
----------------------------------------------------------------------------
src/greatproject/__init__.py 0 0 0 0 100.00%
src/greatproject/example.py 2 0 0 0 100.00%
----------------------------------------------------------------------------
TOTAL 2 0 0 0 100.00%
===================================================================== 2 passed in 0.05s =====================================================================
Construa sua documentação com um ambiente Hatch#
Por fim, você pode fazer o build e servir sua documentação usando o Hatch. Para gerar uma versão HTML estática da documentação, execute:
hatch run docs:build
Para executar um servidor local com a documentação atualizada conforme você modifica seus arquivos markdown, execute:
hatch run docs:serve
Para parar de servir a documentação, use:
mac: ctrl + c windows: