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

scrapely_client/_resource_clients/key_value_store_collection.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 (
+    KeyValueStore,
+    KeyValueStoreResponse,
+    ListOfKeyValueStores,
+    ListOfKeyValueStoresResponse,
+)
+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 StorageOwnership
+    from scrapely_client.types import Timeout
+
+
+@docs_group('Resource clients')
+class KeyValueStoreCollectionClient(ResourceClient):
+    """Sub-client for the key-value store collection.
+
+    Provides methods to manage the key-value store collection, e.g. list or create key-value stores. Obtain an instance
+    via an appropriate method on the `ApifyClient` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_path: str = 'key-value-stores',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    def list(
+        self,
+        *,
+        unnamed: bool | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        ownership: StorageOwnership | None = None,
+        timeout: Timeout = 'medium',
+    ) -> ListOfKeyValueStores:
+        """List the available key-value stores.
+
+
+        Args:
+            unnamed: Whether to include unnamed key-value stores in the list.
+            limit: How many key-value stores to retrieve.
+            offset: What key-value store to include as first when retrieving the list.
+            desc: Whether to sort the key-value stores in descending order based on their modification date.
+            ownership: Filter by ownership. `'ownedByMe'` returns only user's own key-value stores,
+                `'sharedWithMe'` returns only key-value stores shared with the user.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The list of available key-value stores matching the specified filters.
+        """
+        result = self._list(
+            timeout=timeout,
+            unnamed=unnamed,
+            limit=limit,
+            offset=offset,
+            desc=desc,
+            ownership=ownership,
+        )
+        return ListOfKeyValueStoresResponse.model_validate(result).data
+
+    def iterate(
+        self,
+        *,
+        unnamed: bool | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        ownership: StorageOwnership | None = None,
+        timeout: Timeout = 'medium',
+    ) -> Iterator[KeyValueStore]:
+        """Iterate over the available key-value stores.
+
+        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:
+            unnamed: Whether to include unnamed key-value stores in the list.
+            limit: How many key-value stores to retrieve.
+            offset: What key-value store to include as first when retrieving the list.
+            desc: Whether to sort the key-value stores in descending order based on their modification date.
+            ownership: Filter by ownership. 'ownedByMe' returns only user's own key-value stores,
+                'sharedWithMe' returns only key-value stores shared with the user.
+            timeout: Timeout for the API HTTP request.
+
+        Yields:
+            The available key-value stores matching the specified filters.
+        """
+
+        def _callback(*, limit: int | None = None, offset: int | None = None) -> ListOfKeyValueStores:
+            return self.list(
+                unnamed=unnamed, limit=limit, offset=offset, desc=desc, ownership=ownership, timeout=timeout
+            )
+
+        return get_items_iterator(_callback, limit=limit, offset=offset)
+
+    def get_or_create(
+        self,
+        *,
+        name: str | None = None,
+        schema: dict | None = None,
+        timeout: Timeout = 'short',
+    ) -> KeyValueStore:
+        """Retrieve a named key-value store, or create a new one when it doesn't exist.
+
+
+        Args:
+            name: The name of the key-value store to retrieve or create.
+            schema: The schema of the key-value store.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved or newly-created key-value store.
+        """
+        result = self._get_or_create(timeout=timeout, name=name, resource_fields={'schema': schema})
+        return KeyValueStoreResponse.model_validate(result).data
+
+
+@docs_group('Resource clients')
+class KeyValueStoreCollectionClientAsync(ResourceClientAsync):
+    """Sub-client for the key-value store collection.
+
+    Provides methods to manage the key-value store collection, e.g. list or create key-value stores. Obtain an instance
+    via an appropriate method on the `ApifyClientAsync` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_path: str = 'key-value-stores',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    async def list(
+        self,
+        *,
+        unnamed: bool | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        ownership: StorageOwnership | None = None,
+        timeout: Timeout = 'medium',
+    ) -> ListOfKeyValueStores:
+        """List the available key-value stores.
+
+
+        Args:
+            unnamed: Whether to include unnamed key-value stores in the list.
+            limit: How many key-value stores to retrieve.
+            offset: What key-value store to include as first when retrieving the list.
+            desc: Whether to sort the key-value stores in descending order based on their modification date.
+            ownership: Filter by ownership. `'ownedByMe'` returns only user's own key-value stores,
+                `'sharedWithMe'` returns only key-value stores shared with the user.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The list of available key-value stores matching the specified filters.
+        """
+        result = await self._list(
+            timeout=timeout,
+            unnamed=unnamed,
+            limit=limit,
+            offset=offset,
+            desc=desc,
+            ownership=ownership,
+        )
+        return ListOfKeyValueStoresResponse.model_validate(result).data
+
+    def iterate(
+        self,
+        *,
+        unnamed: bool | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+        desc: bool | None = None,
+        ownership: StorageOwnership | None = None,
+        timeout: Timeout = 'medium',
+    ) -> AsyncIterator[KeyValueStore]:
+        """Iterate over the available key-value stores.
+
+        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:
+            unnamed: Whether to include unnamed key-value stores in the list.
+            limit: How many key-value stores to retrieve.
+            offset: What key-value store to include as first when retrieving the list.
+            desc: Whether to sort the key-value stores in descending order based on their modification date.
+            ownership: Filter by ownership. 'ownedByMe' returns only user's own key-value stores,
+                'sharedWithMe' returns only key-value stores shared with the user.
+            timeout: Timeout for the API HTTP request.
+
+        Yields:
+            The available key-value stores matching the specified filters.
+        """
+
+        async def _callback(*, limit: int | None = None, offset: int | None = None) -> ListOfKeyValueStores:
+            return await self.list(
+                unnamed=unnamed, limit=limit, offset=offset, desc=desc, ownership=ownership, timeout=timeout
+            )
+
+        return get_items_iterator_async(_callback, limit=limit, offset=offset)
+
+    async def get_or_create(
+        self,
+        *,
+        name: str | None = None,
+        schema: dict | None = None,
+        timeout: Timeout = 'short',
+    ) -> KeyValueStore:
+        """Retrieve a named key-value store, or create a new one when it doesn't exist.
+
+
+        Args:
+            name: The name of the key-value store to retrieve or create.
+            schema: The schema of the key-value store.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved or newly-created key-value store.
+        """
+        result = await self._get_or_create(timeout=timeout, name=name, resource_fields={'schema': schema})
+        return KeyValueStoreResponse.model_validate(result).data

scrapely_client/_resource_clients/log.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager, contextmanager
+from typing import TYPE_CHECKING, Any
+
+from scrapely_client._docs import docs_group
+from scrapely_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
+from scrapely_client._utils.errors import catch_not_found_for_resource_or_throw
+from scrapely_client.errors import ApifyApiError
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Iterator
+
+    from scrapely_client.http_clients import HttpResponse
+    from scrapely_client.types import Timeout
+
+
+@docs_group('Resource clients')
+class LogClient(ResourceClient):
+    """Sub-client for managing a specific log.
+
+    Provides methods to manage logs, e.g. get or stream them. Obtain an instance via an appropriate method on the
+    `ApifyClient` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_path: str = 'logs',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    def get(self, *, raw: bool = False, timeout: Timeout = 'long') -> str | None:
+        """Retrieve the log as text.
+
+
+        404s collapse to `None` only when this client targets a specific log by ID (e.g. `client.log(run_id).get()`).
+        For chained clients without a `resource_id` (e.g. `run.log().get()`), a 404 is ambiguous and propagates.
+
+        Args:
+            raw: If true, the log will include formatting. For example, coloring character sequences.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved log, or None, if it does not exist.
+        """
+        try:
+            response = self._http_client.call(
+                url=self._build_url(),
+                method='GET',
+                params=self._build_params(raw=raw),
+                timeout=timeout,
+            )
+
+            return response.text  # noqa: TRY300
+
+        except ApifyApiError as exc:
+            catch_not_found_for_resource_or_throw(exc, self._resource_id)
+
+        return None
+
+    def get_as_bytes(self, *, raw: bool = False, timeout: Timeout = 'long') -> bytes | None:
+        """Retrieve the log as raw bytes.
+
+
+        Args:
+            raw: If true, the log will include formatting. For example, coloring character sequences.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved log as raw bytes, or None, if it does not exist.
+        """
+        try:
+            response = self._http_client.call(
+                url=self._build_url(),
+                method='GET',
+                params=self._build_params(raw=raw),
+                timeout=timeout,
+            )
+
+            return response.content  # noqa: TRY300
+
+        except ApifyApiError as exc:
+            catch_not_found_for_resource_or_throw(exc, self._resource_id)
+
+        return None
+
+    @contextmanager
+    def stream(self, *, raw: bool = False, timeout: Timeout = 'long') -> Iterator[HttpResponse | None]:
+        """Retrieve the log as a stream.
+
+
+        Args:
+            raw: If true, the log will include formatting. For example, coloring character sequences.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved log as a context-managed streaming `Response`, or None, if it does not exist.
+        """
+        response = None
+        try:
+            response = self._http_client.call(
+                url=self._build_url(),
+                method='GET',
+                params=self._build_params(stream=True, raw=raw),
+                stream=True,
+                timeout=timeout,
+            )
+
+            yield response
+        except ApifyApiError as exc:
+            catch_not_found_for_resource_or_throw(exc, self._resource_id)
+            yield None
+        finally:
+            if response:
+                response.close()
+
+
+@docs_group('Resource clients')
+class LogClientAsync(ResourceClientAsync):
+    """Sub-client for managing a specific log.
+
+    Provides methods to manage logs, e.g. get or stream them. Obtain an instance via an appropriate method on the
+    `ApifyClientAsync` class.
+    """
+
+    def __init__(
+        self,
+        *,
+        resource_path: str = 'logs',
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            resource_path=resource_path,
+            **kwargs,
+        )
+
+    async def get(self, *, raw: bool = False, timeout: Timeout = 'long') -> str | None:
+        """Retrieve the log as text.
+
+
+        404s collapse to `None` only when this client targets a specific log by ID (e.g. `client.log(run_id).get()`).
+        For chained clients without a `resource_id` (e.g. `run.log().get()`), a 404 is ambiguous and propagates.
+
+        Args:
+            raw: If true, the log will include formatting. For example, coloring character sequences.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved log, or None, if it does not exist.
+        """
+        try:
+            response = await self._http_client.call(
+                url=self._build_url(),
+                method='GET',
+                params=self._build_params(raw=raw),
+                timeout=timeout,
+            )
+
+            return response.text  # noqa: TRY300
+
+        except ApifyApiError as exc:
+            catch_not_found_for_resource_or_throw(exc, self._resource_id)
+
+        return None
+
+    async def get_as_bytes(self, *, raw: bool = False, timeout: Timeout = 'long') -> bytes | None:
+        """Retrieve the log as raw bytes.
+
+
+        Args:
+            raw: If true, the log will include formatting. For example, coloring character sequences.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved log as raw bytes, or None, if it does not exist.
+        """
+        try:
+            response = await self._http_client.call(
+                url=self._build_url(),
+                method='GET',
+                params=self._build_params(raw=raw),
+                timeout=timeout,
+            )
+
+            return response.content  # noqa: TRY300
+
+        except ApifyApiError as exc:
+            catch_not_found_for_resource_or_throw(exc, self._resource_id)
+
+        return None
+
+    @asynccontextmanager
+    async def stream(self, *, raw: bool = False, timeout: Timeout = 'long') -> AsyncIterator[HttpResponse | None]:
+        """Retrieve the log as a stream.
+
+
+        Args:
+            raw: If true, the log will include formatting. For example, coloring character sequences.
+            timeout: Timeout for the API HTTP request.
+
+        Returns:
+            The retrieved log as a context-managed streaming `Response`, or None, if it does not exist.
+        """
+        response = None
+        try:
+            response = await self._http_client.call(
+                url=self._build_url(),
+                method='GET',
+                params=self._build_params(stream=True, raw=raw),
+                stream=True,
+                timeout=timeout,
+            )
+
+            yield response
+        except ApifyApiError as exc:
+            catch_not_found_for_resource_or_throw(exc, self._resource_id)
+            yield None
+        finally:
+            if response:
+                await response.aclose()