Overview
Concrete tool for request parameter transformation provided by the openai-python SDK.
Description
The Transform Utils module handles the conversion of Python-native data structures into API-compatible request payloads. It provides the PropertyInfo metadata class used with Annotated types to define field aliases and format specifications (e.g., ISO 8601 dates, base64-encoded files). The core transform() and async_transform() functions recursively walk typed dictionaries and apply renaming and formatting rules driven by type annotations. The module also exposes maybe_transform() and async_maybe_transform() convenience wrappers that accept None values without raising errors. Internally the module uses _transform_recursive() and _async_transform_recursive() to handle nested structures including lists, iterables, sequences, union types, and pydantic models.
Usage
Use the Transform Utils when you need to convert Python-style snake_case parameter dictionaries into the camelCase or otherwise aliased format expected by the OpenAI API. This is called automatically by every resource method before sending request bodies. It is also useful when building custom request pipelines that must conform to the SDK's transformation conventions.
Code Reference
Source Location
Signature
PropertyInfo
class PropertyInfo:
alias: str | None
format: PropertyFormat | None
format_template: str | None
discriminator: str | None
def __init__(
self,
*,
alias: str | None = None,
format: PropertyFormat | None = None,
format_template: str | None = None,
discriminator: str | None = None,
) -> None: ...
transform()
def transform(
data: _T,
expected_type: object,
) -> _T: ...
async_transform()
async def async_transform(
data: _T,
expected_type: object,
) -> _T: ...
maybe_transform()
def maybe_transform(
data: object,
expected_type: object,
) -> Any | None: ...
async_maybe_transform()
async def async_maybe_transform(
data: object,
expected_type: object,
) -> Any | None: ...
Import
from openai._utils._transform import PropertyInfo, transform, async_transform, maybe_transform, async_maybe_transform
I/O Contract
Inputs (transform / async_transform)
| Name |
Type |
Required |
Description
|
| data |
_T |
Yes |
The data dictionary or value to transform according to the expected type annotations.
|
| expected_type |
object |
Yes |
A TypedDict or other annotated type that provides field alias and format metadata via PropertyInfo.
|
Inputs (PropertyInfo)
| Name |
Type |
Required |
Description
|
| alias |
str or None |
No |
The API field name to map the Python field name to (e.g., "accountHolderName" for "account_holder_name").
|
| format |
PropertyFormat or None |
No |
The format to apply to the value. One of "iso8601", "base64", or "custom".
|
| format_template |
str or None |
No |
A strftime-compatible template string used when format is "custom".
|
| discriminator |
str or None |
No |
A discriminator key used for union type resolution.
|
Outputs
| Name |
Type |
Description
|
| return (transform) |
_T |
The transformed data with aliases applied and values formatted per annotations.
|
| return (maybe_transform) |
Any or None |
Same as transform, but returns None if the input data is None.
|
Usage Examples
Basic Usage: Field Aliasing
from typing import Required
from typing_extensions import Annotated, TypedDict
from openai._utils._transform import PropertyInfo, transform
class MyParams(TypedDict, total=False):
card_id: Required[Annotated[str, PropertyInfo(alias="cardID")]]
result = transform({"card_id": "<my card ID>"}, MyParams)
# result: {'cardID': '<my card ID>'}
Date Formatting
from datetime import datetime
from typing_extensions import Annotated, TypedDict
from openai._utils._transform import PropertyInfo, transform
class DateParams(TypedDict, total=False):
created_at: Annotated[datetime, PropertyInfo(format="iso8601")]
result = transform({"created_at": datetime(2024, 1, 15, 12, 0, 0)}, DateParams)
# result: {'created_at': '2024-01-15T12:00:00'}
Async Usage
from openai._utils._transform import async_maybe_transform
# Used internally by async resource methods
body = await async_maybe_transform(
{"card_id": "abc123"},
MyParams,
)
Related Pages
