|
| 1 | +--- |
| 2 | +id: typed-models |
| 3 | +title: Typed models |
| 4 | +description: Resource client methods return Pydantic models generated from the Apify OpenAPI spec, with IDE autocomplete, runtime validation, and forward-compatible field access. |
| 5 | +--- |
| 6 | + |
| 7 | +import Tabs from '@theme/Tabs'; |
| 8 | +import TabItem from '@theme/TabItem'; |
| 9 | +import CodeBlock from '@theme/CodeBlock'; |
| 10 | +import ApiLink from '@site/src/components/ApiLink'; |
| 11 | + |
| 12 | +import AccessAsyncExample from '!!raw-loader!./code/12_typed_models_access_async.py'; |
| 13 | +import AccessSyncExample from '!!raw-loader!./code/12_typed_models_access_sync.py'; |
| 14 | + |
| 15 | +import InputAsyncExample from '!!raw-loader!./code/12_typed_models_input_async.py'; |
| 16 | +import InputSyncExample from '!!raw-loader!./code/12_typed_models_input_sync.py'; |
| 17 | + |
| 18 | +Resource client methods return [Pydantic](https://docs.pydantic.dev/) models generated directly from the [Apify OpenAPI specification](https://docs.apify.com/api/openapi.json). You get IDE autocompletion, runtime validation of API responses, and a Python-idiomatic snake_case interface on top of the underlying camelCase API. |
| 19 | + |
| 20 | +## Accessing response fields |
| 21 | + |
| 22 | +Every method that returns a structured payload returns a Pydantic model. Fields are accessed using their Python snake_case names regardless of the camelCase used by the API, and the static type of each field comes through to your editor. |
| 23 | + |
| 24 | +<Tabs> |
| 25 | + <TabItem value="AsyncExample" label="Async client" default> |
| 26 | + <CodeBlock className="language-python"> |
| 27 | + {AccessAsyncExample} |
| 28 | + </CodeBlock> |
| 29 | + </TabItem> |
| 30 | + <TabItem value="SyncExample" label="Sync client"> |
| 31 | + <CodeBlock className="language-python"> |
| 32 | + {AccessSyncExample} |
| 33 | + </CodeBlock> |
| 34 | + </TabItem> |
| 35 | +</Tabs> |
| 36 | + |
| 37 | +Date strings are automatically parsed into timezone-aware `datetime.datetime` objects, enums into `Literal` aliases, and nested objects into their own typed models, so you can compose attribute access without manual conversion. |
| 38 | + |
| 39 | +## Providing structured input |
| 40 | + |
| 41 | +A Pydantic model returned from one client call can be passed directly into any other method that accepts the same shape — useful for round-trip flows where you read a resource, tweak it, and write it back. |
| 42 | + |
| 43 | +For input you construct yourself, plain dictionaries work on every input method. Each input shape has a matching [`TypedDict`](https://docs.python.org/3/library/typing.html#typing.TypedDict) that documents the expected keys. |
| 44 | + |
| 45 | +<Tabs> |
| 46 | + <TabItem value="AsyncExample" label="Async client" default> |
| 47 | + <CodeBlock className="language-python"> |
| 48 | + {InputAsyncExample} |
| 49 | + </CodeBlock> |
| 50 | + </TabItem> |
| 51 | + <TabItem value="SyncExample" label="Sync client"> |
| 52 | + <CodeBlock className="language-python"> |
| 53 | + {InputSyncExample} |
| 54 | + </CodeBlock> |
| 55 | + </TabItem> |
| 56 | +</Tabs> |
| 57 | + |
| 58 | +## Forward compatibility |
| 59 | + |
| 60 | +Generated models are configured with `extra='allow'`. Any new fields the API starts returning in the future are preserved on the model instance — they simply do not yet have a typed attribute. Upgrading the client to pick up a newer OpenAPI spec is a non-breaking change for code that reads existing fields. |
| 61 | + |
| 62 | +## Browsing all models |
| 63 | + |
| 64 | +The full list of generated models and TypedDicts is available in the [API reference](/api/client/python/reference) under the **Models** and **Typed dicts** groups. |
| 65 | + |
| 66 | +## Methods that return plain types |
| 67 | + |
| 68 | +A few endpoints intentionally return plain Python types instead of Pydantic models because their payloads are user-defined or inherently unstructured: |
| 69 | + |
| 70 | +- <ApiLink to="class/DatasetClient#list_items">`DatasetClient.list_items()`</ApiLink> returns a <ApiLink to="class/DatasetItemsPage">`DatasetItemsPage`</ApiLink> whose `items` field is `list[dict[str, Any]]`. Dataset items follow the [Actor output schema](https://docs.apify.com/platform/actors/development/actor-definition/output-schema), which the client cannot know in advance. |
| 71 | +- <ApiLink to="class/KeyValueStoreClient#get_record">`KeyValueStoreClient.get_record()`</ApiLink> returns a `dict` with `key`, `value`, and `content_type` keys. The shape of `value` is determined by the record's content type. |
| 72 | + |
| 73 | +For background on the migration from plain dicts to typed models, see [Upgrading to v3](../04_upgrading/upgrading_to_v3.mdx). |
0 commit comments