aletheca 0.1.0__py3-none-any.whl

aletheca/__init__.py

@@ -0,0 +1,64 @@
+"""Aletheca: Python interface for the OpenAlex API."""
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _get_version
+
+    __version__ = _get_version("aletheca")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+from bibliofabric.exceptions import (
+    APIError,
+    AuthError,
+    BibliofabricError,
+    ConfigurationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    TimeoutError,
+    ValidationError,
+)
+
+from .client import AlethecaClient
+from .models import (
+    ApiResponse,
+    Author,
+    Award,
+    BaseEntity,
+    Funder,
+    Institution,
+    Keyword,
+    Meta,
+    Publisher,
+    Source,
+    Topic,
+    Work,
+)
+from .session import AlethecaSession
+
+__all__ = [
+    "__version__",
+    "APIError",
+    "ApiResponse",
+    "AuthError",
+    "Award",
+    "Author",
+    "BaseEntity",
+    "BibliofabricError",
+    "ConfigurationError",
+    "Funder",
+    "Institution",
+    "Keyword",
+    "Meta",
+    "NetworkError",
+    "NotFoundError",
+    "Publisher",
+    "RateLimitError",
+    "Source",
+    "AlethecaClient",
+    "AlethecaSession",
+    "TimeoutError",
+    "Topic",
+    "ValidationError",
+    "Work",
+]

aletheca/_helpers.py

@@ -0,0 +1,105 @@
+"""Utility helpers for working with OpenAlex identifiers and data."""
+
+from __future__ import annotations
+
+import re
+
+
+def normalize_doi(doi: str) -> str:
+    """Normalize a DOI to its bare form (no URL prefix).
+
+    Args:
+        doi: A DOI string, possibly with ``https://doi.org/`` prefix.
+
+    Returns:
+        The bare DOI string.
+
+    Examples:
+        >>> normalize_doi("https://doi.org/10.1234/x")
+        "10.1234/x"
+        >>> normalize_doi("10.1234/x")
+        "10.1234/x"
+    """
+    doi = doi.strip()
+    for prefix in ("https://doi.org/", "http://doi.org/", "doi.org/"):
+        if doi.startswith(prefix):
+            return doi[len(prefix) :]
+    return doi
+
+
+def parse_openalex_id(url_or_id: str) -> str:
+    """Extract the short OpenAlex ID from a full URL or bare ID.
+
+    Args:
+        url_or_id: An OpenAlex ID or URL (e.g., ``https://openalex.org/W123``).
+
+    Returns:
+        The short ID (e.g., ``W123``).
+
+    Examples:
+        >>> parse_openalex_id("https://openalex.org/W1234567890")
+        "W1234567890"
+        >>> parse_openalex_id("W1234567890")
+        "W1234567890"
+    """
+    url_or_id = url_or_id.strip()
+    match = re.search(r"([WAITSFPDC]\d+)", url_or_id)
+    if match:
+        return match.group(1)
+    return url_or_id
+
+
+def detect_id_type(identifier: str) -> str | None:
+    """Detect the type of a scholarly identifier.
+
+    Args:
+        identifier: A string identifier.
+
+    Returns:
+        One of ``"openalex"``, ``"doi"``, ``"pmid"``, ``"orcid"``,
+        ``"issn"``, ``"ror"``, or ``None``.
+    """
+    identifier = identifier.strip()
+    if re.match(r"^[WAITSFPDC]\d+$", identifier, re.IGNORECASE):
+        return "openalex"
+    identifier_lower = identifier.lower()
+    if identifier_lower.startswith("10.") or "doi.org/" in identifier_lower:
+        return "doi"
+    if re.match(r"^\d{4}-\d{3,4}$", identifier_lower):
+        return "issn"
+    if re.match(r"^\d{7,8}$", identifier_lower):
+        return "pmid"
+    if identifier_lower.startswith("https://orcid.org/") or re.match(
+        r"\d{4}-\d{4}-\d{4}-\d{4}", identifier_lower
+    ):
+        return "orcid"
+    if identifier_lower.startswith("https://ror.org/") or re.match(
+        r"^0[a-hj-km-np-tv-z]{2,3}\w{3,14}$", identifier_lower
+    ):
+        return "ror"
+    return None
+
+
+def reconstruct_abstract(
+    inverted_index: dict[str, list[int]] | None,
+) -> str | None:
+    """Reconstruct an abstract from OpenAlex's inverted index format.
+
+    Args:
+        inverted_index: Mapping of word → list of positions.
+
+    Returns:
+        The reconstructed abstract string, or None if input is None/empty.
+    """
+    if not inverted_index:
+        return None
+
+    words: dict[int, str] = {}
+    for word, positions in inverted_index.items():
+        for pos in positions:
+            words[pos] = word
+
+    if not words:
+        return None
+
+    return " ".join(words[i] for i in sorted(words.keys()))

aletheca/client.py

@@ -0,0 +1,162 @@
+"""AlethecaClient — async client for the OpenAlex API."""
+
+from bibliofabric.auth import AuthStrategy, NoAuth, QueryParameterAuth
+from bibliofabric.client import BaseApiClient
+from bibliofabric.log_config import logger
+
+from .config import AlethecaSettings, get_settings
+from .constants import OPENALEX_API_BASE_URL
+from .unwrapper import OpenAlexUnwrapper
+
+
+class AlethecaClient(BaseApiClient):
+    """Asynchronous client for the OpenAlex API.
+
+    Provides access to all OpenAlex entity endpoints through typed resource
+    client properties.
+
+    Usage::
+
+        async with AlethecaClient() as client:
+            work = await client.works.get("W1234567890")
+    """
+
+    def __init__(
+        self,
+        settings: AlethecaSettings | None = None,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        auth_strategy: AuthStrategy | None = None,
+    ):
+        """Initialize the AlethecaClient.
+
+        Args:
+            settings: Optional AlethecaSettings instance. If None, loads from env.
+            api_key: Optional OpenAlex API key (overrides settings). Ignored
+                when ``auth_strategy`` is also provided.
+            base_url: Optional API base URL override.
+            auth_strategy: Optional auth strategy override. When provided,
+                takes precedence over ``api_key``.
+        """
+        self._settings = settings or get_settings()
+        resolved_api_key = api_key or self._settings.openalex_api_key
+        resolved_base_url = base_url or OPENALEX_API_BASE_URL
+
+        if auth_strategy is not None:
+            auth = auth_strategy
+        else:
+            auth = self._resolve_auth(resolved_api_key)
+
+        super().__init__(
+            settings=self._settings,
+            response_unwrapper=OpenAlexUnwrapper(),
+            auth_strategy=auth,
+            base_url=resolved_base_url,
+        )
+
+        # Resource clients will be initialized lazily as properties
+        self._works = None
+        self._authors = None
+        self._sources = None
+        self._institutions = None
+        self._topics = None
+        self._keywords = None
+        self._publishers = None
+        self._funders = None
+        self._awards = None
+
+        logger.debug("AlethecaClient initialized successfully.")
+
+    @staticmethod
+    def _resolve_auth(api_key: str | None) -> AuthStrategy:
+        """Resolve the authentication strategy.
+
+        OpenAlex uses query-parameter auth (api_key), not header-based.
+        """
+        if api_key:
+            return QueryParameterAuth(key_name="api_key", key_value=api_key)
+        return NoAuth()
+
+    # --- Resource client properties (lazy init) ---
+
+    @property
+    def works(self):
+        """Access the Works endpoint client."""
+        if self._works is None:
+            from .resources import WorksClient
+
+            self._works = WorksClient(self)
+        return self._works
+
+    @property
+    def authors(self):
+        """Access the Authors endpoint client."""
+        if self._authors is None:
+            from .resources import AuthorsClient
+
+            self._authors = AuthorsClient(self)
+        return self._authors
+
+    @property
+    def sources(self):
+        """Access the Sources endpoint client."""
+        if self._sources is None:
+            from .resources import SourcesClient
+
+            self._sources = SourcesClient(self)
+        return self._sources
+
+    @property
+    def institutions(self):
+        """Access the Institutions endpoint client."""
+        if self._institutions is None:
+            from .resources import InstitutionsClient
+
+            self._institutions = InstitutionsClient(self)
+        return self._institutions
+
+    @property
+    def topics(self):
+        """Access the Topics endpoint client."""
+        if self._topics is None:
+            from .resources import TopicsClient
+
+            self._topics = TopicsClient(self)
+        return self._topics
+
+    @property
+    def keywords(self):
+        """Access the Keywords endpoint client."""
+        if self._keywords is None:
+            from .resources import KeywordsClient
+
+            self._keywords = KeywordsClient(self)
+        return self._keywords
+
+    @property
+    def publishers(self):
+        """Access the Publishers endpoint client."""
+        if self._publishers is None:
+            from .resources import PublishersClient
+
+            self._publishers = PublishersClient(self)
+        return self._publishers
+
+    @property
+    def funders(self):
+        """Access the Funders endpoint client."""
+        if self._funders is None:
+            from .resources import FundersClient
+
+            self._funders = FundersClient(self)
+        return self._funders
+
+    @property
+    def awards(self):
+        """Access the Awards endpoint client."""
+        if self._awards is None:
+            from .resources import AwardsClient
+
+            self._awards = AwardsClient(self)
+        return self._awards

aletheca/config.py

@@ -0,0 +1,45 @@
+"""Aletheca-specific settings for the OpenAlex API client."""
+
+from functools import lru_cache
+
+from bibliofabric.config import BaseApiSettings
+from pydantic import Field
+from pydantic_settings import SettingsConfigDict
+
+from .constants import DEFAULT_USER_AGENT
+
+
+class AlethecaSettings(BaseApiSettings):
+    """OpenAlex-specific settings.
+
+    Inherits all generic API client settings from BaseApiSettings and adds
+    OpenAlex-specific configuration.
+
+    Settings are loaded from environment variables (prefixed with 'ALETHECA_')
+    or .env/secrets.env files.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=(".env", "secrets.env"),
+        env_file_encoding="utf-8",
+        env_prefix="ALETHECA_",
+        extra="ignore",
+        case_sensitive=False,
+        arbitrary_types_allowed=True,
+    )
+
+    user_agent: str = Field(
+        default=DEFAULT_USER_AGENT,
+        description="User-Agent header for requests",
+    )
+
+    openalex_api_key: str | None = Field(
+        default=None,
+        description="OpenAlex API key for the polite pool",
+    )
+
+
+@lru_cache
+def get_settings() -> AlethecaSettings:
+    """Provide cached access to application settings."""
+    return AlethecaSettings()

aletheca/constants.py

@@ -0,0 +1,21 @@
+"""Constants used throughout the Aletheca library."""
+
+from importlib.metadata import PackageNotFoundError, version as _get_version
+
+OPENALEX_API_BASE_URL = "https://api.openalex.org"
+
+DEFAULT_TIMEOUT: int = 30
+DEFAULT_RETRIES: int = 3
+DEFAULT_PAGE_SIZE: int = 25
+ITERATE_PAGE_SIZE: int = 200  # OpenAlex allows up to 200 per_page for cursor pagination
+
+try:
+    __version__: str = _get_version("aletheca")
+except PackageNotFoundError:
+    __version__: str = "0.0.0"
+
+DEFAULT_USER_AGENT: str = f"aletheca/{__version__}"
+CLIENT_HEADERS: dict[str, str] = {
+    "accept": "application/json",
+    "User-Agent": DEFAULT_USER_AGENT,
+}