From ea60c971a424901b7b72f50dcc4c02bca9d7e0c3 Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Fri, 15 May 2026 13:36:34 +0200 Subject: [PATCH 1/4] refactor: shrink public API surface for v3 --- .../code/10_architecture_imports.py | 2 +- docs/02_concepts/code/10_plugging_in_async.py | 4 +++- docs/02_concepts/code/10_plugging_in_sync.py | 4 +++- .../code/05_custom_http_client_async.py | 8 +++++-- .../code/05_custom_http_client_sync.py | 8 +++++-- docs/04_upgrading/upgrading_to_v3.mdx | 5 +++- src/apify_client/__init__.py | 14 ----------- src/apify_client/_apify_client.py | 8 ++++--- .../_resource_clients/_resource_client.py | 12 ++++++---- src/apify_client/_resource_clients/actor.py | 2 +- .../_resource_clients/actor_collection.py | 2 +- .../_resource_clients/actor_env_var.py | 2 +- .../actor_env_var_collection.py | 2 +- .../_resource_clients/actor_version.py | 2 +- .../actor_version_collection.py | 2 +- src/apify_client/_resource_clients/build.py | 2 +- .../_resource_clients/build_collection.py | 2 +- src/apify_client/_resource_clients/dataset.py | 4 ++-- .../_resource_clients/dataset_collection.py | 2 +- .../_resource_clients/key_value_store.py | 4 ++-- .../key_value_store_collection.py | 2 +- src/apify_client/_resource_clients/log.py | 4 ++-- .../_resource_clients/request_queue.py | 2 +- .../request_queue_collection.py | 2 +- src/apify_client/_resource_clients/run.py | 2 +- .../_resource_clients/run_collection.py | 2 +- .../_resource_clients/schedule.py | 2 +- .../_resource_clients/schedule_collection.py | 2 +- .../_resource_clients/store_collection.py | 2 +- src/apify_client/_resource_clients/task.py | 2 +- .../_resource_clients/task_collection.py | 2 +- src/apify_client/_resource_clients/user.py | 2 +- src/apify_client/_resource_clients/webhook.py | 2 +- .../_resource_clients/webhook_collection.py | 2 +- .../_resource_clients/webhook_dispatch.py | 2 +- .../webhook_dispatch_collection.py | 2 +- src/apify_client/_utils.py | 4 ++-- src/apify_client/errors.py | 16 ++++++++++++- .../__init__.py | 0 .../{_http_clients => http_clients}/_base.py | 2 +- .../{_http_clients => http_clients}/_impit.py | 6 ++--- src/apify_client/{_types.py => types.py} | 10 +++++--- tests/unit/test_client_errors.py | 2 +- tests/unit/test_client_headers.py | 2 +- tests/unit/test_client_timeouts.py | 2 +- tests/unit/test_http_clients.py | 4 ++-- tests/unit/test_pluggable_http_client.py | 23 +++++++++---------- 47 files changed, 109 insertions(+), 87 deletions(-) rename src/apify_client/{_http_clients => http_clients}/__init__.py (100%) rename src/apify_client/{_http_clients => http_clients}/_base.py (99%) rename src/apify_client/{_http_clients => http_clients}/_impit.py (99%) rename src/apify_client/{_types.py => types.py} (89%) diff --git a/docs/02_concepts/code/10_architecture_imports.py b/docs/02_concepts/code/10_architecture_imports.py index c2eaf4ce1..c462b2f96 100644 --- a/docs/02_concepts/code/10_architecture_imports.py +++ b/docs/02_concepts/code/10_architecture_imports.py @@ -1,4 +1,4 @@ -from apify_client import ( +from apify_client.http_clients import ( HttpClient, HttpClientAsync, HttpResponse, diff --git a/docs/02_concepts/code/10_plugging_in_async.py b/docs/02_concepts/code/10_plugging_in_async.py index 0a9b6b2dd..331f0b622 100644 --- a/docs/02_concepts/code/10_plugging_in_async.py +++ b/docs/02_concepts/code/10_plugging_in_async.py @@ -1,6 +1,8 @@ from typing import Any -from apify_client import ApifyClientAsync, HttpClientAsync, HttpResponse, Timeout +from apify_client import ApifyClientAsync +from apify_client.http_clients import HttpClientAsync, HttpResponse +from apify_client.types import Timeout TOKEN = 'MY-APIFY-TOKEN' diff --git a/docs/02_concepts/code/10_plugging_in_sync.py b/docs/02_concepts/code/10_plugging_in_sync.py index 3c964d5e8..386281ae2 100644 --- a/docs/02_concepts/code/10_plugging_in_sync.py +++ b/docs/02_concepts/code/10_plugging_in_sync.py @@ -1,6 +1,8 @@ from typing import Any -from apify_client import ApifyClient, HttpClient, HttpResponse, Timeout +from apify_client import ApifyClient +from apify_client.http_clients import HttpClient, HttpResponse +from apify_client.types import Timeout TOKEN = 'MY-APIFY-TOKEN' diff --git a/docs/03_guides/code/05_custom_http_client_async.py b/docs/03_guides/code/05_custom_http_client_async.py index e6ebcdd1d..7a70d4440 100644 --- a/docs/03_guides/code/05_custom_http_client_async.py +++ b/docs/03_guides/code/05_custom_http_client_async.py @@ -1,11 +1,15 @@ from __future__ import annotations import asyncio -from typing import Any +from typing import TYPE_CHECKING, Any import httpx -from apify_client import ApifyClientAsync, HttpClientAsync, HttpResponse, Timeout +from apify_client import ApifyClientAsync +from apify_client.http_clients import HttpClientAsync, HttpResponse + +if TYPE_CHECKING: + from apify_client.types import Timeout TOKEN = 'MY-APIFY-TOKEN' diff --git a/docs/03_guides/code/05_custom_http_client_sync.py b/docs/03_guides/code/05_custom_http_client_sync.py index d196d6b67..ca499e50d 100644 --- a/docs/03_guides/code/05_custom_http_client_sync.py +++ b/docs/03_guides/code/05_custom_http_client_sync.py @@ -1,10 +1,14 @@ from __future__ import annotations -from typing import Any +from typing import TYPE_CHECKING, Any import httpx -from apify_client import ApifyClient, HttpClient, HttpResponse, Timeout +from apify_client import ApifyClient +from apify_client.http_clients import HttpClient, HttpResponse + +if TYPE_CHECKING: + from apify_client.types import Timeout TOKEN = 'MY-APIFY-TOKEN' diff --git a/docs/04_upgrading/upgrading_to_v3.mdx b/docs/04_upgrading/upgrading_to_v3.mdx index c5caeebbd..255718c5f 100644 --- a/docs/04_upgrading/upgrading_to_v3.mdx +++ b/docs/04_upgrading/upgrading_to_v3.mdx @@ -112,7 +112,8 @@ The HTTP layer is now abstracted behind `HttpClie To use a custom HTTP client, implement the `call()` method and pass the instance via the `ApifyClient.with_custom_http_client()` class method: ```python -from apify_client import ApifyClient, HttpClient, HttpResponse, Timeout +from apify_client import ApifyClient +from apify_client.http_clients import HttpClient, HttpResponse class MyHttpClient(HttpClient): def call(self, *, method, url, headers=None, params=None, @@ -127,6 +128,8 @@ client = ApifyClient.with_custom_http_client( The response must satisfy the `HttpResponse` protocol (properties: `status_code`, `text`, `content`, `headers`; methods: `json()`, `read()`, `close()`, `iter_bytes()`). Many popular libraries like `httpx` already satisfy this protocol out of the box. +The HTTP base classes, the `HttpResponse` protocol, and the default `ImpitHttpClient` / `ImpitHttpClientAsync` implementations live in the `apify_client.http_clients` submodule. The `Timeout` alias used on the `call()` signature lives in `apify_client.types`. + For a full walkthrough and working examples, see the [Custom HTTP clients](/docs/concepts/custom-http-clients) concept page and the [Custom HTTP client](/docs/guides/custom-http-client-httpx) guide. ## Tiered timeout system diff --git a/src/apify_client/__init__.py b/src/apify_client/__init__.py index 3add76db4..97534ce36 100644 --- a/src/apify_client/__init__.py +++ b/src/apify_client/__init__.py @@ -1,25 +1,11 @@ from importlib import metadata from ._apify_client import ApifyClient, ApifyClientAsync -from ._http_clients import ( - HttpClient, - HttpClientAsync, - HttpResponse, - ImpitHttpClient, - ImpitHttpClientAsync, -) -from ._types import Timeout __version__ = metadata.version('apify-client') __all__ = [ 'ApifyClient', 'ApifyClientAsync', - 'HttpClient', - 'HttpClientAsync', - 'HttpResponse', - 'ImpitHttpClient', - 'ImpitHttpClientAsync', - 'Timeout', '__version__', ] diff --git a/src/apify_client/_apify_client.py b/src/apify_client/_apify_client.py index c10f44248..30137aa8e 100644 --- a/src/apify_client/_apify_client.py +++ b/src/apify_client/_apify_client.py @@ -15,7 +15,6 @@ DEFAULT_TIMEOUT_SHORT, ) from apify_client._docs import docs_group -from apify_client._http_clients import HttpClient, HttpClientAsync, ImpitHttpClient, ImpitHttpClientAsync from apify_client._resource_clients import ( ActorClient, ActorClientAsync, @@ -74,6 +73,7 @@ ) from apify_client._statistics import ClientStatistics from apify_client._utils import check_custom_headers +from apify_client.http_clients import HttpClient, HttpClientAsync, ImpitHttpClient, ImpitHttpClientAsync if TYPE_CHECKING: from datetime import timedelta @@ -224,7 +224,8 @@ def with_custom_http_client( ### Usage ```python - from apify_client import ApifyClient, HttpClient, HttpResponse + from apify_client import ApifyClient + from apify_client.http_clients import HttpClient, HttpResponse class MyHttpClient(HttpClient): def call(self, *, method, url, **kwargs) -> HttpResponse: @@ -577,7 +578,8 @@ def with_custom_http_client( ### Usage ```python - from apify_client import ApifyClientAsync, HttpClientAsync, HttpResponse + from apify_client import ApifyClientAsync + from apify_client.http_clients import HttpClientAsync, HttpResponse class MyHttpClient(HttpClientAsync): async def call(self, *, method, url, **kwargs) -> HttpResponse: diff --git a/src/apify_client/_resource_clients/_resource_client.py b/src/apify_client/_resource_clients/_resource_client.py index f2e341042..590605724 100644 --- a/src/apify_client/_resource_clients/_resource_client.py +++ b/src/apify_client/_resource_clients/_resource_client.py @@ -4,12 +4,11 @@ import time from datetime import UTC, datetime, timedelta from functools import cached_property -from typing import TYPE_CHECKING, Any, get_args +from typing import TYPE_CHECKING, Any, Literal, get_args from apify_client._consts import DEFAULT_WAIT_FOR_FINISH, DEFAULT_WAIT_WHEN_JOB_NOT_EXIST from apify_client._docs import docs_group from apify_client._logging import WithLogDetailsClient -from apify_client._types import TerminalActorJobStatus from apify_client._utils import ( catch_not_found_for_resource_or_throw, catch_not_found_or_throw, @@ -21,10 +20,13 @@ if TYPE_CHECKING: from apify_client._client_registry import ClientRegistry, ClientRegistryAsync - from apify_client._http_clients import HttpClient, HttpClientAsync - from apify_client._types import Timeout + from apify_client.http_clients import HttpClient, HttpClientAsync + from apify_client.types import Timeout -_TERMINAL_STATUSES: frozenset[TerminalActorJobStatus] = frozenset(get_args(TerminalActorJobStatus)) +_TerminalActorJobStatus = Literal['SUCCEEDED', 'FAILED', 'TIMED-OUT', 'ABORTED'] +"""Subset of `ActorJobStatus` values that indicate the job has finished and will not change again.""" + +_TERMINAL_STATUSES: frozenset[_TerminalActorJobStatus] = frozenset(get_args(_TerminalActorJobStatus)) class ResourceClientBase(metaclass=WithLogDetailsClient): diff --git a/src/apify_client/_resource_clients/actor.py b/src/apify_client/_resource_clients/actor.py index e0ba33fef..150c70385 100644 --- a/src/apify_client/_resource_clients/actor.py +++ b/src/apify_client/_resource_clients/actor.py @@ -52,7 +52,7 @@ WebhookCollectionClient, WebhookCollectionClientAsync, ) - from apify_client._types import Timeout, WebhooksList + from apify_client.types import Timeout, WebhooksList _PricingInfo = ( PayPerEventActorPricingInfo diff --git a/src/apify_client/_resource_clients/actor_collection.py b/src/apify_client/_resource_clients/actor_collection.py index 9fbdb9281..e63adbdf7 100644 --- a/src/apify_client/_resource_clients/actor_collection.py +++ b/src/apify_client/_resource_clients/actor_collection.py @@ -22,7 +22,7 @@ from datetime import timedelta from apify_client._models import ActorShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/actor_env_var.py b/src/apify_client/_resource_clients/actor_env_var.py index 58e0ac8bb..9d04018ac 100644 --- a/src/apify_client/_resource_clients/actor_env_var.py +++ b/src/apify_client/_resource_clients/actor_env_var.py @@ -7,7 +7,7 @@ from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync if TYPE_CHECKING: - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/actor_env_var_collection.py b/src/apify_client/_resource_clients/actor_env_var_collection.py index 081e4c0eb..2a013d35a 100644 --- a/src/apify_client/_resource_clients/actor_env_var_collection.py +++ b/src/apify_client/_resource_clients/actor_env_var_collection.py @@ -9,7 +9,7 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/actor_version.py b/src/apify_client/_resource_clients/actor_version.py index 7a4a3acfa..497adfa03 100644 --- a/src/apify_client/_resource_clients/actor_version.py +++ b/src/apify_client/_resource_clients/actor_version.py @@ -23,7 +23,7 @@ ActorEnvVarCollectionClient, ActorEnvVarCollectionClientAsync, ) - from apify_client._types import Timeout + from apify_client.types import Timeout _source_file_list_adapter = TypeAdapter(list[SourceCodeFile | SourceCodeFolder]) diff --git a/src/apify_client/_resource_clients/actor_version_collection.py b/src/apify_client/_resource_clients/actor_version_collection.py index 23026db52..7a74277ed 100644 --- a/src/apify_client/_resource_clients/actor_version_collection.py +++ b/src/apify_client/_resource_clients/actor_version_collection.py @@ -21,7 +21,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._literals import VersionSourceType - from apify_client._types import Timeout + from apify_client.types import Timeout _source_file_list_adapter = TypeAdapter(list[SourceCodeFile | SourceCodeFolder]) diff --git a/src/apify_client/_resource_clients/build.py b/src/apify_client/_resource_clients/build.py index 1ae73de18..ed68fbe68 100644 --- a/src/apify_client/_resource_clients/build.py +++ b/src/apify_client/_resource_clients/build.py @@ -11,7 +11,7 @@ from datetime import timedelta from apify_client._resource_clients import LogClient, LogClientAsync - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/build_collection.py b/src/apify_client/_resource_clients/build_collection.py index ad90c4dee..ea7dd773b 100644 --- a/src/apify_client/_resource_clients/build_collection.py +++ b/src/apify_client/_resource_clients/build_collection.py @@ -11,7 +11,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import BuildShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/dataset.py b/src/apify_client/_resource_clients/dataset.py index b023efad5..faefdaf13 100644 --- a/src/apify_client/_resource_clients/dataset.py +++ b/src/apify_client/_resource_clients/dataset.py @@ -20,9 +20,9 @@ from collections.abc import AsyncIterator, Iterator from datetime import timedelta - from apify_client._http_clients import HttpResponse from apify_client._literals import GeneralAccess - from apify_client._types import JsonSerializable, Timeout + from apify_client.http_clients import HttpResponse + from apify_client.types import JsonSerializable, Timeout @docs_group('Other') diff --git a/src/apify_client/_resource_clients/dataset_collection.py b/src/apify_client/_resource_clients/dataset_collection.py index c194bd80c..af1cedd0c 100644 --- a/src/apify_client/_resource_clients/dataset_collection.py +++ b/src/apify_client/_resource_clients/dataset_collection.py @@ -17,7 +17,7 @@ from apify_client._literals import StorageOwnership from apify_client._models import DatasetListItem - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/key_value_store.py b/src/apify_client/_resource_clients/key_value_store.py index f371bf91c..5b83bbb8e 100644 --- a/src/apify_client/_resource_clients/key_value_store.py +++ b/src/apify_client/_resource_clients/key_value_store.py @@ -29,9 +29,9 @@ from collections.abc import AsyncIterator, Iterator from datetime import timedelta - from apify_client._http_clients import HttpResponse from apify_client._literals import GeneralAccess - from apify_client._types import Timeout + from apify_client.http_clients import HttpResponse + from apify_client.types import Timeout def _parse_get_record_response(response: HttpResponse) -> Any: diff --git a/src/apify_client/_resource_clients/key_value_store_collection.py b/src/apify_client/_resource_clients/key_value_store_collection.py index b4bf506d8..0fa0bb32f 100644 --- a/src/apify_client/_resource_clients/key_value_store_collection.py +++ b/src/apify_client/_resource_clients/key_value_store_collection.py @@ -16,7 +16,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._literals import StorageOwnership - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/log.py b/src/apify_client/_resource_clients/log.py index e92bd0375..723b0312e 100644 --- a/src/apify_client/_resource_clients/log.py +++ b/src/apify_client/_resource_clients/log.py @@ -11,8 +11,8 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator - from apify_client._http_clients import HttpResponse - from apify_client._types import Timeout + from apify_client.http_clients import HttpResponse + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/request_queue.py b/src/apify_client/_resource_clients/request_queue.py index 8bf31fb6e..70613d0b0 100644 --- a/src/apify_client/_resource_clients/request_queue.py +++ b/src/apify_client/_resource_clients/request_queue.py @@ -46,7 +46,7 @@ from apify_client._literals import GeneralAccess from apify_client._typeddicts import RequestDict, RequestDraftDeleteDict, RequestDraftDict - from apify_client._types import Timeout + from apify_client.types import Timeout _RQ_MAX_REQUESTS_PER_BATCH = 25 _MAX_PAYLOAD_SIZE_BYTES = 9 * 1024 * 1024 # 9 MB diff --git a/src/apify_client/_resource_clients/request_queue_collection.py b/src/apify_client/_resource_clients/request_queue_collection.py index 3239e30e6..c358e7131 100644 --- a/src/apify_client/_resource_clients/request_queue_collection.py +++ b/src/apify_client/_resource_clients/request_queue_collection.py @@ -17,7 +17,7 @@ from apify_client._literals import StorageOwnership from apify_client._models import RequestQueueShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/run.py b/src/apify_client/_resource_clients/run.py index ec0c0e8d8..fa1e8977d 100644 --- a/src/apify_client/_resource_clients/run.py +++ b/src/apify_client/_resource_clients/run.py @@ -30,7 +30,7 @@ RequestQueueClient, RequestQueueClientAsync, ) - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/run_collection.py b/src/apify_client/_resource_clients/run_collection.py index 21b7d1869..8b9edd873 100644 --- a/src/apify_client/_resource_clients/run_collection.py +++ b/src/apify_client/_resource_clients/run_collection.py @@ -13,7 +13,7 @@ from apify_client._literals import ActorJobStatus from apify_client._models import RunShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/schedule.py b/src/apify_client/_resource_clients/schedule.py index 8eee629ba..b6d2b3e23 100644 --- a/src/apify_client/_resource_clients/schedule.py +++ b/src/apify_client/_resource_clients/schedule.py @@ -14,7 +14,7 @@ from apify_client._utils import response_to_dict if TYPE_CHECKING: - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/schedule_collection.py b/src/apify_client/_resource_clients/schedule_collection.py index 138246e56..0e3bfa206 100644 --- a/src/apify_client/_resource_clients/schedule_collection.py +++ b/src/apify_client/_resource_clients/schedule_collection.py @@ -17,7 +17,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import ScheduleShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/store_collection.py b/src/apify_client/_resource_clients/store_collection.py index f1990ee12..3cff28e8b 100644 --- a/src/apify_client/_resource_clients/store_collection.py +++ b/src/apify_client/_resource_clients/store_collection.py @@ -11,7 +11,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import StoreListActor - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/task.py b/src/apify_client/_resource_clients/task.py index 819bc4649..0492e9813 100644 --- a/src/apify_client/_resource_clients/task.py +++ b/src/apify_client/_resource_clients/task.py @@ -29,7 +29,7 @@ WebhookCollectionClientAsync, ) from apify_client._typeddicts import TaskInputDict - from apify_client._types import Timeout, WebhooksList + from apify_client.types import Timeout, WebhooksList @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/task_collection.py b/src/apify_client/_resource_clients/task_collection.py index 04b6223d9..22075129b 100644 --- a/src/apify_client/_resource_clients/task_collection.py +++ b/src/apify_client/_resource_clients/task_collection.py @@ -23,7 +23,7 @@ from apify_client._models import TaskShort from apify_client._typeddicts import TaskInputDict - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/user.py b/src/apify_client/_resource_clients/user.py index 6703000f8..26a18acd8 100644 --- a/src/apify_client/_resource_clients/user.py +++ b/src/apify_client/_resource_clients/user.py @@ -19,7 +19,7 @@ from apify_client._utils import response_to_dict if TYPE_CHECKING: - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook.py b/src/apify_client/_resource_clients/webhook.py index 10b6a14b6..439ba34c3 100644 --- a/src/apify_client/_resource_clients/webhook.py +++ b/src/apify_client/_resource_clients/webhook.py @@ -19,7 +19,7 @@ if TYPE_CHECKING: from apify_client._literals import WebhookEventType from apify_client._resource_clients import WebhookDispatchCollectionClient, WebhookDispatchCollectionClientAsync - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook_collection.py b/src/apify_client/_resource_clients/webhook_collection.py index 4c7b3cf7c..d7fbf5174 100644 --- a/src/apify_client/_resource_clients/webhook_collection.py +++ b/src/apify_client/_resource_clients/webhook_collection.py @@ -18,7 +18,7 @@ from apify_client._literals import WebhookEventType from apify_client._models import Webhook, WebhookShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook_dispatch.py b/src/apify_client/_resource_clients/webhook_dispatch.py index c94e965e4..a3ed7c862 100644 --- a/src/apify_client/_resource_clients/webhook_dispatch.py +++ b/src/apify_client/_resource_clients/webhook_dispatch.py @@ -7,7 +7,7 @@ from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync if TYPE_CHECKING: - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook_dispatch_collection.py b/src/apify_client/_resource_clients/webhook_dispatch_collection.py index 2682ac472..805ea5deb 100644 --- a/src/apify_client/_resource_clients/webhook_dispatch_collection.py +++ b/src/apify_client/_resource_clients/webhook_dispatch_collection.py @@ -11,7 +11,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import WebhookDispatch - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_utils.py b/src/apify_client/_utils.py index 7196e369b..e488b5bea 100644 --- a/src/apify_client/_utils.py +++ b/src/apify_client/_utils.py @@ -20,9 +20,9 @@ if TYPE_CHECKING: from datetime import timedelta - from apify_client._http_clients import HttpResponse - from apify_client._types import WebhooksList from apify_client.errors import ApifyApiError + from apify_client.http_clients import HttpResponse + from apify_client.types import WebhooksList T = TypeVar('T') diff --git a/src/apify_client/errors.py b/src/apify_client/errors.py index 84c5423de..630fe0654 100644 --- a/src/apify_client/errors.py +++ b/src/apify_client/errors.py @@ -8,7 +8,7 @@ if TYPE_CHECKING: from typing import Self - from apify_client._http_clients import HttpResponse + from apify_client.http_clients import HttpResponse @docs_group('Errors') @@ -161,3 +161,17 @@ def __init__(self, response: HttpResponse) -> None: 409: ConflictError, 429: RateLimitError, } + + +__all__ = [ + 'ApifyApiError', + 'ApifyClientError', + 'ConflictError', + 'ForbiddenError', + 'InvalidRequestError', + 'InvalidResponseBodyError', + 'NotFoundError', + 'RateLimitError', + 'ServerError', + 'UnauthorizedError', +] diff --git a/src/apify_client/_http_clients/__init__.py b/src/apify_client/http_clients/__init__.py similarity index 100% rename from src/apify_client/_http_clients/__init__.py rename to src/apify_client/http_clients/__init__.py diff --git a/src/apify_client/_http_clients/_base.py b/src/apify_client/http_clients/_base.py similarity index 99% rename from src/apify_client/_http_clients/_base.py rename to src/apify_client/http_clients/_base.py index 2abe8ab54..6da96dbf9 100644 --- a/src/apify_client/_http_clients/_base.py +++ b/src/apify_client/http_clients/_base.py @@ -25,7 +25,7 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator, Mapping - from apify_client._types import JsonSerializable, Timeout + from apify_client.types import JsonSerializable, Timeout @docs_group('HTTP clients') diff --git a/src/apify_client/_http_clients/_impit.py b/src/apify_client/http_clients/_impit.py similarity index 99% rename from src/apify_client/_http_clients/_impit.py rename to src/apify_client/http_clients/_impit.py index 0701ad5c1..c137dde77 100644 --- a/src/apify_client/_http_clients/_impit.py +++ b/src/apify_client/http_clients/_impit.py @@ -19,17 +19,17 @@ DEFAULT_TIMEOUT_SHORT, ) from apify_client._docs import docs_group -from apify_client._http_clients import HttpClient, HttpClientAsync from apify_client._logging import log_context, logger_name from apify_client._utils import to_seconds from apify_client.errors import ApifyApiError, InvalidResponseBodyError +from apify_client.http_clients._base import HttpClient, HttpClientAsync if TYPE_CHECKING: from collections.abc import Awaitable, Callable - from apify_client._http_clients import HttpResponse from apify_client._statistics import ClientStatistics - from apify_client._types import JsonSerializable, Timeout + from apify_client.http_clients._base import HttpResponse + from apify_client.types import JsonSerializable, Timeout T = TypeVar('T') diff --git a/src/apify_client/_types.py b/src/apify_client/types.py similarity index 89% rename from src/apify_client/_types.py rename to src/apify_client/types.py index 8d285dce1..14bc9b513 100644 --- a/src/apify_client/_types.py +++ b/src/apify_client/types.py @@ -17,9 +17,6 @@ `condition`) are ignored at runtime. """ -TerminalActorJobStatus = Literal['SUCCEEDED', 'FAILED', 'TIMED-OUT', 'ABORTED'] -"""Subset of `ActorJobStatus` values that indicate the job has finished and will not change again.""" - Timeout = timedelta | Literal['no_timeout', 'short', 'medium', 'long'] """Type for the `timeout` parameter on resource client methods. @@ -32,3 +29,10 @@ Based on the definition discussed in https://github.com/python/typing/issues/182. """ + + +__all__ = [ + 'JsonSerializable', + 'Timeout', + 'WebhooksList', +] diff --git a/tests/unit/test_client_errors.py b/tests/unit/test_client_errors.py index d86a476bf..4dae21687 100644 --- a/tests/unit/test_client_errors.py +++ b/tests/unit/test_client_errors.py @@ -7,7 +7,6 @@ from werkzeug import Response from apify_client import ApifyClient, ApifyClientAsync -from apify_client._http_clients import ImpitHttpClient, ImpitHttpClientAsync from apify_client.errors import ( ApifyApiError, ConflictError, @@ -18,6 +17,7 @@ ServerError, UnauthorizedError, ) +from apify_client.http_clients import ImpitHttpClient, ImpitHttpClientAsync if TYPE_CHECKING: from collections.abc import Awaitable, Callable diff --git a/tests/unit/test_client_headers.py b/tests/unit/test_client_headers.py index 84f9b2b8c..fcc086fdb 100644 --- a/tests/unit/test_client_headers.py +++ b/tests/unit/test_client_headers.py @@ -8,7 +8,7 @@ from werkzeug import Request, Response -from apify_client._http_clients import ImpitHttpClient, ImpitHttpClientAsync +from apify_client.http_clients import ImpitHttpClient, ImpitHttpClientAsync if TYPE_CHECKING: from pytest_httpserver import HTTPServer diff --git a/tests/unit/test_client_timeouts.py b/tests/unit/test_client_timeouts.py index 7c961f50d..2e87279e3 100644 --- a/tests/unit/test_client_timeouts.py +++ b/tests/unit/test_client_timeouts.py @@ -7,7 +7,7 @@ import pytest from impit import HTTPError, Response, TimeoutException -from apify_client._http_clients import ImpitHttpClient, ImpitHttpClientAsync +from apify_client.http_clients import ImpitHttpClient, ImpitHttpClientAsync if TYPE_CHECKING: from collections.abc import Iterator diff --git a/tests/unit/test_http_clients.py b/tests/unit/test_http_clients.py index 50d9f54c0..b54c9fee8 100644 --- a/tests/unit/test_http_clients.py +++ b/tests/unit/test_http_clients.py @@ -8,10 +8,10 @@ import impit import pytest -from apify_client._http_clients import HttpClient, HttpClientAsync, HttpResponse, ImpitHttpClient, ImpitHttpClientAsync -from apify_client._http_clients._impit import _is_retryable_error from apify_client._statistics import ClientStatistics from apify_client.errors import InvalidResponseBodyError +from apify_client.http_clients import HttpClient, HttpClientAsync, HttpResponse, ImpitHttpClient, ImpitHttpClientAsync +from apify_client.http_clients._impit import _is_retryable_error class _ConcreteHttpClient(HttpClient): diff --git a/tests/unit/test_pluggable_http_client.py b/tests/unit/test_pluggable_http_client.py index e601e3c5b..e5eab9e8b 100644 --- a/tests/unit/test_pluggable_http_client.py +++ b/tests/unit/test_pluggable_http_client.py @@ -6,22 +6,22 @@ import pytest import apify_client as apify_client_module -from apify_client import ( - ApifyClient, - ApifyClientAsync, +from apify_client import ApifyClient, ApifyClientAsync +from apify_client.errors import ApifyApiError +from apify_client.http_clients import ( HttpClient, HttpClientAsync, HttpResponse, + ImpitHttpClient, + ImpitHttpClientAsync, ) -from apify_client._http_clients import ImpitHttpClient, ImpitHttpClientAsync -from apify_client.errors import ApifyApiError if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator from pytest_httpserver import HTTPServer - from apify_client._types import Timeout + from apify_client.types import Timeout # -- Test response and client implementations -- @@ -287,12 +287,11 @@ async def test_apify_client_async_with_custom_http_client_accepts_url_params() - def test_public_exports() -> None: - """Test that all HTTP client types are available from the public API.""" - assert hasattr(apify_client_module, 'HttpClient') - assert hasattr(apify_client_module, 'HttpClientAsync') - assert hasattr(apify_client_module, 'HttpResponse') - assert hasattr(apify_client_module, 'ImpitHttpClient') - assert hasattr(apify_client_module, 'ImpitHttpClientAsync') + """HTTP client types are exposed from `apify_client.http_clients`, not the root namespace.""" + http_clients_module = apify_client_module.http_clients + for name in ('HttpClient', 'HttpClientAsync', 'HttpResponse', 'ImpitHttpClient', 'ImpitHttpClientAsync'): + assert hasattr(http_clients_module, name) + assert not hasattr(apify_client_module, name) # -- http_client property -- From 54ce3b990064050e627eb8dad6ed3bba488b92fb Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Sun, 17 May 2026 20:23:20 +0200 Subject: [PATCH 2/4] refactor: keep `_types.py` private, expose only `Timeout` via `types.py` Co-Authored-By: Claude Opus 4.7 (1M context) --- .../_resource_clients/_resource_client.py | 2 +- src/apify_client/_resource_clients/actor.py | 2 +- .../_resource_clients/actor_collection.py | 2 +- .../_resource_clients/actor_env_var.py | 2 +- .../actor_env_var_collection.py | 2 +- .../_resource_clients/actor_version.py | 2 +- .../actor_version_collection.py | 2 +- src/apify_client/_resource_clients/build.py | 2 +- .../_resource_clients/build_collection.py | 2 +- src/apify_client/_resource_clients/dataset.py | 2 +- .../_resource_clients/dataset_collection.py | 2 +- .../_resource_clients/key_value_store.py | 2 +- .../key_value_store_collection.py | 2 +- src/apify_client/_resource_clients/log.py | 2 +- .../_resource_clients/request_queue.py | 2 +- .../request_queue_collection.py | 2 +- src/apify_client/_resource_clients/run.py | 2 +- .../_resource_clients/run_collection.py | 2 +- .../_resource_clients/schedule.py | 2 +- .../_resource_clients/schedule_collection.py | 2 +- .../_resource_clients/store_collection.py | 2 +- src/apify_client/_resource_clients/task.py | 2 +- .../_resource_clients/task_collection.py | 2 +- src/apify_client/_resource_clients/user.py | 2 +- src/apify_client/_resource_clients/webhook.py | 2 +- .../_resource_clients/webhook_collection.py | 2 +- .../_resource_clients/webhook_dispatch.py | 2 +- .../webhook_dispatch_collection.py | 2 +- src/apify_client/_types.py | 38 +++++++++++++++++++ src/apify_client/_utils.py | 2 +- src/apify_client/http_clients/_base.py | 2 +- src/apify_client/http_clients/_impit.py | 2 +- src/apify_client/types.py | 33 +--------------- tests/unit/test_pluggable_http_client.py | 2 +- 34 files changed, 71 insertions(+), 64 deletions(-) create mode 100644 src/apify_client/_types.py diff --git a/src/apify_client/_resource_clients/_resource_client.py b/src/apify_client/_resource_clients/_resource_client.py index 590605724..d445d0a8b 100644 --- a/src/apify_client/_resource_clients/_resource_client.py +++ b/src/apify_client/_resource_clients/_resource_client.py @@ -20,8 +20,8 @@ if TYPE_CHECKING: from apify_client._client_registry import ClientRegistry, ClientRegistryAsync + from apify_client._types import Timeout from apify_client.http_clients import HttpClient, HttpClientAsync - from apify_client.types import Timeout _TerminalActorJobStatus = Literal['SUCCEEDED', 'FAILED', 'TIMED-OUT', 'ABORTED'] """Subset of `ActorJobStatus` values that indicate the job has finished and will not change again.""" diff --git a/src/apify_client/_resource_clients/actor.py b/src/apify_client/_resource_clients/actor.py index 150c70385..e0ba33fef 100644 --- a/src/apify_client/_resource_clients/actor.py +++ b/src/apify_client/_resource_clients/actor.py @@ -52,7 +52,7 @@ WebhookCollectionClient, WebhookCollectionClientAsync, ) - from apify_client.types import Timeout, WebhooksList + from apify_client._types import Timeout, WebhooksList _PricingInfo = ( PayPerEventActorPricingInfo diff --git a/src/apify_client/_resource_clients/actor_collection.py b/src/apify_client/_resource_clients/actor_collection.py index e63adbdf7..9fbdb9281 100644 --- a/src/apify_client/_resource_clients/actor_collection.py +++ b/src/apify_client/_resource_clients/actor_collection.py @@ -22,7 +22,7 @@ from datetime import timedelta from apify_client._models import ActorShort - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/actor_env_var.py b/src/apify_client/_resource_clients/actor_env_var.py index 9d04018ac..58e0ac8bb 100644 --- a/src/apify_client/_resource_clients/actor_env_var.py +++ b/src/apify_client/_resource_clients/actor_env_var.py @@ -7,7 +7,7 @@ from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync if TYPE_CHECKING: - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/actor_env_var_collection.py b/src/apify_client/_resource_clients/actor_env_var_collection.py index 2a013d35a..081e4c0eb 100644 --- a/src/apify_client/_resource_clients/actor_env_var_collection.py +++ b/src/apify_client/_resource_clients/actor_env_var_collection.py @@ -9,7 +9,7 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/actor_version.py b/src/apify_client/_resource_clients/actor_version.py index 497adfa03..7a4a3acfa 100644 --- a/src/apify_client/_resource_clients/actor_version.py +++ b/src/apify_client/_resource_clients/actor_version.py @@ -23,7 +23,7 @@ ActorEnvVarCollectionClient, ActorEnvVarCollectionClientAsync, ) - from apify_client.types import Timeout + from apify_client._types import Timeout _source_file_list_adapter = TypeAdapter(list[SourceCodeFile | SourceCodeFolder]) diff --git a/src/apify_client/_resource_clients/actor_version_collection.py b/src/apify_client/_resource_clients/actor_version_collection.py index 7a74277ed..23026db52 100644 --- a/src/apify_client/_resource_clients/actor_version_collection.py +++ b/src/apify_client/_resource_clients/actor_version_collection.py @@ -21,7 +21,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._literals import VersionSourceType - from apify_client.types import Timeout + from apify_client._types import Timeout _source_file_list_adapter = TypeAdapter(list[SourceCodeFile | SourceCodeFolder]) diff --git a/src/apify_client/_resource_clients/build.py b/src/apify_client/_resource_clients/build.py index ed68fbe68..1ae73de18 100644 --- a/src/apify_client/_resource_clients/build.py +++ b/src/apify_client/_resource_clients/build.py @@ -11,7 +11,7 @@ from datetime import timedelta from apify_client._resource_clients import LogClient, LogClientAsync - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/build_collection.py b/src/apify_client/_resource_clients/build_collection.py index ea7dd773b..ad90c4dee 100644 --- a/src/apify_client/_resource_clients/build_collection.py +++ b/src/apify_client/_resource_clients/build_collection.py @@ -11,7 +11,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import BuildShort - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/dataset.py b/src/apify_client/_resource_clients/dataset.py index faefdaf13..d243c88ef 100644 --- a/src/apify_client/_resource_clients/dataset.py +++ b/src/apify_client/_resource_clients/dataset.py @@ -21,8 +21,8 @@ from datetime import timedelta from apify_client._literals import GeneralAccess + from apify_client._types import JsonSerializable, Timeout from apify_client.http_clients import HttpResponse - from apify_client.types import JsonSerializable, Timeout @docs_group('Other') diff --git a/src/apify_client/_resource_clients/dataset_collection.py b/src/apify_client/_resource_clients/dataset_collection.py index af1cedd0c..c194bd80c 100644 --- a/src/apify_client/_resource_clients/dataset_collection.py +++ b/src/apify_client/_resource_clients/dataset_collection.py @@ -17,7 +17,7 @@ from apify_client._literals import StorageOwnership from apify_client._models import DatasetListItem - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/key_value_store.py b/src/apify_client/_resource_clients/key_value_store.py index 5b83bbb8e..9418102e7 100644 --- a/src/apify_client/_resource_clients/key_value_store.py +++ b/src/apify_client/_resource_clients/key_value_store.py @@ -30,8 +30,8 @@ from datetime import timedelta from apify_client._literals import GeneralAccess + from apify_client._types import Timeout from apify_client.http_clients import HttpResponse - from apify_client.types import Timeout def _parse_get_record_response(response: HttpResponse) -> Any: diff --git a/src/apify_client/_resource_clients/key_value_store_collection.py b/src/apify_client/_resource_clients/key_value_store_collection.py index 0fa0bb32f..b4bf506d8 100644 --- a/src/apify_client/_resource_clients/key_value_store_collection.py +++ b/src/apify_client/_resource_clients/key_value_store_collection.py @@ -16,7 +16,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._literals import StorageOwnership - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/log.py b/src/apify_client/_resource_clients/log.py index 723b0312e..18f9636bb 100644 --- a/src/apify_client/_resource_clients/log.py +++ b/src/apify_client/_resource_clients/log.py @@ -11,8 +11,8 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator + from apify_client._types import Timeout from apify_client.http_clients import HttpResponse - from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/request_queue.py b/src/apify_client/_resource_clients/request_queue.py index 70613d0b0..8bf31fb6e 100644 --- a/src/apify_client/_resource_clients/request_queue.py +++ b/src/apify_client/_resource_clients/request_queue.py @@ -46,7 +46,7 @@ from apify_client._literals import GeneralAccess from apify_client._typeddicts import RequestDict, RequestDraftDeleteDict, RequestDraftDict - from apify_client.types import Timeout + from apify_client._types import Timeout _RQ_MAX_REQUESTS_PER_BATCH = 25 _MAX_PAYLOAD_SIZE_BYTES = 9 * 1024 * 1024 # 9 MB diff --git a/src/apify_client/_resource_clients/request_queue_collection.py b/src/apify_client/_resource_clients/request_queue_collection.py index c358e7131..3239e30e6 100644 --- a/src/apify_client/_resource_clients/request_queue_collection.py +++ b/src/apify_client/_resource_clients/request_queue_collection.py @@ -17,7 +17,7 @@ from apify_client._literals import StorageOwnership from apify_client._models import RequestQueueShort - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/run.py b/src/apify_client/_resource_clients/run.py index fa1e8977d..ec0c0e8d8 100644 --- a/src/apify_client/_resource_clients/run.py +++ b/src/apify_client/_resource_clients/run.py @@ -30,7 +30,7 @@ RequestQueueClient, RequestQueueClientAsync, ) - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/run_collection.py b/src/apify_client/_resource_clients/run_collection.py index 8b9edd873..21b7d1869 100644 --- a/src/apify_client/_resource_clients/run_collection.py +++ b/src/apify_client/_resource_clients/run_collection.py @@ -13,7 +13,7 @@ from apify_client._literals import ActorJobStatus from apify_client._models import RunShort - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/schedule.py b/src/apify_client/_resource_clients/schedule.py index b6d2b3e23..8eee629ba 100644 --- a/src/apify_client/_resource_clients/schedule.py +++ b/src/apify_client/_resource_clients/schedule.py @@ -14,7 +14,7 @@ from apify_client._utils import response_to_dict if TYPE_CHECKING: - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/schedule_collection.py b/src/apify_client/_resource_clients/schedule_collection.py index 0e3bfa206..138246e56 100644 --- a/src/apify_client/_resource_clients/schedule_collection.py +++ b/src/apify_client/_resource_clients/schedule_collection.py @@ -17,7 +17,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import ScheduleShort - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/store_collection.py b/src/apify_client/_resource_clients/store_collection.py index 3cff28e8b..f1990ee12 100644 --- a/src/apify_client/_resource_clients/store_collection.py +++ b/src/apify_client/_resource_clients/store_collection.py @@ -11,7 +11,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import StoreListActor - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/task.py b/src/apify_client/_resource_clients/task.py index 0492e9813..819bc4649 100644 --- a/src/apify_client/_resource_clients/task.py +++ b/src/apify_client/_resource_clients/task.py @@ -29,7 +29,7 @@ WebhookCollectionClientAsync, ) from apify_client._typeddicts import TaskInputDict - from apify_client.types import Timeout, WebhooksList + from apify_client._types import Timeout, WebhooksList @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/task_collection.py b/src/apify_client/_resource_clients/task_collection.py index 22075129b..04b6223d9 100644 --- a/src/apify_client/_resource_clients/task_collection.py +++ b/src/apify_client/_resource_clients/task_collection.py @@ -23,7 +23,7 @@ from apify_client._models import TaskShort from apify_client._typeddicts import TaskInputDict - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/user.py b/src/apify_client/_resource_clients/user.py index 26a18acd8..6703000f8 100644 --- a/src/apify_client/_resource_clients/user.py +++ b/src/apify_client/_resource_clients/user.py @@ -19,7 +19,7 @@ from apify_client._utils import response_to_dict if TYPE_CHECKING: - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook.py b/src/apify_client/_resource_clients/webhook.py index 439ba34c3..10b6a14b6 100644 --- a/src/apify_client/_resource_clients/webhook.py +++ b/src/apify_client/_resource_clients/webhook.py @@ -19,7 +19,7 @@ if TYPE_CHECKING: from apify_client._literals import WebhookEventType from apify_client._resource_clients import WebhookDispatchCollectionClient, WebhookDispatchCollectionClientAsync - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook_collection.py b/src/apify_client/_resource_clients/webhook_collection.py index d7fbf5174..4c7b3cf7c 100644 --- a/src/apify_client/_resource_clients/webhook_collection.py +++ b/src/apify_client/_resource_clients/webhook_collection.py @@ -18,7 +18,7 @@ from apify_client._literals import WebhookEventType from apify_client._models import Webhook, WebhookShort - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook_dispatch.py b/src/apify_client/_resource_clients/webhook_dispatch.py index a3ed7c862..c94e965e4 100644 --- a/src/apify_client/_resource_clients/webhook_dispatch.py +++ b/src/apify_client/_resource_clients/webhook_dispatch.py @@ -7,7 +7,7 @@ from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync if TYPE_CHECKING: - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook_dispatch_collection.py b/src/apify_client/_resource_clients/webhook_dispatch_collection.py index 805ea5deb..2682ac472 100644 --- a/src/apify_client/_resource_clients/webhook_dispatch_collection.py +++ b/src/apify_client/_resource_clients/webhook_dispatch_collection.py @@ -11,7 +11,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import WebhookDispatch - from apify_client.types import Timeout + from apify_client._types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_types.py b/src/apify_client/_types.py new file mode 100644 index 000000000..14bc9b513 --- /dev/null +++ b/src/apify_client/_types.py @@ -0,0 +1,38 @@ +from __future__ import annotations + +from datetime import timedelta +from typing import Literal + +from apify_client._models import WebhookCreate, WebhookRepresentation +from apify_client._typeddicts import WebhookCreateDict, WebhookRepresentationDict + +WebhooksList = ( + list[WebhookCreate] | list[WebhookCreateDict] | list[WebhookRepresentation] | list[WebhookRepresentationDict] +) +"""Type for the `webhooks` parameter on resource-client `start`/`call` methods and `from_webhooks`. + +`WebhookRepresentation` / `WebhookRepresentationDict` are the minimal ad-hoc webhook shape (only +`event_types` and `request_url` required). `WebhookCreate` / `WebhookCreateDict` are accepted so a +persistent-webhook definition can be reused; their fields not relevant to ad-hoc webhooks (e.g. +`condition`) are ignored at runtime. +""" + +Timeout = timedelta | Literal['no_timeout', 'short', 'medium', 'long'] +"""Type for the `timeout` parameter on resource client methods. + +`'short'`, `'medium'`, and `'long'` are tier literals resolved by the HTTP client to configured values. +A `timedelta` overrides the timeout for this call, and `'no_timeout'` disables the timeout entirely. +""" + +JsonSerializable = dict[str, 'JsonSerializable'] | list['JsonSerializable'] | str | int | float | bool | None +"""Recursive type for JSON-serializable values - primitives plus objects and arrays with JSON-serializable contents. + +Based on the definition discussed in https://github.com/python/typing/issues/182. +""" + + +__all__ = [ + 'JsonSerializable', + 'Timeout', + 'WebhooksList', +] diff --git a/src/apify_client/_utils.py b/src/apify_client/_utils.py index e488b5bea..6e3c5c7e2 100644 --- a/src/apify_client/_utils.py +++ b/src/apify_client/_utils.py @@ -20,9 +20,9 @@ if TYPE_CHECKING: from datetime import timedelta + from apify_client._types import WebhooksList from apify_client.errors import ApifyApiError from apify_client.http_clients import HttpResponse - from apify_client.types import WebhooksList T = TypeVar('T') diff --git a/src/apify_client/http_clients/_base.py b/src/apify_client/http_clients/_base.py index 6da96dbf9..2abe8ab54 100644 --- a/src/apify_client/http_clients/_base.py +++ b/src/apify_client/http_clients/_base.py @@ -25,7 +25,7 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator, Mapping - from apify_client.types import JsonSerializable, Timeout + from apify_client._types import JsonSerializable, Timeout @docs_group('HTTP clients') diff --git a/src/apify_client/http_clients/_impit.py b/src/apify_client/http_clients/_impit.py index c137dde77..ef7a0b8fd 100644 --- a/src/apify_client/http_clients/_impit.py +++ b/src/apify_client/http_clients/_impit.py @@ -28,8 +28,8 @@ from collections.abc import Awaitable, Callable from apify_client._statistics import ClientStatistics + from apify_client._types import JsonSerializable, Timeout from apify_client.http_clients._base import HttpResponse - from apify_client.types import JsonSerializable, Timeout T = TypeVar('T') diff --git a/src/apify_client/types.py b/src/apify_client/types.py index 14bc9b513..cbedc5123 100644 --- a/src/apify_client/types.py +++ b/src/apify_client/types.py @@ -1,38 +1,7 @@ from __future__ import annotations -from datetime import timedelta -from typing import Literal - -from apify_client._models import WebhookCreate, WebhookRepresentation -from apify_client._typeddicts import WebhookCreateDict, WebhookRepresentationDict - -WebhooksList = ( - list[WebhookCreate] | list[WebhookCreateDict] | list[WebhookRepresentation] | list[WebhookRepresentationDict] -) -"""Type for the `webhooks` parameter on resource-client `start`/`call` methods and `from_webhooks`. - -`WebhookRepresentation` / `WebhookRepresentationDict` are the minimal ad-hoc webhook shape (only -`event_types` and `request_url` required). `WebhookCreate` / `WebhookCreateDict` are accepted so a -persistent-webhook definition can be reused; their fields not relevant to ad-hoc webhooks (e.g. -`condition`) are ignored at runtime. -""" - -Timeout = timedelta | Literal['no_timeout', 'short', 'medium', 'long'] -"""Type for the `timeout` parameter on resource client methods. - -`'short'`, `'medium'`, and `'long'` are tier literals resolved by the HTTP client to configured values. -A `timedelta` overrides the timeout for this call, and `'no_timeout'` disables the timeout entirely. -""" - -JsonSerializable = dict[str, 'JsonSerializable'] | list['JsonSerializable'] | str | int | float | bool | None -"""Recursive type for JSON-serializable values - primitives plus objects and arrays with JSON-serializable contents. - -Based on the definition discussed in https://github.com/python/typing/issues/182. -""" - +from apify_client._types import Timeout __all__ = [ - 'JsonSerializable', 'Timeout', - 'WebhooksList', ] diff --git a/tests/unit/test_pluggable_http_client.py b/tests/unit/test_pluggable_http_client.py index e5eab9e8b..e075bf58e 100644 --- a/tests/unit/test_pluggable_http_client.py +++ b/tests/unit/test_pluggable_http_client.py @@ -21,7 +21,7 @@ from pytest_httpserver import HTTPServer - from apify_client.types import Timeout + from apify_client._types import Timeout # -- Test response and client implementations -- From d6701fea298f1d8df513e0f4b99cd00078d7b42e Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Mon, 18 May 2026 13:46:39 +0200 Subject: [PATCH 3/4] refactor: move public type aliases to `types.py`, rename `_types.py` to `_internal_types.py` Co-Authored-By: Claude Opus 4.7 (1M context) --- src/apify_client/_internal_types.py | 6 +++ .../_resource_clients/_resource_client.py | 2 +- src/apify_client/_resource_clients/actor.py | 2 +- .../_resource_clients/actor_collection.py | 2 +- .../_resource_clients/actor_env_var.py | 2 +- .../actor_env_var_collection.py | 2 +- .../_resource_clients/actor_version.py | 2 +- .../actor_version_collection.py | 2 +- src/apify_client/_resource_clients/build.py | 2 +- .../_resource_clients/build_collection.py | 2 +- src/apify_client/_resource_clients/dataset.py | 2 +- .../_resource_clients/dataset_collection.py | 2 +- .../_resource_clients/key_value_store.py | 2 +- .../key_value_store_collection.py | 2 +- src/apify_client/_resource_clients/log.py | 2 +- .../_resource_clients/request_queue.py | 2 +- .../request_queue_collection.py | 2 +- src/apify_client/_resource_clients/run.py | 2 +- .../_resource_clients/run_collection.py | 2 +- .../_resource_clients/schedule.py | 2 +- .../_resource_clients/schedule_collection.py | 2 +- .../_resource_clients/store_collection.py | 2 +- src/apify_client/_resource_clients/task.py | 2 +- .../_resource_clients/task_collection.py | 2 +- src/apify_client/_resource_clients/user.py | 2 +- src/apify_client/_resource_clients/webhook.py | 2 +- .../_resource_clients/webhook_collection.py | 2 +- .../_resource_clients/webhook_dispatch.py | 2 +- .../webhook_dispatch_collection.py | 2 +- src/apify_client/_types.py | 38 ------------------- src/apify_client/_utils.py | 2 +- src/apify_client/http_clients/_base.py | 2 +- src/apify_client/http_clients/_impit.py | 2 +- src/apify_client/types.py | 32 +++++++++++++++- tests/unit/test_pluggable_http_client.py | 2 +- 35 files changed, 69 insertions(+), 71 deletions(-) create mode 100644 src/apify_client/_internal_types.py delete mode 100644 src/apify_client/_types.py diff --git a/src/apify_client/_internal_types.py b/src/apify_client/_internal_types.py new file mode 100644 index 000000000..84facd8f9 --- /dev/null +++ b/src/apify_client/_internal_types.py @@ -0,0 +1,6 @@ +from __future__ import annotations + +from typing import Literal + +TerminalActorJobStatus = Literal['SUCCEEDED', 'FAILED', 'TIMED-OUT', 'ABORTED'] +"""Subset of `ActorJobStatus` values that indicate the job has finished and will not change again.""" diff --git a/src/apify_client/_resource_clients/_resource_client.py b/src/apify_client/_resource_clients/_resource_client.py index d445d0a8b..590605724 100644 --- a/src/apify_client/_resource_clients/_resource_client.py +++ b/src/apify_client/_resource_clients/_resource_client.py @@ -20,8 +20,8 @@ if TYPE_CHECKING: from apify_client._client_registry import ClientRegistry, ClientRegistryAsync - from apify_client._types import Timeout from apify_client.http_clients import HttpClient, HttpClientAsync + from apify_client.types import Timeout _TerminalActorJobStatus = Literal['SUCCEEDED', 'FAILED', 'TIMED-OUT', 'ABORTED'] """Subset of `ActorJobStatus` values that indicate the job has finished and will not change again.""" diff --git a/src/apify_client/_resource_clients/actor.py b/src/apify_client/_resource_clients/actor.py index e0ba33fef..150c70385 100644 --- a/src/apify_client/_resource_clients/actor.py +++ b/src/apify_client/_resource_clients/actor.py @@ -52,7 +52,7 @@ WebhookCollectionClient, WebhookCollectionClientAsync, ) - from apify_client._types import Timeout, WebhooksList + from apify_client.types import Timeout, WebhooksList _PricingInfo = ( PayPerEventActorPricingInfo diff --git a/src/apify_client/_resource_clients/actor_collection.py b/src/apify_client/_resource_clients/actor_collection.py index 9fbdb9281..e63adbdf7 100644 --- a/src/apify_client/_resource_clients/actor_collection.py +++ b/src/apify_client/_resource_clients/actor_collection.py @@ -22,7 +22,7 @@ from datetime import timedelta from apify_client._models import ActorShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/actor_env_var.py b/src/apify_client/_resource_clients/actor_env_var.py index 58e0ac8bb..9d04018ac 100644 --- a/src/apify_client/_resource_clients/actor_env_var.py +++ b/src/apify_client/_resource_clients/actor_env_var.py @@ -7,7 +7,7 @@ from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync if TYPE_CHECKING: - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/actor_env_var_collection.py b/src/apify_client/_resource_clients/actor_env_var_collection.py index 081e4c0eb..2a013d35a 100644 --- a/src/apify_client/_resource_clients/actor_env_var_collection.py +++ b/src/apify_client/_resource_clients/actor_env_var_collection.py @@ -9,7 +9,7 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/actor_version.py b/src/apify_client/_resource_clients/actor_version.py index 7a4a3acfa..497adfa03 100644 --- a/src/apify_client/_resource_clients/actor_version.py +++ b/src/apify_client/_resource_clients/actor_version.py @@ -23,7 +23,7 @@ ActorEnvVarCollectionClient, ActorEnvVarCollectionClientAsync, ) - from apify_client._types import Timeout + from apify_client.types import Timeout _source_file_list_adapter = TypeAdapter(list[SourceCodeFile | SourceCodeFolder]) diff --git a/src/apify_client/_resource_clients/actor_version_collection.py b/src/apify_client/_resource_clients/actor_version_collection.py index 23026db52..7a74277ed 100644 --- a/src/apify_client/_resource_clients/actor_version_collection.py +++ b/src/apify_client/_resource_clients/actor_version_collection.py @@ -21,7 +21,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._literals import VersionSourceType - from apify_client._types import Timeout + from apify_client.types import Timeout _source_file_list_adapter = TypeAdapter(list[SourceCodeFile | SourceCodeFolder]) diff --git a/src/apify_client/_resource_clients/build.py b/src/apify_client/_resource_clients/build.py index 1ae73de18..ed68fbe68 100644 --- a/src/apify_client/_resource_clients/build.py +++ b/src/apify_client/_resource_clients/build.py @@ -11,7 +11,7 @@ from datetime import timedelta from apify_client._resource_clients import LogClient, LogClientAsync - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/build_collection.py b/src/apify_client/_resource_clients/build_collection.py index ad90c4dee..ea7dd773b 100644 --- a/src/apify_client/_resource_clients/build_collection.py +++ b/src/apify_client/_resource_clients/build_collection.py @@ -11,7 +11,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import BuildShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/dataset.py b/src/apify_client/_resource_clients/dataset.py index d243c88ef..faefdaf13 100644 --- a/src/apify_client/_resource_clients/dataset.py +++ b/src/apify_client/_resource_clients/dataset.py @@ -21,8 +21,8 @@ from datetime import timedelta from apify_client._literals import GeneralAccess - from apify_client._types import JsonSerializable, Timeout from apify_client.http_clients import HttpResponse + from apify_client.types import JsonSerializable, Timeout @docs_group('Other') diff --git a/src/apify_client/_resource_clients/dataset_collection.py b/src/apify_client/_resource_clients/dataset_collection.py index c194bd80c..af1cedd0c 100644 --- a/src/apify_client/_resource_clients/dataset_collection.py +++ b/src/apify_client/_resource_clients/dataset_collection.py @@ -17,7 +17,7 @@ from apify_client._literals import StorageOwnership from apify_client._models import DatasetListItem - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/key_value_store.py b/src/apify_client/_resource_clients/key_value_store.py index 9418102e7..5b83bbb8e 100644 --- a/src/apify_client/_resource_clients/key_value_store.py +++ b/src/apify_client/_resource_clients/key_value_store.py @@ -30,8 +30,8 @@ from datetime import timedelta from apify_client._literals import GeneralAccess - from apify_client._types import Timeout from apify_client.http_clients import HttpResponse + from apify_client.types import Timeout def _parse_get_record_response(response: HttpResponse) -> Any: diff --git a/src/apify_client/_resource_clients/key_value_store_collection.py b/src/apify_client/_resource_clients/key_value_store_collection.py index b4bf506d8..0fa0bb32f 100644 --- a/src/apify_client/_resource_clients/key_value_store_collection.py +++ b/src/apify_client/_resource_clients/key_value_store_collection.py @@ -16,7 +16,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._literals import StorageOwnership - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/log.py b/src/apify_client/_resource_clients/log.py index 18f9636bb..723b0312e 100644 --- a/src/apify_client/_resource_clients/log.py +++ b/src/apify_client/_resource_clients/log.py @@ -11,8 +11,8 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator - from apify_client._types import Timeout from apify_client.http_clients import HttpResponse + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/request_queue.py b/src/apify_client/_resource_clients/request_queue.py index 8bf31fb6e..70613d0b0 100644 --- a/src/apify_client/_resource_clients/request_queue.py +++ b/src/apify_client/_resource_clients/request_queue.py @@ -46,7 +46,7 @@ from apify_client._literals import GeneralAccess from apify_client._typeddicts import RequestDict, RequestDraftDeleteDict, RequestDraftDict - from apify_client._types import Timeout + from apify_client.types import Timeout _RQ_MAX_REQUESTS_PER_BATCH = 25 _MAX_PAYLOAD_SIZE_BYTES = 9 * 1024 * 1024 # 9 MB diff --git a/src/apify_client/_resource_clients/request_queue_collection.py b/src/apify_client/_resource_clients/request_queue_collection.py index 3239e30e6..c358e7131 100644 --- a/src/apify_client/_resource_clients/request_queue_collection.py +++ b/src/apify_client/_resource_clients/request_queue_collection.py @@ -17,7 +17,7 @@ from apify_client._literals import StorageOwnership from apify_client._models import RequestQueueShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/run.py b/src/apify_client/_resource_clients/run.py index ec0c0e8d8..fa1e8977d 100644 --- a/src/apify_client/_resource_clients/run.py +++ b/src/apify_client/_resource_clients/run.py @@ -30,7 +30,7 @@ RequestQueueClient, RequestQueueClientAsync, ) - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/run_collection.py b/src/apify_client/_resource_clients/run_collection.py index 21b7d1869..8b9edd873 100644 --- a/src/apify_client/_resource_clients/run_collection.py +++ b/src/apify_client/_resource_clients/run_collection.py @@ -13,7 +13,7 @@ from apify_client._literals import ActorJobStatus from apify_client._models import RunShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/schedule.py b/src/apify_client/_resource_clients/schedule.py index 8eee629ba..b6d2b3e23 100644 --- a/src/apify_client/_resource_clients/schedule.py +++ b/src/apify_client/_resource_clients/schedule.py @@ -14,7 +14,7 @@ from apify_client._utils import response_to_dict if TYPE_CHECKING: - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/schedule_collection.py b/src/apify_client/_resource_clients/schedule_collection.py index 138246e56..0e3bfa206 100644 --- a/src/apify_client/_resource_clients/schedule_collection.py +++ b/src/apify_client/_resource_clients/schedule_collection.py @@ -17,7 +17,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import ScheduleShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/store_collection.py b/src/apify_client/_resource_clients/store_collection.py index f1990ee12..3cff28e8b 100644 --- a/src/apify_client/_resource_clients/store_collection.py +++ b/src/apify_client/_resource_clients/store_collection.py @@ -11,7 +11,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import StoreListActor - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/task.py b/src/apify_client/_resource_clients/task.py index 819bc4649..0492e9813 100644 --- a/src/apify_client/_resource_clients/task.py +++ b/src/apify_client/_resource_clients/task.py @@ -29,7 +29,7 @@ WebhookCollectionClientAsync, ) from apify_client._typeddicts import TaskInputDict - from apify_client._types import Timeout, WebhooksList + from apify_client.types import Timeout, WebhooksList @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/task_collection.py b/src/apify_client/_resource_clients/task_collection.py index 04b6223d9..22075129b 100644 --- a/src/apify_client/_resource_clients/task_collection.py +++ b/src/apify_client/_resource_clients/task_collection.py @@ -23,7 +23,7 @@ from apify_client._models import TaskShort from apify_client._typeddicts import TaskInputDict - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/user.py b/src/apify_client/_resource_clients/user.py index 6703000f8..26a18acd8 100644 --- a/src/apify_client/_resource_clients/user.py +++ b/src/apify_client/_resource_clients/user.py @@ -19,7 +19,7 @@ from apify_client._utils import response_to_dict if TYPE_CHECKING: - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook.py b/src/apify_client/_resource_clients/webhook.py index 10b6a14b6..439ba34c3 100644 --- a/src/apify_client/_resource_clients/webhook.py +++ b/src/apify_client/_resource_clients/webhook.py @@ -19,7 +19,7 @@ if TYPE_CHECKING: from apify_client._literals import WebhookEventType from apify_client._resource_clients import WebhookDispatchCollectionClient, WebhookDispatchCollectionClientAsync - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook_collection.py b/src/apify_client/_resource_clients/webhook_collection.py index 4c7b3cf7c..d7fbf5174 100644 --- a/src/apify_client/_resource_clients/webhook_collection.py +++ b/src/apify_client/_resource_clients/webhook_collection.py @@ -18,7 +18,7 @@ from apify_client._literals import WebhookEventType from apify_client._models import Webhook, WebhookShort - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook_dispatch.py b/src/apify_client/_resource_clients/webhook_dispatch.py index c94e965e4..a3ed7c862 100644 --- a/src/apify_client/_resource_clients/webhook_dispatch.py +++ b/src/apify_client/_resource_clients/webhook_dispatch.py @@ -7,7 +7,7 @@ from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync if TYPE_CHECKING: - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_resource_clients/webhook_dispatch_collection.py b/src/apify_client/_resource_clients/webhook_dispatch_collection.py index 2682ac472..805ea5deb 100644 --- a/src/apify_client/_resource_clients/webhook_dispatch_collection.py +++ b/src/apify_client/_resource_clients/webhook_dispatch_collection.py @@ -11,7 +11,7 @@ from collections.abc import AsyncIterator, Iterator from apify_client._models import WebhookDispatch - from apify_client._types import Timeout + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_types.py b/src/apify_client/_types.py deleted file mode 100644 index 14bc9b513..000000000 --- a/src/apify_client/_types.py +++ /dev/null @@ -1,38 +0,0 @@ -from __future__ import annotations - -from datetime import timedelta -from typing import Literal - -from apify_client._models import WebhookCreate, WebhookRepresentation -from apify_client._typeddicts import WebhookCreateDict, WebhookRepresentationDict - -WebhooksList = ( - list[WebhookCreate] | list[WebhookCreateDict] | list[WebhookRepresentation] | list[WebhookRepresentationDict] -) -"""Type for the `webhooks` parameter on resource-client `start`/`call` methods and `from_webhooks`. - -`WebhookRepresentation` / `WebhookRepresentationDict` are the minimal ad-hoc webhook shape (only -`event_types` and `request_url` required). `WebhookCreate` / `WebhookCreateDict` are accepted so a -persistent-webhook definition can be reused; their fields not relevant to ad-hoc webhooks (e.g. -`condition`) are ignored at runtime. -""" - -Timeout = timedelta | Literal['no_timeout', 'short', 'medium', 'long'] -"""Type for the `timeout` parameter on resource client methods. - -`'short'`, `'medium'`, and `'long'` are tier literals resolved by the HTTP client to configured values. -A `timedelta` overrides the timeout for this call, and `'no_timeout'` disables the timeout entirely. -""" - -JsonSerializable = dict[str, 'JsonSerializable'] | list['JsonSerializable'] | str | int | float | bool | None -"""Recursive type for JSON-serializable values - primitives plus objects and arrays with JSON-serializable contents. - -Based on the definition discussed in https://github.com/python/typing/issues/182. -""" - - -__all__ = [ - 'JsonSerializable', - 'Timeout', - 'WebhooksList', -] diff --git a/src/apify_client/_utils.py b/src/apify_client/_utils.py index 6e3c5c7e2..e488b5bea 100644 --- a/src/apify_client/_utils.py +++ b/src/apify_client/_utils.py @@ -20,9 +20,9 @@ if TYPE_CHECKING: from datetime import timedelta - from apify_client._types import WebhooksList from apify_client.errors import ApifyApiError from apify_client.http_clients import HttpResponse + from apify_client.types import WebhooksList T = TypeVar('T') diff --git a/src/apify_client/http_clients/_base.py b/src/apify_client/http_clients/_base.py index 2abe8ab54..6da96dbf9 100644 --- a/src/apify_client/http_clients/_base.py +++ b/src/apify_client/http_clients/_base.py @@ -25,7 +25,7 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator, Mapping - from apify_client._types import JsonSerializable, Timeout + from apify_client.types import JsonSerializable, Timeout @docs_group('HTTP clients') diff --git a/src/apify_client/http_clients/_impit.py b/src/apify_client/http_clients/_impit.py index ef7a0b8fd..c137dde77 100644 --- a/src/apify_client/http_clients/_impit.py +++ b/src/apify_client/http_clients/_impit.py @@ -28,8 +28,8 @@ from collections.abc import Awaitable, Callable from apify_client._statistics import ClientStatistics - from apify_client._types import JsonSerializable, Timeout from apify_client.http_clients._base import HttpResponse + from apify_client.types import JsonSerializable, Timeout T = TypeVar('T') diff --git a/src/apify_client/types.py b/src/apify_client/types.py index cbedc5123..c206f00a6 100644 --- a/src/apify_client/types.py +++ b/src/apify_client/types.py @@ -1,7 +1,37 @@ from __future__ import annotations -from apify_client._types import Timeout +from datetime import timedelta +from typing import Literal + +from apify_client._models import WebhookCreate, WebhookRepresentation +from apify_client._typeddicts import WebhookCreateDict, WebhookRepresentationDict + +WebhooksList = ( + list[WebhookCreate] | list[WebhookCreateDict] | list[WebhookRepresentation] | list[WebhookRepresentationDict] +) +"""Type for the `webhooks` parameter on resource-client `start`/`call` methods and `from_webhooks`. + +`WebhookRepresentation` / `WebhookRepresentationDict` are the minimal ad-hoc webhook shape (only +`event_types` and `request_url` required). `WebhookCreate` / `WebhookCreateDict` are accepted so a +persistent-webhook definition can be reused; their fields not relevant to ad-hoc webhooks (e.g. +`condition`) are ignored at runtime. +""" + +Timeout = timedelta | Literal['no_timeout', 'short', 'medium', 'long'] +"""Type for the `timeout` parameter on resource client methods. + +`'short'`, `'medium'`, and `'long'` are tier literals resolved by the HTTP client to configured values. +A `timedelta` overrides the timeout for this call, and `'no_timeout'` disables the timeout entirely. +""" + +JsonSerializable = dict[str, 'JsonSerializable'] | list['JsonSerializable'] | str | int | float | bool | None +"""Recursive type for JSON-serializable values - primitives plus objects and arrays with JSON-serializable contents. + +Based on the definition discussed in https://github.com/python/typing/issues/182. +""" __all__ = [ + 'JsonSerializable', 'Timeout', + 'WebhooksList', ] diff --git a/tests/unit/test_pluggable_http_client.py b/tests/unit/test_pluggable_http_client.py index e075bf58e..e5eab9e8b 100644 --- a/tests/unit/test_pluggable_http_client.py +++ b/tests/unit/test_pluggable_http_client.py @@ -21,7 +21,7 @@ from pytest_httpserver import HTTPServer - from apify_client._types import Timeout + from apify_client.types import Timeout # -- Test response and client implementations -- From 210c8409221bf7d31daacf29e09d7e845e1c0879 Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Mon, 18 May 2026 14:03:45 +0200 Subject: [PATCH 4/4] types and _internal_types --- docs/04_upgrading/upgrading_to_v3.mdx | 2 +- src/apify_client/_internal_types.py | 19 ++++++++++++++++ src/apify_client/_resource_clients/actor.py | 3 ++- src/apify_client/_resource_clients/dataset.py | 3 ++- src/apify_client/_resource_clients/task.py | 3 ++- src/apify_client/_utils.py | 2 +- src/apify_client/http_clients/_base.py | 3 ++- src/apify_client/http_clients/_impit.py | 3 ++- src/apify_client/types.py | 22 ------------------- 9 files changed, 31 insertions(+), 29 deletions(-) diff --git a/docs/04_upgrading/upgrading_to_v3.mdx b/docs/04_upgrading/upgrading_to_v3.mdx index 255718c5f..d5efd17a6 100644 --- a/docs/04_upgrading/upgrading_to_v3.mdx +++ b/docs/04_upgrading/upgrading_to_v3.mdx @@ -126,7 +126,7 @@ client = ApifyClient.with_custom_http_client( ) ``` -The response must satisfy the `HttpResponse` protocol (properties: `status_code`, `text`, `content`, `headers`; methods: `json()`, `read()`, `close()`, `iter_bytes()`). Many popular libraries like `httpx` already satisfy this protocol out of the box. +The response must satisfy the `HttpResponse` protocol (properties: `status_code`, `text`, `content`, `headers`; sync methods: `json()`, `read()`, `close()`, `iter_bytes()`; async methods: `aread()`, `aclose()`, `aiter_bytes()`). Many popular libraries like `httpx` already satisfy this protocol out of the box. The HTTP base classes, the `HttpResponse` protocol, and the default `ImpitHttpClient` / `ImpitHttpClientAsync` implementations live in the `apify_client.http_clients` submodule. The `Timeout` alias used on the `call()` signature lives in `apify_client.types`. diff --git a/src/apify_client/_internal_types.py b/src/apify_client/_internal_types.py index 84facd8f9..a1ebd8476 100644 --- a/src/apify_client/_internal_types.py +++ b/src/apify_client/_internal_types.py @@ -2,5 +2,24 @@ from typing import Literal +from apify_client._models import WebhookCreate, WebhookRepresentation +from apify_client._typeddicts import WebhookCreateDict, WebhookRepresentationDict + +WebhooksList = ( + list[WebhookCreate] | list[WebhookCreateDict] | list[WebhookRepresentation] | list[WebhookRepresentationDict] +) +"""Type for the `webhooks` parameter on resource-client `start`/`call` methods and `from_webhooks`. + +`WebhookRepresentation` / `WebhookRepresentationDict` are the minimal ad-hoc webhook shape (only `event_types` and +`request_url` required). `WebhookCreate` / `WebhookCreateDict` are accepted so persistent-webhook definition can +be reused; their fields not relevant to ad-hoc webhooks (e.g. `condition`) are ignored at runtime. +""" + TerminalActorJobStatus = Literal['SUCCEEDED', 'FAILED', 'TIMED-OUT', 'ABORTED'] """Subset of `ActorJobStatus` values that indicate the job has finished and will not change again.""" + +JsonSerializable = dict[str, 'JsonSerializable'] | list['JsonSerializable'] | str | int | float | bool | None +"""Recursive type for JSON-serializable values - primitives plus objects and arrays with JSON-serializable contents. + +Based on the definition discussed in https://github.com/python/typing/issues/182. +""" diff --git a/src/apify_client/_resource_clients/actor.py b/src/apify_client/_resource_clients/actor.py index 150c70385..af2e123c0 100644 --- a/src/apify_client/_resource_clients/actor.py +++ b/src/apify_client/_resource_clients/actor.py @@ -35,6 +35,7 @@ from decimal import Decimal from logging import Logger + from apify_client._internal_types import WebhooksList from apify_client._literals import ActorJobStatus, ActorPermissionLevel, RunOrigin from apify_client._resource_clients import ( ActorVersionClient, @@ -52,7 +53,7 @@ WebhookCollectionClient, WebhookCollectionClientAsync, ) - from apify_client.types import Timeout, WebhooksList + from apify_client.types import Timeout _PricingInfo = ( PayPerEventActorPricingInfo diff --git a/src/apify_client/_resource_clients/dataset.py b/src/apify_client/_resource_clients/dataset.py index faefdaf13..2db782185 100644 --- a/src/apify_client/_resource_clients/dataset.py +++ b/src/apify_client/_resource_clients/dataset.py @@ -20,9 +20,10 @@ from collections.abc import AsyncIterator, Iterator from datetime import timedelta + from apify_client._internal_types import JsonSerializable from apify_client._literals import GeneralAccess from apify_client.http_clients import HttpResponse - from apify_client.types import JsonSerializable, Timeout + from apify_client.types import Timeout @docs_group('Other') diff --git a/src/apify_client/_resource_clients/task.py b/src/apify_client/_resource_clients/task.py index 0492e9813..5ed02f0ab 100644 --- a/src/apify_client/_resource_clients/task.py +++ b/src/apify_client/_resource_clients/task.py @@ -19,6 +19,7 @@ if TYPE_CHECKING: from datetime import timedelta + from apify_client._internal_types import WebhooksList from apify_client._literals import ActorJobStatus, RunOrigin from apify_client._resource_clients import ( RunClient, @@ -29,7 +30,7 @@ WebhookCollectionClientAsync, ) from apify_client._typeddicts import TaskInputDict - from apify_client.types import Timeout, WebhooksList + from apify_client.types import Timeout @docs_group('Resource clients') diff --git a/src/apify_client/_utils.py b/src/apify_client/_utils.py index e488b5bea..b696524fa 100644 --- a/src/apify_client/_utils.py +++ b/src/apify_client/_utils.py @@ -20,9 +20,9 @@ if TYPE_CHECKING: from datetime import timedelta + from apify_client._internal_types import WebhooksList from apify_client.errors import ApifyApiError from apify_client.http_clients import HttpResponse - from apify_client.types import WebhooksList T = TypeVar('T') diff --git a/src/apify_client/http_clients/_base.py b/src/apify_client/http_clients/_base.py index 6da96dbf9..ed2ff85cc 100644 --- a/src/apify_client/http_clients/_base.py +++ b/src/apify_client/http_clients/_base.py @@ -25,7 +25,8 @@ if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator, Mapping - from apify_client.types import JsonSerializable, Timeout + from apify_client._internal_types import JsonSerializable + from apify_client.types import Timeout @docs_group('HTTP clients') diff --git a/src/apify_client/http_clients/_impit.py b/src/apify_client/http_clients/_impit.py index c137dde77..8c36b738a 100644 --- a/src/apify_client/http_clients/_impit.py +++ b/src/apify_client/http_clients/_impit.py @@ -27,9 +27,10 @@ if TYPE_CHECKING: from collections.abc import Awaitable, Callable + from apify_client._internal_types import JsonSerializable from apify_client._statistics import ClientStatistics from apify_client.http_clients._base import HttpResponse - from apify_client.types import JsonSerializable, Timeout + from apify_client.types import Timeout T = TypeVar('T') diff --git a/src/apify_client/types.py b/src/apify_client/types.py index c206f00a6..fa0503153 100644 --- a/src/apify_client/types.py +++ b/src/apify_client/types.py @@ -3,20 +3,6 @@ from datetime import timedelta from typing import Literal -from apify_client._models import WebhookCreate, WebhookRepresentation -from apify_client._typeddicts import WebhookCreateDict, WebhookRepresentationDict - -WebhooksList = ( - list[WebhookCreate] | list[WebhookCreateDict] | list[WebhookRepresentation] | list[WebhookRepresentationDict] -) -"""Type for the `webhooks` parameter on resource-client `start`/`call` methods and `from_webhooks`. - -`WebhookRepresentation` / `WebhookRepresentationDict` are the minimal ad-hoc webhook shape (only -`event_types` and `request_url` required). `WebhookCreate` / `WebhookCreateDict` are accepted so a -persistent-webhook definition can be reused; their fields not relevant to ad-hoc webhooks (e.g. -`condition`) are ignored at runtime. -""" - Timeout = timedelta | Literal['no_timeout', 'short', 'medium', 'long'] """Type for the `timeout` parameter on resource client methods. @@ -24,14 +10,6 @@ A `timedelta` overrides the timeout for this call, and `'no_timeout'` disables the timeout entirely. """ -JsonSerializable = dict[str, 'JsonSerializable'] | list['JsonSerializable'] | str | int | float | bool | None -"""Recursive type for JSON-serializable values - primitives plus objects and arrays with JSON-serializable contents. - -Based on the definition discussed in https://github.com/python/typing/issues/182. -""" - __all__ = [ - 'JsonSerializable', 'Timeout', - 'WebhooksList', ]