aletheca 0.1.0__tar.gz

aletheca-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.3
+Name: aletheca
+Version: 0.1.0
+Summary: Python interface for the OpenAlex API, built on top of the bibliofabric framework.
+Author: Samuel Mok
+Author-email: Samuel Mok <s.mok@utwente.nl>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: AsyncIO
+Classifier: Typing :: Typed
+Requires-Dist: bibliofabric>=0.4.1,<0.5.0
+Requires-Dist: polars ; extra == 'analysis'
+Requires-Dist: duckdb>=1.3.0 ; extra == 'analysis'
+Requires-Dist: matplotlib>=3.8.0 ; extra == 'analysis'
+Requires-Dist: rich>=13.0.0 ; extra == 'analysis'
+Requires-Dist: pandas>=2.1.0 ; extra == 'analysis'
+Requires-Dist: numpy>=1.26.0 ; extra == 'analysis'
+Requires-Dist: pyarrow>=14.0.0 ; extra == 'analysis'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/utsmok/aletheca
+Provides-Extra: analysis
+Description-Content-Type: text/markdown
+
+# Aletheca: Asynchronous Python client for the OpenAlex API
+
+Samuel Mok -- s.mok@utwente.nl -- 2025-2026
+
+Aletheca is an async Python client for the [OpenAlex API](https://docs.openalex.org/), built on [bibliofabric](https://github.com/utsmok/bibliofabric).
+
+**Docs:** [utsmok.github.io/aletheca](https://utsmok.github.io/aletheca/) -- **PyPI:** [aletheca](https://pypi.org/project/aletheca/) -- **License:** MIT
+
+## Features
+
+- **Async by design** -- built on `httpx` + `asyncio` with proper connection pooling
+- **Typed throughout** -- Pydantic v2 models for all entities, PEP 561 `py.typed` marker
+- **Cursor pagination** -- efficient iteration over large result sets via cursor-based auto-pagination
+- **Filter serialization** -- automatic conversion to OpenAlex `filter=key:value` syntax with Pydantic filter models
+- **Safe types** -- `SafeList` and `SafeStr` for None-safe traversal of API responses
+- **Convenience queries** -- high-level functions for common workflows (`works_by_author`, `citing_works`, etc.)
+
+## Installation
+
+```bash
+uv add aletheca
+```
+
+Or with pip: `pip install aletheca`. Requires Python >=3.12.
+
+## Quick Start
+
+```python
+import asyncio
+from aletheca import AlethecaSession
+
+async def main():
+    async with AlethecaSession() as session:
+        # Get a work by OpenAlex ID
+        work = await session.works.get("W1234567890")
+        print(work.title)
+
+        # Search works
+        results = await session.works.search(search="machine learning", page_size=10)
+        for work in results.results:
+            print(f"{work.title} ({work.publication_year})")
+
+        # Iterate all works by an author (cursor-based auto-pagination)
+        async for work in session.works.iterate(
+            filters={"authorships.author.id": "A1234567890"},
+            page_size=200,
+        ):
+            print(work.title)
+
+asyncio.run(main())
+```
+
+No authentication required -- the OpenAlex API works without it. For higher rate limits, see [Authentication](#authentication).
+
+## Examples
+
+All examples in [`examples/`](examples/) are dual-purpose -- run as scripts or as interactive [marimo](https://marimo.io) notebooks:
+
+```bash
+# As a script
+uv run examples/simple_example.py
+
+# As an interactive notebook
+uv run marimo edit examples/simple_example.py
+```
+
+| Script | Description |
+|--------|-------------|
+| `simple_example.py` | Search, iterate, get works |
+| `02_filtering_and_search.py` | WorksFilters, AuthorsFilters, and other filter models |
+| `03_institution_research.py` | Works by institution, topic analysis |
+| `04_author_discovery.py` | Find authors, retrieve their works |
+| `05_advanced_queries.py` | Cursor pagination, select fields, sort |
+| `06_convenience_queries.py` | `session.queries.*` convenience functions |
+| `07_iterator_helpers.py` | `collect()`, `count()`, `first()` from bibliofabric mixins |
+| `08_safe_types_and_helpers.py` | SafeList, SafeStr, DOI normalization, abstract reconstruction |
+
+## Authentication
+
+Aletheca auto-detects the OpenAlex API key from environment variables or `.env` files (prefixed with `ALETHECA_`). No auth is the default if nothing is configured.
+
+```dotenv
+ALETHECA_OPENALEX_API_KEY=your_api_key
+```
+
+Or pass explicitly:
+
+```python
+async with AlethecaSession(api_key="your_api_key") as session:
+    ...
+```
+
+With an API key you get faster responses (dedicated pool). Without one, you use the polite pool (slower).
+
+## Basic Usage
+
+### Get a single entity
+
+```python
+work = await session.works.get("W2741809801")
+print(work.title, work.doi, work.publication_year)
+```
+
+### Search
+
+```python
+results = await session.works.search(search="machine learning", page_size=5)
+for work in results.results:
+    print(work.title)
+```
+
+### Iterate all results
+
+```python
+async for work in session.works.iterate(
+    filters={"publication_year": 2024, "is_oa": True},
+    page_size=200,
+):
+    print(work.title)
+    break  # stop when you want
+```
+
+### Convenience queries
+
+```python
+citations = await session.queries.citing_works("W2741809801")
+print(f"{len(citations)} citations")
+```
+
+## Known OpenAlex API Issues
+
+Full bug report with reproduction steps: [`OPENALEX_BUG_REPORT.md`](OPENALEX_BUG_REPORT.md).
+
+- **OpenAPI spec is substantially incomplete** -- 50+ fields returned by the live API are missing from the spec schemas across all entity types. Several spec fields don't exist in the live API.
+- **Wrong field names in spec** -- `content_url` (spec) vs `content_urls` (live), `grants_count` (spec) vs `awards_count` (live)
+- **Undocumented fields** -- `institution_awarded` on Awards is not documented anywhere; 15+ nested Award filters are missing from the docs filter table
+- **Awards endpoint missing from `llms.txt`** -- the awards endpoint is not listed in the API quick reference
+- **`per_page` max is 200, not 100** -- documented as 100 but the API accepts 200
+
+## Development
+
+```bash
+uv sync --all-groups --all-extras         # install everything
+uv run ruff check src/ --fix              # lint
+uv run ruff format src/                   # format
+uvx ty check src/                         # type check
+uv run pytest tests/                      # run tests
+uv run pytest --cov=aletheca tests/       # coverage (CI threshold: 95%)
+uv build                                  # build package
+uv run mkdocs serve                       # local docs
+```
+
+Contributions welcome -- see [Contributing](https://utsmok.github.io/aletheca/contributing/).
+
+## License
+
+MIT

aletheca-0.1.0/README.md

@@ -0,0 +1,157 @@
+# Aletheca: Asynchronous Python client for the OpenAlex API
+
+Samuel Mok -- s.mok@utwente.nl -- 2025-2026
+
+Aletheca is an async Python client for the [OpenAlex API](https://docs.openalex.org/), built on [bibliofabric](https://github.com/utsmok/bibliofabric).
+
+**Docs:** [utsmok.github.io/aletheca](https://utsmok.github.io/aletheca/) -- **PyPI:** [aletheca](https://pypi.org/project/aletheca/) -- **License:** MIT
+
+## Features
+
+- **Async by design** -- built on `httpx` + `asyncio` with proper connection pooling
+- **Typed throughout** -- Pydantic v2 models for all entities, PEP 561 `py.typed` marker
+- **Cursor pagination** -- efficient iteration over large result sets via cursor-based auto-pagination
+- **Filter serialization** -- automatic conversion to OpenAlex `filter=key:value` syntax with Pydantic filter models
+- **Safe types** -- `SafeList` and `SafeStr` for None-safe traversal of API responses
+- **Convenience queries** -- high-level functions for common workflows (`works_by_author`, `citing_works`, etc.)
+
+## Installation
+
+```bash
+uv add aletheca
+```
+
+Or with pip: `pip install aletheca`. Requires Python >=3.12.
+
+## Quick Start
+
+```python
+import asyncio
+from aletheca import AlethecaSession
+
+async def main():
+    async with AlethecaSession() as session:
+        # Get a work by OpenAlex ID
+        work = await session.works.get("W1234567890")
+        print(work.title)
+
+        # Search works
+        results = await session.works.search(search="machine learning", page_size=10)
+        for work in results.results:
+            print(f"{work.title} ({work.publication_year})")
+
+        # Iterate all works by an author (cursor-based auto-pagination)
+        async for work in session.works.iterate(
+            filters={"authorships.author.id": "A1234567890"},
+            page_size=200,
+        ):
+            print(work.title)
+
+asyncio.run(main())
+```
+
+No authentication required -- the OpenAlex API works without it. For higher rate limits, see [Authentication](#authentication).
+
+## Examples
+
+All examples in [`examples/`](examples/) are dual-purpose -- run as scripts or as interactive [marimo](https://marimo.io) notebooks:
+
+```bash
+# As a script
+uv run examples/simple_example.py
+
+# As an interactive notebook
+uv run marimo edit examples/simple_example.py
+```
+
+| Script | Description |
+|--------|-------------|
+| `simple_example.py` | Search, iterate, get works |
+| `02_filtering_and_search.py` | WorksFilters, AuthorsFilters, and other filter models |
+| `03_institution_research.py` | Works by institution, topic analysis |
+| `04_author_discovery.py` | Find authors, retrieve their works |
+| `05_advanced_queries.py` | Cursor pagination, select fields, sort |
+| `06_convenience_queries.py` | `session.queries.*` convenience functions |
+| `07_iterator_helpers.py` | `collect()`, `count()`, `first()` from bibliofabric mixins |
+| `08_safe_types_and_helpers.py` | SafeList, SafeStr, DOI normalization, abstract reconstruction |
+
+## Authentication
+
+Aletheca auto-detects the OpenAlex API key from environment variables or `.env` files (prefixed with `ALETHECA_`). No auth is the default if nothing is configured.
+
+```dotenv
+ALETHECA_OPENALEX_API_KEY=your_api_key
+```
+
+Or pass explicitly:
+
+```python
+async with AlethecaSession(api_key="your_api_key") as session:
+    ...
+```
+
+With an API key you get faster responses (dedicated pool). Without one, you use the polite pool (slower).
+
+## Basic Usage
+
+### Get a single entity
+
+```python
+work = await session.works.get("W2741809801")
+print(work.title, work.doi, work.publication_year)
+```
+
+### Search
+
+```python
+results = await session.works.search(search="machine learning", page_size=5)
+for work in results.results:
+    print(work.title)
+```
+
+### Iterate all results
+
+```python
+async for work in session.works.iterate(
+    filters={"publication_year": 2024, "is_oa": True},
+    page_size=200,
+):
+    print(work.title)
+    break  # stop when you want
+```
+
+### Convenience queries
+
+```python
+citations = await session.queries.citing_works("W2741809801")
+print(f"{len(citations)} citations")
+```
+
+## Known OpenAlex API Issues
+
+Full bug report with reproduction steps: [`OPENALEX_BUG_REPORT.md`](OPENALEX_BUG_REPORT.md).
+
+- **OpenAPI spec is substantially incomplete** -- 50+ fields returned by the live API are missing from the spec schemas across all entity types. Several spec fields don't exist in the live API.
+- **Wrong field names in spec** -- `content_url` (spec) vs `content_urls` (live), `grants_count` (spec) vs `awards_count` (live)
+- **Undocumented fields** -- `institution_awarded` on Awards is not documented anywhere; 15+ nested Award filters are missing from the docs filter table
+- **Awards endpoint missing from `llms.txt`** -- the awards endpoint is not listed in the API quick reference
+- **`per_page` max is 200, not 100** -- documented as 100 but the API accepts 200
+
+## Development
+
+```bash
+uv sync --all-groups --all-extras         # install everything
+uv run ruff check src/ --fix              # lint
+uv run ruff format src/                   # format
+uvx ty check src/                         # type check
+uv run pytest tests/                      # run tests
+uv run pytest --cov=aletheca tests/       # coverage (CI threshold: 95%)
+uv build                                  # build package
+uv run mkdocs serve                       # local docs
+```
+
+Contributions welcome -- see [Contributing](https://utsmok.github.io/aletheca/contributing/).
+
+## License
+
+MIT

aletheca-0.1.0/pyproject.toml

@@ -0,0 +1,119 @@
+[project]
+name = "aletheca"
+version = "0.1.0"
+description = "Python interface for the OpenAlex API, built on top of the bibliofabric framework."
+authors = [
+    {name = "Samuel Mok", email = "s.mok@utwente.nl"}
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.12"
+dependencies = [
+    "bibliofabric>=0.4.1,<0.5.0",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: AsyncIO",
+    "Typing :: Typed",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.26.0",
+    "pytest-cov>=6.1.1",
+    "pytest-httpx>=0.35.0",
+    "python-dotenv>=1.0.0",
+]
+docs = [
+    "mkdocs~=1.6.0",
+    "mkdocs-material~=9.5.0",
+    "mkdocstrings[python]",
+]
+lint = ["ruff>=0.8.0"]
+test = ["pytest", "pytest-randomly"]
+
+[project.optional-dependencies]
+analysis = [
+    "polars",
+    "duckdb>=1.3.0",
+    "matplotlib>=3.8.0",
+    "rich>=13.0.0",
+    "pandas>=2.1.0",
+    "numpy>=1.26.0",
+    "pyarrow>=14.0.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/utsmok/aletheca"
+
+[build-system]
+requires = ["uv_build>=0.11.19,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.pip]
+generate-hashes = true
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.format]
+docstring-code-format = true
+docstring-code-line-length = 60
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I", # isort
+    "B", # bugbear -- flake8 bugfinder
+    "Q", # correct quotes usage
+    "PTH",  # Replace os functions with pathlib functions
+    "SIM", # Simplify statements
+    "RET", # Return value related rules
+    "PIE", # misc flake8 rules
+    "FBT", # boolean traps
+    "PERF", # performance optimization
+    "PL", # pylint
+    "UP", # check for deprecated ways of coding
+    "FURB",
+]
+ignore = ["PLR2004"]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"**/client.py" = ["PLR0913", "PLR0912", "PLR0915", "PLC0415"]
+"**/session.py" = ["PLC0415"]
+"**/queries.py" = ["PLC0415"]
+"**/endpoints.py" = ["PLR0913"]
+"examples/**/*.py" = ["PLC0415", "F821", "PERF401", "B007", "F841"]
+"marimo_checks/**/*.py" = ["PLC0415", "F821", "F841", "B905", "PLW2901", "I001", "PLR1711", "F404", "UP037"]
+
+[tool.ruff.lint.pylint]
+max-args = 10
+max-branches = 25
+max-statements = 75
+max-returns = 10
+
+[tool.pytest.ini_options]
+pythonpath = [
+  "src"
+]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_functions = "test_*"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+markers = [
+    "live_api: marks tests that hit the live OpenAlex API (requires API key, skipped in CI)",
+]
+addopts = "-m 'not live_api'"

aletheca-0.1.0/src/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-0.1.0/src/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()))