Python Pydantic - Alexander Lee

Pydantic is a Python data validation and settings management library.（Pydantic 是一个用于 Python 数据校验和配置管理的库）

1) `BaseModel` (Define models)#

It defines a typed data structure (schema). Pydantic will create an object and validate the input based on the type hints.

1
from pydantic import BaseModel
2

3
class User(BaseModel):
4
    id: int
5
    name: str
6

7
u = User(id=1, name="Tom")
8
print(u)

2) Validation + Type Coercion#

It validates input types and will automatically convert compatible values (e.g. "123" → 123). If it can’t validate/convert, it raises an error.

1
from pydantic import BaseModel
2

3
class User(BaseModel):
4
    id: int
5

6
u = User(id="123")  # "123" -> 123
7
print(u.id, type(u.id))

3) `Field` (Constraints / Metadata)#

Field() lets you add constraints (like min/max) and extra metadata (like description). Pydantic will enforce the constraints during validation.

1
from pydantic import BaseModel, Field
2

3
class User(BaseModel):
4
    age: int = Field(ge=0, le=150, description="Age must be between 0 and 150")
5

6
u = User(age=18)
7
print(u)

4) Nested Models#

A model can contain another model as a field. Pydantic will validate nested dictionaries and convert them into nested model objects automatically.

1
from pydantic import BaseModel
2

3
class Address(BaseModel):
4
    city: str
5

6
class User(BaseModel):
7
    name: str
8
    address: Address
9

10
u = User(name="Tom", address={"city": "Shanghai"})
11
print(u.address.city)

5) Optional Fields + Defaults#

Optional fields (T | None) can be missing or set to None. Default values make the field optional during initialization.

1
from pydantic import BaseModel
2

3
class User(BaseModel):
4
    name: str
5
    email: str | None = None
6

7
u1 = User(name="Tom")
8
u2 = User(name="Jerry", email="jerry@example.com")
9

10
print(u1)
11
print(u2)

6) `@field_validator` (Field-level validation)#

It lets you write custom validation logic for a specific field (e.g., trimming spaces, format checks, rejecting certain values).

1
from pydantic import BaseModel, field_validator
2

3
class User(BaseModel):
4
    name: str
5

6
    @field_validator("name")
7
    @classmethod
8
    def name_not_empty(cls, v: str):
9
        if not v.strip():
10
            raise ValueError("name must not be empty")
11
        return v.strip()
12

13
u = User(name="  Tom  ")
14
print(u)

7) `@model_validator` (Model-level validation)#

It validates the model as a whole, which is useful for rules involving multiple fields (cross-field validation).

1
from pydantic import BaseModel, model_validator
2

3
class Login(BaseModel):
4
    username: str
5
    password: str
6

7
    @model_validator(mode="after")
8
    def check_password(self):
9
        if len(self.password) < 6:
10
            raise ValueError("password too short (min 6)")
11
        return self
12

13
ok = Login(username="tom", password="123456")
14
print(ok)

8) `model_dump()` (Export to dict)#

It converts a validated model instance into a standard Python dictionary, often used for business logic or API responses.

1
from pydantic import BaseModel
2

3
class User(BaseModel):
4
    id: int
5
    name: str
6

7
u = User(id=1, name="Tom")
8
print(u.model_dump())
9
print(type(u.model_dump()))

9) `model_dump_json()` (Export to JSON)#

It converts the model into a JSON string, convenient for HTTP responses, logs, caches, or storing data.

1
from pydantic import BaseModel
2

3
class User(BaseModel):
4
    id: int
5
    name: str
6

7
u = User(id=1, name="Tom")
8
print(u.model_dump_json())
9
print(type(u.model_dump_json()))

10) `BaseSettings` (Settings management)#

It reads configuration from environment variables (and other sources) into a typed model, validating types just like BaseModel.

1
pip install pydantic-settings
2
from pydantic_settings import BaseSettings
3

4
class Settings(BaseSettings):
5
    app_name: str = "demo"
6
    debug: bool = False
7

8
s = Settings()
9
print(s.app_name, s.debug)

(Optional) run with environment variables:

1
export APP_NAME=myapp
2
export DEBUG=true
3
python your_file.py

1) BaseModel (Define models)#

2) Validation + Type Coercion#

3) Field (Constraints / Metadata)#

4) Nested Models#

5) Optional Fields + Defaults#

6) @field_validator (Field-level validation)#

7) @model_validator (Model-level validation)#

8) model_dump() (Export to dict)#

9) model_dump_json() (Export to JSON)#

10) BaseSettings (Settings management)#