uv - O Gerenciador de Pacotes Python que Você Precisava

# macOS e Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Via pip (se preferir)
pip install uv

# Via Homebrew (macOS)
brew install uv

source ~/.bashrc   # ou ~/.zshrc

uv --version
# uv 0.5.x (...)

[project]
name = "meu-projeto"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi[standard]>=0.115.0",
]

[dependency-groups]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.9.0",
]

# Opção 1: cria a pasta e inicializa
uv init meu-projeto
cd meu-projeto

# Opção 2: inicializa na pasta atual
mkdir meu-projeto && cd meu-projeto
uv init

# Listar versões disponíveis
uv python list

# Instalar uma versão
uv python install 3.13

# Fixar a versão no projeto (cria/atualiza .python-version)
uv python pin 3.13

# Dependência principal
uv add fastapi

# Com extras (equivale a pip install fastapi[standard])
uv add "fastapi[standard]"

# Dependência de desenvolvimento
uv add --dev pytest ruff

# Versão específica
uv add "sqlalchemy>=2.0,<3.0"

# Sincroniza o ambiente com o pyproject.toml / uv.lock
uv sync

# Sem dependências de dev (útil em produção)
uv sync --no-dev

uv remove fastapi

# Rodar a aplicação
uv run fastapi dev meu_projeto/app.py

# Rodar testes
uv run pytest

# Rodar um script
uv run python script.py

# Abrir o interpretador interativo
uv run python

source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows

# 1. Criar o projeto
uv init fast-zero
cd fast-zero

# 2. Criar o pacote Python
mkdir fast_zero
touch fast_zero/__init__.py

# 3. Instalar dependências
uv add "fastapi[standard]"
uv add --dev pytest pytest-cov ruff taskipy

# 4. Rodar
uv run fastapi dev fast_zero/app.py

from fastapi import FastAPI

app = FastAPI()


@app.get('/')
def read_root():
    return {'message': 'Olá Mundo!'}

# ─────────────────────────────────────────────
# [project] — metadados e dependências principais
# Informações essenciais do projeto e pacotes
# necessários para rodar em produção.
# ─────────────────────────────────────────────
[project]
name = "fast-zero"          # nome do projeto (kebab-case por convenção)
version = "0.1.0"           # versão atual do projeto
requires-python = ">=3.12"  # versão mínima do Python aceita
dependencies = [
    # fastapi com o grupo [standard], que inclui uvicorn, httpx e outros
    # extras úteis para desenvolvimento e produção
    "fastapi[standard]>=0.115.0",
]

# ─────────────────────────────────────────────
# [dependency-groups] — dependências de desenvolvimento
# Pacotes usados apenas durante o desenvolvimento
# (testes, linting, formatação). Não vão para produção.
# ─────────────────────────────────────────────
[dependency-groups]
dev = [
    "pytest>=8.0.0",      # framework de testes
    "pytest-cov>=6.0.0",  # plugin para medir cobertura de testes
    "ruff>=0.9.0",        # linter e formatador de código
    "taskipy>=1.14.0",    # task runner — atalhos para comandos do projeto
]

# ─────────────────────────────────────────────
# [tool.ruff] — configuração global do Ruff
# Define comportamentos que se aplicam tanto
# ao linter quanto ao formatador.
# ─────────────────────────────────────────────
[tool.ruff]
line-length = 79             # limite de caracteres por linha (padrão PEP 8)
extend-exclude = ['migrations']  # ignora a pasta de migrações (código gerado
                                 # automaticamente — não queremos que o ruff altere)

# ─────────────────────────────────────────────
# [tool.ruff.lint] — configuração do linter
# Define quais regras de boas práticas o ruff
# vai checar no código.
# ─────────────────────────────────────────────
[tool.ruff.lint]
preview = true  # habilita regras ainda em fase experimental
select = [
    'I',   # isort — verifica ordenação alfabética dos imports
    'F',   # pyflakes — detecta erros comuns (variáveis não usadas, imports desnecessários)
    'E',   # pycodestyle errors — erros de estilo de código
    'W',   # pycodestyle warnings — avisos de estilo de código
    'PL',  # pylint — boas práticas gerais de Python
    'PT',  # flake8-pytest — boas práticas específicas para testes com pytest
]

# ─────────────────────────────────────────────
# [tool.ruff.format] — configuração do formatador
# Define o estilo de formatação automática do código.
# ─────────────────────────────────────────────
[tool.ruff.format]
preview = true          # habilita comportamentos de formatação experimentais
quote-style = 'single'  # usa aspas simples em vez de duplas (escolha pessoal/de equipe)

# ─────────────────────────────────────────────
# [tool.pytest.ini_options] — configuração do pytest
# Define como o pytest se comporta ao rodar os testes.
# ─────────────────────────────────────────────
[tool.pytest.ini_options]
pythonpath = "."           # adiciona a raiz do projeto ao PYTHONPATH, permitindo
                           # imports como "from fast_zero.app import app"
addopts = '-p no:warnings' # suprime warnings de bibliotecas externas para
                           # manter a saída dos testes mais limpa

# ─────────────────────────────────────────────
# [tool.taskipy.tasks] — atalhos de comandos
# Define tarefas executáveis com "uv run task <nome>".
# Evita ter que lembrar flags e caminhos longos.
# ─────────────────────────────────────────────
[tool.taskipy.tasks]
lint   = 'ruff check'                        # verifica boas práticas no código
format = 'ruff format'                       # formata o código automaticamente
run    = 'fastapi dev fast_zero/app.py'      # inicia o servidor de desenvolvimento
test   = 'pytest -s -x --cov=fast_zero -vv' # roda os testes com:
                                             #   -s: exibe prints durante os testes
                                             #   -x: para na primeira falha
                                             #   --cov=fast_zero: mede cobertura do pacote
                                             #   -vv: saída detalhada

uv run task test
uv run task lint
uv run task run

# Instalar uma ferramenta globalmente
uv tool install ruff
uv tool install httpie
uv tool install black

# Usar sem instalar (ambiente temporário, equivale a pipx run)
uvx ruff check .
uvx black --check .

# Listar ferramentas instaladas
uv tool list

# Atualizar
uv tool upgrade ruff

# Remover
uv tool uninstall black

# script.py
# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "httpx",
#   "rich",
# ]
# ///

import httpx
from rich import print

response = httpx.get("https://api.github.com/repos/astral-sh/uv")
print(response.json()["stargazers_count"])

uv run script.py
# Instala as deps automaticamente em um ambiente isolado e executa

# 1. Instale o uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. No diretório do projeto, sincronize
# O uv lê o pyproject.toml do Poetry normalmente
uv sync

# 3. Troque os comandos no dia a dia
# poetry run pytest   →   uv run pytest
# poetry add X        →   uv add X
# poetry shell        →   source .venv/bin/activate  (ou só use uv run)

# 4. (Opcional) Gere o uv.lock e delete o poetry.lock
uv lock
git rm poetry.lock
git add uv.lock

DATABASE_URL=postgresql://localhost/dev uv run python manage.py migrate

# uv não lê .env automaticamente, use python-dotenv ou direnv
uv add --dev python-dotenv

uv pip list
uv pip show fastapi

uv lock --upgrade
uv sync

uv pip compile pyproject.toml -o requirements.txt
# ou, para incluir só produção:
uv export --no-dev -o requirements.txt

uv run --with fastapi --with uvicorn python -c "
import uvicorn
from fastapi import FastAPI
app = FastAPI()

@app.get('/')
def root(): return {'ok': True}

uvicorn.run(app)
"

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4
        with:
          version: "latest"

      - name: Install dependencies
        run: uv sync --frozen

      - name: Run tests
        run: uv run pytest

FROM python:3.13-slim

# Instalar uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app

# Copiar lockfile e instalar dependências (camada cacheável)
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

# Copiar código
COPY . .

CMD ["uv", "run", "fastapi", "run", "fast_zero/app.py", "--port", "8000"]