opds-client 0.0.1__py3-none-any.whl

opds_client/__init__.py

@@ -0,0 +1,47 @@
+"""OPDS Client Library supporting OPDS 1.2 and OPDS 2.0."""
+
+from opds_client.client import OPDSClient
+from opds_client.models import (
+    AcquisitionLink,
+    Facet,
+    Group,
+    Link,
+    Metadata,
+    NavigationLink,
+    OPDSFeed,
+    OPDSPublication,
+    Publication,
+)
+from opds_client.opds12 import OPDS12Client
+from opds_client.opds12.models import (
+    Entry as OPDS12Entry,
+)
+from opds_client.opds12.models import (
+    FacetGroup,
+)
+from opds_client.opds12.models import (
+    Feed as OPDS12Feed,
+)
+from opds_client.opds12.models import (
+    Link as OPDS12Link,
+)
+from opds_client.opds12.parser import OPDS12Parser
+
+__all__ = [
+    "OPDSClient",
+    "Link",
+    "Metadata",
+    "Publication",
+    "OPDSPublication",
+    "OPDSFeed",
+    "NavigationLink",
+    "Facet",
+    "Group",
+    "AcquisitionLink",
+    "OPDS12Client",
+    "OPDS12Feed",
+    "OPDS12Entry",
+    "OPDS12Link",
+    "FacetGroup",
+    "OPDS12Parser",
+]

opds_client/client.py

@@ -0,0 +1,385 @@
+"""OPDS 2.0 client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import requests
+from requests.adapters import HTTPAdapter, Retry
+from requests.auth import HTTPBasicAuth
+
+from opds_client.exceptions import (
+    OPDSHTTPError,
+    OPDSNavigationError,
+    OPDSParseError,
+    OPDSValidationError,
+    SearchError,
+)
+from opds_client.models import Link, OPDSFeed, OPDSPublication
+from opds_client.parser import OPDSParser, URITemplateResolver
+from opds_client.utils import merge_urls
+
+
+class OPDSClient:
+    """Client for OPDS 2.0 catalogs."""
+
+    DEFAULT_HEADERS = {
+        "Accept": "application/opds+json, application/json, */*",
+        "User-Agent": "OPDS-Client/1.0",
+    }
+
+    def __init__(
+        self,
+        username: str | None = None,
+        password: str | None = None,
+        auth: requests.auth.AuthBase | None = None,
+        timeout: int = 30,
+        max_retries: int = 3,
+        backoff_factor: float = 0.5,
+        session: requests.Session | None = None,
+        parser: OPDSParser | None = None,
+        origin: str | None = None,
+    ):
+        """Initialize OPDS client.
+
+        Args:
+            username: Username for HTTP Basic Auth.
+            password: Password for HTTP Basic Auth.
+            auth: Custom auth object (overrides username/password).
+            timeout: Request timeout in seconds.
+            max_retries: Maximum number of retries on error.
+            backoff_factor: Backoff factor for retries.
+            session: Optional requests session to reuse.
+            parser: Optional OPDS parser instance.
+            origin: Optional base URL to prepend to relative URLs.
+        """
+        self.timeout = timeout
+        self.session = session or requests.Session()
+        self.origin = origin
+
+        # Configure authentication
+        if auth is not None:
+            self.session.auth = auth
+        elif username is not None and password is not None:
+            self.session.auth = HTTPBasicAuth(username, password)
+
+        if max_retries > 0:
+            retry_strategy = Retry(
+                total=max_retries,
+                backoff_factor=backoff_factor,
+                status_forcelist=[429, 500, 502, 503, 504],
+                allowed_methods=["GET", "POST"],
+            )
+            adapter = HTTPAdapter(max_retries=retry_strategy)
+            self.session.mount("http://", adapter)
+            self.session.mount("https://", adapter)
+
+        self.parser = parser or OPDSParser()
+
+    def _prepare_url(self, url: str) -> str:
+        """Prepare URL by merging with origin if needed.
+
+        Args:
+            url: URL string.
+
+        Returns:
+            Merged absolute URL.
+        """
+        if self.origin is not None:
+            return merge_urls(self.origin, url)
+        return url
+
+    def fetch_feed(self, url: str) -> "OPDSFeed":
+        """Fetch and parse an OPDS feed.
+
+        Args:
+            url: URL of the OPDS feed.
+
+        Returns:
+            Parsed OPDSFeed object.
+
+        Raises:
+            OPDSHTTPError: If HTTP request fails.
+            OPDSParseError: If parsing fails.
+            OPDSValidationError: If validation fails.
+            OPDSNavigationError: If navigation fails.
+        """
+        try:
+            response = self.session.get(
+                self._prepare_url(url),
+                headers=self.DEFAULT_HEADERS,
+                timeout=self.timeout,
+            )
+            response.raise_for_status()
+        except requests.exceptions.RequestException as e:
+            if hasattr(e, "response") and e.response is not None:
+                raise OPDSHTTPError(
+                    f"HTTP error {e.response.status_code}",
+                    e.response.status_code,
+                    self._prepare_url(url),
+                    e.response.text,
+                ) from e
+            raise OPDSHTTPError(str(e), 0, self._prepare_url(url)) from e
+
+        try:
+            feed = self.parser.parse(response.text)
+            feed._url = url  # type: ignore[attr-defined]
+            return feed
+        except (OPDSParseError, OPDSValidationError) as e:
+            raise e
+
+    def fetch_publication(self, url: str) -> "OPDSPublication":
+        """Fetch and parse an OPDS publication.
+
+        Args:
+            url: URL of the OPDS publication.
+
+        Returns:
+            Parsed OPDSPublication object.
+
+        Raises:
+            OPDSHTTPError: If HTTP request fails.
+            OPDSParseError: If parsing fails.
+            OPDSValidationError: If validation fails.
+        """
+        headers = self.DEFAULT_HEADERS.copy()
+        headers["Accept"] = (
+            "application/opds-publication+json, application/opds+json, " +
+            "application/json, */*"
+        )
+
+        try:
+            response = self.session.get(
+                self._prepare_url(url), headers=headers, timeout=self.timeout
+            )
+            response.raise_for_status()
+        except requests.exceptions.RequestException as e:
+            if hasattr(e, "response") and e.response is not None:
+                raise OPDSHTTPError(
+                    f"HTTP error {e.response.status_code}",
+                    e.response.status_code,
+                    self._prepare_url(url),
+                    e.response.text,
+                ) from e
+            raise OPDSHTTPError(str(e), 0, self._prepare_url(url)) from e
+
+        try:
+            publication = self.parser.parse_publication(response.text)
+            publication._url = self._prepare_url(url)  # type: ignore[attr-defined]
+            return publication
+        except (OPDSParseError, OPDSValidationError) as e:
+            raise e
+
+    def follow_link(self, link: "Link", **params: str | int | float) -> "OPDSFeed":
+        """Follow a link and fetch the target feed.
+
+        Args:
+            link: Link object to follow.
+            **params: Parameters for URI template resolution.
+
+        Returns:
+            Parsed OPDSFeed object.
+
+        Raises:
+            OPDSNavigationError: If link cannot be followed.
+            OPDSHTTPError: If HTTP request fails.
+        """
+        if link.templated:
+            url = URITemplateResolver.fill_template(str(link.href), **params)
+        else:
+            url = str(link.href)
+
+        return self.fetch_feed(self._prepare_url(url))
+
+    def navigate_to(
+        self, feed: "OPDSFeed", rel: str, **params: str | int | float
+    ) -> "OPDSFeed":
+        """Navigate to a feed using a link relation.
+
+        Args:
+            feed: Current OPDS feed.
+            rel: Link relation to follow.
+            **params: Parameters for URI template resolution.
+
+        Returns:
+            Parsed OPDSFeed object.
+
+        Raises:
+            OPDSNavigationError: If link with relation not found.
+        """
+        link = feed.get_link_by_rel(rel)
+        if link is None:
+            raise OPDSNavigationError(f"Link with relation '{rel}' not found")
+
+        return self.follow_link(link, **params)
+
+    def get_link_by_rel(self, feed: "OPDSFeed", rel: str) -> Optional["Link"]:
+        """Get a link by relation from feed.
+
+        Args:
+            feed: OPDS feed.
+            rel: Link relation to find.
+
+        Returns:
+            Link object or None if not found.
+        """
+        return feed.get_link_by_rel(rel)
+
+    def search(
+        self,
+        feed: "OPDSFeed",
+        query: str,
+        **filters: str | int | float,
+    ) -> "OPDSFeed":
+        """Search an OPDS feed.
+
+        Args:
+            feed: OPDS feed with search link.
+            query: Search query string.
+            **filters: Additional filter parameters.
+
+        Returns:
+            Parsed OPDSFeed object with search results.
+
+        Raises:
+            SearchError: If search is not supported.
+            OPDSHTTPError: If HTTP request fails.
+            OPDSNavigationError: If navigation fails.
+        """
+        search_link = feed.get_search_link()
+        if search_link is None:
+            raise SearchError("Search is not supported by this catalog")
+
+        params: dict[str, str] = {"query": query}
+        if filters:
+            params.update({str(k): str(v) for k, v in filters.items()})
+
+        try:
+            return self.follow_link(search_link, **params)
+        except OPDSHTTPError as e:
+            raise SearchError(f"Search failed: {e}") from e
+
+    def get_next_page(self, feed: "OPDSFeed") -> Optional["OPDSFeed"]:
+        """Get the next page of results.
+
+        Args:
+            feed: Current OPDS feed.
+
+        Returns:
+            Next page OPDSFeed or None if no next page.
+        """
+        next_link = feed.get_next_link()
+        if next_link is None:
+            return None
+
+        return self.follow_link(next_link)
+
+    def get_previous_page(self, feed: "OPDSFeed") -> Optional["OPDSFeed"]:
+        """Get the previous page of results.
+
+        Args:
+            feed: Current OPDS feed.
+
+        Returns:
+            Previous page OPDSFeed or None if no previous page.
+        """
+        prev_link = feed.get_previous_link()
+        if prev_link is None:
+            return None
+
+        return self.follow_link(prev_link)
+
+    def get_first_page(self, feed: "OPDSFeed") -> Optional["OPDSFeed"]:
+        """Get the first page of results.
+
+        Args:
+            feed: Current OPDS feed.
+
+        Returns:
+            First page OPDSFeed or None if already on first page.
+        """
+        first_link = feed.get_first_link()
+        if first_link is None:
+            return None
+
+        return self.follow_link(first_link)
+
+    def get_last_page(self, feed: "OPDSFeed") -> Optional["OPDSFeed"]:
+        """Get the last page of results.
+
+        Args:
+            feed: Current OPDS feed.
+
+        Returns:
+            Last page OPDSFeed or None if already on last page.
+        """
+        last_link = feed.get_last_link()
+        if last_link is None:
+            return None
+
+        return self.follow_link(last_link)
+
+    def follow_navigation(self, feed: "OPDSFeed", title: str) -> "OPDSFeed":
+        """Follow a navigation link by title.
+
+        Args:
+            feed: OPDS feed with navigation.
+            title: Title of navigation link to follow.
+
+        Returns:
+            Parsed OPDSFeed object.
+
+        Raises:
+            OPDSNavigationError: If navigation link not found.
+        """
+        if feed.navigation is None:
+            raise OPDSNavigationError("Feed has no navigation links")
+
+        for nav_link in feed.navigation:
+            if nav_link.title == title:
+                return self.follow_link(nav_link)
+
+        raise OPDSNavigationError(f"Navigation link with title '{title}' not found")
+
+    def follow_facet(
+        self, feed: "OPDSFeed", facet_title: str, link_title: str
+    ) -> "OPDSFeed":
+        """Follow a facet link by facet and link title.
+
+        Args:
+            feed: OPDS feed with facets.
+            facet_title: Title of the facet group.
+            link_title: Title of the facet link to follow.
+
+        Returns:
+            Parsed OPDSFeed object.
+
+        Raises:
+            OPDSNavigationError: If facet or link not found.
+        """
+        facet = feed.get_facets_by_title(facet_title)
+        if facet is None:
+            raise OPDSNavigationError(f"Facet '{facet_title}' not found")
+
+        link = facet.get_facet_by_title(link_title)
+        if link is None:
+            raise OPDSNavigationError(f"Facet link '{link_title}' not found")
+
+        return self.follow_link(link)
+
+    def close(self) -> None:
+        """Close the underlying session."""
+        self.session.close()
+
+    def __enter__(self) -> "OPDSClient":
+        """Context manager entry."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[object],
+    ) -> None:
+        """Context manager exit."""
+        self.close()

opds_client/exceptions.py

@@ -0,0 +1,93 @@
+"""Custom exceptions for OPDS client."""
+
+from __future__ import annotations
+
+
+class OPDSClientError(Exception):
+    """Base exception for OPDS client errors."""
+
+    pass
+
+
+class OPDSParseError(OPDSClientError):
+    """Error parsing OPDS JSON."""
+
+    def __init__(self, message: str, original_error: Exception | None = None):
+        """Initialize OPDSParseError.
+
+        Args:
+            message: Error message.
+            original_error: Original exception that caused this error.
+        """
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class OPDSValidationError(OPDSClientError):
+    """Error validating OPDS data against schema."""
+
+    def __init__(self, message: str, validation_errors: list[str] | None = None):
+        """Initialize OPDSValidationError.
+
+        Args:
+            message: Error message.
+            validation_errors: List of validation error details.
+        """
+        super().__init__(message)
+        self.validation_errors = validation_errors or []
+
+
+class InvalidOPDSFeedError(OPDSValidationError):
+    """Feed doesn't meet OPDS 2.0 requirements."""
+
+    pass
+
+
+class OPDSHTTPError(OPDSClientError):
+    """HTTP error from OPDS server."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        url: str,
+        response_body: str | None = None,
+    ):
+        """Initialize OPDSHTTPError.
+
+        Args:
+            message: Error message.
+            status_code: HTTP status code.
+            url: URL that caused the error.
+            response_body: Optional response body for debugging.
+        """
+        super().__init__(message)
+        self.status_code = status_code
+        self.url = url
+        self.response_body = response_body
+
+
+class OPDSNavigationError(OPDSClientError):
+    """Error navigating OPDS feed."""
+
+    pass
+
+
+class OPDSRetryError(OPDSClientError):
+    """Error indicating operation should be retried."""
+
+    def __init__(self, message: str, retry_after: int | None = None):
+        """Initialize OPDSRetryError.
+
+        Args:
+            message: Error message.
+            retry_after: Optional seconds to wait before retrying.
+        """
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class SearchError(OPDSClientError):
+    """Error during search operation."""
+
+    pass

opds_client/models/__init__.py

@@ -0,0 +1,51 @@
+"""Pydantic models exports."""
+
+from opds_client.models.acquisition import (
+    AcquisitionFlow,
+    AcquisitionManager,
+)
+from opds_client.models.base import (
+    FacetLink,
+    ImageLink,
+    IndirectAcquisition,
+    Link,
+    Metadata,
+    NavigationLink,
+    Price,
+)
+from opds_client.models.feed import (
+    Collection,
+    Facet,
+    Group,
+    OPDSFeed,
+)
+from opds_client.models.publication import (
+    AcquisitionLink,
+    BelongsTo,
+    Contributor,
+    OPDSPublication,
+    Publication,
+    Series,
+)
+
+__all__ = [
+    "Link",
+    "Metadata",
+    "NavigationLink",
+    "ImageLink",
+    "FacetLink",
+    "Price",
+    "IndirectAcquisition",
+    "Contributor",
+    "Series",
+    "BelongsTo",
+    "AcquisitionLink",
+    "Publication",
+    "OPDSPublication",
+    "Collection",
+    "Facet",
+    "Group",
+    "OPDSFeed",
+    "AcquisitionFlow",
+    "AcquisitionManager",
+]

opds_client/models/acquisition.py

@@ -0,0 +1,85 @@
+"""Acquisition models for OPDS 2.0."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from opds_client.models.base import Link
+
+
+class AcquisitionFlow(BaseModel):
+    """Represents an acquisition flow with multiple steps."""
+
+    link: Link
+    indirect_acquisition: Optional[list["AcquisitionFlow"]] = Field(
+        default=None, alias="indirectAcquisition"
+    )
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    def get_final_link(self) -> Link:
+        """Get the final link in the acquisition chain.
+
+        Returns the deepest link in the indirect acquisition chain.
+        If there are no indirect acquisitions, returns the current link.
+        """
+        if not self.indirect_acquisition:
+            return self.link
+
+        current = self
+        while current.indirect_acquisition:
+            current = current.indirect_acquisition[0]
+        return current.link
+
+
+class AcquisitionManager:
+    """Manager for handling acquisition flows."""
+
+    def __init__(self, link: Link):
+        """Initialize with an acquisition link."""
+        self.link = link
+        self.flows: list[AcquisitionFlow] = []
+
+    def add_flow(self, flow: AcquisitionFlow) -> None:
+        """Add an acquisition flow."""
+        self.flows.append(flow)
+
+    def get_open_access_link(self) -> Optional[Link]:
+        """Get an open access link if available."""
+        if self.link.rel == "open-access":
+            return self.link
+        return None
+
+    def get_buy_link(self) -> Optional[Link]:
+        """Get a buy link if available."""
+        if self.link.rel == "buy" or (
+            isinstance(self.link.rel, list) and "buy" in self.link.rel
+        ):
+            return self.link
+        return None
+
+    def get_borrow_link(self) -> Optional[Link]:
+        """Get a borrow link if available."""
+        if self.link.rel == "borrow" or (
+            isinstance(self.link.rel, list) and "borrow" in self.link.rel
+        ):
+            return self.link
+        return None
+
+    def get_subscribe_link(self) -> Optional[Link]:
+        """Get a subscribe link if available."""
+        if self.link.rel == "subscribe" or (
+            isinstance(self.link.rel, list) and "subscribe" in self.link.rel
+        ):
+            return self.link
+        return None
+
+    def get_download_link(self) -> Optional[Link]:
+        """Get a download link if available."""
+        if self.link.rel == "download" or (
+            isinstance(self.link.rel, list) and "download" in self.link.rel
+        ):
+            return self.link
+        return None