Refactoring p1

Author: vdusek

src/apify_client/__init__.py

@@ -1,6 +1,6 @@
 from importlib import metadata
 
-from ._client import ApifyClient, ApifyClientAsync
+from ._apify_client import ApifyClient, ApifyClientAsync
 
 __version__ = metadata.version('apify-client')
 

src/apify_client/_client.py src/apify_client/_apify_client.pysrc/apify_client/_client.py renamed to src/apify_client/_apify_client.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from apify_client._http_client import HTTPClient, HTTPClientAsync
+from apify_client._client_config import ClientConfig
+from apify_client._http_client import HttpClient, HttpClientAsync
 from apify_client._resource_clients import (
     ActorClient,
     ActorClientAsync,
@@ -49,61 +50,12 @@
     WebhookDispatchCollectionClient,
     WebhookDispatchCollectionClientAsync,
 )
-from apify_client._types import Statistics
+from apify_client._statistics import Statistics
 
-DEFAULT_API_URL = 'https://api.apify.com'
-DEFAULT_TIMEOUT = 360
-API_VERSION = 'v2'
 
-
-class _BaseApifyClient:
-    http_client: HTTPClient | HTTPClientAsync
-
-    def __init__(
-        self,
-        token: str | None = None,
-        *,
-        api_url: str | None = None,
-        api_public_url: str | None = None,
-        max_retries: int | None = 8,
-        min_delay_between_retries_millis: int | None = 500,
-        timeout_secs: int | None = DEFAULT_TIMEOUT,
-    ) -> None:
-        """Initialize a new instance.
-
-        Args:
-            token: The Apify API token.
-            api_url: The URL of the Apify API server to which to connect. Defaults to https://api.apify.com. It can
-                be an internal URL that is not globally accessible, in such case `api_public_url` should be set as well.
-            api_public_url: The globally accessible URL of the Apify API server. It should be set only if the `api_url`
-                is an internal URL that is not globally accessible.
-            max_retries: How many times to retry a failed request at most.
-            min_delay_between_retries_millis: How long will the client wait between retrying requests
-                (increases exponentially from this value).
-            timeout_secs: The socket timeout of the HTTP requests sent to the Apify API.
-        """
-        self.token = token
-        api_url = (api_url or DEFAULT_API_URL).rstrip('/')
-        self.base_url = f'{api_url}/{API_VERSION}'
-        api_public_url = (api_public_url or DEFAULT_API_URL).rstrip('/')
-        self.public_base_url = f'{api_public_url}/{API_VERSION}'
-        self.max_retries = max_retries or 8
-        self.min_delay_between_retries_millis = min_delay_between_retries_millis or 500
-        self.timeout_secs = timeout_secs or DEFAULT_TIMEOUT
-
-    def _options(self) -> dict:
-        return {
-            'root_client': self,
-            'base_url': self.base_url,
-            'http_client': self.http_client,
-        }
-
-
-class ApifyClient(_BaseApifyClient):
+class ApifyClient:
     """The Apify API client."""
 
-    http_client: HTTPClient
-
     def __init__(
         self,
         token: str | None = None,
@@ -112,7 +64,7 @@ def __init__(
         api_public_url: str | None = None,
         max_retries: int | None = 8,
         min_delay_between_retries_millis: int | None = 500,
-        timeout_secs: int | None = DEFAULT_TIMEOUT,
+        timeout_secs: int | None = 360,
     ) -> None:
         """Initialize a new instance.
 
@@ -127,8 +79,8 @@ def __init__(
                 (increases exponentially from this value).
             timeout_secs: The socket timeout of the HTTP requests sent to the Apify API.
         """
-        super().__init__(
-            token,
+        self._config = ClientConfig.from_user_params(
+            token=token,
             api_url=api_url,
             api_public_url=api_public_url,
             max_retries=max_retries,
@@ -137,21 +89,26 @@ def __init__(
         )
 
         self.stats = Statistics()
-        self.http_client = HTTPClient(
-            token=token,
-            max_retries=self.max_retries,
-            min_delay_between_retries_millis=self.min_delay_between_retries_millis,
-            timeout_secs=self.timeout_secs,
-            stats=self.stats,
-        )
+        self.http_client = HttpClient(config=self._config, stats=self.stats)
+
+    def _options(self) -> dict:
+        return {
+            'base_url': self._config.base_url,
+            'public_base_url': self._config.public_base_url,
+            'http_client': self.http_client,
+        }
 
     def actor(self, actor_id: str) -> ActorClient:
         """Retrieve the sub-client for manipulating a single Actor.
 
         Args:
             actor_id: ID of the Actor to be manipulated.
         """
-        return ActorClient(resource_id=actor_id, **self._options())
+        return ActorClient(
+            resource_id=actor_id,
+            resource_path='acts',
+            **self._options()
+        )
 
     def actors(self) -> ActorCollectionClient:
         """Retrieve the sub-client for manipulating Actors."""
@@ -287,11 +244,9 @@ def store(self) -> StoreCollectionClient:
         return StoreCollectionClient(**self._options())
 
 
-class ApifyClientAsync(_BaseApifyClient):
+class ApifyClientAsync:
     """The asynchronous version of the Apify API client."""
 
-    http_client: HTTPClientAsync
-
     def __init__(
         self,
         token: str | None = None,
@@ -300,7 +255,7 @@ def __init__(
         api_public_url: str | None = None,
         max_retries: int | None = 8,
         min_delay_between_retries_millis: int | None = 500,
-        timeout_secs: int | None = DEFAULT_TIMEOUT,
+        timeout_secs: int | None = 360,
     ) -> None:
         """Initialize a new instance.
 
@@ -315,8 +270,8 @@ def __init__(
                 (increases exponentially from this value).
             timeout_secs: The socket timeout of the HTTP requests sent to the Apify API.
         """
-        super().__init__(
-            token,
+        self._config = ClientConfig.from_user_params(
+            token=token,
             api_url=api_url,
             api_public_url=api_public_url,
             max_retries=max_retries,
@@ -325,13 +280,14 @@ def __init__(
         )
 
         self.stats = Statistics()
-        self.http_client = HTTPClientAsync(
-            token=token,
-            max_retries=self.max_retries,
-            min_delay_between_retries_millis=self.min_delay_between_retries_millis,
-            timeout_secs=self.timeout_secs,
-            stats=self.stats,
-        )
+        self.http_client = HttpClientAsync(config=self._config, stats=self.stats)
+
+    def _options(self) -> dict:
+        return {
+            'base_url': self._config.base_url,
+            'public_base_url': self._config.public_base_url,
+            'http_client': self.http_client,
+        }
 
     def actor(self, actor_id: str) -> ActorClientAsync:
         """Retrieve the sub-client for manipulating a single Actor.

src/apify_client/_client_config.py

@@ -0,0 +1,83 @@
+"""Client configuration module.
+
+This module provides the ClientConfig dataclass that encapsulates all
+configuration options for the Apify API client.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_API_URL = 'https://api.apify.com'
+DEFAULT_TIMEOUT = 360
+API_VERSION = 'v2'
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Immutable configuration for Apify HTTP client.
+
+    This dataclass holds all configuration options needed by the HTTP client
+    to communicate with the Apify API. It is created once by ApifyClient
+    and shared across all resource clients.
+
+    All fields are frozen (immutable) to prevent accidental modification
+    after initialization.
+    """
+
+    base_url: str
+    """Base URL of the Apify API (e.g., 'https://api.apify.com/v2')."""
+
+    public_base_url: str
+    """Public base URL for CDN access (e.g., 'https://cdn.apify.com/v2')."""
+
+    token: str | None = None
+    """Apify API token for authentication."""
+
+    max_retries: int = 8
+    """Maximum number of retries for failed requests."""
+
+    min_delay_between_retries_millis: int = 500
+    """Minimum delay between retries in milliseconds (increases exponentially)."""
+
+    timeout_secs: int = 360
+    """Request timeout in seconds."""
+
+    @classmethod
+    def from_user_params(
+        cls,
+        *,
+        token: str | None = None,
+        api_url: str | None = None,
+        api_public_url: str | None = None,
+        max_retries: int | None = 8,
+        min_delay_between_retries_millis: int | None = 500,
+        timeout_secs: int | None = 360,
+    ) -> ClientConfig:
+        """Create ClientConfig from user-provided parameters.
+
+        This factory method processes user input and creates a properly
+        formatted ClientConfig instance with sensible defaults.
+
+        Args:
+            token: Apify API token for authentication.
+            api_url: Base API URL (default: https://api.apify.com).
+            api_public_url: Public CDN URL (default: same as api_url).
+            max_retries: Maximum number of retries for failed requests (default: 8).
+            min_delay_between_retries_millis: Minimum delay between retries in ms (default: 500).
+            timeout_secs: Request timeout in seconds (default: 360).
+
+        Returns:
+            Immutable ClientConfig instance.
+        """
+        api_url = (api_url or DEFAULT_API_URL).rstrip('/')
+        api_public_url = (api_public_url or DEFAULT_API_URL).rstrip('/')
+
+        return cls(
+            base_url=f'{api_url}/{API_VERSION}',
+            public_base_url=f'{api_public_url}/{API_VERSION}',
+            token=token,
+            max_retries=max_retries or 8,
+            min_delay_between_retries_millis=min_delay_between_retries_millis or 500,
+            timeout_secs=timeout_secs or DEFAULT_TIMEOUT,
+        )

src/apify_client/_consts.py

@@ -0,0 +1,124 @@
+"""Constants and enums used by the Apify client."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ActorJobStatus(str, Enum):
+    """Available statuses for Actor jobs (runs or builds).
+
+    These statuses represent the lifecycle of an Actor execution,
+    from initialization to completion or termination.
+    """
+
+    READY = 'READY'
+    """Actor job has been initialized but not yet started."""
+
+    RUNNING = 'RUNNING'
+    """Actor job is currently executing."""
+
+    SUCCEEDED = 'SUCCEEDED'
+    """Actor job completed successfully without errors."""
+
+    FAILED = 'FAILED'
+    """Actor job or build failed due to an error or exception."""
+
+    TIMING_OUT = 'TIMING-OUT'
+    """Actor job is currently in the process of timing out."""
+
+    TIMED_OUT = 'TIMED-OUT'
+    """Actor job was terminated due to timeout."""
+
+    ABORTING = 'ABORTING'
+    """Actor job is currently being aborted by user request."""
+
+    ABORTED = 'ABORTED'
+    """Actor job was successfully aborted by user request."""
+
+    @property
+    def is_terminal(self: ActorJobStatus) -> bool:
+        """Whether this Actor job status is terminal."""
+        return self in (
+            ActorJobStatus.SUCCEEDED,
+            ActorJobStatus.FAILED,
+            ActorJobStatus.TIMED_OUT,
+            ActorJobStatus.ABORTED,
+        )
+
+
+class WebhookEventType(str, Enum):
+    """Event types that can trigger webhook notifications.
+
+    These events are sent to configured webhook URLs when specific
+    Actor run or build lifecycle events occur, enabling integration
+    with external systems and automated workflows.
+    """
+
+    ACTOR_RUN_CREATED = 'ACTOR.RUN.CREATED'
+    """Triggered when a new Actor run is created and initialized."""
+
+    ACTOR_RUN_SUCCEEDED = 'ACTOR.RUN.SUCCEEDED'
+    """Triggered when an Actor run completes successfully."""
+
+    ACTOR_RUN_FAILED = 'ACTOR.RUN.FAILED'
+    """Triggered when an Actor run fails due to an error."""
+
+    ACTOR_RUN_TIMED_OUT = 'ACTOR.RUN.TIMED_OUT'
+    """Triggered when an Actor run is terminated due to timeout."""
+
+    ACTOR_RUN_ABORTED = 'ACTOR.RUN.ABORTED'
+    """Triggered when an Actor run is manually aborted by user."""
+
+    ACTOR_RUN_RESURRECTED = 'ACTOR.RUN.RESURRECTED'
+    """Triggered when a previously failed Actor run is automatically resurrected."""
+
+    ACTOR_BUILD_CREATED = 'ACTOR.BUILD.CREATED'
+    """Triggered when a new Actor build process is initiated."""
+
+    ACTOR_BUILD_SUCCEEDED = 'ACTOR.BUILD.SUCCEEDED'
+    """Triggered when an Actor build completes successfully."""
+
+    ACTOR_BUILD_FAILED = 'ACTOR.BUILD.FAILED'
+    """Triggered when an Actor build fails due to compilation or setup errors."""
+
+    ACTOR_BUILD_TIMED_OUT = 'ACTOR.BUILD.TIMED_OUT'
+    """Triggered when an Actor build process exceeds the time limit."""
+
+    ACTOR_BUILD_ABORTED = 'ACTOR.BUILD.ABORTED'
+    """Triggered when an Actor build is manually cancelled by user."""
+
+
+class StorageGeneralAccess(str, Enum):
+    """Storage setting determining how others can access the storage.
+
+    This setting overrides the user setting of the storage owner.
+    """
+
+    FOLLOW_USER_SETTING = 'FOLLOW_USER_SETTING'
+    """Respect the user setting of the storage owner (default behavior)."""
+
+    RESTRICTED = 'RESTRICTED'
+    """Only signed-in users with explicit access can read this storage."""
+
+    ANYONE_WITH_ID_CAN_READ = 'ANYONE_WITH_ID_CAN_READ'
+    """Anyone with a link or the unique storage ID can read this storage."""
+
+    ANYONE_WITH_NAME_CAN_READ = 'ANYONE_WITH_NAME_CAN_READ'
+    """Anyone with a link, ID, or storage name can read this storage."""
+
+
+class RunGeneralAccess(str, Enum):
+    """Run setting determining how others can access the run.
+
+    This setting overrides the user setting of the run owner.
+    """
+
+    FOLLOW_USER_SETTING = 'FOLLOW_USER_SETTING'
+    """Respect the user setting of the storage owner (default behavior)."""
+
+    RESTRICTED = 'RESTRICTED'
+    """Only signed-in users with explicit access can read this run."""
+
+    ANYONE_WITH_ID_CAN_READ = 'ANYONE_WITH_ID_CAN_READ'
+    """Anyone with a link or the unique run ID can read this run."""