Instalação e Configuração de Ambiente — Gerenciador de Pacotes Rápido UV

Um bom ambiente de desenvolvimento é como uma cozinha totalmente equipada—os ingredientes (dependências) ficam disponíveis em questão de segundos, o fogão (servidor) acende com um clique, e a receita (estrutura do projeto) está bem organizada.

1. O Que Você Vai Aprender

• Instalação do UV e Comandos Centrais: Fluxo de trabalho para uv init, uv add e uv run
• Criando o Esqueleto do Projeto PriceTracker: Estrutura de Diretórios e Convenções de Nomenclatura
• Configurações do servidor de desenvolvimento Uvicorn: --reload, --host, --port, --workers
• Gerenciamento de Variáveis de Ambiente .env e Integração com python-dotenv
• Use uv run uvicorn para iniciar o serviço de desenvolvimento com um clique

2. A História Real da Alice

(1) Problema: pip é lento como uma lesma ao instalar dependências

Alice usou pip para instalar dependências do seu projeto FastAPI, e levou três minutos para terminar. Para piorar, Bob na equipe estava usando Python 3.11, enquanto Alice usava 3.12—a incompatibilidade de versões causava conflitos frequentes em seus ambientes virtuais. Toda vez que pip install -r requirements.txt roda, é como jogar na loteria—você nunca sabe se vai falhar devido a um conflito de versão com algum lock file.

(2) Solução com o UV

UV é um gerenciador de pacotes Python escrito em Rust pela equipe Astral. Ele instala dependências 10 a 100 vezes mais rápido que o pip, possui gerenciamento integrado de ambiente virtual e troca de versão do Python, e permite inicializar um projeto com um único comando.

# Inicializar projeto e adicionar FastAPI de uma vez
uv init pricetracker
cd pricetracker
uv add fastapi uvicorn
uv run uvicorn app.main:app --reload

(3) Resultado

O tempo de instalação de dependências da Alice caiu de 3 minutos para 3 segundos; Bob e Alice têm ambientes idênticos (versão travada no uv.lock), e os tempos de build CI/CD foram reduzidos em 80%.

3. Noções Básicas do Gerenciador de Pacotes UV

(1) Referência Rápida dos Comandos Centrais do UV

(1) ▶ Exemplo: Inicializando um Projeto UV

# Criar diretório do projeto
uv init pricetracker
cd pricetracker

# Isso cria:
# pricetracker/
#   pyproject.toml
#   .python-version
#   hello.py
#   .venv/  (ambiente virtual criado automaticamente)

Saída:

Initialized project pricetracker

(2) ▶ Exemplo: Adicionando uma dependência FastAPI

# Adicionar FastAPI e Uvicorn
uv add fastapi uvicorn[standard]

# Verificar pyproject.toml
cat pyproject.toml

Saída (trecho do pyproject.toml):

[project]
name = "pricetracker"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.115.0",
    "uvicorn[standard]>=0.30.0",
]

(2) Comparação entre UV, pip e Poetry

4. Esqueleto do Projeto PriceTracker

(1) Design da Estrutura de Diretórios

graph TD
    Root[pricetracker/] --> App[app/]
    App --> Main[__init__.py]
    App --> MainPy[main.py]
    App --> Api[api/]
    Api --> Routes[routes/]
    Routes --> Products[products.py]
    Routes --> Prices[prices.py]
    Routes --> Auth[auth.py]
    App --> Models[models/]
    App --> Schemas[schemas/]
    App --> Services[services/]
    App --> Core[core/]
    Core --> Config[config.py]
    Core --> Security[security.py]
    App --> Db[db.py]
    Root --> Tests[tests/]
    Root --> Alembic[alembic/]
    Root --> Docker[docker/]
    Root --> Env[.env]
    Root --> Pyproject[pyproject.toml]

graph TD
    Root[pricetracker/] --> App[app/]
    App --> Main[__init__.py]
    App --> MainPy[main.py]
    App --> Api[api/]
    Api --> Routes[routes/]
    Routes --> Products[products.py]
    Routes --> Prices[prices.py]
    Routes --> Auth[auth.py]
    App --> Models[models/]
    App --> Schemas[schemas/]
    App --> Services[services/]
    App --> Core[core/]
    Core --> Config[config.py]
    Core --> Security[security.py]
    App --> Db[db.py]
    Root --> Tests[tests/]
    Root --> Alembic[alembic/]
    Root --> Docker[docker/]
    Root --> Env[.env]
    Root --> Pyproject[pyproject.toml]

(1) ▶ Exemplo: Criando o Esqueleto do Projeto

# Criar todos os diretórios
mkdir -p app/api/routes app/models app/schemas app/services app/core
mkdir -p tests alembic docker

# Criar arquivos __init__.py
touch app/__init__.py app/api/__init__.py app/api/routes/__init__.py
touch app/models/__init__.py app/schemas/__init__.py
touch app/services/__init__.py app/core/__init__.py
touch tests/__init__.py

Saída:

CONTAINER ID   IMAGE     STATUS    
abc123         latest    Up 2 hours

(2) ▶ Exemplo: Aplicação FastAPI Mínima app/main.py

from fastapi import FastAPI

app = FastAPI(
    title="PriceTracker API",
    description="Serviço SaaS de rastreamento de preços para e-commerce",
    version="0.1.0",
)

@app.get("/health")
async def health_check():
    return {"status": "healthy", "service": "pricetracker"}

Saída:

# Função definida com sucesso

5. Servidor de Desenvolvimento Uvicorn

(1) Parâmetros Chave do Uvicorn

(1) ▶ Exemplo: Iniciando em Modo de Desenvolvimento

# Iniciar com hot reload - reinicialização automática ao alterar código
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Saída:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.

(2) ▶ Exemplo: Iniciando em Modo de Produção

# Produção: múltiplos workers, sem reload
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Saída:

# Comando executado com sucesso

(2) Comparação das Configurações do Uvicorn para Desenvolvimento vs. Produção

6. Gerenciamento de Variáveis de Ambiente

(1) O Arquivo .env e python-dotenv

Variáveis de ambiente são um princípio central do 12-Factor App; configurações sensíveis (como senhas de banco de dados e chaves JWT) nunca devem ser hard-coded.

(1) ▶ Exemplo: Criando um arquivo .env

# .env - NUNCA commite este arquivo no git!
APP_NAME=PriceTracker
DEBUG=true
DATABASE_URL=postgresql+asyncpg://pricetracker:secret@localhost:5432/pricetracker
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=your-super-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

Saída:

// Execução Bem-Sucedida

(2) ▶ Exemplo: Pydantic Settings Lendo Variáveis de Ambiente

# app/core/config.py
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "PriceTracker"
    debug: bool = False
    database_url: str = "postgresql+asyncpg://localhost/pricetracker"
    redis_url: str = "redis://localhost:6379/0"
    secret_key: str = "change-me-in-production"
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30

    model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}

settings = Settings()

Saída:

# Execução Bem-Sucedida

(3) ▶ Exemplo: Usando Configuração no FastAPI

# app/main.py
from fastapi import FastAPI
from app.core.config import settings

app = FastAPI(
    title=settings.app_name,
    debug=settings.debug,
)

@app.get("/info")
async def app_info():
    return {
        "app": settings.app_name,
        "debug": settings.debug,
        "database": settings.database_url.split("@")[-1],  # Ocultar credenciais
    }

Saída:

# Função definida com sucesso

(2) Itens Essenciais para .gitignore

# Adicionar ao .gitignore
.env
.env.local
.env.production
.venv/
__pycache__/
*.pyc

7. Exemplo Abrangente

Combinando gerenciamento de pacotes UV, configuração Pydantic Settings e inicialização Uvicorn, este guia demonstra o processo completo da inicialização do projeto ao deploy do serviço.

# dependências pyproject.toml: fastapi, uvicorn, pydantic-settings
from fastapi import FastAPI
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "PriceTracker"
    debug: bool = False
    database_url: str = "postgresql+asyncpg://user:pass@localhost/pricetracker"

    model_config = {"env_file": ".env"}

settings = Settings()
app = FastAPI(title=settings.app_name, debug=settings.debug)

@app.get("/health")
async def health():
    return {"status": "ok", "app": settings.app_name}

@app.get("/info")
async def info():
    return {"app": settings.app_name, "debug": settings.debug}
# Iniciar: uv run uvicorn app.main:app --reload

Saída:

GET /health → {"status":"ok","app":"PriceTracker"}
GET /info → {"app":"PriceTracker","debug":false}

❓ Perguntas Frequentes

📖 Resumo

• UV é escrito em Rust; instala dependências 10 a 100 vezes mais rápido que pip e inclui ambientes virtuais integrados e gerenciamento de versão do Python.
• O projeto PriceTracker usa uma arquitetura em camadas consistindo de cinco camadas: api/routes, models, schemas, services e core
• Uvicorn usa --reload para hot reloading em desenvolvimento e --workers para operação multi-processo em produção
• .env + Pydantic Settings: Gerencie variáveis de ambiente; nunca hard-code configurações sensíveis
• uv run uvicorn app.main:app --reload Inicie um ambiente de desenvolvimento completo com um único comando

📝 Exercícios

1. Exercício Básico (Dificuldade ⭐): Crie um projeto usando uv init, adicione as dependências FastAPI e Uvicorn, e execute seu primeiro endpoint "Hello World". Dica: uv add fastapi uvicorn
2. Exercício Avançado (Dificuldade: ⭐⭐): Crie a estrutura de diretórios do projeto PriceTracker, escreva o endpoint app/main.py que inclui o endpoint /health, e use uv run uvicorn para iniciar e verificar. Dica: Consulte o diagrama de estrutura de diretórios neste artigo.
3. Desafio (Dificuldade: ⭐⭐⭐): Use Pydantic Settings para criar uma classe de configuração que leia arquivos do arquivo .env, leia DATABASE_URL e SECRET_KEY, e retorne o nome da aplicação no endpoint /info (sem expor o segredo). Dica: pip install pydantic-settings, ou seja, uv add pydantic-settings

---|

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

Sobre Nós