0
# Pydantic
1

2
A comprehensive Python data validation library that leverages Python type hints to provide fast and extensible data validation. Pydantic enables developers to define data schemas using pure, canonical Python syntax and validates data against these schemas with high performance through its Rust-based pydantic-core backend.
3

4
## Package Information
5

6
- **Package Name**: pydantic
7
- **Language**: Python
8
- **Installation**: `pip install pydantic`
9
- **Documentation**: https://docs.pydantic.dev/
10

11
## Core Imports
12

13
```python
14
import pydantic
15
```
16

17
Common for working with models:
18

19
```python
20
from pydantic import BaseModel, Field, ConfigDict
21
```
22

23
Specific imports for advanced features:
24

25
```python
26
from pydantic import (
27
    ValidationError, TypeAdapter, field_validator, model_validator,
28
    computed_field, create_model, validate_call, WithJsonSchema
29
)
30
```
31

32
JSON schema and plugin imports:
33

34
```python
35
from pydantic.json_schema import GenerateJsonSchema, model_json_schema
36
from pydantic.plugin import PydanticPluginProtocol
37
from pydantic.alias_generators import to_camel, to_pascal, to_snake
38
```
39

40
## Basic Usage
41

42
```python
43
from pydantic import BaseModel, Field
44
from typing import Optional
45
from datetime import datetime
46

47
class User(BaseModel):
48
    id: int
49
    name: str = Field(..., min_length=1, max_length=100)
50
    email: str = Field(..., pattern=r'^[\w\.-]+@[\w\.-]+\.\w+$')
51
    age: Optional[int] = Field(None, ge=0, le=150)
52
    created_at: datetime = Field(default_factory=datetime.now)
53

54
# Validation from dictionary
55
user_data = {
56
    'id': 123,
57
    'name': 'John Doe',
58
    'email': 'john@example.com',
59
    'age': 30
60
}
61

62
user = User(**user_data)
63
print(user.model_dump())  # Convert to dict
64
print(user.model_dump_json())  # Convert to JSON string
65

66
# Validation from JSON
67
json_str = '{"id": 456, "name": "Jane Smith", "email": "jane@example.com"}'
68
user2 = User.model_validate_json(json_str)
69

70
# Handle validation errors
71
try:
72
    invalid_user = User(id="not-an-int", name="", email="invalid-email")
73
except ValidationError as e:
74
    print(e.errors())
75
```
76

77
## Architecture
78

79
Pydantic v2 is built on a robust architecture that separates concerns:
80

81
- **BaseModel**: Core model class providing validation, serialization, and schema generation
82
- **Field System**: Flexible field definitions with validation constraints and metadata
83
- **Type System**: Rich type support including custom types, constraints, and generic types
84
- **Validation Engine**: High-performance Rust-based validation via pydantic-core
85
- **Serialization System**: Configurable serialization with custom serializers
86
- **Configuration System**: Model-level and field-level configuration options
87

88
This design enables pydantic to serve as the foundation for API frameworks (FastAPI), configuration management (pydantic-settings), and data processing pipelines across the Python ecosystem.
89

90
## Capabilities
91

92
### Core Models and Validation
93

94
Base model classes, field definitions, and core validation functionality that forms the foundation of pydantic's data validation capabilities.
95

96
```python { .api }
97
class BaseModel:
98
    def __init__(self, **data): ...
99
    @classmethod
100
    def model_validate(cls, obj): ...
101
    @classmethod 
102
    def model_validate_json(cls, json_str): ...
103
    def model_dump(self, **kwargs): ...
104
    def model_dump_json(self, **kwargs): ...
105

106
def Field(default=..., **kwargs): ...
107
def create_model(model_name: str, **field_definitions): ...
108
```
109

110
[Core Models](./core-models.md)
111

112
### Validation System
113

114
Decorators and functions for custom validation logic, including field validators, model validators, and functional validation utilities.
115

116
```python { .api }
117
def field_validator(*fields, **kwargs): ...
118
def model_validator(*, mode: str): ...
119
def validate_call(func): ...
120
```
121

122
[Validation System](./validation-system.md)
123

124
### Type System and Constraints
125

126
Specialized types for common data patterns including network addresses, file paths, dates, colors, and constrained types with built-in validation.
127

128
```python { .api }
129
class EmailStr(str): ...
130
class HttpUrl(str): ...
131
class UUID4(UUID): ...
132
class PositiveInt(int): ...
133
class constr(str): ...
134
class conint(int): ...
135
```
136

137
[Type System](./type-system.md)
138

139
### Serialization and Configuration
140

141
Computed fields, serialization customization, and model configuration options for controlling validation and serialization behavior.
142

143
```python { .api }
144
def computed_field(**kwargs): ...
145
class ConfigDict(TypedDict): ...
146
def field_serializer(*fields, **kwargs): ...
147
def model_serializer(**kwargs): ...
148
```
149

150
[Serialization and Configuration](./serialization-config.md)
151

152
### Dataclasses and Type Adapters
153

154
Integration with Python dataclasses and standalone type validation without model inheritance.
155

156
```python { .api }
157
def dataclass(**kwargs): ...
158
class TypeAdapter:
159
    def __init__(self, type_): ...
160
    def validate_python(self, obj): ...
161
    def validate_json(self, json_str): ...
162
```
163

164
[Dataclasses and Type Adapters](./dataclasses-adapters.md)
165

166
### JSON Schema Generation
167

168
JSON schema generation capabilities for creating OpenAPI-compatible schemas from pydantic models and types.
169

170
```python { .api }
171
def model_json_schema(cls, by_alias=True, ref_template='#/$defs/{model}'): ...
172
class GenerateJsonSchema: ...
173
class WithJsonSchema: ...
174
```
175

176
[JSON Schema](./json-schema.md)
177

178
### Plugin System
179

180
Advanced plugin system for extending pydantic's validation and schema generation capabilities.
181

182
```python { .api }
183
class PydanticPluginProtocol: ...
184
class BaseValidateHandlerProtocol: ...
185
def register_plugin(plugin): ...
186
```
187

188
[Plugins](./plugins.md)
189

190
### Error Handling and Utilities
191

192
Exception classes, warning system, and utility functions for advanced pydantic usage patterns.
193

194
```python { .api }
195
class ValidationError(ValueError): ...
196
class PydanticUserError(TypeError): ...
197
def parse_obj_as(type_, obj): ...
198
def schema_of(type_): ...
199
```
200

201
[Error Handling](./error-handling.md)