Primeiros passos e boas práticas com Python do zero

Começar com Python é simples. Crescer com qualidade é onde a maioria emperra. Se você quer sair do básico rápido e sem gambiarra, este guia é o atalho.

Python hoje é maduro, rápido de produzir e gigante no ecossistema. Aqui você vai montar um setup profissional para escrever código limpo, testar, medir e entregar.

Com este artigo você sai do “hello world” para um pipeline sólido, vendo: PEP 8, pyproject.toml, pytest, ruff/black, logging, CI e empacotamento.

Python no Mercado e Ecossistema

• Web, dados e automação: Continua sendo a escolha principal para CLIs, serviços e APIs.
• Inteligência Artificial: O ecossistema de IA e agentes autônomos é predominantemente construído em Python.
• Documentação: A documentação oficial é consistente e atende desde o iniciante até o especialista.

Python em Automação e IA de Agentes

Frameworks de agentes em Python encurtam drasticamente o ciclo do protótipo ao produto.

• CrewAI: Ideal para orquestrar agentes, tarefas e ferramentas de forma colaborativa.
• Agno: Um runtime completo para agentes, integrando LLMs, memórias e ferramentas de maneira eficiente.

Por que Python? A resposta é simples: velocidade de entrega + ecossistema de bibliotecas. Os ganhos em produtividade e integração são imediatos, especialmente em automação e IA.

Por que Python Continua Dominante em 2025

• Comunidade: Enorme, ativa e com suporte para praticamente qualquer desafio.
• Bibliotecas: Um ecossistema maduro que resolve desde web scraping até computação quântica.
• Ferramentas Modernas: Ferramentas como Ruff e uv aceleram drasticamente o ciclo de desenvolvimento.
• Evolução Constante: Versões estáveis e em evolução, como a 3.13, garantem a longevidade da linguagem.

Setup Profissional em Minutos

Instalação e Gerenciadores (uv, venv, pipx)

• uv: Ferramenta moderna da Astral que instala Python, cria ambientes virtuais (venvs) e gerencia dependências. É extremamente rápido.
• venv: O padrão da biblioteca nativa do Python para isolar as dependências de cada projeto.
• pip: O instalador de pacotes clássico, ainda fundamental no ecossistema.
• pipx: A melhor forma de instalar ferramentas de linha de comando (CLIs) de forma isolada e global.

Comandos Essenciais com uv

# 1. Instale uv (consulte a documentação para o seu sistema)

# 2. Crie um projeto e ative o ambiente virtual
uv init myapp
cd myapp
uv python install 3.12
uv venv
source .venv/bin/activate # Windows: .venv\Scripts\activate

# 3. Adicione ferramentas de desenvolvimento e dependências
uv add "fastapi[all]" ruff black pytest mypy

# 4. Execute um comando dentro do ambiente
uv run python -V

Alternativa com Poetry

Poetry é outra excelente ferramenta que gerencia dependências, lockfiles e o build do projeto, tudo a partir do pyproject.toml.

Nota Técnica: uv oferece uma interface compatível com pip e um sistema de lock universal. Já o Poetry é um gerenciador de projetos completo com seu próprio resolvedor de dependências. A escolha depende do seu fluxo de trabalho.

• Use uv para máxima velocidade e simplicidade.
• Use Poetry se você já prefere seu ecossistema e plugins.
• Use venv sempre para isolar projetos.
• Use pipx para instalar CLIs como black, ruff e o próprio uv.

Ambiente Reprodutível: pyproject.toml

O pyproject.toml é o padrão moderno para centralizar metadados do projeto, dependências, configurações de build e de ferramentas como ruff e pytest. Ele substitui a necessidade de múltiplos arquivos de configuração.

Bulleted List:

• Padrão: A PEP 621 padroniza como os metadados do projeto são definidos.
• Consistência: Use um arquivo de lock (uv.lock ou poetry.lock) para garantir que todos os desenvolvedores e ambientes de produção usem exatamente as mesmas versões de pacotes.
• Boas Práticas: Sempre defina a versão mínima do Python exigida com a chave requires-python = ">=3.xx".

Arquitetura Mínima que Escala

Estrutura de Pastas e Módulos

Uma boa estrutura de projeto evita importações confusas e facilita a localização de código. Separe o código-fonte, os testes, a documentação e os scripts.

myapp/
├── pyproject.toml
├── README.md
├── src/
│   └── myapp/
│       ├── __init__.py
│       ├── api.py
│       └── core/
│           ├── __init__.py
│           └── logic.py
└── tests/
  └── test_core.py

• A pasta src/ (source layout) previne problemas de importação e garante que seu pacote seja instalado corretamente.
• Mantenha os testes em uma pasta separada, mas com uma estrutura que espelhe a do seu código-fonte.
• Arquivos de configuração e documentação devem ficar na raiz do projeto.

Boas Práticas Fundamentais

PEP 8 e Estilo Consistente

Um código consistente é mais fácil de ler e manter. Ferramentas automatizadas eliminam debates sobre estilo.

• PEP 8: O guia de estilo oficial do Python. Define convenções para nomeação, imports, espaçamento, etc.
• black: Um formatador de código opinado que garante um estilo uniforme em todo o projeto.
• ruff: Um linter e formatador extremamente rápido, escrito em Rust, que pode substituir dezenas de outras ferramentas.

Configuração mínima no pyproject.toml:

TOML

[tool.black]
line-length = 88
target-version = ['py312']

[tool.ruff]
line-length = 88
target-version = "py312"

[tool.ruff.lint]
# E (pycodestyle), F (Pyflakes), I (isort), B (flake8-bugbear)
select = ["E", "F", "I", "B"]

Fluxo de Trabalho Recomendado:

1. Escreva seu código.
2. Execute ruff check --fix . para corrigir erros e organizar imports.
3. Execute black . para garantir a formatação final.
4. Configure seu CI para falhar se o código não seguir esses padrões.

Docstrings e Tipagem Estática (mypy)

Tipos estáticos e boa documentação previnem bugs e tornam o código mais compreensível.

• Tipagem: Use anotações de tipo (str, int, list[str]) para detectar erros antes da execução.
• Docstrings: Documente o que a função faz, seus argumentos (Args) e o que ela retorna (Returns).
• mypy: O verificador de tipos mais popular, que analisa seu código em busca de inconsistências.

Exemplo de função bem documentada e tipada:

PYTHON

from typing import Iterable

def calculate_mean(numbers: Iterable[float]) -> float:
  """Calcula a média aritmética de uma sequência.

  Args:
      numbers: Uma sequência de números do tipo float.

  Returns:
      A média dos valores ou 0.0 se a sequência estiver vazia.
  """
  data = list(numbers)
  if not data:
      return 0.0
  return sum(data) / len(data)

Logging Profissional

Pare de usar print() para depuração. O módulo logging nativo do Python oferece controle, níveis de severidade e flexibilidade para ambientes de desenvolvimento e produção.

PYTHON

import logging

# Configuração básica para exibir logs a partir do nível INFO
logging.basicConfig(
  level=logging.INFO,
  format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
  datefmt="%Y-%m-%d %H:%M:%S",
)

# Obter um logger específico para o módulo atual
logger = logging.getLogger(__name__)

def process_data(path: str) -> None:
  logger.info("Iniciando processamento do arquivo: %s", path)
  try:
      logger.info("Arquivo %s processado com sucesso.", path)
  except Exception:
      logger.error("Falha ao processar o arquivo: %s", path, exc_info=True)

• Use Níveis: DEBUG para diagnóstico, INFO para eventos normais, WARNING para alertas, ERROR para problemas.
• Adicione Contexto: Inclua variáveis e informações relevantes nas mensagens de log.
• Configure Handlers: Em produção, configure o logging para enviar logs para arquivos, serviços de monitoramento ou o console de forma estruturada (JSON).

Qualidade e Manutenção Contínua

Testes com pytest

pytest é o framework de testes padrão da indústria para Python devido à sua simplicidade e poder.

• Simplicidade: Testes são apenas funções que começam com test_. Use assert para verificar os resultados.
• Fixtures: Reutilize código de setup (como conexões de banco de dados) de forma elegante.
• Plugins: Um ecossistema gigante, incluindo pytest-cov para medir a cobertura de testes.

PYTHON

# Em tests/test_logic.py
import pytest
from myapp.logic import calculate_mean

# Parametriza o teste para rodar com múltiplos inputs
@pytest.mark.parametrize(
  "numbers, expected",
  [
      ([1.0, 2.0, 3.0], 2.0), # Happy path
      ([], 0.0),             # Edge case: lista vazia
      ([-1.0, 1.0], 0.0),      # Edge case: números negativos
  ],
)
def test_calculate_mean(numbers, expected):
  """Verifica se a média é calculada corretamente."""
  assert calculate_mean(numbers) == expected

Cobertura com pytest-cov

Para usar, primeiro adicione o plugin ao seu ambiente:

Bash

# Adiciona o pytest-cov às dependências de desenvolvimento
uv add --dev pytest-cov

Agora, execute os testes com a flag --cov para gerar um relatório no terminal. Para uma visualização detalhada, gere um relatório em HTML:

Bash

# Roda os testes e mostra o relatório de cobertura no terminal
uv run pytest --cov=myapp

# Gera um relatório HTML interativo na pasta htmlcov/
uv run pytest --cov=myapp --cov-report=html

O relatório HTML mostra exatamente quais linhas do seu código foram ou não executadas pelos testes, ajudando a identificar pontos que precisam de mais atenção.

• Escreva testes que cubram não apenas o "caminho feliz", mas também os casos de borda e falhas esperadas.
• Mensure a cobertura em seu ambiente de CI e configure-o para falhar se a cobertura cair abaixo de um certo limiar.
• Use o relatório de cobertura para guiar a escrita de novos testes de forma inteligente.

Erros Comuns e Como Evitá-los

Imports, Paths e Ambientes Virtuais

Erros de importação e de ambiente são os mais comuns para quem está começando. A causa é quase sempre a mesma: executar o código ou instalar pacotes fora do ambiente virtual (venv) correto.

• Ambientes Misturados: Instalar pacotes no Python global do sistema em vez do venv do projeto causa ImportError e conflitos de versão.
• PYTHONPATH: Evite alterar a variável de ambiente PYTHONPATH manualmente. Ferramentas como uv e Poetry gerenciam os paths de forma correta e automática.
• Ativação é Chave: Sempre ative o ambiente virtual com source .venv/bin/activate (ou o script equivalente no Windows) antes de rodar qualquer comando.

Checklist Rápido para Diagnóstico:

Se algo não funcionar, verifique dentro do terminal:

1. which python e which pip (ou where python no Windows): Devem apontar para a pasta .venv/bin/ do seu projeto.
2. uv pip list: Mostra os pacotes instalados dentro do ambiente ativo. Verifique se o que você precisa está lá.
3. Execute ferramentas sempre com um runner: uv run pytest ou poetry run ruff. Isso garante o uso das versões corretas instaladas no projeto.

Python para Automação e IA com Agentes

Automação Rápida e Robusta

Python brilha em tarefas de automação, como criar CLIs, processos de ETL/ELT, integrar APIs e fazer web scraping. As ferramentas certas tornam isso ainda mais produtivo: requests para chamadas HTTP, Typer para criar CLIs, Pydantic para validação de dados e Rich para interfaces de terminal elegantes.

• Escale aos Poucos: Scripts que começam pequenos podem evoluir para serviços robustos.
• Agende Execuções: Use o agendador do seu CI (como GitHub Actions) ou orquestradores como Airflow para rodar suas automações.
• Monitore Tudo: Use logging para registrar o que sua automação faz. Se algo falhar, você saberá o porquê.

Construindo Agentes com CrewAI e Agno

Frameworks de agentes permitem criar sistemas complexos que usam LLMs para raciocinar e executar tarefas.

• CrewAI: Excelente para orquestrar múltiplos agentes que colaboram em tarefas. Você define papéis (ex: "Pesquisador", "Escritor"), suas ferramentas e o processo geral.
• Agno: Um runtime focado em composição e execução de agentes. Facilita a integração de diferentes LLMs, ferramentas e sistemas de memória.

Dicas para Começar:

1. Inicie com os exemplos e guias de "quickstart" dos frameworks.
2. Pense nas "ferramentas" (tools) como a ponte entre o agente e o seu domínio de negócio. Uma ferramenta pode ser uma função que consulta seu banco de dados ou chama uma API interna.
3. Logue os prompts, as respostas dos modelos e as métricas de execução para entender e depurar o comportamento dos agentes.

CI com GitHub Actions

A Integração Contínua (CI) automatiza a verificação de qualidade a cada alteração no código. O GitHub Actions é uma forma gratuita e poderosa de fazer isso.

Workflow com uv (mais rápido):

YAML

name: CI

on: [push, pull_request]

jobs:
test-and-lint:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Set up uv
      uses: astral-sh/setup-uv@v1
      with:
        python-version: "3.12"
    
    - name: Install dependencies
      run: uv sync --all-extras

    - name: Lint with ruff
      run: uv run ruff check .

    - name: Test with pytest
      run: uv run pytest

• Fail Fast: Rode os linters e testes mais rápidos primeiro.
• Cache: Use o cache de dependências para acelerar a execução dos workflows.
• Automatize Tudo: CI é o local para rodar linters, formatadores, testes e verificações de cobertura.

Comunidade e Aprendizado Contínuo

A melhor forma de evoluir é aprender com quem está construindo e ensinando ativamente na comunidade.

• Aprenda com Especialistas: Acompanhe criadores de conteúdo como Eduardo Mendes (Live de Python), que oferece material prático e atualizado, incluindo cursos aprofundados como o de FastAPI do Zero.
• Adote Tecnologias Modernas: FastAPI é o framework web ideal para quem valoriza performance, tipagem estática e uma documentação gerada automaticamente.
• Seja Proativo: Siga desenvolvedores consistentes, tente replicar projetos que você admira e, quando se sentir confortável, contribua para projetos open-source, mesmo que seja apenas melhorando a documentação.