Skip to main content

Documentação Completa de Uso do Pydantic

O Pydantic é uma biblioteca do Python para validação de dados e gerenciamento de tipos. Ele é amplamente usado para criar modelos de dados que garantem consistência e validade.

Estrutura Básica

Um modelo no Pydantic é uma classe que herda de BaseModel. Os campos são definidos com anotações de tipo (type hints) do Python.

python
from pydantic import BaseModel class User(BaseModel): id: int name: str is_active: bool = True # Campo opcional com valor padrão # Criando uma instância user = User(id=1, name="Alice") print(user.dict()) # {'id': 1, 'name': 'Alice', 'is_active': True}

Tipos Suportados

O Pydantic suporta todos os principais tipos do Python e suas variações.

1. Tipos Básicos

Tipo Descrição Exemplo
int Números inteiros id: int = 123
float Números de ponto flutuante price: float = 9.99
str Cadeia de caracteres name: str = "Alice"
bool Valores booleanos is_active: bool = True
bytes Dados binários content: bytes = b"binary data"

Exemplo:

python
class Product(BaseModel): id: int name: str price: float is_available: bool = True product = Product(id=1, name="Laptop", price=999.99) print(product.dict())

2. Coleções

Tipo Descrição Exemplo
List Lista de itens tags: List[str] = ["python", "pydantic"]
Tuple Tupla com tipos fixos coords: Tuple[float, float] = (10.0, 20.0)
Dict Dicionário com tipos de chave e valor metadata: Dict[str, str] = {"author": "A"}
Set Conjunto de valores únicos unique_ids: Set[int] = {1, 2, 3}

Exemplo:

python
from typing import List, Tuple, Dict, Set class Post(BaseModel): tags: List[str] coords: Tuple[float, float] metadata: Dict[str, str] unique_ids: Set[int] post = Post( tags=["python", "pydantic"], coords=(10.0, 20.0), metadata={"author": "John", "editor": "Jane"}, unique_ids={1, 2, 3} ) print(post.dict())

3. Tipos Especiais

Tipo Descrição Exemplo
Optional Campo opcional age: Optional[int] = None
Union Aceita múltiplos tipos value: Union[int, str] = "text"
Any Aceita qualquer tipo data: Any = 123
Literal Restringe a valores específicos status: Literal["draft", "published"]
Annotated Adiciona metadados para validação title: Annotated[str, Field(max_length=50)]

Exemplo:

python
from typing import Optional, Union, Literal, Any class User(BaseModel): age: Optional[int] = None # Pode ser `None` ou `int` value: Union[int, str] # Pode ser `int` ou `str` status: Literal["draft", "published"] # Valores fixos data: Any # Aceita qualquer coisa user = User(value="text", status="draft") print(user.dict())

4. Tipos de Data e Tempo

Tipo Descrição Exemplo
datetime Data e hora created_at: datetime = datetime.now()
date Apenas data dob: date = date(1990, 1, 1)
time Apenas hora event_time: time = time(14, 30)
timedelta Duração de tempo duration: timedelta = timedelta(hours=1)

Exemplo:

python
from datetime import datetime, date, time, timedelta class Event(BaseModel): name: str start_date: date start_time: time duration: timedelta event = Event( name="Meeting", start_date=date.today(), start_time=time(14, 30), duration=timedelta(hours=2) ) print(event.dict())

5. Validações Customizadas

Validações Com Decorador @validator

python
from pydantic import BaseModel, validator class User(BaseModel): name: str age: int @validator("age") def validate_age(cls, value): if value < 18: raise ValueError("Idade deve ser maior ou igual a 18.") return value

Validações no Campo com Field

python
from pydantic import BaseModel, Field class Product(BaseModel): name: str = Field(..., min_length=3, max_length=50) price: float = Field(..., ge=0.0) product = Product(name="Laptop", price=999.99) 

6. Serialização

Converter para Dicionário

python
model.dict()

Converter para JSON

python
model.json()

Campos Excluídos na Serialização

python
class User(BaseModel): id: int password: str class Config: fields = {"password": {"exclude": True}} user = User(id=1, password="1234") print(user.dict()) # {'id': 1}

7. Configuração Avançada

Modo Arbitrário (Config)

Permitir campos que não foram definidos.

python
class MyModel(BaseModel): class Config: arbitrary_types_allowed = True

Modificar Comportamento de Serialização

python
class MyModel(BaseModel): class Config: orm_mode = True # Permite integração com ORMs

8. Erro de Validação

Pydantic levanta uma exceção ValidationError para entradas inválidas.

python
from pydantic import ValidationError try: User(name="Lucas", age=17) # Inválido except ValidationError as e: print(e.json())

9.7. Aninhamento de Modelos

Você pode incluir um modelo dentro de outro.

python
class Address(BaseModel): city: str country: str class User(BaseModel): name: str address: Address user = User(name="Lucas", address={"city": "NY", "country": "USA"}) print(user.dict())

Se precisar de exemplos mais específicos ou recursos avançados do Pydantic, me avise!

Back to top