Package pydantic_custom_types
Pydantic Custom Types
Use any type with pydantic, without any of the hassle
Installation
You can install this package with pip.
$ pip install pydantic-custom-types
Links
Usage
The pydantic-custom-types
package provides a simple way to integrate custom types with Pydantic models through the PydanticAdapter
class. This adapter handles serialization and deserialization of your custom types, making them fully compatible with Pydantic's validation system.
By using PydanticAdapter, you can seamlessly integrate any custom type with Pydantic's validation system, without having to modify the original type or create complex serialization logic.
Basic usage
To use a custom type with Pydantic:
- Import the necessary components:
from typing import Annotated
from pydantic import BaseModel
from pydantic_custom_types import PydanticAdapter
- Create an adapter for your custom type:
from my_module import MyCustomType
# Define how to parse from JSON and dump to JSON
MyCustomTypeAnnotation = Annotated[
MyCustomType,
PydanticAdapter(
type=MyCustomType,
parse=MyCustomType.from_string, # Convert string to MyCustomType
dump=str # Convert MyCustomType to string
)
]
- Use the custom type in your Pydantic model:
class MyModel(BaseModel):
custom_field: MyCustomTypeAnnotation
Complete example
Here's a complete example with a custom Email type:
from typing import Annotated
from pydantic import BaseModel
from pydantic_custom_types import PydanticAdapter
class Email:
def __init__(self, address: str):
if "@" not in address:
raise ValueError("Invalid email address")
self.address = address
def __str__(self) -> str:
return self.address
# Create the adapter
EmailType = Annotated[Email, PydanticAdapter(type=Email, parse=Email, dump=str)]
# Use in a model
class User(BaseModel):
name: str
email: EmailType
# Create a model instance
user = User(name="John Doe", email="john@example.com")
# or with an already constructed Email instance
user = User(name="Jane Doe", email=Email("jane@example.com"))
# Serialize to JSON
json_data = user.model_dump_json()
print(json_data) # {"name": "John Doe", "email": "john@example.com"}
# Deserialize from JSON
user_dict = {"name": "Alice", "email": "alice@example.com"}
user = User.model_validate(user_dict)
print(user.email.address) # alice@example.com
Working with complex types
The PydanticAdapter
also works with complex types that need custom serialization to JSON:
from datetime import datetime, timezone
from typing import Annotated, Any, Self
from pydantic import BaseModel
from pydantic_custom_types import PydanticAdapter
class Timestamp:
def __init__(self, dt: datetime):
self.datetime = dt
@classmethod
def parse(cls, data: dict[str, Any]) -> Self:
return cls(datetime.fromisoformat(data["iso"]))
def to_dict(self) -> dict[str, Any]:
return {
"iso": self.datetime.isoformat(),
"unix": int(self.datetime.timestamp())
}
# Create the adapter with dict serialization
TimestampType = Annotated[
Timestamp,
PydanticAdapter(
type=Timestamp,
parse=Timestamp.parse,
dump=lambda ts: ts.to_dict()
)
]
class Event(BaseModel):
name: str
timestamp: TimestampType
# Create and use the model
event = Event(
name="Server Started",
timestamp=Timestamp(datetime.now(timezone.utc))
)
# Serialize to JSON - timestamp will be a dictionary with iso and unix fields
json_data = event.model_dump_json()
print(json_data)
Multiple adapters for different contexts
You can create multiple annotations for the same type to handle different serialization formats:
from typing import Annotated, Self
from pydantic import BaseModel
from pydantic_custom_types import PydanticAdapter
class Point:
def __init__(self, x: float, y: float):
self.x = x
self.y = y
@classmethod
def from_string(cls, value: str) -> Self:
x, y = map(float, value.split(","))
return cls(x, y)
@classmethod
def from_dict(cls, data: dict) -> Self:
return cls(data["x"], data["y"])
def to_string(self) -> str:
return f"{self.x},{self.y}"
def to_dict(self) -> dict:
return {"x": self.x, "y": self.y}
# String representation adapter
PointString = Annotated[
Point,
PydanticAdapter(
type=Point,
parse=Point.from_string,
dump=lambda p: p.to_string()
)
]
# Dictionary representation adapter
PointDict = Annotated[
Point,
PydanticAdapter(
type=Point,
parse=Point.from_dict,
dump=lambda p: p.to_dict()
)
]
# Use different representations in different models
class LocationString(BaseModel):
position: PointString
class LocationDict(BaseModel):
position: PointDict
Classes
class PydanticAdapter (type: type[T], *, parse: Callable[[J], T], dump: Callable[[T], J])
-
A Pydantic adapter for a custom type.
This class allows you to use custom types with pydantic by providing functions to convert between your custom type and some JSON-compatible type, such as a string or a number.
It is useful when you want to use a custom type in a Pydantic model and need to define how to serialize and deserialize that type.
Example
from typing import Annotated from pydantic import BaseModel from some_module import CustomType from pydantic_custom_types import PydanticAdapter CustomTypeAnnotation = Annotated[CustomType, PydanticAdapter(CustomType, parse=CustomType.parse, dump=str)] class MyModel(BaseModel): custom_field: CustomTypeAnnotation
Args
type
- The type of the custom object.
parse
- A function that takes a JSON value and returns an instance of the custom type. The function should raise a ValueError if the value cannot be converted to the custom type, either because it is of the wrong type entirely or because it is not a valid value for the custom type.
dump
- A function that takes an instance of the custom type and returns a JSON value. The value returned should be a valid input for the
parse
function.
Ancestors
- typing.Generic