Noções Básicas de Pydantic

9 exemplos para modelos Pydantic 2 - 6 básicos e 3 intermediários.

Pré-requisitos

uv pip install "pydantic>=2" pydantic-settings

• Pydantic 2 usa pydantic-core para validação rápida em Python 3.14.

Exemplos Básicos

1. Definir um Modelo

Contêiner de dados tipado com validação.

from pydantic import BaseModel
 
class User(BaseModel):
    id: int
    name: str

• Subclasses de BaseModel definem campos.
• A validação é executada na instanciação.
• Campos extras são proibidos por padrão nos modos estritos da v2.

Relacionado: Tipos e Restrições de Campo - Field()

2. Erros de Validação

Capturar entrada incorreta.

from pydantic import BaseModel, ValidationError
 
class Age(BaseModel):
    years: int
 
try:
    Age(years="x")
except ValidationError as e:
    print(e.error_count())

• ValidationError carrega as localizações.
• Use em respostas 422 de API.
• error_count resume as falhas.

3. Padrões e Opcional

Campos opcionais e fábricas.

from pydantic import BaseModel, Field
 
class Item(BaseModel):
    name: str
    tags: list[str] = Field(default_factory=list)

• Use default_factory para padrões mutáveis.
• Optional significa T | None.
• Não definido vs nulo explícito diferem em dumps.

4. model_dump

Serializar para dados compatíveis com dict/JSON.

user = User(id=1, name="Ada")
user.model_dump()
user.model_dump(mode="json")

• mode='json' converte datetimes.
• exclude_unset omite campos ausentes.
• Prefira model_dump em vez de dict().

Relacionado: Serialização - dumps avançados

5. Modelos Aninhados

Compor estruturas.

class Address(BaseModel):
    city: str
 
class Profile(BaseModel):
    address: Address

• Modelos aninhados validam recursivamente.
• Use list[Model] para coleções.
• Achate com model_dump aninhado.

Relacionado: Modelos Aninhados e Recursivos - árvores

6. ConfigDict

Comportamento em todo o modelo.

from pydantic import BaseModel, ConfigDict
 
class Strict(BaseModel):
    model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)

• extra='forbid' rejeita chaves desconhecidas.
• str_strip_whitespace limpa a entrada.
• from_attributes habilita o modo ORM.

Exemplos Intermediários

7. field_validator

Verificações personalizadas em nível de campo.

from pydantic import BaseModel, field_validator
 
class EmailUser(BaseModel):
    email: str
 
    @field_validator("email")
    @classmethod
    def must_have_at(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("invalid email")
        return v.lower()

• Validadores são executados após a coerção de tipo.
• classmethod é necessário na v2.
• Lance ValueError para falhas.

Relacionado: Validadores - validadores de modelo

8. model_validator

Regras entre campos.

from pydantic import BaseModel, model_validator
 
class Range(BaseModel):
    low: int
    high: int
 
    @model_validator(mode="after")
    def check_order(self):
        if self.high < self.low:
            raise ValueError("high < low")
        return self

• mode='after' vê o modelo analisado.
• Use para pares de confirmação de senha.
• Retorne self em validadores 'after'.

9. JSON Schema

Gerar esquema para documentação.

User.model_json_schema()

• Alimenta componentes OpenAPI.
• Mantenha os modelos como única fonte de verdade.
• Exportar para geração de código do cliente.

Relacionado: Serialização - exportação de esquema

Versões da Stack: Esta página foi escrita para Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.