Skip to content

Commit 5659c0e

Browse files
committed
Merge remote-tracking branch 'origin/master' into iterable-list-methods-2
2 parents d8bc536 + f906ff3 commit 5659c0e

79 files changed

Lines changed: 5583 additions & 4615 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/manual_regenerate_models.yaml‎

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
# This workflow regenerates Pydantic models (src/apify_client/_models.py) from the OpenAPI spec.
1+
# This workflow regenerates Pydantic models and TypedDicts (src/apify_client/_{models,typeddicts}_generated.py) from the OpenAPI spec.
22
#
33
# It can be triggered in two ways:
4-
# 1. Automatically via workflow_dispatch from the apify-docs CI pipeline (with docs_pr_number and docs_workflow_run_id).
4+
# 1. Automatically via workflow_dispatch from the apify-docs CI pipeline.
55
# 2. Manually from the GitHub UI (without any inputs) to regenerate from the live published spec.
66

77
name: Regenerate models
@@ -63,8 +63,8 @@ jobs:
6363
with:
6464
token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
6565

66-
# If the branch already exists on the remote (e.g. from a previous run, possibly with
67-
# reviewer commits), check it out to build on top of it instead of starting fresh.
66+
# If the branch already exists on the remote (e.g. from a previous run, possibly with reviewer commits),
67+
# check it out to build on top of it instead of starting fresh.
6868
- name: Switch to existing branch or create a new one
6969
run: |
7070
if git ls-remote --exit-code --heads origin "$BRANCH" > /dev/null 2>&1; then
@@ -108,7 +108,7 @@ jobs:
108108
id: commit
109109
uses: EndBug/add-and-commit@v10
110110
with:
111-
add: src/apify_client/_models.py
111+
add: 'src/apify_client/_*_generated.py'
112112
author_name: apify-service-account
113113
author_email: apify-service-account@users.noreply.github.com
114114
message: ${{ env.TITLE }}
@@ -130,9 +130,9 @@ jobs:
130130
else
131131
if [[ -n "$DOCS_PR_NUMBER" ]]; then
132132
DOCS_PR_URL="https://github.com/apify/apify-docs/pull/${DOCS_PR_NUMBER}"
133-
BODY="This PR updates the auto-generated Pydantic models based on OpenAPI specification changes in [apify-docs PR #${DOCS_PR_NUMBER}](${DOCS_PR_URL})."
133+
BODY="This PR updates the auto-generated Pydantic models and TypedDicts based on OpenAPI specification changes in [apify-docs PR #${DOCS_PR_NUMBER}](${DOCS_PR_URL})."
134134
else
135-
BODY="This PR updates the auto-generated Pydantic models from the [published OpenAPI specification](https://docs.apify.com/api/openapi.json)."
135+
BODY="This PR updates the auto-generated Pydantic models and TypedDicts from the [published OpenAPI specification](https://docs.apify.com/api/openapi.json)."
136136
fi
137137
138138
PR_URL=$(gh pr create \
@@ -155,15 +155,30 @@ jobs:
155155
GH_TOKEN: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }}
156156
PR_CREATED: ${{ steps.pr.outputs.created }}
157157
PR_URL: ${{ steps.pr.outputs.pr_url }}
158+
DOCS_PR_AUTHOR: ${{ inputs.docs_pr_author }}
158159
run: |
159-
if [[ "$PR_CREATED" = "true" ]]; then
160-
COMMENT="A PR to update the Python client models has been created: ${PR_URL}
160+
MENTION=""
161+
if [[ -n "$DOCS_PR_AUTHOR" ]]; then
162+
MENTION="@${DOCS_PR_AUTHOR} "
163+
fi
161164
162-
This was automatically triggered by OpenAPI specification changes in this PR."
165+
if [[ "$PR_CREATED" = "true" ]]; then
166+
HEADLINE="A companion PR has been opened in \`apify-client-python\` with the regenerated models: ${PR_URL}"
163167
else
164-
COMMENT="The Python client model PR has been updated with the latest OpenAPI spec changes: ${PR_URL}"
168+
HEADLINE="The companion \`apify-client-python\` PR has been updated with the latest spec changes: ${PR_URL}"
165169
fi
166170
171+
COMMENT=$(printf '%s\n' \
172+
"> [!IMPORTANT]" \
173+
"> **Action required** — ${MENTION}please coordinate this docs PR with the Python API client PR linked below." \
174+
">" \
175+
"> Because this PR modifies the OpenAPI specification, the generated models in \`apify-client-python\` must be regenerated to stay in sync. This has already been done automatically:" \
176+
">" \
177+
"> ${HEADLINE}" \
178+
">" \
179+
"> - Please make sure to review and merge both PRs together to keep the OpenAPI spec and API clients in sync." \
180+
"> - You can ask for review and help from the Tooling team if needed.")
181+
167182
gh pr comment "$DOCS_PR_NUMBER" \
168183
--repo apify/apify-docs \
169184
--body "$COMMENT"

‎.rules.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ uv run poe type-check # Run ty type checker
1919
uv run poe unit-tests # Run unit tests
2020
uv run poe check-docstrings # Verify async docstrings match sync
2121
uv run poe fix-docstrings # Auto-fix async docstrings
22-
uv run poe generate-models # Regenerate _models.py from live OpenAPI spec
22+
uv run poe generate-models # Regenerate _models_generated.py and _typeddicts_generated.py from live OpenAPI spec
2323
uv run poe generate-models-from-file <path> # Regenerate from a local OpenAPI spec file
2424

2525
# Run a single test
@@ -73,7 +73,7 @@ Docstrings are written on sync clients and **automatically copied** to async cli
7373

7474
### Data Models
7575

76-
`src/apify_client/_models.py` is **auto-generated** — do not edit it manually.
76+
`src/apify_client/_models_generated.py` and `src/apify_client/_typeddicts_generated.py` are **auto-generated** — do not edit them manually. The hand-maintained `src/apify_client/_models.py` and `src/apify_client/_typeddicts.py` hold only shapes that are not exposed by the OpenAPI spec (or that need local logic); import generated types directly from the `_*_generated` modules.
7777

7878
- Generated by `datamodel-code-generator` from the OpenAPI spec at `https://docs.apify.com/api/openapi.json` (config in `pyproject.toml` under `[tool.datamodel-codegen]`, aliases in `datamodel_codegen_aliases.json`)
7979
- After generation, `scripts/postprocess_generated_models.py` is run to apply additional fixes

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,17 @@ All notable changes to this project will be documented in this file.
1212
- Accept Pydantic models as alternatives to dicts in resource client methods ([#663](https://github.com/apify/apify-client-python/pull/663)) ([b778c20](https://github.com/apify/apify-client-python/commit/b778c2040228ff9f5a97765de10535cec3f0353e)) by [@vdusek](https://github.com/vdusek), closes [#421](https://github.com/apify/apify-client-python/issues/421)
1313
- Add ownership parameter to storage collection listing methods ([#696](https://github.com/apify/apify-client-python/pull/696)) ([51a92a3](https://github.com/apify/apify-client-python/commit/51a92a31dac5dd433acfaea76155011d0892d8c8)) by [@nmanerikar](https://github.com/nmanerikar)
1414
- Add filter and cursor parameters to list_requests method ([#743](https://github.com/apify/apify-client-python/pull/743)) ([3445ff7](https://github.com/apify/apify-client-python/commit/3445ff74e61d5f1f9a964f2ee3c14d198298f709)) by [@mvolfik](https://github.com/mvolfik)
15+
- Add ApifyApiError subclasses grouped by HTTP status ([#737](https://github.com/apify/apify-client-python/pull/737)) ([a6daff7](https://github.com/apify/apify-client-python/commit/a6daff754e5e1af8a6230f4c504db24a246c734f)) by [@vdusek](https://github.com/vdusek)
16+
- Generate TypedDict types for input-side models ([#738](https://github.com/apify/apify-client-python/pull/738)) ([2fd66d0](https://github.com/apify/apify-client-python/commit/2fd66d0adf253dff470f40d0bfdbc620da0ed608)) by [@vdusek](https://github.com/vdusek), closes [#666](https://github.com/apify/apify-client-python/issues/666)
1517

1618
### 🐛 Bug Fixes
1719

1820
- Guard integration test resource names against 63-char API limit ([#729](https://github.com/apify/apify-client-python/pull/729)) ([47a7a69](https://github.com/apify/apify-client-python/commit/47a7a6967e28c7042fa8e75cd4c138356495fa2c)) by [@vdusek](https://github.com/vdusek)
1921
- Prevent `_prepare_request_call` from mutating caller&#x27;s headers dict ([#746](https://github.com/apify/apify-client-python/pull/746)) ([d553162](https://github.com/apify/apify-client-python/commit/d5531621535f5a491be5b5791ea4b80e46de1405)) by [@vdusek](https://github.com/vdusek)
22+
- Don&#x27;t block StatusMessageWatcher exit with 6s sleep on exception ([#753](https://github.com/apify/apify-client-python/pull/753)) ([48f5037](https://github.com/apify/apify-client-python/commit/48f50378e92e2058ff8e5aaba45ef9e3a6e5f081)) by [@vdusek](https://github.com/vdusek)
23+
- Treat naive datetime query params as UTC ([#752](https://github.com/apify/apify-client-python/pull/752)) ([9ab096a](https://github.com/apify/apify-client-python/commit/9ab096a7453080a3079c7459079f99a30bd6a7cb)) by [@vdusek](https://github.com/vdusek)
24+
- Raise NotFoundError on ambiguous 404 responses ([#755](https://github.com/apify/apify-client-python/pull/755)) ([701185e](https://github.com/apify/apify-client-python/commit/701185e6e8a98f0b14d83cab10139f1e19be3f47)) by [@vdusek](https://github.com/vdusek)
25+
- Correct deadline logic in _wait_for_finish ([#749](https://github.com/apify/apify-client-python/pull/749)) ([fd0663e](https://github.com/apify/apify-client-python/commit/fd0663e22b31ddd289325146c9750ff07c068d6b)) by [@vdusek](https://github.com/vdusek)
2026

2127
### 🚜 Refactor
2228

‎docs/02_concepts/code/03_nested_async.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
from apify_client import ApifyClientAsync
2-
from apify_client._models import ActorJobStatus
2+
from apify_client._models_generated import ActorJobStatus
33

44
TOKEN = 'MY-APIFY-TOKEN'
55

‎docs/02_concepts/code/03_nested_sync.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
from apify_client import ApifyClient
2-
from apify_client._models import ActorJobStatus
2+
from apify_client._models_generated import ActorJobStatus
33

44
TOKEN = 'MY-APIFY-TOKEN'
55

‎docs/04_upgrading/upgrading_to_v3.mdx‎

Lines changed: 65 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ run.status
5555
Models also use `populate_by_name=True`, which means you can use either the Python field name or the camelCase alias when **constructing** a model:
5656

5757
```python
58-
from apify_client._models import Run
58+
from apify_client._models_generated import Run
5959

6060
# Both work when constructing models
6161
Run(default_dataset_id='abc') # Python field name
@@ -86,7 +86,7 @@ rq_client.add_request({
8686
After (v3) — both forms are accepted:
8787

8888
```python
89-
from apify_client._types import RequestInput
89+
from apify_client._models import RequestInput
9090

9191
# Option 1: dict (still works)
9292
rq_client.add_request({
@@ -186,6 +186,69 @@ The default timeout tier assigned to each method on non-storage resource clients
186186

187187
If your code relied on the previous global timeout behavior, review the timeout tier on the methods you use and adjust via the `timeout` parameter or by overriding tier defaults on the <ApiLink to="class/ApifyClient">`ApifyClient`</ApiLink> constructor (see [Tiered timeout system](#tiered-timeout-system) above).
188188

189+
## Exception subclasses for API errors
190+
191+
<ApiLink to="class/ApifyApiError">`ApifyApiError`</ApiLink> now dispatches to a dedicated subclass based on the HTTP status code of the failed response. Instantiating `ApifyApiError` directly still works — it returns the most specific subclass for the status — so existing `except ApifyApiError` handlers are unaffected.
192+
193+
The following subclasses are available:
194+
195+
| Status | Subclass |
196+
|---|---|
197+
| 400 | <ApiLink to="class/InvalidRequestError">`InvalidRequestError`</ApiLink> |
198+
| 401 | <ApiLink to="class/UnauthorizedError">`UnauthorizedError`</ApiLink> |
199+
| 403 | <ApiLink to="class/ForbiddenError">`ForbiddenError`</ApiLink> |
200+
| 404 | <ApiLink to="class/NotFoundError">`NotFoundError`</ApiLink> |
201+
| 409 | <ApiLink to="class/ConflictError">`ConflictError`</ApiLink> |
202+
| 429 | <ApiLink to="class/RateLimitError">`RateLimitError`</ApiLink> |
203+
| 5xx | <ApiLink to="class/ServerError">`ServerError`</ApiLink> |
204+
205+
You can now branch on error kind without inspecting `status_code` or `type`:
206+
207+
```python
208+
from apify_client import ApifyClient
209+
from apify_client.errors import NotFoundError, RateLimitError
210+
211+
client = ApifyClient(token='MY-APIFY-TOKEN')
212+
213+
try:
214+
run = client.run('some-run-id').get()
215+
except NotFoundError:
216+
run = None
217+
except RateLimitError:
218+
...
219+
```
220+
221+
### Behavior change: 404 on ambiguous endpoints now raises `NotFoundError`
222+
223+
Direct, ID-identified fetches like `client.dataset(id).get()` or `client.run(id).get()` continue to swallow 404 into `None` — a 404 there unambiguously means the named resource does not exist. Similarly, `.delete()` on an ID-identified client keeps its idempotent behavior (404 is silently swallowed).
224+
225+
For calls where a 404 is *ambiguous*, the client now propagates <ApiLink to="class/NotFoundError">`NotFoundError`</ApiLink> instead of returning `None` / silently succeeding. Three categories of endpoints are affected:
226+
227+
1. **Chained calls that target a default sub-resource without an ID** — `run.dataset()`, `run.key_value_store()`, `run.request_queue()`, `run.log()`. A 404 here could mean the parent run is missing OR the default sub-resource is missing, and the API body does not disambiguate. Applies to both `.get()` and `.delete()`.
228+
2. **`.get()` / `.get_as_bytes()` / `.stream()` on a chained `LogClient`** — e.g. `run.log().get()`. Direct `client.log(build_or_run_id).get()` still returns `None` on 404.
229+
3. **Singleton sub-resource endpoints fetched via a fixed path** — <ApiLink to="class/ScheduleClient#get_log">`ScheduleClient.get_log()`</ApiLink>, <ApiLink to="class/TaskClient#get_input">`TaskClient.get_input()`</ApiLink>, <ApiLink to="class/DatasetClient#get_statistics">`DatasetClient.get_statistics()`</ApiLink>, <ApiLink to="class/UserClient#monthly_usage">`UserClient.monthly_usage()`</ApiLink>, <ApiLink to="class/UserClient#limits">`UserClient.limits()`</ApiLink>, <ApiLink to="class/WebhookClient#test">`WebhookClient.test()`</ApiLink>. These hit paths like `/schedules/{id}/log` or `/actor-tasks/{id}/input`, so a 404 effectively means the parent is missing. Return types moved from `T | None` to `T`.
230+
231+
```python
232+
from apify_client import ApifyClient
233+
from apify_client.errors import NotFoundError
234+
235+
client = ApifyClient(token='MY-APIFY-TOKEN')
236+
237+
try:
238+
dataset = client.run('some-run-id').dataset().get()
239+
except NotFoundError:
240+
# Previously this returned `None`; now you must handle it explicitly.
241+
dataset = None
242+
243+
try:
244+
schedule_log = client.schedule('some-schedule-id').get_log()
245+
except NotFoundError:
246+
# `get_log()` previously returned `None` when the schedule was missing; now it raises.
247+
schedule_log = None
248+
```
249+
250+
Direct `.get()` also now swallows every 404 regardless of the `error.type` string in the response body (previously only `record-not-found` and `record-or-token-not-found` types were swallowed). If your code needs to distinguish between "resource missing" and "404 with an unexpected type", inspect `.type` on a caught <ApiLink to="class/NotFoundError">`NotFoundError`</ApiLink> from a non-`.get()` call path.
251+
189252
## Snake_case `sort_by` values on `actors().list()`
190253

191254
The `sort_by` parameter of <ApiLink to="class/ActorCollectionClient#list">`ActorCollectionClient.list()`</ApiLink> and <ApiLink to="class/ActorCollectionClientAsync#list">`ActorCollectionClientAsync.list()`</ApiLink> now accepts pythonic snake_case values instead of the raw camelCase values used by the API.

‎pyproject.toml‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ indent-style = "space"
152152
"**/docs/03_guides/code/05_custom_http_client_{async,sync}.py" = [
153153
"ARG002", # Unused method argument
154154
]
155-
"src/apify_client/_models.py" = [
155+
"src/apify_client/_*_generated.py" = [
156156
"D", # Everything from the pydocstyle
157157
"E501", # Line too long
158158
"ERA001", # Commented-out code
@@ -210,7 +210,7 @@ context = 7
210210
# https://koxudaxi.github.io/datamodel-code-generator/
211211
[tool.datamodel-codegen]
212212
input_file_type = "openapi"
213-
output = "src/apify_client/_models.py"
213+
output = "src/apify_client/_models_generated.py"
214214
target_python_version = "3.11"
215215
output_model_type = "pydantic_v2.BaseModel"
216216
use_schema_description = true
@@ -272,8 +272,22 @@ shell = "./build_api_reference.sh && corepack enable && yarn && uv run yarn star
272272
cwd = "website"
273273

274274
[tool.poe.tasks.generate-models]
275-
shell = "uv run datamodel-codegen --url https://docs.apify.com/api/openapi.json && python scripts/postprocess_generated_models.py"
275+
shell = """
276+
uv run datamodel-codegen --url https://docs.apify.com/api/openapi.json \
277+
&& uv run datamodel-codegen --url https://docs.apify.com/api/openapi.json \
278+
--output src/apify_client/_typeddicts_generated.py \
279+
--output-model-type typing.TypedDict \
280+
--no-use-closed-typed-dict \
281+
&& python scripts/postprocess_generated_models.py
282+
"""
276283

277284
[tool.poe.tasks.generate-models-from-file]
278-
shell = "uv run datamodel-codegen --input $input_file && python scripts/postprocess_generated_models.py"
285+
shell = """
286+
uv run datamodel-codegen --input $input_file \
287+
&& uv run datamodel-codegen --input $input_file \
288+
--output src/apify_client/_typeddicts_generated.py \
289+
--output-model-type typing.TypedDict \
290+
--no-use-closed-typed-dict \
291+
&& python scripts/postprocess_generated_models.py
292+
"""
279293
args = [{ name = "input-file", positional = true, required = true }]

0 commit comments

Comments
 (0)