Skip to content

Commit b590b5e

Browse files
authored
docs: add typed models concept guide (#777)
## Summary Adds a concepts page documenting the v3 typed-model surface: how response Pydantic models are accessed, how to provide structured input as plain dicts (with matching TypedDicts for shape), forward compatibility under `extra='allow'`, and where to browse all generated models in the API reference. The README's `Fully typed responses` feature bullet referenced typed models without a dedicated concept page — this fills that gap.
1 parent c441fc1 commit b590b5e

5 files changed

Lines changed: 143 additions & 0 deletions

File tree

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
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).
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
from apify_client import ApifyClientAsync
2+
3+
TOKEN = 'MY-APIFY-TOKEN'
4+
5+
6+
async def main() -> None:
7+
apify_client = ApifyClientAsync(TOKEN)
8+
9+
# `get` returns an `Actor` Pydantic model — fields are typed and IDE-completable.
10+
actor = await apify_client.actor('apify/hello-world').get()
11+
if actor is None:
12+
return
13+
14+
print(actor.id) # str
15+
print(actor.username) # str
16+
print(actor.is_public) # bool
17+
print(actor.created_at) # datetime.datetime (timezone-aware)
18+
print(actor.stats.total_runs) # int — nested model, attribute access all the way down
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
from apify_client import ApifyClient
2+
3+
TOKEN = 'MY-APIFY-TOKEN'
4+
5+
6+
def main() -> None:
7+
apify_client = ApifyClient(TOKEN)
8+
9+
# `get` returns an `Actor` Pydantic model — fields are typed and IDE-completable.
10+
actor = apify_client.actor('apify/hello-world').get()
11+
if actor is None:
12+
return
13+
14+
print(actor.id) # str
15+
print(actor.username) # str
16+
print(actor.is_public) # bool
17+
print(actor.created_at) # datetime.datetime (timezone-aware)
18+
print(actor.stats.total_runs) # int — nested model, attribute access all the way down
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
from apify_client import ApifyClientAsync
2+
3+
TOKEN = 'MY-APIFY-TOKEN'
4+
5+
6+
async def main() -> None:
7+
apify_client = ApifyClientAsync(TOKEN)
8+
rq_client = apify_client.request_queue('REQUEST-QUEUE-ID')
9+
10+
# Plain dict — keys may be snake_case or camelCase.
11+
await rq_client.add_request(
12+
{
13+
'url': 'https://example.com',
14+
'unique_key': 'https://example.com',
15+
'method': 'GET',
16+
}
17+
)
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
from apify_client import ApifyClient
2+
3+
TOKEN = 'MY-APIFY-TOKEN'
4+
5+
6+
def main() -> None:
7+
apify_client = ApifyClient(TOKEN)
8+
rq_client = apify_client.request_queue('REQUEST-QUEUE-ID')
9+
10+
# Plain dict — keys may be snake_case or camelCase.
11+
rq_client.add_request(
12+
{
13+
'url': 'https://example.com',
14+
'unique_key': 'https://example.com',
15+
'method': 'GET',
16+
}
17+
)

0 commit comments

Comments
 (0)