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

scrapely_client/_resource_clients/webhook.py

@@ -0,0 +1,292 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import AnyUrl
+
+from scrapely_client._docs import docs_group
+from scrapely_client._models import (
+    TestWebhookResponse,
+    Webhook,
+    WebhookCondition,
+    WebhookDispatch,
+    WebhookResponse,
+    WebhookUpdate,
+)
+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._literals import WebhookEventType
+    from scrapely_client._resource_clients import WebhookDispatchCollectionClient, WebhookDispatchCollectionClientAsync
+    from scrapely_client.types import Timeout
+
+
+@docs_group('Resource clients')
+class WebhookClient(ResourceClient):
+    """Sub-client for managing a specific webhook.
+
+    Provides methods to manage a specific webhook, 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 = 'webhooks',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_id=resource_id,
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    def get(self, *, timeout: Timeout = 'short') -> Webhook | None:
+        """Retrieve the webhook.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved webhook, or None if it does not exist.
+        """
+        result = self._get(timeout=timeout)
+        if result is None:
+            return None
+        return WebhookResponse.model_validate(result).data
+
+    def update(
+        self,
+        *,
+        event_types: list[WebhookEventType] | None = None,
+        request_url: str | None = None,
+        payload_template: str | None = None,
+        headers_template: str | None = None,
+        actor_id: str | None = None,
+        actor_task_id: str | None = None,
+        actor_run_id: str | None = None,
+        ignore_ssl_errors: bool | None = None,
+        do_not_retry: bool | None = None,
+        is_ad_hoc: bool | None = None,
+        timeout: Timeout = 'short',
+    ) -> Webhook:
+        """Update the webhook.
+
+
+        Args:
+            event_types: List of event types that should trigger the webhook. At least one is required.
+            request_url: URL that will be invoked once the webhook is triggered.
+            payload_template: Specification of the payload that will be sent to request_url.
+            headers_template: Headers that will be sent to the request_url.
+            actor_id: Id of the Actor whose runs should trigger the webhook.
+            actor_task_id: Id of the Actor task whose runs should trigger the webhook.
+            actor_run_id: Id of the Actor run which should trigger the webhook.
+            ignore_ssl_errors: Whether the webhook should ignore SSL errors returned by request_url.
+            do_not_retry: Whether the webhook should retry sending the payload to request_url upon failure.
+            is_ad_hoc: Set to True if you want the webhook to be triggered only the first time the condition
+                is fulfilled. Only applicable when actor_run_id is filled.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The updated webhook.
+        """
+        webhook_update = WebhookUpdate(
+            event_types=list(event_types) if event_types is not None else None,
+            request_url=AnyUrl(request_url) if request_url is not None else None,
+            payload_template=payload_template,
+            headers_template=headers_template,
+            ignore_ssl_errors=ignore_ssl_errors,
+            do_not_retry=do_not_retry,
+            is_ad_hoc=is_ad_hoc if actor_run_id else None,
+            condition=WebhookCondition(
+                actor_run_id=actor_run_id,
+                actor_task_id=actor_task_id,
+                actor_id=actor_id,
+            ),
+        )
+        result = self._update(timeout=timeout, **webhook_update.model_dump(by_alias=True, exclude_none=True))
+        return WebhookResponse.model_validate(result).data
+
+    def delete(self, *, timeout: Timeout = 'short') -> None:
+        """Delete the webhook.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+        """
+        self._delete(timeout=timeout)
+
+    def test(self, *, timeout: Timeout = 'medium') -> WebhookDispatch:
+        """Test a webhook.
+
+        Creates a webhook dispatch with a dummy payload.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The webhook dispatch created by the test.
+
+        Raises:
+            NotFoundError: If the webhook does not exist.
+        """
+        response = self._http_client.call(
+            url=self._build_url('test'),
+            method='POST',
+            params=self._build_params(),
+            timeout=timeout,
+        )
+
+        result = response_to_dict(response)
+        return TestWebhookResponse.model_validate(result).data
+
+    def dispatches(self) -> WebhookDispatchCollectionClient:
+        """Get dispatches of the webhook.
+
+
+        Returns:
+            A client allowing access to dispatches of this webhook using its list method.
+        """
+        return self._client_registry.webhook_dispatch_collection_client(
+            resource_path='dispatches',
+            **self._base_client_kwargs,
+        )
+
+
+@docs_group('Resource clients')
+class WebhookClientAsync(ResourceClientAsync):
+    """Sub-client for managing a specific webhook.
+
+    Provides methods to manage a specific webhook, 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 = 'webhooks',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_id=resource_id,
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    async def get(self, *, timeout: Timeout = 'short') -> Webhook | None:
+        """Retrieve the webhook.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved webhook, or None if it does not exist.
+        """
+        result = await self._get(timeout=timeout)
+        if result is None:
+            return None
+        return WebhookResponse.model_validate(result).data
+
+    async def update(
+        self,
+        *,
+        event_types: list[WebhookEventType] | None = None,
+        request_url: str | None = None,
+        payload_template: str | None = None,
+        headers_template: str | None = None,
+        actor_id: str | None = None,
+        actor_task_id: str | None = None,
+        actor_run_id: str | None = None,
+        ignore_ssl_errors: bool | None = None,
+        do_not_retry: bool | None = None,
+        is_ad_hoc: bool | None = None,
+        timeout: Timeout = 'short',
+    ) -> Webhook:
+        """Update the webhook.
+
+
+        Args:
+            event_types: List of event types that should trigger the webhook. At least one is required.
+            request_url: URL that will be invoked once the webhook is triggered.
+            payload_template: Specification of the payload that will be sent to request_url.
+            headers_template: Headers that will be sent to the request_url.
+            actor_id: Id of the Actor whose runs should trigger the webhook.
+            actor_task_id: Id of the Actor task whose runs should trigger the webhook.
+            actor_run_id: Id of the Actor run which should trigger the webhook.
+            ignore_ssl_errors: Whether the webhook should ignore SSL errors returned by request_url.
+            do_not_retry: Whether the webhook should retry sending the payload to request_url upon failure.
+            is_ad_hoc: Set to True if you want the webhook to be triggered only the first time the condition
+                is fulfilled. Only applicable when actor_run_id is filled.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The updated webhook.
+        """
+        webhook_update = WebhookUpdate(
+            event_types=list(event_types) if event_types is not None else None,
+            request_url=AnyUrl(request_url) if request_url is not None else None,
+            payload_template=payload_template,
+            headers_template=headers_template,
+            ignore_ssl_errors=ignore_ssl_errors,
+            do_not_retry=do_not_retry,
+            is_ad_hoc=is_ad_hoc if actor_run_id else None,
+            condition=WebhookCondition(
+                actor_run_id=actor_run_id,
+                actor_task_id=actor_task_id,
+                actor_id=actor_id,
+            ),
+        )
+        result = await self._update(timeout=timeout, **webhook_update.model_dump(by_alias=True, exclude_none=True))
+        return WebhookResponse.model_validate(result).data
+
+    async def delete(self, *, timeout: Timeout = 'short') -> None:
+        """Delete the webhook.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+        """
+        await self._delete(timeout=timeout)
+
+    async def test(self, *, timeout: Timeout = 'medium') -> WebhookDispatch:
+        """Test a webhook.
+
+        Creates a webhook dispatch with a dummy payload.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The webhook dispatch created by the test.
+
+        Raises:
+            NotFoundError: If the webhook does not exist.
+        """
+        response = await self._http_client.call(
+            url=self._build_url('test'),
+            method='POST',
+            params=self._build_params(),
+            timeout=timeout,
+        )
+
+        result = response_to_dict(response)
+        return TestWebhookResponse.model_validate(result).data
+
+    def dispatches(self) -> WebhookDispatchCollectionClientAsync:
+        """Get dispatches of the webhook.
+
+
+        Returns:
+            A client allowing access to dispatches of this webhook using its list method.
+        """
+        return self._client_registry.webhook_dispatch_collection_client(
+            resource_path='dispatches',
+            **self._base_client_kwargs,
+        )

scrapely_client/_resource_clients/webhook_collection.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from scrapely_client._docs import docs_group
+from scrapely_client._models import (
+    ListOfWebhooks,
+    ListOfWebhooksResponse,
+    WebhookCondition,
+    WebhookCreate,
+    WebhookResponse,
+)
+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 scrapely_client._literals import WebhookEventType
+    from scrapely_client._models import Webhook, WebhookShort
+    from scrapely_client.types import Timeout
+
+
+@docs_group('Resource clients')
+class WebhookCollectionClient(ResourceClient):
+    """Sub-client for the webhook collection.
+
+    Provides methods to manage the webhook collection, e.g. list or create webhooks. Obtain an instance via an
+    appropriate method on the `ApifyClient` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_path: str = 'webhooks',
+        **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,
+        timeout: Timeout = 'medium',
+    ) -> ListOfWebhooks:
+        """List the available webhooks.
+
+
+        Args:
+            limit: How many webhooks to retrieve.
+            offset: What webhook to include as first when retrieving the list.
+            desc: Whether to sort the webhooks in descending order based on their date of creation.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The list of available webhooks matching the specified filters.
+        """
+        result = self._list(timeout=timeout, limit=limit, offset=offset, desc=desc)
+        return ListOfWebhooksResponse.model_validate(result).data
+
+    def iterate(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        timeout: Timeout = 'medium',
+    ) -> Iterator[WebhookShort]:
+        """Iterate over the available webhooks.
+
+        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 webhooks to retrieve.
+            offset: What webhook to include as first when retrieving the list.
+            desc: Whether to sort the webhooks in descending order based on their date of creation.
+            timeout: Timeout for the API HTTP request.
+
+        Yields:
+            The available webhooks matching the specified filters.
+        """
+
+        def _callback(*, limit: int | None = None, offset: int | None = None) -> ListOfWebhooks:
+            return self.list(limit=limit, offset=offset, desc=desc, timeout=timeout)
+
+        return get_items_iterator(_callback, limit=limit, offset=offset)
+
+    def create(
+        self,
+        *,
+        event_types: list[WebhookEventType],  # ty: ignore[invalid-type-form]
+        request_url: str,
+        payload_template: str | None = None,
+        headers_template: str | None = None,
+        actor_id: str | None = None,
+        actor_task_id: str | None = None,
+        actor_run_id: str | None = None,
+        ignore_ssl_errors: bool | None = None,
+        do_not_retry: bool | None = None,
+        idempotency_key: str | None = None,
+        is_ad_hoc: bool | None = None,
+        timeout: Timeout = 'short',
+    ) -> Webhook:
+        """Create a new webhook.
+
+        You have to specify exactly one out of actor_id, actor_task_id or actor_run_id.
+
+
+        Args:
+            event_types: List of event types that should trigger the webhook. At least one is required.
+            request_url: URL that will be invoked once the webhook is triggered.
+            payload_template: Specification of the payload that will be sent to request_url.
+            headers_template: Headers that will be sent to the request_url.
+            actor_id: Id of the Actor whose runs should trigger the webhook.
+            actor_task_id: Id of the Actor task whose runs should trigger the webhook.
+            actor_run_id: Id of the Actor run which should trigger the webhook.
+            ignore_ssl_errors: Whether the webhook should ignore SSL errors returned by request_url.
+            do_not_retry: Whether the webhook should retry sending the payload to request_url upon failure.
+            idempotency_key: A unique identifier of a webhook. You can use it to ensure that you won't create
+                the same webhook multiple times.
+            is_ad_hoc: Set to True if you want the webhook to be triggered only the first time the condition
+                is fulfilled. Only applicable when actor_run_id is filled.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+           The created webhook.
+        """
+        webhook_create = WebhookCreate(
+            event_types=list(event_types),
+            request_url=request_url,
+            payload_template=payload_template,
+            headers_template=headers_template,
+            ignore_ssl_errors=ignore_ssl_errors,
+            do_not_retry=do_not_retry,
+            idempotency_key=idempotency_key,
+            is_ad_hoc=is_ad_hoc if actor_run_id else None,
+            condition=WebhookCondition(
+                actor_run_id=actor_run_id,
+                actor_task_id=actor_task_id,
+                actor_id=actor_id,
+            ),
+        )
+        result = self._create(timeout=timeout, **webhook_create.model_dump(by_alias=True, exclude_none=True))
+        return WebhookResponse.model_validate(result).data
+
+
+@docs_group('Resource clients')
+class WebhookCollectionClientAsync(ResourceClientAsync):
+    """Sub-client for the webhook collection.
+
+    Provides methods to manage the webhook collection, e.g. list or create webhooks. Obtain an instance via an
+    appropriate method on the `ApifyClientAsync` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_path: str = 'webhooks',
+        **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,
+        timeout: Timeout = 'medium',
+    ) -> ListOfWebhooks:
+        """List the available webhooks.
+
+
+        Args:
+            limit: How many webhooks to retrieve.
+            offset: What webhook to include as first when retrieving the list.
+            desc: Whether to sort the webhooks in descending order based on their date of creation.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The list of available webhooks matching the specified filters.
+        """
+        result = await self._list(timeout=timeout, limit=limit, offset=offset, desc=desc)
+        return ListOfWebhooksResponse.model_validate(result).data
+
+    def iterate(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        timeout: Timeout = 'medium',
+    ) -> AsyncIterator[WebhookShort]:
+        """Iterate over the available webhooks.
+
+        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 webhooks to retrieve.
+            offset: What webhook to include as first when retrieving the list.
+            desc: Whether to sort the webhooks in descending order based on their date of creation.
+            timeout: Timeout for the API HTTP request.
+
+        Yields:
+            The available webhooks matching the specified filters.
+        """
+
+        async def _callback(*, limit: int | None = None, offset: int | None = None) -> ListOfWebhooks:
+            return await self.list(limit=limit, offset=offset, desc=desc, timeout=timeout)
+
+        return get_items_iterator_async(_callback, limit=limit, offset=offset)
+
+    async def create(
+        self,
+        *,
+        event_types: list[WebhookEventType],  # ty: ignore[invalid-type-form]
+        request_url: str,
+        payload_template: str | None = None,
+        headers_template: str | None = None,
+        actor_id: str | None = None,
+        actor_task_id: str | None = None,
+        actor_run_id: str | None = None,
+        ignore_ssl_errors: bool | None = None,
+        do_not_retry: bool | None = None,
+        idempotency_key: str | None = None,
+        is_ad_hoc: bool | None = None,
+        timeout: Timeout = 'short',
+    ) -> Webhook:
+        """Create a new webhook.
+
+        You have to specify exactly one out of actor_id, actor_task_id or actor_run_id.
+
+
+        Args:
+            event_types: List of event types that should trigger the webhook. At least one is required.
+            request_url: URL that will be invoked once the webhook is triggered.
+            payload_template: Specification of the payload that will be sent to request_url.
+            headers_template: Headers that will be sent to the request_url.
+            actor_id: Id of the Actor whose runs should trigger the webhook.
+            actor_task_id: Id of the Actor task whose runs should trigger the webhook.
+            actor_run_id: Id of the Actor run which should trigger the webhook.
+            ignore_ssl_errors: Whether the webhook should ignore SSL errors returned by request_url.
+            do_not_retry: Whether the webhook should retry sending the payload to request_url upon failure.
+            idempotency_key: A unique identifier of a webhook. You can use it to ensure that you won't create
+                the same webhook multiple times.
+            is_ad_hoc: Set to True if you want the webhook to be triggered only the first time the condition
+                is fulfilled. Only applicable when actor_run_id is filled.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+           The created webhook.
+        """
+        webhook_create = WebhookCreate(
+            event_types=list(event_types),
+            request_url=request_url,
+            payload_template=payload_template,
+            headers_template=headers_template,
+            ignore_ssl_errors=ignore_ssl_errors,
+            do_not_retry=do_not_retry,
+            idempotency_key=idempotency_key,
+            is_ad_hoc=is_ad_hoc if actor_run_id else None,
+            condition=WebhookCondition(
+                actor_run_id=actor_run_id,
+                actor_task_id=actor_task_id,
+                actor_id=actor_id,
+            ),
+        )
+        result = await self._create(timeout=timeout, **webhook_create.model_dump(by_alias=True, exclude_none=True))
+        return WebhookResponse.model_validate(result).data

scrapely_client/_resource_clients/webhook_dispatch.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from scrapely_client._docs import docs_group
+from scrapely_client._models import WebhookDispatch, WebhookDispatchResponse
+from scrapely_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
+
+if TYPE_CHECKING:
+    from scrapely_client.types import Timeout
+
+
+@docs_group('Resource clients')
+class WebhookDispatchClient(ResourceClient):
+    """Sub-client for managing a specific webhook dispatch.
+
+    Provides methods to manage a specific webhook dispatch, e.g. get its details. Obtain an instance via an appropriate
+    method on the `ApifyClient` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_id: str,
+        resource_path: str = 'webhook-dispatches',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_id=resource_id,
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    def get(self, *, timeout: Timeout = 'short') -> WebhookDispatch | None:
+        """Retrieve the webhook dispatch.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved webhook dispatch, or None if it does not exist.
+        """
+        result = self._get(timeout=timeout)
+        if result is None:
+            return None
+        return WebhookDispatchResponse.model_validate(result).data
+
+
+@docs_group('Resource clients')
+class WebhookDispatchClientAsync(ResourceClientAsync):
+    """Sub-client for managing a specific webhook dispatch.
+
+    Provides methods to manage a specific webhook dispatch, e.g. get its details. Obtain an instance via an appropriate
+    method on the `ApifyClientAsync` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_id: str,
+        resource_path: str = 'webhook-dispatches',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_id=resource_id,
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    async def get(self, *, timeout: Timeout = 'short') -> WebhookDispatch | None:
+        """Retrieve the webhook dispatch.
+
+
+        Args:
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved webhook dispatch, or None if it does not exist.
+        """
+        result = await self._get(timeout=timeout)
+        if result is None:
+            return None
+        return WebhookDispatchResponse.model_validate(result).data