Empacotar uma biblioteca Python

De uma pasta de scripts a uma biblioteca instalável

O código que vive numa pasta de scripts funciona em uma máquina, para uma pessoa, até o dia em que outra pessoa precisa dele ou você precisa dele em outro ambiente. Empacotar transforma seu código numa biblioteca com nome, versão e dependências declaradas que qualquer um instala com pip install. É assim que uma equipe compartilha uma biblioteca de precificação sem copiar arquivos, que um notebook de pesquisa e um job de produção executam exatamente o mesmo código, e que uma correção chega a todos por um novo número de versão.

# Versions are numbers, not text: compare them as tuples
def parse_version(text):
    parts = [int(part) for part in text.split(".")]
    return tuple(parts + [0] * (3 - len(parts)))

print("1.10" > "1.9")                                # False  as text, "1" < "9" decides it: wrong
print(parse_version("1.10") > parse_version("1.9"))  # True   as numbers (1, 10, 0) is newer than (1, 9, 0)
print(parse_version("2"))                            # (2, 0, 0)

Estrutura, pyproject.toml e build

Um layout comum põe o código em src/yourlib/ (com um __init__.py), os testes em tests/ e um pyproject.toml na raiz. Esse único arquivo nomeia a ferramenta de build (a tabela [build-system]) e descreve o projeto: seu name, version, uma descrição, as versões do Python suportadas e suas dependencies. pip install -e . instala a pasta em modo editável enquanto você desenvolve, então as edições valem na hora; python -m build produz um wheel (.whl, pronto para instalar) e um sdist (arquivo-fonte) em dist/. Ponha a versão em um só lugar e exponha-a como yourlib.__version__ se os usuários precisarem.

# A minimal pyproject.toml, generated and then read back with tomllib to prove it is valid
import tomllib

def pyproject_toml(name, version, dependencies):
    lines = ["[build-system]", 'requires = ["setuptools>=68"]', 'build-backend = "setuptools.build_meta"', "",
             "[project]", f'name = "{name}"', f'version = "{version}"']
    if dependencies:
        lines += ["dependencies = ["] + [f'    "{d}",' for d in dependencies] + ["]"]
    else:
        lines.append("dependencies = []")
    return "\n".join(lines) + "\n"

text = pyproject_toml("qcpricing", "0.3.0", ["numpy>=1.26", "pandas>=2"])
data = tomllib.loads(text)
print(data["project"]["name"], data["project"]["version"])      # qcpricing 0.3.0
print(data["project"]["dependencies"])                          # ['numpy>=1.26', 'pandas>=2']

Versões e especificadores de versão

A maioria das bibliotecas segue o versionamento semântico: MAJOR.MINOR.PATCH. Uma correção de bug sobe o patch (1.4.2 para 1.4.3), uma funcionalidade retrocompatível sobe o minor e zera o patch (1.5.0) e uma mudança incompatível sobe o major (2.0.0). As dependências são declaradas com especificadores: numpy>=1.26,<3 aceita qualquer NumPy da 1.26 até a 3, exclusive. Seja tão flexível quanto puder ser honestamente: um limite inferior para a versão mais antiga que testou, um limite superior só para uma versão major que sabe que o quebra. Fixar versões exatas (==) cabe ao arquivo de lock de uma aplicação, não a uma biblioteca que outros instalam.

# Bumping a version and checking a requirement, with versions compared as tuples
import operator

def parse_version(text):
    parts = [int(part) for part in text.split(".")]
    return tuple(parts + [0] * (3 - len(parts)))

def bump_version(version, part):
    major, minor, patch = parse_version(version)
    return {"major": f"{major + 1}.0.0", "minor": f"{major}.{minor + 1}.0", "patch": f"{major}.{minor}.{patch + 1}"}[part]

OPS = {">=": operator.ge, "<": operator.lt, "==": operator.eq}

def satisfies(version, specifier):
    for clause in specifier.split(","):
        symbol = next(op for op in (">=", "==", "<") if clause.startswith(op))
        if not OPS[symbol](parse_version(version), parse_version(clause[len(symbol):])):
            return False
    return True

print(bump_version("1.4.2", "minor"))                # 1.5.0
print(satisfies("1.26.4", ">=1.26,<3"), satisfies("3.0.0", ">=1.26,<3"))      # True False

# One place for the version: read it from the source instead of repeating it in several files
import re

init_py = """__version__ = "0.3.0"
from .pricing import price
"""
match = re.search(r'^__version__ = "([^"]+)"', init_py, re.MULTILINE)
version = match.group(1)
print(version)                                       # 0.3.0
print(tuple(int(part) for part in version.split(".")))      # (0, 3, 0)

• O empacotamento dá ao código um nome, uma versão e dependências declaradas, instalável com pip install; desenvolva com pip install -e ., construa com python -m build.
• O pyproject.toml guarda o sistema de build e os metadados [project]; compare versões como tuplas de números, nunca como texto.
• Use versionamento semântico (MAJOR.MINOR.PATCH) e especificadores flexíveis (numpy>=1.26,<3); nunca mude uma versão publicada e deixe os segredos fora do pacote.

A seguir: CI/CD para código quantitativo, executar as verificações automaticamente a cada mudança.

Lab: o que é avaliado

• Comparar versões como números com parse_version25 pts
• Lançar a próxima versão com bump_version25 pts
• Verificar um requisito com satisfies25 pts
• Descrever o pacote com pyproject_toml25 pts