python-re3data-v2 0.1.0__py3-none-any.whl

re3data/_client/_sync.py

@@ -0,0 +1,145 @@
+"""The synchronous client to interact with the re3data v40 API."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Self
+
+import httpx
+
+from re3data._client.base import (
+    BaseClient,
+    Endpoint,
+    ResourceType,
+    ReturnType,
+    _dispatch_return_type,
+    build_query_params,
+    is_valid_return_type,
+)
+from re3data._exceptions import RepositoryNotFoundError
+from re3data._response import Response, _build_response
+
+if TYPE_CHECKING:
+    from re3data._resources import Repository, RepositorySummary
+
+logger = logging.getLogger(__name__)
+
+
+def log_response(response: httpx.Response) -> None:
+    """Log method, URL and status code of an HTTP response on the debug level."""
+    logger.debug("[http] Response: %s %s - Status %s", response.request.method, response.request.url, response.status_code)
+
+
+class RepositoryManager:
+    """A manager for interacting with the repositories endpoints."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def list(
+        self,
+        query: str | None = None,
+        return_type: ReturnType = ReturnType.DATACLASS,
+        count: bool = False,
+        filters: dict[str, str | list[str] | tuple[str, ...]] | None = None,
+    ) -> list[RepositorySummary] | Response | list[dict] | str | int:
+        """List the metadata of repositories in the re3data API.
+
+        Args:
+            query: A query string to filter the results. If provided, only
+                repositories matching the query will be returned.
+            return_type: The desired return type for the API resource.
+                Defaults to `ReturnType.DATACLASS`.
+            count: Whether to return the total number of matching items
+                instead of a list of repositories.
+            filters: Optional facet filters for the v40 endpoint, e.g.
+                ``{"countries": ["DEU", "NZL"], "dataAccess": "open"}``.
+
+        Returns:
+            Depending on the `return_type`, this is a list of
+            RepositorySummary objects, an HTTP response, a dictionary/JSON/CSV
+            representation, the original XML, or the count of repositories.
+
+        Raises:
+            ValueError: If an invalid `return_type` is provided.
+            httpx.HTTPStatusError: If the server returned an error status code >= 500.
+        """
+        is_valid_return_type(return_type)
+        params = build_query_params(query, filters)
+        response = self._client._request(Endpoint.REPOSITORY_LIST.value, params)
+        return _dispatch_return_type(response, ResourceType.REPOSITORY_LIST, return_type, count)
+
+    def get(self, repository_id: str, return_type: ReturnType = ReturnType.DATACLASS) -> Repository | Response | dict | str:
+        """Get the metadata of a specific repository.
+
+        Args:
+            repository_id: The identifier of the repository to retrieve,
+                e.g. "r3d100012417".
+            return_type: The desired return type for the API resource.
+                Defaults to `ReturnType.DATACLASS`.
+
+        Returns:
+            Depending on the `return_type`, this is a Repository object, an
+            HTTP response, a dictionary/JSON/CSV representation or the
+            original XML.
+
+        Raises:
+            ValueError: If an invalid `return_type` is provided.
+            httpx.HTTPStatusError: If the server returned an error status code >= 500.
+            RepositoryNotFoundError: If no repository with the given ID is found.
+        """
+        is_valid_return_type(return_type)
+        response = self._client._request(Endpoint.REPOSITORY.value.format(repository_id=repository_id))
+        if response.status_code == httpx.codes.NOT_FOUND:
+            raise RepositoryNotFoundError(f"No repository with id '{repository_id}' available at {response.url}.")
+        return _dispatch_return_type(response, ResourceType.REPOSITORY, return_type)
+
+
+class Client(BaseClient):
+    """A client that interacts with the re3data v40 API.
+
+    Examples:
+        >>> client = Client()
+        >>> client.repositories.get("r3d100012417")
+        Repository(identifiers=Identifiers(re3data='r3d100012417', doi='https://doi.org/10.17616/R34F41'), ...)
+        >>> client.repositories.list(query="biosharing")
+        [RepositorySummary(id='r3d100010142', ...)]
+    """
+
+    _client: httpx.Client
+
+    def __init__(self, transport: httpx.BaseTransport | None = None) -> None:
+        """Initialize the client.
+
+        Args:
+            transport: An optional custom httpx transport, e.g. for testing.
+        """
+        super().__init__(httpx.Client, transport)
+        self._client.event_hooks["response"] = [log_response]
+        self._repository_manager: RepositoryManager = RepositoryManager(self)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release connections."""
+        self._client.close()
+
+    def _request(self, path: str, query_params: list[tuple[str, str]] | None = None) -> Response:
+        """Send an HTTP GET request to the specified API endpoint.
+
+        Raises:
+            httpx.HTTPStatusError: If the server returned an error status code >= 500.
+        """
+        http_response = self._client.get(path, params=query_params)
+        if http_response.is_server_error:
+            http_response.raise_for_status()
+        return _build_response(http_response)
+
+    @property
+    def repositories(self) -> RepositoryManager:
+        """The repository manager of this client."""
+        return self._repository_manager

re3data/_client/base.py

@@ -0,0 +1,152 @@
+"""Shared building blocks for the sync and async re3data API clients."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import TYPE_CHECKING, Any, Literal, overload
+
+import httpx
+
+from re3data import __version__
+from re3data._parser import parse_repository, parse_repository_list
+from re3data._response import Response
+from re3data._serializer import _to_csv, _to_dict, _to_json
+
+if TYPE_CHECKING:
+    from re3data._resources import Repository, RepositorySummary
+
+BASE_URL: str = "https://www.re3data.org/api/v40/"
+DEFAULT_HEADERS: dict[str, str] = {
+    "Accept": "application/xml; charset=utf-8",
+    "User-Agent": f"python-re3data-v2/{__version__}",
+}
+DEFAULT_TIMEOUT = httpx.Timeout(timeout=10.0)  # timeout in seconds
+
+
+class Endpoint(StrEnum):
+    """The re3data v40 API endpoints."""
+
+    REPOSITORY = "repository/{repository_id}"
+    REPOSITORY_LIST = "repositories"
+
+
+class ResourceType(StrEnum):
+    """The type of an API resource."""
+
+    REPOSITORY = "repository"
+    REPOSITORY_LIST = "repositories"
+
+
+class ReturnType(StrEnum):
+    """The supported serialization formats of API resources."""
+
+    CSV = "csv"
+    DATACLASS = "dataclass"
+    DICT = "dict"
+    JSON = "json"
+    RESPONSE = "response"
+    XML = "xml"
+
+
+def is_valid_return_type(return_type: Any) -> None:
+    """Validate that the given return type is a known :class:`ReturnType`.
+
+    Raises:
+        ValueError: If the given return type is not one of the allowed types.
+    """
+    if not isinstance(return_type, ReturnType):
+        allowed_types = [return_type.value for return_type in ReturnType]
+        raise ValueError(  # noqa: TRY004 - ValueError for compat with the original client
+            f"Invalid value for `return_type`: {return_type} is not one of {allowed_types}."
+        )
+
+
+def build_query_params(
+    query: str | None = None,
+    filters: dict[str, str | list[str] | tuple[str, ...]] | None = None,
+) -> list[tuple[str, str]]:
+    """Build the query parameters for the list endpoint.
+
+    Args:
+        query: An optional search term, sent as the ``query`` parameter.
+        filters: Optional facet filters. Keys are the v40 filter names without
+            brackets (e.g. ``countries``, ``dataAccess``, ``subjects``); values
+            are one value or a sequence of values. They are serialized as
+            repeated ``name[]`` parameters, e.g. ``countries[]=NZL``.
+
+    Returns:
+        A list of query parameter pairs, ready for ``httpx``.
+    """
+    params: list[tuple[str, str]] = []
+    if query:
+        params.append(("query", query))
+    for name, raw_values in (filters or {}).items():
+        values = (raw_values,) if isinstance(raw_values, str) else raw_values
+        params.extend((f"{name}[]", str(value)) for value in values)
+    return params
+
+
+@overload
+def _dispatch_return_type(
+    response: Response, resource_type: Literal[ResourceType.REPOSITORY], return_type: ReturnType
+) -> Repository | Response | dict | str: ...
+@overload
+def _dispatch_return_type(
+    response: Response, resource_type: Literal[ResourceType.REPOSITORY_LIST], return_type: ReturnType, count: bool = False
+) -> list[RepositorySummary] | Response | list[dict] | str | int: ...
+
+
+def _dispatch_return_type(  # noqa: PLR0911 - mirrors the upstream dispatch structure
+    response: Response, resource_type: ResourceType, return_type: ReturnType, count: bool = False
+) -> Repository | list[RepositorySummary] | Response | dict | list[dict] | str | int:
+    """Dispatch a response to the requested return type.
+
+    Args:
+        response: The response object.
+        resource_type: The type of resource being processed.
+        return_type: The desired return type for the API resource.
+        count: Whether to return the total number of matching items instead of
+            a list of repositories (list endpoint only).
+
+    Returns:
+        Depending on the return type: a typed model, the response object, the
+            raw XML, a dict/JSON/CSV serialization or the repository count.
+    """
+    if resource_type is ResourceType.REPOSITORY_LIST and count:
+        return response.text.count("<repository>")
+    if return_type is ReturnType.RESPONSE:
+        return response
+    if return_type is ReturnType.XML:
+        return response.text
+
+    parsed = (
+        parse_repository_list(response.text).repository
+        if resource_type is ResourceType.REPOSITORY_LIST
+        else parse_repository(response.text)
+    )
+    if return_type is ReturnType.DATACLASS:
+        return parsed
+    if return_type is ReturnType.DICT:
+        return _to_dict(parsed)
+    if return_type is ReturnType.JSON:
+        return _to_json(parsed)
+    return _to_csv(parsed)
+
+
+class BaseClient:
+    """A base class for clients that interact with the re3data v40 API."""
+
+    def __init__(
+        self,
+        client: type[httpx.Client | httpx.AsyncClient],
+        transport: httpx.BaseTransport | httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        kwargs: dict[str, object] = {
+            "base_url": BASE_URL,
+            "headers": DEFAULT_HEADERS,
+            "timeout": DEFAULT_TIMEOUT,
+            "follow_redirects": True,
+        }
+        if transport is not None:
+            kwargs["transport"] = transport
+        self._client = client(**kwargs)

re3data/_exceptions.py

@@ -0,0 +1,9 @@
+"""Exception classes for errors encountered when using the re3data API."""
+
+
+class Re3dataError(Exception):
+    """Base exception class for errors related to the re3data API."""
+
+
+class RepositoryNotFoundError(Re3dataError):
+    """Exception raised when a repository is not found."""