refactor: Consolidate public interface for v3

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,

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'
 

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'
 

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'
 

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'
 

docs/04_upgrading/upgrading_to_v3.mdx

@@ -112,7 +112,8 @@ The HTTP layer is now abstracted behind <ApiLink to="class/HttpClient">`HttpClie
 To use a custom HTTP client, implement the `call()` method and pass the instance via the <ApiLink to="class/ApifyClient#with_custom_http_client">`ApifyClient.with_custom_http_client()`</ApiLink> 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 <ApiLink to="class/HttpResponse">`HttpResponse`</ApiLink> 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

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__',
 ]

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:

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):

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

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')

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')

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')

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])
 

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])

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')

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')

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')

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')

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:

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')

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')

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

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')

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')

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')

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')

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')

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')

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')

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')

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')

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')