Implementation:Openai Openai python Multipart File Handling
| Knowledge Sources | |
|---|---|
| Domains | SDK_Infrastructure |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Concrete tool for file upload preparation provided by the openai-python SDK.
Description
The _files module handles the conversion of user-supplied file inputs into the format expected by the httpx HTTP library. It provides both synchronous (to_httpx_files()) and asynchronous (async_to_httpx_files()) converters that accept mappings or sequences of FileTypes and produce HttpxRequestFiles. The module includes is_file_content() for type-guarding whether an object qualifies as uploadable content (bytes, IO, PathLike, or tuple), is_base64_file_input() for detecting IO/PathLike inputs, and assert_is_file_content() for raising descriptive errors. Internal helpers _transform_file() and _async_transform_file() resolve PathLike objects by reading them into bytes (using pathlib.Path synchronously or anyio.Path asynchronously).
Usage
Use this module when preparing file data for multipart upload API calls such as audio transcription, image editing, or file creation endpoints.
Code Reference
Source Location
- Repository: openai-python
- File: src/openai/_files.py
- Lines: 1-123
Signature
def is_base64_file_input(obj: object) -> TypeGuard[Base64FileInput]: ...
def is_file_content(obj: object) -> TypeGuard[FileContent]: ...
def assert_is_file_content(obj: object, *, key: str | None = None) -> None: ...
def to_httpx_files(files: RequestFiles | None) -> HttpxRequestFiles | None: ...
async def async_to_httpx_files(files: RequestFiles | None) -> HttpxRequestFiles | None: ...
def read_file_content(file: FileContent) -> HttpxFileContent: ...
async def async_read_file_content(file: FileContent) -> HttpxFileContent: ...
Import
from openai._files import to_httpx_files, async_to_httpx_files, is_file_content
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| files | RequestFiles or None | Yes | Mapping or sequence of (key, FileTypes) pairs; can be None |
| obj | object | Yes | Object to check via is_file_content or assert_is_file_content |
| key | str or None | No | Optional key name for error messages in assert_is_file_content |
Outputs
| Name | Type | Description |
|---|---|---|
| to_httpx_files result | HttpxRequestFiles or None | Files dict/list formatted for httpx multipart uploads |
| is_file_content result | bool (TypeGuard) | True if the object is bytes, IO, PathLike, or tuple |
| read_file_content result | HttpxFileContent | IO[bytes] or bytes after resolving PathLike |
Usage Examples
Basic Usage
from pathlib import Path
from openai._files import to_httpx_files
# Convert a mapping of files for httpx
files = to_httpx_files({"file": Path("audio.mp3")})
# Result: {"file": ("audio.mp3", b"<file bytes>")}
# Convert a sequence of file tuples
files = to_httpx_files([("file", ("report.pdf", open("report.pdf", "rb"), "application/pdf"))])