Implementation:Openai Openai python Pydantic Compat
| Knowledge Sources | |
|---|---|
| Domains | SDK_Infrastructure |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Concrete tool for Pydantic v1/v2 compatibility provided by the openai-python SDK.
Description
The _compat module provides a compatibility layer that allows the openai-python SDK to work seamlessly with both Pydantic v1 and Pydantic v2 (and v3). It detects the installed Pydantic version at runtime via the PYDANTIC_V1 flag and dispatches calls to the appropriate API surface. Key adapter functions include model_dump() (wrapping .dict() vs .model_dump()), model_parse() (wrapping .parse_obj() vs .model_validate()), model_json(), model_copy(), parse_obj(), and model_json_schema(). It also provides a unified GenericModel base class, ConfigDict re-export, field inspection helpers (field_is_required, field_get_default, field_outer_type, get_model_fields), and a typed_cached_property descriptor that is settable at runtime.
Usage
Use this module whenever you need to serialize, deserialize, inspect, or copy Pydantic models inside the SDK without hard-coding a specific Pydantic version. All internal SDK models route through these helpers.
Code Reference
Source Location
- Repository: openai-python
- File: src/openai/_compat.py
- Lines: 1-231
Signature
PYDANTIC_V1: bool # True if pydantic.VERSION starts with "1."
def parse_obj(model: type[_ModelT], value: object) -> _ModelT: ...
def field_is_required(field: FieldInfo) -> bool: ...
def field_get_default(field: FieldInfo) -> Any: ...
def field_outer_type(field: FieldInfo) -> Any: ...
def get_model_config(model: type[pydantic.BaseModel]) -> Any: ...
def get_model_fields(model: type[pydantic.BaseModel]) -> dict[str, FieldInfo]: ...
def model_copy(model: _ModelT, *, deep: bool = False) -> _ModelT: ...
def model_json(model: pydantic.BaseModel, *, indent: int | None = None) -> str: ...
def model_dump(
model: pydantic.BaseModel,
*,
exclude: IncEx | None = None,
exclude_unset: bool = False,
exclude_defaults: bool = False,
warnings: bool = True,
mode: Literal["json", "python"] = "python",
by_alias: bool | None = None,
) -> dict[str, Any]: ...
def model_parse(model: type[_ModelT], data: Any) -> _ModelT: ...
def model_parse_json(model: type[_ModelT], data: str | bytes) -> _ModelT: ...
def model_json_schema(model: type[_ModelT]) -> dict[str, Any]: ...
class GenericModel(pydantic.BaseModel): ...
class typed_cached_property(Generic[_T]): ...
Import
from openai._compat import (
PYDANTIC_V1,
model_dump,
model_parse,
model_json,
model_copy,
parse_obj,
GenericModel,
ConfigDict,
get_model_fields,
typed_cached_property,
cached_property,
)
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| model | type[_ModelT] / pydantic.BaseModel | Yes | The Pydantic model class or instance to operate on |
| value / data | object / Any / str / bytes | Yes | The data to parse or the model instance to serialize |
| exclude | IncEx or None | No | Fields to exclude when dumping |
| exclude_unset | bool | No | Whether to exclude fields that were not explicitly set |
| mode | Literal["json", "python"] | No | Output mode for model_dump (default "python") |
| deep | bool | No | Whether to perform a deep copy in model_copy |
Outputs
| Name | Type | Description |
|---|---|---|
| model_dump result | dict[str, Any] | Dictionary representation of the model |
| model_parse result | _ModelT | Validated and parsed model instance |
| model_json result | str | JSON string representation of the model |
| model_copy result | _ModelT | Copy of the model instance |
| model_json_schema result | dict[str, Any] | JSON Schema dict for the model |
Usage Examples
Basic Usage
from openai._compat import model_dump, model_parse, PYDANTIC_V1
from openai._models import BaseModel
class MyModel(BaseModel):
name: str
value: int
# Parse raw data into a model regardless of Pydantic version
instance = model_parse(MyModel, {"name": "test", "value": 42})
# Dump model to dict
data = model_dump(instance, exclude_unset=True)
# {'name': 'test', 'value': 42}