scrapely-client-python 3.1.3__py3-none-any.whl

scrapely_client/_resource_clients/run_collection.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from scrapely_client._docs import docs_group
+from scrapely_client._models import ListOfRuns, ListOfRunsResponse
+from scrapely_client._pagination import get_items_iterator, get_items_iterator_async
+from scrapely_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterator
+    from datetime import datetime
+
+    from scrapely_client._literals import ActorJobStatus
+    from scrapely_client._models import RunShort
+    from scrapely_client.types import Timeout
+
+
+@docs_group('Resource clients')
+class RunCollectionClient(ResourceClient):
+    """Sub-client for the Actor run collection.
+
+    Provides methods to manage Actor runs, e.g. list them. Obtain an instance via an appropriate method on the
+    `ApifyClient` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_path: str = 'actor-runs',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        status: ActorJobStatus | list[ActorJobStatus] | None = None,  # ty: ignore[invalid-type-form]
+        started_before: str | datetime | None = None,
+        started_after: str | datetime | None = None,
+        timeout: Timeout = 'medium',
+    ) -> ListOfRuns:
+        """List all Actor runs.
+
+        List all Actor runs, either of a single Actor, or all user's Actors, depending on where this client
+        was initialized from.
+
+
+        Args:
+            limit: How many runs to retrieve.
+            offset: What run to include as first when retrieving the list.
+            desc: Whether to sort the runs in descending order based on their start date.
+            status: Retrieve only runs with the provided statuses.
+            started_before: Only return runs started before this date (inclusive).
+            started_after: Only return runs started after this date (inclusive).
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved Actor runs.
+        """
+        status_param = list(status) if isinstance(status, list) else status
+
+        result = self._list(
+            timeout=timeout,
+            limit=limit,
+            offset=offset,
+            desc=desc,
+            status=status_param,
+            startedBefore=started_before,
+            startedAfter=started_after,
+        )
+        return ListOfRunsResponse.model_validate(result).data
+
+    def iterate(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        status: ActorJobStatus | list[ActorJobStatus] | None = None,  # ty: ignore[invalid-type-form]
+        started_before: str | datetime | None = None,
+        started_after: str | datetime | None = None,
+        timeout: Timeout = 'medium',
+    ) -> Iterator[RunShort]:
+        """Iterate over all Actor runs.
+
+        Simple `list` does only one API call, possibly not listing all items matching the criteria. This method
+        returns an iterator that is capable of making multiple API calls to retrieve all items matching the criteria.
+
+
+        Args:
+            limit: How many runs to retrieve.
+            offset: What run to include as first when retrieving the list.
+            desc: Whether to sort the runs in descending order based on their start date.
+            status: Retrieve only runs with the provided statuses.
+            started_before: Only return runs started before this date (inclusive).
+            started_after: Only return runs started after this date (inclusive).
+            timeout: Timeout for the API HTTP request.
+
+        Yields:
+            The Actor runs matching the specified filters.
+        """
+
+        def _callback(*, limit: int | None = None, offset: int | None = None) -> ListOfRuns:
+            return self.list(
+                limit=limit,
+                offset=offset,
+                desc=desc,
+                status=status,
+                started_before=started_before,
+                started_after=started_after,
+                timeout=timeout,
+            )
+
+        return get_items_iterator(_callback, limit=limit, offset=offset)
+
+
+@docs_group('Resource clients')
+class RunCollectionClientAsync(ResourceClientAsync):
+    """Sub-client for the Actor run collection.
+
+    Provides methods to manage Actor runs, e.g. list them. Obtain an instance via an appropriate method on the
+    `ApifyClientAsync` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_path: str = 'actor-runs',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    async def list(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        status: ActorJobStatus | list[ActorJobStatus] | None = None,  # ty: ignore[invalid-type-form]
+        started_before: str | datetime | None = None,
+        started_after: str | datetime | None = None,
+        timeout: Timeout = 'medium',
+    ) -> ListOfRuns:
+        """List all Actor runs.
+
+        List all Actor runs, either of a single Actor, or all user's Actors, depending on where this client
+        was initialized from.
+
+
+        Args:
+            limit: How many runs to retrieve.
+            offset: What run to include as first when retrieving the list.
+            desc: Whether to sort the runs in descending order based on their start date.
+            status: Retrieve only runs with the provided statuses.
+            started_before: Only return runs started before this date (inclusive).
+            started_after: Only return runs started after this date (inclusive).
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved Actor runs.
+        """
+        status_param = list(status) if isinstance(status, list) else status
+
+        result = await self._list(
+            timeout=timeout,
+            limit=limit,
+            offset=offset,
+            desc=desc,
+            status=status_param,
+            startedBefore=started_before,
+            startedAfter=started_after,
+        )
+        return ListOfRunsResponse.model_validate(result).data
+
+    def iterate(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        status: ActorJobStatus | list[ActorJobStatus] | None = None,  # ty: ignore[invalid-type-form]
+        started_before: str | datetime | None = None,
+        started_after: str | datetime | None = None,
+        timeout: Timeout = 'medium',
+    ) -> AsyncIterator[RunShort]:
+        """Iterate over all Actor runs.
+
+        Simple `list` does only one API call, possibly not listing all items matching the criteria. This method
+        returns an iterator that is capable of making multiple API calls to retrieve all items matching the criteria.
+
+
+        Args:
+            limit: How many runs to retrieve.
+            offset: What run to include as first when retrieving the list.
+            desc: Whether to sort the runs in descending order based on their start date.
+            status: Retrieve only runs with the provided statuses.
+            started_before: Only return runs started before this date (inclusive).
+            started_after: Only return runs started after this date (inclusive).
+            timeout: Timeout for the API HTTP request.
+
+        Yields:
+            The Actor runs matching the specified filters.
+        """
+
+        async def _callback(*, limit: int | None = None, offset: int | None = None) -> ListOfRuns:
+            return await self.list(
+                limit=limit,
+                offset=offset,
+                desc=desc,
+                status=status,
+                started_before=started_before,
+                started_after=started_after,
+                timeout=timeout,
+            )
+
+        return get_items_iterator_async(_callback, limit=limit, offset=offset)

scrapely_client/_resource_clients/schedule.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from scrapely_client._docs import docs_group
+from scrapely_client._models import (
+    Schedule,
+    ScheduleCreate,
+    ScheduleInvoked,
+    ScheduleLogResponse,
+    ScheduleResponse,
+)
+from scrapely_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
+from scrapely_client._utils.http import response_to_dict
+
+if TYPE_CHECKING:
+    from scrapely_client.types import Timeout
+
+
+@docs_group('Resource clients')
+class ScheduleClient(ResourceClient):
+    """Sub-client for managing a specific schedule.
+
+    Provides methods to manage a specific schedule, e.g. get, update, or delete it. Obtain an instance via an
+    appropriate method on the `ApifyClient` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_id: str,
+        resource_path: str = 'schedules',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_id=resource_id,
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    def get(self, *, timeout: Timeout = 'short') -> Schedule | None:
+        """Return information about the schedule.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved schedule.
+        """
+        result = self._get(timeout=timeout)
+        if result is None:
+            return None
+        return ScheduleResponse.model_validate(result).data
+
+    def update(
+        self,
+        *,
+        cron_expression: str | None = None,
+        is_enabled: bool | None = None,
+        is_exclusive: bool | None = None,
+        name: str | None = None,
+        actions: list[dict[str, Any]] | None = None,
+        description: str | None = None,
+        timezone: str | None = None,
+        title: str | None = None,
+        timeout: Timeout = 'short',
+    ) -> Schedule:
+        """Update the schedule with specified fields.
+
+
+        Args:
+            cron_expression: The cron expression used by this schedule.
+            is_enabled: True if the schedule should be enabled.
+            is_exclusive: When set to true, don't start Actor or Actor task if it's still running from the previous
+                schedule.
+            name: The name of the schedule to create.
+            actions: Actors or tasks that should be run on this schedule. See the API documentation for exact structure.
+            description: Description of this schedule.
+            timezone: Timezone in which your cron expression runs (TZ database name from
+                https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+            title: A human-friendly equivalent of the name.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The updated schedule.
+        """
+        schedule_fields = ScheduleCreate(
+            cron_expression=cron_expression,
+            is_enabled=is_enabled,
+            is_exclusive=is_exclusive,
+            name=name,
+            actions=actions or None,
+            description=description,
+            timezone=timezone,
+            title=title,
+        )
+        result = self._update(timeout=timeout, **schedule_fields.model_dump(by_alias=True, exclude_none=True))
+        return ScheduleResponse.model_validate(result).data
+
+    def delete(self, *, timeout: Timeout = 'short') -> None:
+        """Delete the schedule.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+        """
+        self._delete(timeout=timeout)
+
+    def get_log(self, *, timeout: Timeout = 'medium') -> list[ScheduleInvoked]:
+        """Return log for the given schedule.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            Retrieved log of the given schedule.
+
+        Raises:
+            NotFoundError: If the schedule does not exist.
+        """
+        response = self._http_client.call(
+            url=self._build_url('log'),
+            method='GET',
+            params=self._build_params(),
+            timeout=timeout,
+        )
+        result = response_to_dict(response)
+        return ScheduleLogResponse.model_validate(result).data
+
+
+@docs_group('Resource clients')
+class ScheduleClientAsync(ResourceClientAsync):
+    """Sub-client for managing a specific schedule.
+
+    Provides methods to manage a specific schedule, e.g. get, update, or delete it. Obtain an instance via an
+    appropriate method on the `ApifyClientAsync` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_id: str,
+        resource_path: str = 'schedules',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_id=resource_id,
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    async def get(self, *, timeout: Timeout = 'short') -> Schedule | None:
+        """Return information about the schedule.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved schedule.
+        """
+        result = await self._get(timeout=timeout)
+        if result is None:
+            return None
+        return ScheduleResponse.model_validate(result).data
+
+    async def update(
+        self,
+        *,
+        cron_expression: str | None = None,
+        is_enabled: bool | None = None,
+        is_exclusive: bool | None = None,
+        name: str | None = None,
+        actions: list[dict[str, Any]] | None = None,
+        description: str | None = None,
+        timezone: str | None = None,
+        title: str | None = None,
+        timeout: Timeout = 'short',
+    ) -> Schedule:
+        """Update the schedule with specified fields.
+
+
+        Args:
+            cron_expression: The cron expression used by this schedule.
+            is_enabled: True if the schedule should be enabled.
+            is_exclusive: When set to true, don't start Actor or Actor task if it's still running from the previous
+                schedule.
+            name: The name of the schedule to create.
+            actions: Actors or tasks that should be run on this schedule. See the API documentation for exact structure.
+            description: Description of this schedule.
+            timezone: Timezone in which your cron expression runs (TZ database name from
+                https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+            title: A human-friendly equivalent of the name.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The updated schedule.
+        """
+        schedule_fields = ScheduleCreate(
+            cron_expression=cron_expression,
+            is_enabled=is_enabled,
+            is_exclusive=is_exclusive,
+            name=name,
+            actions=actions or None,
+            description=description,
+            timezone=timezone,
+            title=title,
+        )
+        result = await self._update(timeout=timeout, **schedule_fields.model_dump(by_alias=True, exclude_none=True))
+        return ScheduleResponse.model_validate(result).data
+
+    async def delete(self, *, timeout: Timeout = 'short') -> None:
+        """Delete the schedule.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+        """
+        await self._delete(timeout=timeout)
+
+    async def get_log(self, *, timeout: Timeout = 'medium') -> list[ScheduleInvoked]:
+        """Return log for the given schedule.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            Retrieved log of the given schedule.
+
+        Raises:
+            NotFoundError: If the schedule does not exist.
+        """
+        response = await self._http_client.call(
+            url=self._build_url('log'),
+            method='GET',
+            params=self._build_params(),
+            timeout=timeout,
+        )
+        result = response_to_dict(response)
+        return ScheduleLogResponse.model_validate(result).data