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

8. Tipos de Dados do Pydantic

Tipos Básicos

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

Tipo Descrição
int Números inteiros
float Números de ponto flutuante
str Cadeias de caracteres
bool Valores booleanos (True, False)
bytes Dados binários
list Listas genéricas
tuple Tuplas genéricas
set Conjuntos
dict Dicionários

Tipos Numéricos com Validação

Tipo Descrição
PositiveInt Números inteiros positivos (> 0)
NegativeInt Números inteiros negativos (< 0)
NonNegativeInt Números inteiros não-negativos (>= 0)
NonPositiveInt Números inteiros não-positivos (<= 0)
PositiveFloat Números de ponto flutuante positivos (> 0.0)
NegativeFloat Números de ponto flutuante negativos (< 0.0)
NonNegativeFloat Números de ponto flutuante não-negativos (>= 0.0)
NonPositiveFloat Números de ponto flutuante não-positivos (<= 0.0)
conint Inteiros com restrições (ge, le, multiple_of)
confloat Floats com restrições (ge, le, multiple_of)

Tipos de String com Validação

Tipo Descrição
EmailStr String validada como e-mail
UrlStr String validada como URL completa
AnyUrl Qualquer URL válida
HttpUrl URLs HTTP(S) válidas com validações extras (ex.: comprimento mínimo)
FilePath Caminho válido para um arquivo
DirectoryPath Caminho válido para um diretório
constr String com restrições (min_length, max_length, regex)
SecretStr String tratada como secreta, com suporte para .get_secret_value()

Tipos de Data e Hora

Tipo Descrição
datetime Data e hora completas
date Apenas data
time Apenas hora
timedelta Diferença entre duas datas/horas
PastDate Valida que a data seja no passado
FutureDate Valida que a data seja no futuro

Tipos Booleanos

Tipo Descrição
StrictBool Aceita apenas True ou False explicitamente (sem conversão implícita)

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

Tipo Descrição
conlist Lista com restrições (min_items, max_items)
conset Conjunto com restrições (min_items, max_items)
contuple Tupla com restrições (min_length, max_length)

Tipos de Redes e Endereços

Tipo Descrição
IPvAnyAddress Aceita endereços IPv4 ou IPv6
IPv4Address Apenas endereços IPv4
IPv6Address Apenas endereços IPv6
IPvAnyInterface Interface de rede IPv4 ou IPv6
IPv4Interface Apenas interfaces IPv4
IPv6Interface Apenas interfaces IPv6
IPvAnyNetwork Rede IPv4 ou IPv6
IPv4Network Apenas redes IPv4
IPv6Network Apenas redes IPv6
MacAddress Endereço MAC

Tipos Especiais

Tipo Descrição
SecretBytes Dados binários tratados como secretos
Json String JSON válida
PaymentCardNumber Número de cartão de crédito válido
Decimal Valores decimais com precisão arbitrária
Color Valida 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

Categoria Exemplos Principais
Básicos int, float, str, bool, list, dict
Numéricos PositiveInt, NonNegativeFloat, conint, confloat
Strings EmailStr, UrlStr, SecretStr, constr
Datas e Horas datetime, date, timedelta, FutureDate
Redes IPv4Address, IPvAnyNetwork, MacAddress
Especiais Json, PaymentCardNumber, Color, Decimal

Essa lista cobre os tipos mais usados no Pydantic!

1 Comment
Alexsander
Alexsander  commented 11 months ago
#3

In reply to #2

essa eh a resposta da resposta do comentario

Back to top