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. 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())

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

8. precisarTipos de exemplosDados do Pydantic

Tipos Básicos

São baseados nos tipos nativos do Python, mas incluem validação extra.

TipoDescrição
intNúmeros inteiros
floatNúmeros de ponto flutuante
strCadeias de caracteres
boolValores booleanos (True, False)
bytesDados binários
listListas genéricas
tupleTuplas genéricas
setConjuntos
dictDicionários

Tipos Numéricos com Validação

TipoDescrição
PositiveIntNúmeros inteiros positivos (> 0)
NegativeIntNúmeros inteiros negativos (< 0)
NonNegativeIntNúmeros inteiros não-negativos (>= 0)
NonPositiveIntNúmeros inteiros não-positivos (<= 0)
PositiveFloatNúmeros de ponto flutuante positivos (> 0.0)
NegativeFloatNúmeros de ponto flutuante negativos (< 0.0)
NonNegativeFloatNúmeros de ponto flutuante não-negativos (>= 0.0)
NonPositiveFloatNúmeros de ponto flutuante não-positivos (<= 0.0)
conintInteiros com restrições (ge, le, multiple_of)
confloatFloats com restrições (ge, le, multiple_of)

Tipos de String com Validação

TipoDescrição
EmailStrString validada como e-mail
UrlStrString validada como URL completa
AnyUrlQualquer URL válida
HttpUrlURLs HTTP(S) válidas com validações extras (ex.: comprimento mínimo)
FilePathCaminho válido para um arquivo
DirectoryPathCaminho válido para um diretório
constrString com restrições (min_length, max_length, regex)
SecretStrString tratada como secreta, com suporte para .get_secret_value()

Tipos de Data e Hora

TipoDescrição
datetimeData e hora completas
dateApenas data
timeApenas hora
timedeltaDiferença entre duas datas/horas
PastDateValida que a data seja no passado
FutureDateValida que a data seja no futuro

Tipos Booleanos

TipoDescrição
StrictBoolAceita apenas True ou False explicitamente (sem conversão implícita)

Tipos de Lista, Conjunto e Tupla com Validação

TipoDescrição
conlistLista com restrições (min_items, max_items)
consetConjunto com restrições (min_items, max_items)
contupleTupla com restrições (min_length, max_length)

Tipos de Redes e Endereços

TipoDescrição
IPvAnyAddressAceita endereços IPv4 ou IPv6
IPv4AddressApenas endereços IPv4
IPv6AddressApenas endereços IPv6
IPvAnyInterfaceInterface de rede IPv4 ou IPv6
IPv4InterfaceApenas interfaces IPv4
IPv6InterfaceApenas interfaces IPv6
IPvAnyNetworkRede IPv4 ou IPv6
IPv4NetworkApenas redes IPv4
IPv6NetworkApenas redes IPv6
MacAddressEndereço MAC

Tipos Especiais

TipoDescrição
SecretBytesDados binários tratados como secretos
JsonString JSON válida
PaymentCardNumberNúmero de cartão de crédito válido
DecimalValores decimais com precisão arbitrária
ColorValida e representa cores (hexadecimal, nome, etc.)

Customização com Tipos Restritivos

Pydantic permite criar tipos customizados como conint ou constr para validar valores de acordo com restrições específicas.

Exemplo: Tipo de String Restritiva

python
from pydantic import BaseModel, constr class MyModel(BaseModel): name: constr(min_length=3, max_length=50, regex=r'^[A-Za-z]+$') MyModel(name="Lucas") # Válido MyModel(name="Lu") # Inválido (min_length) MyModel(name="123") # Inválido (regex)

Exemplo: Inteiros com Restrições

python
from pydantic import BaseModel, conint class MyModel(BaseModel): age: conint(ge=18, le=100) # Inteiro entre 18 e 100 MyModel(age=25) # Válido MyModel(age=17) # Inválido

Resumo

CategoriaExemplos Principais
Básicosint, float, str, bool, list, dict
NuméricosPositiveInt, NonNegativeFloat, conint, confloat
StringsEmailStr, UrlStr, SecretStr, constr
Datas e Horasdatetime, date, timedelta, FutureDate
RedesIPv4Address, IPvAnyNetwork, MacAddress
EspeciaisJson, PaymentCardNumber, Color, Decimal

Essa lista cobre os tipos mais específicosusados ouno recursos avançados do Pydantic, me avise!Pydantic!

Back to top