From a926e167da58a486bbec17c1a1d5f01f94f867a1 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Fri, 3 Jul 2026 18:06:07 -0500 Subject: [PATCH 01/24] fix(client): handle integer pagination cursors from export API The Readwise export API returns integer `nextPageCursor` values, but `parse_pagination_cursor` called `.startswith("http")` on the raw value, crashing with `AttributeError` on non-string cursors. Add `str()` coercion before the string check. This was previously worked around by a monkey-patch in highlight_helper. Co-Authored-By: Claude Fable 5 --- src/readwise_sdk/_utils.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/readwise_sdk/_utils.py b/src/readwise_sdk/_utils.py index f9df35a..341e648 100644 --- a/src/readwise_sdk/_utils.py +++ b/src/readwise_sdk/_utils.py @@ -84,6 +84,7 @@ def parse_pagination_cursor( Returns: Tuple of (url, params) for the next request. """ + next_cursor = str(next_cursor) # Handle integer cursors from export API if next_cursor.startswith("http"): parsed = urlparse(next_cursor) url = f"{parsed.scheme}://{parsed.netloc}{parsed.path}" From f836514297b22fec4b5f97c66bef01f3fa2e5739 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 20:46:06 -0500 Subject: [PATCH 02/24] feat(mcp): add MCP server as the readwise-plus[mcp] extra Fold the standalone readwise-mcp server into readwise-plus as an optional interface, alongside the existing [cli] extra. - New readwise_sdk.mcp package (server + console entry point) exposing 9 agent-friendly tools over the SDK: documents (v3), highlights + books (v2). - New `mcp` optional-dependency and `readwise-mcp` console script (also runnable as `python -m readwise_sdk.mcp`). - Tests under tests/mcp/ (28 unit tests, mocked HTTP; live tests gated on READWISE_API_KEY). Graceful collect_ignore + importorskip when the extra isn't installed, mirroring the cli pattern. mcp added to the dev group so CI exercises it; ty excludes the FastMCP module like it does for cli. - README: MCP Server section, install extra, ToC entry. Co-Authored-By: Claude Opus 4.8 (1M context) --- Justfile | 2 +- README.md | 43 +++ pyproject.toml | 5 + src/readwise_sdk/mcp/__init__.py | 5 + src/readwise_sdk/mcp/__main__.py | 5 + src/readwise_sdk/mcp/server.py | 594 +++++++++++++++++++++++++++++++ tests/conftest.py | 5 + tests/mcp/__init__.py | 0 tests/mcp/conftest.py | 42 +++ tests/mcp/test_live.py | 107 ++++++ tests/mcp/test_tools.py | 416 ++++++++++++++++++++++ uv.lock | 448 ++++++++++++++++++++++- 12 files changed, 1669 insertions(+), 3 deletions(-) create mode 100644 src/readwise_sdk/mcp/__init__.py create mode 100644 src/readwise_sdk/mcp/__main__.py create mode 100644 src/readwise_sdk/mcp/server.py create mode 100644 tests/mcp/__init__.py create mode 100644 tests/mcp/conftest.py create mode 100644 tests/mcp/test_live.py create mode 100644 tests/mcp/test_tools.py diff --git a/Justfile b/Justfile index bd4ef33..555b058 100644 --- a/Justfile +++ b/Justfile @@ -16,7 +16,7 @@ lint-fix: uv run ruff check . --fix type: - uv run ty check . --exclude "src/readwise_sdk/cli/" --exclude "tests/test_cli.py" --exclude "tests/conftest.py" + uv run ty check . --exclude "src/readwise_sdk/cli/" --exclude "src/readwise_sdk/mcp/" --exclude "tests/test_cli.py" --exclude "tests/mcp/" --exclude "tests/conftest.py" test: uv run pytest diff --git a/README.md b/README.md index 852318a..c40f2d7 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ Comprehensive Python SDK for [Readwise](https://readwise.io) with high-level wor - [Workflows](#workflows) - [Contrib Interfaces](#contrib-interfaces) - [CLI](#cli) +- [MCP Server](#mcp-server) - [Development](#development) - [Contributing](#contributing) - [License](#license) @@ -44,6 +45,12 @@ With CLI support: pip install readwise-plus[cli] ``` +As an MCP server for AI agents: + +```bash +pip install readwise-plus[mcp] +``` + ## Quick Start ```python @@ -408,6 +415,42 @@ readwise sync full --output-dir ./data readwise sync incremental --state-file sync.json ``` +## MCP Server + +`readwise-plus` ships an optional [MCP](https://modelcontextprotocol.io) server that exposes Readwise and Reader operations as tools for AI agents (Claude Code, Claude Desktop, or any MCP client). It's a thin layer over the SDK — install the `mcp` extra and register the `readwise-mcp` command. + +### Register with Claude Code + +```bash +claude mcp add readwise --env READWISE_API_KEY=your-token -- uvx --from "readwise-plus[mcp]" readwise-mcp +``` + +### Register with any MCP client + +```json +{ + "mcpServers": { + "readwise": { + "command": "uvx", + "args": ["--from", "readwise-plus[mcp]", "readwise-mcp"], + "env": { "READWISE_API_KEY": "your-token" } + } + } +} +``` + +If `readwise-plus[mcp]` is already installed in the environment, run the `readwise-mcp` console script (equivalently `python -m readwise_sdk.mcp`) directly. + +### Tools + +Nine tools, backed by the SDK: + +- **Documents (Reader v3):** `save_to_reader`, `search_documents`, `get_document`, `update_document`, `delete_document` +- **Highlights (Readwise v2):** `get_highlights`, `export_highlights`, `create_highlight` +- **Books (Readwise v2):** `get_books` + +Auth comes from `READWISE_API_KEY` (an environment variable, or a `READWISE_API_KEY=` line in `~/.env`). Talk to your agent in natural language — "save this URL to my reading list", "find the article I archived about X" — and it picks the right tool. + ## Development ```bash diff --git a/pyproject.toml b/pyproject.toml index a8693c7..a9063d5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,6 +28,9 @@ cli = [ "typer>=0.21.0", "rich>=14.0.0", ] +mcp = [ + "mcp>=1.26.0", +] [project.urls] Homepage = "https://github.com/EvanOman/readwise-plus" @@ -36,6 +39,7 @@ Issues = "https://github.com/EvanOman/readwise-plus/issues" [project.scripts] readwise = "readwise_sdk.cli.main:app" +readwise-mcp = "readwise_sdk.mcp.server:main" [build-system] requires = ["hatchling"] @@ -52,6 +56,7 @@ dev = [ "respx>=0.22.0", "ruff>=0.14.0", "ty>=0.0.8", + "mcp>=1.26.0", "mkdocs>=1.6.1", "mkdocs-material>=9.7.1", "mkdocstrings[python]>=1.0.0", diff --git a/src/readwise_sdk/mcp/__init__.py b/src/readwise_sdk/mcp/__init__.py new file mode 100644 index 0000000..330f25b --- /dev/null +++ b/src/readwise_sdk/mcp/__init__.py @@ -0,0 +1,5 @@ +"""Readwise MCP server — an optional interface exposed via ``readwise-plus[mcp]``. + +Install with the ``mcp`` extra (``pip install readwise-plus[mcp]``) and run the +``readwise-mcp`` console script, or ``python -m readwise_sdk.mcp``. +""" diff --git a/src/readwise_sdk/mcp/__main__.py b/src/readwise_sdk/mcp/__main__.py new file mode 100644 index 0000000..aa224c1 --- /dev/null +++ b/src/readwise_sdk/mcp/__main__.py @@ -0,0 +1,5 @@ +"""Entry point for ``python -m readwise_sdk.mcp``.""" + +from readwise_sdk.mcp.server import main + +main() diff --git a/src/readwise_sdk/mcp/server.py b/src/readwise_sdk/mcp/server.py new file mode 100644 index 0000000..5c02838 --- /dev/null +++ b/src/readwise_sdk/mcp/server.py @@ -0,0 +1,594 @@ +"""Readwise MCP server — exposes Readwise/Reader operations as MCP tools. + +Tools are designed for agent ergonomics: fewer well-composed tools rather than +many thin wrappers. The server talks to Readwise through the readwise-plus SDK. + +Auth: reads ``READWISE_API_KEY`` from the environment, falling back to a +``READWISE_API_KEY=`` line in ``~/.env``. +""" + +from __future__ import annotations + +import json +import os +from datetime import datetime +from typing import Any + +from mcp.server.fastmcp import FastMCP + +from readwise_sdk import ( + AsyncReadwiseClient, + NotFoundError, + ReadwiseError, +) +from readwise_sdk.v2.models import HighlightCreate +from readwise_sdk.v3.models import DocumentCreate, DocumentLocation, DocumentUpdate + +# --------------------------------------------------------------------------- +# Server + client setup +# --------------------------------------------------------------------------- + +mcp = FastMCP( + "readwise", + instructions=( + "Readwise/Reader tools. Use save_to_reader to save URLs or upload content. " + "Use search_documents / get_document to find and read articles. " + "Use get_highlights / export_highlights for highlight data. " + "Use get_books to browse the library." + ), +) + + +def _get_api_key() -> str: + """Resolve the Readwise API key. + + Checks ``READWISE_API_KEY`` env var first, then falls back to a + ``READWISE_API_KEY=`` line in ``~/.env``. + """ + key = os.environ.get("READWISE_API_KEY", "") + if key: + return key + + env_file = os.path.expanduser("~/.env") + if os.path.isfile(env_file): + with open(env_file) as f: + for line in f: + line = line.strip() + if line.startswith("READWISE_API_KEY="): + return line.split("=", 1)[1].strip().strip("'\"") + + msg = "READWISE_API_KEY not found. Set it as an environment variable or add it to ~/.env" + raise RuntimeError(msg) + + +def _client() -> AsyncReadwiseClient: + """Create a fresh async client for each tool call.""" + return AsyncReadwiseClient(api_key=_get_api_key()) + + +def main() -> None: + """Console-script entry point: run the MCP server over stdio.""" + mcp.run() + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _doc_summary(doc: Any) -> dict[str, Any]: + """Compact summary of a Document for listing results.""" + return { + k: v + for k, v in { + "id": doc.id, + "title": doc.title, + "author": doc.author, + "url": doc.source_url or doc.url, + "category": doc.category.value if doc.category else None, + "location": doc.location.value if doc.location else None, + "tags": doc.tags or None, + "word_count": doc.word_count, + "reading_progress": doc.reading_progress, + "site_name": doc.site_name, + "published_date": doc.published_date.isoformat() if doc.published_date else None, + "saved_at": doc.saved_at.isoformat() if doc.saved_at else None, + }.items() + if v is not None + } + + +def _doc_full(doc: Any) -> dict[str, Any]: + """Full document representation including content.""" + result = _doc_summary(doc) + if doc.content: + result["content"] = doc.content + if doc.summary: + result["summary"] = doc.summary + if doc.notes: + result["notes"] = doc.notes + return result + + +def _highlight_summary(h: Any) -> dict[str, Any]: + """Compact summary of a Highlight.""" + return { + k: v + for k, v in { + "id": h.id, + "text": h.text, + "note": h.note, + "book_id": h.book_id, + "color": h.color.value if h.color else None, + "location": h.location, + "highlighted_at": h.highlighted_at.isoformat() if h.highlighted_at else None, + "tags": [t.name for t in h.tags] if h.tags else None, + }.items() + if v is not None + } + + +def _book_summary(b: Any) -> dict[str, Any]: + """Compact summary of a Book.""" + return { + k: v + for k, v in { + "id": b.id, + "title": b.title, + "author": b.author, + "category": b.category.value if b.category else None, + "source": b.source, + "num_highlights": b.num_highlights, + "source_url": b.source_url, + "cover_image_url": b.cover_image_url, + "last_highlight_at": (b.last_highlight_at.isoformat() if b.last_highlight_at else None), + }.items() + if v is not None + } + + +def _parse_iso_datetime(s: str | None) -> datetime | None: + """Parse an ISO 8601 datetime string, returning None on failure.""" + if not s: + return None + try: + return datetime.fromisoformat(s) + except (ValueError, TypeError): + return None + + +def _json_result(data: Any) -> str: + """Serialize a result to a compact JSON string.""" + return json.dumps(data, ensure_ascii=False, default=str) + + +# --------------------------------------------------------------------------- +# Tools — Documents (Reader v3) +# --------------------------------------------------------------------------- + + +@mcp.tool() +async def save_to_reader( + url: str, + title: str | None = None, + author: str | None = None, + summary: str | None = None, + html: str | None = None, + tags: list[str] | None = None, + notes: str | None = None, + category: str | None = None, + location: str | None = None, +) -> str: + """Save a URL or upload content to Readwise Reader. + + To save a web page for later reading, provide just the URL. + To upload local content (e.g. a Markdown document converted to HTML), + provide both a URL (as a unique identifier) and the html parameter. + + Args: + url: The URL to save. For uploads, use a synthetic unique URL. + title: Override the parsed title. + author: Override the parsed author. + summary: A short summary of the document. + html: HTML content to upload (omit to let Reader scrape the URL). + tags: Tags to apply to the document. + notes: A top-level note on the document. + category: Document type: article, email, pdf, epub, tweet, video. + location: Where to put it: new (inbox), later, archive. + + Returns: + JSON with the created document's id and Reader URL. + """ + doc_location = None + if location: + try: + doc_location = DocumentLocation(location) + except ValueError: + return _json_result( + {"error": f"Invalid location '{location}'. Use: new, later, archive, feed."} + ) + + doc = DocumentCreate( + url=url, + title=title, + author=author, + summary=summary, + html=html, + tags=tags, + notes=notes, + location=doc_location, + saved_using="readwise-mcp", + ) + + async with _client() as client: + try: + result = await client.v3.create_document(doc) + return _json_result({"id": result.id, "url": result.url}) + except ReadwiseError as e: + return _json_result({"error": str(e)}) + + +@mcp.tool() +async def search_documents( + location: str | None = None, + category: str | None = None, + updated_after: str | None = None, + tags: list[str] | None = None, + query: str | None = None, + limit: int = 20, +) -> str: + """Search and filter documents in Readwise Reader. + + Returns a list of document summaries (no content — use get_document + to fetch the full content of a specific document). + + Args: + location: Filter by location: new (inbox), later, archive, feed. + category: Filter by type: article, email, rss, pdf, epub, tweet, video. + updated_after: ISO datetime — only docs updated after this time. + tags: Filter by tags. + query: Text search in title (case-insensitive substring match). + limit: Maximum results to return (default 20, max 100). + + Returns: + JSON array of document summaries. + """ + from readwise_sdk.v3.models import DocumentCategory, DocumentLocation + + limit = min(max(limit, 1), 100) + doc_location = None + doc_category = None + + if location: + try: + doc_location = DocumentLocation(location) + except ValueError: + return _json_result({"error": f"Invalid location '{location}'."}) + if category: + try: + doc_category = DocumentCategory(category) + except ValueError: + return _json_result({"error": f"Invalid category '{category}'."}) + + dt_after = _parse_iso_datetime(updated_after) + query_lower = query.lower() if query else None + + async with _client() as client: + try: + results: list[dict[str, Any]] = [] + async for doc in client.v3.list_documents( + location=doc_location, + category=doc_category, + updated_after=dt_after, + tags=tags, + ): + if query_lower and doc.title and query_lower not in doc.title.lower(): + continue + results.append(_doc_summary(doc)) + if len(results) >= limit: + break + return _json_result(results) + except ReadwiseError as e: + return _json_result({"error": str(e)}) + + +@mcp.tool() +async def get_document(document_id: str) -> str: + """Get a single document from Readwise Reader by ID, including its full content. + + Args: + document_id: The document ID (from search_documents results). + + Returns: + JSON with full document details and HTML content. + """ + async with _client() as client: + try: + doc = await client.v3.get_document(document_id, with_content=True) + if doc is None: + return _json_result({"error": f"Document '{document_id}' not found."}) + return _json_result(_doc_full(doc)) + except NotFoundError: + return _json_result({"error": f"Document '{document_id}' not found."}) + except ReadwiseError as e: + return _json_result({"error": str(e)}) + + +@mcp.tool() +async def update_document( + document_id: str, + title: str | None = None, + author: str | None = None, + summary: str | None = None, + location: str | None = None, + tags: list[str] | None = None, + notes: str | None = None, +) -> str: + """Update a document's metadata, move it between locations, or set tags. + + To archive a document, set location to "archive". + To move it to the reading list, set location to "later". + To move it back to inbox, set location to "new". + + Note: setting tags replaces all existing tags on the document. + To add a tag without removing others, first get the document to see + its current tags, then include them all in the tags list. + + Args: + document_id: The document ID to update. + title: New title. + author: New author. + summary: New summary. + location: Move to: new, later, archive. + tags: Replace tags with this list. + notes: Set the document note. + + Returns: + JSON with the updated document's id and URL. + """ + doc_location = None + if location: + try: + doc_location = DocumentLocation(location) + except ValueError: + return _json_result({"error": f"Invalid location '{location}'."}) + + update = DocumentUpdate( + title=title, + author=author, + summary=summary, + location=doc_location, + tags=tags, + notes=notes, + ) + + async with _client() as client: + try: + result = await client.v3.update_document(document_id, update) + return _json_result({"id": result.id, "url": result.url}) + except NotFoundError: + return _json_result({"error": f"Document '{document_id}' not found."}) + except ReadwiseError as e: + return _json_result({"error": str(e)}) + + +@mcp.tool() +async def delete_document(document_id: str) -> str: + """Delete a document from Readwise Reader. + + This is permanent and cannot be undone. + + Args: + document_id: The document ID to delete. + + Returns: + JSON confirmation or error. + """ + async with _client() as client: + try: + await client.v3.delete_document(document_id) + return _json_result({"deleted": document_id}) + except NotFoundError: + return _json_result({"error": f"Document '{document_id}' not found."}) + except ReadwiseError as e: + return _json_result({"error": str(e)}) + + +# --------------------------------------------------------------------------- +# Tools — Highlights (Readwise v2) +# --------------------------------------------------------------------------- + + +@mcp.tool() +async def get_highlights( + book_id: int | None = None, + updated_after: str | None = None, + query: str | None = None, + limit: int = 50, +) -> str: + """List highlights from Readwise with optional filters. + + Args: + book_id: Only highlights from this book/source ID. + updated_after: ISO datetime — only highlights updated after this. + query: Text search in highlight text (case-insensitive substring). + limit: Maximum results (default 50, max 200). + + Returns: + JSON array of highlights. + """ + limit = min(max(limit, 1), 200) + dt_after = _parse_iso_datetime(updated_after) + query_lower = query.lower() if query else None + + async with _client() as client: + try: + results: list[dict[str, Any]] = [] + async for h in client.v2.list_highlights( + book_id=book_id, + updated_after=dt_after, + ): + if query_lower and query_lower not in h.text.lower(): + continue + results.append(_highlight_summary(h)) + if len(results) >= limit: + break + return _json_result(results) + except ReadwiseError as e: + return _json_result({"error": str(e)}) + + +@mcp.tool() +async def export_highlights( + updated_after: str | None = None, + book_ids: list[int] | None = None, + limit: int = 20, +) -> str: + """Export highlights grouped by book — efficient for bulk retrieval. + + Each result is a book with its highlights nested inside, which is + more efficient than listing highlights individually. + + Args: + updated_after: ISO datetime — only highlights updated after this. + book_ids: Only export from these specific book IDs. + limit: Maximum number of books to return (default 20, max 100). + + Returns: + JSON array of books, each containing a highlights array. + """ + limit = min(max(limit, 1), 100) + dt_after = _parse_iso_datetime(updated_after) + + async with _client() as client: + try: + results: list[dict[str, Any]] = [] + async for book in client.v2.export_highlights( + updated_after=dt_after, + book_ids=book_ids, + ): + book_data: dict[str, Any] = { + "book_id": book.user_book_id, + "title": book.title, + "author": book.author, + "category": book.category.value if book.category else None, + "source": book.source, + "source_url": book.source_url, + "highlights": [_highlight_summary(h) for h in book.highlights], + } + results.append({k: v for k, v in book_data.items() if v is not None}) + if len(results) >= limit: + break + return _json_result(results) + except ReadwiseError as e: + return _json_result({"error": str(e)}) + + +@mcp.tool() +async def create_highlight( + text: str, + title: str | None = None, + author: str | None = None, + source_url: str | None = None, + note: str | None = None, + category: str | None = None, + highlighted_at: str | None = None, +) -> str: + """Create a new highlight in Readwise. + + The highlight will be associated with a book/source identified by + title + author + source_url. If no matching book exists, Readwise + creates one automatically. + + Args: + text: The highlighted text (required, max 8191 chars). + title: Title of the book or article. + author: Author name. + source_url: URL of the source. + note: A note to attach to the highlight. + category: Source category: books, articles, tweets, podcasts. + highlighted_at: ISO datetime when the highlight was made. + + Returns: + JSON with created highlight IDs. + """ + from readwise_sdk.v2.models import BookCategory + + book_category = None + if category: + try: + book_category = BookCategory(category) + except ValueError: + return _json_result( + {"error": f"Invalid category '{category}'. Use: books, articles, tweets, podcasts."} + ) + + highlight = HighlightCreate( + text=text[:8191], + title=title, + author=author, + source_url=source_url, + note=note, + category=book_category, + highlighted_at=_parse_iso_datetime(highlighted_at), + ) + + async with _client() as client: + try: + ids = await client.v2.create_highlights([highlight]) + return _json_result({"created_highlight_ids": ids}) + except ReadwiseError as e: + return _json_result({"error": str(e)}) + + +# --------------------------------------------------------------------------- +# Tools — Books (Readwise v2) +# --------------------------------------------------------------------------- + + +@mcp.tool() +async def get_books( + category: str | None = None, + source: str | None = None, + query: str | None = None, + limit: int = 20, +) -> str: + """List books and sources in Readwise. + + Args: + category: Filter by type: books, articles, tweets, podcasts, supplementals. + source: Filter by import source (e.g. kindle, instapaper, manual). + query: Text search in title (case-insensitive substring). + limit: Maximum results (default 20, max 100). + + Returns: + JSON array of book summaries. + """ + from readwise_sdk.v2.models import BookCategory + + limit = min(max(limit, 1), 100) + book_category = None + + if category: + try: + book_category = BookCategory(category) + except ValueError: + return _json_result({"error": f"Invalid category '{category}'."}) + + query_lower = query.lower() if query else None + + async with _client() as client: + try: + results: list[dict[str, Any]] = [] + async for book in client.v2.list_books( + category=book_category, + source=source, + ): + if query_lower and query_lower not in book.title.lower(): + continue + results.append(_book_summary(book)) + if len(results) >= limit: + break + return _json_result(results) + except ReadwiseError as e: + return _json_result({"error": str(e)}) diff --git a/tests/conftest.py b/tests/conftest.py index b9fc32d..f499bf9 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -12,6 +12,11 @@ except ModuleNotFoundError: collect_ignore.append(str(Path(__file__).parent / "test_cli.py")) +try: + import mcp # noqa: F401 +except ModuleNotFoundError: + collect_ignore.append(str(Path(__file__).parent / "mcp")) + @pytest.fixture def api_key() -> str: diff --git a/tests/mcp/__init__.py b/tests/mcp/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/tests/mcp/conftest.py b/tests/mcp/conftest.py new file mode 100644 index 0000000..8dd721e --- /dev/null +++ b/tests/mcp/conftest.py @@ -0,0 +1,42 @@ +"""Shared fixtures for readwise-mcp tests.""" + +from __future__ import annotations + +import os + +import pytest + +# Capture the real API key at import time, before any monkeypatching. +_REAL_API_KEY: str = "" +_env_key = os.environ.get("READWISE_API_KEY", "") +if _env_key: + _REAL_API_KEY = _env_key +else: + _env_file = os.path.expanduser("~/.env") + if os.path.isfile(_env_file): + with open(_env_file) as _f: + for _line in _f: + _line = _line.strip() + if _line.startswith("READWISE_API_KEY="): + _REAL_API_KEY = _line.split("=", 1)[1].strip().strip("'\"") + break + + +@pytest.fixture(autouse=True) +def _isolate_env(monkeypatch: pytest.MonkeyPatch) -> None: + """Prevent tests from leaking env vars or touching the real API.""" + monkeypatch.setenv("READWISE_API_KEY", "test-key-000") + + +@pytest.fixture() +def api_key_from_env() -> str: + """Return the real API key for live tests, captured before monkeypatch.""" + if not _REAL_API_KEY: + pytest.skip("READWISE_API_KEY not available for live tests") + return _REAL_API_KEY + + +@pytest.fixture() +def _use_real_api_key(api_key_from_env: str, monkeypatch: pytest.MonkeyPatch) -> None: + """Override the isolated env with the real API key for live tests.""" + monkeypatch.setenv("READWISE_API_KEY", api_key_from_env) diff --git a/tests/mcp/test_live.py b/tests/mcp/test_live.py new file mode 100644 index 0000000..18c960b --- /dev/null +++ b/tests/mcp/test_live.py @@ -0,0 +1,107 @@ +"""Live tests against the real Readwise API. + +Run with: uv run pytest -m live +Requires READWISE_API_KEY in env or ~/.env. +""" + +from __future__ import annotations + +import json + +import pytest + +pytest.importorskip("mcp") + +from readwise_sdk.mcp.server import ( + delete_document, + export_highlights, + get_books, + get_document, + get_highlights, + save_to_reader, + search_documents, +) + +pytestmark = pytest.mark.live + + +@pytest.mark.asyncio +class TestLiveDocuments: + """Test document operations against the real Reader API.""" + + @pytest.mark.usefixtures("_use_real_api_key") + async def test_search_inbox(self) -> None: + """List documents in the inbox — read-only, always safe.""" + raw = await search_documents(location="new", limit=3) + result = json.loads(raw) + assert isinstance(result, list) + # Inbox might be empty, but should not error + if result: + doc = result[0] + assert "id" in doc + assert "title" in doc + + @pytest.mark.usefixtures("_use_real_api_key") + async def test_save_and_cleanup(self) -> None: + """Save a test URL to Reader, verify it exists, then delete it.""" + test_url = "https://httpbin.org/html" + + # Save + save_raw = await save_to_reader( + url=test_url, + tags=["mcp-test"], + notes="Automated MCP server test — safe to delete", + ) + save_result = json.loads(save_raw) + assert "id" in save_result, f"Save failed: {save_result}" + doc_id = save_result["id"] + + # Get — verify it was saved + get_raw = await get_document(document_id=doc_id) + get_result = json.loads(get_raw) + assert get_result.get("id") == doc_id + + # Clean up + del_raw = await delete_document(document_id=doc_id) + del_result = json.loads(del_raw) + assert del_result.get("deleted") == doc_id + + +@pytest.mark.asyncio +class TestLiveHighlights: + """Test highlight operations — read-only.""" + + @pytest.mark.usefixtures("_use_real_api_key") + async def test_list_highlights(self) -> None: + raw = await get_highlights(limit=3) + result = json.loads(raw) + assert isinstance(result, list) + if result: + h = result[0] + assert "id" in h + assert "text" in h + + @pytest.mark.usefixtures("_use_real_api_key") + async def test_export_highlights(self) -> None: + raw = await export_highlights(limit=2) + result = json.loads(raw) + assert isinstance(result, list) + if result: + book = result[0] + assert "title" in book + assert "highlights" in book + + +@pytest.mark.asyncio +class TestLiveBooks: + """Test book listing — read-only.""" + + @pytest.mark.usefixtures("_use_real_api_key") + async def test_list_books(self) -> None: + raw = await get_books(limit=3) + result = json.loads(raw) + assert isinstance(result, list) + if result: + book = result[0] + assert "id" in book + assert "title" in book diff --git a/tests/mcp/test_tools.py b/tests/mcp/test_tools.py new file mode 100644 index 0000000..2b8a67b --- /dev/null +++ b/tests/mcp/test_tools.py @@ -0,0 +1,416 @@ +"""Unit tests for MCP tool handlers with mocked HTTP transport.""" + +from __future__ import annotations + +import json +from unittest.mock import patch + +import httpx +import pytest +import respx + +pytest.importorskip("mcp") + +from readwise_sdk.mcp.server import ( + _get_api_key, + _json_result, + _parse_iso_datetime, + create_highlight, + delete_document, + export_highlights, + get_books, + get_document, + get_highlights, + save_to_reader, + search_documents, + update_document, +) + +# --------------------------------------------------------------------------- +# Helper tests +# --------------------------------------------------------------------------- + + +class TestGetApiKey: + def test_from_env(self, monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("READWISE_API_KEY", "env-key-123") + assert _get_api_key() == "env-key-123" + + def test_from_dotenv_file(self, monkeypatch: pytest.MonkeyPatch, tmp_path) -> None: + monkeypatch.delenv("READWISE_API_KEY", raising=False) + env_file = tmp_path / ".env" + env_file.write_text("READWISE_API_KEY=file-key-456\n") + with patch("readwise_sdk.mcp.server.os.path.expanduser", return_value=str(env_file)): + assert _get_api_key() == "file-key-456" + + def test_missing_raises(self, monkeypatch: pytest.MonkeyPatch, tmp_path) -> None: + monkeypatch.delenv("READWISE_API_KEY", raising=False) + env_file = tmp_path / ".env" + env_file.write_text("OTHER_KEY=nope\n") + with ( + patch("readwise_sdk.mcp.server.os.path.expanduser", return_value=str(env_file)), + pytest.raises(RuntimeError, match="READWISE_API_KEY not found"), + ): + _get_api_key() + + +class TestParseIsoDatetime: + def test_valid(self) -> None: + dt = _parse_iso_datetime("2025-01-15T10:30:00") + assert dt is not None + assert dt.year == 2025 + + def test_none(self) -> None: + assert _parse_iso_datetime(None) is None + + def test_empty(self) -> None: + assert _parse_iso_datetime("") is None + + def test_invalid(self) -> None: + assert _parse_iso_datetime("not-a-date") is None + + +class TestJsonResult: + def test_serializes_dict(self) -> None: + result = _json_result({"id": "abc", "count": 42}) + parsed = json.loads(result) + assert parsed == {"id": "abc", "count": 42} + + def test_serializes_list(self) -> None: + result = _json_result([1, 2, 3]) + assert json.loads(result) == [1, 2, 3] + + +# --------------------------------------------------------------------------- +# Tool tests with respx mocking +# --------------------------------------------------------------------------- + +V3_BASE = "https://readwise.io/api/v3" +V2_BASE = "https://readwise.io/api/v2" + + +@pytest.mark.asyncio +class TestSaveToReader: + @respx.mock + async def test_save_url(self) -> None: + respx.post(f"{V3_BASE}/save/").mock( + return_value=httpx.Response( + 201, + json={"id": "doc-1", "url": "https://read.readwise.io/read/doc-1"}, + ) + ) + result = json.loads(await save_to_reader(url="https://example.com/article")) + assert result["id"] == "doc-1" + assert "url" in result + + @respx.mock + async def test_save_with_html(self) -> None: + respx.post(f"{V3_BASE}/save/").mock( + return_value=httpx.Response( + 201, + json={"id": "doc-2", "url": "https://read.readwise.io/read/doc-2"}, + ) + ) + result = json.loads( + await save_to_reader( + url="https://local-upload.example.com/test", + title="My Document", + html="

Content here

", + tags=["test"], + ) + ) + assert result["id"] == "doc-2" + + async def test_invalid_location(self) -> None: + result = json.loads(await save_to_reader(url="https://example.com", location="invalid")) + assert "error" in result + assert "Invalid location" in result["error"] + + +@pytest.mark.asyncio +class TestSearchDocuments: + @respx.mock + async def test_basic_search(self) -> None: + respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": "doc-1", + "url": "https://read.readwise.io/read/doc-1", + "title": "Test Article", + "author": "Author", + "category": "article", + "location": "new", + "tags": [], + } + ], + "nextPageCursor": None, + }, + ) + ) + result = json.loads(await search_documents(limit=5)) + assert isinstance(result, list) + assert len(result) == 1 + assert result[0]["title"] == "Test Article" + + @respx.mock + async def test_search_with_query_filter(self) -> None: + respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": "doc-1", + "url": "https://r.io/1", + "title": "Python Testing Guide", + "category": "article", + "location": "new", + "tags": [], + }, + { + "id": "doc-2", + "url": "https://r.io/2", + "title": "Rust Programming", + "category": "article", + "location": "new", + "tags": [], + }, + ], + "nextPageCursor": None, + }, + ) + ) + result = json.loads(await search_documents(query="Python")) + assert len(result) == 1 + assert result[0]["title"] == "Python Testing Guide" + + async def test_invalid_location(self) -> None: + result = json.loads(await search_documents(location="bogus")) + assert "error" in result + + +@pytest.mark.asyncio +class TestGetDocument: + @respx.mock + async def test_found(self) -> None: + respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": "doc-1", + "url": "https://read.readwise.io/read/doc-1", + "title": "Full Article", + "content": "

Full HTML content

", + "summary": "A test article", + "category": "article", + "location": "later", + "tags": ["test"], + } + ], + "nextPageCursor": None, + }, + ) + ) + result = json.loads(await get_document(document_id="doc-1")) + assert result["title"] == "Full Article" + assert result["content"] == "

Full HTML content

" + + @respx.mock + async def test_not_found(self) -> None: + respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response( + 200, + json={"results": [], "nextPageCursor": None}, + ) + ) + result = json.loads(await get_document(document_id="no-such-doc")) + assert "error" in result + assert "not found" in result["error"] + + +@pytest.mark.asyncio +class TestUpdateDocument: + @respx.mock + async def test_move_to_archive(self) -> None: + respx.patch(f"{V3_BASE}/update/doc-1/").mock( + return_value=httpx.Response( + 200, + json={"id": "doc-1", "url": "https://read.readwise.io/read/doc-1"}, + ) + ) + result = json.loads(await update_document(document_id="doc-1", location="archive")) + assert result["id"] == "doc-1" + + async def test_invalid_location(self) -> None: + result = json.loads(await update_document(document_id="doc-1", location="nowhere")) + assert "error" in result + + +@pytest.mark.asyncio +class TestDeleteDocument: + @respx.mock + async def test_delete_success(self) -> None: + respx.delete(f"{V3_BASE}/delete/doc-1/").mock(return_value=httpx.Response(204)) + result = json.loads(await delete_document(document_id="doc-1")) + assert result["deleted"] == "doc-1" + + +@pytest.mark.asyncio +class TestGetHighlights: + @respx.mock + async def test_list_highlights(self) -> None: + respx.get(f"{V2_BASE}/highlights/").mock( + return_value=httpx.Response( + 200, + json={ + "count": 1, + "next": None, + "results": [ + { + "id": 101, + "text": "Important insight from the book", + "note": "My note", + "book_id": 42, + "color": "yellow", + "tags": [{"id": 1, "name": "insight"}], + } + ], + }, + ) + ) + result = json.loads(await get_highlights(limit=10)) + assert isinstance(result, list) + assert len(result) == 1 + assert result[0]["text"] == "Important insight from the book" + + @respx.mock + async def test_query_filter(self) -> None: + respx.get(f"{V2_BASE}/highlights/").mock( + return_value=httpx.Response( + 200, + json={ + "count": 2, + "next": None, + "results": [ + {"id": 1, "text": "Python is great", "tags": []}, + {"id": 2, "text": "Rust is fast", "tags": []}, + ], + }, + ) + ) + result = json.loads(await get_highlights(query="Python")) + assert len(result) == 1 + assert "Python" in result[0]["text"] + + +@pytest.mark.asyncio +class TestExportHighlights: + @respx.mock + async def test_export(self) -> None: + respx.get(f"{V2_BASE}/export/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "user_book_id": 42, + "title": "Test Book", + "author": "Author Name", + "category": "books", + "highlights": [ + {"id": 1, "text": "A highlight", "tags": []}, + {"id": 2, "text": "Another highlight", "tags": []}, + ], + } + ], + "nextPageCursor": None, + }, + ) + ) + result = json.loads(await export_highlights(limit=5)) + assert isinstance(result, list) + assert len(result) == 1 + assert result[0]["title"] == "Test Book" + assert len(result[0]["highlights"]) == 2 + + +@pytest.mark.asyncio +class TestCreateHighlight: + @respx.mock + async def test_create(self) -> None: + respx.post(f"{V2_BASE}/highlights/").mock( + return_value=httpx.Response( + 200, + json=[{"modified_highlights": [999]}], + ) + ) + result = json.loads( + await create_highlight( + text="Test highlight text", + title="My Book", + author="Author", + ) + ) + assert result["created_highlight_ids"] == [999] + + async def test_invalid_category(self) -> None: + result = json.loads(await create_highlight(text="Some text", category="invalid")) + assert "error" in result + + +@pytest.mark.asyncio +class TestGetBooks: + @respx.mock + async def test_list_books(self) -> None: + respx.get(f"{V2_BASE}/books/").mock( + return_value=httpx.Response( + 200, + json={ + "count": 1, + "next": None, + "results": [ + { + "id": 42, + "title": "The Art of Testing", + "author": "Jane Doe", + "category": "books", + "num_highlights": 15, + "source": "kindle", + "tags": [], + } + ], + }, + ) + ) + result = json.loads(await get_books(limit=10)) + assert isinstance(result, list) + assert len(result) == 1 + assert result[0]["title"] == "The Art of Testing" + + @respx.mock + async def test_query_filter(self) -> None: + respx.get(f"{V2_BASE}/books/").mock( + return_value=httpx.Response( + 200, + json={ + "count": 2, + "next": None, + "results": [ + {"id": 1, "title": "Python Cookbook", "num_highlights": 5, "tags": []}, + {"id": 2, "title": "Rust Handbook", "num_highlights": 3, "tags": []}, + ], + }, + ) + ) + result = json.loads(await get_books(query="Python")) + assert len(result) == 1 + assert result[0]["title"] == "Python Cookbook" + + async def test_invalid_category(self) -> None: + result = json.loads(await get_books(category="invalid")) + assert "error" in result diff --git a/uv.lock b/uv.lock index d5bb417..1fa7139 100644 --- a/uv.lock +++ b/uv.lock @@ -1,6 +1,16 @@ version = 1 revision = 3 requires-python = ">=3.12" +resolution-markers = [ + "python_full_version >= '3.14' and sys_platform == 'win32'", + "python_full_version >= '3.14' and sys_platform != 'win32'", + "python_full_version < '3.14' and sys_platform == 'win32'", + "python_full_version < '3.14' and sys_platform != 'win32'", +] + +[options] +exclude-newer = "2026-07-07T01:43:53.664484438Z" +exclude-newer-span = "P7D" [[package]] name = "annotated-types" @@ -24,6 +34,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/38/0e/27be9fdef66e72d64c0cdc3cc2823101b80585f8119b5c112c2e8f5f7dab/anyio-4.12.1-py3-none-any.whl", hash = "sha256:d405828884fc140aa80a3c667b8beed277f1dfedec42ba031bd6ac3db606ab6c", size = 113592, upload-time = "2026-01-06T11:45:19.497Z" }, ] +[[package]] +name = "attrs" +version = "26.1.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/9a/8e/82a0fe20a541c03148528be8cac2408564a6c9a0cc7e9171802bc1d26985/attrs-26.1.0.tar.gz", hash = "sha256:d03ceb89cb322a8fd706d4fb91940737b6642aa36998fe130a9bc96c985eff32", size = 952055, upload-time = "2026-03-19T14:22:25.026Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548, upload-time = "2026-03-19T14:22:23.645Z" }, +] + [[package]] name = "babel" version = "2.17.0" @@ -56,6 +75,91 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/e6/ad/3cc14f097111b4de0040c83a525973216457bbeeb63739ef1ed275c1c021/certifi-2026.1.4-py3-none-any.whl", hash = "sha256:9943707519e4add1115f44c2bc244f782c0249876bf51b6599fee1ffbedd685c", size = 152900, upload-time = "2026-01-04T02:42:40.15Z" }, ] +[[package]] +name = "cffi" +version = "2.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pycparser", marker = "implementation_name != 'PyPy'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/57/5f/ff100cae70ebe9d8df1c01a00e510e45d9adb5c1fdda84791b199141de97/cffi-2.1.0.tar.gz", hash = "sha256:efc1cdd798b1aaf39b4610bba7aad28c9bea9b910f25c784ccf9ec1fa719d1f9", size = 531036, upload-time = "2026-07-06T21:34:30.382Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1e/85/990925db5df586ec90beb97529c853497e7f85ba0234830447faf41c3057/cffi-2.1.0-cp312-cp312-macosx_10_15_x86_64.whl", hash = "sha256:df2b82571a1b30f58a87bf4e5a9e78d2b1eff6c6ce8fd3aa3757221f93f0863f", size = 184829, upload-time = "2026-07-06T21:32:44.324Z" }, + { url = "https://files.pythonhosted.org/packages/4b/92/e7bb136ad6b5352603732cf907ef862ca103f20f2031c1735a46300c20c9/cffi-2.1.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:78474632761faa0fb96f30b1c928c84ebcf68713cbb80d15bab09dfe61640fde", size = 184728, upload-time = "2026-07-06T21:32:45.683Z" }, + { url = "https://files.pythonhosted.org/packages/c3/c0/d1ec30ffb370f748f2fb54425972bfef9871e0132e82fb589c46b6676049/cffi-2.1.0-cp312-cp312-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:5972433ad71a9e46516584ef60a0fda12d9dc459938d1539c3ddecf9bdc1368d", size = 214815, upload-time = "2026-07-06T21:32:48.557Z" }, + { url = "https://files.pythonhosted.org/packages/1b/dc/5620cf930688be01f2d673804291de757a934c90b946dbdc3d84130c2ea4/cffi-2.1.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b6422532152adf4e59b110cb2808cee7a033800952f5c036b4af047ee43199e7", size = 222429, upload-time = "2026-07-06T21:32:49.848Z" }, + { url = "https://files.pythonhosted.org/packages/4b/a4/77b53abbf7a1e0beb9637edbef2a94d15f9c822f591e85d439ffd91519a6/cffi-2.1.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:46b1c8db8f6122420f32d02fffb924c2fe9bc772d228c7c711748fff56aabb2b", size = 210315, upload-time = "2026-07-06T21:32:51.221Z" }, + { url = "https://files.pythonhosted.org/packages/58/0c/f528df19cc94b675087324d4760d9e6d5bfae97d6217aa4fac43de4f5fcc/cffi-2.1.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:d9fafc5aa2e2a39aaf7f8cc0c1f044a9b07fca12e558dca53a3cc5c654ad67a7", size = 208859, upload-time = "2026-07-06T21:32:52.512Z" }, + { url = "https://files.pythonhosted.org/packages/62/f2/c9522a81c32132799a1972c39f5c5f8b4c8b9f00488a23feaa6c06f07741/cffi-2.1.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:1e9f50d192a3e525b15a75ab5114e442d83d657b7ec29182a991bc9a88fd3a66", size = 221844, upload-time = "2026-07-06T21:32:53.704Z" }, + { url = "https://files.pythonhosted.org/packages/6e/28/bd53988b9833e8f8ad539d26f4c07a6b3f6bcb1e9e02e7ca038250b3428d/cffi-2.1.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:98fff996e983a36d3aa2eca83af40c5821202e7e6f32d13ae94e3d2286f10cfe", size = 225287, upload-time = "2026-07-06T21:32:54.907Z" }, + { url = "https://files.pythonhosted.org/packages/79/99/0d0fd37f055224085f42bbb2c022d002e17dde4a97972822327b07d84101/cffi-2.1.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:379de10ce1ba048b1448599d1b37b24caee16309d1ac98d3982fc997f768700b", size = 223681, upload-time = "2026-07-06T21:32:56.329Z" }, + { url = "https://files.pythonhosted.org/packages/b0/80/c138990aa2a70b1a269f6e06348729836d733d6f970867943f61d367f8cc/cffi-2.1.0-cp312-cp312-win32.whl", hash = "sha256:9b8f0f26ca4e7513c534d351eca551947d053fac438f2a04ac96d882909b0d3a", size = 175269, upload-time = "2026-07-06T21:32:57.777Z" }, + { url = "https://files.pythonhosted.org/packages/a8/eb/f636456ff21a83fc13c032b58cc5dde061691546ac79efa284b2989b7982/cffi-2.1.0-cp312-cp312-win_amd64.whl", hash = "sha256:c97f080ea627e2863524c5af3836e2270b5f5dfff1f104392b959f8df0c5d384", size = 185881, upload-time = "2026-07-06T21:32:59.253Z" }, + { url = "https://files.pythonhosted.org/packages/dd/2c/400ea43e721727dca8a65c4521390e9196757caba4a45643acb2b63271b8/cffi-2.1.0-cp312-cp312-win_arm64.whl", hash = "sha256:6d194185eabd279f1c05ebe3504265ddfc5ad2b58d0714f7db9f01da592e9eb6", size = 180088, upload-time = "2026-07-06T21:33:02.278Z" }, + { url = "https://files.pythonhosted.org/packages/96/88/a996879e2eeccb815f6e3a5967b12a308257412acec882039d386bd2aa7b/cffi-2.1.0-cp313-cp313-ios_13_0_arm64_iphoneos.whl", hash = "sha256:10537b1df4967ca26d21e5072d7d54188354483b91dc75058968d3f0cf13fbda", size = 194331, upload-time = "2026-07-06T21:33:03.697Z" }, + { url = "https://files.pythonhosted.org/packages/58/85/7ae00d5c8dd6266f4e944c3db630f3c5c9a98b61d469c714d848b1d8138a/cffi-2.1.0-cp313-cp313-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:a95b05f9baf29b91171b3a8bd2020b028835243e7b0ff6bb23e2a3c228518b1b", size = 196966, upload-time = "2026-07-06T21:33:05.353Z" }, + { url = "https://files.pythonhosted.org/packages/8c/e9/45c3a76ad8d43ad9261f4c95436da61128d3ca545d72b9612c0ab5be0b1c/cffi-2.1.0-cp313-cp313-macosx_10_15_x86_64.whl", hash = "sha256:15faec4adfff450819f3aee0e2e02c812de6edb88203aa58807955db2003472a", size = 184795, upload-time = "2026-07-06T21:33:06.699Z" }, + { url = "https://files.pythonhosted.org/packages/84/4c/82f132cb4418ee6d953d982b19191e87e2a6372c8a4ce36e50b69d6ade4a/cffi-2.1.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:716ff8ec22f20b4d988b12884086bcef0fc99737043e503f7a3935a6be99b1ea", size = 184746, upload-time = "2026-07-06T21:33:08.071Z" }, + { url = "https://files.pythonhosted.org/packages/a0/1c/4ed5a0e5bdca6cbc275556de3328dd1b76fd0c11cc13c88fe66d1d8715f2/cffi-2.1.0-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:63960549e4f8dc41e31accb97b975abaecfc44c03e396c093a6436763c2ea7db", size = 214747, upload-time = "2026-07-06T21:33:09.671Z" }, + { url = "https://files.pythonhosted.org/packages/3a/a6/e879bb68cc23a2bc9ba8f4b7d8019f0c2694bad2ab6c4a3701d429439f58/cffi-2.1.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:ff067a8d8d880e7809e4ac88eb009bb848870115317b306666502ccad30b147f", size = 222392, upload-time = "2026-07-06T21:33:10.896Z" }, + { url = "https://files.pythonhosted.org/packages/88/f6/01890cfd63c08f8eb96a8319b0443690197d240a8bd6346048cf7bde9190/cffi-2.1.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:3b926723c13eba9f81d2ef3820d63aeceec3b2d4639906047bf675cb8a7a500d", size = 210285, upload-time = "2026-07-06T21:33:12.251Z" }, + { url = "https://files.pythonhosted.org/packages/a6/cf/2b684132056f438567b61e19d690dd31cd0921ace051e0a458be6074369e/cffi-2.1.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:47ff3a8bfd8cb9da1af7524b965127095055654c177fcfc7578debcb015eecd0", size = 208801, upload-time = "2026-07-06T21:33:13.617Z" }, + { url = "https://files.pythonhosted.org/packages/6f/08/f2e7d62c460faae0926f2d6e423694aa409ced3bc1fe2927a0a6e5f05416/cffi-2.1.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:799416bae98336e400981ff6e532d67d5c709cfb30afb79865a1315f94b0e224", size = 221808, upload-time = "2026-07-06T21:33:15.466Z" }, + { url = "https://files.pythonhosted.org/packages/38/37/04f54b8e63a02f3d908332c9effbf8c366167c6f733ed8a3d4f79b7e2a1e/cffi-2.1.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:961be50688f7fba2fa65f63712d3b9b341a22311f5253460ce933f52f0de1c8c", size = 225241, upload-time = "2026-07-06T21:33:16.869Z" }, + { url = "https://files.pythonhosted.org/packages/a9/d6/c72eecca433cd3e681c65ed313ab4835d9d4a379704d0f628a6a05f51c2e/cffi-2.1.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:bf5c6cf48238b0eb4c086978c492ad1cbc22373fc5b2d7353b3a598ce6db887a", size = 223588, upload-time = "2026-07-06T21:33:18.239Z" }, + { url = "https://files.pythonhosted.org/packages/c6/4b/e706f67279140f92939da3475ad610df18bfd52d50f14953a8e5fede71d5/cffi-2.1.0-cp313-cp313-win32.whl", hash = "sha256:db3eb7d46527159a878ec3460e9d40615bc25ba337d477db681aea6e4f05c5d2", size = 175248, upload-time = "2026-07-06T21:33:19.799Z" }, + { url = "https://files.pythonhosted.org/packages/5a/47/59eb7975cb0e4ef0afa764ea945b29a5bb4537a9f771cb7d6c8a5dd74c95/cffi-2.1.0-cp313-cp313-win_amd64.whl", hash = "sha256:8e74a6135550c4748af665b1b1118b6aab33b1fc6a16f9aff630af107c3b4512", size = 185717, upload-time = "2026-07-06T21:33:21.47Z" }, + { url = "https://files.pythonhosted.org/packages/5a/af/34fee85c48f8d94efc8597bc09470c9dd274c145f1c12e0fbc6ab6d38d74/cffi-2.1.0-cp313-cp313-win_arm64.whl", hash = "sha256:2282cd5e38aa8accd03e99d1256af8411c84cdbee6a89d841b563fdbd1f3e50f", size = 180114, upload-time = "2026-07-06T21:33:22.515Z" }, + { url = "https://files.pythonhosted.org/packages/d8/f0/81478e482afa03f6d18dc8f2afb5edc45b3080853b634b5ed91961be0998/cffi-2.1.0-cp314-cp314-ios_13_0_arm64_iphoneos.whl", hash = "sha256:d2117334c3af3bdcb9a88522b844a2bdb5efdc4f71c6c822df55486ae1c3347a", size = 194142, upload-time = "2026-07-06T21:33:23.657Z" }, + { url = "https://files.pythonhosted.org/packages/7d/95/8de304305cd9204974b0ca051b86d307cafca13aa575a0ef1b44d92c0d8c/cffi-2.1.0-cp314-cp314-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:702c436735fbe99d59ada02a1f65cfc0d31c0ee8b7290912f8fbc5cd1e4b16c3", size = 196819, upload-time = "2026-07-06T21:33:25.007Z" }, + { url = "https://files.pythonhosted.org/packages/20/71/7c8372d30e42415602ed9f268f7cfd66f1b855fed881ecd168bcb45dbc0b/cffi-2.1.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:1ff3456eab0d889592d1936d6125bbfbc7ae4d3354a700f8bd80450a66445d4d", size = 184965, upload-time = "2026-07-06T21:33:26.605Z" }, + { url = "https://files.pythonhosted.org/packages/d6/5c/584e626835f0375c928176c04137c96927165cb8733cdb3150ec04e5ee5e/cffi-2.1.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c4165821e131d6d4ca444347c2b694e2311bcfa3fe5a861cc72968f28867beac", size = 184952, upload-time = "2026-07-06T21:33:27.823Z" }, + { url = "https://files.pythonhosted.org/packages/2e/d2/065fcae1c73979fac8e054462478d0ff8a29c40cdc2ed7ea5676a061df53/cffi-2.1.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:276f20fffd7b396e12516ba8edf9509210ac248cbbc5acbc39cd512f9f59ebe6", size = 222353, upload-time = "2026-07-06T21:33:29.178Z" }, + { url = "https://files.pythonhosted.org/packages/ed/a5/e8bbb1ce5b3ac2f53ad6a10bde44318a5a8d99d4f4a000d44a6e39aeb3e4/cffi-2.1.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:7d5980a3433d4b71a5e120f9dd551403d7824e31e2e67124fe2769c404c06913", size = 210051, upload-time = "2026-07-06T21:33:30.534Z" }, + { url = "https://files.pythonhosted.org/packages/28/ed/c127d3ac36e899c965e3361357c3befacd6578c03f40125183e41c3b219e/cffi-2.1.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:6ca4919c6e4f89aa99c42510b42cf54596892c00b3f9077f6bdd1505e24b9c8d", size = 208630, upload-time = "2026-07-06T21:33:31.753Z" }, + { url = "https://files.pythonhosted.org/packages/cc/d7/97d3136f81db489ec8d1d67748c110d6c994268fd7528014aa9f2b085e4e/cffi-2.1.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:d53d10f7da99ae46f7373b9150393e9c5eab9b224909982b43832668de4779f5", size = 221593, upload-time = "2026-07-06T21:33:33.044Z" }, + { url = "https://files.pythonhosted.org/packages/d3/27/93195977168ee63aed233a1a0993a2178798654d1f4bddcdd321d6fd3b21/cffi-2.1.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c351efb95e832a853a29361675f33a7ce53de1a109cd73fd47af0712213aa4ce", size = 225146, upload-time = "2026-07-06T21:33:34.224Z" }, + { url = "https://files.pythonhosted.org/packages/b3/c1/6dbd291ee2ae5a50a034aa057207081f545923bbf15dad4511e985aafff5/cffi-2.1.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:dbf7c7a88e2bac086f06d14577332760bdeecc42bdec8ac4077f6260557d9326", size = 223240, upload-time = "2026-07-06T21:33:35.57Z" }, + { url = "https://files.pythonhosted.org/packages/0f/6f/ade5ce9863a57992a6ea3d0d10d7e29b8749fc127204b3d493d667b2815f/cffi-2.1.0-cp314-cp314-win32.whl", hash = "sha256:1854b724d00f6654c742097d5387569021be12d3a0f770eae1df8f8acfcc6acd", size = 177723, upload-time = "2026-07-06T21:33:51.626Z" }, + { url = "https://files.pythonhosted.org/packages/41/de/92b9eeed4ae4a21d6fd9b2a2c8505cbed573299902ea73981cc13f7ff62c/cffi-2.1.0-cp314-cp314-win_amd64.whl", hash = "sha256:1b96bfe2c4bd825681b7d311ad6d9b7280a091f43e8f63da5729638083cd3bfb", size = 187937, upload-time = "2026-07-06T21:33:53.403Z" }, + { url = "https://files.pythonhosted.org/packages/2e/1a/cc6ae6c2913a03aab8898eee57963cf1035b8df5872ed8b9115fcc7e2be8/cffi-2.1.0-cp314-cp314-win_arm64.whl", hash = "sha256:7d28dff1db6764108bc30788d85d61c876beff416d9a49cb9dd7c5a9f34f5804", size = 183001, upload-time = "2026-07-06T21:33:54.74Z" }, + { url = "https://files.pythonhosted.org/packages/14/f0/134c00ce0779ec86dea2aa1aac69339c2741a8045072676763512363a2ea/cffi-2.1.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:7ea6b3e2c4250ff1de21c630fe72d0f63eb95c2c32ffbf64a358cf4a8836d714", size = 188538, upload-time = "2026-07-06T21:33:36.792Z" }, + { url = "https://files.pythonhosted.org/packages/50/d8/3b86aba791cb610d24e8a3e1b2cd529e71fa15096b04e4d4e360049d4a4c/cffi-2.1.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:6af371f3767faeffc6ac1ef57cdfd25844403e9d3f476c5537caee499de96376", size = 188230, upload-time = "2026-07-06T21:33:38.011Z" }, + { url = "https://files.pythonhosted.org/packages/14/d0/117dcd9209255ad8571fbc8c92ef32593a1d294dcec91ddc4e4db50606f2/cffi-2.1.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:eb4e8997a49aa2c08a3e43c9045d224448b8941d88e7ac163c7d383e560cbf98", size = 223899, upload-time = "2026-07-06T21:33:39.514Z" }, + { url = "https://files.pythonhosted.org/packages/b6/3d/f20f8b886b254e3ad10e15cd4186d3aed49f3e6a35ab37aab9f8f25f7c03/cffi-2.1.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:bf01d8c84cbea96b944c73b22182e6c7c432b3475632b8111dbfdc95ddad6e13", size = 211652, upload-time = "2026-07-06T21:33:40.851Z" }, + { url = "https://files.pythonhosted.org/packages/28/3b/fad54de07260b93ddeef4b96d0131d57ea900675df1d410ae1deee52d7a6/cffi-2.1.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:33eb1ad83ebe8f313e0df035c406227d55a79456704a863fad9842136af5ad7d", size = 210755, upload-time = "2026-07-06T21:33:42.183Z" }, + { url = "https://files.pythonhosted.org/packages/cc/82/3d5c705acb7abbba9bbd7d79b8e62e0f25b6120eb7ae6ac49f1b721722fe/cffi-2.1.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:ac0f1a2d0cfa7eea3f2aaf006ab6e70e8feeb16b75d65b7e5939982ca2f11056", size = 223933, upload-time = "2026-07-06T21:33:43.603Z" }, + { url = "https://files.pythonhosted.org/packages/6c/d0/47e338384ab6b1004241002fa616301020cea4fc95f283506565d252f276/cffi-2.1.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c16914df9fb7f500e440e6875fa23ff5e0b31db01fa9c06af98d59a91f0dc2e4", size = 226749, upload-time = "2026-07-06T21:33:45.046Z" }, + { url = "https://files.pythonhosted.org/packages/70/25/65bd5b58ea4bfdfc15cde02cb5365f89ef8ab8b2adfb8fe5c4bd4233382f/cffi-2.1.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5ecbd0499275d57506d397eebe1981cee87b47fcd9ef5c22cab7ed7644a39a94", size = 225703, upload-time = "2026-07-06T21:33:46.374Z" }, + { url = "https://files.pythonhosted.org/packages/dc/78/aa01ac599a8a4322533d45a1f9bc93b338276d2d59dabbe7c6d92a775c81/cffi-2.1.0-cp314-cp314t-win32.whl", hash = "sha256:7d034dcffa09e9a46c93fa3a3be402096cb5354ac6e41ab8e5cc9cd8b642ad76", size = 182857, upload-time = "2026-07-06T21:33:47.696Z" }, + { url = "https://files.pythonhosted.org/packages/b9/26/d00496b22de4d4228f32dde94ad996f350c8aad676d63bcca0743c8dea4d/cffi-2.1.0-cp314-cp314t-win_amd64.whl", hash = "sha256:0582a58f3051372229ca8e7f5f589f9e5632678208d8636fea3676711fdf7fe5", size = 194065, upload-time = "2026-07-06T21:33:48.953Z" }, + { url = "https://files.pythonhosted.org/packages/d5/dd/0c7dbf815a579ff005008a2d815a55d6bb047c349eef536d9dc53d3f0a8d/cffi-2.1.0-cp314-cp314t-win_arm64.whl", hash = "sha256:510aeeeac94811b138077451da1fb18b308a5feab47dd2b603af55804155e1c8", size = 186404, upload-time = "2026-07-06T21:33:50.309Z" }, + { url = "https://files.pythonhosted.org/packages/55/c7/8c8c50cb11c6750051daf12164098a9a6f027ac4356967fd4d800a07f242/cffi-2.1.0-cp315-cp315-ios_13_0_arm64_iphoneos.whl", hash = "sha256:2e9dabb9abcb7ad15938c7196ad5c1718a4e6d33cc79b4c0209bdb64c4a54a5c", size = 194121, upload-time = "2026-07-06T21:33:56.109Z" }, + { url = "https://files.pythonhosted.org/packages/99/e2/67680bf19a6b60d2bb7ff83baefa2a4c3d2d7dc0f3277034b802e1fc504c/cffi-2.1.0-cp315-cp315-ios_13_0_arm64_iphonesimulator.whl", hash = "sha256:37f525a7e7e50c017fdebe58b787be310ad59357ae43a053943a6e1a6c526001", size = 196820, upload-time = "2026-07-06T21:33:57.288Z" }, + { url = "https://files.pythonhosted.org/packages/ed/da/4bbe583a3b3a5c8c60892124fe17f3fa3656523faf0d3484eae90f091853/cffi-2.1.0-cp315-cp315-macosx_10_15_x86_64.whl", hash = "sha256:95f2954c2c9473d892eca6e0409f3568b37ab62a8eedb122461f73cc273476e3", size = 184936, upload-time = "2026-07-06T21:33:58.765Z" }, + { url = "https://files.pythonhosted.org/packages/e5/4b/1f4c36ab273980d7aa75bb126ea4f8971f24a96108acad3a0a084028c57b/cffi-2.1.0-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:cdf2448aab5f661c9315308ec8b93f4e8a1a67a3c733f8631067a2b67d5913dc", size = 185045, upload-time = "2026-07-06T21:34:00.085Z" }, + { url = "https://files.pythonhosted.org/packages/ef/c3/ad299dc38f3583f8d916b299f028af418a9ec98bc695fcbebeae7420691c/cffi-2.1.0-cp315-cp315-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:90bec57cf82089383bd06a605b3eb8daebf7e5a668520beaf6e327a83a947699", size = 222342, upload-time = "2026-07-06T21:34:01.814Z" }, + { url = "https://files.pythonhosted.org/packages/eb/d8/df4543cc087245044ed02ef3ad8e0a26619d0075ac7a77a12dc81177851b/cffi-2.1.0-cp315-cp315-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:6274dcb2d15cef48daa73ed1be5a40d501d74dccd0cd6db364776d12cb6ba022", size = 210073, upload-time = "2026-07-06T21:34:03.255Z" }, + { url = "https://files.pythonhosted.org/packages/2c/0e/fac738d73728c6cea2a88a2883dca54892496cbba88a1dc1f2909cb8a6f5/cffi-2.1.0-cp315-cp315-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:2b71d409cccee78310ab5dec549aed052aaea483346e282c7b02362596e01bb0", size = 208551, upload-time = "2026-07-06T21:34:04.433Z" }, + { url = "https://files.pythonhosted.org/packages/e6/3f/0b04a700dd64f465c93020253a793a82c9b4dff9961f48facd0df945d9b8/cffi-2.1.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7d3538f9c0e50670f4deb93dbb696576e60590369cae2faf7de681e597a8a1f1", size = 221649, upload-time = "2026-07-06T21:34:06.157Z" }, + { url = "https://files.pythonhosted.org/packages/5d/7c/b7379a5704c79eda57ce075869ba70a0368d1c850f803b3c0d078d39dcaf/cffi-2.1.0-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:8f9ec95b8a043d3dfbc74d9abc6f7baf524dd27a8dc160b0a32ff9cdab650c28", size = 225203, upload-time = "2026-07-06T21:34:07.489Z" }, + { url = "https://files.pythonhosted.org/packages/5a/02/d5e6c43ea85c41bda2a184a3418f195fe7cf602967a8d2b94e085b83deef/cffi-2.1.0-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:af5e2915d41fe6c961694d7bfdc8562942638200f3ce2765dfb8b745cf997629", size = 223263, upload-time = "2026-07-06T21:34:08.712Z" }, + { url = "https://files.pythonhosted.org/packages/2c/d8/772b8259bf75749adffb1c546828978381fb516f60cf701f6c83daf60c85/cffi-2.1.0-cp315-cp315-win32.whl", hash = "sha256:0a42c688d19fca6e095a53c6a6e2295a5b050a8b289f109adab02a9e61a25de6", size = 177696, upload-time = "2026-07-06T21:34:26.355Z" }, + { url = "https://files.pythonhosted.org/packages/2f/dd/afa2191fc6d57fedd26e5844a2fe2fcc0bbfa00961bbaa5a41e4921e7cca/cffi-2.1.0-cp315-cp315-win_amd64.whl", hash = "sha256:bccbbb5ee76a61f9d99b5bf3846a51d7fca4b6a732fe46f89295610edaf41853", size = 187914, upload-time = "2026-07-06T21:34:27.58Z" }, + { url = "https://files.pythonhosted.org/packages/05/ef/6cd4f8c671517162379dc79cfae5aea9106bc38abb89628d5c16adf6a838/cffi-2.1.0-cp315-cp315-win_arm64.whl", hash = "sha256:8d35c139744adb3e727cd51b1a18324bbe44b8bd41bf8322bca4d41289f48eda", size = 183004, upload-time = "2026-07-06T21:34:28.905Z" }, + { url = "https://files.pythonhosted.org/packages/11/b6/12fc55092817a5faa26fb8c40c7f9d662e11a46ee248c137aafc42517d92/cffi-2.1.0-cp315-cp315t-macosx_10_15_x86_64.whl", hash = "sha256:f9912624a0c0b834b7520d7769b3644453aabc0a7e1c839da7359f050750e9bc", size = 188378, upload-time = "2026-07-06T21:34:09.926Z" }, + { url = "https://files.pythonhosted.org/packages/8d/2e/cdac88979f295fde5daa69622c7d2111e56e7ceb94f211357fbe452339e4/cffi-2.1.0-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:df92f2aba50eb4d96718b68ef76f2e57a57b54f2fa62333496d16c6d585a85ca", size = 188319, upload-time = "2026-07-06T21:34:11.101Z" }, + { url = "https://files.pythonhosted.org/packages/e0/27/1d0b408497e41a74795af122d7b603c418c5fed0171450f899afd04e594f/cffi-2.1.0-cp315-cp315t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:0520e1f4c35f44e209cbbb421b67eec42e6a157f59444dfb6058874ff3610e5d", size = 223904, upload-time = "2026-07-06T21:34:12.606Z" }, + { url = "https://files.pythonhosted.org/packages/8b/31/e115c985105dd7ffb32444505f18ceb874bb42d992af05d5dced7ecf1980/cffi-2.1.0-cp315-cp315t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:3681e031db29958a7502f5c0c9d6bbc4c36cb20f7b104086fa642d1799631ff8", size = 211554, upload-time = "2026-07-06T21:34:13.987Z" }, + { url = "https://files.pythonhosted.org/packages/5a/67/9e6e09409336d9e515c58367e7cfcf4f89df06ad25252675595a58eb59d5/cffi-2.1.0-cp315-cp315t-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:762f99479dcb369f60ab9017ad4ab97a36a1dd7c1ee5a3b15db0f4b8659120cd", size = 210795, upload-time = "2026-07-06T21:34:15.972Z" }, + { url = "https://files.pythonhosted.org/packages/19/e5/d3cc82a4a0be7902af279c04181ad038449c096734464a5ae1de3e1401bd/cffi-2.1.0-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0611e7ebf90573a535ebdc33ae9da222d037853983e13359f580fab781ca017f", size = 223843, upload-time = "2026-07-06T21:34:17.509Z" }, + { url = "https://files.pythonhosted.org/packages/b9/65/b434abc97ce7cecc2c640fde160507c0ecc7e21544b483ba3325d2e2ea17/cffi-2.1.0-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:86cf8755a791f72c85dc287128cc62d4f24d392e3f1e15837245623f4a33cccc", size = 226773, upload-time = "2026-07-06T21:34:19.05Z" }, + { url = "https://files.pythonhosted.org/packages/b5/9f/d4dc66ca651eb1145a133314cda721abf13cfac3d28c4a0402263ae6ad75/cffi-2.1.0-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:ba00f661f8ba35d075c937174e27c2c421cec3942fd2e0ea3e66996757c0fdd9", size = 225719, upload-time = "2026-07-06T21:34:20.576Z" }, + { url = "https://files.pythonhosted.org/packages/68/5a/e536c528bc8057496c360c0978559a2dc45653f89dd6151078aa7d8fca1a/cffi-2.1.0-cp315-cp315t-win32.whl", hash = "sha256:cb96698e3c7413d906ce83f8ffd245ec1bd94707541f299d0ce4d6b0193e982b", size = 182760, upload-time = "2026-07-06T21:34:22.059Z" }, + { url = "https://files.pythonhosted.org/packages/d3/0b/0ffe8b82d3875bced5fa1e7986a7a46b748262a40ab7f60b475eb9fb1bb3/cffi-2.1.0-cp315-cp315t-win_amd64.whl", hash = "sha256:f146d154428a2523f9cc7936c02353c2459b8f6cf07d3cd1ee1c0a611109c5d5", size = 193769, upload-time = "2026-07-06T21:34:23.589Z" }, + { url = "https://files.pythonhosted.org/packages/a0/17/1073b53b68c9b5ca6914adf5f8bf55aacc2d3be102418c90700160ea8605/cffi-2.1.0-cp315-cp315t-win_arm64.whl", hash = "sha256:cbb7640ce37159548d2147b5b8c241f962143d4c71231431820783f4dc78f210", size = 186405, upload-time = "2026-07-06T21:34:24.857Z" }, +] + [[package]] name = "charset-normalizer" version = "3.4.4" @@ -208,6 +312,56 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/cc/48/d9f421cb8da5afaa1a64570d9989e00fb7955e6acddc5a12979f7666ef60/coverage-7.13.1-py3-none-any.whl", hash = "sha256:2016745cb3ba554469d02819d78958b571792bb68e31302610e898f80dd3a573", size = 210722, upload-time = "2025-12-28T15:42:54.901Z" }, ] +[[package]] +name = "cryptography" +version = "49.0.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "cffi", marker = "platform_python_implementation != 'PyPy'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/1f/99/d1c90d6041656cc6ee229dc99cd67fd0cd5aec3c5f7d72fffc27cc750054/cryptography-49.0.0.tar.gz", hash = "sha256:f89660a348f4f78a92366240a61404e337586ef7f5909a2fef59ca88ef505493", size = 854345, upload-time = "2026-06-12T20:02:30.512Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9b/22/adf66990e63584a68dfb50c24f48a125c07b1699899381c8151e63ed458c/cryptography-49.0.0-cp311-abi3-macosx_11_0_arm64.whl", hash = "sha256:966fe0e9c67490071f14c0d2b1cb2dfb3023c5ce39457343931415f08382f2db", size = 4032100, upload-time = "2026-06-12T20:02:32.143Z" }, + { url = "https://files.pythonhosted.org/packages/09/41/3797cfaf69cae04a13ee78ebd83f0678d9c02b4779d21ce24445326f1a69/cryptography-49.0.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:36d1709f992593689b45bda411498d62c6e365f2ca00b84657d4dadd24de16db", size = 4692978, upload-time = "2026-06-12T20:01:21.305Z" }, + { url = "https://files.pythonhosted.org/packages/e6/8b/43011f7ebe515a8aa20d61f290a326cd890c2e738e16e59eaff8d9c3a412/cryptography-49.0.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:0e959b578856a3924bc0cbb710fc12c387b9412a951389f3ca61704a9e25f325", size = 4716422, upload-time = "2026-06-12T20:01:48.566Z" }, + { url = "https://files.pythonhosted.org/packages/4a/91/01ce7303a4579e6d3a6abef01bd322848e9ea7a219adcabc5048b9033571/cryptography-49.0.0-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:53ecee2e23f7169b6117e99fc8a944e5e50f79e69758a83b52a00cb98ab2b2d2", size = 4700503, upload-time = "2026-06-12T20:02:47.091Z" }, + { url = "https://files.pythonhosted.org/packages/62/99/a2c95cf8293f07491e9e27c20cc4dcd18176d944e674679adeb1d0173fd6/cryptography-49.0.0-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:2eda353d8a27bcbcaa4cbed18994a74ab4d19a2ca897db188ea269ab9b71419b", size = 5309779, upload-time = "2026-06-12T20:02:08.987Z" }, + { url = "https://files.pythonhosted.org/packages/20/2c/0622f20ff02b2ef32558733443805dc82fd4c275be01b2d19d14676f3a1b/cryptography-49.0.0-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:2afe9051da7ae7bd5905da5a949280c7d2bb75682e188f650a9d0f2756b834c6", size = 4749683, upload-time = "2026-06-12T20:02:03.335Z" }, + { url = "https://files.pythonhosted.org/packages/a3/5b/c5246635d5fd3b64e0d45ae10e99fd32fe9676a79915ccfe5a61ba9af1a5/cryptography-49.0.0-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:0b82e28ee398a386f0807bba7884d30f25218855690f45115831bcce5d90822c", size = 4337874, upload-time = "2026-06-12T20:02:54.323Z" }, + { url = "https://files.pythonhosted.org/packages/6d/88/05563c7fe2e914e87d1a536d06fe83e66b4e1d95cb593e05aea375531da8/cryptography-49.0.0-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:ccac2bfebc306b862133e3bb71f3f6ee8bb525240089b2d952e4144b3a6d5da7", size = 4700283, upload-time = "2026-06-12T20:01:34.822Z" }, + { url = "https://files.pythonhosted.org/packages/c4/b6/d7696e4e890d6ae1469935164c9e5215c557671cb78d6e3f458ccceaa632/cryptography-49.0.0-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:d0527ce944105f257f605a827d6ebead966c752038b6e8656abb9c5edee6fc68", size = 5265844, upload-time = "2026-06-12T20:01:24.09Z" }, + { url = "https://files.pythonhosted.org/packages/a9/3c/f3ad17eecc1a57b0ba236dc01f90e783c51f4a2f35f64777cc4f47a184b2/cryptography-49.0.0-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:cbc77da8c523d5abd028635ba850a6966fcee2c82e2bf65a41d1d8afe0f98be9", size = 4749290, upload-time = "2026-06-12T20:01:30.848Z" }, + { url = "https://files.pythonhosted.org/packages/4f/01/339573cf1023163a400b0b5d16f6d507de413b9f60be6fd1b77feeaf6737/cryptography-49.0.0-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:b87e65d263b3e5d3bb92a57e2a6638e2f31110fa7aa890c7b2dbba42248d0a3f", size = 4834612, upload-time = "2026-06-12T20:01:29.246Z" }, + { url = "https://files.pythonhosted.org/packages/71/fd/577302e213a1be9468f92d1afef66fcf1ef83d516819d9992ca547f592bd/cryptography-49.0.0-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:66ec79c3904820572d7e987abdf304281f141d37ad9a489b8e97066e7b9b6459", size = 4980804, upload-time = "2026-06-12T20:01:42.853Z" }, + { url = "https://files.pythonhosted.org/packages/1f/09/f42b1d190c5ba75f72062a387f8030d1d75f6ab035788f1d9c4b01de6525/cryptography-49.0.0-cp311-abi3-win_amd64.whl", hash = "sha256:e5dfc1e64de5677cec922ffa8da89c546d0415bf6efdf081842e5d44c84e1f0e", size = 3810026, upload-time = "2026-06-12T20:02:39.262Z" }, + { url = "https://files.pythonhosted.org/packages/ec/9e/db72b3ae7fc9cfad53e630e56c6ae83b9b6ff0bf3718ffb8012d20b3aabf/cryptography-49.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:73a205dce83953d131a4aa1e0fd917a2fd1c5b1eef251e9d7152efefcbf5caf7", size = 4013892, upload-time = "2026-06-12T20:02:10.735Z" }, + { url = "https://files.pythonhosted.org/packages/86/12/c48a424f38db03027be9f7ed5c7dc5de9933dbee992865f98b13727a009d/cryptography-49.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:196ecd6a36e4e9aa10270393bb98d8df88fccee0bf1e5128b91ae4eb4375896d", size = 4678835, upload-time = "2026-06-12T20:02:48.743Z" }, + { url = "https://files.pythonhosted.org/packages/68/28/8a3ad4653662c93fc44dc4e5d8fd374c25c42e07b34bbfbadf49cf57a5a8/cryptography-49.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7abcee80084cda3f7691f3eb1ce480d8df49cec637b429aa35986c1de71738aa", size = 4697239, upload-time = "2026-06-12T20:02:56.03Z" }, + { url = "https://files.pythonhosted.org/packages/a8/b2/2193fc74f81aee4f9b62733133b73b5176718932ed8f2e4b03fa040480a6/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:4ae387c9cb68ea569ca17e490d66d8142b81c3cc814bf179974b7d146e490bbb", size = 4685593, upload-time = "2026-06-12T20:02:50.666Z" }, + { url = "https://files.pythonhosted.org/packages/47/f1/1d3eaa243bfc5de4a187b22aa8c048b3e4980bfbe830ac46e6bac2e66947/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:f37d847238971164fdbc68ade6f6574aecc9c0af714190e2083429ff68f4ce9d", size = 5289961, upload-time = "2026-06-12T20:01:46.468Z" }, + { url = "https://files.pythonhosted.org/packages/58/39/2d51306721330c486495853eda1c567880ff036de15a14c4b74f399934af/cryptography-49.0.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:c2bc30226390d60ea19d9f82b19db005fe0452154a23c1c410c12ea801e43561", size = 4731145, upload-time = "2026-06-12T20:02:16.832Z" }, + { url = "https://files.pythonhosted.org/packages/17/50/983e838c7fd0d87fd8c969bcdd328edaf5f756e38df5281637424c155873/cryptography-49.0.0-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:07cab27cc7b7e0fd28e5e26bb9eeedde5c135c868b46de4a27845abe94af6122", size = 4321719, upload-time = "2026-06-12T20:02:52.611Z" }, + { url = "https://files.pythonhosted.org/packages/a7/f5/8f571d7e27c55bce9f76f026143bcb1e040a4233149ecca0bea5fa5dd5f7/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:b20133d204d2bb56ba047642199603876c872026ca53e79c35b83772ab2cc505", size = 4685209, upload-time = "2026-06-12T20:02:07.282Z" }, + { url = "https://files.pythonhosted.org/packages/e7/84/0e27016a6fc5a0886f797018b26aa42f40c09a82332bff77822a451deaaa/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:b970c6da94d5bb18629db453d14f2a1300f6bf59b61e9b82377931ef95504866", size = 5246285, upload-time = "2026-06-12T20:01:32.439Z" }, + { url = "https://files.pythonhosted.org/packages/11/2d/5e1fb307cb5931881516b464c98774b3f2c36b5d4bb9a2830253cf553cad/cryptography-49.0.0-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:d8ecde755e2e91bf773fc94e8c9d730cd7f2007004cb492263a794ec3899a1c8", size = 4730441, upload-time = "2026-06-12T20:02:01.469Z" }, + { url = "https://files.pythonhosted.org/packages/e4/c0/bff5a02ee731d207d6a1ed51732549d8c53d2bc8da1d10ec6f2844201d68/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:e3fb64c420688e5319ae25113a354015abbd8dffbfbc41781a1ea66fc7622ac3", size = 4815869, upload-time = "2026-06-12T20:01:36.574Z" }, + { url = "https://files.pythonhosted.org/packages/b9/26/814681d14248d95d73d5c3eea0c39a94eb8302df966f670a2c60de90974b/cryptography-49.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:32703d93296f5c1f4b53349ad3a250c2cae0fdecd3a3dd5d47e616d8d616af27", size = 4960948, upload-time = "2026-06-12T20:02:18.688Z" }, + { url = "https://files.pythonhosted.org/packages/4c/fe/93ecac273d3738939d023612ad12cca9a3740a5345d69fda04134c43fd96/cryptography-49.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:33cd0565932807baddb67b96dbee92f2c374b5c89dee09fd74079aeb8c8dba61", size = 3799153, upload-time = "2026-06-12T20:01:39.059Z" }, + { url = "https://files.pythonhosted.org/packages/19/2a/5bb823f5bedcf80718cea7fbc95ec5515cca3769633c4b01a32be7f30e7c/cryptography-49.0.0-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:ec5e529fb80935c94fe7b729f9972b50e351a0e6b50aa294fd5cabb109fcc29a", size = 4025947, upload-time = "2026-06-12T20:01:25.745Z" }, + { url = "https://files.pythonhosted.org/packages/3d/df/40577043ca124e17012f408ddddaeb213b856336ac82ddb3bc915f39e29f/cryptography-49.0.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f78ff2c9ed8dc2d036b0f4d640e22522213d047c1b14e61205a7e55c80a494d4", size = 4692429, upload-time = "2026-06-12T20:01:53.628Z" }, + { url = "https://files.pythonhosted.org/packages/2c/99/2d13299eb3dd27b02dcfaafcc91d6b5cb3329f7cbd6d8f51921acd566c1a/cryptography-49.0.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:35b151772baff2c74cba7fa290ceaff4c3b11c0c881eb93eb5dbc05a7cfbba18", size = 4700968, upload-time = "2026-06-12T20:02:45.383Z" }, + { url = "https://files.pythonhosted.org/packages/a5/4d/9c0cd02f95e2602dd5e563da149ee0830abef3537be8b34dc56281ebe27a/cryptography-49.0.0-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:0f21641cf4b30fca7aee061ced0ec7ad7b073518088b7c9969a297c0ae796c69", size = 4697758, upload-time = "2026-06-12T20:01:41.13Z" }, + { url = "https://files.pythonhosted.org/packages/24/01/186c825898477d77e2324d5360fefe622ff1d8d1963ec0554e2cada8ec77/cryptography-49.0.0-cp39-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:9e82dcc8e56052715fb18b2429e3bca4823b1629136a2084fc45a9a5cecb9b64", size = 5298863, upload-time = "2026-06-12T20:02:24.579Z" }, + { url = "https://files.pythonhosted.org/packages/b8/7b/62cbbab75d0659865bf0273790031544a0b16c8072d258f9428dcd8190dc/cryptography-49.0.0-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:6f2debedf9ca60cf1d5bd466475638af5130f89965605cd818484d19987d3a21", size = 4735983, upload-time = "2026-06-12T20:01:50.14Z" }, + { url = "https://files.pythonhosted.org/packages/6c/72/3e798c064bc39e471008075d0f9bc9daf77a80879c092e4a8e170c585ed4/cryptography-49.0.0-cp39-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:8c25ceb16df5b9435f3f6a9829204985b0e0cbee3b48aacd432c7d2c850b44d9", size = 4334173, upload-time = "2026-06-12T20:01:44.743Z" }, + { url = "https://files.pythonhosted.org/packages/f0/ee/6fca21d1ac73e06f8bef71940abfd4d2f6472b4bca284d770f32bd4086f6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:28d8b15e6275f12c8a207dc309dfa957903c927d08d0cc937ee3f63f200693cc", size = 4697298, upload-time = "2026-06-12T20:02:20.918Z" }, + { url = "https://files.pythonhosted.org/packages/67/d0/a5fcd3515f0bae49a7b6d0413cc1bdccdcc1fc0047037a0d480642cdc5d6/cryptography-49.0.0-cp39-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:6fc361c34fb6aac015ce19435876635e5c6d21db31998b0920f675f131e043b8", size = 5254338, upload-time = "2026-06-12T20:02:22.737Z" }, + { url = "https://files.pythonhosted.org/packages/a0/84/84fe36f19caf857d61cb7fc9c63035a47ffabd84ea12d1d393148efa3615/cryptography-49.0.0-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:2400ef9c9e2299a25614eb1dea3db54a69b1349efd043bfac9c67630d136df36", size = 4735650, upload-time = "2026-06-12T20:02:41.389Z" }, + { url = "https://files.pythonhosted.org/packages/6c/a0/db537264e234f7273a73ec020873d6d6b39dfd8a53db78b550ca8320440e/cryptography-49.0.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:67e1d20ad9ef3a563c59ef22e7a8a0b8210bd26604369ea4a30a7c66aefe504e", size = 4834820, upload-time = "2026-06-12T20:01:51.847Z" }, + { url = "https://files.pythonhosted.org/packages/93/77/8df9eb486495979bccecd1062e2eaf435250e84437040295b57d09048b0b/cryptography-49.0.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:42b0684e0e40cf26122427802486f6d93aea593612603a94fbf260c7eb1e9c1b", size = 4967968, upload-time = "2026-06-12T20:02:12.524Z" }, + { url = "https://files.pythonhosted.org/packages/c2/e6/f60198ea8d9dfa15fff9ed4ca02ce362f6eadd9ba757dcc50634c4257b63/cryptography-49.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:026ac7423e6fa66872d3bf889be5974507da3944f866f704fa200eadacd00001", size = 3785547, upload-time = "2026-06-12T20:02:26.847Z" }, +] + [[package]] name = "defusedxml" version = "0.7.1" @@ -298,6 +452,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" }, ] +[[package]] +name = "httpx-sse" +version = "0.4.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/0f/4c/751061ffa58615a32c31b2d82e8482be8dd4a89154f003147acee90f2be9/httpx_sse-0.4.3.tar.gz", hash = "sha256:9b1ed0127459a66014aec3c56bebd93da3c1bc8bb6618c8082039a44889a755d", size = 15943, upload-time = "2025-10-10T21:48:22.271Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d2/fd/6668e5aec43ab844de6fc74927e155a3b37bf40d7c3790e49fc0406b6578/httpx_sse-0.4.3-py3-none-any.whl", hash = "sha256:0ac1c9fe3c0afad2e0ebb25a934a59f4c7823b60792691f779fad2c5568830fc", size = 8960, upload-time = "2025-10-10T21:48:21.158Z" }, +] + [[package]] name = "idna" version = "3.11" @@ -328,6 +491,33 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899, upload-time = "2025-03-05T20:05:00.369Z" }, ] +[[package]] +name = "jsonschema" +version = "4.26.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "attrs" }, + { name = "jsonschema-specifications" }, + { name = "referencing" }, + { name = "rpds-py" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583, upload-time = "2026-01-07T13:41:07.246Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630, upload-time = "2026-01-07T13:41:05.306Z" }, +] + +[[package]] +name = "jsonschema-specifications" +version = "2025.9.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "referencing" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/19/74/a633ee74eb36c44aa6d1095e7cc5569bebf04342ee146178e2d36600708b/jsonschema_specifications-2025.9.1.tar.gz", hash = "sha256:b540987f239e745613c7a9176f3edb72b832a4ac465cf02712288397832b5e8d", size = 32855, upload-time = "2025-09-08T01:34:59.186Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" }, +] + [[package]] name = "markdown" version = "3.10" @@ -412,6 +602,31 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/70/bc/6f1c2f612465f5fa89b95bead1f44dcb607670fd42891d8fdcd5d039f4f4/markupsafe-3.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa", size = 14146, upload-time = "2025-09-27T18:37:28.327Z" }, ] +[[package]] +name = "mcp" +version = "1.28.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anyio" }, + { name = "httpx" }, + { name = "httpx-sse" }, + { name = "jsonschema" }, + { name = "pydantic" }, + { name = "pydantic-settings" }, + { name = "pyjwt", extra = ["crypto"] }, + { name = "python-multipart" }, + { name = "pywin32", marker = "sys_platform == 'win32'" }, + { name = "sse-starlette" }, + { name = "starlette" }, + { name = "typing-extensions" }, + { name = "typing-inspection" }, + { name = "uvicorn", marker = "sys_platform != 'emscripten'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/6e/77/9450b8f251a13affb6281997d0523c4615f8a8b35d0b21ff30db3a5aac9d/mcp-1.28.1.tar.gz", hash = "sha256:d51e36a5f5644faea4f85ea649bfffa6bc6c26770d42798ad6a3de3d2ba69683", size = 638501, upload-time = "2026-06-26T12:57:29.093Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e2/5e/d118fce19f87a2e7d8101c35c8ae0ec289098a4df0ff244cec23e415aca0/mcp-1.28.1-py3-none-any.whl", hash = "sha256:2726bca5e7193f61c5dde8b12500a6de2d9acf6d1a1c0be9e8c2e706437991df", size = 222620, upload-time = "2026-06-26T12:57:27.218Z" }, +] + [[package]] name = "mdurl" version = "0.1.2" @@ -663,6 +878,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/54/20/4d324d65cc6d9205fabedc306948156824eb9f0ee1633355a8f7ec5c66bf/pluggy-1.6.0-py3-none-any.whl", hash = "sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746", size = 20538, upload-time = "2025-05-15T12:30:06.134Z" }, ] +[[package]] +name = "pycparser" +version = "3.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/1b/7d/92392ff7815c21062bea51aa7b87d45576f649f16458d78b7cf94b9ab2e6/pycparser-3.0.tar.gz", hash = "sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29", size = 103492, upload-time = "2026-01-21T14:26:51.89Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/0c/c3/44f3fbbfa403ea2a7c779186dc20772604442dde72947e7d01069cbe98e3/pycparser-3.0-py3-none-any.whl", hash = "sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992", size = 48172, upload-time = "2026-01-21T14:26:50.693Z" }, +] + [[package]] name = "pydantic" version = "2.12.5" @@ -749,6 +973,20 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f7/07/34573da085946b6a313d7c42f82f16e8920bfd730665de2d11c0c37a74b5/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:76d0819de158cd855d1cbb8fcafdf6f5cf1eb8e470abe056d5d161106e38062b", size = 2139017, upload-time = "2025-11-04T13:42:59.471Z" }, ] +[[package]] +name = "pydantic-settings" +version = "2.14.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pydantic" }, + { name = "python-dotenv" }, + { name = "typing-inspection" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/5c/b5/8f48e906c3e0205276e8bd8cb7512217a87b2685304d64be27cad5b3019f/pydantic_settings-2.14.2.tar.gz", hash = "sha256:c19dd64b19097f1de80184f0cc7b0272a13ae6e170cbf240a3e27e381ed14a5f", size = 237700, upload-time = "2026-06-19T13:44:56.324Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/77/c1/6e422f34e569cf8e18df68d1939c81c099d2b61e4f7d9621c8a77560799c/pydantic_settings-2.14.2-py3-none-any.whl", hash = "sha256:a20c97b37910b6550d5ea50fbcc2d4187defe58cd57070b73863d069419c9440", size = 61715, upload-time = "2026-06-19T13:44:55.02Z" }, +] + [[package]] name = "pygments" version = "2.19.2" @@ -758,6 +996,20 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" }, ] +[[package]] +name = "pyjwt" +version = "2.13.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/3b/81/58d0ac84e1ef3a3843791d6954d94c0b33d526c75eeb1efbce9d0a4c4077/pyjwt-2.13.0.tar.gz", hash = "sha256:41571c89ca91598c79e8ef18a2d07367d4810fbbd6f637794879baf1b7703423", size = 107515, upload-time = "2026-05-21T19:54:36.618Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/a3/5e/ecf12fdb62546d64385c158514e9b2b671f7832108ef2ecd2020ce0af2d1/pyjwt-2.13.0-py3-none-any.whl", hash = "sha256:66adcc2aff09b3f1bbd95fc1e1577df8ac8723c978552fd43304c8a290ac5728", size = 31274, upload-time = "2026-05-21T19:54:35.362Z" }, +] + +[package.optional-dependencies] +crypto = [ + { name = "cryptography" }, +] + [[package]] name = "pymdown-extensions" version = "10.20" @@ -826,6 +1078,43 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/ec/57/56b9bcc3c9c6a792fcbaf139543cee77261f3651ca9da0c93f5c1221264b/python_dateutil-2.9.0.post0-py2.py3-none-any.whl", hash = "sha256:a8b2bc7bffae282281c8140a97d3aa9c14da0b136dfe83f850eea9a5f7470427", size = 229892, upload-time = "2024-03-01T18:36:18.57Z" }, ] +[[package]] +name = "python-dotenv" +version = "1.2.2" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/82/ed/0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8/python_dotenv-1.2.2.tar.gz", hash = "sha256:2c371a91fbd7ba082c2c1dc1f8bf89ca22564a087c2c287cd9b662adde799cf3", size = 50135, upload-time = "2026-03-01T16:00:26.196Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" }, +] + +[[package]] +name = "python-multipart" +version = "0.0.32" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/5b/42/55c32bb9b12693c092ad250a0e82edb5b31ddeda6eb772de5f308b3804ad/python_multipart-0.0.32.tar.gz", hash = "sha256:be54b7f3fa167bb83e4fcd936b887b708f4e57fe75911c02aebf53efaf8d938e", size = 46881, upload-time = "2026-06-04T16:18:58.647Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/e1/04/e8135ebd1ad02c56ec633277529b2602ff99ff634be76cdba5744cf554fd/python_multipart-0.0.32-py3-none-any.whl", hash = "sha256:ff6d3f776f16878c894e52e107296ffc890e913c611b1a4ec6c44e2821fe2e23", size = 30042, upload-time = "2026-06-04T16:18:57.319Z" }, +] + +[[package]] +name = "pywin32" +version = "312" +source = { registry = "https://pypi.org/simple" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/83/ff/32aa7d2ed0ab12b323aaa64f9b75e6ad4f8fd09f9ccfc28c79414d46838d/pywin32-312-cp312-cp312-win32.whl", hash = "sha256:dab4f65ac9c4e48400a2a0530c46c3c579cd5905ecd11b80692373915269208b", size = 6371877, upload-time = "2026-06-04T07:49:28.836Z" }, + { url = "https://files.pythonhosted.org/packages/03/d9/77040d3b43df3f3be32ea289433d660d2727f5ba327bc73be835127d9d60/pywin32-312-cp312-cp312-win_amd64.whl", hash = "sha256:b457f6d628a47e8a7346ce22acb7e1a46a4a78b52e1d17e1af56871bd19a93bc", size = 6914841, upload-time = "2026-06-04T07:49:31.85Z" }, + { url = "https://files.pythonhosted.org/packages/e3/cc/7b1ec671775756020a0ee7f4feeaf3c568f0ab86bd3900088cf986937a92/pywin32-312-cp312-cp312-win_arm64.whl", hash = "sha256:6017c58e12f6809fbb0555b75df144c2922a9ffd18e4b9b5afa863b6c1a9d950", size = 6727901, upload-time = "2026-06-04T07:49:34.244Z" }, + { url = "https://files.pythonhosted.org/packages/2d/41/12fbfd7f36ed2146d8bc9de96c2741296bf0d490b98508496cff322e274c/pywin32-312-cp313-cp313-win32.whl", hash = "sha256:7a27df850933d16a8eabfbaeb73d52b273e2da667f80d70b01a89d1f6828d02c", size = 6370184, upload-time = "2026-06-04T07:49:36.253Z" }, + { url = "https://files.pythonhosted.org/packages/ba/db/36a78e3403099d31d9746d13fdcde5accc43c1155f375a34d15983a479a7/pywin32-312-cp313-cp313-win_amd64.whl", hash = "sha256:c53e878d15a1c44788082bfe712a905433473aa38f86375b7cf8b45e3acbaaf9", size = 6914298, upload-time = "2026-06-04T07:49:38.876Z" }, + { url = "https://files.pythonhosted.org/packages/84/37/c1697194092b76de9ed47ca124323f02c57ffc8a45c06f88a3d5acaf01eb/pywin32-312-cp313-cp313-win_arm64.whl", hash = "sha256:59aba5d5940842075343a5ddc6b11f1cdf0d1567fe745290359dfbcc7c2eb831", size = 6727640, upload-time = "2026-06-04T07:49:41.083Z" }, + { url = "https://files.pythonhosted.org/packages/fc/2b/1f3cded5822fd49c02f40544cbb5f58c7cfd6b1694869fd476cb6170ee97/pywin32-312-cp314-cp314-win32.whl", hash = "sha256:a77a90fbb6881238d2ca9c6fd797b25817f3768fe78d214a90137ff055a75f5b", size = 6468928, upload-time = "2026-06-04T07:49:43.188Z" }, + { url = "https://files.pythonhosted.org/packages/21/82/3bf86d2e2808902013132e1ce905a7da0da53790f3836c64bf44d55e24f3/pywin32-312-cp314-cp314-win_amd64.whl", hash = "sha256:a4dd3a848290ef724347b19f301045831d8e802fa4464f491b98b1e0a081432e", size = 7024157, upload-time = "2026-06-04T07:49:45.34Z" }, + { url = "https://files.pythonhosted.org/packages/a4/0e/73f6d6800b4f27655abd9e9f6aaeaefcddb2b946e4674efa2bab184a7f7b/pywin32-312-cp314-cp314-win_arm64.whl", hash = "sha256:9fce94568364e0155e6dfb781ac5d95903be8baf28670632beab1b523f300daa", size = 6839598, upload-time = "2026-06-04T07:49:47.613Z" }, + { url = "https://files.pythonhosted.org/packages/eb/61/caa39686032d2ebdd04ff0ab5cbe163126c0066d98e00c9018646e42393b/pywin32-312-cp315-cp315-win32.whl", hash = "sha256:5c1fbe4a937a73ae9297384a3da38518cbc694c68ad8a809b2e19acd350f03ed", size = 6471159, upload-time = "2026-06-04T07:49:50.035Z" }, + { url = "https://files.pythonhosted.org/packages/0f/cd/7e1de64a4a6f69c04214169657ccab0d93a670ea50e35eb8f489d7378249/pywin32-312-cp315-cp315-win_amd64.whl", hash = "sha256:c2f03a0f73f804a13c2735b99392b0cd426bb4f2c4d0178e5ac966a0f21618d5", size = 7025293, upload-time = "2026-06-04T07:49:54.857Z" }, + { url = "https://files.pythonhosted.org/packages/23/ed/4532e9388e65fa16b46776ef47ad631a64eda1631884488af707666350ed/pywin32-312-cp315-cp315-win_arm64.whl", hash = "sha256:a8597d28f267b39074aef51fa593530082b39cbe5a074226096857b1fed2dfb9", size = 6840337, upload-time = "2026-06-04T07:49:57.531Z" }, +] + [[package]] name = "pyyaml" version = "6.0.3" @@ -886,7 +1175,7 @@ wheels = [ [[package]] name = "readwise-plus" -version = "0.1.3" +version = "0.2.1" source = { editable = "." } dependencies = [ { name = "httpx" }, @@ -898,10 +1187,14 @@ cli = [ { name = "rich" }, { name = "typer" }, ] +mcp = [ + { name = "mcp" }, +] [package.dev-dependencies] dev = [ { name = "genbadge", extra = ["coverage"] }, + { name = "mcp" }, { name = "mkdocs" }, { name = "mkdocs-material" }, { name = "mkdocstrings", extra = ["python"] }, @@ -921,15 +1214,17 @@ docs = [ [package.metadata] requires-dist = [ { name = "httpx", specifier = ">=0.27.0" }, + { name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.26.0" }, { name = "pydantic", specifier = ">=2.0.0" }, { name = "rich", marker = "extra == 'cli'", specifier = ">=14.0.0" }, { name = "typer", marker = "extra == 'cli'", specifier = ">=0.21.0" }, ] -provides-extras = ["cli"] +provides-extras = ["cli", "mcp"] [package.metadata.requires-dev] dev = [ { name = "genbadge", extras = ["coverage"], specifier = ">=1.1.3" }, + { name = "mcp", specifier = ">=1.26.0" }, { name = "mkdocs", specifier = ">=1.6.1" }, { name = "mkdocs-material", specifier = ">=9.7.1" }, { name = "mkdocstrings", extras = ["python"], specifier = ">=1.0.0" }, @@ -946,6 +1241,20 @@ docs = [ { name = "mkdocstrings", extras = ["python"], specifier = ">=1.0.0" }, ] +[[package]] +name = "referencing" +version = "0.37.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "attrs" }, + { name = "rpds-py" }, + { name = "typing-extensions", marker = "python_full_version < '3.13'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/22/f5/df4e9027acead3ecc63e50fe1e36aca1523e1719559c499951bb4b53188f/referencing-0.37.0.tar.gz", hash = "sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8", size = 78036, upload-time = "2025-10-13T15:30:48.871Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" }, +] + [[package]] name = "requests" version = "2.32.5" @@ -986,6 +1295,102 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/25/7a/b0178788f8dc6cafce37a212c99565fa1fe7872c70c6c9c1e1a372d9d88f/rich-14.2.0-py3-none-any.whl", hash = "sha256:76bc51fe2e57d2b1be1f96c524b890b816e334ab4c1e45888799bfaab0021edd", size = 243393, upload-time = "2025-10-09T14:16:51.245Z" }, ] +[[package]] +name = "rpds-py" +version = "2026.6.3" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/aa/2a/9618a122aeb2a169a28b03889a2995fe297588964333d4a7d67bdf46e147/rpds_py-2026.6.3.tar.gz", hash = "sha256:1cebd1337c242e4ec2293e541f712b2da849b29f48f0c293684b71c0632625d4", size = 64051, upload-time = "2026-06-30T07:17:53.009Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5c/be/2e8974163072e7bab7df1a5acd54c4498e75e35d6d18b864d3a9d5dadc92/rpds_py-2026.6.3-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:a0811d33247c3d6128a3001d763f2aa056bb3425204335400ac54f89eec3a0d0", size = 343691, upload-time = "2026-06-30T07:15:14.96Z" }, + { url = "https://files.pythonhosted.org/packages/a4/73/319dfa745dd668efe89309141ded489126461fcecd2b8f3a3cda185129b6/rpds_py-2026.6.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:538949e262e46caa31ac01bdb3c1e8f642622922cacbabbae6a8445d9dc33eaf", size = 338542, upload-time = "2026-06-30T07:15:16.267Z" }, + { url = "https://files.pythonhosted.org/packages/21/63/4239893be1c4d09b709b1a8f6be4188f0870084ff547f46606b8a75f1b03/rpds_py-2026.6.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:55927d532399c2c646100ff7feb48eaa940ad70f42cd68e1328f3ded9f81ca24", size = 368180, upload-time = "2026-06-30T07:15:17.62Z" }, + { url = "https://files.pythonhosted.org/packages/1c/ca/9c5de382225234ceb37b1844ebdb140db12b2a278bb9efe2fcd19f6c82ce/rpds_py-2026.6.3-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f56f1695bc5c0871cbc33dc0130fcf503aab0c57dcc5a6700a4f49eba4f2652e", size = 375067, upload-time = "2026-06-30T07:15:18.952Z" }, + { url = "https://files.pythonhosted.org/packages/87/dc/863f69d1bf04ade34b7fe0d59b9fdf6f0135fe2d7cbca74f1d665589559d/rpds_py-2026.6.3-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:270b293dae9058fc9fcedab50f13cebf46fb8ed1d1d54e0521a9da5d6b211975", size = 490509, upload-time = "2026-06-30T07:15:20.434Z" }, + { url = "https://files.pythonhosted.org/packages/ce/ef/eac16a12048b45ec7c7fa94f2be3438a5f26bf9cc8580b18a1cfd609b7f6/rpds_py-2026.6.3-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:127565fead0a10943b282957bd5447804ff3160ad79f2ad2635e6d249e380680", size = 382754, upload-time = "2026-06-30T07:15:21.831Z" }, + { url = "https://files.pythonhosted.org/packages/04/8f/d2f3f532616be4d06c316ef119683e832bd3d41e112bf3a88f4151c95b17/rpds_py-2026.6.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ecabd69db66de867690f9797f2f8fa27ba501bbc24540cbdbdc649cd15888ba6", size = 366189, upload-time = "2026-06-30T07:15:23.371Z" }, + { url = "https://files.pythonhosted.org/packages/e3/29/41a7b0e98a4b44cd676ab7598419623373eb43b20be68c084935c1a8cf88/rpds_py-2026.6.3-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:58eadac9cd119677b60e1cf8ac4052f35949d71b8a9e5556efccbe82533cf22a", size = 377750, upload-time = "2026-06-30T07:15:24.659Z" }, + { url = "https://files.pythonhosted.org/packages/2e/05/ecda0bec46f9a1565090bcdc941d023f6a25aff85fda28f89f8d19878152/rpds_py-2026.6.3-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:7491ee23305ac3eb59e492b6945881f5cd77a6f731061a3f25b77fd40f9e99a4", size = 395576, upload-time = "2026-06-30T07:15:25.987Z" }, + { url = "https://files.pythonhosted.org/packages/68/a8/6ed52f03ee6cb854ce78785cc9a9a672eb880e83fd7224d471f667d151f1/rpds_py-2026.6.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:2c99f7e8ccb3dd6e3e4bfeac657a7b208c9bac8075f4b078c02d7404c34107fa", size = 543807, upload-time = "2026-06-30T07:15:27.356Z" }, + { url = "https://files.pythonhosted.org/packages/8f/d6/156c0d3eea27ba09b92562ba2364ba124c0a061b199e17eac637cd25a5e2/rpds_py-2026.6.3-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:62698275682bf121181861295c9181e789030a2d516071f5b8f3c23c170cd0fc", size = 611187, upload-time = "2026-06-30T07:15:28.931Z" }, + { url = "https://files.pythonhosted.org/packages/f1/31/774212ed989c62f7f310220089f9b0a3fb8f40f5443d1727abd5d9f52bc9/rpds_py-2026.6.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:a214c993455f99a89aaeadc9b21241900037adc9d97203e374d75513c5911822", size = 573030, upload-time = "2026-06-30T07:15:30.553Z" }, + { url = "https://files.pythonhosted.org/packages/c9/50/22f73127a41f1ce4f87fe39aadfb9a126345801c274aa93ae88456249327/rpds_py-2026.6.3-cp312-cp312-win32.whl", hash = "sha256:501f9f04a588d6a09179368c57071301445191767c64e4b52a6aa9871f1ef5ed", size = 202185, upload-time = "2026-06-30T07:15:32.027Z" }, + { url = "https://files.pythonhosted.org/packages/04/3a/f0ee4d4dde9d3b69dedf1b5f74e7a40017046d55052d173e418c6a94f960/rpds_py-2026.6.3-cp312-cp312-win_amd64.whl", hash = "sha256:2c958bf94822e9290a40aaf2a822d4bc5c88099093e3948ad6c571eca9272e5f", size = 220394, upload-time = "2026-06-30T07:15:33.359Z" }, + { url = "https://files.pythonhosted.org/packages/f3/83/3382fe37f809b59f02aac04dbc4e765b480b46ee0227ed516e3bdc4d3dfc/rpds_py-2026.6.3-cp312-cp312-win_arm64.whl", hash = "sha256:22bffe6042b9bcb0822bcd1955ec00e245daf17b4344e4ed8e9551b976b63e96", size = 215753, upload-time = "2026-06-30T07:15:34.778Z" }, + { url = "https://files.pythonhosted.org/packages/a4/9e/b818ee580026ec578138e961027a68820c40afeb1ec8f6819b54fb99e196/rpds_py-2026.6.3-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:3cfe765c1da0072636ca06628261e0ea05688e160d5c8a03e0217c3854037223", size = 343012, upload-time = "2026-06-30T07:15:36.005Z" }, + { url = "https://files.pythonhosted.org/packages/f3/6b/686d9dc4359a8f163cfbbf89ee0b4e586431de22fe8248edb63a8cf50d49/rpds_py-2026.6.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:f4d78253f6996be4901669ad25319f842f740eccf4d58e3c7f3dd39e6dde1d8f", size = 338203, upload-time = "2026-06-30T07:15:37.462Z" }, + { url = "https://files.pythonhosted.org/packages/9e/9b/069aa329940f8207615e091f5eedbbd40e1e15eac68a0790fd05ccdf796c/rpds_py-2026.6.3-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:54f45a148e28767bf343d33a684693c70e451c6f4c0e9904709a723fafbdfc1f", size = 367984, upload-time = "2026-06-30T07:15:39.008Z" }, + { url = "https://files.pythonhosted.org/packages/14/db/34c203e4becff3703e4d3bc121842c00b8689197f398161203a880052f4e/rpds_py-2026.6.3-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:842e7b070435622248c7a2c44ae53fa1440e073cc3023bc919fed570884097a7", size = 374815, upload-time = "2026-06-30T07:15:40.253Z" }, + { url = "https://files.pythonhosted.org/packages/ee/7d/8071067d2cc453d916ad836e828c943f575e8a44612537759002a1e07381/rpds_py-2026.6.3-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8020133a74bd81b4572dd8e4be028a6b1ebcd70e6726edc3918008c08bee6ee6", size = 490545, upload-time = "2026-06-30T07:15:41.729Z" }, + { url = "https://files.pythonhosted.org/packages/a3/42/da06c5aa8f0484ff07f270787434204d9f4535e2f8c3b51ed402267e63c3/rpds_py-2026.6.3-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cdc7e35386f3847df728fbcb5e887e2d79c19e2fa1eba9e51b6621d23e3243af", size = 382828, upload-time = "2026-06-30T07:15:43.327Z" }, + { url = "https://files.pythonhosted.org/packages/57/d7/fe978efc2ae50abe48eb7464668ea99f53c010c60aeebb7b35ad27f23661/rpds_py-2026.6.3-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:acac386b453c2516111b50985d60ce46e7fadb5ea71ae7b25f4c946935bf27cf", size = 365678, upload-time = "2026-06-30T07:15:44.992Z" }, + { url = "https://files.pythonhosted.org/packages/69/9d/1d8922e1990b2a6eb532b6ff53d3e73d2b3bbffc84116c75826bee73dfc6/rpds_py-2026.6.3-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:425560c6fa0415f27261727bb20bd097568485e5eb0c121f1949417d1c516885", size = 377811, upload-time = "2026-06-30T07:15:46.523Z" }, + { url = "https://files.pythonhosted.org/packages/b1/3d/198dceafb4fb034a6a47347e1b0735d34e0bd4a50be4e898d408ee66cb14/rpds_py-2026.6.3-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a550fb4950a06dde3beb4721f5ad4b25bf4513784665b0a8522c792e2bd822a4", size = 395382, upload-time = "2026-06-30T07:15:47.955Z" }, + { url = "https://files.pythonhosted.org/packages/1f/f1/13968e49655d40b6b19d8b9140296bbc6f1d86b3f0f6c346cf9f1adddf4b/rpds_py-2026.6.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:4f4bca01b63096f606e095734dd56e74e175f94cfbf24ff3d63281cec61f7bb7", size = 543832, upload-time = "2026-06-30T07:15:49.33Z" }, + { url = "https://files.pythonhosted.org/packages/ac/ab/289bcb1b90bd3e40a2900c561fa0e2087345ecbb094f0b870f2345142b7c/rpds_py-2026.6.3-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:ccffae9a092a00deb7efd545fe5e2c33c33b88e7c054337e9a74c179347d0b7d", size = 611011, upload-time = "2026-06-30T07:15:50.847Z" }, + { url = "https://files.pythonhosted.org/packages/1e/16/5043105e679436ccfbc8e5e0dd2d663ed18a8b8113515fd06a5e5d77c83e/rpds_py-2026.6.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:1cf01971c4f2c5553b772a542e4aaf191789cd331bc2cd4ff0e6e65ba49e1e97", size = 572431, upload-time = "2026-06-30T07:15:52.394Z" }, + { url = "https://files.pythonhosted.org/packages/85/ed/adab103321c0a6565d5ae1c2998349bc3ee175b82ccc5ae8fc04cc413075/rpds_py-2026.6.3-cp313-cp313-win32.whl", hash = "sha256:8c3d1e9c15b9d51ca0391e13da1a25a0a4df3c58a37c9dc368e0736cf7f69df0", size = 201710, upload-time = "2026-06-30T07:15:53.894Z" }, + { url = "https://files.pythonhosted.org/packages/7b/ed/a03b09668e74e5dabbf2e211f6468e1820c0552f7b0500082da31841bf7b/rpds_py-2026.6.3-cp313-cp313-win_amd64.whl", hash = "sha256:9250a9a0a6fd4648b3f868da8d91a4c52b5811a62df58e753d50ae4454a36f80", size = 219454, upload-time = "2026-06-30T07:15:55.25Z" }, + { url = "https://files.pythonhosted.org/packages/27/17/b8642c12930b71bc2b25831f6708ccf0f75abcd11883932ec9ce54ba3a78/rpds_py-2026.6.3-cp313-cp313-win_arm64.whl", hash = "sha256:900a67df3fd1660b035a4761c4ce73c382ea6b35f90f9863c36c6fd8bf8b09bb", size = 215063, upload-time = "2026-06-30T07:15:56.573Z" }, + { url = "https://files.pythonhosted.org/packages/b6/36/7fbe9dcdaf857fb3f63c2a2284b62492d95f5e8334e947e5fb6e7f68c9be/rpds_py-2026.6.3-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:931908d9fc855d8f74783377822be318edb6dcb19e47169dc038f9a1bf60b06e", size = 344510, upload-time = "2026-06-30T07:15:57.921Z" }, + { url = "https://files.pythonhosted.org/packages/ba/54/f785cc3d3f60839ca57a5af4927a9f347b07b2799c373fc20f7949f87c7e/rpds_py-2026.6.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:d7469697dce35be237db177d42e2a2ee26e6dcc5fc052078a6fefabd288c6edd", size = 339495, upload-time = "2026-06-30T07:15:59.238Z" }, + { url = "https://files.pythonhosted.org/packages/63/ef/d4cdaf309e6b095b43597103cf8c0b951d6cca2acce68c474f75ec12e0c7/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:bcfbcf66006befb9fd2aeaa9e01feaf881b4dc330a02ba07d2322b1c11be7b5d", size = 369454, upload-time = "2026-06-30T07:16:01.021Z" }, + { url = "https://files.pythonhosted.org/packages/96/4a/9559a68b7ee15db09d7981212e8c2e219d2a1d6d4faa0391d813c3496a36/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:847927daf4cffbd4e90e42bc890069897101edd015f956cb8721b3473372edda", size = 374583, upload-time = "2026-06-30T07:16:02.287Z" }, + { url = "https://files.pythonhosted.org/packages/ef/75/8964aa7d2c6e8ac43eba8eb6e6b0fdda1f46d39f2fc3e6aa9f2cb17f485d/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:aca6c1ef08a82bfe327cc156da694660f599923e2e6665b6d81c9c2d0ac9ffc8", size = 492919, upload-time = "2026-06-30T07:16:03.723Z" }, + { url = "https://files.pythonhosted.org/packages/8f/97/6908094ac804115e65aedfd90f1b5fee4eebebd3f6c4cfc5419939267565/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ae50181a047c871561212bb97f7932a2d45fb53e947bd9b57ebad85b529cbc53", size = 383725, upload-time = "2026-06-30T07:16:05.305Z" }, + { url = "https://files.pythonhosted.org/packages/d1/9c/0d1fdc2e7aba23e290d603bc494e97bd205bae262ce33c6b32a69768ed5e/rpds_py-2026.6.3-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:dc319e5a1de4b6913aac94bf6a2f9e847371e0a140a43dd4991db1a09bc2d504", size = 367255, upload-time = "2026-06-30T07:16:07.086Z" }, + { url = "https://files.pythonhosted.org/packages/c4/fe/f0209ca4a9ed074bc8acb44dfd0e81c3122e94c9689f5645b7973a866719/rpds_py-2026.6.3-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:e4316bf32babbed84e691e352faf967ce2f0f024174a8643c37c94a1080374fc", size = 379060, upload-time = "2026-06-30T07:16:08.525Z" }, + { url = "https://files.pythonhosted.org/packages/c6/8d/f1cc54c616b9d8897de8738aac148d20afca93f68187475fe194d09a71b9/rpds_py-2026.6.3-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:8c6e5a2f750cc71c3e3b11d71661f21d6f9bc6cebc6564b1466417a1ec03ec77", size = 395960, upload-time = "2026-06-30T07:16:09.989Z" }, + { url = "https://files.pythonhosted.org/packages/fb/04/aafff00f73aeca2945f734f1d483c64ab8f472d0864ab02377fd8e89c3b2/rpds_py-2026.6.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:4470ce197d4090875cf6affbf1f853338387428df97c4fb7b7106317b8214698", size = 545356, upload-time = "2026-06-30T07:16:11.816Z" }, + { url = "https://files.pythonhosted.org/packages/fd/cc/e229663b9e4ddac5a4acbe9085dd80a71af2a5d356b8b39d6bff233f24b0/rpds_py-2026.6.3-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:ea964164cc9afa72d4d9b23cc28dafae93693c0a53e0b42acbff15b22c3f9ddd", size = 612319, upload-time = "2026-06-30T07:16:13.586Z" }, + { url = "https://files.pythonhosted.org/packages/e3/7a/8a0e6d3e6cd066af108b71b43122c3fe158dd9eb86acac626593a2582eb1/rpds_py-2026.6.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:639c8929aa0afe81be836b04de888460d6bed38b9c54cfc18da8f6bfabf5af5d", size = 573508, upload-time = "2026-06-30T07:16:15.23Z" }, + { url = "https://files.pythonhosted.org/packages/87/03/2a69ab618a789cf6cf85c86bb844c62d090e700ab1a2aa676b3741b6c516/rpds_py-2026.6.3-cp314-cp314-win32.whl", hash = "sha256:882076c00c0a608b131187055ddc5ae29f2e7eaf870d6168980420d58528a5c8", size = 202504, upload-time = "2026-06-30T07:16:16.893Z" }, + { url = "https://files.pythonhosted.org/packages/85/62/a3892ba945f4e24c78f352e5de3c7620d8479f73f211406a97263d13c7d2/rpds_py-2026.6.3-cp314-cp314-win_amd64.whl", hash = "sha256:0be972be84cfcaf46c8c6edf690ca0f154ac17babf1f6a955a51579b34ad2dc5", size = 220380, upload-time = "2026-06-30T07:16:18.108Z" }, + { url = "https://files.pythonhosted.org/packages/3d/e7/c2bd44dc831931815ad11ebb5f430b5a0a4d3caa9de837107876c30c3432/rpds_py-2026.6.3-cp314-cp314-win_arm64.whl", hash = "sha256:2a9c6f195058cb45335e8cc3802745c603d716eb96bc9625950c1aac71c0c703", size = 215976, upload-time = "2026-06-30T07:16:19.654Z" }, + { url = "https://files.pythonhosted.org/packages/79/9c/fff7b74bce9a091ec9a012a03f9ff5f69364eaf9451060dfc4486da2ffdd/rpds_py-2026.6.3-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:f90938e92afda60266da758ee7d363447f7f0138c9559f9e1811629580582d90", size = 346840, upload-time = "2026-06-30T07:16:21.268Z" }, + { url = "https://files.pythonhosted.org/packages/e9/44/77bcb1168b33704908295533d27f10eb811e9e3e193e8993dc99572211d3/rpds_py-2026.6.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:ec829541c45bca16e61c7ae50c20501f213605beb75d1aba91a6ee37fbbb56a4", size = 340282, upload-time = "2026-06-30T07:16:22.875Z" }, + { url = "https://files.pythonhosted.org/packages/87/3c/7a9081c7c9e645b39efe19e4ffbeccd80add246327cd9b888aecffd72317/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:afd70d95892096cdb26f15a00c45907b17817577aa8d1c76b2dcc2788391f9e9", size = 370403, upload-time = "2026-06-30T07:16:24.415Z" }, + { url = "https://files.pythonhosted.org/packages/f7/69/af47021eb7dad6ff3396cb001c08f0f3c4d06c20253f75be6421a59fe6b7/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:29dfa0533a5d4c94d4dfa1b694fcb56c9c63aad8330ffdd816fd225d0a7a162f", size = 376055, upload-time = "2026-06-30T07:16:26.111Z" }, + { url = "https://files.pythonhosted.org/packages/81/fc/a3bcf517084396a6dd258c592567a3c011ba4557f2fde23dceaf26e74f2e/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:af05d726809bff6b141be124d4c7ce998f9c9c7f30edb1f46c07aa103d540b41", size = 494419, upload-time = "2026-06-30T07:16:27.596Z" }, + { url = "https://files.pythonhosted.org/packages/c9/eb/13d529d1788135425c7bf207f8463458ca5d92e43f3f701365b83e9dffc1/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9826217f048f620d9a712672818bf231442c1b35d96b227a07eabd11b4bb6945", size = 384848, upload-time = "2026-06-30T07:16:29.183Z" }, + { url = "https://files.pythonhosted.org/packages/8e/f4/b7ac49f30013aba8f7b9566b1dd07e81de95e708c1374b7bacc5b9bc5c9c/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:536bceea4fa4acf7e1c61da2b5786304367c816c8895be71b8f537c480b0ea1f", size = 371369, upload-time = "2026-06-30T07:16:30.912Z" }, + { url = "https://files.pythonhosted.org/packages/31/86/6260bafa622f788b07ddec0e52d810305c8b9b0b8c27f58a2ab04bf62b4f/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:bc0011654b91cc4fb2ae701bec0a0ba1e552c0714247fa7af6c59e0ccfa3a4e1", size = 379673, upload-time = "2026-06-30T07:16:32.486Z" }, + { url = "https://files.pythonhosted.org/packages/19/c3/03f1ee79a047b48daeca157c89a18509cde22b6b951d642b9b0af1be660a/rpds_py-2026.6.3-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:539d75de9e0d536c84ff18dfeb805398e58227001ce09231a26a08b9aed1ee0e", size = 397500, upload-time = "2026-06-30T07:16:34.471Z" }, + { url = "https://files.pythonhosted.org/packages/f0/95/8ed0cd8c377dca12aea498f119fe639fc474d1461545c39d2b5872eb1c0f/rpds_py-2026.6.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:166cf54d9f44fc6ceb53c7860258dde44a81406646de79f8ed3234fca3b6e538", size = 545978, upload-time = "2026-06-30T07:16:36.45Z" }, + { url = "https://files.pythonhosted.org/packages/d3/f2/0eb57f0eaa83f8fc152a7e03de968ab77e1f00732bebc892b190c6eebde7/rpds_py-2026.6.3-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:d34c20167764fbcf927194d532dd7e0c56772f0a5f943fa5ef9e9afbba8fb9db", size = 613350, upload-time = "2026-06-30T07:16:38.213Z" }, + { url = "https://files.pythonhosted.org/packages/5b/de/e0674bdbc3ef7634989b3f854c3f34bc1f587d36e5bfdc5c378d57034619/rpds_py-2026.6.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ea7bb13b7c9a29791f87a0387ba7d3ad3a6d783d827e4d3f27b40a0ff44495e2", size = 576486, upload-time = "2026-06-30T07:16:39.797Z" }, + { url = "https://files.pythonhosted.org/packages/f2/f6/21101359743cd136ada781e8210a85769578422ba460672eea0e29739200/rpds_py-2026.6.3-cp314-cp314t-win32.whl", hash = "sha256:6de4744d05bd1aa1be4ed7ea1189e3979196808008113bbbf899a460966b925e", size = 201068, upload-time = "2026-06-30T07:16:41.316Z" }, + { url = "https://files.pythonhosted.org/packages/a6/b2/9574d4d44f7760c2aa32d92a0a4f41698e33f5b204a0bf5c9758f52c79d5/rpds_py-2026.6.3-cp314-cp314t-win_amd64.whl", hash = "sha256:c7b9a2f8f4d8e90af72571d3d495deebdd7e3c75451f5b41719aee166e940fc2", size = 220600, upload-time = "2026-06-30T07:16:43.091Z" }, + { url = "https://files.pythonhosted.org/packages/08/ae/f23a2697e6ee6340a578b0f136be6483657bef0c6f9497b752bb5c0964bb/rpds_py-2026.6.3-cp315-cp315-macosx_10_12_x86_64.whl", hash = "sha256:e059c5dde6452b44424bd1834557556c226b57781dee1227af23518459722b13", size = 344726, upload-time = "2026-06-30T07:16:44.5Z" }, + { url = "https://files.pythonhosted.org/packages/c3/63/e7b3a1a5358dd32c930a1062d8e15b67fd6e8922e81df9e91706d66ee5c8/rpds_py-2026.6.3-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:2f7c26fbc5acd2522b95d4177fe4710ffd8e9b20529e703ffbf8db4d93903f05", size = 339587, upload-time = "2026-06-30T07:16:46.255Z" }, + { url = "https://files.pythonhosted.org/packages/ec/64/10a85681916ca55fffb91b0a211f84e34297c109243484dd6394660a8a7c/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a3086b538543802f84c843911242db20447de00d8752dd0efc936dbcf02218ba", size = 369585, upload-time = "2026-06-30T07:16:48.101Z" }, + { url = "https://files.pythonhosted.org/packages/76/c2/baf95c7c38823e12ba34407c5f5767a89e5cf2233895e56f608167ae9493/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8f2e5c5ee828d42cb11760761c0af6507927bec42d0ad5458f97c9203b054617", size = 375479, upload-time = "2026-06-30T07:16:49.93Z" }, + { url = "https://files.pythonhosted.org/packages/6a/94/0aad06c72d65101e11d33528d438cda99a39ce0da99466e156158f2541d3/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:ed0c1e5d10cdc7135537988c74a0188da68e2f3c30813ba3744ab1e42e0480f9", size = 492418, upload-time = "2026-06-30T07:16:51.641Z" }, + { url = "https://files.pythonhosted.org/packages/b5/17/de3f5a479a1f056535d7489819639d8cd591ea6281d700390b43b1abd745/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8c2642a7603ec0b16ed77da4555db3b4b472341904873788327c0b0d7b95f1bb", size = 384123, upload-time = "2026-06-30T07:16:53.622Z" }, + { url = "https://files.pythonhosted.org/packages/46/7d/bf09bd1b145bb2671c03e1e6d1ab8651858d90d8c7dfeadd85a37a934fd8/rpds_py-2026.6.3-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8e4320744c1ffdd95a603def63344bfab2d33edeab301c5007e7de9f9f5b3885", size = 367351, upload-time = "2026-06-30T07:16:55.241Z" }, + { url = "https://files.pythonhosted.org/packages/a3/ea/1bb734f314b8be319149ddee80b18bd41372bdcfbdf88d28131c0cd37719/rpds_py-2026.6.3-cp315-cp315-manylinux_2_31_riscv64.whl", hash = "sha256:a9f4645593036b81bbdb36b9c8e0ea0d1c3fee968c4d59db0344c14087ef143a", size = 378827, upload-time = "2026-06-30T07:16:56.841Z" }, + { url = "https://files.pythonhosted.org/packages/4b/93/d9611e5b25e26df9a3649813ed66193ace9347a7c7fc4ab7cf70e94851c0/rpds_py-2026.6.3-cp315-cp315-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e55d236be29255554da47abe5c577637db7c24a02b8b46f0ca9524c855801868", size = 395966, upload-time = "2026-06-30T07:16:58.557Z" }, + { url = "https://files.pythonhosted.org/packages/c3/cb/99d77e16e5534ae1d90629bbe419ba6ee170833a6a85e3aa1cc41726fbbc/rpds_py-2026.6.3-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:24e9c5386e16669b674a69c156c8eeefcb578f3b3397b713b08e6d60f3c7b187", size = 545680, upload-time = "2026-06-30T07:17:00.164Z" }, + { url = "https://files.pythonhosted.org/packages/59/15/11a29755f790cef7a2f755e8e14f4f0c33f39489e1893a632a2eee59672b/rpds_py-2026.6.3-cp315-cp315-musllinux_1_2_i686.whl", hash = "sha256:c60924535c75f1566b6eb75b5c31a48a43fef04fa2d0d201acbad8a9969c6107", size = 611853, upload-time = "2026-06-30T07:17:01.962Z" }, + { url = "https://files.pythonhosted.org/packages/68/86/0c27547e21644da938fb530f7e1a8148dd24d02db07e7a5f2567a17ce710/rpds_py-2026.6.3-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:38a2fea2787428f811719ceb9114cb78964a3138838320c29ac39526c79c16ba", size = 573715, upload-time = "2026-06-30T07:17:03.693Z" }, + { url = "https://files.pythonhosted.org/packages/29/71/4d8fcf700931815594bce892255bbd973b94efaf0fc1932b0590df18d886/rpds_py-2026.6.3-cp315-cp315-win32.whl", hash = "sha256:d483fe17f01ad64b7bf7cc38fcefff1ca9fb83f8c2b2542b68f97ffe0611b369", size = 202864, upload-time = "2026-06-30T07:17:05.746Z" }, + { url = "https://files.pythonhosted.org/packages/eb/62/b577562de0edbb55b2be85ce5fd09c33e386b9b13eee09833af4240fd5c4/rpds_py-2026.6.3-cp315-cp315-win_amd64.whl", hash = "sha256:67e3a721ffc5d8d2210d3671872298c4a84e4b8035cfe42ffd7cde35d772b146", size = 220430, upload-time = "2026-06-30T07:17:07.471Z" }, + { url = "https://files.pythonhosted.org/packages/c8/95/d6d0b2509825141eef60669a5739eec88dbc6a48053d6c92993a5704defe/rpds_py-2026.6.3-cp315-cp315-win_arm64.whl", hash = "sha256:6e84adbcf4bf841aed8116a8264b9f50b4cb3e7bd89b516122e616ac56ca269e", size = 215877, upload-time = "2026-06-30T07:17:09.008Z" }, + { url = "https://files.pythonhosted.org/packages/b7/bf/f3ea278f0afd615c1d0f19cb69043a41526e2bb600c2b536eb192218eb27/rpds_py-2026.6.3-cp315-cp315t-macosx_10_12_x86_64.whl", hash = "sha256:ae6dd8f10bd17aad820876d24caec9efdafd80a318d16c0a48edb5e136902c6b", size = 346933, upload-time = "2026-06-30T07:17:10.762Z" }, + { url = "https://files.pythonhosted.org/packages/9d/29/9907bdf1c5346763cf10b7f6852aad86652168c259def904cbe0082c5864/rpds_py-2026.6.3-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:bdbd97738551fca3917c1bd7188bec1920bb520104f28e7e1007f9ceb17b7690", size = 340274, upload-time = "2026-06-30T07:17:12.266Z" }, + { url = "https://files.pythonhosted.org/packages/6f/2c/8e03767b5778ef25cebf74a7a91a2c3806f8eced4c92cb7406bbe060756d/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8b95977e7211527ab0ba576e286d023389fbeeb32a6b7b771665d333c60e5342", size = 370763, upload-time = "2026-06-30T07:17:14.107Z" }, + { url = "https://files.pythonhosted.org/packages/2e/e1/df2a7e1ba2efd796af26194250b8d42c821b46592311595162af9ef0528d/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d15fde0e6fb0d88a60d221204873743e5d9f0b7d29165e62cd86d0413ad74ba6", size = 376467, upload-time = "2026-06-30T07:17:15.76Z" }, + { url = "https://files.pythonhosted.org/packages/6b/de/8a0814d1946af29cb068fb259aa8622f856df1d0bab58429448726b537f5/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:a136d453475ac0fcbda502ef1e6504bd28d6d904700915d278deeab0d00fe140", size = 496689, upload-time = "2026-06-30T07:17:17.308Z" }, + { url = "https://files.pythonhosted.org/packages/df/f3/f19e0c852ba13694f5a79f3b719331051573cb5693feacf8a88ffffc3a71/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f826877d462181e5eb1c26a0026b8d0cab05d99844ecb6d8bf3627a2ca0c0442", size = 385340, upload-time = "2026-06-30T07:17:18.928Z" }, + { url = "https://files.pythonhosted.org/packages/e2/ae/7ec3a9d2d4351f99e37bcb06b6b6f954512646bfdbf9742e1de727865daf/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:79486287de1730dbaff3dbd124d0ca4d2ef7f9d29bf2544f1f93c09b5bcbbd12", size = 372179, upload-time = "2026-06-30T07:17:20.539Z" }, + { url = "https://files.pythonhosted.org/packages/d3/ac/9cee911dff2aaa9a5a8354f6610bf2e6a616de9197c5fff4f54f82585f1e/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_31_riscv64.whl", hash = "sha256:808345f53cb952433ca2816f1604ff3515608a81784954f38d4452acfe8e61d5", size = 379993, upload-time = "2026-06-30T07:17:22.212Z" }, + { url = "https://files.pythonhosted.org/packages/83/6b/7c2a07ba88d1e9a936612f7a5d067467ed03d971d5a06f7d309dff044a7e/rpds_py-2026.6.3-cp315-cp315t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1967debc37f64f2c4dc90a7f563aec558b471966e12adcac4e1c4240496b6ebf", size = 398909, upload-time = "2026-06-30T07:17:23.66Z" }, + { url = "https://files.pythonhosted.org/packages/97/0b/776ffcb66783637b0031f6d58d6fb55913c8b5abf00aeecd46bf933fb477/rpds_py-2026.6.3-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:f0840b5b17057f7fd918b76183a4b5a0635f43e14eb2ce60dce1d4ee4707ea00", size = 546584, upload-time = "2026-06-30T07:17:25.264Z" }, + { url = "https://files.pythonhosted.org/packages/55/33/ba3bc04d7092bd553c9b2b195624992d2cc4f3de1f380b7b93cbee67bd79/rpds_py-2026.6.3-cp315-cp315t-musllinux_1_2_i686.whl", hash = "sha256:faa679d19a6696fd54259ad321251ad77a13e70e03dd834daa762a44fb6196ef", size = 614357, upload-time = "2026-06-30T07:17:26.888Z" }, + { url = "https://files.pythonhosted.org/packages/8b/71/14edf065f04630b1a8472f7653cad03f6c478bcf95ea0e6aed55451e33ea/rpds_py-2026.6.3-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:23a439f31ccbeff1574e24889128821d1f7917470e830cf6544dced1c662262a", size = 576533, upload-time = "2026-06-30T07:17:28.546Z" }, + { url = "https://files.pythonhosted.org/packages/ba/76/65002b08596c389105720a8c0d22298b8dc25a4baf89b2ce431343c8b1de/rpds_py-2026.6.3-cp315-cp315t-win32.whl", hash = "sha256:913ca42ccad3f8cc6e292b587ae8ae49c8c823e5dce51a736252fc7c7cdfa577", size = 201204, upload-time = "2026-06-30T07:17:30.193Z" }, + { url = "https://files.pythonhosted.org/packages/8c/97/d855d6b3c322d1f27e26f5241c42016b56cf01377ea8ed348285f54652f0/rpds_py-2026.6.3-cp315-cp315t-win_amd64.whl", hash = "sha256:ae3d4fe8c0b9213624fdce7279d70e3b148b682ca20719ebd193a23ebfa47324", size = 220719, upload-time = "2026-06-30T07:17:31.788Z" }, +] + [[package]] name = "ruff" version = "0.14.11" @@ -1039,6 +1444,32 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b7/ce/149a00dd41f10bc29e5921b496af8b574d8413afcd5e30dfa0ed46c2cc5e/six-1.17.0-py2.py3-none-any.whl", hash = "sha256:4721f391ed90541fddacab5acf947aa0d3dc7d27b2e1e8eda2be8970586c3274", size = 11050, upload-time = "2024-12-04T17:35:26.475Z" }, ] +[[package]] +name = "sse-starlette" +version = "3.4.5" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anyio" }, + { name = "starlette" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/d2/1b/bc9e3e7a72dcdad7dc7888758f5d00f56f8909ed5cfdff822bd72bb4c520/sse_starlette-3.4.5.tar.gz", hash = "sha256:83072538bc211a2f68b7b0422226c4af3e9b62e106e07034664b832ca019842a", size = 35249, upload-time = "2026-06-20T17:36:58.322Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/78/75/c88d3f5dafd59c791da1ce27650d30bf5b70cbf1cbf01cd00e5f9e360915/sse_starlette-3.4.5-py3-none-any.whl", hash = "sha256:e71bad53323f65573c3864a6c3bd0c1eb6e5f092b2e48082b0c35927d19ca296", size = 16518, upload-time = "2026-06-20T17:36:56.729Z" }, +] + +[[package]] +name = "starlette" +version = "1.3.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "anyio" }, + { name = "typing-extensions", marker = "python_full_version < '3.13'" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/eb/e3/7c1dc7381d9f8ab7d854328ebfa884e62cb3f3d8549ddfd37c7814f42afa/starlette-1.3.1.tar.gz", hash = "sha256:05d0213193f2fbaae60e2ecb593b4add4262ad4e46536b54abe36f11a71724e0", size = 2703240, upload-time = "2026-06-12T09:23:11.602Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ec/bb/2799cc2ede3ed41131f8975621e7213dfc7ef4acbbaadfa440f32500c370/starlette-1.3.1-py3-none-any.whl", hash = "sha256:c7372aae11c3c3f26a42df7bd626cec2f47d03483d261d369516a615a53714c6", size = 73632, upload-time = "2026-06-12T09:23:10.017Z" }, +] + [[package]] name = "ty" version = "0.0.11" @@ -1109,6 +1540,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" }, ] +[[package]] +name = "uvicorn" +version = "0.50.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "click" }, + { name = "h11" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/9f/f6/cc9aadc0e481344a42095d222bfa764122fb8cfba708d1922917bd8bfb01/uvicorn-0.50.2.tar.gz", hash = "sha256:b92bf03509b82bcb9d49e7335b4fd364518ad021c2dc18b4e6a2fec8c955a0bb", size = 93716, upload-time = "2026-07-06T10:38:31.984Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/aa/f0/7c228ee10c7ab8fd3a21d06579a6f7c6075c6ce72594a20fb5d2f206ff24/uvicorn-0.50.2-py3-none-any.whl", hash = "sha256:4ae72a385630bcc17a0adb8290f26c993865e0b43a2114c2aab96420172c056a", size = 72846, upload-time = "2026-07-06T10:38:30.543Z" }, +] + [[package]] name = "watchdog" version = "6.0.0" From 9172b041162358fe15c0d191f438790486dc8d17 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 22:39:19 -0500 Subject: [PATCH 03/24] docs: 0.3.0 architecture plan + Feathers refactoring discipline Design (Codex gpt-5.6 oracle) for the unified operations-core restructure, plus the standing Working-Effectively-With-Legacy-Code contract every stage must follow. Co-Authored-By: Claude Opus 4.8 (1M context) --- ARCHITECTURE_PLAN.md | 1407 +++++++++++++++++++++++++++++++++++++ REFACTORING_DISCIPLINE.md | 21 + 2 files changed, 1428 insertions(+) create mode 100644 ARCHITECTURE_PLAN.md create mode 100644 REFACTORING_DISCIPLINE.md diff --git a/ARCHITECTURE_PLAN.md b/ARCHITECTURE_PLAN.md new file mode 100644 index 0000000..f398ad1 --- /dev/null +++ b/ARCHITECTURE_PLAN.md @@ -0,0 +1,1407 @@ +# Target Architecture for `readwise-plus` + +## Executive Decision + +**Introduce one canonical, async-first operations layer and make the SDK facade, CLI, and MCP server thin adapters over it.** + +The existing v2/v3 clients should become low-level resource clients, not the primary place where user-facing behavior is composed. Managers, workflows, contrib helpers, CLI commands, and MCP tools should progressively delegate to the operations layer. + +I recommend **Option A: an aggressive internal restructure released as `0.3.0`**, while retaining inexpensive compatibility shims throughout the `0.x` series. Remove deprecated APIs only at `1.0.0`. + +The primary target API becomes: + +```python +from readwise_sdk import AsyncReadwise + +async with AsyncReadwise() as readwise: + documents = await readwise.documents.search( + query="python", + location="later", + limit=20, + ) +``` + +And synchronously: + +```python +from readwise_sdk import Readwise + +with Readwise() as readwise: + documents = readwise.documents.search( + query="python", + location="later", + limit=20, + ) +``` + +The CLI and MCP server call those same operations. + +--- + +# 1. Current-State Assessment + +## Strengths + +### Clear external API boundaries + +The repository correctly recognizes that Readwise v2 and Reader v3 are different APIs: + +- v2 highlights, books, tags, export, and review live in `src/readwise_sdk/v2/client.py:24`. +- Reader documents and Reader tags live in `src/readwise_sdk/v3/client.py:23`. +- Their models are separated in `src/readwise_sdk/v2/models.py:14` and `src/readwise_sdk/v3/models.py:15`. + +That distinction should remain at the resource layer. + +### Useful typed models + +The Pydantic models provide: + +- Typed enums. +- Tolerant parsing of unknown categories and colors. +- API payload conversion through `to_api_dict()`. +- Normalization of Reader tags and HTML content. + +Examples include: + +- `HighlightCreate.to_api_dict()` in `src/readwise_sdk/v2/models.py:146`. +- `Document.merge_html_content()` in `src/readwise_sdk/v3/models.py:79`. +- `DocumentCreate.to_api_dict()` in `src/readwise_sdk/v3/models.py:183`. + +These are good foundations. They need relocation and clearer naming more than replacement. + +### Shared basic transport behavior + +Authentication, retrying, response handling, and pagination are at least partially centralized: + +- Retry behavior: `src/readwise_sdk/client.py:103` and `src/readwise_sdk/client.py:424`. +- HTTP status translation: `src/readwise_sdk/_utils.py:24`. +- Cursor parsing: `src/readwise_sdk/_utils.py:72`. +- Pagination: `src/readwise_sdk/client.py:245` and `src/readwise_sdk/client.py:487`. + +### Strong behavioral coverage + +Tests cover each major layer separately: + +- Low-level clients. +- Sync and async managers. +- Workflows. +- Contrib helpers. +- CLI commands. +- All nine MCP tools. + +That makes a staged restructuring practical, provided characterization tests are added before moving public contracts. + +### Packaging boundaries are already sound + +The package keeps optional surfaces separate: + +- Core: `httpx`, `pydantic`. +- CLI: Typer and Rich. +- MCP: FastMCP. +- Console scripts remain distinct in `pyproject.toml`. + +The target architecture should preserve those dependency boundaries. + +--- + +## Structural Problems + +### 1. `client.py` combines too many responsibilities + +`src/readwise_sdk/client.py` currently owns: + +- Authentication configuration. +- HTTP client construction. +- Retry policy. +- response handling. +- pagination. +- API client composition through `.v2` and `.v3`. +- public context-manager lifecycle. +- both sync and async implementations. + +The sync and async implementations repeat almost the same request and pagination algorithms at `src/readwise_sdk/client.py:103` and `src/readwise_sdk/client.py:424`. + +This is simultaneously a transport, client facade, retry engine, pagination engine, and dependency container. + +### 2. Sync and async code are maintained as parallel copies + +The duplication is substantial: + +- `src/readwise_sdk/v2/client.py`: 395 lines. +- `src/readwise_sdk/v2/async_client.py`: 418 lines. +- `src/readwise_sdk/v3/client.py`: 311 lines. +- `src/readwise_sdk/v3/async_client.py`: 336 lines. +- `src/readwise_sdk/managers/async_managers.py`: 800 lines, largely mirroring the four synchronous manager modules. + +For example, `HighlightManager.search_highlights()` at `src/readwise_sdk/managers/highlights.py:81` is repeated asynchronously at `src/readwise_sdk/managers/async_managers.py:97`. + +Any semantic fix must currently be made at least twice, often more. + +### 3. Managers are mostly alternate client APIs, not a distinct layer + +Many manager methods simply materialize low-level iterators or rename an existing operation: + +```python +return list(self._client.v2.list_highlights()) +``` + +That pattern appears in `src/readwise_sdk/managers/highlights.py:27`, with similar wrappers for books and documents. + +Other manager methods introduce business behavior, such as: + +- Local text search. +- Bulk operations. +- Statistics. +- Date-range calculation. +- partial-failure handling. + +Those two categories are mixed together. The result is an ambiguous layer: users cannot tell whether a manager is required, optional, or merely another spelling of `.v2`. + +### 4. Workflows, managers, and contrib overlap heavily + +There are multiple implementations of synchronization: + +- `SyncManager` in `src/readwise_sdk/managers/sync.py:74`. +- `BackgroundPoller` in `src/readwise_sdk/workflows/poller.py:75`. +- `BatchSync` in `src/readwise_sdk/contrib/batch_sync.py:113`. +- Async counterparts in `async_managers.py` and `batch_sync.py`. + +They each maintain related state, JSON persistence, timestamps, and callbacks, but with separate data models and behavior. + +Other overlaps include: + +- `HighlightManager.create_highlight()` versus `HighlightPusher`. +- `DocumentManager` versus `DocumentImporter`. +- Manager search methods versus MCP-local search. +- `TagWorkflow` versus manager bulk tagging and low-level tag methods. + +The current directory names describe historical intent rather than architectural roles. + +### 5. CLI and MCP implement operations independently + +The CLI directly queries low-level clients: + +- Highlight filtering and limiting: `src/readwise_sdk/cli/main.py:68`. +- Book listing: `src/readwise_sdk/cli/main.py:180`. +- Reader inbox listing: `src/readwise_sdk/cli/main.py:247`. +- Reader save/archive: `src/readwise_sdk/cli/main.py:285` and `src/readwise_sdk/cli/main.py:302`. + +The MCP server independently implements: + +- Enum validation. +- limit clamping. +- datetime parsing. +- local substring search. +- result projections. +- error translation. +- operation composition. + +For example, document search is defined locally in `src/readwise_sdk/mcp/server.py:231`; highlight search repeats the same pattern at `src/readwise_sdk/mcp/server.py:402`; book search does so again at `src/readwise_sdk/mcp/server.py:549`. + +These are operations, not MCP protocol concerns. + +### 6. Presentation logic is mixed into business objects + +`DigestBuilder` both queries data and renders Markdown, JSON, CSV, and text in `src/readwise_sdk/workflows/digest.py:27`. + +Similarly: + +- The CLI constructs bespoke JSON objects and Rich tables. +- MCP constructs different summary dictionaries in `src/readwise_sdk/mcp/server.py:79`. +- Neither output shape is a declared, reusable contract. + +Data acquisition, business composition, and rendering should be independently testable. + +### 7. Error behavior is inconsistent and sometimes hidden + +Observed patterns include: + +- `get_document()` returns `None` for missing documents at `src/readwise_sdk/v3/client.py:78`. +- Update and delete raise `NotFoundError`. +- Bulk manager operations catch `Exception` and return `False`. +- Tag workflows silently suppress tag failures at `src/readwise_sdk/workflows/tags.py:103`. +- Sync callbacks silently suppress arbitrary callback exceptions at `src/readwise_sdk/managers/sync.py:121`. +- MCP converts SDK errors into JSON strings. +- CLI frequently allows exceptions to escape through Typer. + +There is no declared rule for whether an operation raises, returns a partial result, or suppresses errors. + +### 8. Pagination is nominally generic but still ad hoc + +`paginate()` accepts arbitrary result and cursor keys, and `parse_pagination_cursor()` handles URLs and cursor values. However, endpoint-specific assumptions leak into callers: + +- V2 standard pagination uses `next`. +- V2 export uses integer cursors. +- V3 uses `nextPageCursor`. +- Reader filters accept a tag list, but `list_documents()` only sends the first tag at `src/readwise_sdk/v3/client.py:65`. + +Pagination semantics should be represented by endpoint-specific page decoders, not string arguments passed around the package. + +### 9. High-level code leaks API-version terminology + +High-level operations import directly from `v2.models` and `v3.models`. The MCP server does this at `src/readwise_sdk/mcp/server.py:24`. + +Versions are appropriate at the transport/resource boundary. User concepts should normally be called `highlights`, `books`, `documents`, and `reader_tags`. + +### 10. The adapter layers are excluded from type checking + +`just type` excludes the CLI and MCP packages in `Justfile:18`. + +These are now first-class published surfaces. Their exclusion makes drift between the core, CLI, and MCP more likely. + +### 11. One documented MCP parameter is currently ignored + +`save_to_reader()` accepts `category` at `src/readwise_sdk/mcp/server.py:179`, but the constructed `DocumentCreate` at `src/readwise_sdk/mcp/server.py:211` does not include it. + +Because MCP behavior must remain identical during restructuring, this discrepancy should first receive a characterization test. Fixing it should be a separate, explicit behavior-change PR. + +--- + +# 2. Target Architecture + +## Layering + +```text +Public models and errors + ↓ +Transport and pagination + ↓ +Low-level resource clients + ↓ +Operations / service core + ↓ +SDK facade | CLI adapter | MCP adapter +``` + +Dependencies must point downward only. + +The CLI and MCP packages must not call resource clients directly. Managers, workflows, and contrib compatibility classes should delegate to operations rather than reach into `.v2` or `.v3`. + +--- + +## Proposed Layout + +```text +src/readwise_sdk/ +├── __init__.py +├── config.py +├── errors.py +├── models/ +│ ├── __init__.py +│ ├── readwise.py +│ ├── reader.py +│ ├── queries.py +│ └── results.py +├── transport/ +│ ├── __init__.py +│ ├── config.py +│ ├── errors.py +│ ├── retry.py +│ ├── pagination.py +│ ├── sync.py +│ └── async_.py +├── resources/ +│ ├── __init__.py +│ ├── v2/ +│ │ ├── highlights.py +│ │ ├── books.py +│ │ ├── tags.py +│ │ ├── export.py +│ │ └── review.py +│ └── v3/ +│ ├── documents.py +│ └── tags.py +├── operations/ +│ ├── __init__.py +│ ├── service.py +│ ├── documents.py +│ ├── highlights.py +│ ├── books.py +│ ├── tags.py +│ ├── digests.py +│ ├── imports.py +│ └── sync.py +├── state/ +│ ├── __init__.py +│ ├── store.py +│ └── json_file.py +├── sdk/ +│ ├── __init__.py +│ ├── async_.py +│ └── sync.py +├── presenters/ +│ ├── __init__.py +│ ├── json.py +│ ├── tables.py +│ └── digests.py +├── cli/ +│ ├── main.py +│ ├── context.py +│ ├── output.py +│ └── commands/ +│ ├── documents.py +│ ├── highlights.py +│ ├── books.py +│ ├── tags.py +│ ├── digests.py +│ └── sync.py +├── mcp/ +│ ├── server.py +│ ├── context.py +│ ├── output.py +│ └── tools/ +│ ├── documents.py +│ ├── highlights.py +│ └── books.py +└── compat/ + ├── clients.py + ├── managers.py + ├── workflows.py + └── contrib.py +``` + +Compatibility modules at the current paths should re-export or wrap these implementations. + +--- + +## Core Abstractions + +### `ClientConfig` + +One immutable configuration object should own: + +- API key. +- timeout. +- retry count. +- retry backoff. +- user agent. +- optional base-URL overrides for testing. + +```python +@dataclass(frozen=True, slots=True) +class ClientConfig: + api_key: str + timeout: float = 30.0 + max_retries: int = 3 + retry_backoff: float = 0.5 +``` + +CLI and MCP credential resolution may differ, but both must ultimately produce this same configuration. + +### Transport + +Provide native sync and async transports with identical interfaces: + +```python +class AsyncTransport(Protocol): + async def request(self, request: Request) -> Response: ... + +class SyncTransport(Protocol): + def request(self, request: Request) -> Response: ... +``` + +Shared components should own: + +- Header construction. +- retry classification. +- backoff calculation. +- HTTP-to-SDK exception mapping. +- page decoding rules. + +Only the actual `httpx.Client.request()` versus `httpx.AsyncClient.request()` call and sleeping mechanism should differ. + +### Resource clients + +Resources represent the exact remote APIs. They should: + +- Build endpoint-specific requests. +- Decode API models. +- Expose raw pagination. +- Perform no local text search. +- Perform no Rich/JSON formatting. +- Perform no multi-resource workflow. +- Avoid broad exception suppression. + +Examples: + +```python +await resources.documents.get(document_id, with_content=True) +resources.highlights.iter(updated_after=...) +await resources.documents.update(document_id, update) +``` + +The v2/v3 distinction remains inside `resources/`. + +### Operation inputs + +Use explicit Pydantic input models or frozen dataclasses: + +```python +class DocumentSearch: + location: DocumentLocation | None + category: DocumentCategory | None + updated_after: datetime | None + tags: tuple[str, ...] + query: str | None + limit: int +``` + +These types provide one place for: + +- limit bounds. +- whitespace normalization. +- semantic validation. +- mutually exclusive options. +- default behavior. + +Do not use Typer or FastMCP parameter objects in this layer. + +### Operation results + +Operations should return typed domain models or declared result types, never Rich objects or JSON strings. + +Examples: + +```python +class DocumentSearchResult(BaseModel): + items: list[DocumentSummary] + truncated: bool + +class BulkResult[T](BaseModel): + succeeded: list[T] + failures: list[OperationFailure] + +class SyncResult(BaseModel): + highlights: list[Highlight] + books: list[Book] + documents: list[Document] + checkpoint: SyncCheckpoint +``` + +`DocumentSummary`, `HighlightSummary`, and `BookSummary` are legitimate shared read models because CLI and MCP need the same semantic projection. Protocol-specific JSON shaping remains in the adapters. + +### `ReadwiseService` + +The service is the single public operation container: + +```python +class ReadwiseService: + documents: DocumentOperations + highlights: HighlightOperations + books: BookOperations + tags: TagOperations + digests: DigestOperations + sync: SyncOperations +``` + +Representative operation definitions: + +```python +result = await service.documents.search(input) +document = await service.documents.get(document_id, with_content=True) +created = await service.documents.save(input) +updated = await service.documents.update(document_id, input) + +result = await service.highlights.search(input) +export = await service.highlights.export(input) +created = await service.highlights.create(input) + +result = await service.books.search(input) +``` + +Each is defined once and used from three surfaces. + +--- + +## What Belongs in the Operations Layer + +Operations should own: + +- Search filtering. +- result limits. +- bulk operation semantics. +- date-window calculation. +- multi-request composition. +- partial-failure policy. +- tag merging and normalization. +- digest data selection and grouping. +- synchronization and checkpoints. +- import and truncation policies. + +Adapters should own: + +- Reading command-line or MCP arguments. +- credential discovery. +- human rendering. +- JSON serialization. +- exit codes or MCP error envelopes. +- protocol lifecycle. + +Resource clients should own only API calls. + +--- + +## SDK as an Adapter + +The SDK public API is itself an adapter over the service core. + +### New preferred facade + +```python +from readwise_sdk import AsyncReadwise, Readwise +``` + +Expose concept-oriented attributes: + +```python +readwise.documents +readwise.highlights +readwise.books +readwise.tags +readwise.digests +readwise.sync +``` + +For advanced users, provide an explicitly low-level escape hatch: + +```python +readwise.raw.v2 +readwise.raw.v3 +``` + +Do not retain `.v2` and `.v3` as the primary recommended API. They force users to know endpoint versions and encourage bypassing the operation core. + +--- + +# 3. CLI Design + +## Keep Typer + +Retain Typer because: + +- It already supports the current nested command structure. +- It is a published optional dependency. +- Existing tests use `CliRunner`. +- Replacing it would create migration cost without solving the architectural problem. + +The problem is not Typer. The problem is that `cli/main.py` currently contains command declaration, client creation, API calls, formatting, and error behavior in one 752-line module. + +Split command modules and make each command invoke exactly one service operation. + +--- + +## Proposed Command Tree + +```text +readwise +├── auth +│ └── check +├── documents +│ ├── list +│ ├── get +│ ├── save +│ ├── update +│ ├── delete +│ ├── move +│ └── tag +├── highlights +│ ├── list +│ ├── get +│ ├── create +│ ├── update +│ ├── delete +│ ├── export +│ ├── tag +│ └── untag +├── books +│ ├── list +│ └── get +├── tags +│ ├── list +│ ├── search +│ ├── report +│ ├── auto +│ ├── rename +│ ├── merge +│ └── delete +├── digest +│ ├── daily +│ ├── weekly +│ ├── book +│ └── custom +├── sync +│ ├── full +│ ├── incremental +│ ├── status +│ └── reset +└── version +``` + +### Compatibility aliases + +Retain `readwise reader ...` as a deprecated alias for `readwise documents ...` throughout `0.x`. + +Existing commands such as `reader inbox`, `reader save`, and `reader archive` should continue to work but emit a warning to stderr in human mode. + +--- + +## Global Output Contract + +Add a consistent global option: + +```text +--output table|json|jsonl +``` + +Recommended defaults: + +- Interactive terminal: `table`. +- Redirected stdout: still `table` unless explicitly requested; avoid surprising scripts. +- Automation and agents: `--output json` or `--output jsonl`. + +Additional options: + +```text +--pretty / --no-pretty +--no-color +--quiet +--api-key +``` + +### Output rules + +- Machine-readable data goes to stdout. +- Warnings, progress, and errors go to stderr. +- JSON output never contains Rich markup or progress text. +- JSON contains full values; truncation is only a human-table concern. +- JSON uses stable named fields from result models. +- Streaming list commands support JSONL. +- Exit codes are consistent: + - `0`: success. + - `1`: SDK/API failure. + - `2`: invalid command input. + - `3`: not found. + - `4`: partial bulk failure. + +### Command implementation pattern + +```python +@documents_app.command("list") +def list_documents(options: DocumentOptions) -> None: + result = run_operation( + lambda service: service.documents.search(options.to_input()) + ) + output.render(result) +``` + +No command should directly call `.v2`, `.v3`, or an HTTP client. + +--- + +# 4. MCP Mapping + +The nine existing MCP tool names and return behavior remain unchanged. + +| Existing MCP tool | Core operation | +|---|---| +| `save_to_reader` | `service.documents.save()` | +| `search_documents` | `service.documents.search()` | +| `get_document` | `service.documents.get()` | +| `update_document` | `service.documents.update()` | +| `delete_document` | `service.documents.delete()` | +| `get_highlights` | `service.highlights.search()` | +| `export_highlights` | `service.highlights.export()` | +| `create_highlight` | `service.highlights.create()` | +| `get_books` | `service.books.search()` | + +Each MCP function should contain only: + +1. Protocol argument adaptation. +2. One service call. +3. Existing JSON-envelope rendering. +4. Existing MCP-compatible error translation. + +Example target: + +```python +@mcp.tool() +async def search_documents(...) -> str: + try: + result = await get_service().documents.search( + DocumentSearchInput(...) + ) + return render_mcp_documents(result) + except ReadwiseError as error: + return render_mcp_error(error) +``` + +## Behavior that must remain identical + +Characterization tests should lock: + +- Tool names and argument names. +- default and maximum limits. +- compact JSON strings. +- omission of `None` fields. +- not-found message text. +- invalid-enum error envelopes. +- current lenient datetime parsing. +- current summary fields. +- per-call client lifecycle, unless tests establish that reuse is invisible. +- current `save_to_reader(category=...)` behavior until separately approved. + +The MCP-specific projections in `_doc_summary`, `_highlight_summary`, and `_book_summary` may remain MCP presenters. They are presentation policy, not duplicated operation logic. + +--- + +# 5. Sync Versus Async + +## Recommendation: Async canonical core, explicit sync bridge + +MCP is async, and network operations are naturally async. Therefore the canonical operations implementation should be async. + +The new `Readwise` synchronous facade should execute the async service through a dedicated blocking portal running on its own event-loop thread. `anyio` is the most suitable implementation dependency. + +```python +with Readwise() as readwise: + result = readwise.documents.search(...) +``` + +Internally: + +```python +portal.call(async_service.documents.search, input) +``` + +## Why not `asyncio.run()` per method? + +It fails when called from a thread already running an event loop, and it repeatedly creates clients and event loops. That is unsuitable for notebooks and mixed async applications. + +## Why not keep handwritten parallel operation layers? + +That is the current failure mode. It guarantees semantic drift across: + +- managers. +- async managers. +- workflows. +- contrib. +- CLI. +- MCP. + +## Caveat: streaming + +Bridging an async iterator to a synchronous iterator requires queueing across the portal and complicates lifecycle management. + +Therefore: + +- Core user-facing operations should normally return bounded result objects. +- Advanced raw resources may retain native sync and async iterators. +- Sync streaming can be added deliberately later if required. +- Existing generator APIs remain available through compatibility clients. + +## Transitional strategy + +During `0.3`: + +- New `AsyncReadwise` uses the canonical operations directly. +- New `Readwise` uses the blocking portal. +- Existing `ReadwiseClient` and `AsyncReadwiseClient` remain as compatibility facades. +- Existing low-level sync clients continue working until `1.0`. + +This avoids forcing the transport/resource migration and public sync migration into one risky step. + +--- + +# 6. Migration Options + +## Option A — Aggressive Restructure + +### Description + +Introduce the new concept-oriented API and move all new development to it. Existing modules become compatibility layers. + +### Breaking-change inventory + +Without shims, the following are public breaks. + +#### Root imports + +Current imports include: + +```python +from readwise_sdk import ReadwiseClient, AsyncReadwiseClient +from readwise_sdk import HighlightManager, DigestBuilder +``` + +Target imports become: + +```python +from readwise_sdk import Readwise, AsyncReadwise +``` + +#### Client attributes + +Current: + +```python +client.v2.list_highlights() +client.v3.list_documents() +``` + +Target: + +```python +client.highlights.search() +client.documents.search() +client.raw.v2... +client.raw.v3... +``` + +#### Versioned client imports + +These paths would move: + +```python +readwise_sdk.v2.client.ReadwiseV2Client +readwise_sdk.v2.async_client.AsyncReadwiseV2Client +readwise_sdk.v3.client.ReadwiseV3Client +readwise_sdk.v3.async_client.AsyncReadwiseV3Client +``` + +#### Models + +Current MCP and external users may import: + +```python +from readwise_sdk.v2.models import HighlightCreate +from readwise_sdk.v3.models import DocumentCreate, DocumentUpdate +``` + +Target canonical paths: + +```python +from readwise_sdk.models.readwise import HighlightCreate +from readwise_sdk.models.reader import DocumentCreate, DocumentUpdate +``` + +The existing paths should remain re-export modules until `1.0`. + +#### Managers and workflows + +These become deprecated operation wrappers: + +```python +readwise_sdk.managers.* +readwise_sdk.workflows.* +readwise_sdk.contrib.* +``` + +#### Return and failure semantics + +Some current APIs return: + +- iterators. +- lists. +- `None`. +- `dict[id, bool]`. +- formatted strings. + +The target operations return declared typed result objects. Compatibility wrappers must preserve old return values. + +#### MCP internal imports + +The MCP server currently imports `AsyncReadwiseClient` from the package root and request models from `v2.models`/`v3.models` at `src/readwise_sdk/mcp/server.py:19`. + +It should migrate to `AsyncReadwise` and canonical model/input paths, while compatibility re-exports preserve external integrations. + +### Deprecation plan + +- `0.3.0`: add the new API and aggressively restructure internals. +- `0.3.x`: emit `DeprecationWarning` for legacy constructors and manager/workflow creation. +- Keep old module paths as re-exports. +- Keep `.v2` and `.v3` functional but document them as low-level compatibility APIs. +- `0.4+`: no new features on deprecated surfaces. +- `1.0.0`: remove deprecated managers/workflows and old client names after a documented migration window. + +Warnings should be emitted on object construction or deprecated method use, not merely importing a module. Import-time warnings are noisy and difficult for downstream users to control. + +### Version + +Use **`0.3.0`**, not `1.0.0`. + +The project is currently `0.2.1` and classified as alpha. A breaking minor release is semantically legitimate before 1.0. The new architecture should prove itself across one or more `0.x` releases before declaring a stable 1.0 contract. + +--- + +## Option B — Conservative Refactor + +### Description + +Keep `ReadwiseClient`, `.v2`, `.v3`, managers, workflows, and contrib as the documented API. Internally route CLI and MCP through a newly added service layer. + +### Advantages + +- Minimal downstream migration. +- Lower short-term release risk. +- Documentation changes can be incremental. +- Existing users see little disruption. + +### Disadvantages + +- The package retains two competing public abstractions. +- `.v2/.v3` remains the easiest and most visible route. +- Manager/workflow naming remains ambiguous. +- New service capabilities must coexist indefinitely with obsolete organization. +- It becomes harder to remove sync/async duplication later. +- The “single source of truth” exists internally but not conceptually for users. + +--- + +## Recommendation + +**Choose Option A.** + +This package is still at `0.2.1`, the codebase is modest in size, and MCP has exposed the cost of the current architecture. This is the correct time to establish a coherent public model. + +Be aggressive about internal organization and the new recommended API, but pragmatic about compatibility: + +- Preserve old imports through re-exports. +- Preserve old return values through wrappers. +- Do not preserve old internals. +- Remove the compatibility surface only at 1.0. + +--- + +# 7. Staged Execution Plan + +Each stage is intended to be one PR or a small cluster of tightly related PRs. Every stage ends with `just fc` passing. + +## PR 1 — Add characterization contracts + +Before moving code, lock observable behavior. + +Add tests for: + +- Root exports and import paths. +- `ReadwiseClient` constructor, context manager, `.v2`, `.v3`, and `create_optional()`. +- Sync and async pagination cursor behavior. +- Existing manager return types. +- sync-state JSON file formats. +- CLI stdout, stderr, exit codes, and JSON structures. +- All nine MCP tools, including exact error envelopes and field omission. +- MCP limit clamping and lenient invalid-datetime behavior. +- `save_to_reader(category=...)` request payload as currently implemented. +- callback exception suppression where currently documented by behavior. +- bulk-operation partial-failure maps. + +No production behavior changes. + +## PR 2 — Introduce canonical config and errors + +Add: + +- `config.py`. +- `errors.py`. +- immutable client configuration. +- credential resolution utilities shared where appropriate. +- error classification helpers. + +Keep `exceptions.py` as a re-export. + +Existing clients delegate to the new configuration and exception definitions. + +## PR 3 — Extract retry and pagination infrastructure + +Move shared logic from `client.py` and `_utils.py` into: + +- `transport/retry.py`. +- `transport/pagination.py`. +- `transport/errors.py`. + +Introduce endpoint-aware page decoders: + +```python +StandardV2Page +ExportV2Page +ReaderV3Page +``` + +Keep `ReadwiseClient.paginate()` and `AsyncReadwiseClient.paginate()` as compatibility wrappers. + +Characterization tests must confirm identical requests and retry timing decisions. + +## PR 4 — Introduce async transport and resources + +Create canonical async resources for: + +- v2 highlights. +- v2 books. +- v2 tags. +- v2 export/review. +- v3 documents. +- v3 tags. + +Make `AsyncReadwiseV2Client` and `AsyncReadwiseV3Client` delegate to them. + +Do not change public methods or return types. + +## PR 5 — Add operation inputs and result models + +Introduce: + +- search input models. +- create/update inputs where existing API models are insufficient. +- summary read models. +- `BulkResult`. +- `OperationFailure`. +- unified `SyncCheckpoint` and `SyncResult`. + +This PR should be mostly additive and model-level. + +## PR 6 — Implement document operations + +Create canonical operations for: + +- search. +- get. +- save. +- update. +- delete. +- move. +- set/add/remove tags. +- inbox/archive/later views. +- statistics. + +Port semantics from: + +- `DocumentManager`. +- `ReadingInbox`. +- `DocumentImporter`. +- MCP document tools. +- CLI Reader commands. + +Test operations directly with fake resources where possible and with `respx` integration tests where transport behavior matters. + +## PR 7 — Implement highlight and book operations + +Create canonical operations for: + +- highlight search/list/get/create/update/delete. +- bulk tag and untag. +- export. +- book search/list/get. +- book-with-highlights. +- reading statistics. +- highlight truncation and partial-failure policies. + +Port semantics from: + +- highlight and book managers. +- `HighlightPusher`. +- CLI. +- MCP. + +Do not yet delete legacy implementations. + +## PR 8 — Migrate the nine MCP tools + +Change each MCP tool to call one operation. + +Move presentation helpers to `mcp/output.py`. + +Preserve: + +- names. +- argument schemas. +- return strings. +- error JSON. +- summary fields. +- limits. +- documented per-tool behavior. + +Run the MCP tool tests after migrating each tool group rather than waiting for all nine. + +## PR 9 — Add the new async SDK facade + +Add `AsyncReadwise` composed from the canonical service. + +Expose: + +```python +.documents +.highlights +.books +.tags +.digests +.sync +.raw +``` + +Add public facade tests and documentation examples. + +Keep `AsyncReadwiseClient` unchanged externally but let it share resources. + +## PR 10 — Add the synchronous SDK facade + +Add `Readwise` using a dedicated AnyIO blocking portal. + +Test: + +- ordinary synchronous use. +- use from a thread with an already running event loop. +- context-manager cleanup. +- repeated operations. +- exceptions crossing the portal. +- cancellation and close behavior. + +Do not convert legacy synchronous iterators yet. + +## PR 11 — Rebuild the CLI shell + +Split `cli/main.py` into command modules. + +Add: + +- global `--output`. +- common output renderer. +- consistent errors and exit codes. +- service context/lifecycle. +- strict stdout/stderr separation. + +Initially migrate direct equivalents only: + +- documents. +- highlights. +- books. +- version/auth. + +Keep old command names and output defaults. + +## PR 12 — Expand the CLI + +Add missing core-backed commands: + +- document get/update/delete/move/tag. +- highlight create/update/delete/tag/untag. +- custom digest. +- sync status/reset. +- JSONL output. +- global no-color and quiet behavior. + +Add deprecated `reader` aliases for `documents`. + +## PR 13 — Consolidate tags and digests + +Move: + +- `TagWorkflow`. +- digest data selection. +- grouping logic. + +into operations. + +Move Markdown, text, CSV, and JSON rendering into presenters. + +`DigestBuilder` becomes a compatibility wrapper that calls digest operations plus a presenter. + +## PR 14 — Consolidate synchronization and persistence + +Replace duplicated state handling with: + +```python +class StateStore(Protocol): + def load(self) -> SyncCheckpoint: ... + def save(self, checkpoint: SyncCheckpoint) -> None: ... +``` + +Provide `JsonFileStateStore`. + +Rebuild: + +- full sync. +- incremental sync. +- poll-once. +- batch callbacks. +- background scheduling. + +on the same sync operation. + +Keep legacy state-file readers capable of loading current formats. + +## PR 15 — Convert managers, workflows, and contrib to shims + +Replace implementation bodies with delegation. + +For example: + +```python +class HighlightManager: + def search_highlights(...): + warn_deprecated(...) + return self._client.operations.highlights.search_legacy(...) +``` + +Preserve old return types and failure behavior. + +Once delegation is complete, delete duplicated implementation code. + +## PR 16 — Canonicalize model paths + +Move canonical definitions to: + +- `models/readwise.py`. +- `models/reader.py`. + +Keep: + +- `v2/models.py`. +- `v3/models.py`. + +as re-export modules. + +Update internal code, including MCP, to import only canonical paths. + +## PR 17 — Tighten typing and packaging + +- Remove CLI and MCP exclusions from `Justfile:18`. +- Type-check adapters. +- Ensure importing core does not import Typer, Rich, or MCP. +- Verify wheels with core only, `[cli]`, and `[mcp]`. +- Verify both console scripts. +- Add a `py.typed` marker if not already included. +- Build with Hatchling and inspect wheel contents. + +## PR 18 — Documentation and deprecation release + +Update: + +- README. +- `llms.txt`. +- API guides. +- CLI documentation. +- migration guide. +- deprecation timeline. +- architecture contributor guide. + +Release as: + +```text +feat!: introduce unified Readwise operations architecture +``` + +Version: `0.3.0`. + +--- + +# 8. Risks and De-Risking + +## Public API breakage + +**Risk:** Downstream users may import undocumented-but-accessible classes and models. + +**Mitigation:** + +- Keep old modules as re-exports. +- Add import-contract tests. +- Search README, docs, tests, and release history for every promoted import. +- Publish a migration table. +- Delay removals until 1.0. + +## Behavioral drift in MCP + +**Risk:** Moving validation, filtering, and serialization changes tool output. + +**Mitigation:** + +- Treat current MCP JSON as a wire contract. +- Add exact characterization tests before migration. +- Migrate one tool group at a time. +- Keep MCP presenters separate from general JSON presenters. +- Make behavior fixes in separate PRs after the refactor. + +## Sync bridge complexity + +**Risk:** Threaded portal lifecycle, exceptions, and streaming can be subtle. + +**Mitigation:** + +- Keep the sync facade deliberately small. +- Avoid sync streaming in the new operation API initially. +- Retain legacy native-sync raw clients. +- Add tests for running-event-loop environments. +- Make ownership explicit: the facade owns and closes its portal and async client. + +## State-file incompatibility + +**Risk:** Users may have persisted `SyncManager`, `BatchSync`, or poller state. + +**Mitigation:** + +- Add version fields to new state files. +- Write migration readers for all existing structures. +- Never silently reset malformed or unknown state. +- Back up or preserve legacy files before rewriting. +- Characterize current datetime formatting. + +## Loss of partial-failure semantics + +**Risk:** Existing bulk methods frequently suppress exceptions and return booleans. + +**Mitigation:** + +- Introduce a typed `BulkResult`. +- Compatibility wrappers convert it back to current dictionaries/lists. +- Record the original exception in the new result. +- Do not continue broad `except Exception` in canonical operations. + +## Over-generalized operation framework + +**Risk:** A command bus, registry, or generated metaprogramming system could obscure simple calls. + +**Mitigation:** + +- Use explicit service classes and ordinary methods. +- Do not derive CLI or MCP schemas automatically from operation signatures. +- Share behavior, not protocol metadata. +- Prefer duplicated five-line adapter declarations over a clever universal decorator. + +## Dependency leakage + +**Risk:** Core imports may accidentally require CLI or MCP extras. + +**Mitigation:** + +- Keep adapters at the outermost layer. +- Test importing `readwise_sdk` with only core dependencies installed. +- Keep FastMCP imports entirely under `readwise_sdk.mcp`. +- Keep Rich and Typer imports entirely under `readwise_sdk.cli`. + +## Type-checking expansion + +**Risk:** Enabling `ty` for CLI and MCP may expose many existing issues. + +**Mitigation:** + +- Add adapter typing after splitting the large modules. +- Remove exclusions directory by directory. +- Use typed context objects and result presenters. +- Avoid `Any` in operation boundaries even if protocol adapters require it. + +--- + +# Final Recommendation + +Proceed with an **aggressive `0.3.0` architecture migration** built around an async `ReadwiseService`. + +The key rule should be: + +> Resource clients know Readwise endpoints. Operations know user intent. Adapters know presentation and protocol. + +Under that rule: + +- `.v2` and `.v3` become low-level compatibility access. +- Managers, workflows, and contrib stop owning behavior. +- CLI commands and MCP tools call the same operation methods. +- Async behavior is canonical. +- Sync is a deliberate facade, not a second implementation. +- Existing imports and observable behavior survive through tested shims until `1.0`. \ No newline at end of file diff --git a/REFACTORING_DISCIPLINE.md b/REFACTORING_DISCIPLINE.md new file mode 100644 index 0000000..f1ae49b --- /dev/null +++ b/REFACTORING_DISCIPLINE.md @@ -0,0 +1,21 @@ +# Refactoring Discipline — Michael Feathers, *Working Effectively with Legacy Code* + +This restructure is a legacy-code exercise. Every stage MUST honor these rules. They override speed, cleverness, and convenience. A stage that cannot follow them is too big — split it. + +1. **Legacy code is code without tests.** No structural change ships without a test that would fail if behavior regressed. If code isn't covered, cover it *before* moving it. + +2. **Characterization tests pin ACTUAL behavior, not intended behavior.** They record what the code does *today* — quirks and bugs included. When a test captures surprising or wrong behavior, keep it and annotate `# characterizes current (buggy) behavior`. Do not "correct" it in the same breath. + +3. **Cover and Modify — never Edit and Pray.** Get code under test first, then change it. If it's untestable as written, introduce a *seam* (a place to substitute behavior without editing in place) and break the dependency minimally, rather than rewriting blind. + +4. **Refactoring preserves behavior — full stop.** Never change structure and behavior in the same commit. Move / rename / extract / re-layer are behavior-neutral. Bug fixes and feature changes are SEPARATE, clearly-labeled commits, each with a test that *demonstrates* the change. (Example: the `save_to_reader(category=…)` bug is fixed in its own commit, only after a characterization test locks the current — broken — payload.) + +5. **Small steps, always green.** Every step ends with `just fc` passing (format, lint, type, test). Prefer many tiny verifiable moves to one big leap. Never weaken the Justfile, delete/skip a test, or widen a `ty` exclusion to make a step "pass." + +6. **Preserve the public contract with shims, not by freezing internals.** Old imports and return values survive through re-exports and compatibility wrappers whose behavior is pinned by characterization tests. Internals may change freely; the observable surface may not — until 1.0. + +7. **The Legacy Change Algorithm**, applied to each move: identify change points → find test points → break dependencies (seams) → write tests → make the change → refactor. + +8. **When in doubt, add a test.** A refactor you can't cover is a refactor you shouldn't make yet. + +> Resource clients know endpoints. Operations know intent. Adapters know protocol. Tests know what must not change. From 5a6f9ff318df978876e0a5520730e94103671a62 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 22:39:19 -0500 Subject: [PATCH 04/24] test: characterization tests locking current behavior (refactor stage 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stage 1 of the 0.3.0 restructure (Feathers step 1: cover before you move). 69 characterization tests pinning today's observable behavior before any code moves — public exports, client/context-manager contracts, the three pagination cursor styles, manager return shapes, sync-state JSON schemas, CLI stdout/stderr/exit codes, and all nine MCP tools' exact JSON envelopes. Includes tests that pin known-buggy behavior AS-IS (e.g. save_to_reader drops `category`) so a later, separate commit can fix it deliberately. Tests only; no src/ changes. `just fc` green (605 passed). Generated by Codex gpt-5.6-sol under REFACTORING_DISCIPLINE.md. Co-Authored-By: Claude Opus 4.8 (1M context) --- tests/characterization/__init__.py | 1 + tests/characterization/test_cli_contracts.py | 128 ++++++ .../characterization/test_client_contracts.py | 109 +++++ .../test_manager_contracts.py | 115 +++++ tests/characterization/test_mcp_contracts.py | 395 ++++++++++++++++++ .../test_pagination_contracts.py | 148 +++++++ tests/characterization/test_public_api.py | 148 +++++++ .../characterization/test_state_contracts.py | 151 +++++++ 8 files changed, 1195 insertions(+) create mode 100644 tests/characterization/__init__.py create mode 100644 tests/characterization/test_cli_contracts.py create mode 100644 tests/characterization/test_client_contracts.py create mode 100644 tests/characterization/test_manager_contracts.py create mode 100644 tests/characterization/test_mcp_contracts.py create mode 100644 tests/characterization/test_pagination_contracts.py create mode 100644 tests/characterization/test_public_api.py create mode 100644 tests/characterization/test_state_contracts.py diff --git a/tests/characterization/__init__.py b/tests/characterization/__init__.py new file mode 100644 index 0000000..b9f169d --- /dev/null +++ b/tests/characterization/__init__.py @@ -0,0 +1 @@ +"""Characterization contracts for the pre-refactor public behavior.""" diff --git a/tests/characterization/test_cli_contracts.py b/tests/characterization/test_cli_contracts.py new file mode 100644 index 0000000..64b15b7 --- /dev/null +++ b/tests/characterization/test_cli_contracts.py @@ -0,0 +1,128 @@ +"""Characterize representative CLI output, streams, statuses, and JSON.""" + +from __future__ import annotations + +import importlib +from importlib.metadata import version + +import httpx +import pytest +import respx + +from readwise_sdk.client import READWISE_API_V2_BASE, READWISE_API_V3_BASE + +pytest.importorskip("typer") +pytest.importorskip("rich") +typer_testing = importlib.import_module("typer.testing") +app = importlib.import_module("readwise_sdk.cli.main").app + +runner = typer_testing.CliRunner() + + +def test_version_writes_exact_stdout_and_no_stderr() -> None: + """The version command is a clean successful stdout-only command.""" + result = runner.invoke(app, ["version"]) + + assert result.exit_code == 0 + assert result.stdout == f"readwise-plus v{version('readwise-plus')}\n" + assert result.stderr == "" + + +@respx.mock +def test_highlights_json_has_exact_structure_and_stdout_routing( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Highlight JSON includes null note and is emitted only on stdout.""" + monkeypatch.setenv("READWISE_API_KEY", "token") + respx.get(f"{READWISE_API_V2_BASE}/highlights/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [{"id": 7, "text": "Exact text", "note": None}], + "next": None, + }, + ) + ) + + result = runner.invoke(app, ["highlights", "list", "--json"]) + + assert result.exit_code == 0 + assert result.stdout == ( + '[\n {\n "id": 7,\n "text": "Exact text",\n "note": null\n }\n]\n' + ) + assert result.stderr == "" + + +@respx.mock +def test_reader_inbox_json_has_exact_structure_and_stdout_routing( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Reader JSON retains null fields and the documented key ordering.""" + monkeypatch.setenv("READWISE_API_KEY", "token") + respx.get(f"{READWISE_API_V3_BASE}/list/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": "doc-1", + "url": "https://example.com/article", + "title": None, + "category": None, + } + ], + "nextPageCursor": None, + }, + ) + ) + + result = runner.invoke(app, ["reader", "inbox", "--json"]) + + assert result.exit_code == 0 + assert result.stdout == ( + "[\n" + " {\n" + ' "id": "doc-1",\n' + ' "title": null,\n' + ' "url": "https://example.com/article",\n' + ' "category": null\n' + " }\n" + "]\n" + ) + assert result.stderr == "" + + +def test_missing_api_key_is_an_exit_one_message_on_stdout( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Application-level configuration errors currently use stdout.""" + monkeypatch.delenv("READWISE_API_KEY", raising=False) + + result = runner.invoke(app, ["highlights", "list"]) + + assert result.exit_code == 1 + assert result.stdout == "Error: READWISE_API_KEY environment variable not set\n" + assert result.stderr == "" + + +def test_invalid_book_category_is_an_exit_one_message_on_stdout( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Command validation performed inside the handler currently uses stdout.""" + monkeypatch.setenv("READWISE_API_KEY", "token") + + result = runner.invoke(app, ["books", "list", "--category", "invalid"]) + + assert result.exit_code == 1 + assert result.stdout == "Invalid category. Use: books, articles, tweets, podcasts\n" + assert result.stderr == "" + + +def test_typer_parse_error_is_exit_two_and_routed_to_stderr() -> None: + """Framework-level argument errors differ from application errors.""" + result = runner.invoke(app, ["highlights", "list", "--bad-option"]) + + assert result.exit_code == 2 + assert result.stdout == "" + assert "No such option: --bad-option" in result.stderr + assert "Usage: readwise highlights list [OPTIONS]" in result.stderr diff --git a/tests/characterization/test_client_contracts.py b/tests/characterization/test_client_contracts.py new file mode 100644 index 0000000..f06a7b4 --- /dev/null +++ b/tests/characterization/test_client_contracts.py @@ -0,0 +1,109 @@ +"""Characterize construction, composition, and lifecycle of public clients.""" + +from __future__ import annotations + +import httpx +import pytest + +from readwise_sdk.client import AsyncReadwiseClient, ReadwiseClient +from readwise_sdk.exceptions import AuthenticationError +from readwise_sdk.v2.async_client import AsyncReadwiseV2Client +from readwise_sdk.v2.client import ReadwiseV2Client +from readwise_sdk.v3.async_client import AsyncReadwiseV3Client +from readwise_sdk.v3.client import ReadwiseV3Client + + +def test_sync_client_constructor_and_composed_clients( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Constructor settings and lazy cached v2/v3 resources are observable.""" + monkeypatch.delenv("READWISE_API_KEY", raising=False) + with pytest.raises(AuthenticationError, match="API key is required"): + ReadwiseClient() + + client = ReadwiseClient("token", 12.5, 7, 1.25) + assert (client.api_key, client.timeout, client.max_retries, client.retry_backoff) == ( + "token", + 12.5, + 7, + 1.25, + ) + assert isinstance(client.v2, ReadwiseV2Client) + assert isinstance(client.v3, ReadwiseV3Client) + assert client.v2 is client.v2 + assert client.v3 is client.v3 + + +def test_sync_client_context_manager_returns_self_and_closes_transport() -> None: + """The sync context manager closes an initialized transport on exit.""" + client = ReadwiseClient(api_key="token") + with client as entered: + transport = entered.client + assert entered is client + assert isinstance(transport, httpx.Client) + assert transport.is_closed is False + + assert transport.is_closed is True + assert client._client is None + + +def test_sync_create_optional_defers_missing_key_failure( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """create_optional permits construction but not requests without a key.""" + monkeypatch.delenv("READWISE_API_KEY", raising=False) + client = ReadwiseClient.create_optional(timeout=9, max_retries=4, retry_backoff=2) + assert client.is_configured is False + assert client.api_key is None + assert (client.timeout, client.max_retries, client.retry_backoff) == (9, 4, 2) + with pytest.raises(AuthenticationError, match="API key is required"): + client.get("https://readwise.io/api/v2/highlights/") + + +def test_async_client_constructor_and_composed_clients( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Async construction mirrors sync construction and caches async resources.""" + monkeypatch.delenv("READWISE_API_KEY", raising=False) + with pytest.raises(AuthenticationError, match="API key is required"): + AsyncReadwiseClient() + + client = AsyncReadwiseClient("token", 12.5, 7, 1.25) + assert (client.api_key, client.timeout, client.max_retries, client.retry_backoff) == ( + "token", + 12.5, + 7, + 1.25, + ) + assert isinstance(client.v2, AsyncReadwiseV2Client) + assert isinstance(client.v3, AsyncReadwiseV3Client) + assert client.v2 is client.v2 + assert client.v3 is client.v3 + + +@pytest.mark.asyncio +async def test_async_client_context_manager_returns_self_and_closes_transport() -> None: + """The async context manager closes an initialized transport on exit.""" + client = AsyncReadwiseClient(api_key="token") + async with client as entered: + transport = entered.client + assert entered is client + assert isinstance(transport, httpx.AsyncClient) + assert transport.is_closed is False + + assert transport.is_closed is True + assert client._client is None + + +@pytest.mark.asyncio +async def test_async_create_optional_defers_missing_key_failure( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Async create_optional also defers authentication until request time.""" + monkeypatch.delenv("READWISE_API_KEY", raising=False) + client = AsyncReadwiseClient.create_optional(timeout=9, max_retries=4, retry_backoff=2) + assert client.is_configured is False + assert client.api_key is None + assert (client.timeout, client.max_retries, client.retry_backoff) == (9, 4, 2) + with pytest.raises(AuthenticationError, match="API key is required"): + await client.get("https://readwise.io/api/v2/highlights/") diff --git a/tests/characterization/test_manager_contracts.py b/tests/characterization/test_manager_contracts.py new file mode 100644 index 0000000..2a59695 --- /dev/null +++ b/tests/characterization/test_manager_contracts.py @@ -0,0 +1,115 @@ +"""Characterize manager result containers and partial-failure behavior.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator, Iterator +from typing import Any +from unittest.mock import AsyncMock, Mock + +import pytest + +from readwise_sdk.managers import ( + AsyncDocumentManager, + AsyncHighlightManager, + BookManager, + DocumentManager, + HighlightManager, +) +from readwise_sdk.managers.books import BookWithHighlights +from readwise_sdk.v2.models import Book, Highlight, Tag +from readwise_sdk.v3.models import Document + + +def test_sync_manager_collection_methods_materialize_lists() -> None: + """The three manager families return lists rather than raw iterators.""" + highlight = Highlight(id=1, text="one") + book = Book(id=2, title="two") + document = Document(id="three", url="https://example.com/three") + client: Any = Mock() + client.v2.list_highlights.return_value = iter([highlight]) + client.v2.list_books.return_value = iter([book]) + client.v3.get_inbox.return_value = iter([document]) + + assert HighlightManager(client).get_all_highlights() == [highlight] + assert BookManager(client).get_all_books() == [book] + assert DocumentManager(client).get_inbox() == [document] + + +def test_filter_methods_remain_lazy_iterators_while_search_is_a_list() -> None: + """Predicate filters are lazy, while manager search eagerly materializes.""" + highlight = Highlight(id=1, text="matching highlight") + document = Document(id="doc", url="https://example.com", title="Matching document") + client: Any = Mock() + client.v2.list_highlights.side_effect = lambda **_kwargs: iter([highlight]) + client.v3.list_documents.side_effect = lambda **_kwargs: iter([document]) + + highlight_manager = HighlightManager(client) + document_manager = DocumentManager(client) + highlight_filter = highlight_manager.filter_highlights(lambda _item: True) + document_filter = document_manager.filter_documents(lambda _item: True) + + assert isinstance(highlight_filter, Iterator) + assert isinstance(document_filter, Iterator) + assert list(highlight_filter) == [highlight] + assert list(document_filter) == [document] + assert highlight_manager.search_highlights("matching") == [highlight] + assert document_manager.search_documents("matching") == [document] + + +def test_book_with_highlights_return_shape_is_a_dataclass_with_a_list() -> None: + """The composed book result retains its named fields and list shape.""" + highlight = Highlight(id=1, text="one") + book = Book(id=2, title="two") + client: Any = Mock() + client.v2.get_book.return_value = book + client.v2.list_highlights.return_value = iter([highlight]) + + result = BookManager(client).get_book_with_highlights(2) + + assert isinstance(result, BookWithHighlights) + assert result.book is book + assert isinstance(result.highlights, list) + assert result.highlights == [highlight] + + +def test_sync_bulk_operations_return_complete_partial_failure_maps() -> None: + """Every requested ID is mapped to bool even when individual calls fail.""" + client: Any = Mock() + client.v2.create_highlight_tag.side_effect = [Tag(id=1, name="tag"), RuntimeError("no")] + client.v3.archive.side_effect = [None, RuntimeError("no")] + client.v3.tag_document.side_effect = [RuntimeError("no"), None] + + # NOTE: characterizes current (possibly overly broad) exception suppression. + assert HighlightManager(client).bulk_tag([1, 2], "tag") == {1: True, 2: False} + assert DocumentManager(client).bulk_archive(["a", "b"]) == {"a": True, "b": False} + assert DocumentManager(client).bulk_tag_documents(["a", "b"], ["tag"]) == { + "a": False, + "b": True, + } + + +@pytest.mark.asyncio +async def test_async_manager_lists_iterators_and_partial_failure_maps() -> None: + """Async managers preserve list, async-iterator, and bool-map shapes.""" + highlight = Highlight(id=1, text="one") + document = Document(id="doc", url="https://example.com") + client: Any = Mock() + + async def highlights() -> AsyncIterator[Highlight]: + yield highlight + + async def documents(**_kwargs: Any) -> AsyncIterator[Document]: + yield document + + client.v2.list_highlights = highlights + client.v3.list_documents = documents + client.v3.archive = AsyncMock(side_effect=[None, RuntimeError("no")]) + + highlight_manager = AsyncHighlightManager(client) + document_manager = AsyncDocumentManager(client) + assert await highlight_manager.get_all_highlights() == [highlight] + filtered = document_manager.filter_documents(lambda _item: True) + assert isinstance(filtered, AsyncIterator) + assert [item async for item in filtered] == [document] + # NOTE: characterizes current (possibly overly broad) exception suppression. + assert await document_manager.bulk_archive(["a", "b"]) == {"a": True, "b": False} diff --git a/tests/characterization/test_mcp_contracts.py b/tests/characterization/test_mcp_contracts.py new file mode 100644 index 0000000..fff4f92 --- /dev/null +++ b/tests/characterization/test_mcp_contracts.py @@ -0,0 +1,395 @@ +"""Exact characterization contracts for all nine MCP tool handlers.""" + +from __future__ import annotations + +import json + +import httpx +import pytest +import respx + +pytest.importorskip("mcp") + +from readwise_sdk.mcp.server import ( + create_highlight, + delete_document, + export_highlights, + get_books, + get_document, + get_highlights, + save_to_reader, + search_documents, + update_document, +) + +V2_BASE = "https://readwise.io/api/v2" +V3_BASE = "https://readwise.io/api/v3" + + +@pytest.fixture(autouse=True) +def _api_key(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("READWISE_API_KEY", "token") + + +@respx.mock +@pytest.mark.asyncio +async def test_save_to_reader_returns_exact_compact_json() -> None: + """save_to_reader is a compact two-field JSON adapter.""" + respx.post(f"{V3_BASE}/save/").mock( + return_value=httpx.Response( + 201, + json={"id": "doc-1", "url": "https://read.readwise.io/read/doc-1"}, + ) + ) + + assert await save_to_reader("https://example.com") == ( + '{"id": "doc-1", "url": "https://read.readwise.io/read/doc-1"}' + ) + + +@respx.mock +@pytest.mark.asyncio +async def test_save_to_reader_category_is_currently_dropped_from_payload() -> None: + """The accepted category argument is not copied into DocumentCreate today.""" + route = respx.post(f"{V3_BASE}/save/").mock( + return_value=httpx.Response(201, json={"id": "doc-1", "url": "reader-url"}) + ) + + await save_to_reader( + "https://example.com", + title="Title", + author="Author", + summary="Summary", + html="

Body

", + tags=["tag"], + notes="Note", + category="article", + location="later", + ) + + # NOTE: characterizes current (possibly buggy) behavior; category is dropped. + assert json.loads(route.calls.last.request.content) == { + "url": "https://example.com", + "html": "

Body

", + "title": "Title", + "author": "Author", + "summary": "Summary", + "location": "later", + "saved_using": "readwise-mcp", + "tags": ["tag"], + "notes": "Note", + } + + +@respx.mock +@pytest.mark.asyncio +async def test_search_documents_returns_exact_compact_json_and_omits_none() -> None: + """Document summaries omit absent fields rather than serializing nulls.""" + respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": "doc-1", + "url": "https://reader.example/doc-1", + "source_url": "https://source.example/article", + "title": "Title", + "author": None, + "category": "article", + "location": "new", + "tags": [], + "word_count": 10, + } + ], + "nextPageCursor": None, + }, + ) + ) + + assert await search_documents() == ( + '[{"id": "doc-1", "title": "Title", ' + '"url": "https://source.example/article", "category": "article", ' + '"location": "new", "word_count": 10}]' + ) + + +@respx.mock +@pytest.mark.asyncio +async def test_get_document_returns_exact_full_compact_json_and_omits_none() -> None: + """Full documents add only truthy content, summary, and notes fields.""" + respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": "doc-1", + "url": "https://example.com", + "title": None, + "content": "

Body

", + "summary": "Summary", + "notes": "", + } + ], + "nextPageCursor": None, + }, + ) + ) + + assert await get_document("doc-1") == ( + '{"id": "doc-1", "url": "https://example.com", ' + '"content": "

Body

", "summary": "Summary"}' + ) + + +@respx.mock +@pytest.mark.asyncio +async def test_update_document_returns_exact_compact_json() -> None: + """update_document returns only the API's id and URL projection.""" + respx.patch(f"{V3_BASE}/update/doc-1/").mock( + return_value=httpx.Response(200, json={"id": "doc-1", "url": "reader-url"}) + ) + + assert await update_document("doc-1", title="New") == ('{"id": "doc-1", "url": "reader-url"}') + + +@respx.mock +@pytest.mark.asyncio +async def test_delete_document_returns_exact_compact_json() -> None: + """delete_document returns its exact confirmation envelope.""" + respx.delete(f"{V3_BASE}/delete/doc-1/").mock(return_value=httpx.Response(204)) + + assert await delete_document("doc-1") == '{"deleted": "doc-1"}' + + +@respx.mock +@pytest.mark.asyncio +async def test_get_highlights_returns_exact_compact_json_and_omits_none() -> None: + """Highlight summaries include zero values and omit absent optional fields.""" + respx.get(f"{V2_BASE}/highlights/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": 1, + "text": "Insight", + "note": None, + "book_id": 0, + "color": "yellow", + "location": 0, + "tags": [], + } + ], + "next": None, + }, + ) + ) + + assert await get_highlights() == ( + '[{"id": 1, "text": "Insight", "book_id": 0, "color": "yellow", "location": 0}]' + ) + + +@respx.mock +@pytest.mark.asyncio +async def test_export_highlights_returns_exact_compact_json_and_omits_none() -> None: + """Export books and their nested highlights use compact projections.""" + respx.get(f"{V2_BASE}/export/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "user_book_id": 2, + "title": "Book", + "author": None, + "highlights": [{"id": 1, "text": "Insight", "tags": []}], + } + ], + "nextPageCursor": None, + }, + ) + ) + + assert await export_highlights() == ( + '[{"book_id": 2, "title": "Book", "highlights": [{"id": 1, "text": "Insight"}]}]' + ) + + +@respx.mock +@pytest.mark.asyncio +async def test_create_highlight_returns_exact_compact_json() -> None: + """create_highlight returns the exact created-IDs envelope.""" + respx.post(f"{V2_BASE}/highlights/").mock( + return_value=httpx.Response(200, json=[{"modified_highlights": [8, 9]}]) + ) + + assert await create_highlight("Insight") == '{"created_highlight_ids": [8, 9]}' + + +@respx.mock +@pytest.mark.asyncio +async def test_get_books_returns_exact_compact_json_and_omits_none() -> None: + """Book summaries retain zero counts but omit absent metadata.""" + respx.get(f"{V2_BASE}/books/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": 2, + "title": "Book", + "author": None, + "category": "books", + "source": None, + "num_highlights": 0, + } + ], + "next": None, + }, + ) + ) + + assert await get_books() == ( + '[{"id": 2, "title": "Book", "category": "books", "num_highlights": 0}]' + ) + + +@pytest.mark.asyncio +async def test_invalid_enums_return_exact_error_envelopes() -> None: + """Every enum-validating MCP entry point retains its current message.""" + assert await save_to_reader("https://example.com", location="bad") == ( + '{"error": "Invalid location \'bad\'. Use: new, later, archive, feed."}' + ) + assert await search_documents(location="bad") == ('{"error": "Invalid location \'bad\'."}') + assert await search_documents(category="bad") == ('{"error": "Invalid category \'bad\'."}') + assert await update_document("doc-1", location="bad") == ( + '{"error": "Invalid location \'bad\'."}' + ) + assert await create_highlight("text", category="bad") == ( + '{"error": "Invalid category \'bad\'. Use: books, articles, tweets, podcasts."}' + ) + assert await get_books(category="bad") == '{"error": "Invalid category \'bad\'."}' + + +@respx.mock +@pytest.mark.asyncio +async def test_document_not_found_messages_are_exact() -> None: + """All three document tools use the same quoted not-found wording.""" + respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response(200, json={"results": [], "nextPageCursor": None}) + ) + respx.patch(f"{V3_BASE}/update/missing/").mock( + return_value=httpx.Response(404, text="not found") + ) + respx.delete(f"{V3_BASE}/delete/missing/").mock( + return_value=httpx.Response(404, text="not found") + ) + expected = '{"error": "Document \'missing\' not found."}' + + assert await get_document("missing") == expected + assert await update_document("missing", title="new") == expected + assert await delete_document("missing") == expected + + +def _documents(count: int) -> list[dict[str, object]]: + return [{"id": f"doc-{index}", "url": f"https://example.com/{index}"} for index in range(count)] + + +def _highlights(count: int) -> list[dict[str, object]]: + return [{"id": index, "text": f"highlight-{index}"} for index in range(count)] + + +def _exports(count: int) -> list[dict[str, object]]: + return [ + {"user_book_id": index, "title": f"book-{index}", "highlights": []} + for index in range(count) + ] + + +def _books(count: int) -> list[dict[str, object]]: + return [{"id": index, "title": f"book-{index}"} for index in range(count)] + + +@respx.mock +@pytest.mark.asyncio +async def test_search_documents_default_minimum_and_maximum_limits() -> None: + """Document search defaults to 20 and clamps into the inclusive 1..100 range.""" + respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response(200, json={"results": _documents(101), "nextPageCursor": None}) + ) + + assert len(json.loads(await search_documents())) == 20 + assert len(json.loads(await search_documents(limit=0))) == 1 + assert len(json.loads(await search_documents(limit=1000))) == 100 + + +@respx.mock +@pytest.mark.asyncio +async def test_get_highlights_default_minimum_and_maximum_limits() -> None: + """Highlight search defaults to 50 and clamps into the inclusive 1..200 range.""" + respx.get(f"{V2_BASE}/highlights/").mock( + return_value=httpx.Response(200, json={"results": _highlights(201), "next": None}) + ) + + assert len(json.loads(await get_highlights())) == 50 + assert len(json.loads(await get_highlights(limit=0))) == 1 + assert len(json.loads(await get_highlights(limit=1000))) == 200 + + +@respx.mock +@pytest.mark.asyncio +async def test_export_highlights_default_minimum_and_maximum_limits() -> None: + """Highlight export defaults to 20 and clamps into the inclusive 1..100 range.""" + respx.get(f"{V2_BASE}/export/").mock( + return_value=httpx.Response(200, json={"results": _exports(101), "nextPageCursor": None}) + ) + + assert len(json.loads(await export_highlights())) == 20 + assert len(json.loads(await export_highlights(limit=0))) == 1 + assert len(json.loads(await export_highlights(limit=1000))) == 100 + + +@respx.mock +@pytest.mark.asyncio +async def test_get_books_default_minimum_and_maximum_limits() -> None: + """Book search defaults to 20 and clamps into the inclusive 1..100 range.""" + respx.get(f"{V2_BASE}/books/").mock( + return_value=httpx.Response(200, json={"results": _books(101), "next": None}) + ) + + assert len(json.loads(await get_books())) == 20 + assert len(json.loads(await get_books(limit=0))) == 1 + assert len(json.loads(await get_books(limit=1000))) == 100 + + +@respx.mock +@pytest.mark.asyncio +async def test_invalid_datetimes_are_leniently_ignored_by_all_four_tools() -> None: + """Invalid ISO strings silently become None rather than error envelopes.""" + docs = respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response(200, json={"results": [], "nextPageCursor": None}) + ) + highlights = respx.get(f"{V2_BASE}/highlights/").mock( + return_value=httpx.Response(200, json={"results": [], "next": None}) + ) + exports = respx.get(f"{V2_BASE}/export/").mock( + return_value=httpx.Response(200, json={"results": [], "nextPageCursor": None}) + ) + created = respx.post(f"{V2_BASE}/highlights/").mock( + return_value=httpx.Response(200, json=[{"modified_highlights": [1]}]) + ) + + # NOTE: characterizes current lenient (possibly surprising) parsing. + assert await search_documents(updated_after="not-a-date") == "[]" + assert await get_highlights(updated_after="not-a-date") == "[]" + assert await export_highlights(updated_after="not-a-date") == "[]" + assert await create_highlight("text", highlighted_at="not-a-date") == ( + '{"created_highlight_ids": [1]}' + ) + assert str(docs.calls.last.request.url) == f"{V3_BASE}/list/" + assert str(highlights.calls.last.request.url) == f"{V2_BASE}/highlights/?page_size=100" + assert str(exports.calls.last.request.url) == f"{V2_BASE}/export/" + assert json.loads(created.calls.last.request.content) == {"highlights": [{"text": "text"}]} diff --git a/tests/characterization/test_pagination_contracts.py b/tests/characterization/test_pagination_contracts.py new file mode 100644 index 0000000..7c4a8f9 --- /dev/null +++ b/tests/characterization/test_pagination_contracts.py @@ -0,0 +1,148 @@ +"""Lock the three pagination cursor dialects and exact request sequences.""" + +from __future__ import annotations + +import httpx +import pytest +import respx + +from readwise_sdk.client import ( + READWISE_API_V2_BASE, + READWISE_API_V3_BASE, + AsyncReadwiseClient, + ReadwiseClient, +) + + +def _urls(route: respx.Route) -> list[str]: + return [str(call.request.url) for call in route.calls] + + +@respx.mock +def test_sync_v2_next_url_replaces_the_request_url_and_parameters() -> None: + """Standard v2 `next` is a full URL whose query replaces prior params.""" + route = respx.get(url__startswith=f"{READWISE_API_V2_BASE}/highlights/").mock( + side_effect=[ + httpx.Response( + 200, + json={ + "results": [], + "next": f"{READWISE_API_V2_BASE}/highlights/?page=2", + }, + ), + httpx.Response(200, json={"results": [], "next": None}), + ] + ) + + list(ReadwiseClient("token").v2.list_highlights(page_size=25, book_id=7)) + + assert _urls(route) == [ + f"{READWISE_API_V2_BASE}/highlights/?page_size=25&book_id=7", + f"{READWISE_API_V2_BASE}/highlights/?page=2", + ] + + +@respx.mock +def test_sync_v2_export_integer_cursor_becomes_page_cursor() -> None: + """The v2 export integer cursor is stringified into `pageCursor`.""" + route = respx.get(f"{READWISE_API_V2_BASE}/export/").mock( + side_effect=[ + httpx.Response(200, json={"results": [], "nextPageCursor": 42}), + httpx.Response(200, json={"results": [], "nextPageCursor": None}), + ] + ) + + list(ReadwiseClient("token").v2.export_highlights(book_ids=[3, 4])) + + assert _urls(route) == [ + f"{READWISE_API_V2_BASE}/export/?ids=3%2C4", + f"{READWISE_API_V2_BASE}/export/?ids=3%2C4&pageCursor=42", + ] + + +@respx.mock +def test_sync_v3_cursor_becomes_page_cursor_and_retains_filters() -> None: + """Reader's `nextPageCursor` retains filters and adds `pageCursor`.""" + route = respx.get(f"{READWISE_API_V3_BASE}/list/").mock( + side_effect=[ + httpx.Response(200, json={"results": [], "nextPageCursor": "reader-cursor"}), + httpx.Response(200, json={"results": [], "nextPageCursor": None}), + ] + ) + + from readwise_sdk.v3.models import DocumentLocation + + list(ReadwiseClient("token").v3.list_documents(location=DocumentLocation.LATER)) + + assert _urls(route) == [ + f"{READWISE_API_V3_BASE}/list/?location=later", + f"{READWISE_API_V3_BASE}/list/?location=later&pageCursor=reader-cursor", + ] + + +@respx.mock +@pytest.mark.asyncio +async def test_async_v2_next_url_replaces_the_request_url_and_parameters() -> None: + """Async standard v2 pagination issues the same exact sequence.""" + route = respx.get(url__startswith=f"{READWISE_API_V2_BASE}/highlights/").mock( + side_effect=[ + httpx.Response( + 200, + json={ + "results": [], + "next": f"{READWISE_API_V2_BASE}/highlights/?page=2", + }, + ), + httpx.Response(200, json={"results": [], "next": None}), + ] + ) + + async with AsyncReadwiseClient("token") as client: + _ = [item async for item in client.v2.list_highlights(page_size=25, book_id=7)] + + assert _urls(route) == [ + f"{READWISE_API_V2_BASE}/highlights/?page_size=25&book_id=7", + f"{READWISE_API_V2_BASE}/highlights/?page=2", + ] + + +@respx.mock +@pytest.mark.asyncio +async def test_async_v2_export_integer_cursor_becomes_page_cursor() -> None: + """Async v2 export stringifies integer cursors in the same way.""" + route = respx.get(f"{READWISE_API_V2_BASE}/export/").mock( + side_effect=[ + httpx.Response(200, json={"results": [], "nextPageCursor": 42}), + httpx.Response(200, json={"results": [], "nextPageCursor": None}), + ] + ) + + async with AsyncReadwiseClient("token") as client: + _ = [item async for item in client.v2.export_highlights(book_ids=[3, 4])] + + assert _urls(route) == [ + f"{READWISE_API_V2_BASE}/export/?ids=3%2C4", + f"{READWISE_API_V2_BASE}/export/?ids=3%2C4&pageCursor=42", + ] + + +@respx.mock +@pytest.mark.asyncio +async def test_async_v3_cursor_becomes_page_cursor_and_retains_filters() -> None: + """Async Reader pagination retains filters while adding its cursor.""" + route = respx.get(f"{READWISE_API_V3_BASE}/list/").mock( + side_effect=[ + httpx.Response(200, json={"results": [], "nextPageCursor": "reader-cursor"}), + httpx.Response(200, json={"results": [], "nextPageCursor": None}), + ] + ) + + from readwise_sdk.v3.models import DocumentLocation + + async with AsyncReadwiseClient("token") as client: + _ = [item async for item in client.v3.list_documents(location=DocumentLocation.LATER)] + + assert _urls(route) == [ + f"{READWISE_API_V3_BASE}/list/?location=later", + f"{READWISE_API_V3_BASE}/list/?location=later&pageCursor=reader-cursor", + ] diff --git a/tests/characterization/test_public_api.py b/tests/characterization/test_public_api.py new file mode 100644 index 0000000..5ebc475 --- /dev/null +++ b/tests/characterization/test_public_api.py @@ -0,0 +1,148 @@ +"""Characterize the import surface that exists before the restructure.""" + +from __future__ import annotations + +import importlib + +import pytest + +import readwise_sdk + +ROOT_EXPORTS = [ + "ReadwiseClient", + "AsyncReadwiseClient", + "ReadwiseError", + "AuthenticationError", + "RateLimitError", + "NotFoundError", + "ValidationError", + "ServerError", + "Book", + "BookCategory", + "Highlight", + "HighlightColor", + "Tag", + "DailyReview", + "Document", + "DocumentCategory", + "DocumentCreate", + "DocumentLocation", + "DocumentTag", + "HighlightManager", + "BookManager", + "DocumentManager", + "SyncManager", + "SyncState", + "DigestBuilder", + "DigestFormat", + "BackgroundPoller", + "TagWorkflow", + "ReadingInbox", +] + +PACKAGE_EXPORTS = { + "readwise_sdk.managers": [ + "HighlightManager", + "BookManager", + "DocumentManager", + "SyncManager", + "SyncState", + "AsyncHighlightManager", + "AsyncBookManager", + "AsyncDocumentManager", + "AsyncSyncManager", + ], + "readwise_sdk.workflows": [ + "DigestBuilder", + "DigestFormat", + "BackgroundPoller", + "TagWorkflow", + "ReadingInbox", + ], + "readwise_sdk.contrib": [ + "HighlightPusher", + "AsyncHighlightPusher", + "SimpleHighlight", + "PushResult", + "UpdateResult", + "DeleteResult", + "TruncationInfo", + "FieldTruncation", + "DocumentImporter", + "AsyncDocumentImporter", + "ImportedDocument", + "ImportResult", + "BatchSync", + "AsyncBatchSync", + "BatchSyncConfig", + "BatchSyncResult", + ], + "readwise_sdk.v2": [ + "ReadwiseV2Client", + "AsyncReadwiseV2Client", + "Book", + "BookCategory", + "Highlight", + "HighlightColor", + "HighlightCreate", + "HighlightUpdate", + "Tag", + "DailyReview", + ], + "readwise_sdk.v3": [ + "ReadwiseV3Client", + "AsyncReadwiseV3Client", + "Document", + "DocumentCategory", + "DocumentLocation", + "DocumentTag", + "DocumentCreate", + "DocumentUpdate", + ], +} + + +def test_root_package_exports_are_exact_and_importable() -> None: + """The root package's declared public names remain stable and usable.""" + assert readwise_sdk.__all__ == ROOT_EXPORTS + assert isinstance(readwise_sdk.__version__, str) + for name in ROOT_EXPORTS: + assert getattr(readwise_sdk, name) is not None + + +@pytest.mark.parametrize(("module_name", "expected"), PACKAGE_EXPORTS.items()) +def test_subpackage_exports_are_exact_and_importable(module_name: str, expected: list[str]) -> None: + """Manager, workflow, contrib, and versioned imports are public today.""" + module = importlib.import_module(module_name) + assert module.__all__ == expected + for name in expected: + assert getattr(module, name) is not None + + +@pytest.mark.parametrize( + ("module_name", "class_name"), + [ + ("readwise_sdk.client", "ReadwiseClient"), + ("readwise_sdk.client", "AsyncReadwiseClient"), + ("readwise_sdk.v2.client", "ReadwiseV2Client"), + ("readwise_sdk.v2.async_client", "AsyncReadwiseV2Client"), + ("readwise_sdk.v3.client", "ReadwiseV3Client"), + ("readwise_sdk.v3.async_client", "AsyncReadwiseV3Client"), + ("readwise_sdk.managers.highlights", "HighlightManager"), + ("readwise_sdk.managers.books", "BookManager"), + ("readwise_sdk.managers.documents", "DocumentManager"), + ("readwise_sdk.managers.sync", "SyncManager"), + ("readwise_sdk.workflows.digest", "DigestBuilder"), + ("readwise_sdk.workflows.poller", "BackgroundPoller"), + ("readwise_sdk.workflows.tags", "TagWorkflow"), + ("readwise_sdk.workflows.inbox", "ReadingInbox"), + ("readwise_sdk.contrib.highlight_push", "HighlightPusher"), + ("readwise_sdk.contrib.document_import", "DocumentImporter"), + ("readwise_sdk.contrib.batch_sync", "BatchSync"), + ], +) +def test_existing_concrete_import_paths_remain_importable( + module_name: str, class_name: str +) -> None: + """Concrete module paths used before the refactor continue to resolve.""" + assert getattr(importlib.import_module(module_name), class_name) is not None diff --git a/tests/characterization/test_state_contracts.py b/tests/characterization/test_state_contracts.py new file mode 100644 index 0000000..c9d5675 --- /dev/null +++ b/tests/characterization/test_state_contracts.py @@ -0,0 +1,151 @@ +"""Lock the incompatible state-file schemas written by current sync helpers.""" + +from __future__ import annotations + +import json +from datetime import UTC, datetime +from typing import Any +from unittest.mock import Mock + +from readwise_sdk.contrib.batch_sync import BatchSync, BatchSyncConfig +from readwise_sdk.managers.async_managers import AsyncSyncManager +from readwise_sdk.managers.sync import SyncManager, SyncResult +from readwise_sdk.workflows.poller import BackgroundPoller, PollerConfig + +STAMP = datetime(2025, 2, 3, 4, 5, 6, tzinfo=UTC) + + +def test_sync_manager_writes_its_exact_json_schema(tmp_path) -> None: + """SyncManager persists five fields with ISO strings and nulls.""" + state_file = tmp_path / "sync-manager.json" + client: Any = Mock() + manager = SyncManager(client, state_file=state_file) + manager.state.last_highlight_sync = STAMP + manager.state.last_book_sync = None + manager.state.last_document_sync = STAMP + manager.state.total_syncs = 7 + manager.state.last_sync_time = STAMP + + manager._save_state() + + assert json.loads(state_file.read_text()) == { + "last_highlight_sync": "2025-02-03T04:05:06+00:00", + "last_book_sync": None, + "last_document_sync": "2025-02-03T04:05:06+00:00", + "total_syncs": 7, + "last_sync_time": "2025-02-03T04:05:06+00:00", + } + + +def test_batch_sync_writes_its_exact_json_schema(tmp_path) -> None: + """BatchSync uses per-resource totals and a bounded errors list.""" + state_file = tmp_path / "batch-sync.json" + client: Any = Mock() + sync = BatchSync(client, config=BatchSyncConfig(state_file=state_file)) + sync.state.last_highlight_sync = STAMP + sync.state.last_book_sync = None + sync.state.last_document_sync = STAMP + sync.state.total_highlights_synced = 11 + sync.state.total_books_synced = 12 + sync.state.total_documents_synced = 13 + sync.state.last_sync_time = STAMP + sync.state.errors = ["first", "second"] + + sync._save_state() + + assert json.loads(state_file.read_text()) == { + "last_highlight_sync": "2025-02-03T04:05:06+00:00", + "last_book_sync": None, + "last_document_sync": "2025-02-03T04:05:06+00:00", + "total_highlights_synced": 11, + "total_books_synced": 12, + "total_documents_synced": 13, + "last_sync_time": "2025-02-03T04:05:06+00:00", + "errors": ["first", "second"], + } + + +def test_background_poller_writes_its_exact_json_schema(tmp_path) -> None: + """Poller state omits its in-memory is_running flag from disk.""" + state_file = tmp_path / "poller.json" + client: Any = Mock() + poller = BackgroundPoller(client, config=PollerConfig(state_file=state_file)) + poller.state.last_poll_time = STAMP + poller.state.last_highlight_sync = STAMP + poller.state.last_document_sync = None + poller.state.poll_count = 9 + poller.state.error_count = 2 + poller.state.last_error = "boom" + poller.state.is_running = True + + poller._save_state() + + # NOTE: characterizes current behavior: is_running is deliberately absent on disk. + assert json.loads(state_file.read_text()) == { + "last_poll_time": "2025-02-03T04:05:06+00:00", + "last_highlight_sync": "2025-02-03T04:05:06+00:00", + "last_document_sync": None, + "poll_count": 9, + "error_count": 2, + "last_error": "boom", + } + + +def test_sync_manager_suppresses_callback_exceptions_and_continues() -> None: + """One broken callback does not prevent later callbacks from running.""" + client: Any = Mock() + manager = SyncManager(client) + received: list[SyncResult] = [] + + def broken(_result: SyncResult) -> None: + raise RuntimeError("callback failed") + + manager.on_sync(broken) + manager.on_sync(received.append) + result = SyncResult(sync_time=STAMP) + + # NOTE: characterizes current callback-exception suppression. + manager._notify_callbacks(result) + assert received == [result] + + +def test_async_sync_manager_suppresses_callback_exceptions_and_continues() -> None: + """AsyncSyncManager callbacks are synchronous and suppress exceptions too.""" + client: Any = Mock() + manager = AsyncSyncManager(client) + received: list[SyncResult] = [] + + def broken(_result: SyncResult) -> None: + raise RuntimeError("callback failed") + + manager.on_sync(broken) + manager.on_sync(received.append) + result = SyncResult(sync_time=STAMP) + + # NOTE: characterizes current callback-exception suppression. + manager._notify_callbacks(result) + assert received == [result] + + +def test_poller_suppresses_both_sync_and_error_callback_exceptions() -> None: + """Poller continues through failures in both callback registries.""" + client: Any = Mock() + poller = BackgroundPoller(client) + sync_received: list[SyncResult] = [] + errors_received: list[Exception] = [] + + def broken(_value: object) -> None: + raise RuntimeError("callback failed") + + result = SyncResult(sync_time=STAMP) + error = ValueError("poll failed") + poller.on_sync(broken) + poller.on_sync(sync_received.append) + poller.on_error(broken) + poller.on_error(errors_received.append) + + # NOTE: characterizes current callback-exception suppression. + poller._notify_callbacks(result) + poller._notify_error_callbacks(error) + assert sync_received == [result] + assert errors_received == [error] From ade3e57e5908d6f0592f5f47405ae04de8033242 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 22:50:23 -0500 Subject: [PATCH 05/24] refactor: extract canonical ClientConfig and errors (stage 2) Behavior-preserving. Adds immutable config.py (ClientConfig) and canonical errors.py; exceptions.py re-exports the same classes (identity-preserving, verified `exceptions.ReadwiseError is errors.ReadwiseError`). Sync/async clients delegate to ClientConfig with all defaults carried over verbatim (timeout 30.0, retries 3, backoff 0.5, v2/v3 base URLs). No behavior change; characterization + full suite green. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/__init__.py | 2 +- src/readwise_sdk/_utils.py | 2 +- src/readwise_sdk/client.py | 150 ++++++++++++++++++++++------ src/readwise_sdk/config.py | 44 ++++++++ src/readwise_sdk/errors.py | 86 ++++++++++++++++ src/readwise_sdk/exceptions.py | 95 ++++-------------- src/readwise_sdk/v2/async_client.py | 41 ++++---- src/readwise_sdk/v2/client.py | 38 +++---- src/readwise_sdk/v3/async_client.py | 17 ++-- src/readwise_sdk/v3/client.py | 18 ++-- 10 files changed, 333 insertions(+), 160 deletions(-) create mode 100644 src/readwise_sdk/config.py create mode 100644 src/readwise_sdk/errors.py diff --git a/src/readwise_sdk/__init__.py b/src/readwise_sdk/__init__.py index dd44d9f..e33c773 100644 --- a/src/readwise_sdk/__init__.py +++ b/src/readwise_sdk/__init__.py @@ -3,7 +3,7 @@ from importlib.metadata import version from readwise_sdk.client import AsyncReadwiseClient, ReadwiseClient -from readwise_sdk.exceptions import ( +from readwise_sdk.errors import ( AuthenticationError, NotFoundError, RateLimitError, diff --git a/src/readwise_sdk/_utils.py b/src/readwise_sdk/_utils.py index 341e648..5c265ae 100644 --- a/src/readwise_sdk/_utils.py +++ b/src/readwise_sdk/_utils.py @@ -11,7 +11,7 @@ import httpx -from readwise_sdk.exceptions import ( +from readwise_sdk.errors import ( AuthenticationError, NotFoundError, RateLimitError, diff --git a/src/readwise_sdk/client.py b/src/readwise_sdk/client.py index ea4b9b7..b0cf4a2 100644 --- a/src/readwise_sdk/client.py +++ b/src/readwise_sdk/client.py @@ -2,14 +2,27 @@ from __future__ import annotations -import os -from importlib.metadata import version +from dataclasses import replace from typing import TYPE_CHECKING, Any import httpx from readwise_sdk._utils import handle_response, parse_pagination_cursor -from readwise_sdk.exceptions import AuthenticationError, RateLimitError, ReadwiseError +from readwise_sdk.config import ( + DEFAULT_MAX_RETRIES, + DEFAULT_RETRY_BACKOFF, + DEFAULT_TIMEOUT, + DEFAULT_USER_AGENT, + ClientConfig, + resolve_api_key, +) +from readwise_sdk.config import ( + READWISE_API_V2_BASE as CONFIG_READWISE_API_V2_BASE, +) +from readwise_sdk.config import ( + READWISE_API_V3_BASE as CONFIG_READWISE_API_V3_BASE, +) +from readwise_sdk.errors import AuthenticationError, RateLimitError, ReadwiseError if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator @@ -19,17 +32,10 @@ from readwise_sdk.v3.async_client import AsyncReadwiseV3Client from readwise_sdk.v3.client import ReadwiseV3Client -# API base URLs -READWISE_API_V2_BASE = "https://readwise.io/api/v2" -READWISE_API_V3_BASE = "https://readwise.io/api/v3" - -# Default configuration -DEFAULT_TIMEOUT = 30.0 -DEFAULT_MAX_RETRIES = 3 -DEFAULT_RETRY_BACKOFF = 0.5 - -# User agent string with dynamic version -_USER_AGENT = f"readwise-plus/{version('readwise-plus')}" +# Compatibility alias for the previous module-level user agent. +_USER_AGENT = DEFAULT_USER_AGENT +READWISE_API_V2_BASE = CONFIG_READWISE_API_V2_BASE +READWISE_API_V3_BASE = CONFIG_READWISE_API_V3_BASE class BaseClient: @@ -53,18 +59,62 @@ def __init__( retry_backoff: Base backoff time between retries (exponential). _defer_validation: Internal flag used by create_optional(). Do not use directly. """ - self.api_key = api_key or os.environ.get("READWISE_API_KEY") - if not self.api_key and not _defer_validation: + resolved_api_key = resolve_api_key(api_key) + if not resolved_api_key and not _defer_validation: raise AuthenticationError( "API key is required. Set READWISE_API_KEY or pass api_key parameter." ) - self.timeout = timeout - self.max_retries = max_retries - self.retry_backoff = retry_backoff + self._config = ClientConfig( + api_key=resolved_api_key, + timeout=timeout, + max_retries=max_retries, + retry_backoff=retry_backoff, + ) self._client: httpx.Client | None = None + @property + def config(self) -> ClientConfig: + """Return the immutable canonical client configuration.""" + return self._config + + @property + def api_key(self) -> str | None: + """Return the configured API key.""" + return self._config.api_key + + @api_key.setter + def api_key(self, value: str | None) -> None: + self._config = replace(self._config, api_key=value) + + @property + def timeout(self) -> float: + """Return the request timeout in seconds.""" + return self._config.timeout + + @timeout.setter + def timeout(self, value: float) -> None: + self._config = replace(self._config, timeout=value) + + @property + def max_retries(self) -> int: + """Return the maximum number of request retries.""" + return self._config.max_retries + + @max_retries.setter + def max_retries(self, value: int) -> None: + self._config = replace(self._config, max_retries=value) + + @property + def retry_backoff(self) -> float: + """Return the base exponential retry backoff in seconds.""" + return self._config.retry_backoff + + @retry_backoff.setter + def retry_backoff(self, value: float) -> None: + self._config = replace(self._config, retry_backoff=value) + @property def is_configured(self) -> bool: """Check whether the client has an API key configured. @@ -83,7 +133,7 @@ def client(self) -> httpx.Client: headers={ "Authorization": f"Token {self.api_key}", "Content-Type": "application/json", - "User-Agent": _USER_AGENT, + "User-Agent": self.config.user_agent, }, ) return self._client @@ -237,7 +287,7 @@ def validate_token(self) -> bool: True if the token is valid, False otherwise. """ try: - response = self.get(f"{READWISE_API_V2_BASE}/auth/") + response = self.get(f"{self.config.v2_base_url}/auth/") return response.status_code == 204 except AuthenticationError: return False @@ -312,20 +362,64 @@ def __init__( retry_backoff: Base backoff time between retries (exponential). _defer_validation: Internal flag used by create_optional(). Do not use directly. """ - self.api_key = api_key or os.environ.get("READWISE_API_KEY") - if not self.api_key and not _defer_validation: + resolved_api_key = resolve_api_key(api_key) + if not resolved_api_key and not _defer_validation: raise AuthenticationError( "API key is required. Set READWISE_API_KEY or pass api_key parameter." ) - self.timeout = timeout - self.max_retries = max_retries - self.retry_backoff = retry_backoff + self._config = ClientConfig( + api_key=resolved_api_key, + timeout=timeout, + max_retries=max_retries, + retry_backoff=retry_backoff, + ) self._client: httpx.AsyncClient | None = None self._v2: AsyncReadwiseV2Client | None = None self._v3: AsyncReadwiseV3Client | None = None + @property + def config(self) -> ClientConfig: + """Return the immutable canonical client configuration.""" + return self._config + + @property + def api_key(self) -> str | None: + """Return the configured API key.""" + return self._config.api_key + + @api_key.setter + def api_key(self, value: str | None) -> None: + self._config = replace(self._config, api_key=value) + + @property + def timeout(self) -> float: + """Return the request timeout in seconds.""" + return self._config.timeout + + @timeout.setter + def timeout(self, value: float) -> None: + self._config = replace(self._config, timeout=value) + + @property + def max_retries(self) -> int: + """Return the maximum number of request retries.""" + return self._config.max_retries + + @max_retries.setter + def max_retries(self, value: int) -> None: + self._config = replace(self._config, max_retries=value) + + @property + def retry_backoff(self) -> float: + """Return the base exponential retry backoff in seconds.""" + return self._config.retry_backoff + + @retry_backoff.setter + def retry_backoff(self, value: float) -> None: + self._config = replace(self._config, retry_backoff=value) + @property def is_configured(self) -> bool: """Check whether the client has an API key configured. @@ -386,7 +480,7 @@ def client(self) -> httpx.AsyncClient: headers={ "Authorization": f"Token {self.api_key}", "Content-Type": "application/json", - "User-Agent": _USER_AGENT, + "User-Agent": self.config.user_agent, }, ) return self._client @@ -479,7 +573,7 @@ async def validate_token(self) -> bool: True if the token is valid, False otherwise. """ try: - response = await self.get(f"{READWISE_API_V2_BASE}/auth/") + response = await self.get(f"{self.config.v2_base_url}/auth/") return response.status_code == 204 except AuthenticationError: return False diff --git a/src/readwise_sdk/config.py b/src/readwise_sdk/config.py new file mode 100644 index 0000000..2365caa --- /dev/null +++ b/src/readwise_sdk/config.py @@ -0,0 +1,44 @@ +"""Canonical client configuration for the Readwise SDK.""" + +from __future__ import annotations + +import os +from dataclasses import dataclass +from importlib.metadata import version + +READWISE_API_V2_BASE = "https://readwise.io/api/v2" +READWISE_API_V3_BASE = "https://readwise.io/api/v3" + +DEFAULT_TIMEOUT = 30.0 +DEFAULT_MAX_RETRIES = 3 +DEFAULT_RETRY_BACKOFF = 0.5 +DEFAULT_USER_AGENT = f"readwise-plus/{version('readwise-plus')}" + + +@dataclass(frozen=True, slots=True) +class ClientConfig: + """Immutable settings shared by synchronous and asynchronous clients.""" + + api_key: str | None = None + timeout: float = DEFAULT_TIMEOUT + max_retries: int = DEFAULT_MAX_RETRIES + retry_backoff: float = DEFAULT_RETRY_BACKOFF + user_agent: str = DEFAULT_USER_AGENT + v2_base_url: str = READWISE_API_V2_BASE + v3_base_url: str = READWISE_API_V3_BASE + + +def resolve_api_key(api_key: str | None) -> str | None: + """Resolve an explicit API key with the existing environment fallback.""" + return api_key or os.environ.get("READWISE_API_KEY") + + +__all__ = [ + "ClientConfig", + "DEFAULT_MAX_RETRIES", + "DEFAULT_RETRY_BACKOFF", + "DEFAULT_TIMEOUT", + "DEFAULT_USER_AGENT", + "READWISE_API_V2_BASE", + "READWISE_API_V3_BASE", +] diff --git a/src/readwise_sdk/errors.py b/src/readwise_sdk/errors.py new file mode 100644 index 0000000..8eb243a --- /dev/null +++ b/src/readwise_sdk/errors.py @@ -0,0 +1,86 @@ +"""Canonical exception hierarchy for the Readwise SDK.""" + +from __future__ import annotations + + +class ReadwiseError(Exception): + """Base exception for all Readwise SDK errors.""" + + def __init__( + self, message: str, status_code: int | None = None, response_body: str | None = None + ) -> None: + super().__init__(message) + self.message = message + self.status_code = status_code + self.response_body = response_body + + def __str__(self) -> str: + if self.status_code: + return f"[{self.status_code}] {self.message}" + return self.message + + +class AuthenticationError(ReadwiseError): + """Raised when authentication fails (401 Unauthorized).""" + + def __init__( + self, message: str = "Invalid or missing API token", response_body: str | None = None + ) -> None: + super().__init__(message, status_code=401, response_body=response_body) + + +class RateLimitError(ReadwiseError): + """Raised when rate limit is exceeded (429 Too Many Requests).""" + + def __init__( + self, + message: str = "Rate limit exceeded", + retry_after: int | None = None, + response_body: str | None = None, + ) -> None: + super().__init__(message, status_code=429, response_body=response_body) + self.retry_after = retry_after + + def __str__(self) -> str: + base = super().__str__() + if self.retry_after: + return f"{base} (retry after {self.retry_after}s)" + return base + + +class NotFoundError(ReadwiseError): + """Raised when a requested resource is not found (404 Not Found).""" + + def __init__( + self, message: str = "Resource not found", response_body: str | None = None + ) -> None: + super().__init__(message, status_code=404, response_body=response_body) + + +class ValidationError(ReadwiseError): + """Raised when request validation fails (400 Bad Request).""" + + def __init__(self, message: str = "Validation error", response_body: str | None = None) -> None: + super().__init__(message, status_code=400, response_body=response_body) + + +class ServerError(ReadwiseError): + """Raised when the server returns an error (5xx).""" + + def __init__( + self, + message: str = "Server error", + status_code: int = 500, + response_body: str | None = None, + ) -> None: + super().__init__(message, status_code=status_code, response_body=response_body) + + +__all__ = [ + "AuthenticationError", + "NotFoundError", + "RateLimitError", + "ReadwiseError", + "ServerError", + "ValidationError", +] diff --git a/src/readwise_sdk/exceptions.py b/src/readwise_sdk/exceptions.py index 94447f9..af8110b 100644 --- a/src/readwise_sdk/exceptions.py +++ b/src/readwise_sdk/exceptions.py @@ -1,76 +1,19 @@ -"""Exception hierarchy for the Readwise SDK.""" - -from __future__ import annotations - - -class ReadwiseError(Exception): - """Base exception for all Readwise SDK errors.""" - - def __init__( - self, message: str, status_code: int | None = None, response_body: str | None = None - ) -> None: - super().__init__(message) - self.message = message - self.status_code = status_code - self.response_body = response_body - - def __str__(self) -> str: - if self.status_code: - return f"[{self.status_code}] {self.message}" - return self.message - - -class AuthenticationError(ReadwiseError): - """Raised when authentication fails (401 Unauthorized).""" - - def __init__( - self, message: str = "Invalid or missing API token", response_body: str | None = None - ) -> None: - super().__init__(message, status_code=401, response_body=response_body) - - -class RateLimitError(ReadwiseError): - """Raised when rate limit is exceeded (429 Too Many Requests).""" - - def __init__( - self, - message: str = "Rate limit exceeded", - retry_after: int | None = None, - response_body: str | None = None, - ) -> None: - super().__init__(message, status_code=429, response_body=response_body) - self.retry_after = retry_after - - def __str__(self) -> str: - base = super().__str__() - if self.retry_after: - return f"{base} (retry after {self.retry_after}s)" - return base - - -class NotFoundError(ReadwiseError): - """Raised when a requested resource is not found (404 Not Found).""" - - def __init__( - self, message: str = "Resource not found", response_body: str | None = None - ) -> None: - super().__init__(message, status_code=404, response_body=response_body) - - -class ValidationError(ReadwiseError): - """Raised when request validation fails (400 Bad Request).""" - - def __init__(self, message: str = "Validation error", response_body: str | None = None) -> None: - super().__init__(message, status_code=400, response_body=response_body) - - -class ServerError(ReadwiseError): - """Raised when the server returns an error (5xx).""" - - def __init__( - self, - message: str = "Server error", - status_code: int = 500, - response_body: str | None = None, - ) -> None: - super().__init__(message, status_code=status_code, response_body=response_body) +"""Compatibility re-exports for the canonical Readwise SDK errors.""" + +from readwise_sdk.errors import ( + AuthenticationError, + NotFoundError, + RateLimitError, + ReadwiseError, + ServerError, + ValidationError, +) + +__all__ = [ + "AuthenticationError", + "NotFoundError", + "RateLimitError", + "ReadwiseError", + "ServerError", + "ValidationError", +] diff --git a/src/readwise_sdk/v2/async_client.py b/src/readwise_sdk/v2/async_client.py index cee3466..da23826 100644 --- a/src/readwise_sdk/v2/async_client.py +++ b/src/readwise_sdk/v2/async_client.py @@ -5,7 +5,6 @@ from datetime import datetime from typing import TYPE_CHECKING, Any -from readwise_sdk.client import READWISE_API_V2_BASE from readwise_sdk.v2.models import ( Book, BookCategory, @@ -92,7 +91,7 @@ async def list_highlights( params["highlighted_at__lt"] = highlighted_before.isoformat() async for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/highlights/", + f"{self._client.config.v2_base_url}/highlights/", params=params, ): yield Highlight.model_validate(item) @@ -109,7 +108,9 @@ async def get_highlight(self, highlight_id: int) -> Highlight: Raises: NotFoundError: If the highlight doesn't exist. """ - response = await self._client.get(f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/") + response = await self._client.get( + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/" + ) return Highlight.model_validate(response.json()) async def create_highlights(self, highlights: list[HighlightCreate]) -> list[int]: @@ -122,7 +123,9 @@ async def create_highlights(self, highlights: list[HighlightCreate]) -> list[int List of created highlight IDs (from modified_highlights). """ payload = {"highlights": [h.to_api_dict() for h in highlights]} - response = await self._client.post(f"{READWISE_API_V2_BASE}/highlights/", json=payload) + response = await self._client.post( + f"{self._client.config.v2_base_url}/highlights/", json=payload + ) data = response.json() # Extract modified highlight IDs from response @@ -147,7 +150,7 @@ async def update_highlight(self, highlight_id: int, update: HighlightUpdate) -> NotFoundError: If the highlight doesn't exist. """ response = await self._client.patch( - f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/", + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/", json=update.to_api_dict(), ) return Highlight.model_validate(response.json()) @@ -161,7 +164,7 @@ async def delete_highlight(self, highlight_id: int) -> None: Raises: NotFoundError: If the highlight doesn't exist. """ - await self._client.delete(f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/") + await self._client.delete(f"{self._client.config.v2_base_url}/highlights/{highlight_id}/") # ==================== Books ==================== @@ -206,7 +209,7 @@ async def list_books( params["last_highlight_at__lt"] = last_highlight_before.isoformat() async for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/books/", + f"{self._client.config.v2_base_url}/books/", params=params, ): yield Book.model_validate(item) @@ -223,7 +226,7 @@ async def get_book(self, book_id: int) -> Book: Raises: NotFoundError: If the book doesn't exist. """ - response = await self._client.get(f"{READWISE_API_V2_BASE}/books/{book_id}/") + response = await self._client.get(f"{self._client.config.v2_base_url}/books/{book_id}/") return Book.model_validate(response.json()) # ==================== Highlight Tags ==================== @@ -241,7 +244,7 @@ async def list_highlight_tags(self, highlight_id: int) -> AsyncIterator[Tag]: NotFoundError: If the highlight doesn't exist. """ async for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/tags/", + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/", ): yield Tag.model_validate(item) @@ -259,7 +262,7 @@ async def create_highlight_tag(self, highlight_id: int, name: str) -> Tag: NotFoundError: If the highlight doesn't exist. """ response = await self._client.post( - f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/tags/", + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/", json={"name": name[:127]}, ) return Tag.model_validate(response.json()) @@ -279,7 +282,7 @@ async def update_highlight_tag(self, highlight_id: int, tag_id: int, name: str) NotFoundError: If the highlight or tag doesn't exist. """ response = await self._client.patch( - f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/tags/{tag_id}/", + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/{tag_id}/", json={"name": name[:127]}, ) return Tag.model_validate(response.json()) @@ -295,7 +298,7 @@ async def delete_highlight_tag(self, highlight_id: int, tag_id: int) -> None: NotFoundError: If the highlight or tag doesn't exist. """ await self._client.delete( - f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/tags/{tag_id}/" + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/{tag_id}/" ) # ==================== Book Tags ==================== @@ -313,7 +316,7 @@ async def list_book_tags(self, book_id: int) -> AsyncIterator[Tag]: NotFoundError: If the book doesn't exist. """ async for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/books/{book_id}/tags/", + f"{self._client.config.v2_base_url}/books/{book_id}/tags/", ): yield Tag.model_validate(item) @@ -331,7 +334,7 @@ async def create_book_tag(self, book_id: int, name: str) -> Tag: NotFoundError: If the book doesn't exist. """ response = await self._client.post( - f"{READWISE_API_V2_BASE}/books/{book_id}/tags/", + f"{self._client.config.v2_base_url}/books/{book_id}/tags/", json={"name": name[:512]}, ) return Tag.model_validate(response.json()) @@ -351,7 +354,7 @@ async def update_book_tag(self, book_id: int, tag_id: int, name: str) -> Tag: NotFoundError: If the book or tag doesn't exist. """ response = await self._client.patch( - f"{READWISE_API_V2_BASE}/books/{book_id}/tags/{tag_id}/", + f"{self._client.config.v2_base_url}/books/{book_id}/tags/{tag_id}/", json={"name": name[:512]}, ) return Tag.model_validate(response.json()) @@ -366,7 +369,9 @@ async def delete_book_tag(self, book_id: int, tag_id: int) -> None: Raises: NotFoundError: If the book or tag doesn't exist. """ - await self._client.delete(f"{READWISE_API_V2_BASE}/books/{book_id}/tags/{tag_id}/") + await self._client.delete( + f"{self._client.config.v2_base_url}/books/{book_id}/tags/{tag_id}/" + ) # ==================== Export ==================== @@ -400,7 +405,7 @@ async def export_highlights( params["includeDeleted"] = "true" async for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/export/", + f"{self._client.config.v2_base_url}/export/", params=params, cursor_key="nextPageCursor", ): @@ -414,5 +419,5 @@ async def get_daily_review(self) -> DailyReview: Returns: The DailyReview object with selected highlights. """ - response = await self._client.get(f"{READWISE_API_V2_BASE}/review/") + response = await self._client.get(f"{self._client.config.v2_base_url}/review/") return DailyReview.model_validate(response.json()) diff --git a/src/readwise_sdk/v2/client.py b/src/readwise_sdk/v2/client.py index 1ec7a06..06ddffb 100644 --- a/src/readwise_sdk/v2/client.py +++ b/src/readwise_sdk/v2/client.py @@ -5,7 +5,7 @@ from datetime import datetime from typing import TYPE_CHECKING, Any -from readwise_sdk.client import READWISE_API_V2_BASE, ReadwiseClient +from readwise_sdk.client import ReadwiseClient from readwise_sdk.v2.models import ( Book, BookCategory, @@ -71,7 +71,7 @@ def list_highlights( params["highlighted_at__lt"] = highlighted_before.isoformat() for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/highlights/", + f"{self._client.config.v2_base_url}/highlights/", params=params, ): yield Highlight.model_validate(item) @@ -88,7 +88,7 @@ def get_highlight(self, highlight_id: int) -> Highlight: Raises: NotFoundError: If the highlight doesn't exist. """ - response = self._client.get(f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/") + response = self._client.get(f"{self._client.config.v2_base_url}/highlights/{highlight_id}/") return Highlight.model_validate(response.json()) def create_highlights(self, highlights: list[HighlightCreate]) -> list[int]: @@ -101,7 +101,7 @@ def create_highlights(self, highlights: list[HighlightCreate]) -> list[int]: List of created highlight IDs (from modified_highlights). """ payload = {"highlights": [h.to_api_dict() for h in highlights]} - response = self._client.post(f"{READWISE_API_V2_BASE}/highlights/", json=payload) + response = self._client.post(f"{self._client.config.v2_base_url}/highlights/", json=payload) data = response.json() # Extract modified highlight IDs from response @@ -126,7 +126,7 @@ def update_highlight(self, highlight_id: int, update: HighlightUpdate) -> Highli NotFoundError: If the highlight doesn't exist. """ response = self._client.patch( - f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/", + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/", json=update.to_api_dict(), ) return Highlight.model_validate(response.json()) @@ -140,7 +140,7 @@ def delete_highlight(self, highlight_id: int) -> None: Raises: NotFoundError: If the highlight doesn't exist. """ - self._client.delete(f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/") + self._client.delete(f"{self._client.config.v2_base_url}/highlights/{highlight_id}/") # ==================== Books ==================== @@ -185,7 +185,7 @@ def list_books( params["last_highlight_at__lt"] = last_highlight_before.isoformat() for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/books/", + f"{self._client.config.v2_base_url}/books/", params=params, ): yield Book.model_validate(item) @@ -202,7 +202,7 @@ def get_book(self, book_id: int) -> Book: Raises: NotFoundError: If the book doesn't exist. """ - response = self._client.get(f"{READWISE_API_V2_BASE}/books/{book_id}/") + response = self._client.get(f"{self._client.config.v2_base_url}/books/{book_id}/") return Book.model_validate(response.json()) # ==================== Highlight Tags ==================== @@ -220,7 +220,7 @@ def list_highlight_tags(self, highlight_id: int) -> Iterator[Tag]: NotFoundError: If the highlight doesn't exist. """ for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/tags/", + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/", ): yield Tag.model_validate(item) @@ -238,7 +238,7 @@ def create_highlight_tag(self, highlight_id: int, name: str) -> Tag: NotFoundError: If the highlight doesn't exist. """ response = self._client.post( - f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/tags/", + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/", json={"name": name[:127]}, ) return Tag.model_validate(response.json()) @@ -258,7 +258,7 @@ def update_highlight_tag(self, highlight_id: int, tag_id: int, name: str) -> Tag NotFoundError: If the highlight or tag doesn't exist. """ response = self._client.patch( - f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/tags/{tag_id}/", + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/{tag_id}/", json={"name": name[:127]}, ) return Tag.model_validate(response.json()) @@ -273,7 +273,9 @@ def delete_highlight_tag(self, highlight_id: int, tag_id: int) -> None: Raises: NotFoundError: If the highlight or tag doesn't exist. """ - self._client.delete(f"{READWISE_API_V2_BASE}/highlights/{highlight_id}/tags/{tag_id}/") + self._client.delete( + f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/{tag_id}/" + ) # ==================== Book Tags ==================== @@ -290,7 +292,7 @@ def list_book_tags(self, book_id: int) -> Iterator[Tag]: NotFoundError: If the book doesn't exist. """ for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/books/{book_id}/tags/", + f"{self._client.config.v2_base_url}/books/{book_id}/tags/", ): yield Tag.model_validate(item) @@ -308,7 +310,7 @@ def create_book_tag(self, book_id: int, name: str) -> Tag: NotFoundError: If the book doesn't exist. """ response = self._client.post( - f"{READWISE_API_V2_BASE}/books/{book_id}/tags/", + f"{self._client.config.v2_base_url}/books/{book_id}/tags/", json={"name": name[:512]}, ) return Tag.model_validate(response.json()) @@ -328,7 +330,7 @@ def update_book_tag(self, book_id: int, tag_id: int, name: str) -> Tag: NotFoundError: If the book or tag doesn't exist. """ response = self._client.patch( - f"{READWISE_API_V2_BASE}/books/{book_id}/tags/{tag_id}/", + f"{self._client.config.v2_base_url}/books/{book_id}/tags/{tag_id}/", json={"name": name[:512]}, ) return Tag.model_validate(response.json()) @@ -343,7 +345,7 @@ def delete_book_tag(self, book_id: int, tag_id: int) -> None: Raises: NotFoundError: If the book or tag doesn't exist. """ - self._client.delete(f"{READWISE_API_V2_BASE}/books/{book_id}/tags/{tag_id}/") + self._client.delete(f"{self._client.config.v2_base_url}/books/{book_id}/tags/{tag_id}/") # ==================== Export ==================== @@ -377,7 +379,7 @@ def export_highlights( params["includeDeleted"] = "true" for item in self._client.paginate( - f"{READWISE_API_V2_BASE}/export/", + f"{self._client.config.v2_base_url}/export/", params=params, cursor_key="nextPageCursor", ): @@ -391,5 +393,5 @@ def get_daily_review(self) -> DailyReview: Returns: The DailyReview object with selected highlights. """ - response = self._client.get(f"{READWISE_API_V2_BASE}/review/") + response = self._client.get(f"{self._client.config.v2_base_url}/review/") return DailyReview.model_validate(response.json()) diff --git a/src/readwise_sdk/v3/async_client.py b/src/readwise_sdk/v3/async_client.py index 0f8dece..e647d46 100644 --- a/src/readwise_sdk/v3/async_client.py +++ b/src/readwise_sdk/v3/async_client.py @@ -5,7 +5,6 @@ from datetime import datetime from typing import TYPE_CHECKING, Any -from readwise_sdk.client import READWISE_API_V3_BASE from readwise_sdk.v3.models import ( CreateDocumentResult, Document, @@ -90,7 +89,7 @@ async def list_documents( params["withHtmlContent"] = "true" async for item in self._client.paginate( - f"{READWISE_API_V3_BASE}/list/", + f"{self._client.config.v3_base_url}/list/", params=params, cursor_key="nextPageCursor", ): @@ -112,7 +111,7 @@ async def get_document( if with_content: params["withHtmlContent"] = "true" - response = await self._client.get(f"{READWISE_API_V3_BASE}/list/", params=params) + response = await self._client.get(f"{self._client.config.v3_base_url}/list/", params=params) data = response.json() results = data.get("results", []) @@ -130,7 +129,7 @@ async def create_document(self, document: DocumentCreate) -> CreateDocumentResul CreateDocumentResult with id and url. """ response = await self._client.post( - f"{READWISE_API_V3_BASE}/save/", + f"{self._client.config.v3_base_url}/save/", json=document.to_api_dict(), ) return CreateDocumentResult.model_validate(response.json()) @@ -178,7 +177,7 @@ async def update_document( NotFoundError: If the document doesn't exist. """ response = await self._client.patch( - f"{READWISE_API_V3_BASE}/update/{document_id}/", + f"{self._client.config.v3_base_url}/update/{document_id}/", json=update.to_api_dict(), ) return CreateDocumentResult.model_validate(response.json()) @@ -192,7 +191,7 @@ async def delete_document(self, document_id: str) -> None: Raises: NotFoundError: If the document doesn't exist. """ - await self._client.delete(f"{READWISE_API_V3_BASE}/delete/{document_id}/") + await self._client.delete(f"{self._client.config.v3_base_url}/delete/{document_id}/") async def move_to_later(self, document_id: str) -> CreateDocumentResult: """Move a document to the reading list (later). @@ -239,7 +238,7 @@ async def list_tags(self) -> AsyncIterator[DocumentTag]: DocumentTag objects with key and name. """ async for item in self._client.paginate( - f"{READWISE_API_V3_BASE}/tags/", + f"{self._client.config.v3_base_url}/tags/", cursor_key="nextPageCursor", ): yield DocumentTag.model_validate(item) @@ -272,7 +271,7 @@ async def add_tag(self, document_id: str, tag: str) -> CreateDocumentResult: # First get the document to see existing tags doc = await self.get_document(document_id) if doc is None: - from readwise_sdk.exceptions import NotFoundError + from readwise_sdk.errors import NotFoundError raise NotFoundError(f"Document {document_id} not found") @@ -294,7 +293,7 @@ async def remove_tag(self, document_id: str, tag: str) -> CreateDocumentResult: """ doc = await self.get_document(document_id) if doc is None: - from readwise_sdk.exceptions import NotFoundError + from readwise_sdk.errors import NotFoundError raise NotFoundError(f"Document {document_id} not found") diff --git a/src/readwise_sdk/v3/client.py b/src/readwise_sdk/v3/client.py index aaf08a6..cf162ef 100644 --- a/src/readwise_sdk/v3/client.py +++ b/src/readwise_sdk/v3/client.py @@ -5,7 +5,7 @@ from datetime import datetime from typing import TYPE_CHECKING, Any -from readwise_sdk.client import READWISE_API_V3_BASE, ReadwiseClient +from readwise_sdk.client import ReadwiseClient from readwise_sdk.v3.models import ( CreateDocumentResult, Document, @@ -69,7 +69,7 @@ def list_documents( params["withHtmlContent"] = "true" for item in self._client.paginate( - f"{READWISE_API_V3_BASE}/list/", + f"{self._client.config.v3_base_url}/list/", params=params, cursor_key="nextPageCursor", ): @@ -89,7 +89,7 @@ def get_document(self, document_id: str, *, with_content: bool = False) -> Docum if with_content: params["withHtmlContent"] = "true" - response = self._client.get(f"{READWISE_API_V3_BASE}/list/", params=params) + response = self._client.get(f"{self._client.config.v3_base_url}/list/", params=params) data = response.json() results = data.get("results", []) @@ -107,7 +107,7 @@ def create_document(self, document: DocumentCreate) -> CreateDocumentResult: CreateDocumentResult with id and url. """ response = self._client.post( - f"{READWISE_API_V3_BASE}/save/", + f"{self._client.config.v3_base_url}/save/", json=document.to_api_dict(), ) return CreateDocumentResult.model_validate(response.json()) @@ -153,7 +153,7 @@ def update_document(self, document_id: str, update: DocumentUpdate) -> CreateDoc NotFoundError: If the document doesn't exist. """ response = self._client.patch( - f"{READWISE_API_V3_BASE}/update/{document_id}/", + f"{self._client.config.v3_base_url}/update/{document_id}/", json=update.to_api_dict(), ) return CreateDocumentResult.model_validate(response.json()) @@ -167,7 +167,7 @@ def delete_document(self, document_id: str) -> None: Raises: NotFoundError: If the document doesn't exist. """ - self._client.delete(f"{READWISE_API_V3_BASE}/delete/{document_id}/") + self._client.delete(f"{self._client.config.v3_base_url}/delete/{document_id}/") def move_to_later(self, document_id: str) -> CreateDocumentResult: """Move a document to the reading list (later). @@ -214,7 +214,7 @@ def list_tags(self) -> Iterator[DocumentTag]: DocumentTag objects with key and name. """ for item in self._client.paginate( - f"{READWISE_API_V3_BASE}/tags/", + f"{self._client.config.v3_base_url}/tags/", cursor_key="nextPageCursor", ): yield DocumentTag.model_validate(item) @@ -247,7 +247,7 @@ def add_tag(self, document_id: str, tag: str) -> CreateDocumentResult: # First get the document to see existing tags doc = self.get_document(document_id) if doc is None: - from readwise_sdk.exceptions import NotFoundError + from readwise_sdk.errors import NotFoundError raise NotFoundError(f"Document {document_id} not found") @@ -269,7 +269,7 @@ def remove_tag(self, document_id: str, tag: str) -> CreateDocumentResult: """ doc = self.get_document(document_id) if doc is None: - from readwise_sdk.exceptions import NotFoundError + from readwise_sdk.errors import NotFoundError raise NotFoundError(f"Document {document_id} not found") From ec2bc017b336e8be76be9f4021f7376b0ce7c020 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 22:58:46 -0500 Subject: [PATCH 06/24] refactor: extract retry + pagination transport layer (stage 3) Behavior-preserving. Moves retry classification/backoff and the pagination engine out of client.py/_utils.py into transport/{retry,pagination,errors}.py, with endpoint-aware page decoders (standard v2 `next`, v2 export integer cursors, v3 `nextPageCursor`). Retry semantics (max_retries+1 attempts, retry_backoff * 2**attempt, same retryable conditions) and cursor behavior carried over verbatim. ReadwiseClient/AsyncReadwiseClient.paginate() remain compatibility wrappers with unchanged signatures. Characterization + full suite green. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/_utils.py | 87 +----------- src/readwise_sdk/client.py | 80 +++++------ src/readwise_sdk/errors.py | 3 + src/readwise_sdk/transport/__init__.py | 1 + src/readwise_sdk/transport/errors.py | 52 +++++++ src/readwise_sdk/transport/pagination.py | 173 +++++++++++++++++++++++ src/readwise_sdk/transport/retry.py | 42 ++++++ src/readwise_sdk/v2/async_client.py | 6 +- src/readwise_sdk/v2/client.py | 6 +- src/readwise_sdk/v3/async_client.py | 11 +- src/readwise_sdk/v3/client.py | 11 +- 11 files changed, 334 insertions(+), 138 deletions(-) create mode 100644 src/readwise_sdk/transport/__init__.py create mode 100644 src/readwise_sdk/transport/errors.py create mode 100644 src/readwise_sdk/transport/pagination.py create mode 100644 src/readwise_sdk/transport/retry.py diff --git a/src/readwise_sdk/_utils.py b/src/readwise_sdk/_utils.py index 5c265ae..f8c594a 100644 --- a/src/readwise_sdk/_utils.py +++ b/src/readwise_sdk/_utils.py @@ -7,94 +7,13 @@ from datetime import datetime from typing import Any -from urllib.parse import parse_qs, urlparse -import httpx - -from readwise_sdk.errors import ( - AuthenticationError, - NotFoundError, - RateLimitError, - ReadwiseError, - ServerError, - ValidationError, +from readwise_sdk.transport.errors import handle_response as handle_response +from readwise_sdk.transport.pagination import ( + parse_pagination_cursor as parse_pagination_cursor, ) -def handle_response(response: httpx.Response) -> httpx.Response: - """Handle HTTP response and raise appropriate exceptions. - - Args: - response: The HTTP response to handle. - - Returns: - The response if successful. - - Raises: - AuthenticationError: If status is 401. - NotFoundError: If status is 404. - RateLimitError: If status is 429. - ValidationError: If status is 400. - ServerError: If status is 5xx. - ReadwiseError: For other error statuses. - """ - if response.is_success: - return response - - body = response.text - status = response.status_code - - if status == 401: - raise AuthenticationError(response_body=body) - if status == 404: - raise NotFoundError(response_body=body) - if status == 429: - retry_after = response.headers.get("Retry-After") - raise RateLimitError( - retry_after=int(retry_after) if retry_after else None, - response_body=body, - ) - if status == 400: - raise ValidationError(message=f"Validation error: {body}", response_body=body) - if status >= 500: - raise ServerError( - message=f"Server error: {body}", - status_code=status, - response_body=body, - ) - raise ReadwiseError( - message=f"Unexpected error: {body}", - status_code=status, - response_body=body, - ) - - -def parse_pagination_cursor( - next_cursor: str, - current_url: str, - current_params: dict[str, Any], -) -> tuple[str, dict[str, Any]]: - """Parse a pagination cursor, handling both full URLs and cursor strings. - - Args: - next_cursor: The next cursor value (URL or cursor string). - current_url: The current URL being paginated. - current_params: The current query parameters. - - Returns: - Tuple of (url, params) for the next request. - """ - next_cursor = str(next_cursor) # Handle integer cursors from export API - if next_cursor.startswith("http"): - parsed = urlparse(next_cursor) - url = f"{parsed.scheme}://{parsed.netloc}{parsed.path}" - params = {k: v[0] for k, v in parse_qs(parsed.query).items()} - return url, params - params = current_params.copy() - params["pageCursor"] = next_cursor - return current_url, params - - def parse_datetime_string(value: Any) -> datetime | None: """Parse a datetime value from various formats. diff --git a/src/readwise_sdk/client.py b/src/readwise_sdk/client.py index b0cf4a2..8c25a1f 100644 --- a/src/readwise_sdk/client.py +++ b/src/readwise_sdk/client.py @@ -7,7 +7,6 @@ import httpx -from readwise_sdk._utils import handle_response, parse_pagination_cursor from readwise_sdk.config import ( DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF, @@ -23,6 +22,13 @@ READWISE_API_V3_BASE as CONFIG_READWISE_API_V3_BASE, ) from readwise_sdk.errors import AuthenticationError, RateLimitError, ReadwiseError +from readwise_sdk.transport.errors import handle_response +from readwise_sdk.transport.pagination import KeyedPage, paginate, paginate_async +from readwise_sdk.transport.retry import ( + RETRYABLE_NETWORK_EXCEPTIONS, + calculate_retry_delay, + is_retryable_exception, +) if TYPE_CHECKING: from collections.abc import AsyncIterator, Iterator @@ -171,15 +177,18 @@ def _request( try: response = self.client.request(method, url, params=params, json=json) return handle_response(response) - except (httpx.ConnectError, httpx.TimeoutException) as e: + except RETRYABLE_NETWORK_EXCEPTIONS as e: last_error = e - if attempt < self.max_retries: - wait_time = self.retry_backoff * (2**attempt) - time.sleep(wait_time) + if attempt < self.max_retries and is_retryable_exception(e): + wait_time = calculate_retry_delay(e, self.retry_backoff, attempt) + if wait_time is not None: + time.sleep(wait_time) except RateLimitError as e: last_error = e - if attempt < self.max_retries and e.retry_after: - time.sleep(e.retry_after) + if attempt < self.max_retries and is_retryable_exception(e): + wait_time = calculate_retry_delay(e, self.retry_backoff, attempt) + if wait_time is not None: + time.sleep(wait_time) else: raise @@ -310,20 +319,12 @@ def paginate( Yields: Individual result items from each page. """ - params = params.copy() if params else {} - - while True: - response = self.get(url, params=params) - data = response.json() - - results = data.get(results_key, []) - yield from results - - next_cursor = data.get(cursor_key) - if not next_cursor: - break - - url, params = parse_pagination_cursor(next_cursor, url, params) + yield from paginate( + self.get, + url, + params, + decoder=KeyedPage(results_key=results_key, cursor_key=cursor_key), + ) class AsyncReadwiseClient: @@ -536,15 +537,18 @@ async def _request( try: response = await self.client.request(method, url, params=params, json=json) return handle_response(response) - except (httpx.ConnectError, httpx.TimeoutException) as e: + except RETRYABLE_NETWORK_EXCEPTIONS as e: last_error = e - if attempt < self.max_retries: - wait_time = self.retry_backoff * (2**attempt) - await asyncio.sleep(wait_time) + if attempt < self.max_retries and is_retryable_exception(e): + wait_time = calculate_retry_delay(e, self.retry_backoff, attempt) + if wait_time is not None: + await asyncio.sleep(wait_time) except RateLimitError as e: last_error = e - if attempt < self.max_retries and e.retry_after: - await asyncio.sleep(e.retry_after) + if attempt < self.max_retries and is_retryable_exception(e): + wait_time = calculate_retry_delay(e, self.retry_backoff, attempt) + if wait_time is not None: + await asyncio.sleep(wait_time) else: raise @@ -596,18 +600,10 @@ async def paginate( Yields: Individual result items from each page. """ - params = params.copy() if params else {} - - while True: - response = await self.get(url, params=params) - data = response.json() - - results = data.get(results_key, []) - for item in results: - yield item - - next_cursor = data.get(cursor_key) - if not next_cursor: - break - - url, params = parse_pagination_cursor(next_cursor, url, params) + async for item in paginate_async( + self.get, + url, + params, + decoder=KeyedPage(results_key=results_key, cursor_key=cursor_key), + ): + yield item diff --git a/src/readwise_sdk/errors.py b/src/readwise_sdk/errors.py index 8eb243a..13c96ea 100644 --- a/src/readwise_sdk/errors.py +++ b/src/readwise_sdk/errors.py @@ -2,6 +2,8 @@ from __future__ import annotations +from readwise_sdk.transport.errors import handle_response + class ReadwiseError(Exception): """Base exception for all Readwise SDK errors.""" @@ -83,4 +85,5 @@ def __init__( "ReadwiseError", "ServerError", "ValidationError", + "handle_response", ] diff --git a/src/readwise_sdk/transport/__init__.py b/src/readwise_sdk/transport/__init__.py new file mode 100644 index 0000000..fc8dba7 --- /dev/null +++ b/src/readwise_sdk/transport/__init__.py @@ -0,0 +1 @@ +"""Shared HTTP transport infrastructure.""" diff --git a/src/readwise_sdk/transport/errors.py b/src/readwise_sdk/transport/errors.py new file mode 100644 index 0000000..ca8c517 --- /dev/null +++ b/src/readwise_sdk/transport/errors.py @@ -0,0 +1,52 @@ +"""Translate HTTP responses into Readwise SDK exceptions.""" + +from __future__ import annotations + +import httpx + + +def handle_response(response: httpx.Response) -> httpx.Response: + """Return successful responses and map error statuses to SDK exceptions.""" + # Import locally so ``readwise_sdk.errors`` can re-export this compatibility + # helper without creating an import cycle. + from readwise_sdk.errors import ( + AuthenticationError, + NotFoundError, + RateLimitError, + ReadwiseError, + ServerError, + ValidationError, + ) + + if response.is_success: + return response + + body = response.text + status = response.status_code + + if status == 401: + raise AuthenticationError(response_body=body) + if status == 404: + raise NotFoundError(response_body=body) + if status == 429: + retry_after = response.headers.get("Retry-After") + raise RateLimitError( + retry_after=int(retry_after) if retry_after else None, + response_body=body, + ) + if status == 400: + raise ValidationError(message=f"Validation error: {body}", response_body=body) + if status >= 500: + raise ServerError( + message=f"Server error: {body}", + status_code=status, + response_body=body, + ) + raise ReadwiseError( + message=f"Unexpected error: {body}", + status_code=status, + response_body=body, + ) + + +__all__ = ["handle_response"] diff --git a/src/readwise_sdk/transport/pagination.py b/src/readwise_sdk/transport/pagination.py new file mode 100644 index 0000000..ee32cf5 --- /dev/null +++ b/src/readwise_sdk/transport/pagination.py @@ -0,0 +1,173 @@ +"""Shared pagination engines and endpoint-aware page decoders.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator, Awaitable, Iterator +from dataclasses import dataclass +from typing import Any, Protocol +from urllib.parse import parse_qs, urlparse + +import httpx + +type Params = dict[str, Any] + + +class SyncPageGetter(Protocol): + """Callable shape used to fetch one synchronous page.""" + + def __call__(self, url: str, params: Params | None = None) -> httpx.Response: ... + + +class AsyncPageGetter(Protocol): + """Callable shape used to fetch one asynchronous page.""" + + def __call__(self, url: str, params: Params | None = None) -> Awaitable[httpx.Response]: ... + + +@dataclass(frozen=True, slots=True) +class DecodedPage: + """Results and continuation value decoded from one response page.""" + + results: Any + next_cursor: Any + + +class PageDecoder(Protocol): + """Decode one endpoint's results and continuation cursor.""" + + def decode(self, data: Any) -> DecodedPage: ... + + def next_request( + self, + next_cursor: Any, + current_url: str, + current_params: Params, + ) -> tuple[str, Params]: ... + + +@dataclass(frozen=True, slots=True) +class KeyedPage: + """Compatibility decoder for callers supplying response key names.""" + + results_key: str = "results" + cursor_key: str = "next" + + def decode(self, data: Any) -> DecodedPage: + return DecodedPage( + results=data.get(self.results_key, []), + next_cursor=data.get(self.cursor_key), + ) + + def next_request( + self, + next_cursor: Any, + current_url: str, + current_params: Params, + ) -> tuple[str, Params]: + return parse_pagination_cursor(next_cursor, current_url, current_params) + + +class StandardV2Page(KeyedPage): + """Decode standard Readwise v2 pages using the ``next`` URL.""" + + def __init__(self) -> None: + super().__init__(results_key="results", cursor_key="next") + + +class ExportV2Page(KeyedPage): + """Decode Readwise v2 export pages using integer continuation cursors.""" + + def __init__(self) -> None: + super().__init__(results_key="results", cursor_key="nextPageCursor") + + +class ReaderV3Page(KeyedPage): + """Decode Reader v3 pages using string continuation cursors.""" + + def __init__(self) -> None: + super().__init__(results_key="results", cursor_key="nextPageCursor") + + +def parse_pagination_cursor( + next_cursor: Any, + current_url: str, + current_params: Params, +) -> tuple[str, Params]: + """Parse a full next URL or add a scalar cursor to existing parameters.""" + next_cursor = str(next_cursor) # Handle integer cursors from export API + if next_cursor.startswith("http"): + parsed = urlparse(next_cursor) + url = f"{parsed.scheme}://{parsed.netloc}{parsed.path}" + params = {key: values[0] for key, values in parse_qs(parsed.query).items()} + return url, params + params = current_params.copy() + params["pageCursor"] = next_cursor + return current_url, params + + +def paginate( + get_page: SyncPageGetter, + url: str, + params: Params | None = None, + *, + decoder: PageDecoder | None = None, +) -> Iterator[dict[str, Any]]: + """Yield items from every page using a synchronous page getter.""" + current_params = params.copy() if params else {} + page_decoder = decoder or StandardV2Page() + + while True: + response = get_page(url, params=current_params) + page = page_decoder.decode(response.json()) + + yield from page.results + + if not page.next_cursor: + break + + url, current_params = page_decoder.next_request( + page.next_cursor, + url, + current_params, + ) + + +async def paginate_async( + get_page: AsyncPageGetter, + url: str, + params: Params | None = None, + *, + decoder: PageDecoder | None = None, +) -> AsyncIterator[dict[str, Any]]: + """Yield items from every page using an asynchronous page getter.""" + current_params = params.copy() if params else {} + page_decoder = decoder or StandardV2Page() + + while True: + response = await get_page(url, params=current_params) + page = page_decoder.decode(response.json()) + + for item in page.results: + yield item + + if not page.next_cursor: + break + + url, current_params = page_decoder.next_request( + page.next_cursor, + url, + current_params, + ) + + +__all__ = [ + "DecodedPage", + "ExportV2Page", + "KeyedPage", + "PageDecoder", + "ReaderV3Page", + "StandardV2Page", + "paginate", + "paginate_async", + "parse_pagination_cursor", +] diff --git a/src/readwise_sdk/transport/retry.py b/src/readwise_sdk/transport/retry.py new file mode 100644 index 0000000..b3e8c4f --- /dev/null +++ b/src/readwise_sdk/transport/retry.py @@ -0,0 +1,42 @@ +"""Retry classification and delay calculation.""" + +from __future__ import annotations + +import httpx + +from readwise_sdk.errors import RateLimitError + +RETRYABLE_NETWORK_EXCEPTIONS = (httpx.ConnectError, httpx.TimeoutException) + + +def is_retryable_exception(error: BaseException) -> bool: + """Return whether the current client retries ``error`` when attempts remain.""" + if isinstance(error, RETRYABLE_NETWORK_EXCEPTIONS): + return True + return isinstance(error, RateLimitError) and bool(error.retry_after) + + +def calculate_backoff(retry_backoff: float, attempt: int) -> float: + """Calculate the existing exponential delay for a zero-based attempt.""" + return retry_backoff * (2**attempt) + + +def calculate_retry_delay( + error: BaseException, + retry_backoff: float, + attempt: int, +) -> float | int | None: + """Return the existing retry delay for ``error``, or ``None`` if not retried.""" + if isinstance(error, RETRYABLE_NETWORK_EXCEPTIONS): + return calculate_backoff(retry_backoff, attempt) + if isinstance(error, RateLimitError) and error.retry_after: + return error.retry_after + return None + + +__all__ = [ + "RETRYABLE_NETWORK_EXCEPTIONS", + "calculate_backoff", + "calculate_retry_delay", + "is_retryable_exception", +] diff --git a/src/readwise_sdk/v2/async_client.py b/src/readwise_sdk/v2/async_client.py index da23826..c5f4469 100644 --- a/src/readwise_sdk/v2/async_client.py +++ b/src/readwise_sdk/v2/async_client.py @@ -5,6 +5,7 @@ from datetime import datetime from typing import TYPE_CHECKING, Any +from readwise_sdk.transport.pagination import ExportV2Page, paginate_async from readwise_sdk.v2.models import ( Book, BookCategory, @@ -404,10 +405,11 @@ async def export_highlights( if include_deleted: params["includeDeleted"] = "true" - async for item in self._client.paginate( + async for item in paginate_async( + self._client.get, f"{self._client.config.v2_base_url}/export/", params=params, - cursor_key="nextPageCursor", + decoder=ExportV2Page(), ): yield ExportBook.model_validate(item) diff --git a/src/readwise_sdk/v2/client.py b/src/readwise_sdk/v2/client.py index 06ddffb..62357e8 100644 --- a/src/readwise_sdk/v2/client.py +++ b/src/readwise_sdk/v2/client.py @@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Any from readwise_sdk.client import ReadwiseClient +from readwise_sdk.transport.pagination import ExportV2Page, paginate from readwise_sdk.v2.models import ( Book, BookCategory, @@ -378,10 +379,11 @@ def export_highlights( if include_deleted: params["includeDeleted"] = "true" - for item in self._client.paginate( + for item in paginate( + self._client.get, f"{self._client.config.v2_base_url}/export/", params=params, - cursor_key="nextPageCursor", + decoder=ExportV2Page(), ): yield ExportBook.model_validate(item) diff --git a/src/readwise_sdk/v3/async_client.py b/src/readwise_sdk/v3/async_client.py index e647d46..d4ebeab 100644 --- a/src/readwise_sdk/v3/async_client.py +++ b/src/readwise_sdk/v3/async_client.py @@ -5,6 +5,7 @@ from datetime import datetime from typing import TYPE_CHECKING, Any +from readwise_sdk.transport.pagination import ReaderV3Page, paginate_async from readwise_sdk.v3.models import ( CreateDocumentResult, Document, @@ -88,10 +89,11 @@ async def list_documents( if with_content: params["withHtmlContent"] = "true" - async for item in self._client.paginate( + async for item in paginate_async( + self._client.get, f"{self._client.config.v3_base_url}/list/", params=params, - cursor_key="nextPageCursor", + decoder=ReaderV3Page(), ): yield Document.model_validate(item) @@ -237,9 +239,10 @@ async def list_tags(self) -> AsyncIterator[DocumentTag]: Yields: DocumentTag objects with key and name. """ - async for item in self._client.paginate( + async for item in paginate_async( + self._client.get, f"{self._client.config.v3_base_url}/tags/", - cursor_key="nextPageCursor", + decoder=ReaderV3Page(), ): yield DocumentTag.model_validate(item) diff --git a/src/readwise_sdk/v3/client.py b/src/readwise_sdk/v3/client.py index cf162ef..3c0f4ab 100644 --- a/src/readwise_sdk/v3/client.py +++ b/src/readwise_sdk/v3/client.py @@ -6,6 +6,7 @@ from typing import TYPE_CHECKING, Any from readwise_sdk.client import ReadwiseClient +from readwise_sdk.transport.pagination import ReaderV3Page, paginate from readwise_sdk.v3.models import ( CreateDocumentResult, Document, @@ -68,10 +69,11 @@ def list_documents( if with_content: params["withHtmlContent"] = "true" - for item in self._client.paginate( + for item in paginate( + self._client.get, f"{self._client.config.v3_base_url}/list/", params=params, - cursor_key="nextPageCursor", + decoder=ReaderV3Page(), ): yield Document.model_validate(item) @@ -213,9 +215,10 @@ def list_tags(self) -> Iterator[DocumentTag]: Yields: DocumentTag objects with key and name. """ - for item in self._client.paginate( + for item in paginate( + self._client.get, f"{self._client.config.v3_base_url}/tags/", - cursor_key="nextPageCursor", + decoder=ReaderV3Page(), ): yield DocumentTag.model_validate(item) From d3234d45b0f1a702fa6bd6bb21fdd0e917d1f410 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 23:08:26 -0500 Subject: [PATCH 07/24] refactor: async transport + resources layer (stage 4) Behavior-preserving. Adds canonical async transport (transport/async_.py) and a resources/ layer (v2 highlights/books/tags/export/review, v3 documents/tags) that build endpoint requests and decode models with no local search/format/ workflow logic. AsyncReadwiseV2Client/AsyncReadwiseV3Client now delegate to resources with unchanged public methods, signatures, and return types. Sync clients untouched. New tests cover the resources/transport surface; existing characterization suite unchanged. Non-live gate green (605 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/client.py | 57 +-- src/readwise_sdk/resources/__init__.py | 1 + src/readwise_sdk/resources/v2/__init__.py | 15 + src/readwise_sdk/resources/v2/books.py | 61 +++ src/readwise_sdk/resources/v2/export.py | 45 +++ src/readwise_sdk/resources/v2/highlights.py | 83 +++++ src/readwise_sdk/resources/v2/review.py | 20 + src/readwise_sdk/resources/v2/tags.py | 73 ++++ src/readwise_sdk/resources/v3/__init__.py | 6 + src/readwise_sdk/resources/v3/documents.py | 94 +++++ src/readwise_sdk/resources/v3/tags.py | 27 ++ src/readwise_sdk/transport/async_.py | 127 +++++++ src/readwise_sdk/v2/async_client.py | 388 +++----------------- src/readwise_sdk/v3/async_client.py | 263 ++----------- tests/async/test_async_public_surface.py | 89 +++++ tests/resources/__init__.py | 1 + tests/resources/test_async_resources.py | 54 +++ tests/transport/__init__.py | 1 + tests/transport/test_async_transport.py | 38 ++ 19 files changed, 828 insertions(+), 615 deletions(-) create mode 100644 src/readwise_sdk/resources/__init__.py create mode 100644 src/readwise_sdk/resources/v2/__init__.py create mode 100644 src/readwise_sdk/resources/v2/books.py create mode 100644 src/readwise_sdk/resources/v2/export.py create mode 100644 src/readwise_sdk/resources/v2/highlights.py create mode 100644 src/readwise_sdk/resources/v2/review.py create mode 100644 src/readwise_sdk/resources/v2/tags.py create mode 100644 src/readwise_sdk/resources/v3/__init__.py create mode 100644 src/readwise_sdk/resources/v3/documents.py create mode 100644 src/readwise_sdk/resources/v3/tags.py create mode 100644 src/readwise_sdk/transport/async_.py create mode 100644 tests/async/test_async_public_surface.py create mode 100644 tests/resources/__init__.py create mode 100644 tests/resources/test_async_resources.py create mode 100644 tests/transport/__init__.py create mode 100644 tests/transport/test_async_transport.py diff --git a/src/readwise_sdk/client.py b/src/readwise_sdk/client.py index 8c25a1f..040dd01 100644 --- a/src/readwise_sdk/client.py +++ b/src/readwise_sdk/client.py @@ -22,6 +22,7 @@ READWISE_API_V3_BASE as CONFIG_READWISE_API_V3_BASE, ) from readwise_sdk.errors import AuthenticationError, RateLimitError, ReadwiseError +from readwise_sdk.transport.async_ import AsyncTransport from readwise_sdk.transport.errors import handle_response from readwise_sdk.transport.pagination import KeyedPage, paginate, paginate_async from readwise_sdk.transport.retry import ( @@ -376,10 +377,15 @@ def __init__( retry_backoff=retry_backoff, ) - self._client: httpx.AsyncClient | None = None + self._transport = AsyncTransport(self._config) self._v2: AsyncReadwiseV2Client | None = None self._v3: AsyncReadwiseV3Client | None = None + @property + def _client(self) -> httpx.AsyncClient | None: + """Retain the legacy observable reference to the raw HTTP client.""" + return self._transport.raw_client + @property def config(self) -> ClientConfig: """Return the immutable canonical client configuration.""" @@ -393,6 +399,7 @@ def api_key(self) -> str | None: @api_key.setter def api_key(self, value: str | None) -> None: self._config = replace(self._config, api_key=value) + self._transport.config = self._config @property def timeout(self) -> float: @@ -402,6 +409,7 @@ def timeout(self) -> float: @timeout.setter def timeout(self, value: float) -> None: self._config = replace(self._config, timeout=value) + self._transport.config = self._config @property def max_retries(self) -> int: @@ -411,6 +419,7 @@ def max_retries(self) -> int: @max_retries.setter def max_retries(self, value: int) -> None: self._config = replace(self._config, max_retries=value) + self._transport.config = self._config @property def retry_backoff(self) -> float: @@ -420,6 +429,7 @@ def retry_backoff(self) -> float: @retry_backoff.setter def retry_backoff(self, value: float) -> None: self._config = replace(self._config, retry_backoff=value) + self._transport.config = self._config @property def is_configured(self) -> bool: @@ -475,16 +485,7 @@ def create_optional( @property def client(self) -> httpx.AsyncClient: """Lazily initialize and return the async HTTP client.""" - if self._client is None: - self._client = httpx.AsyncClient( - timeout=self.timeout, - headers={ - "Authorization": f"Token {self.api_key}", - "Content-Type": "application/json", - "User-Agent": self.config.user_agent, - }, - ) - return self._client + return self._transport.client @property def v2(self) -> AsyncReadwiseV2Client: @@ -506,9 +507,7 @@ def v3(self) -> AsyncReadwiseV3Client: async def close(self) -> None: """Close the HTTP client.""" - if self._client is not None: - await self._client.aclose() - self._client = None + await self._transport.close() async def __aenter__(self) -> AsyncReadwiseClient: return self @@ -524,35 +523,7 @@ async def _request( json: dict[str, Any] | None = None, ) -> httpx.Response: """Make an async HTTP request with retry logic.""" - if not self.api_key: - raise AuthenticationError( - "API key is required. Set READWISE_API_KEY or pass api_key parameter." - ) - - import asyncio - - last_error: Exception | None = None - - for attempt in range(self.max_retries + 1): - try: - response = await self.client.request(method, url, params=params, json=json) - return handle_response(response) - except RETRYABLE_NETWORK_EXCEPTIONS as e: - last_error = e - if attempt < self.max_retries and is_retryable_exception(e): - wait_time = calculate_retry_delay(e, self.retry_backoff, attempt) - if wait_time is not None: - await asyncio.sleep(wait_time) - except RateLimitError as e: - last_error = e - if attempt < self.max_retries and is_retryable_exception(e): - wait_time = calculate_retry_delay(e, self.retry_backoff, attempt) - if wait_time is not None: - await asyncio.sleep(wait_time) - else: - raise - - raise ReadwiseError(f"Request failed after {self.max_retries + 1} attempts: {last_error}") + return await self._transport.request(method, url, params=params, json=json) async def get(self, url: str, params: dict[str, Any] | None = None) -> httpx.Response: """Make an async GET request.""" diff --git a/src/readwise_sdk/resources/__init__.py b/src/readwise_sdk/resources/__init__.py new file mode 100644 index 0000000..8e2a21d --- /dev/null +++ b/src/readwise_sdk/resources/__init__.py @@ -0,0 +1 @@ +"""Canonical low-level clients for Readwise API resources.""" diff --git a/src/readwise_sdk/resources/v2/__init__.py b/src/readwise_sdk/resources/v2/__init__.py new file mode 100644 index 0000000..0b3b2dc --- /dev/null +++ b/src/readwise_sdk/resources/v2/__init__.py @@ -0,0 +1,15 @@ +"""Asynchronous resources for the Readwise v2 API.""" + +from readwise_sdk.resources.v2.books import AsyncBooksResource +from readwise_sdk.resources.v2.export import AsyncExportResource +from readwise_sdk.resources.v2.highlights import AsyncHighlightsResource +from readwise_sdk.resources.v2.review import AsyncReviewResource +from readwise_sdk.resources.v2.tags import AsyncTagsResource + +__all__ = [ + "AsyncBooksResource", + "AsyncExportResource", + "AsyncHighlightsResource", + "AsyncReviewResource", + "AsyncTagsResource", +] diff --git a/src/readwise_sdk/resources/v2/books.py b/src/readwise_sdk/resources/v2/books.py new file mode 100644 index 0000000..5fbe398 --- /dev/null +++ b/src/readwise_sdk/resources/v2/books.py @@ -0,0 +1,61 @@ +"""Asynchronous access to Readwise v2 book endpoints.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from datetime import datetime +from typing import Any + +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.transport.pagination import StandardV2Page, paginate_async +from readwise_sdk.v2.models import Book, BookCategory + + +class AsyncBooksResource: + """Build book requests and decode book models.""" + + def __init__(self, transport: AsyncTransport) -> None: + self._transport = transport + + async def iter( + self, + *, + page_size: int = 100, + category: BookCategory | None = None, + source: str | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + last_highlight_after: datetime | None = None, + last_highlight_before: datetime | None = None, + ) -> AsyncIterator[Book]: + params: dict[str, Any] = {"page_size": min(page_size, 1000)} + + if category: + params["category"] = category.value + if source: + params["source"] = source + if updated_after: + params["updated__gt"] = updated_after.isoformat() + if updated_before: + params["updated__lt"] = updated_before.isoformat() + if last_highlight_after: + params["last_highlight_at__gt"] = last_highlight_after.isoformat() + if last_highlight_before: + params["last_highlight_at__lt"] = last_highlight_before.isoformat() + + async for item in paginate_async( + self._transport.get, + f"{self._transport.config.v2_base_url}/books/", + params=params, + decoder=StandardV2Page(), + ): + yield Book.model_validate(item) + + async def get(self, book_id: int) -> Book: + response = await self._transport.get( + f"{self._transport.config.v2_base_url}/books/{book_id}/" + ) + return Book.model_validate(response.json()) + + +__all__ = ["AsyncBooksResource"] diff --git a/src/readwise_sdk/resources/v2/export.py b/src/readwise_sdk/resources/v2/export.py new file mode 100644 index 0000000..5ece16f --- /dev/null +++ b/src/readwise_sdk/resources/v2/export.py @@ -0,0 +1,45 @@ +"""Asynchronous access to the Readwise v2 export endpoint.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from datetime import datetime +from typing import Any + +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.transport.pagination import ExportV2Page, paginate_async +from readwise_sdk.v2.models import ExportBook + + +class AsyncExportResource: + """Build export requests and decode nested export books.""" + + def __init__(self, transport: AsyncTransport) -> None: + self._transport = transport + + async def iter( + self, + *, + updated_after: datetime | None = None, + book_ids: list[int] | None = None, + include_deleted: bool = False, + ) -> AsyncIterator[ExportBook]: + params: dict[str, Any] = {} + + if updated_after: + params["updatedAfter"] = updated_after.isoformat() + if book_ids: + params["ids"] = ",".join(str(book_id) for book_id in book_ids) + if include_deleted: + params["includeDeleted"] = "true" + + async for item in paginate_async( + self._transport.get, + f"{self._transport.config.v2_base_url}/export/", + params=params, + decoder=ExportV2Page(), + ): + yield ExportBook.model_validate(item) + + +__all__ = ["AsyncExportResource"] diff --git a/src/readwise_sdk/resources/v2/highlights.py b/src/readwise_sdk/resources/v2/highlights.py new file mode 100644 index 0000000..d1a5c82 --- /dev/null +++ b/src/readwise_sdk/resources/v2/highlights.py @@ -0,0 +1,83 @@ +"""Asynchronous access to Readwise v2 highlight endpoints.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from datetime import datetime +from typing import Any + +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.transport.pagination import StandardV2Page, paginate_async +from readwise_sdk.v2.models import Highlight, HighlightCreate, HighlightUpdate + + +class AsyncHighlightsResource: + """Build highlight requests and decode highlight models.""" + + def __init__(self, transport: AsyncTransport) -> None: + self._transport = transport + + async def iter( + self, + *, + page_size: int = 100, + book_id: int | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + highlighted_after: datetime | None = None, + highlighted_before: datetime | None = None, + ) -> AsyncIterator[Highlight]: + params: dict[str, Any] = {"page_size": min(page_size, 1000)} + + if book_id is not None: + params["book_id"] = book_id + if updated_after: + params["updated__gt"] = updated_after.isoformat() + if updated_before: + params["updated__lt"] = updated_before.isoformat() + if highlighted_after: + params["highlighted_at__gt"] = highlighted_after.isoformat() + if highlighted_before: + params["highlighted_at__lt"] = highlighted_before.isoformat() + + async for item in paginate_async( + self._transport.get, + f"{self._transport.config.v2_base_url}/highlights/", + params=params, + decoder=StandardV2Page(), + ): + yield Highlight.model_validate(item) + + async def get(self, highlight_id: int) -> Highlight: + response = await self._transport.get( + f"{self._transport.config.v2_base_url}/highlights/{highlight_id}/" + ) + return Highlight.model_validate(response.json()) + + async def create(self, highlights: list[HighlightCreate]) -> list[int]: + payload = {"highlights": [highlight.to_api_dict() for highlight in highlights]} + response = await self._transport.post( + f"{self._transport.config.v2_base_url}/highlights/", + json=payload, + ) + + highlight_ids: list[int] = [] + for book_data in response.json(): + modified = book_data.get("modified_highlights", []) + highlight_ids.extend(modified) + return highlight_ids + + async def update(self, highlight_id: int, update: HighlightUpdate) -> Highlight: + response = await self._transport.patch( + f"{self._transport.config.v2_base_url}/highlights/{highlight_id}/", + json=update.to_api_dict(), + ) + return Highlight.model_validate(response.json()) + + async def delete(self, highlight_id: int) -> None: + await self._transport.delete( + f"{self._transport.config.v2_base_url}/highlights/{highlight_id}/" + ) + + +__all__ = ["AsyncHighlightsResource"] diff --git a/src/readwise_sdk/resources/v2/review.py b/src/readwise_sdk/resources/v2/review.py new file mode 100644 index 0000000..0e94e18 --- /dev/null +++ b/src/readwise_sdk/resources/v2/review.py @@ -0,0 +1,20 @@ +"""Asynchronous access to the Readwise v2 daily-review endpoint.""" + +from __future__ import annotations + +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.v2.models import DailyReview + + +class AsyncReviewResource: + """Build the daily-review request and decode its model.""" + + def __init__(self, transport: AsyncTransport) -> None: + self._transport = transport + + async def get(self) -> DailyReview: + response = await self._transport.get(f"{self._transport.config.v2_base_url}/review/") + return DailyReview.model_validate(response.json()) + + +__all__ = ["AsyncReviewResource"] diff --git a/src/readwise_sdk/resources/v2/tags.py b/src/readwise_sdk/resources/v2/tags.py new file mode 100644 index 0000000..3c84d01 --- /dev/null +++ b/src/readwise_sdk/resources/v2/tags.py @@ -0,0 +1,73 @@ +"""Asynchronous access to Readwise v2 tag endpoints.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator + +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.transport.pagination import StandardV2Page, paginate_async +from readwise_sdk.v2.models import Tag + + +class AsyncTagsResource: + """Build highlight/book tag requests and decode tag models.""" + + def __init__(self, transport: AsyncTransport) -> None: + self._transport = transport + + async def iter_highlight(self, highlight_id: int) -> AsyncIterator[Tag]: + async for item in paginate_async( + self._transport.get, + f"{self._transport.config.v2_base_url}/highlights/{highlight_id}/tags/", + decoder=StandardV2Page(), + ): + yield Tag.model_validate(item) + + async def create_highlight(self, highlight_id: int, name: str) -> Tag: + response = await self._transport.post( + f"{self._transport.config.v2_base_url}/highlights/{highlight_id}/tags/", + json={"name": name[:127]}, + ) + return Tag.model_validate(response.json()) + + async def update_highlight(self, highlight_id: int, tag_id: int, name: str) -> Tag: + response = await self._transport.patch( + f"{self._transport.config.v2_base_url}/highlights/{highlight_id}/tags/{tag_id}/", + json={"name": name[:127]}, + ) + return Tag.model_validate(response.json()) + + async def delete_highlight(self, highlight_id: int, tag_id: int) -> None: + await self._transport.delete( + f"{self._transport.config.v2_base_url}/highlights/{highlight_id}/tags/{tag_id}/" + ) + + async def iter_book(self, book_id: int) -> AsyncIterator[Tag]: + async for item in paginate_async( + self._transport.get, + f"{self._transport.config.v2_base_url}/books/{book_id}/tags/", + decoder=StandardV2Page(), + ): + yield Tag.model_validate(item) + + async def create_book(self, book_id: int, name: str) -> Tag: + response = await self._transport.post( + f"{self._transport.config.v2_base_url}/books/{book_id}/tags/", + json={"name": name[:512]}, + ) + return Tag.model_validate(response.json()) + + async def update_book(self, book_id: int, tag_id: int, name: str) -> Tag: + response = await self._transport.patch( + f"{self._transport.config.v2_base_url}/books/{book_id}/tags/{tag_id}/", + json={"name": name[:512]}, + ) + return Tag.model_validate(response.json()) + + async def delete_book(self, book_id: int, tag_id: int) -> None: + await self._transport.delete( + f"{self._transport.config.v2_base_url}/books/{book_id}/tags/{tag_id}/" + ) + + +__all__ = ["AsyncTagsResource"] diff --git a/src/readwise_sdk/resources/v3/__init__.py b/src/readwise_sdk/resources/v3/__init__.py new file mode 100644 index 0000000..e5f7d6e --- /dev/null +++ b/src/readwise_sdk/resources/v3/__init__.py @@ -0,0 +1,6 @@ +"""Asynchronous resources for the Reader v3 API.""" + +from readwise_sdk.resources.v3.documents import AsyncDocumentsResource +from readwise_sdk.resources.v3.tags import AsyncTagsResource + +__all__ = ["AsyncDocumentsResource", "AsyncTagsResource"] diff --git a/src/readwise_sdk/resources/v3/documents.py b/src/readwise_sdk/resources/v3/documents.py new file mode 100644 index 0000000..c0ca685 --- /dev/null +++ b/src/readwise_sdk/resources/v3/documents.py @@ -0,0 +1,94 @@ +"""Asynchronous access to Reader v3 document endpoints.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from datetime import datetime +from typing import Any + +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.transport.pagination import ReaderV3Page, paginate_async +from readwise_sdk.v3.models import ( + CreateDocumentResult, + Document, + DocumentCategory, + DocumentCreate, + DocumentLocation, + DocumentUpdate, +) + + +class AsyncDocumentsResource: + """Build document requests and decode document API models.""" + + def __init__(self, transport: AsyncTransport) -> None: + self._transport = transport + + async def iter( + self, + *, + location: DocumentLocation | None = None, + category: DocumentCategory | None = None, + updated_after: datetime | None = None, + tags: list[str] | None = None, + with_content: bool = False, + ) -> AsyncIterator[Document]: + params: dict[str, Any] = {} + + if location: + params["location"] = location.value + if category: + params["category"] = category.value + if updated_after: + params["updatedAfter"] = updated_after.isoformat() + if tags and len(tags) > 0: + # Characterizes the existing single-tag behavior. + params["tag"] = tags[0] + if with_content: + params["withHtmlContent"] = "true" + + async for item in paginate_async( + self._transport.get, + f"{self._transport.config.v3_base_url}/list/", + params=params, + decoder=ReaderV3Page(), + ): + yield Document.model_validate(item) + + async def get(self, document_id: str, *, with_content: bool = False) -> Document | None: + params: dict[str, Any] = {"id": document_id} + if with_content: + params["withHtmlContent"] = "true" + + response = await self._transport.get( + f"{self._transport.config.v3_base_url}/list/", + params=params, + ) + results = response.json().get("results", []) + if results: + return Document.model_validate(results[0]) + return None + + async def create(self, document: DocumentCreate) -> CreateDocumentResult: + response = await self._transport.post( + f"{self._transport.config.v3_base_url}/save/", + json=document.to_api_dict(), + ) + return CreateDocumentResult.model_validate(response.json()) + + async def update( + self, + document_id: str, + update: DocumentUpdate, + ) -> CreateDocumentResult: + response = await self._transport.patch( + f"{self._transport.config.v3_base_url}/update/{document_id}/", + json=update.to_api_dict(), + ) + return CreateDocumentResult.model_validate(response.json()) + + async def delete(self, document_id: str) -> None: + await self._transport.delete(f"{self._transport.config.v3_base_url}/delete/{document_id}/") + + +__all__ = ["AsyncDocumentsResource"] diff --git a/src/readwise_sdk/resources/v3/tags.py b/src/readwise_sdk/resources/v3/tags.py new file mode 100644 index 0000000..bde022a --- /dev/null +++ b/src/readwise_sdk/resources/v3/tags.py @@ -0,0 +1,27 @@ +"""Asynchronous access to the Reader v3 tags endpoint.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator + +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.transport.pagination import ReaderV3Page, paginate_async +from readwise_sdk.v3.models import DocumentTag + + +class AsyncTagsResource: + """Build Reader tag requests and decode tag models.""" + + def __init__(self, transport: AsyncTransport) -> None: + self._transport = transport + + async def iter(self) -> AsyncIterator[DocumentTag]: + async for item in paginate_async( + self._transport.get, + f"{self._transport.config.v3_base_url}/tags/", + decoder=ReaderV3Page(), + ): + yield DocumentTag.model_validate(item) + + +__all__ = ["AsyncTagsResource"] diff --git a/src/readwise_sdk/transport/async_.py b/src/readwise_sdk/transport/async_.py new file mode 100644 index 0000000..43ac3c6 --- /dev/null +++ b/src/readwise_sdk/transport/async_.py @@ -0,0 +1,127 @@ +"""Canonical asynchronous HTTP transport for the Readwise APIs.""" + +from __future__ import annotations + +import asyncio +from typing import Any + +import httpx + +from readwise_sdk.config import ClientConfig +from readwise_sdk.errors import AuthenticationError, RateLimitError, ReadwiseError +from readwise_sdk.transport.errors import handle_response +from readwise_sdk.transport.retry import ( + RETRYABLE_NETWORK_EXCEPTIONS, + calculate_retry_delay, + is_retryable_exception, +) + + +class AsyncTransport: + """Own asynchronous HTTP construction, retries, and response translation.""" + + def __init__(self, config: ClientConfig) -> None: + self.config = config + self._client: httpx.AsyncClient | None = None + + @property + def raw_client(self) -> httpx.AsyncClient | None: + """Return the initialized HTTP client without creating one.""" + return self._client + + @property + def client(self) -> httpx.AsyncClient: + """Lazily construct the configured HTTP client.""" + if self._client is None: + self._client = httpx.AsyncClient( + timeout=self.config.timeout, + headers={ + "Authorization": f"Token {self.config.api_key}", + "Content-Type": "application/json", + "User-Agent": self.config.user_agent, + }, + ) + return self._client + + async def close(self) -> None: + """Close and discard the initialized HTTP client.""" + if self._client is not None: + await self._client.aclose() + self._client = None + + async def request( + self, + method: str, + url: str, + params: dict[str, Any] | None = None, + json: dict[str, Any] | None = None, + ) -> httpx.Response: + """Make an authenticated request with the existing retry behavior.""" + if not self.config.api_key: + raise AuthenticationError( + "API key is required. Set READWISE_API_KEY or pass api_key parameter." + ) + + last_error: Exception | None = None + + for attempt in range(self.config.max_retries + 1): + try: + response = await self.client.request(method, url, params=params, json=json) + return handle_response(response) + except RETRYABLE_NETWORK_EXCEPTIONS as error: + last_error = error + if attempt < self.config.max_retries and is_retryable_exception(error): + wait_time = calculate_retry_delay( + error, + self.config.retry_backoff, + attempt, + ) + if wait_time is not None: + await asyncio.sleep(wait_time) + except RateLimitError as error: + last_error = error + if attempt < self.config.max_retries and is_retryable_exception(error): + wait_time = calculate_retry_delay( + error, + self.config.retry_backoff, + attempt, + ) + if wait_time is not None: + await asyncio.sleep(wait_time) + else: + raise + + raise ReadwiseError( + f"Request failed after {self.config.max_retries + 1} attempts: {last_error}" + ) + + async def get( + self, + url: str, + params: dict[str, Any] | None = None, + ) -> httpx.Response: + """Make a GET request.""" + return await self.request("GET", url, params=params) + + async def post( + self, + url: str, + json: dict[str, Any] | None = None, + ) -> httpx.Response: + """Make a POST request.""" + return await self.request("POST", url, json=json) + + async def patch( + self, + url: str, + json: dict[str, Any] | None = None, + ) -> httpx.Response: + """Make a PATCH request.""" + return await self.request("PATCH", url, json=json) + + async def delete(self, url: str) -> httpx.Response: + """Make a DELETE request.""" + return await self.request("DELETE", url) + + +__all__ = ["AsyncTransport"] diff --git a/src/readwise_sdk/v2/async_client.py b/src/readwise_sdk/v2/async_client.py index c5f4469..f882397 100644 --- a/src/readwise_sdk/v2/async_client.py +++ b/src/readwise_sdk/v2/async_client.py @@ -1,11 +1,15 @@ -"""Async Readwise API v2 client implementation.""" +"""Compatibility facade for asynchronous Readwise API v2 resources.""" from __future__ import annotations from datetime import datetime -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING -from readwise_sdk.transport.pagination import ExportV2Page, paginate_async +from readwise_sdk.resources.v2.books import AsyncBooksResource +from readwise_sdk.resources.v2.export import AsyncExportResource +from readwise_sdk.resources.v2.highlights import AsyncHighlightsResource +from readwise_sdk.resources.v2.review import AsyncReviewResource +from readwise_sdk.resources.v2.tags import AsyncTagsResource from readwise_sdk.v2.models import ( Book, BookCategory, @@ -24,36 +28,15 @@ class AsyncReadwiseV2Client: - """Async client for Readwise API v2 (highlights, books, tags). - - This class mirrors the synchronous ReadwiseV2Client but uses async/await - for all I/O operations. Use this when your application is async-first - or when you need to make concurrent API calls. - - Example: - async with AsyncReadwiseClient() as client: - # Iterate through highlights asynchronously - async for highlight in client.v2.list_highlights(): - print(highlight.text) - - # Get multiple highlights concurrently - import asyncio - highlights = await asyncio.gather( - client.v2.get_highlight(1), - client.v2.get_highlight(2), - client.v2.get_highlight(3), - ) - """ + """Preserve the public async v2 API while delegating to resources.""" def __init__(self, base_client: AsyncReadwiseClient) -> None: - """Initialize the async v2 client. - - Args: - base_client: The async base HTTP client for making requests. - """ self._client = base_client - - # ==================== Highlights ==================== + self._highlights = AsyncHighlightsResource(base_client._transport) + self._books = AsyncBooksResource(base_client._transport) + self._tags = AsyncTagsResource(base_client._transport) + self._export = AsyncExportResource(base_client._transport) + self._review = AsyncReviewResource(base_client._transport) async def list_highlights( self, @@ -65,109 +48,27 @@ async def list_highlights( highlighted_after: datetime | None = None, highlighted_before: datetime | None = None, ) -> AsyncIterator[Highlight]: - """List all highlights with optional filtering. - - Args: - page_size: Number of results per page (max 1000). - book_id: Filter highlights by book ID. - updated_after: Only return highlights updated after this datetime. - updated_before: Only return highlights updated before this datetime. - highlighted_after: Only return highlights created after this datetime. - highlighted_before: Only return highlights created before this datetime. - - Yields: - Highlight objects. - """ - params: dict[str, Any] = {"page_size": min(page_size, 1000)} - - if book_id is not None: - params["book_id"] = book_id - if updated_after: - params["updated__gt"] = updated_after.isoformat() - if updated_before: - params["updated__lt"] = updated_before.isoformat() - if highlighted_after: - params["highlighted_at__gt"] = highlighted_after.isoformat() - if highlighted_before: - params["highlighted_at__lt"] = highlighted_before.isoformat() - - async for item in self._client.paginate( - f"{self._client.config.v2_base_url}/highlights/", - params=params, + async for highlight in self._highlights.iter( + page_size=page_size, + book_id=book_id, + updated_after=updated_after, + updated_before=updated_before, + highlighted_after=highlighted_after, + highlighted_before=highlighted_before, ): - yield Highlight.model_validate(item) + yield highlight async def get_highlight(self, highlight_id: int) -> Highlight: - """Get a single highlight by ID. - - Args: - highlight_id: The highlight ID. - - Returns: - The Highlight object. - - Raises: - NotFoundError: If the highlight doesn't exist. - """ - response = await self._client.get( - f"{self._client.config.v2_base_url}/highlights/{highlight_id}/" - ) - return Highlight.model_validate(response.json()) + return await self._highlights.get(highlight_id) async def create_highlights(self, highlights: list[HighlightCreate]) -> list[int]: - """Create one or more highlights. - - Args: - highlights: List of highlights to create. - - Returns: - List of created highlight IDs (from modified_highlights). - """ - payload = {"highlights": [h.to_api_dict() for h in highlights]} - response = await self._client.post( - f"{self._client.config.v2_base_url}/highlights/", json=payload - ) - data = response.json() - - # Extract modified highlight IDs from response - highlight_ids: list[int] = [] - for book_data in data: - modified = book_data.get("modified_highlights", []) - highlight_ids.extend(modified) - - return highlight_ids + return await self._highlights.create(highlights) async def update_highlight(self, highlight_id: int, update: HighlightUpdate) -> Highlight: - """Update an existing highlight. - - Args: - highlight_id: The highlight ID to update. - update: The fields to update. - - Returns: - The updated Highlight object. - - Raises: - NotFoundError: If the highlight doesn't exist. - """ - response = await self._client.patch( - f"{self._client.config.v2_base_url}/highlights/{highlight_id}/", - json=update.to_api_dict(), - ) - return Highlight.model_validate(response.json()) + return await self._highlights.update(highlight_id, update) async def delete_highlight(self, highlight_id: int) -> None: - """Delete a highlight. - - Args: - highlight_id: The highlight ID to delete. - - Raises: - NotFoundError: If the highlight doesn't exist. - """ - await self._client.delete(f"{self._client.config.v2_base_url}/highlights/{highlight_id}/") - - # ==================== Books ==================== + await self._highlights.delete(highlight_id) async def list_books( self, @@ -180,201 +81,45 @@ async def list_books( last_highlight_after: datetime | None = None, last_highlight_before: datetime | None = None, ) -> AsyncIterator[Book]: - """List all books/sources with optional filtering. - - Args: - page_size: Number of results per page (max 1000). - category: Filter by category (books, articles, tweets, podcasts). - source: Filter by source (kindle, instapaper, etc.). - updated_after: Only return books updated after this datetime. - updated_before: Only return books updated before this datetime. - last_highlight_after: Only return books with highlights after this datetime. - last_highlight_before: Only return books with highlights before this datetime. - - Yields: - Book objects. - """ - params: dict[str, Any] = {"page_size": min(page_size, 1000)} - - if category: - params["category"] = category.value - if source: - params["source"] = source - if updated_after: - params["updated__gt"] = updated_after.isoformat() - if updated_before: - params["updated__lt"] = updated_before.isoformat() - if last_highlight_after: - params["last_highlight_at__gt"] = last_highlight_after.isoformat() - if last_highlight_before: - params["last_highlight_at__lt"] = last_highlight_before.isoformat() - - async for item in self._client.paginate( - f"{self._client.config.v2_base_url}/books/", - params=params, + async for book in self._books.iter( + page_size=page_size, + category=category, + source=source, + updated_after=updated_after, + updated_before=updated_before, + last_highlight_after=last_highlight_after, + last_highlight_before=last_highlight_before, ): - yield Book.model_validate(item) + yield book async def get_book(self, book_id: int) -> Book: - """Get a single book by ID. - - Args: - book_id: The book ID. - - Returns: - The Book object. - - Raises: - NotFoundError: If the book doesn't exist. - """ - response = await self._client.get(f"{self._client.config.v2_base_url}/books/{book_id}/") - return Book.model_validate(response.json()) - - # ==================== Highlight Tags ==================== + return await self._books.get(book_id) async def list_highlight_tags(self, highlight_id: int) -> AsyncIterator[Tag]: - """List all tags for a highlight. - - Args: - highlight_id: The highlight ID. - - Yields: - Tag objects. - - Raises: - NotFoundError: If the highlight doesn't exist. - """ - async for item in self._client.paginate( - f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/", - ): - yield Tag.model_validate(item) + async for tag in self._tags.iter_highlight(highlight_id): + yield tag async def create_highlight_tag(self, highlight_id: int, name: str) -> Tag: - """Add a tag to a highlight. - - Args: - highlight_id: The highlight ID. - name: The tag name (max 127 chars). - - Returns: - The created Tag object. - - Raises: - NotFoundError: If the highlight doesn't exist. - """ - response = await self._client.post( - f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/", - json={"name": name[:127]}, - ) - return Tag.model_validate(response.json()) + return await self._tags.create_highlight(highlight_id, name) async def update_highlight_tag(self, highlight_id: int, tag_id: int, name: str) -> Tag: - """Update a tag on a highlight. - - Args: - highlight_id: The highlight ID. - tag_id: The tag ID. - name: The new tag name. - - Returns: - The updated Tag object. - - Raises: - NotFoundError: If the highlight or tag doesn't exist. - """ - response = await self._client.patch( - f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/{tag_id}/", - json={"name": name[:127]}, - ) - return Tag.model_validate(response.json()) + return await self._tags.update_highlight(highlight_id, tag_id, name) async def delete_highlight_tag(self, highlight_id: int, tag_id: int) -> None: - """Remove a tag from a highlight. - - Args: - highlight_id: The highlight ID. - tag_id: The tag ID. - - Raises: - NotFoundError: If the highlight or tag doesn't exist. - """ - await self._client.delete( - f"{self._client.config.v2_base_url}/highlights/{highlight_id}/tags/{tag_id}/" - ) - - # ==================== Book Tags ==================== + await self._tags.delete_highlight(highlight_id, tag_id) async def list_book_tags(self, book_id: int) -> AsyncIterator[Tag]: - """List all tags for a book. - - Args: - book_id: The book ID. - - Yields: - Tag objects. - - Raises: - NotFoundError: If the book doesn't exist. - """ - async for item in self._client.paginate( - f"{self._client.config.v2_base_url}/books/{book_id}/tags/", - ): - yield Tag.model_validate(item) + async for tag in self._tags.iter_book(book_id): + yield tag async def create_book_tag(self, book_id: int, name: str) -> Tag: - """Add a tag to a book. - - Args: - book_id: The book ID. - name: The tag name (max 512 chars). - - Returns: - The created Tag object. - - Raises: - NotFoundError: If the book doesn't exist. - """ - response = await self._client.post( - f"{self._client.config.v2_base_url}/books/{book_id}/tags/", - json={"name": name[:512]}, - ) - return Tag.model_validate(response.json()) + return await self._tags.create_book(book_id, name) async def update_book_tag(self, book_id: int, tag_id: int, name: str) -> Tag: - """Update a tag on a book. - - Args: - book_id: The book ID. - tag_id: The tag ID. - name: The new tag name. - - Returns: - The updated Tag object. - - Raises: - NotFoundError: If the book or tag doesn't exist. - """ - response = await self._client.patch( - f"{self._client.config.v2_base_url}/books/{book_id}/tags/{tag_id}/", - json={"name": name[:512]}, - ) - return Tag.model_validate(response.json()) + return await self._tags.update_book(book_id, tag_id, name) async def delete_book_tag(self, book_id: int, tag_id: int) -> None: - """Remove a tag from a book. - - Args: - book_id: The book ID. - tag_id: The tag ID. - - Raises: - NotFoundError: If the book or tag doesn't exist. - """ - await self._client.delete( - f"{self._client.config.v2_base_url}/books/{book_id}/tags/{tag_id}/" - ) - - # ==================== Export ==================== + await self._tags.delete_book(book_id, tag_id) async def export_highlights( self, @@ -383,43 +128,12 @@ async def export_highlights( book_ids: list[int] | None = None, include_deleted: bool = False, ) -> AsyncIterator[ExportBook]: - """Export highlights using the export endpoint. - - This endpoint returns books with their highlights nested, which is more - efficient for bulk operations. - - Args: - updated_after: Only return highlights updated after this datetime. - book_ids: Only return highlights from these books. - include_deleted: Whether to include deleted highlights. - - Yields: - ExportBook objects containing nested highlights. - """ - params: dict[str, Any] = {} - - if updated_after: - params["updatedAfter"] = updated_after.isoformat() - if book_ids: - params["ids"] = ",".join(str(bid) for bid in book_ids) - if include_deleted: - params["includeDeleted"] = "true" - - async for item in paginate_async( - self._client.get, - f"{self._client.config.v2_base_url}/export/", - params=params, - decoder=ExportV2Page(), + async for book in self._export.iter( + updated_after=updated_after, + book_ids=book_ids, + include_deleted=include_deleted, ): - yield ExportBook.model_validate(item) - - # ==================== Daily Review ==================== + yield book async def get_daily_review(self) -> DailyReview: - """Get the current daily review. - - Returns: - The DailyReview object with selected highlights. - """ - response = await self._client.get(f"{self._client.config.v2_base_url}/review/") - return DailyReview.model_validate(response.json()) + return await self._review.get() diff --git a/src/readwise_sdk/v3/async_client.py b/src/readwise_sdk/v3/async_client.py index d4ebeab..85a44cc 100644 --- a/src/readwise_sdk/v3/async_client.py +++ b/src/readwise_sdk/v3/async_client.py @@ -1,11 +1,12 @@ -"""Async Readwise Reader API v3 client implementation.""" +"""Compatibility facade for asynchronous Reader API v3 resources.""" from __future__ import annotations from datetime import datetime -from typing import TYPE_CHECKING, Any +from typing import TYPE_CHECKING -from readwise_sdk.transport.pagination import ReaderV3Page, paginate_async +from readwise_sdk.resources.v3.documents import AsyncDocumentsResource +from readwise_sdk.resources.v3.tags import AsyncTagsResource from readwise_sdk.v3.models import ( CreateDocumentResult, Document, @@ -23,36 +24,12 @@ class AsyncReadwiseV3Client: - """Async client for Readwise Reader API v3 (documents, reading list). - - This class mirrors the synchronous ReadwiseV3Client but uses async/await - for all I/O operations. Use this when your application is async-first - or when you need to make concurrent API calls. - - Example: - async with AsyncReadwiseClient() as client: - # Iterate through documents asynchronously - async for doc in client.v3.list_documents(): - print(doc.title) - - # Save multiple URLs concurrently - import asyncio - results = await asyncio.gather( - client.v3.save_url("https://example.com/1"), - client.v3.save_url("https://example.com/2"), - client.v3.save_url("https://example.com/3"), - ) - """ + """Preserve the public async v3 API while delegating to resources.""" def __init__(self, base_client: AsyncReadwiseClient) -> None: - """Initialize the async v3 client. - - Args: - base_client: The async base HTTP client for making requests. - """ self._client = base_client - - # ==================== Documents ==================== + self._documents = AsyncDocumentsResource(base_client._transport) + self._tags = AsyncTagsResource(base_client._transport) async def list_documents( self, @@ -63,78 +40,22 @@ async def list_documents( tags: list[str] | None = None, with_content: bool = False, ) -> AsyncIterator[Document]: - """List all documents with optional filtering. - - Args: - location: Filter by location (new, later, archive, feed). - category: Filter by category (article, email, pdf, etc.). - updated_after: Only return documents updated after this datetime. - tags: Filter by tags (up to 5). - with_content: Whether to include HTML content in response. - - Yields: - Document objects. - """ - params: dict[str, Any] = {} - - if location: - params["location"] = location.value - if category: - params["category"] = category.value - if updated_after: - params["updatedAfter"] = updated_after.isoformat() - if tags and len(tags) > 0: - # Use first tag for filtering (API supports up to 5) - params["tag"] = tags[0] - if with_content: - params["withHtmlContent"] = "true" - - async for item in paginate_async( - self._client.get, - f"{self._client.config.v3_base_url}/list/", - params=params, - decoder=ReaderV3Page(), + async for document in self._documents.iter( + location=location, + category=category, + updated_after=updated_after, + tags=tags, + with_content=with_content, ): - yield Document.model_validate(item) + yield document async def get_document( self, document_id: str, *, with_content: bool = False ) -> Document | None: - """Get a single document by ID. - - Args: - document_id: The document ID. - with_content: Whether to include HTML content. - - Returns: - The Document object, or None if not found. - """ - params: dict[str, Any] = {"id": document_id} - if with_content: - params["withHtmlContent"] = "true" - - response = await self._client.get(f"{self._client.config.v3_base_url}/list/", params=params) - data = response.json() - results = data.get("results", []) - - if results: - return Document.model_validate(results[0]) - return None + return await self._documents.get(document_id, with_content=with_content) async def create_document(self, document: DocumentCreate) -> CreateDocumentResult: - """Create a new document in Reader. - - Args: - document: The document data to create. - - Returns: - CreateDocumentResult with id and url. - """ - response = await self._client.post( - f"{self._client.config.v3_base_url}/save/", - json=document.to_api_dict(), - ) - return CreateDocumentResult.model_validate(response.json()) + return await self._documents.create(document) async def save_url( self, @@ -144,195 +65,67 @@ async def save_url( tags: list[str] | None = None, notes: str | None = None, ) -> CreateDocumentResult: - """Convenience method to save a URL to Reader. - - Args: - url: The URL to save. - location: Where to save it (default: new/inbox). - tags: Optional tags to add. - notes: Optional notes to add. - - Returns: - CreateDocumentResult with id and url. - """ - doc = DocumentCreate( - url=url, - location=location, - tags=tags, - notes=notes, - ) - return await self.create_document(doc) + document = DocumentCreate(url=url, location=location, tags=tags, notes=notes) + return await self.create_document(document) async def update_document( self, document_id: str, update: DocumentUpdate ) -> CreateDocumentResult: - """Update an existing document. - - Args: - document_id: The document ID to update. - update: The fields to update. - - Returns: - CreateDocumentResult with id and url. - - Raises: - NotFoundError: If the document doesn't exist. - """ - response = await self._client.patch( - f"{self._client.config.v3_base_url}/update/{document_id}/", - json=update.to_api_dict(), - ) - return CreateDocumentResult.model_validate(response.json()) + return await self._documents.update(document_id, update) async def delete_document(self, document_id: str) -> None: - """Delete a document. - - Args: - document_id: The document ID to delete. - - Raises: - NotFoundError: If the document doesn't exist. - """ - await self._client.delete(f"{self._client.config.v3_base_url}/delete/{document_id}/") + await self._documents.delete(document_id) async def move_to_later(self, document_id: str) -> CreateDocumentResult: - """Move a document to the reading list (later). - - Args: - document_id: The document ID to move. - - Returns: - CreateDocumentResult with id and url. - """ update = DocumentUpdate(location=DocumentLocation.LATER) return await self.update_document(document_id, update) async def archive(self, document_id: str) -> CreateDocumentResult: - """Archive a document. - - Args: - document_id: The document ID to archive. - - Returns: - CreateDocumentResult with id and url. - """ update = DocumentUpdate(location=DocumentLocation.ARCHIVE) return await self.update_document(document_id, update) async def move_to_inbox(self, document_id: str) -> CreateDocumentResult: - """Move a document back to the inbox (new). - - Args: - document_id: The document ID to move. - - Returns: - CreateDocumentResult with id and url. - """ update = DocumentUpdate(location=DocumentLocation.NEW) return await self.update_document(document_id, update) - # ==================== Tags ==================== - async def list_tags(self) -> AsyncIterator[DocumentTag]: - """List all tags in Reader. - - Yields: - DocumentTag objects with key and name. - """ - async for item in paginate_async( - self._client.get, - f"{self._client.config.v3_base_url}/tags/", - decoder=ReaderV3Page(), - ): - yield DocumentTag.model_validate(item) + async for tag in self._tags.iter(): + yield tag async def tag_document(self, document_id: str, tags: list[str]) -> CreateDocumentResult: - """Set tags on a document. - - Note: This replaces all existing tags on the document. - - Args: - document_id: The document ID to tag. - tags: List of tag names to set. - - Returns: - CreateDocumentResult with id and url. - """ update = DocumentUpdate(tags=tags) return await self.update_document(document_id, update) async def add_tag(self, document_id: str, tag: str) -> CreateDocumentResult: - """Add a tag to a document (preserving existing tags). - - Args: - document_id: The document ID. - tag: The tag to add. - - Returns: - CreateDocumentResult with id and url. - """ - # First get the document to see existing tags - doc = await self.get_document(document_id) - if doc is None: + document = await self.get_document(document_id) + if document is None: from readwise_sdk.errors import NotFoundError raise NotFoundError(f"Document {document_id} not found") - new_tags = list(doc.tags) + new_tags = list(document.tags) if tag not in new_tags: new_tags.append(tag) - return await self.tag_document(document_id, new_tags) async def remove_tag(self, document_id: str, tag: str) -> CreateDocumentResult: - """Remove a tag from a document. - - Args: - document_id: The document ID. - tag: The tag to remove. - - Returns: - CreateDocumentResult with id and url. - """ - doc = await self.get_document(document_id) - if doc is None: + document = await self.get_document(document_id) + if document is None: from readwise_sdk.errors import NotFoundError raise NotFoundError(f"Document {document_id} not found") - new_tags = [t for t in doc.tags if t != tag] + new_tags = [existing_tag for existing_tag in document.tags if existing_tag != tag] return await self.tag_document(document_id, new_tags) - # ==================== Convenience Methods ==================== - def get_inbox(self) -> AsyncIterator[Document]: - """Get all documents in the inbox (new). - - Returns: - Async iterator of Document objects in the inbox. - """ return self.list_documents(location=DocumentLocation.NEW) def get_reading_list(self) -> AsyncIterator[Document]: - """Get all documents in the reading list (later). - - Returns: - Async iterator of Document objects in the reading list. - """ return self.list_documents(location=DocumentLocation.LATER) def get_archive(self) -> AsyncIterator[Document]: - """Get all archived documents. - - Returns: - Async iterator of archived Document objects. - """ return self.list_documents(location=DocumentLocation.ARCHIVE) def get_articles(self) -> AsyncIterator[Document]: - """Get all article documents. - - Returns: - Async iterator of Article Document objects. - """ return self.list_documents(category=DocumentCategory.ARTICLE) diff --git a/tests/async/test_async_public_surface.py b/tests/async/test_async_public_surface.py new file mode 100644 index 0000000..0127890 --- /dev/null +++ b/tests/async/test_async_public_surface.py @@ -0,0 +1,89 @@ +"""Lock the complete public surface of the versioned async clients.""" + +from __future__ import annotations + +import inspect +from typing import Any + +from readwise_sdk.v2.async_client import AsyncReadwiseV2Client +from readwise_sdk.v3.async_client import AsyncReadwiseV3Client + +V2_SIGNATURES = { + "list_highlights": "(self, *, page_size: 'int' = 100, book_id: 'int | None' = None, updated_after: 'datetime | None' = None, updated_before: 'datetime | None' = None, highlighted_after: 'datetime | None' = None, highlighted_before: 'datetime | None' = None) -> 'AsyncIterator[Highlight]'", + "get_highlight": "(self, highlight_id: 'int') -> 'Highlight'", + "create_highlights": "(self, highlights: 'list[HighlightCreate]') -> 'list[int]'", + "update_highlight": "(self, highlight_id: 'int', update: 'HighlightUpdate') -> 'Highlight'", + "delete_highlight": "(self, highlight_id: 'int') -> 'None'", + "list_books": "(self, *, page_size: 'int' = 100, category: 'BookCategory | None' = None, source: 'str | None' = None, updated_after: 'datetime | None' = None, updated_before: 'datetime | None' = None, last_highlight_after: 'datetime | None' = None, last_highlight_before: 'datetime | None' = None) -> 'AsyncIterator[Book]'", + "get_book": "(self, book_id: 'int') -> 'Book'", + "list_highlight_tags": "(self, highlight_id: 'int') -> 'AsyncIterator[Tag]'", + "create_highlight_tag": "(self, highlight_id: 'int', name: 'str') -> 'Tag'", + "update_highlight_tag": "(self, highlight_id: 'int', tag_id: 'int', name: 'str') -> 'Tag'", + "delete_highlight_tag": "(self, highlight_id: 'int', tag_id: 'int') -> 'None'", + "list_book_tags": "(self, book_id: 'int') -> 'AsyncIterator[Tag]'", + "create_book_tag": "(self, book_id: 'int', name: 'str') -> 'Tag'", + "update_book_tag": "(self, book_id: 'int', tag_id: 'int', name: 'str') -> 'Tag'", + "delete_book_tag": "(self, book_id: 'int', tag_id: 'int') -> 'None'", + "export_highlights": "(self, *, updated_after: 'datetime | None' = None, book_ids: 'list[int] | None' = None, include_deleted: 'bool' = False) -> 'AsyncIterator[ExportBook]'", + "get_daily_review": "(self) -> 'DailyReview'", +} + +V3_SIGNATURES = { + "list_documents": "(self, *, location: 'DocumentLocation | None' = None, category: 'DocumentCategory | None' = None, updated_after: 'datetime | None' = None, tags: 'list[str] | None' = None, with_content: 'bool' = False) -> 'AsyncIterator[Document]'", + "get_document": "(self, document_id: 'str', *, with_content: 'bool' = False) -> 'Document | None'", + "create_document": "(self, document: 'DocumentCreate') -> 'CreateDocumentResult'", + "save_url": "(self, url: 'str', *, location: 'DocumentLocation' = , tags: 'list[str] | None' = None, notes: 'str | None' = None) -> 'CreateDocumentResult'", + "update_document": "(self, document_id: 'str', update: 'DocumentUpdate') -> 'CreateDocumentResult'", + "delete_document": "(self, document_id: 'str') -> 'None'", + "move_to_later": "(self, document_id: 'str') -> 'CreateDocumentResult'", + "archive": "(self, document_id: 'str') -> 'CreateDocumentResult'", + "move_to_inbox": "(self, document_id: 'str') -> 'CreateDocumentResult'", + "list_tags": "(self) -> 'AsyncIterator[DocumentTag]'", + "tag_document": "(self, document_id: 'str', tags: 'list[str]') -> 'CreateDocumentResult'", + "add_tag": "(self, document_id: 'str', tag: 'str') -> 'CreateDocumentResult'", + "remove_tag": "(self, document_id: 'str', tag: 'str') -> 'CreateDocumentResult'", + "get_inbox": "(self) -> 'AsyncIterator[Document]'", + "get_reading_list": "(self) -> 'AsyncIterator[Document]'", + "get_archive": "(self) -> 'AsyncIterator[Document]'", + "get_articles": "(self) -> 'AsyncIterator[Document]'", +} + + +def _public_methods(client_type: type[Any]) -> dict[str, Any]: + return { + name: value + for name, value in client_type.__dict__.items() + if not name.startswith("_") and callable(value) + } + + +def test_async_v2_public_methods_signatures_and_callable_kinds() -> None: + methods = _public_methods(AsyncReadwiseV2Client) + + assert { + name: str(inspect.signature(method)) for name, method in methods.items() + } == V2_SIGNATURES + assert {name for name, method in methods.items() if inspect.isasyncgenfunction(method)} == { + "list_highlights", + "list_books", + "list_highlight_tags", + "list_book_tags", + "export_highlights", + } + + +def test_async_v3_public_methods_signatures_and_callable_kinds() -> None: + methods = _public_methods(AsyncReadwiseV3Client) + + assert { + name: str(inspect.signature(method)) for name, method in methods.items() + } == V3_SIGNATURES + assert {name for name, method in methods.items() if inspect.isasyncgenfunction(method)} == { + "list_documents", + "list_tags", + } + assert { + name + for name, method in methods.items() + if not inspect.isasyncgenfunction(method) and not inspect.iscoroutinefunction(method) + } == {"get_inbox", "get_reading_list", "get_archive", "get_articles"} diff --git a/tests/resources/__init__.py b/tests/resources/__init__.py new file mode 100644 index 0000000..74fe2fe --- /dev/null +++ b/tests/resources/__init__.py @@ -0,0 +1 @@ +"""Tests for canonical API resources.""" diff --git a/tests/resources/test_async_resources.py b/tests/resources/test_async_resources.py new file mode 100644 index 0000000..3ae3712 --- /dev/null +++ b/tests/resources/test_async_resources.py @@ -0,0 +1,54 @@ +"""Tests for asynchronous resource composition and compatibility delegation.""" + +from __future__ import annotations + +import pytest + +from readwise_sdk.client import AsyncReadwiseClient +from readwise_sdk.resources.v2.books import AsyncBooksResource +from readwise_sdk.resources.v2.export import AsyncExportResource +from readwise_sdk.resources.v2.highlights import AsyncHighlightsResource +from readwise_sdk.resources.v2.review import AsyncReviewResource +from readwise_sdk.resources.v2.tags import AsyncTagsResource as AsyncV2TagsResource +from readwise_sdk.resources.v3.documents import AsyncDocumentsResource +from readwise_sdk.resources.v3.tags import AsyncTagsResource as AsyncV3TagsResource +from readwise_sdk.v2.models import Highlight +from readwise_sdk.v3.models import Document + + +def test_async_versioned_clients_compose_endpoint_resources() -> None: + """The legacy versioned clients are compatibility facades over resources.""" + client = AsyncReadwiseClient("token") + + assert isinstance(client.v2._highlights, AsyncHighlightsResource) + assert isinstance(client.v2._books, AsyncBooksResource) + assert isinstance(client.v2._tags, AsyncV2TagsResource) + assert isinstance(client.v2._export, AsyncExportResource) + assert isinstance(client.v2._review, AsyncReviewResource) + assert isinstance(client.v3._documents, AsyncDocumentsResource) + assert isinstance(client.v3._tags, AsyncV3TagsResource) + + +@pytest.mark.asyncio +async def test_async_versioned_clients_delegate_model_results( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Compatibility methods return the exact model objects supplied by resources.""" + client = AsyncReadwiseClient("token") + highlight = Highlight(id=7, text="delegated highlight") + document = Document(id="doc-7", url="https://example.test/doc-7") + + async def get_highlight(highlight_id: int) -> Highlight: + assert highlight_id == 7 + return highlight + + async def get_document(document_id: str, *, with_content: bool = False) -> Document | None: + assert document_id == "doc-7" + assert with_content is True + return document + + monkeypatch.setattr(client.v2._highlights, "get", get_highlight) + monkeypatch.setattr(client.v3._documents, "get", get_document) + + assert await client.v2.get_highlight(7) is highlight + assert await client.v3.get_document("doc-7", with_content=True) is document diff --git a/tests/transport/__init__.py b/tests/transport/__init__.py new file mode 100644 index 0000000..9072fbd --- /dev/null +++ b/tests/transport/__init__.py @@ -0,0 +1 @@ +"""Tests for canonical HTTP transports.""" diff --git a/tests/transport/test_async_transport.py b/tests/transport/test_async_transport.py new file mode 100644 index 0000000..d22cc41 --- /dev/null +++ b/tests/transport/test_async_transport.py @@ -0,0 +1,38 @@ +"""Tests for the canonical asynchronous transport.""" + +from __future__ import annotations + +import httpx +import pytest +import respx + +from readwise_sdk.config import ClientConfig +from readwise_sdk.transport.async_ import AsyncTransport + + +@respx.mock +@pytest.mark.asyncio +async def test_async_transport_builds_authenticated_requests_from_config() -> None: + """The transport owns the canonical async request path and lifecycle.""" + url = "https://example.test/items/" + route = respx.get(url).mock(return_value=httpx.Response(200, json={"ok": True})) + transport = AsyncTransport( + ClientConfig( + api_key="test-token", + timeout=7.5, + user_agent="readwise-plus/test", + ) + ) + + response = await transport.get(url, params={"page": 2}) + + assert response.json() == {"ok": True} + assert route.calls.last.request.headers["Authorization"] == "Token test-token" + assert route.calls.last.request.headers["Content-Type"] == "application/json" + assert route.calls.last.request.headers["User-Agent"] == "readwise-plus/test" + assert str(route.calls.last.request.url) == f"{url}?page=2" + + raw_client = transport.client + await transport.close() + assert raw_client.is_closed is True + assert transport.raw_client is None From 02bc8d99b8b5bd44af306f1ff3f650597ef513f8 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 23:14:46 -0500 Subject: [PATCH 08/24] feat: add operation input + result models (stage 5) Additive. New models/ package: operation input models (search/create/update inputs owning limit bounds + normalization), shared read/summary models (DocumentSummary/HighlightSummary/BookSummary matching current adapter projections), and result types (DocumentSearchResult, generic BulkResult, OperationFailure, unified SyncCheckpoint/SyncResult). Not yet wired into any call site. New unit tests for validation/normalization. Nothing existing changed; gate green (621 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/models/__init__.py | 27 ++++++ src/readwise_sdk/models/queries.py | 106 +++++++++++++++++++++++ src/readwise_sdk/models/results.py | 125 +++++++++++++++++++++++++++ tests/models/__init__.py | 1 + tests/models/test_queries.py | 74 ++++++++++++++++ tests/models/test_results.py | 126 ++++++++++++++++++++++++++++ 6 files changed, 459 insertions(+) create mode 100644 src/readwise_sdk/models/__init__.py create mode 100644 src/readwise_sdk/models/queries.py create mode 100644 src/readwise_sdk/models/results.py create mode 100644 tests/models/__init__.py create mode 100644 tests/models/test_queries.py create mode 100644 tests/models/test_results.py diff --git a/src/readwise_sdk/models/__init__.py b/src/readwise_sdk/models/__init__.py new file mode 100644 index 0000000..aaaea18 --- /dev/null +++ b/src/readwise_sdk/models/__init__.py @@ -0,0 +1,27 @@ +"""Operation-level input, summary, and result models.""" + +from readwise_sdk.models.queries import BookSearch, DocumentSearch, HighlightSearch +from readwise_sdk.models.results import ( + BookSummary, + BulkResult, + DocumentSearchResult, + DocumentSummary, + HighlightSummary, + OperationFailure, + SyncCheckpoint, + SyncResult, +) + +__all__ = [ + "BookSearch", + "BookSummary", + "BulkResult", + "DocumentSearch", + "DocumentSearchResult", + "DocumentSummary", + "HighlightSearch", + "HighlightSummary", + "OperationFailure", + "SyncCheckpoint", + "SyncResult", +] diff --git a/src/readwise_sdk/models/queries.py b/src/readwise_sdk/models/queries.py new file mode 100644 index 0000000..d63292f --- /dev/null +++ b/src/readwise_sdk/models/queries.py @@ -0,0 +1,106 @@ +"""Validated inputs for the canonical operations layer.""" + +from __future__ import annotations + +from datetime import datetime + +from pydantic import BaseModel, ConfigDict, Field, field_validator + +from readwise_sdk.v2.models import BookCategory +from readwise_sdk.v3.models import DocumentCategory, DocumentLocation + + +def _normalize_optional_text(value: str | None) -> str | None: + """Strip an optional text filter and discard whitespace-only values.""" + if value is None: + return None + normalized = value.strip() + return normalized or None + + +class OperationInput(BaseModel): + """Base configuration shared by immutable operation inputs.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + +class DocumentSearch(OperationInput): + """Input for filtering and searching Reader documents.""" + + location: DocumentLocation | None = None + category: DocumentCategory | None = None + updated_after: datetime | None = None + tags: tuple[str, ...] = () + query: str | None = None + limit: int = 20 + + @field_validator("tags") + @classmethod + def normalize_tags(cls, value: tuple[str, ...]) -> tuple[str, ...]: + """Strip tag names, remove blanks, and preserve unique input order.""" + normalized: list[str] = [] + seen: set[str] = set() + for tag in value: + stripped = tag.strip() + if stripped and stripped not in seen: + normalized.append(stripped) + seen.add(stripped) + return tuple(normalized) + + @field_validator("query") + @classmethod + def normalize_query(cls, value: str | None) -> str | None: + """Normalize an optional local text query.""" + return _normalize_optional_text(value) + + @field_validator("limit") + @classmethod + def clamp_limit(cls, value: int) -> int: + """Clamp document searches to the current adapter contract.""" + return min(max(value, 1), 100) + + +class HighlightSearch(OperationInput): + """Input for filtering and searching Readwise highlights.""" + + book_id: int | None = Field(default=None, gt=0) + updated_after: datetime | None = None + query: str | None = None + limit: int = 50 + + @field_validator("query") + @classmethod + def normalize_query(cls, value: str | None) -> str | None: + """Normalize an optional local text query.""" + return _normalize_optional_text(value) + + @field_validator("limit") + @classmethod + def clamp_limit(cls, value: int) -> int: + """Clamp highlight searches to the current adapter contract.""" + return min(max(value, 1), 200) + + +class BookSearch(OperationInput): + """Input for filtering and searching Readwise books and sources.""" + + category: BookCategory | None = None + source: str | None = None + updated_after: datetime | None = None + query: str | None = None + limit: int = 20 + + @field_validator("source", "query") + @classmethod + def normalize_text_filter(cls, value: str | None) -> str | None: + """Normalize optional source and local text filters.""" + return _normalize_optional_text(value) + + @field_validator("limit") + @classmethod + def clamp_limit(cls, value: int) -> int: + """Clamp book searches to the current adapter contract.""" + return min(max(value, 1), 100) + + +__all__ = ["BookSearch", "DocumentSearch", "HighlightSearch"] diff --git a/src/readwise_sdk/models/results.py b/src/readwise_sdk/models/results.py new file mode 100644 index 0000000..541814d --- /dev/null +++ b/src/readwise_sdk/models/results.py @@ -0,0 +1,125 @@ +"""Shared semantic projections and declared operation results.""" + +from __future__ import annotations + +from datetime import datetime + +from pydantic import BaseModel, ConfigDict, Field + +from readwise_sdk.v2.models import Book, BookCategory, Highlight, HighlightColor +from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation + + +class SummaryModel(BaseModel): + """Base configuration for immutable semantic read projections.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + +class DocumentSummary(SummaryModel): + """Document fields shared by current CLI and MCP list projections.""" + + id: str + title: str | None = None + author: str | None = None + url: str + category: DocumentCategory | None = None + location: DocumentLocation | None = None + tags: tuple[str, ...] = () + word_count: int | None = None + reading_progress: float | None = None + site_name: str | None = None + published_date: datetime | None = None + saved_at: datetime | None = None + + +class HighlightSummary(SummaryModel): + """Highlight fields shared by current CLI and MCP list projections.""" + + id: int + text: str + note: str | None = None + book_id: int | None = None + color: HighlightColor | None = None + location: int | None = None + highlighted_at: datetime | None = None + tags: tuple[str, ...] = () + + +class BookSummary(SummaryModel): + """Book fields shared by current CLI and MCP list projections.""" + + id: int + title: str + author: str | None = None + category: BookCategory | None = None + source: str | None = None + num_highlights: int = 0 + source_url: str | None = None + cover_image_url: str | None = None + last_highlight_at: datetime | None = None + + +class DocumentSearchResult(BaseModel): + """Bounded results from a document search operation.""" + + items: list[DocumentSummary] = Field(default_factory=list) + truncated: bool = False + + +class OperationFailure(BaseModel): + """One failed item from a bulk operation.""" + + model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True) + + item: str | int + error: Exception + + @property + def message(self) -> str: + """Return the adapter-safe text of the original exception.""" + return str(self.error) + + +class BulkResult[T](BaseModel): + """Successful items and item-specific failures from a bulk operation.""" + + succeeded: list[T] = Field(default_factory=list) + failures: list[OperationFailure] = Field(default_factory=list) + + +class SyncCheckpoint(BaseModel): + """Unified cursors for the next incremental synchronization.""" + + model_config = ConfigDict(frozen=True) + + last_highlight_sync: datetime | None = None + last_book_sync: datetime | None = None + last_document_sync: datetime | None = None + last_sync_time: datetime | None = None + + +class SyncResult(BaseModel): + """Resource data and checkpoint produced by one sync operation.""" + + highlights: list[Highlight] = Field(default_factory=list) + books: list[Book] = Field(default_factory=list) + documents: list[Document] = Field(default_factory=list) + checkpoint: SyncCheckpoint = Field(default_factory=SyncCheckpoint) + + @property + def is_empty(self) -> bool: + """Return whether the sync yielded no resource data.""" + return not self.highlights and not self.books and not self.documents + + +__all__ = [ + "BookSummary", + "BulkResult", + "DocumentSearchResult", + "DocumentSummary", + "HighlightSummary", + "OperationFailure", + "SyncCheckpoint", + "SyncResult", +] diff --git a/tests/models/__init__.py b/tests/models/__init__.py new file mode 100644 index 0000000..9ef014a --- /dev/null +++ b/tests/models/__init__.py @@ -0,0 +1 @@ +"""Tests for operation-level models.""" diff --git a/tests/models/test_queries.py b/tests/models/test_queries.py new file mode 100644 index 0000000..a6fa86e --- /dev/null +++ b/tests/models/test_queries.py @@ -0,0 +1,74 @@ +"""Tests for operation input models.""" + +from datetime import UTC, datetime + +import pytest +from pydantic import ValidationError + +from readwise_sdk.models.queries import BookSearch, DocumentSearch, HighlightSearch +from readwise_sdk.v2.models import BookCategory +from readwise_sdk.v3.models import DocumentCategory, DocumentLocation + + +class TestDocumentSearch: + """Tests for document search inputs.""" + + def test_normalizes_whitespace_and_tags(self) -> None: + """Surrounding whitespace and empty or duplicate tags are normalized.""" + updated_after = datetime(2025, 1, 2, 3, 4, tzinfo=UTC) + + search = DocumentSearch( + location=DocumentLocation.LATER, + category=DocumentCategory.ARTICLE, + updated_after=updated_after, + tags=(" python ", "", "ai", "python", " "), + query=" Python SDK ", + ) + + assert search.location is DocumentLocation.LATER + assert search.category is DocumentCategory.ARTICLE + assert search.updated_after is updated_after + assert search.tags == ("python", "ai") + assert search.query == "Python SDK" + + @pytest.mark.parametrize(("provided", "expected"), [(-10, 1), (0, 1), (101, 100)]) + def test_clamps_limit(self, provided: int, expected: int) -> None: + """Document result limits stay within the operation's 1..100 bounds.""" + assert DocumentSearch(limit=provided).limit == expected + + def test_converts_whitespace_only_query_to_none(self) -> None: + """A query with no searchable content is treated as absent.""" + assert DocumentSearch(query=" \n\t ").query is None + + +class TestHighlightSearch: + """Tests for highlight search inputs.""" + + def test_normalizes_query_and_clamps_limit(self) -> None: + """Highlight search owns query trimming and its 1..200 limit bounds.""" + search = HighlightSearch(query=" systems thinking ", limit=500) + + assert search.query == "systems thinking" + assert search.limit == 200 + + def test_rejects_non_positive_book_id(self) -> None: + """A book filter must identify an actual positive Readwise book ID.""" + with pytest.raises(ValidationError): + HighlightSearch(book_id=0) + + +class TestBookSearch: + """Tests for book search inputs.""" + + def test_normalizes_optional_text_filters(self) -> None: + """Source and query filters are stripped, with blank values removed.""" + search = BookSearch(category=BookCategory.BOOKS, source=" kindle ", query=" ") + + assert search.category is BookCategory.BOOKS + assert search.source == "kindle" + assert search.query is None + + @pytest.mark.parametrize(("provided", "expected"), [(-1, 1), (0, 1), (101, 100)]) + def test_clamps_limit(self, provided: int, expected: int) -> None: + """Book result limits stay within the operation's 1..100 bounds.""" + assert BookSearch(limit=provided).limit == expected diff --git a/tests/models/test_results.py b/tests/models/test_results.py new file mode 100644 index 0000000..e075d01 --- /dev/null +++ b/tests/models/test_results.py @@ -0,0 +1,126 @@ +"""Tests for operation result and summary models.""" + +from datetime import UTC, datetime + +from readwise_sdk.models.results import ( + BookSummary, + BulkResult, + DocumentSearchResult, + DocumentSummary, + HighlightSummary, + OperationFailure, + SyncCheckpoint, + SyncResult, +) +from readwise_sdk.v2.models import Book, BookCategory, Highlight, HighlightColor +from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation + + +def test_summary_models_hold_shared_adapter_projections() -> None: + """Summary models declare the semantic fields shared by CLI and MCP output.""" + timestamp = datetime(2025, 1, 2, 3, 4, tzinfo=UTC) + + document = DocumentSummary( + id="doc-1", + title="An article", + author="An Author", + url="https://example.com/article", + category=DocumentCategory.ARTICLE, + location=DocumentLocation.LATER, + tags=("python", "sdk"), + word_count=1200, + reading_progress=0.25, + site_name="Example", + published_date=timestamp, + saved_at=timestamp, + ) + highlight = HighlightSummary( + id=1, + text="A useful passage", + note="Remember this", + book_id=2, + color=HighlightColor.YELLOW, + location=10, + highlighted_at=timestamp, + tags=("favorite",), + ) + book = BookSummary( + id=2, + title="A Book", + author="An Author", + category=BookCategory.BOOKS, + source="kindle", + num_highlights=4, + source_url="https://example.com/book", + cover_image_url="https://example.com/cover.jpg", + last_highlight_at=timestamp, + ) + + assert document.tags == ("python", "sdk") + assert document.category is DocumentCategory.ARTICLE + assert highlight.tags == ("favorite",) + assert highlight.color is HighlightColor.YELLOW + assert book.num_highlights == 4 + assert book.category is BookCategory.BOOKS + + +def test_document_search_result_reports_truncation() -> None: + """Document search returns declared summaries plus a truncation signal.""" + summary = DocumentSummary(id="doc-1", url="https://example.com") + + result = DocumentSearchResult(items=[summary], truncated=True) + + assert result.items == [summary] + assert result.truncated is True + + +def test_bulk_result_keeps_successes_and_original_failures() -> None: + """Bulk failures identify their input and retain the original exception.""" + error = RuntimeError("archive failed") + failure = OperationFailure(item="doc-2", error=error) + + result = BulkResult[str](succeeded=["doc-1"], failures=[failure]) + + assert result.succeeded == ["doc-1"] + assert result.failures == [failure] + assert result.failures[0].error is error + assert result.failures[0].message == "archive failed" + + +def test_sync_result_carries_data_and_unified_checkpoint() -> None: + """A sync result returns all resource data with the checkpoint that follows it.""" + timestamp = datetime(2025, 1, 2, 3, 4, tzinfo=UTC) + checkpoint = SyncCheckpoint( + last_highlight_sync=timestamp, + last_book_sync=timestamp, + last_document_sync=timestamp, + last_sync_time=timestamp, + ) + highlight = Highlight(id=1, text="Passage") + book = Book(id=2, title="Book") + document = Document(id="doc-1", url="https://example.com") + + result = SyncResult( + highlights=[highlight], + books=[book], + documents=[document], + checkpoint=checkpoint, + ) + + assert result.highlights == [highlight] + assert result.books == [book] + assert result.documents == [document] + assert result.checkpoint is checkpoint + assert result.is_empty is False + + +def test_sync_result_defaults_to_empty_collections() -> None: + """An empty sync has independent resource lists and an empty checkpoint.""" + first = SyncResult() + second = SyncResult() + + first.highlights.append(Highlight(id=1, text="Passage")) + + assert second.highlights == [] + assert second.is_empty is True + assert second.checkpoint == SyncCheckpoint() From 1258250c0f57d24dfa6d81266b80d1e1de2e35ee Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 23:25:23 -0500 Subject: [PATCH 09/24] feat: document operations layer (stage 6) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Additive. New operations/documents.py + service wiring: canonical document operations (search, get, save, update, delete, move, tag add/remove/set, inbox/archive/later views, statistics) built on resources/ + stage-5 models. Semantics ported verbatim from DocumentManager, ReadingInbox, DocumentImporter, the MCP document tools, and CLI Reader commands — quirks carried as-is (list_documents single-tag; save_to_reader category still dropped). Operations own intent only (no formatting/protocol). MCP/CLI/managers NOT rewired yet. New operation tests; characterization unchanged; gate green (634 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/operations/__init__.py | 6 + src/readwise_sdk/operations/documents.py | 304 +++++++++++++++++ src/readwise_sdk/operations/service.py | 15 + tests/operations/__init__.py | 1 + tests/operations/test_documents.py | 329 +++++++++++++++++++ tests/operations/test_documents_transport.py | 140 ++++++++ 6 files changed, 795 insertions(+) create mode 100644 src/readwise_sdk/operations/__init__.py create mode 100644 src/readwise_sdk/operations/documents.py create mode 100644 src/readwise_sdk/operations/service.py create mode 100644 tests/operations/__init__.py create mode 100644 tests/operations/test_documents.py create mode 100644 tests/operations/test_documents_transport.py diff --git a/src/readwise_sdk/operations/__init__.py b/src/readwise_sdk/operations/__init__.py new file mode 100644 index 0000000..8ce9cd3 --- /dev/null +++ b/src/readwise_sdk/operations/__init__.py @@ -0,0 +1,6 @@ +"""Canonical async-first operations for Readwise concepts.""" + +from readwise_sdk.operations.documents import DocumentOperations, DocumentStatistics +from readwise_sdk.operations.service import ReadwiseService + +__all__ = ["DocumentOperations", "DocumentStatistics", "ReadwiseService"] diff --git a/src/readwise_sdk/operations/documents.py b/src/readwise_sdk/operations/documents.py new file mode 100644 index 0000000..fd7ed13 --- /dev/null +++ b/src/readwise_sdk/operations/documents.py @@ -0,0 +1,304 @@ +"""Canonical async-first operations for Reader documents.""" + +from __future__ import annotations + +from collections import Counter +from collections.abc import AsyncIterator +from dataclasses import dataclass +from datetime import UTC, datetime +from typing import Protocol + +from readwise_sdk.errors import NotFoundError +from readwise_sdk.models import BulkResult, DocumentSearch, DocumentSearchResult, DocumentSummary +from readwise_sdk.models.results import OperationFailure +from readwise_sdk.v3.models import ( + CreateDocumentResult, + Document, + DocumentCategory, + DocumentCreate, + DocumentLocation, + DocumentUpdate, +) + + +class DocumentsResource(Protocol): + """The low-level document capabilities required by document operations.""" + + def iter( + self, + *, + location: DocumentLocation | None = None, + category: DocumentCategory | None = None, + updated_after: datetime | None = None, + tags: list[str] | None = None, + with_content: bool = False, + ) -> AsyncIterator[Document]: ... + + async def get(self, document_id: str, *, with_content: bool = False) -> Document | None: ... + + async def create(self, document: DocumentCreate) -> CreateDocumentResult: ... + + async def update( + self, + document_id: str, + update: DocumentUpdate, + ) -> CreateDocumentResult: ... + + async def delete(self, document_id: str) -> None: ... + + +@dataclass(frozen=True, slots=True) +class DocumentStatistics: + """The combined legacy inbox and reading-queue statistics projection.""" + + inbox_count: int + reading_list_count: int + archive_count: int + total_count: int + total_unread: int + by_category: dict[str, int] + oldest_inbox_item: Document | None + newest_inbox_item: Document | None + oldest_item_age_days: int | None + average_age_days: float | None + items_older_than_30_days: int + items_older_than_90_days: int + + +def _summary(document: Document) -> DocumentSummary: + """Project a document into the fields shared by list adapters.""" + return DocumentSummary( + id=document.id, + title=document.title, + author=document.author, + url=document.source_url or document.url, + category=document.category, + location=document.location, + tags=tuple(document.tags), + word_count=document.word_count, + reading_progress=document.reading_progress, + site_name=document.site_name, + published_date=document.published_date, + saved_at=document.saved_at, + ) + + +class DocumentOperations: + """Own filtering, composition, limits, and failure policy for documents.""" + + def __init__(self, resource: DocumentsResource) -> None: + self._resource = resource + + async def search(self, search: DocumentSearch) -> DocumentSearchResult: + """Return a bounded summary search using the current MCP title filter.""" + query = search.query.lower() if search.query else None + items: list[DocumentSummary] = [] + + async for document in self._resource.iter( + location=search.location, + category=search.category, + updated_after=search.updated_after, + tags=list(search.tags) or None, + ): + # Characterizes current MCP behavior: query matches only a present title. + # A document without a title is retained even when a query was supplied. + if query and document.title and query not in document.title.lower(): + continue + + items.append(_summary(document)) + if len(items) >= search.limit: + return DocumentSearchResult(items=items, truncated=True) + + return DocumentSearchResult(items=items, truncated=False) + + async def get(self, document_id: str, *, with_content: bool = False) -> Document | None: + """Get one document, preserving the resource's nullable not-found result.""" + return await self._resource.get(document_id, with_content=with_content) + + async def save(self, document: DocumentCreate) -> CreateDocumentResult: + """Save a document while preserving the current dropped-category bug.""" + # Characterizes current (buggy) save_to_reader behavior. A later stage + # deliberately restores category after the operation contract is established. + without_category = document.model_copy(update={"category": None}) + return await self._resource.create(without_category) + + async def update( + self, + document_id: str, + update: DocumentUpdate, + ) -> CreateDocumentResult: + """Update document metadata with the resource's partial-field payload.""" + return await self._resource.update(document_id, update) + + async def delete(self, document_id: str) -> None: + """Permanently delete one document.""" + await self._resource.delete(document_id) + + async def move( + self, + document_id: str, + location: DocumentLocation, + ) -> CreateDocumentResult: + """Move one document by applying a location-only update.""" + return await self.update(document_id, DocumentUpdate(location=location)) + + async def set_tags(self, document_id: str, tags: list[str]) -> CreateDocumentResult: + """Replace all document tags without normalizing the supplied list.""" + return await self.update(document_id, DocumentUpdate(tags=tags)) + + async def add_tag(self, document_id: str, tag: str) -> CreateDocumentResult: + """Add a tag if absent, retaining existing tag order and duplicates.""" + document = await self.get(document_id) + if document is None: + raise NotFoundError(f"Document {document_id} not found") + + tags = list(document.tags) + if tag not in tags: + tags.append(tag) + return await self.set_tags(document_id, tags) + + async def remove_tag(self, document_id: str, tag: str) -> CreateDocumentResult: + """Remove every exact occurrence of a tag from a document.""" + document = await self.get(document_id) + if document is None: + raise NotFoundError(f"Document {document_id} not found") + + tags = [existing for existing in document.tags if existing != tag] + return await self.set_tags(document_id, tags) + + async def inbox( + self, + *, + limit: int | None = None, + with_content: bool = False, + ) -> list[Document]: + """Materialize the Reader inbox view.""" + return await self._view( + DocumentLocation.NEW, + limit=limit, + with_content=with_content, + ) + + async def later( + self, + *, + limit: int | None = None, + with_content: bool = False, + ) -> list[Document]: + """Materialize the Reader reading-list view.""" + return await self._view( + DocumentLocation.LATER, + limit=limit, + with_content=with_content, + ) + + async def archive( + self, + *, + limit: int | None = None, + with_content: bool = False, + ) -> list[Document]: + """Materialize the Reader archive view.""" + return await self._view( + DocumentLocation.ARCHIVE, + limit=limit, + with_content=with_content, + ) + + async def _view( + self, + location: DocumentLocation, + *, + limit: int | None, + with_content: bool, + ) -> list[Document]: + documents: list[Document] = [] + async for document in self._resource.iter( + location=location, + with_content=with_content, + ): + if limit is not None and len(documents) >= limit: + break + documents.append(document) + return documents + + async def statistics(self) -> DocumentStatistics: + """Compose the exact legacy manager and reading-queue statistics.""" + inbox = await self.inbox() + reading_list = await self.later() + archive = await self.archive() + unread = inbox + reading_list + + by_category: Counter[str] = Counter() + for document in unread: + category = document.category.value if document.category else "unknown" + by_category[category] += 1 + + oldest_inbox_item: Document | None = None + newest_inbox_item: Document | None = None + if inbox: + sorted_inbox = sorted( + inbox, + key=lambda item: item.created_at or datetime.min.replace(tzinfo=UTC), + ) + oldest_inbox_item = sorted_inbox[0] + newest_inbox_item = sorted_inbox[-1] + + now = datetime.now(UTC) + ages_days = [ + (now - document.created_at).days + for document in unread + if document.created_at is not None + ] + + return DocumentStatistics( + inbox_count=len(inbox), + reading_list_count=len(reading_list), + archive_count=len(archive), + total_count=len(inbox) + len(reading_list) + len(archive), + total_unread=len(unread), + by_category=dict(by_category), + oldest_inbox_item=oldest_inbox_item, + newest_inbox_item=newest_inbox_item, + oldest_item_age_days=max(ages_days) if ages_days else None, + average_age_days=sum(ages_days) / len(ages_days) if ages_days else None, + items_older_than_30_days=sum(age > 30 for age in ages_days), + items_older_than_90_days=sum(age > 90 for age in ages_days), + ) + + async def bulk_move( + self, + document_ids: list[str], + location: DocumentLocation, + ) -> BulkResult[str]: + """Move documents sequentially and retain every item-specific failure.""" + succeeded: list[str] = [] + failures: list[OperationFailure] = [] + for document_id in document_ids: + try: + await self.move(document_id, location) + succeeded.append(document_id) + except Exception as error: + # Characterizes the managers' current broad partial-failure policy. + failures.append(OperationFailure(item=document_id, error=error)) + return BulkResult[str](succeeded=succeeded, failures=failures) + + async def bulk_set_tags( + self, + document_ids: list[str], + tags: list[str], + ) -> BulkResult[str]: + """Set tags sequentially and retain every item-specific failure.""" + succeeded: list[str] = [] + failures: list[OperationFailure] = [] + for document_id in document_ids: + try: + await self.set_tags(document_id, tags) + succeeded.append(document_id) + except Exception as error: + # Characterizes the managers' current broad partial-failure policy. + failures.append(OperationFailure(item=document_id, error=error)) + return BulkResult[str](succeeded=succeeded, failures=failures) + + +__all__ = ["DocumentOperations", "DocumentStatistics", "DocumentsResource"] diff --git a/src/readwise_sdk/operations/service.py b/src/readwise_sdk/operations/service.py new file mode 100644 index 0000000..e632aad --- /dev/null +++ b/src/readwise_sdk/operations/service.py @@ -0,0 +1,15 @@ +"""Container for canonical operation groups.""" + +from __future__ import annotations + +from readwise_sdk.operations.documents import DocumentOperations, DocumentsResource + + +class ReadwiseService: + """Compose canonical operations from low-level resources.""" + + def __init__(self, *, documents: DocumentsResource) -> None: + self.documents = DocumentOperations(documents) + + +__all__ = ["ReadwiseService"] diff --git a/tests/operations/__init__.py b/tests/operations/__init__.py new file mode 100644 index 0000000..85bac7b --- /dev/null +++ b/tests/operations/__init__.py @@ -0,0 +1 @@ +"""Tests for the canonical operations layer.""" diff --git a/tests/operations/test_documents.py b/tests/operations/test_documents.py new file mode 100644 index 0000000..ee0f4be --- /dev/null +++ b/tests/operations/test_documents.py @@ -0,0 +1,329 @@ +"""Unit tests for canonical document operations.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from datetime import UTC, datetime, timedelta + +import pytest + +from readwise_sdk.errors import NotFoundError +from readwise_sdk.models import DocumentSearch +from readwise_sdk.operations.documents import DocumentOperations +from readwise_sdk.operations.service import ReadwiseService +from readwise_sdk.v3.models import ( + CreateDocumentResult, + Document, + DocumentCategory, + DocumentCreate, + DocumentLocation, + DocumentUpdate, +) + + +class FakeDocumentsResource: + """Small in-memory seam matching the document resource contract.""" + + def __init__(self, documents: list[Document] | None = None) -> None: + self.documents = documents or [] + self.documents_by_id = {document.id: document for document in self.documents} + self.iter_calls: list[dict[str, object]] = [] + self.get_calls: list[tuple[str, bool]] = [] + self.create_calls: list[DocumentCreate] = [] + self.update_calls: list[tuple[str, DocumentUpdate]] = [] + self.delete_calls: list[str] = [] + self.fail_updates: dict[str, Exception] = {} + self.result = CreateDocumentResult(id="result-id", url="https://reader/result-id") + + async def iter( + self, + *, + location: DocumentLocation | None = None, + category: DocumentCategory | None = None, + updated_after: datetime | None = None, + tags: list[str] | None = None, + with_content: bool = False, + ) -> AsyncIterator[Document]: + self.iter_calls.append( + { + "location": location, + "category": category, + "updated_after": updated_after, + "tags": tags, + "with_content": with_content, + } + ) + for document in self.documents: + if location is not None and document.location is not location: + continue + if category is not None and document.category is not category: + continue + yield document + + async def get(self, document_id: str, *, with_content: bool = False) -> Document | None: + self.get_calls.append((document_id, with_content)) + return self.documents_by_id.get(document_id) + + async def create(self, document: DocumentCreate) -> CreateDocumentResult: + self.create_calls.append(document) + return self.result + + async def update( + self, + document_id: str, + update: DocumentUpdate, + ) -> CreateDocumentResult: + self.update_calls.append((document_id, update)) + if error := self.fail_updates.get(document_id): + raise error + return self.result.model_copy(update={"id": document_id}) + + async def delete(self, document_id: str) -> None: + self.delete_calls.append(document_id) + + +def document( + document_id: str, + *, + title: str | None = None, + author: str | None = None, + summary: str | None = None, + source_url: str | None = None, + location: DocumentLocation = DocumentLocation.NEW, + category: DocumentCategory | None = DocumentCategory.ARTICLE, + tags: list[str] | None = None, + created_at: datetime | None = None, +) -> Document: + """Build a compact Reader document fixture.""" + return Document( + id=document_id, + url=f"https://reader/{document_id}", + source_url=source_url, + title=title, + author=author, + summary=summary, + location=location, + category=category, + tags=tags or [], + created_at=created_at, + ) + + +@pytest.mark.asyncio +async def test_search_ports_mcp_filters_projection_limit_and_resource_arguments() -> None: + """Search is title-only, case-insensitive, bounded, and returns MCP summary fields.""" + updated_after = datetime(2025, 1, 2, 3, 4, tzinfo=UTC) + resource = FakeDocumentsResource( + [ + document( + "matching", + title="A PYTHON Guide", + author="Nobody", + source_url="https://source/article", + location=DocumentLocation.LATER, + tags=["python"], + ), + document( + "author-only", + title="Unrelated", + author="Python Author", + location=DocumentLocation.LATER, + ), + # Characterizes current MCP behavior: a missing title is not rejected by a query. + document("missing-title", title=None, location=DocumentLocation.LATER), + ] + ) + operations = DocumentOperations(resource) + + result = await operations.search( + DocumentSearch( + location=DocumentLocation.LATER, + category=DocumentCategory.ARTICLE, + updated_after=updated_after, + tags=("python", "sdk"), + query="python", + limit=2, + ) + ) + + assert [item.id for item in result.items] == ["matching", "missing-title"] + assert result.items[0].url == "https://source/article" + assert result.items[0].tags == ("python",) + assert result.truncated is True + assert resource.iter_calls == [ + { + "location": DocumentLocation.LATER, + "category": DocumentCategory.ARTICLE, + "updated_after": updated_after, + "tags": ["python", "sdk"], + "with_content": False, + } + ] + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("provided", "expected"), [(0, 1), (1000, 100)]) +async def test_search_uses_stage_five_limit_clamping(provided: int, expected: int) -> None: + """The canonical input preserves MCP's inclusive 1..100 limit clamp.""" + resource = FakeDocumentsResource([document(str(index), title="match") for index in range(101)]) + + result = await DocumentOperations(resource).search( + DocumentSearch(query="match", limit=provided) + ) + + assert len(result.items) == expected + + +@pytest.mark.asyncio +async def test_get_save_update_delete_and_move_delegate_typed_results() -> None: + """CRUD and movement preserve the resource models and location update semantics.""" + existing = document("doc-1", title="Old") + resource = FakeDocumentsResource([existing]) + operations = DocumentOperations(resource) + update = DocumentUpdate(title="New") + + assert await operations.get("doc-1", with_content=True) is existing + saved = await operations.save(DocumentCreate(url="https://example.com", title="Saved")) + updated = await operations.update("doc-1", update) + moved = await operations.move("doc-1", DocumentLocation.ARCHIVE) + assert saved is resource.result + assert updated.id == "doc-1" + assert moved.id == "doc-1" + await operations.delete("doc-1") + + assert resource.get_calls == [("doc-1", True)] + assert resource.create_calls[0].title == "Saved" + assert resource.update_calls == [ + ("doc-1", update), + ("doc-1", DocumentUpdate(location=DocumentLocation.ARCHIVE)), + ] + assert resource.delete_calls == ["doc-1"] + + +@pytest.mark.asyncio +async def test_save_intentionally_drops_category_to_preserve_current_mcp_bug() -> None: + """The accepted save category remains absent from the resource payload in PR 6.""" + resource = FakeDocumentsResource() + operations = DocumentOperations(resource) + create = DocumentCreate( + url="https://example.com", + category=DocumentCategory.ARTICLE, + location=DocumentLocation.LATER, + saved_using="readwise-mcp", + ) + + await operations.save(create) + + # Characterizes current (buggy) behavior; a later stage fixes category handling. + assert resource.create_calls[0].category is None + assert resource.create_calls[0].location is DocumentLocation.LATER + assert resource.create_calls[0].saved_using == "readwise-mcp" + + +@pytest.mark.asyncio +async def test_set_add_and_remove_tags_preserve_order_duplicates_and_not_found() -> None: + """Tag composition matches v3: set replaces, add deduplicates one tag, remove removes all.""" + existing = document("doc-1", tags=["one", "duplicate", "duplicate"]) + resource = FakeDocumentsResource([existing]) + operations = DocumentOperations(resource) + + await operations.set_tags("doc-1", ["raw", "raw"]) + await operations.add_tag("doc-1", "two") + await operations.add_tag("doc-1", "one") + await operations.remove_tag("doc-1", "duplicate") + + assert [update.tags for _, update in resource.update_calls] == [ + ["raw", "raw"], + ["one", "duplicate", "duplicate", "two"], + ["one", "duplicate", "duplicate"], + ["one"], + ] + + with pytest.raises(NotFoundError, match="Document missing not found"): + await operations.add_tag("missing", "tag") + with pytest.raises(NotFoundError, match="Document missing not found"): + await operations.remove_tag("missing", "tag") + + +@pytest.mark.asyncio +async def test_location_views_materialize_documents_with_cli_and_importer_limits() -> None: + """Inbox/later/archive are raw document views with optional content and bounded results.""" + resource = FakeDocumentsResource( + [ + document("new-1"), + document("new-2"), + document("later", location=DocumentLocation.LATER), + document("archive", location=DocumentLocation.ARCHIVE), + ] + ) + operations = DocumentOperations(resource) + + assert [item.id for item in await operations.inbox(limit=1, with_content=True)] == ["new-1"] + assert await operations.inbox(limit=0) == [] + assert [item.id for item in await operations.later()] == ["later"] + assert [item.id for item in await operations.archive()] == ["archive"] + assert resource.iter_calls[0]["with_content"] is True + + +@pytest.mark.asyncio +async def test_statistics_combines_manager_and_reading_inbox_semantics() -> None: + """Statistics retain counts, category grouping, inbox extrema, and queue age thresholds.""" + now = datetime.now(UTC) + newest = document("newest", created_at=now - timedelta(days=1)) + oldest = document( + "oldest", + category=None, + created_at=now - timedelta(days=31), + ) + later = document( + "later", + location=DocumentLocation.LATER, + category=DocumentCategory.PDF, + created_at=now - timedelta(days=91), + ) + archived = document("archived", location=DocumentLocation.ARCHIVE) + resource = FakeDocumentsResource([newest, oldest, later, archived]) + + stats = await DocumentOperations(resource).statistics() + + assert stats.inbox_count == 2 + assert stats.reading_list_count == 1 + assert stats.archive_count == 1 + assert stats.total_count == 4 + assert stats.total_unread == 3 + assert stats.by_category == {"article": 1, "unknown": 1, "pdf": 1} + assert stats.oldest_inbox_item is oldest + assert stats.newest_inbox_item is newest + assert stats.oldest_item_age_days == 91 + assert stats.average_age_days == pytest.approx(41.0) + assert stats.items_older_than_30_days == 2 + assert stats.items_older_than_90_days == 1 + + +@pytest.mark.asyncio +async def test_bulk_move_and_set_tags_keep_partial_failures_and_continue() -> None: + """Broad per-item failure suppression is retained in a declared BulkResult.""" + resource = FakeDocumentsResource() + archive_error = RuntimeError("archive failed") + tag_error = RuntimeError("tag failed") + resource.fail_updates = {"archive-bad": archive_error, "tag-bad": tag_error} + operations = DocumentOperations(resource) + + moved = await operations.bulk_move(["archive-ok", "archive-bad"], DocumentLocation.ARCHIVE) + tagged = await operations.bulk_set_tags(["tag-bad", "tag-ok"], ["one"]) + + assert moved.succeeded == ["archive-ok"] + assert moved.failures[0].item == "archive-bad" + assert moved.failures[0].error is archive_error + assert tagged.succeeded == ["tag-ok"] + assert tagged.failures[0].item == "tag-bad" + assert tagged.failures[0].error is tag_error + + +def test_service_wires_the_canonical_document_operations() -> None: + """The operation container exposes one DocumentOperations instance.""" + resource = FakeDocumentsResource() + + service = ReadwiseService(documents=resource) + + assert isinstance(service.documents, DocumentOperations) diff --git a/tests/operations/test_documents_transport.py b/tests/operations/test_documents_transport.py new file mode 100644 index 0000000..10cb85e --- /dev/null +++ b/tests/operations/test_documents_transport.py @@ -0,0 +1,140 @@ +"""Transport-backed integration tests for canonical document operations.""" + +from __future__ import annotations + +import json + +import httpx +import pytest +import respx + +from readwise_sdk.config import ClientConfig +from readwise_sdk.models import DocumentSearch +from readwise_sdk.operations.documents import DocumentOperations +from readwise_sdk.resources.v3.documents import AsyncDocumentsResource +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.v3.models import DocumentCategory, DocumentCreate, DocumentLocation + +V3_BASE = "https://readwise.io/api/v3" + + +def operations_with_transport() -> tuple[DocumentOperations, AsyncTransport]: + """Compose real resource and transport layers under the operation seam.""" + transport = AsyncTransport(ClientConfig(api_key="token")) + return DocumentOperations(AsyncDocumentsResource(transport)), transport + + +@respx.mock +@pytest.mark.asyncio +async def test_search_transport_keeps_single_tag_query_quirk_and_mcp_projection() -> None: + """All tags reach the resource, whose request intentionally sends only the first.""" + route = respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": "doc-1", + "url": "https://reader/doc-1", + "source_url": "https://source/article", + "title": "Python", + "location": "later", + "category": "article", + } + ], + "nextPageCursor": None, + }, + ) + ) + operations, transport = operations_with_transport() + + try: + result = await operations.search( + DocumentSearch( + location=DocumentLocation.LATER, + category=DocumentCategory.ARTICLE, + tags=("first", "second"), + query="python", + ) + ) + finally: + await transport.close() + + assert [item.url for item in result.items] == ["https://source/article"] + assert route.calls.last.request.url.params.get_list("tag") == ["first"] + assert "second" not in str(route.calls.last.request.url) + + +@respx.mock +@pytest.mark.asyncio +async def test_save_transport_preserves_buggy_category_omission() -> None: + """The real save payload omits category while retaining the other MCP fields.""" + route = respx.post(f"{V3_BASE}/save/").mock( + return_value=httpx.Response(201, json={"id": "doc-1", "url": "reader-url"}) + ) + operations, transport = operations_with_transport() + + try: + result = await operations.save( + DocumentCreate( + url="https://example.com", + title="Title", + category=DocumentCategory.ARTICLE, + location=DocumentLocation.LATER, + tags=["tag"], + saved_using="readwise-mcp", + ) + ) + finally: + await transport.close() + + assert result.id == "doc-1" + assert json.loads(route.calls.last.request.content) == { + "url": "https://example.com", + "title": "Title", + "location": "later", + "saved_using": "readwise-mcp", + "tags": ["tag"], + } + + +@respx.mock +@pytest.mark.asyncio +async def test_add_and_remove_tag_transport_compose_get_then_patch() -> None: + """Tag mutation fetches current tags and writes the exact merged replacement list.""" + get_route = respx.get(f"{V3_BASE}/list/").mock( + side_effect=[ + httpx.Response( + 200, + json={"results": [{"id": "doc-1", "url": "https://example.com", "tags": ["one"]}]}, + ), + httpx.Response( + 200, + json={ + "results": [ + { + "id": "doc-1", + "url": "https://example.com", + "tags": ["one", "two", "two"], + } + ] + }, + ), + ] + ) + patch_route = respx.patch(f"{V3_BASE}/update/doc-1/").mock( + return_value=httpx.Response(200, json={"id": "doc-1", "url": "reader-url"}) + ) + operations, transport = operations_with_transport() + + try: + await operations.add_tag("doc-1", "two") + first_payload = json.loads(patch_route.calls.last.request.content) + await operations.remove_tag("doc-1", "two") + second_payload = json.loads(patch_route.calls.last.request.content) + finally: + await transport.close() + + assert len(get_route.calls) == 2 + assert first_payload == {"tags": ["one", "two"]} + assert second_payload == {"tags": ["one"]} From d1e13e0f5d786828c20f17d3a48ff4054f07ae98 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 23:38:55 -0500 Subject: [PATCH 10/24] feat: highlight + book operations layer (stage 7) Additive; completes the operations core. New operations/highlights.py and operations/books.py (wired into service): highlight search/list/get/create/ update/delete, bulk tag/untag, export, truncation + partial-failure policy; book search/list/get, book-with-highlights, reading stats. Semantics ported verbatim from the sync/async managers, HighlightPusher, CLI, and MCP tools (text-substring search, 1-200/1-100 limit clamps, text[:8191] truncation, BookCategory validation incl. supplementals, grouped export). BulkResult retains original exceptions to reproduce legacy dict/list/bool returns later. MCP/CLI/managers not rewired yet. Gate green (657 passed); characterization unchanged; uv.lock unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/operations/__init__.py | 42 +- src/readwise_sdk/operations/books.py | 229 +++++++ src/readwise_sdk/operations/highlights.py | 649 ++++++++++++++++++++ src/readwise_sdk/operations/service.py | 52 +- tests/operations/test_books.py | 258 ++++++++ tests/operations/test_highlights.py | 441 +++++++++++++ tests/operations/test_readwise_transport.py | 124 ++++ 7 files changed, 1792 insertions(+), 3 deletions(-) create mode 100644 src/readwise_sdk/operations/books.py create mode 100644 src/readwise_sdk/operations/highlights.py create mode 100644 tests/operations/test_books.py create mode 100644 tests/operations/test_highlights.py create mode 100644 tests/operations/test_readwise_transport.py diff --git a/src/readwise_sdk/operations/__init__.py b/src/readwise_sdk/operations/__init__.py index 8ce9cd3..fa255ae 100644 --- a/src/readwise_sdk/operations/__init__.py +++ b/src/readwise_sdk/operations/__init__.py @@ -1,6 +1,46 @@ """Canonical async-first operations for Readwise concepts.""" +from readwise_sdk.operations.books import ( + BookOperations, + BookSearchResult, + BookWithHighlights, + ReadingStatistics, +) from readwise_sdk.operations.documents import DocumentOperations, DocumentStatistics +from readwise_sdk.operations.highlights import ( + FieldTruncation, + HighlightCreateResult, + HighlightDeleteResult, + HighlightExportGroup, + HighlightExportResult, + HighlightOperations, + HighlightPushInput, + HighlightPushResult, + HighlightSearchResult, + HighlightUpdateInput, + HighlightUpdateResult, + TruncationInfo, +) from readwise_sdk.operations.service import ReadwiseService -__all__ = ["DocumentOperations", "DocumentStatistics", "ReadwiseService"] +__all__ = [ + "BookOperations", + "BookSearchResult", + "BookWithHighlights", + "DocumentOperations", + "DocumentStatistics", + "FieldTruncation", + "HighlightCreateResult", + "HighlightDeleteResult", + "HighlightExportGroup", + "HighlightExportResult", + "HighlightOperations", + "HighlightPushInput", + "HighlightPushResult", + "HighlightSearchResult", + "HighlightUpdateInput", + "HighlightUpdateResult", + "ReadingStatistics", + "ReadwiseService", + "TruncationInfo", +] diff --git a/src/readwise_sdk/operations/books.py b/src/readwise_sdk/operations/books.py new file mode 100644 index 0000000..f9f9ac1 --- /dev/null +++ b/src/readwise_sdk/operations/books.py @@ -0,0 +1,229 @@ +"""Canonical async-first operations for Readwise books and sources.""" + +from __future__ import annotations + +import builtins +from collections import Counter +from collections.abc import AsyncIterator +from dataclasses import dataclass, field +from datetime import UTC, datetime, timedelta +from typing import Protocol + +from readwise_sdk.models import BookSearch, BookSummary +from readwise_sdk.v2.models import Book, BookCategory, Highlight + + +class BooksResource(Protocol): + """Low-level book capabilities required by book operations.""" + + def iter( + self, + *, + page_size: int = 100, + category: BookCategory | None = None, + source: str | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + last_highlight_after: datetime | None = None, + last_highlight_before: datetime | None = None, + ) -> AsyncIterator[Book]: ... + + async def get(self, book_id: int) -> Book: ... + + +class BookHighlightsResource(Protocol): + """The highlight iteration capability required for book composition.""" + + def iter( + self, + *, + page_size: int = 100, + book_id: int | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + highlighted_after: datetime | None = None, + highlighted_before: datetime | None = None, + ) -> AsyncIterator[Highlight]: ... + + +@dataclass(frozen=True, slots=True) +class BookSearchResult: + """Bounded semantic book summaries.""" + + items: list[BookSummary] = field(default_factory=list) + truncated: bool = False + + +@dataclass(frozen=True, slots=True) +class BookWithHighlights: + """One book and its materialized highlights.""" + + book: Book + highlights: list[Highlight] = field(default_factory=list) + + +@dataclass(frozen=True, slots=True) +class ReadingStatistics: + """Aggregated reading statistics from the legacy book managers.""" + + total_books: int + total_highlights: int + books_by_category: dict[str, int] + highlights_by_category: dict[str, int] + highlights_by_source: dict[str, int] + most_highlighted_books: list[tuple[str, int]] + recent_books: list[Book] + + +def _summary(book: Book) -> BookSummary: + """Project the fields shared by current CLI and MCP adapters.""" + return BookSummary( + id=book.id, + title=book.title, + author=book.author, + category=book.category, + source=book.source, + num_highlights=book.num_highlights, + source_url=book.source_url, + cover_image_url=book.cover_image_url, + last_highlight_at=book.last_highlight_at, + ) + + +class BookOperations: + """Own book filtering, composition, limits, and reading aggregations.""" + + def __init__(self, resource: BooksResource, highlights: BookHighlightsResource) -> None: + self._resource = resource + self._highlights = highlights + + async def search(self, search: BookSearch) -> BookSearchResult: + """Return bounded MCP-compatible summaries using title-only matching.""" + query = search.query.lower() if search.query else None + items: list[BookSummary] = [] + async for book in self._resource.iter( + category=search.category, + source=search.source, + updated_after=search.updated_after, + ): + if query and query not in book.title.lower(): + continue + items.append(_summary(book)) + if len(items) >= search.limit: + return BookSearchResult(items=items, truncated=True) + return BookSearchResult(items=items, truncated=False) + + async def list( + self, + *, + category: BookCategory | None = None, + source: str | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + last_highlight_after: datetime | None = None, + last_highlight_before: datetime | None = None, + limit: int | None = None, + ) -> builtins.list[Book]: + """Materialize raw books with the CLI's un-clamped limit behavior.""" + items: list[Book] = [] + async for book in self._resource.iter( + category=category, + source=source, + updated_after=updated_after, + updated_before=updated_before, + last_highlight_after=last_highlight_after, + last_highlight_before=last_highlight_before, + ): + if limit is not None and len(items) >= limit: + break + items.append(book) + return items + + async def get(self, book_id: int) -> Book: + """Get one book.""" + return await self._resource.get(book_id) + + async def with_highlights(self, book_id: int) -> BookWithHighlights: + """Compose a book with every highlight returned for its ID.""" + book = await self.get(book_id) + highlights = [item async for item in self._highlights.iter(book_id=book_id)] + return BookWithHighlights(book=book, highlights=highlights) + + async def recent( + self, + *, + days: int | None = None, + limit: int | None = None, + ) -> builtins.list[Book]: + """Reproduce manager date filtering, sorting, and truthy-limit slicing.""" + since = datetime.now(UTC) - timedelta(days=days) if days is not None else None + books = await self.list(updated_after=since) + books.sort( + key=lambda book: book.last_highlight_at or datetime.min.replace(tzinfo=UTC), + reverse=True, + ) + if limit: + books = books[:limit] + return books + + async def statistics(self) -> ReadingStatistics: + """Compose the exact legacy reading-statistics aggregations.""" + books = await self.list() + books_by_category: Counter[str] = Counter() + highlights_by_category: Counter[str] = Counter() + highlights_by_source: Counter[str] = Counter() + + for book in books: + category = book.category.value if book.category else "unknown" + books_by_category[category] += 1 + highlights_by_category[category] += book.num_highlights + source = book.source or "unknown" + highlights_by_source[source] += book.num_highlights + + most_highlighted = sorted( + [(book.title, book.num_highlights) for book in books], + key=lambda item: item[1], + reverse=True, + )[:10] + recent = await self.recent(days=30, limit=10) + return ReadingStatistics( + total_books=len(books), + total_highlights=sum(book.num_highlights for book in books), + books_by_category=dict(books_by_category), + highlights_by_category=dict(highlights_by_category), + highlights_by_source=dict(highlights_by_source), + most_highlighted_books=most_highlighted, + recent_books=recent, + ) + + async def search_items( + self, + query: str, + *, + case_sensitive: bool = False, + ) -> builtins.list[Book]: + """Reproduce manager search across book titles and authors.""" + normalized = query if case_sensitive else query.lower() + results: list[Book] = [] + async for book in self._resource.iter(): + title = book.title if case_sensitive else book.title.lower() + author = book.author or "" + if not case_sensitive: + author = author.lower() + if normalized in title or normalized in author: + results.append(book) + return results + + async def count(self) -> int: + """Count books using the manager's materialized-list behavior.""" + return len(await self.list()) + + +__all__ = [ + "BookOperations", + "BookHighlightsResource", + "BookSearchResult", + "BooksResource", + "BookWithHighlights", + "ReadingStatistics", +] diff --git a/src/readwise_sdk/operations/highlights.py b/src/readwise_sdk/operations/highlights.py new file mode 100644 index 0000000..88ac5f0 --- /dev/null +++ b/src/readwise_sdk/operations/highlights.py @@ -0,0 +1,649 @@ +"""Canonical async-first operations for Readwise highlights.""" + +from __future__ import annotations + +import builtins +from collections.abc import AsyncIterator, Callable +from dataclasses import dataclass, field +from datetime import UTC, datetime, timedelta +from typing import Protocol, cast + +from readwise_sdk.models import BulkResult, HighlightSearch, HighlightSummary +from readwise_sdk.models.results import OperationFailure +from readwise_sdk.v2.models import ( + BookCategory, + ExportBook, + Highlight, + HighlightCreate, + HighlightUpdate, + Tag, +) + +MAX_TEXT_LENGTH = 8191 +MAX_NOTE_LENGTH = 8191 +MAX_TITLE_LENGTH = 511 +MAX_AUTHOR_LENGTH = 1024 + + +class HighlightsResource(Protocol): + """Low-level highlight capabilities required by highlight operations.""" + + def iter( + self, + *, + page_size: int = 100, + book_id: int | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + highlighted_after: datetime | None = None, + highlighted_before: datetime | None = None, + ) -> AsyncIterator[Highlight]: ... + + async def get(self, highlight_id: int) -> Highlight: ... + + async def create(self, highlights: list[HighlightCreate]) -> list[int]: ... + + async def update(self, highlight_id: int, update: HighlightUpdate) -> Highlight: ... + + async def delete(self, highlight_id: int) -> None: ... + + +class HighlightTagsResource(Protocol): + """Low-level highlight-tag capabilities required by bulk operations.""" + + def iter_highlight(self, highlight_id: int) -> AsyncIterator[Tag]: ... + + async def create_highlight(self, highlight_id: int, name: str) -> Tag: ... + + async def delete_highlight(self, highlight_id: int, tag_id: int) -> None: ... + + +class ExportResource(Protocol): + """Low-level grouped-export capability required by highlight export.""" + + def iter( + self, + *, + updated_after: datetime | None = None, + book_ids: list[int] | None = None, + include_deleted: bool = False, + ) -> AsyncIterator[ExportBook]: ... + + +@dataclass(frozen=True, slots=True) +class FieldTruncation: + """One field shortened by an operation-owned input policy.""" + + field_name: str + original_length: int + truncated_length: int + + @property + def chars_removed(self) -> int: + """Return the number of characters removed.""" + return self.original_length - self.truncated_length + + +@dataclass(frozen=True, slots=True) +class TruncationInfo: + """Ordered details for every field shortened in one request.""" + + fields: tuple[FieldTruncation, ...] = () + + @property + def truncated_field_names(self) -> list[str]: + """Return field names in the legacy reporting order.""" + return [item.field_name for item in self.fields] + + +@dataclass(frozen=True, slots=True) +class HighlightPushInput: + """Pusher-compatible input retained independently from protocol models.""" + + text: str | None + title: str | None + author: str | None = None + source_url: str | None = None + source_type: str = "readwise_sdk" + category: BookCategory | None = None + note: str | None = None + location: int | None = None + location_type: str | None = None + highlighted_at: datetime | None = None + tags: tuple[str, ...] = () + + +@dataclass(frozen=True, slots=True) +class HighlightUpdateInput: + """One pusher-compatible update request.""" + + highlight_id: int + text: str | None = None + note: str | None = None + location: int | None = None + location_type: str | None = None + + +@dataclass(frozen=True, slots=True) +class HighlightCreateResult: + """Created IDs plus operation-owned truncation metadata.""" + + ids: list[int] + was_truncated: bool = False + truncation_info: TruncationInfo | None = None + + +@dataclass(frozen=True, slots=True) +class HighlightPushResult: + """One ordered result from the pusher-compatible batch policy.""" + + original: HighlightPushInput + highlight_id: int | None = None + error: Exception | str | None = None + was_truncated: bool = False + truncation_info: TruncationInfo | None = None + + @property + def success(self) -> bool: + """Return whether an ID was produced without an error.""" + return self.error is None and self.highlight_id is not None + + @property + def error_message(self) -> str | None: + """Return adapter-ready error text without discarding exceptions.""" + return str(self.error) if self.error is not None else None + + +@dataclass(frozen=True, slots=True) +class HighlightUpdateResult: + """One ordered result from the pusher-compatible update policy.""" + + highlight_id: int + highlight: Highlight | None = None + error: Exception | None = None + was_truncated: bool = False + truncation_info: TruncationInfo | None = None + + @property + def success(self) -> bool: + """Return whether the update produced a highlight.""" + return self.error is None and self.highlight is not None + + +@dataclass(frozen=True, slots=True) +class HighlightDeleteResult: + """One ordered result from the pusher-compatible delete policy.""" + + highlight_id: int + error: Exception | None = None + + @property + def success(self) -> bool: + """Return whether deletion completed without an exception.""" + return self.error is None + + +@dataclass(frozen=True, slots=True) +class HighlightSearchResult: + """Bounded semantic highlight summaries.""" + + items: list[HighlightSummary] = field(default_factory=list) + truncated: bool = False + + +@dataclass(frozen=True, slots=True) +class HighlightExportGroup: + """One exported book with its projected highlights nested inside.""" + + book_id: int + title: str + author: str | None = None + category: BookCategory | None = None + source: str | None = None + source_url: str | None = None + highlights: list[HighlightSummary] = field(default_factory=list) + + +@dataclass(frozen=True, slots=True) +class HighlightExportResult: + """A bounded number of grouped export books.""" + + items: list[HighlightExportGroup] = field(default_factory=list) + truncated: bool = False + + +def _summary(highlight: Highlight) -> HighlightSummary: + """Project the fields shared by current CLI and MCP adapters.""" + return HighlightSummary( + id=highlight.id, + text=highlight.text, + note=highlight.note, + book_id=highlight.book_id, + color=highlight.color, + location=highlight.location, + highlighted_at=highlight.highlighted_at, + tags=tuple(tag.name for tag in highlight.tags), + ) + + +def _truncate_with_ellipsis(value: str | None, maximum: int) -> tuple[str | None, bool]: + """Reproduce HighlightPusher's maximum-length ellipsis policy.""" + if value is None or len(value) <= maximum: + return value, False + return value[: maximum - 3] + "...", True + + +def _truncation( + field_name: str, + original: str | None, + truncated: bool, + maximum: int, +) -> FieldTruncation | None: + if not truncated or original is None: + return None + return FieldTruncation(field_name, len(original), maximum) + + +def _prepare_push( + item: HighlightPushInput, + *, + auto_truncate: bool, +) -> tuple[HighlightCreate, TruncationInfo | None]: + text = item.text + note = item.note + title = item.title + author = item.author + details: list[FieldTruncation] = [] + + if auto_truncate: + original_text, original_note = text, note + original_title, original_author = title, author + text, text_cut = _truncate_with_ellipsis(text, MAX_TEXT_LENGTH) + note, note_cut = _truncate_with_ellipsis(note, MAX_NOTE_LENGTH) + title, title_cut = _truncate_with_ellipsis(title, MAX_TITLE_LENGTH) + author, author_cut = _truncate_with_ellipsis(author, MAX_AUTHOR_LENGTH) + for detail in ( + _truncation("text", original_text, text_cut, MAX_TEXT_LENGTH), + _truncation("note", original_note, note_cut, MAX_NOTE_LENGTH), + _truncation("title", original_title, title_cut, MAX_TITLE_LENGTH), + _truncation("author", original_author, author_cut, MAX_AUTHOR_LENGTH), + ): + if detail is not None: + details.append(detail) + if text is None: + # Characterizes the current pusher's type-bypassing None quirk. + text = "" + + request = HighlightCreate( + # The cast preserves HighlightPusher's runtime validation when + # auto-truncation is disabled and a caller bypasses the declared type. + text=cast(str, text), + title=title, + author=author, + source_url=item.source_url, + source_type=item.source_type, + category=item.category, + note=note, + location=item.location, + location_type=item.location_type, + highlighted_at=item.highlighted_at, + ) + return request, TruncationInfo(tuple(details)) if details else None + + +def _prepare_update( + item: HighlightUpdateInput, + *, + auto_truncate: bool, +) -> tuple[HighlightUpdate, TruncationInfo | None]: + text = item.text + note = item.note + details: list[FieldTruncation] = [] + if auto_truncate: + original_text, original_note = text, note + text, text_cut = _truncate_with_ellipsis(text, MAX_TEXT_LENGTH) + note, note_cut = _truncate_with_ellipsis(note, MAX_NOTE_LENGTH) + for detail in ( + _truncation("text", original_text, text_cut, MAX_TEXT_LENGTH), + _truncation("note", original_note, note_cut, MAX_NOTE_LENGTH), + ): + if detail is not None: + details.append(detail) + + request = HighlightUpdate( + text=text, + note=note, + location=item.location, + location_type=item.location_type, + ) + return request, TruncationInfo(tuple(details)) if details else None + + +def _parse_category(category: str | BookCategory | None) -> BookCategory | None: + if category is None or isinstance(category, BookCategory): + return category + try: + return BookCategory(category) + except ValueError: + raise ValueError(f"Invalid category '{category}'") from None + + +class HighlightOperations: + """Own highlight filtering, limits, truncation, and partial-failure policy.""" + + def __init__( + self, + resource: HighlightsResource, + tags: HighlightTagsResource, + export_resource: ExportResource, + ) -> None: + self._resource = resource + self._tags = tags + self._export = export_resource + + async def search(self, search: HighlightSearch) -> HighlightSearchResult: + """Return bounded MCP-compatible summaries using text-only matching.""" + query = search.query.lower() if search.query else None + items: list[HighlightSummary] = [] + async for highlight in self._resource.iter( + book_id=search.book_id, + updated_after=search.updated_after, + ): + if query and query not in highlight.text.lower(): + continue + items.append(_summary(highlight)) + if len(items) >= search.limit: + return HighlightSearchResult(items=items, truncated=True) + return HighlightSearchResult(items=items, truncated=False) + + async def list( + self, + *, + book_id: int | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + highlighted_after: datetime | None = None, + highlighted_before: datetime | None = None, + limit: int | None = None, + ) -> builtins.list[Highlight]: + """Materialize raw highlights with the CLI's un-clamped limit behavior.""" + items: list[Highlight] = [] + async for highlight in self._resource.iter( + book_id=book_id, + updated_after=updated_after, + updated_before=updated_before, + highlighted_after=highlighted_after, + highlighted_before=highlighted_before, + ): + if limit is not None and len(items) >= limit: + break + items.append(highlight) + return items + + async def get(self, highlight_id: int) -> Highlight: + """Get one highlight.""" + return await self._resource.get(highlight_id) + + async def create(self, highlight: HighlightCreate) -> builtins.list[int]: + """Create one typed highlight and retain every ID returned by v2.""" + return await self._resource.create([highlight]) + + async def create_from_fields( + self, + *, + text: str, + title: str | None = None, + author: str | None = None, + source_url: str | None = None, + note: str | None = None, + category: str | BookCategory | None = None, + highlighted_at: datetime | None = None, + ) -> HighlightCreateResult: + """Create with MCP's raw 8191-character text slice and enum validation.""" + truncated = len(text) > MAX_TEXT_LENGTH + request = HighlightCreate( + text=text[:MAX_TEXT_LENGTH], + title=title, + author=author, + source_url=source_url, + note=note, + category=_parse_category(category), + highlighted_at=highlighted_at, + ) + ids = await self.create(request) + info = None + if truncated: + info = TruncationInfo((FieldTruncation("text", len(text), MAX_TEXT_LENGTH),)) + return HighlightCreateResult(ids=ids, was_truncated=truncated, truncation_info=info) + + async def push_batch( + self, + highlights: builtins.list[HighlightPushInput], + *, + auto_truncate: bool = True, + ) -> builtins.list[HighlightPushResult]: + """Apply the pusher's one-request batch and all-input failure policy.""" + if not highlights: + return [] + + requests: list[HighlightCreate] = [] + infos: list[TruncationInfo | None] = [] + # Conversion intentionally precedes the API try block, matching HighlightPusher. + for item in highlights: + request, info = _prepare_push(item, auto_truncate=auto_truncate) + requests.append(request) + infos.append(info) + + try: + ids = await self._resource.create(requests) + except Exception as error: + # Characterizes current broad, whole-batch pusher failure handling. + return [ + HighlightPushResult( + original=item, + error=error, + was_truncated=infos[index] is not None, + truncation_info=infos[index], + ) + for index, item in enumerate(highlights) + ] + + results: list[HighlightPushResult] = [] + for index, item in enumerate(highlights): + highlight_id = ids[index] if index < len(ids) else None + results.append( + HighlightPushResult( + original=item, + highlight_id=highlight_id, + error=None if highlight_id is not None else "No API result returned", + was_truncated=infos[index] is not None, + truncation_info=infos[index], + ) + ) + return results + + async def update(self, highlight_id: int, update: HighlightUpdate) -> Highlight: + """Update one typed highlight.""" + return await self._resource.update(highlight_id, update) + + async def update_batch( + self, + updates: builtins.list[HighlightUpdateInput], + *, + auto_truncate: bool = True, + ) -> builtins.list[HighlightUpdateResult]: + """Update sequentially and isolate every pusher-compatible failure.""" + results: list[HighlightUpdateResult] = [] + for item in updates: + try: + request, info = _prepare_update(item, auto_truncate=auto_truncate) + highlight = await self.update(item.highlight_id, request) + results.append( + HighlightUpdateResult( + highlight_id=item.highlight_id, + highlight=highlight, + was_truncated=info is not None, + truncation_info=info, + ) + ) + except Exception as error: + # Characterizes current broad per-update pusher failure handling. + results.append(HighlightUpdateResult(highlight_id=item.highlight_id, error=error)) + return results + + async def delete(self, highlight_id: int) -> None: + """Delete one highlight.""" + await self._resource.delete(highlight_id) + + async def delete_batch( + self, highlight_ids: builtins.list[int] + ) -> builtins.list[HighlightDeleteResult]: + """Delete sequentially and isolate every pusher-compatible failure.""" + results: list[HighlightDeleteResult] = [] + for highlight_id in highlight_ids: + try: + await self.delete(highlight_id) + results.append(HighlightDeleteResult(highlight_id)) + except Exception as error: + # Characterizes current broad per-delete pusher failure handling. + results.append(HighlightDeleteResult(highlight_id, error)) + return results + + async def search_items( + self, + query: str, + *, + case_sensitive: bool = False, + ) -> builtins.list[Highlight]: + """Reproduce manager search across highlight text and notes.""" + normalized = query if case_sensitive else query.lower() + results: list[Highlight] = [] + async for highlight in self._resource.iter(): + text = highlight.text if case_sensitive else highlight.text.lower() + note = highlight.note or "" + if not case_sensitive: + note = note.lower() + if normalized in text or normalized in note: + results.append(highlight) + return results + + async def since( + self, + *, + days: int | None = None, + hours: int | None = None, + since: datetime | None = None, + ) -> builtins.list[Highlight]: + """Reproduce manager time-window precedence and validation.""" + if since is None: + if days is not None: + since = datetime.now(UTC) - timedelta(days=days) + elif hours is not None: + since = datetime.now(UTC) - timedelta(hours=hours) + else: + raise ValueError("Must specify days, hours, or since") + return await self.list(updated_after=since) + + async def with_notes(self) -> builtins.list[Highlight]: + """Materialize highlights whose note is truthy.""" + return [highlight async for highlight in self._resource.iter() if highlight.note] + + async def filter( + self, + predicate: Callable[[Highlight], bool], + ) -> AsyncIterator[Highlight]: + """Retain manager-compatible lazy predicate filtering.""" + async for highlight in self._resource.iter(): + if predicate(highlight): + yield highlight + + async def count(self) -> int: + """Count every highlight without materializing them.""" + count = 0 + async for _ in self._resource.iter(): + count += 1 + return count + + async def bulk_tag(self, highlight_ids: builtins.list[int], tag: str) -> BulkResult[int]: + """Tag sequentially and retain every manager-compatible failure.""" + succeeded: list[int] = [] + failures: list[OperationFailure] = [] + for highlight_id in highlight_ids: + try: + await self._tags.create_highlight(highlight_id, tag) + succeeded.append(highlight_id) + except Exception as error: + # Characterizes current broad per-item manager failure handling. + failures.append(OperationFailure(item=highlight_id, error=error)) + return BulkResult[int](succeeded=succeeded, failures=failures) + + async def bulk_untag(self, highlight_ids: builtins.list[int], tag: str) -> BulkResult[int]: + """Delete only the first exact tag match; missing tags count as success.""" + succeeded: list[int] = [] + failures: list[OperationFailure] = [] + for highlight_id in highlight_ids: + try: + match = None + async for existing in self._tags.iter_highlight(highlight_id): + if existing.name == tag: + match = existing + break + if match is not None: + await self._tags.delete_highlight(highlight_id, match.id) + succeeded.append(highlight_id) + except Exception as error: + # Characterizes current broad per-item manager failure handling. + failures.append(OperationFailure(item=highlight_id, error=error)) + return BulkResult[int](succeeded=succeeded, failures=failures) + + async def export( + self, + *, + updated_after: datetime | None = None, + book_ids: builtins.list[int] | None = None, + limit: int = 20, + ) -> HighlightExportResult: + """Return MCP-compatible grouped summaries with a 1..100 book limit.""" + bounded_limit = min(max(limit, 1), 100) + items: list[HighlightExportGroup] = [] + async for book in self._export.iter( + updated_after=updated_after, + book_ids=book_ids, + ): + items.append( + HighlightExportGroup( + book_id=book.user_book_id, + title=book.title, + author=book.author, + category=book.category, + source=book.source, + source_url=book.source_url, + highlights=[_summary(highlight) for highlight in book.highlights], + ) + ) + if len(items) >= bounded_limit: + return HighlightExportResult(items=items, truncated=True) + return HighlightExportResult(items=items, truncated=False) + + +__all__ = [ + "ExportResource", + "FieldTruncation", + "HighlightCreateResult", + "HighlightDeleteResult", + "HighlightExportGroup", + "HighlightExportResult", + "HighlightOperations", + "HighlightPushInput", + "HighlightPushResult", + "HighlightSearchResult", + "HighlightTagsResource", + "HighlightUpdateInput", + "HighlightUpdateResult", + "HighlightsResource", + "MAX_AUTHOR_LENGTH", + "MAX_NOTE_LENGTH", + "MAX_TEXT_LENGTH", + "MAX_TITLE_LENGTH", + "TruncationInfo", +] diff --git a/src/readwise_sdk/operations/service.py b/src/readwise_sdk/operations/service.py index e632aad..54b5cd6 100644 --- a/src/readwise_sdk/operations/service.py +++ b/src/readwise_sdk/operations/service.py @@ -2,14 +2,62 @@ from __future__ import annotations +from readwise_sdk.operations.books import BookHighlightsResource, BookOperations, BooksResource from readwise_sdk.operations.documents import DocumentOperations, DocumentsResource +from readwise_sdk.operations.highlights import ( + ExportResource, + HighlightOperations, + HighlightsResource, + HighlightTagsResource, +) class ReadwiseService: """Compose canonical operations from low-level resources.""" - def __init__(self, *, documents: DocumentsResource) -> None: - self.documents = DocumentOperations(documents) + def __init__( + self, + *, + documents: DocumentsResource | None = None, + highlights: HighlightsResource | None = None, + highlight_tags: HighlightTagsResource | None = None, + export: ExportResource | None = None, + books: BooksResource | None = None, + book_highlights: BookHighlightsResource | None = None, + ) -> None: + self._documents = DocumentOperations(documents) if documents is not None else None + self._highlights = ( + HighlightOperations(highlights, highlight_tags, export) + if highlights is not None and highlight_tags is not None and export is not None + else None + ) + highlights_for_books = book_highlights or highlights + self._books = ( + BookOperations(books, highlights_for_books) + if books is not None and highlights_for_books is not None + else None + ) + + @property + def documents(self) -> DocumentOperations: + """Return configured document operations.""" + if self._documents is None: + raise RuntimeError("Document operations were not configured") + return self._documents + + @property + def highlights(self) -> HighlightOperations: + """Return configured highlight operations.""" + if self._highlights is None: + raise RuntimeError("Highlight operations were not configured") + return self._highlights + + @property + def books(self) -> BookOperations: + """Return configured book operations.""" + if self._books is None: + raise RuntimeError("Book operations were not configured") + return self._books __all__ = ["ReadwiseService"] diff --git a/tests/operations/test_books.py b/tests/operations/test_books.py new file mode 100644 index 0000000..ed98f8f --- /dev/null +++ b/tests/operations/test_books.py @@ -0,0 +1,258 @@ +"""Unit tests for canonical book operations.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from datetime import UTC, datetime, timedelta + +import pytest + +from readwise_sdk.models import BookSearch +from readwise_sdk.operations.books import BookOperations +from readwise_sdk.operations.service import ReadwiseService +from readwise_sdk.v2.models import Book, BookCategory, Highlight + + +class FakeBooksResource: + """In-memory seam matching the v2 book resource contract.""" + + def __init__(self, books: list[Book] | None = None) -> None: + self.books = books or [] + self.iter_calls: list[dict[str, object]] = [] + self.get_calls: list[int] = [] + + async def iter( + self, + *, + page_size: int = 100, + category: BookCategory | None = None, + source: str | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + last_highlight_after: datetime | None = None, + last_highlight_before: datetime | None = None, + ) -> AsyncIterator[Book]: + self.iter_calls.append( + { + "page_size": page_size, + "category": category, + "source": source, + "updated_after": updated_after, + "updated_before": updated_before, + "last_highlight_after": last_highlight_after, + "last_highlight_before": last_highlight_before, + } + ) + for item in self.books: + if category is not None and item.category is not category: + continue + if source is not None and item.source != source: + continue + yield item + + async def get(self, book_id: int) -> Book: + self.get_calls.append(book_id) + return next(item for item in self.books if item.id == book_id) + + +class FakeBookHighlightsResource: + """Minimal highlight seam used for book composition.""" + + def __init__(self, highlights: list[Highlight] | None = None) -> None: + self.highlights = highlights or [] + self.iter_calls: list[int | None] = [] + + async def iter( + self, + *, + page_size: int = 100, + book_id: int | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + highlighted_after: datetime | None = None, + highlighted_before: datetime | None = None, + ) -> AsyncIterator[Highlight]: + self.iter_calls.append(book_id) + for item in self.highlights: + if book_id is None or item.book_id == book_id: + yield item + + +def book( + book_id: int, + title: str, + *, + author: str | None = None, + category: BookCategory | None = BookCategory.BOOKS, + source: str | None = None, + num_highlights: int = 0, + last_highlight_at: datetime | None = None, +) -> Book: + """Build a compact book fixture.""" + return Book( + id=book_id, + title=title, + author=author, + category=category, + source=source, + num_highlights=num_highlights, + last_highlight_at=last_highlight_at, + ) + + +def operations( + books: FakeBooksResource, + highlights: FakeBookHighlightsResource | None = None, +) -> BookOperations: + """Compose book operations over local resource seams.""" + return BookOperations(books, highlights or FakeBookHighlightsResource()) + + +@pytest.mark.asyncio +async def test_search_ports_mcp_title_filter_projection_limit_and_resource_arguments() -> None: + """Canonical search is title-only, case-insensitive, bounded, and projected.""" + updated_after = datetime(2025, 1, 2, 3, 4, tzinfo=UTC) + resource = FakeBooksResource( + [ + book(1, "A PYTHON Book", author="Nobody", source="kindle", num_highlights=0), + book(2, "Unrelated", author="Python Author", source="kindle"), + book(3, "Python Again", source="kindle"), + ] + ) + + result = await operations(resource).search( + BookSearch( + category=BookCategory.BOOKS, + source="kindle", + updated_after=updated_after, + query="python", + limit=2, + ) + ) + + assert [item.id for item in result.items] == [1, 3] + assert result.items[0].num_highlights == 0 + assert result.truncated is True + assert resource.iter_calls == [ + { + "page_size": 100, + "category": BookCategory.BOOKS, + "source": "kindle", + "updated_after": updated_after, + "updated_before": None, + "last_highlight_after": None, + "last_highlight_before": None, + } + ] + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("provided", "expected"), [(0, 1), (1000, 100)]) +async def test_search_uses_stage_five_limit_clamping(provided: int, expected: int) -> None: + """Book searches retain MCP's inclusive 1..100 clamp.""" + resource = FakeBooksResource([book(index, f"match-{index}") for index in range(101)]) + + result = await operations(resource).search(BookSearch(query="match", limit=provided)) + + assert len(result.items) == expected + + +@pytest.mark.asyncio +async def test_list_get_and_manager_search_variants_preserve_raw_semantics() -> None: + """Raw listing/get and manager title-or-author search remain available.""" + title_match = book(1, "Python", author="One") + author_match = book(2, "Other", author="Python Person") + lower = book(3, "python", author=None) + resource = FakeBooksResource([title_match, author_match, lower]) + operation = operations(resource) + + assert await operation.list(limit=2) == [title_match, author_match] + assert await operation.list(limit=0) == [] + assert await operation.get(2) is author_match + assert await operation.search_items("python") == [title_match, author_match, lower] + assert await operation.search_items("Python", case_sensitive=True) == [ + title_match, + author_match, + ] + assert await operation.count() == 3 + + +@pytest.mark.asyncio +async def test_book_with_highlights_composes_exact_book_and_materialized_list() -> None: + """Book composition gets one book and all highlights filtered by its ID.""" + selected = book(7, "Selected") + books = FakeBooksResource([selected]) + first = Highlight(id=1, text="One", book_id=7) + second = Highlight(id=2, text="Two", book_id=8) + highlights = FakeBookHighlightsResource([first, second]) + + result = await operations(books, highlights).with_highlights(7) + + assert result.book is selected + assert result.highlights == [first] + assert books.get_calls == [7] + assert highlights.iter_calls == [7] + + +@pytest.mark.asyncio +async def test_recent_books_preserves_sort_and_truthy_limit_quirks() -> None: + """Recent books sort missing dates last; zero means no slice and negative slices from the end.""" + now = datetime.now(UTC) + oldest = book(1, "Old", last_highlight_at=now - timedelta(days=10)) + missing = book(2, "Missing", last_highlight_at=None) + newest = book(3, "New", last_highlight_at=now - timedelta(days=1)) + operation = operations(FakeBooksResource([oldest, missing, newest])) + + assert await operation.recent(days=30, limit=0) == [newest, oldest, missing] + assert await operation.recent(days=30, limit=-1) == [newest, oldest] + + +@pytest.mark.asyncio +async def test_reading_statistics_preserve_all_legacy_aggregations_and_second_query() -> None: + """Statistics retain unknown buckets, top ten ordering, and a separate recent-books request.""" + now = datetime.now(UTC) + books = FakeBooksResource( + [ + book( + 1, + "Book", + category=BookCategory.BOOKS, + source="kindle", + num_highlights=10, + last_highlight_at=now - timedelta(days=2), + ), + book( + 2, + "Unknown", + category=None, + source=None, + num_highlights=5, + last_highlight_at=None, + ), + ] + ) + + stats = await operations(books).statistics() + + assert stats.total_books == 2 + assert stats.total_highlights == 15 + assert stats.books_by_category == {"books": 1, "unknown": 1} + assert stats.highlights_by_category == {"books": 10, "unknown": 5} + assert stats.highlights_by_source == {"kindle": 10, "unknown": 5} + assert stats.most_highlighted_books == [("Book", 10), ("Unknown", 5)] + assert [item.id for item in stats.recent_books] == [1, 2] + assert len(books.iter_calls) == 2 + recent_cutoff = books.iter_calls[1]["updated_after"] + assert isinstance(recent_cutoff, datetime) + assert now - timedelta(days=31) < recent_cutoff < now - timedelta(days=29) + + +def test_service_wires_canonical_book_operations() -> None: + """The service composes books from book and highlight resources.""" + service = ReadwiseService( + documents=None, + books=FakeBooksResource(), + book_highlights=FakeBookHighlightsResource(), + ) + + assert isinstance(service.books, BookOperations) diff --git a/tests/operations/test_highlights.py b/tests/operations/test_highlights.py new file mode 100644 index 0000000..b8e7117 --- /dev/null +++ b/tests/operations/test_highlights.py @@ -0,0 +1,441 @@ +"""Unit tests for canonical highlight operations.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from datetime import UTC, datetime + +import pytest + +from readwise_sdk.models import HighlightSearch +from readwise_sdk.operations.highlights import ( + MAX_AUTHOR_LENGTH, + MAX_NOTE_LENGTH, + MAX_TEXT_LENGTH, + MAX_TITLE_LENGTH, + HighlightOperations, + HighlightPushInput, + HighlightUpdateInput, +) +from readwise_sdk.operations.service import ReadwiseService +from readwise_sdk.v2.models import ( + BookCategory, + ExportBook, + Highlight, + HighlightColor, + HighlightCreate, + HighlightUpdate, + Tag, +) + + +class FakeHighlightsResource: + """In-memory seam matching the v2 highlight resource contract.""" + + def __init__(self, highlights: list[Highlight] | None = None) -> None: + self.highlights = highlights or [] + self.iter_calls: list[dict[str, object]] = [] + self.get_calls: list[int] = [] + self.create_calls: list[list[HighlightCreate]] = [] + self.update_calls: list[tuple[int, HighlightUpdate]] = [] + self.delete_calls: list[int] = [] + self.created_ids: list[int] = [101] + self.create_error: Exception | None = None + self.update_errors: dict[int, Exception] = {} + self.delete_errors: dict[int, Exception] = {} + + async def iter( + self, + *, + page_size: int = 100, + book_id: int | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + highlighted_after: datetime | None = None, + highlighted_before: datetime | None = None, + ) -> AsyncIterator[Highlight]: + self.iter_calls.append( + { + "page_size": page_size, + "book_id": book_id, + "updated_after": updated_after, + "updated_before": updated_before, + "highlighted_after": highlighted_after, + "highlighted_before": highlighted_before, + } + ) + for item in self.highlights: + if book_id is not None and item.book_id != book_id: + continue + yield item + + async def get(self, highlight_id: int) -> Highlight: + self.get_calls.append(highlight_id) + return next(item for item in self.highlights if item.id == highlight_id) + + async def create(self, highlights: list[HighlightCreate]) -> list[int]: + self.create_calls.append(highlights) + if self.create_error is not None: + raise self.create_error + return self.created_ids + + async def update(self, highlight_id: int, update: HighlightUpdate) -> Highlight: + self.update_calls.append((highlight_id, update)) + if error := self.update_errors.get(highlight_id): + raise error + return Highlight(id=highlight_id, text=update.text or "unchanged", note=update.note) + + async def delete(self, highlight_id: int) -> None: + self.delete_calls.append(highlight_id) + if error := self.delete_errors.get(highlight_id): + raise error + + +class FakeHighlightTagsResource: + """In-memory seam for highlight tag composition and failures.""" + + def __init__(self) -> None: + self.tags: dict[int, list[Tag]] = {} + self.create_calls: list[tuple[int, str]] = [] + self.delete_calls: list[tuple[int, int]] = [] + self.create_errors: dict[int, Exception] = {} + self.iter_errors: dict[int, Exception] = {} + self.delete_errors: dict[int, Exception] = {} + + async def iter_highlight(self, highlight_id: int) -> AsyncIterator[Tag]: + if error := self.iter_errors.get(highlight_id): + raise error + for tag in self.tags.get(highlight_id, []): + yield tag + + async def create_highlight(self, highlight_id: int, name: str) -> Tag: + self.create_calls.append((highlight_id, name)) + if error := self.create_errors.get(highlight_id): + raise error + return Tag(id=highlight_id * 10, name=name) + + async def delete_highlight(self, highlight_id: int, tag_id: int) -> None: + self.delete_calls.append((highlight_id, tag_id)) + if error := self.delete_errors.get(highlight_id): + raise error + + +class FakeExportResource: + """In-memory seam for already-grouped v2 export results.""" + + def __init__(self, books: list[ExportBook] | None = None) -> None: + self.books = books or [] + self.iter_calls: list[dict[str, object]] = [] + + async def iter( + self, + *, + updated_after: datetime | None = None, + book_ids: list[int] | None = None, + include_deleted: bool = False, + ) -> AsyncIterator[ExportBook]: + self.iter_calls.append( + { + "updated_after": updated_after, + "book_ids": book_ids, + "include_deleted": include_deleted, + } + ) + for book in self.books: + yield book + + +def highlight( + highlight_id: int, + text: str, + *, + note: str | None = None, + book_id: int | None = None, + tags: list[Tag] | None = None, +) -> Highlight: + """Build a compact highlight fixture.""" + return Highlight( + id=highlight_id, + text=text, + note=note, + book_id=book_id, + color=HighlightColor.YELLOW, + location=0, + tags=tags or [], + ) + + +def operations( + highlights: FakeHighlightsResource | None = None, + tags: FakeHighlightTagsResource | None = None, + export: FakeExportResource | None = None, +) -> HighlightOperations: + """Compose the three resource seams needed by highlight operations.""" + return HighlightOperations( + highlights or FakeHighlightsResource(), + tags or FakeHighlightTagsResource(), + export or FakeExportResource(), + ) + + +@pytest.mark.asyncio +async def test_search_ports_mcp_text_filter_projection_limit_and_resource_arguments() -> None: + """Canonical search is text-only, case-insensitive, bounded, and projected.""" + updated_after = datetime(2025, 1, 2, 3, 4, tzinfo=UTC) + resource = FakeHighlightsResource( + [ + highlight(1, "A PYTHON insight", book_id=7, tags=[Tag(id=1, name="sdk")]), + highlight(2, "Unrelated", note="python note", book_id=7), + highlight(3, "python second", book_id=7), + ] + ) + + result = await operations(resource).search( + HighlightSearch(book_id=7, updated_after=updated_after, query="python", limit=2) + ) + + assert [item.id for item in result.items] == [1, 3] + assert result.items[0].tags == ("sdk",) + assert result.items[0].color is HighlightColor.YELLOW + assert result.items[0].location == 0 + assert result.truncated is True + assert resource.iter_calls == [ + { + "page_size": 100, + "book_id": 7, + "updated_after": updated_after, + "updated_before": None, + "highlighted_after": None, + "highlighted_before": None, + } + ] + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("provided", "expected"), [(0, 1), (1000, 200)]) +async def test_search_uses_stage_five_limit_clamping(provided: int, expected: int) -> None: + """Highlight searches retain MCP's inclusive 1..200 clamp.""" + resource = FakeHighlightsResource([highlight(index, f"match-{index}") for index in range(201)]) + + result = await operations(resource).search(HighlightSearch(query="match", limit=provided)) + + assert len(result.items) == expected + + +@pytest.mark.asyncio +async def test_list_get_create_update_and_delete_delegate_raw_models() -> None: + """Raw CRUD remains available without imposing adapter projections.""" + existing = highlight(1, "Existing") + resource = FakeHighlightsResource([existing]) + resource.created_ids = [8, 9] + operation = operations(resource) + create = HighlightCreate(text="New") + update = HighlightUpdate(note="Remember") + + assert await operation.list(limit=1) == [existing] + assert await operation.list(limit=0) == [] + assert await operation.get(1) is existing + assert await operation.create(create) == [8, 9] + updated = await operation.update(1, update) + await operation.delete(1) + + assert updated.note == "Remember" + assert resource.create_calls == [[create]] + assert resource.update_calls == [(1, update)] + assert resource.delete_calls == [1] + + +@pytest.mark.asyncio +async def test_manager_search_and_collection_variants_preserve_legacy_semantics() -> None: + """Manager-compatible helpers retain note search, case mode, time precedence, and counts.""" + explicit_since = datetime(2024, 1, 1, tzinfo=UTC) + noted = highlight(1, "Alpha", note="Needle") + lower = highlight(2, "needle", note=None) + resource = FakeHighlightsResource([noted, lower]) + operation = operations(resource) + + assert await operation.search_items("needle") == [noted, lower] + assert await operation.search_items("Needle", case_sensitive=True) == [noted] + assert await operation.with_notes() == [noted] + assert await operation.count() == 2 + assert [item async for item in operation.filter(lambda item: item.id == 2)] == [lower] + assert await operation.since(days=99, hours=99, since=explicit_since) == [noted, lower] + assert resource.iter_calls[-1]["updated_after"] is explicit_since + + with pytest.raises(ValueError, match="Must specify days, hours, or since"): + await operation.since() + + +@pytest.mark.asyncio +async def test_create_from_fields_preserves_mcp_category_and_raw_slice_policy() -> None: + """MCP creation accepts enum values (including supplementals) and slices text without ellipsis.""" + resource = FakeHighlightsResource() + resource.created_ids = [77] + operation = operations(resource) + long_text = "x" * (MAX_TEXT_LENGTH + 10) + + result = await operation.create_from_fields( + text=long_text, + title="Title", + category="supplementals", + ) + + sent = resource.create_calls[0][0] + assert result.ids == [77] + assert result.was_truncated is True + assert sent.text == "x" * MAX_TEXT_LENGTH + assert not sent.text.endswith("...") + assert sent.category is BookCategory.SUPPLEMENTALS + + with pytest.raises(ValueError, match="Invalid category 'invalid'"): + await operation.create_from_fields(text="text", category="invalid") + assert len(resource.create_calls) == 1 + + +@pytest.mark.asyncio +async def test_push_batch_preserves_pusher_truncation_order_and_missing_id_shape() -> None: + """Pusher batches use ellipses, report all truncated fields, and retain input ordering.""" + resource = FakeHighlightsResource() + resource.created_ids = [501] + operation = operations(resource) + first = HighlightPushInput( + text="t" * (MAX_TEXT_LENGTH + 4), + title="y" * (MAX_TITLE_LENGTH + 4), + author="a" * (MAX_AUTHOR_LENGTH + 4), + note="n" * (MAX_NOTE_LENGTH + 4), + tags=("ignored",), + ) + second = HighlightPushInput(text="short", title="Second") + + results = await operation.push_batch([first, second]) + + sent = resource.create_calls[0] + assert sent[0].text.endswith("...") and len(sent[0].text) == MAX_TEXT_LENGTH + assert sent[0].title is not None and sent[0].title.endswith("...") + assert sent[0].author is not None and sent[0].author.endswith("...") + assert sent[0].note is not None and sent[0].note.endswith("...") + assert "tags" not in sent[0].to_api_dict() + assert results[0].success is True + assert results[0].highlight_id == 501 + assert results[0].original is first + assert results[0].truncation_info is not None + assert results[0].truncation_info.truncated_field_names == [ + "text", + "note", + "title", + "author", + ] + assert results[1].success is False + assert results[1].error_message == "No API result returned" + assert results[1].original is second + + +@pytest.mark.asyncio +async def test_push_batch_marks_every_input_failed_when_the_single_api_batch_fails() -> None: + """One create request failure is retained against every batch input.""" + resource = FakeHighlightsResource() + error = RuntimeError("batch failed") + resource.create_error = error + inputs = [ + HighlightPushInput(text="one", title="One"), + HighlightPushInput(text="two", title="Two"), + ] + + results = await operations(resource).push_batch(inputs) + + assert [result.original for result in results] == inputs + assert all(result.success is False for result in results) + assert all(result.error is error for result in results) + + +@pytest.mark.asyncio +async def test_update_and_delete_batches_continue_and_retain_ordered_failures() -> None: + """Pusher mutation batches isolate each item and retain truncation metadata.""" + resource = FakeHighlightsResource() + update_error = RuntimeError("update failed") + delete_error = RuntimeError("delete failed") + resource.update_errors[2] = update_error + resource.delete_errors[2] = delete_error + operation = operations(resource) + + updates = await operation.update_batch( + [ + HighlightUpdateInput(1, text="x" * (MAX_TEXT_LENGTH + 5)), + HighlightUpdateInput(2, note="note"), + ] + ) + deletes = await operation.delete_batch([1, 2, 3]) + + assert updates[0].success is True + assert updates[0].truncation_info is not None + assert updates[0].truncation_info.truncated_field_names == ["text"] + assert updates[1].success is False and updates[1].error is update_error + assert [result.success for result in deletes] == [True, False, True] + assert deletes[1].error is delete_error + + +@pytest.mark.asyncio +async def test_bulk_tag_and_untag_preserve_broad_partial_failure_policy() -> None: + """Manager bool-map semantics can be reconstructed from successes and failures.""" + tags = FakeHighlightTagsResource() + tag_error = RuntimeError("tag failed") + untag_error = RuntimeError("list failed") + tags.create_errors[2] = tag_error + tags.tags = { + 1: [Tag(id=10, name="other"), Tag(id=11, name="target"), Tag(id=12, name="target")], + 2: [Tag(id=20, name="other")], + } + tags.iter_errors[3] = untag_error + operation = operations(tags=tags) + + tagged = await operation.bulk_tag([1, 2, 3], "target") + untagged = await operation.bulk_untag([1, 2, 3], "target") + + assert tagged.succeeded == [1, 3] + assert tagged.failures[0].item == 2 and tagged.failures[0].error is tag_error + assert untagged.succeeded == [1, 2] + assert untagged.failures[0].item == 3 and untagged.failures[0].error is untag_error + assert tags.delete_calls == [(1, 11)] + + +@pytest.mark.asyncio +async def test_export_preserves_grouping_projection_filters_and_limit_clamping() -> None: + """Export remains grouped by book and bounded over books, not nested highlights.""" + timestamp = datetime(2025, 2, 3, tzinfo=UTC) + books = [ + ExportBook( + user_book_id=index, + title=f"Book {index}", + author=None, + category=BookCategory.BOOKS, + highlights=[highlight(index, f"Insight {index}", tags=[Tag(id=1, name="tag")])], + ) + for index in range(101) + ] + resource = FakeExportResource(books) + + result = await operations(export=resource).export( + updated_after=timestamp, + book_ids=[3, 4], + limit=1000, + ) + + assert len(result.items) == 100 + assert result.truncated is True + assert result.items[0].book_id == 0 + assert result.items[0].highlights[0].tags == ("tag",) + assert resource.iter_calls == [ + {"updated_after": timestamp, "book_ids": [3, 4], "include_deleted": False} + ] + + +def test_service_wires_canonical_highlight_operations() -> None: + """The service composes highlights from highlight, tag, and export resources.""" + service = ReadwiseService( + documents=None, + highlights=FakeHighlightsResource(), + highlight_tags=FakeHighlightTagsResource(), + export=FakeExportResource(), + ) + + assert isinstance(service.highlights, HighlightOperations) diff --git a/tests/operations/test_readwise_transport.py b/tests/operations/test_readwise_transport.py new file mode 100644 index 0000000..4805a82 --- /dev/null +++ b/tests/operations/test_readwise_transport.py @@ -0,0 +1,124 @@ +"""Transport-backed tests for highlight and book operations.""" + +from __future__ import annotations + +import json + +import httpx +import pytest +import respx + +from readwise_sdk.config import ClientConfig +from readwise_sdk.models import BookSearch +from readwise_sdk.operations.books import BookOperations +from readwise_sdk.operations.highlights import MAX_TEXT_LENGTH, HighlightOperations +from readwise_sdk.resources.v2 import ( + AsyncBooksResource, + AsyncExportResource, + AsyncHighlightsResource, + AsyncTagsResource, +) +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.v2.models import BookCategory + +V2_BASE = "https://readwise.io/api/v2" + + +def operation_stack() -> tuple[HighlightOperations, BookOperations, AsyncTransport]: + """Compose real operations, resources, and transport.""" + transport = AsyncTransport(ClientConfig(api_key="token")) + highlights = AsyncHighlightsResource(transport) + return ( + HighlightOperations( + highlights, AsyncTagsResource(transport), AsyncExportResource(transport) + ), + BookOperations(AsyncBooksResource(transport), highlights), + transport, + ) + + +@respx.mock +@pytest.mark.asyncio +async def test_create_transport_sends_mcp_slice_and_category_value() -> None: + """MCP creation policy reaches the real resource as an 8191-char non-ellipsis payload.""" + route = respx.post(f"{V2_BASE}/highlights/").mock( + return_value=httpx.Response(200, json=[{"modified_highlights": [8]}]) + ) + highlights, _, transport = operation_stack() + + try: + result = await highlights.create_from_fields( + text="x" * (MAX_TEXT_LENGTH + 20), + category="articles", + ) + finally: + await transport.close() + + payload = json.loads(route.calls.last.request.content) + assert result.ids == [8] + assert payload == {"highlights": [{"text": "x" * MAX_TEXT_LENGTH, "category": "articles"}]} + + +@respx.mock +@pytest.mark.asyncio +async def test_export_transport_preserves_grouping_query_and_nested_projection() -> None: + """Export filters and grouped highlights survive the real resource boundary.""" + route = respx.get(f"{V2_BASE}/export/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "user_book_id": 7, + "title": "Book", + "highlights": [{"id": 1, "text": "Insight", "tags": []}], + } + ], + "nextPageCursor": None, + }, + ) + ) + highlights, _, transport = operation_stack() + + try: + result = await highlights.export(book_ids=[7, 8]) + finally: + await transport.close() + + assert result.items[0].book_id == 7 + assert result.items[0].highlights[0].text == "Insight" + assert route.calls.last.request.url.params["ids"] == "7,8" + + +@respx.mock +@pytest.mark.asyncio +async def test_book_search_transport_keeps_filters_and_title_only_matching() -> None: + """Book resource filters and operation-local title matching compose without drift.""" + route = respx.get(f"{V2_BASE}/books/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + {"id": 1, "title": "Other", "author": "Python Author"}, + {"id": 2, "title": "Python Book", "num_highlights": 0}, + ], + "next": None, + }, + ) + ) + _, books, transport = operation_stack() + + try: + result = await books.search( + BookSearch( + category=BookCategory.BOOKS, + source="kindle", + query="python", + ) + ) + finally: + await transport.close() + + assert [item.id for item in result.items] == [2] + assert route.calls.last.request.url.params["category"] == "books" + assert route.calls.last.request.url.params["source"] == "kindle" From 0b4131f7ede6c7b7ab2692b0fd79b8d4b977c6b8 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 23:47:50 -0500 Subject: [PATCH 11/24] refactor(mcp): delegate the 9 tools to the operations core (stage 8) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Behavior-preserving adapter rewire. Each MCP tool now does: arg adaptation → one operations service call → existing JSON rendering → existing error translation. Presenters (_doc_summary/_highlight_summary/_book_summary/ _json_result + error rendering) moved to mcp/output.py, behavior unchanged. The MCP characterization contract (test_mcp_contracts.py, 17 tests) passes UNCHANGED — byte-for-byte output preserved (tool names, compact JSON, None omission, not-found text, invalid-enum envelopes, limit clamps, lenient datetime, and the still-dropped save_to_reader category). No CLI/manager/ operation changes. Gate green (657 passed); uv.lock unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/mcp/output.py | 125 ++++++++++++++ src/readwise_sdk/mcp/server.py | 295 ++++++++++++--------------------- 2 files changed, 231 insertions(+), 189 deletions(-) create mode 100644 src/readwise_sdk/mcp/output.py diff --git a/src/readwise_sdk/mcp/output.py b/src/readwise_sdk/mcp/output.py new file mode 100644 index 0000000..7b59bcc --- /dev/null +++ b/src/readwise_sdk/mcp/output.py @@ -0,0 +1,125 @@ +"""Presentation helpers for the MCP wire protocol.""" + +from __future__ import annotations + +import json +from typing import Any + + +def _doc_summary(doc: Any) -> dict[str, Any]: + """Compact summary of a Document for listing results.""" + return { + k: v + for k, v in { + "id": doc.id, + "title": doc.title, + "author": doc.author, + "url": getattr(doc, "source_url", None) or doc.url, + "category": doc.category.value if doc.category else None, + "location": doc.location.value if doc.location else None, + "tags": doc.tags or None, + "word_count": doc.word_count, + "reading_progress": doc.reading_progress, + "site_name": doc.site_name, + "published_date": doc.published_date.isoformat() if doc.published_date else None, + "saved_at": doc.saved_at.isoformat() if doc.saved_at else None, + }.items() + if v is not None + } + + +def _doc_full(doc: Any) -> dict[str, Any]: + """Full document representation including content.""" + result = _doc_summary(doc) + if doc.content: + result["content"] = doc.content + if doc.summary: + result["summary"] = doc.summary + if doc.notes: + result["notes"] = doc.notes + return result + + +def _highlight_summary(highlight: Any) -> dict[str, Any]: + """Compact summary of a Highlight.""" + tags = None + if highlight.tags: + tags = [tag if isinstance(tag, str) else tag.name for tag in highlight.tags] + return { + k: v + for k, v in { + "id": highlight.id, + "text": highlight.text, + "note": highlight.note, + "book_id": highlight.book_id, + "color": highlight.color.value if highlight.color else None, + "location": highlight.location, + "highlighted_at": ( + highlight.highlighted_at.isoformat() if highlight.highlighted_at else None + ), + "tags": tags, + }.items() + if v is not None + } + + +def _book_summary(book: Any) -> dict[str, Any]: + """Compact summary of a Book.""" + return { + k: v + for k, v in { + "id": book.id, + "title": book.title, + "author": book.author, + "category": book.category.value if book.category else None, + "source": book.source, + "num_highlights": book.num_highlights, + "source_url": book.source_url, + "cover_image_url": book.cover_image_url, + "last_highlight_at": ( + book.last_highlight_at.isoformat() if book.last_highlight_at else None + ), + }.items() + if v is not None + } + + +def _export_summary(book: Any) -> dict[str, Any]: + """Compact exported-book representation with nested highlights.""" + book_data: dict[str, Any] = { + "book_id": book.book_id, + "title": book.title, + "author": book.author, + "category": book.category.value if book.category else None, + "source": book.source, + "source_url": book.source_url, + "highlights": [_highlight_summary(highlight) for highlight in book.highlights], + } + return {key: value for key, value in book_data.items() if value is not None} + + +def _json_result(data: Any) -> str: + """Serialize a result to a compact JSON string.""" + return json.dumps(data, ensure_ascii=False, default=str) + + +def _error_result(error: Exception | str) -> str: + """Render an SDK or adapter error in the existing MCP envelope.""" + return _json_result({"error": str(error)}) + + +def _document_not_found(document_id: str) -> str: + """Render the existing quoted document-not-found message.""" + return _error_result(f"Document '{document_id}' not found.") + + +__all__ = [ + "_book_summary", + "_doc_full", + "_doc_summary", + "_document_not_found", + "_error_result", + "_export_summary", + "_highlight_summary", + "_json_result", +] diff --git a/src/readwise_sdk/mcp/server.py b/src/readwise_sdk/mcp/server.py index 5c02838..19adee9 100644 --- a/src/readwise_sdk/mcp/server.py +++ b/src/readwise_sdk/mcp/server.py @@ -9,10 +9,8 @@ from __future__ import annotations -import json import os from datetime import datetime -from typing import Any from mcp.server.fastmcp import FastMCP @@ -21,8 +19,32 @@ NotFoundError, ReadwiseError, ) -from readwise_sdk.v2.models import HighlightCreate -from readwise_sdk.v3.models import DocumentCreate, DocumentLocation, DocumentUpdate +from readwise_sdk.mcp.output import ( + _book_summary, + _doc_full, + _doc_summary, + _document_not_found, + _error_result, + _export_summary, + _highlight_summary, + _json_result, +) +from readwise_sdk.models import BookSearch, DocumentSearch, HighlightSearch +from readwise_sdk.operations import ReadwiseService +from readwise_sdk.resources.v2 import ( + AsyncBooksResource, + AsyncExportResource, + AsyncHighlightsResource, + AsyncTagsResource, +) +from readwise_sdk.resources.v3 import AsyncDocumentsResource +from readwise_sdk.v2.models import BookCategory +from readwise_sdk.v3.models import ( + DocumentCategory, + DocumentCreate, + DocumentLocation, + DocumentUpdate, +) # --------------------------------------------------------------------------- # Server + client setup @@ -66,87 +88,25 @@ def _client() -> AsyncReadwiseClient: return AsyncReadwiseClient(api_key=_get_api_key()) +def _service(client: AsyncReadwiseClient) -> ReadwiseService: + """Compose canonical operations over one tool call's client transport.""" + transport = client._transport + highlights = AsyncHighlightsResource(transport) + return ReadwiseService( + documents=AsyncDocumentsResource(transport), + highlights=highlights, + highlight_tags=AsyncTagsResource(transport), + export=AsyncExportResource(transport), + books=AsyncBooksResource(transport), + book_highlights=highlights, + ) + + def main() -> None: """Console-script entry point: run the MCP server over stdio.""" mcp.run() -# --------------------------------------------------------------------------- -# Helpers -# --------------------------------------------------------------------------- - - -def _doc_summary(doc: Any) -> dict[str, Any]: - """Compact summary of a Document for listing results.""" - return { - k: v - for k, v in { - "id": doc.id, - "title": doc.title, - "author": doc.author, - "url": doc.source_url or doc.url, - "category": doc.category.value if doc.category else None, - "location": doc.location.value if doc.location else None, - "tags": doc.tags or None, - "word_count": doc.word_count, - "reading_progress": doc.reading_progress, - "site_name": doc.site_name, - "published_date": doc.published_date.isoformat() if doc.published_date else None, - "saved_at": doc.saved_at.isoformat() if doc.saved_at else None, - }.items() - if v is not None - } - - -def _doc_full(doc: Any) -> dict[str, Any]: - """Full document representation including content.""" - result = _doc_summary(doc) - if doc.content: - result["content"] = doc.content - if doc.summary: - result["summary"] = doc.summary - if doc.notes: - result["notes"] = doc.notes - return result - - -def _highlight_summary(h: Any) -> dict[str, Any]: - """Compact summary of a Highlight.""" - return { - k: v - for k, v in { - "id": h.id, - "text": h.text, - "note": h.note, - "book_id": h.book_id, - "color": h.color.value if h.color else None, - "location": h.location, - "highlighted_at": h.highlighted_at.isoformat() if h.highlighted_at else None, - "tags": [t.name for t in h.tags] if h.tags else None, - }.items() - if v is not None - } - - -def _book_summary(b: Any) -> dict[str, Any]: - """Compact summary of a Book.""" - return { - k: v - for k, v in { - "id": b.id, - "title": b.title, - "author": b.author, - "category": b.category.value if b.category else None, - "source": b.source, - "num_highlights": b.num_highlights, - "source_url": b.source_url, - "cover_image_url": b.cover_image_url, - "last_highlight_at": (b.last_highlight_at.isoformat() if b.last_highlight_at else None), - }.items() - if v is not None - } - - def _parse_iso_datetime(s: str | None) -> datetime | None: """Parse an ISO 8601 datetime string, returning None on failure.""" if not s: @@ -157,11 +117,6 @@ def _parse_iso_datetime(s: str | None) -> datetime | None: return None -def _json_result(data: Any) -> str: - """Serialize a result to a compact JSON string.""" - return json.dumps(data, ensure_ascii=False, default=str) - - # --------------------------------------------------------------------------- # Tools — Documents (Reader v3) # --------------------------------------------------------------------------- @@ -204,9 +159,7 @@ async def save_to_reader( try: doc_location = DocumentLocation(location) except ValueError: - return _json_result( - {"error": f"Invalid location '{location}'. Use: new, later, archive, feed."} - ) + return _error_result(f"Invalid location '{location}'. Use: new, later, archive, feed.") doc = DocumentCreate( url=url, @@ -222,10 +175,10 @@ async def save_to_reader( async with _client() as client: try: - result = await client.v3.create_document(doc) + result = await _service(client).documents.save(doc) return _json_result({"id": result.id, "url": result.url}) except ReadwiseError as e: - return _json_result({"error": str(e)}) + return _error_result(e) @mcp.tool() @@ -253,8 +206,6 @@ async def search_documents( Returns: JSON array of document summaries. """ - from readwise_sdk.v3.models import DocumentCategory, DocumentLocation - limit = min(max(limit, 1), 100) doc_location = None doc_category = None @@ -263,33 +214,28 @@ async def search_documents( try: doc_location = DocumentLocation(location) except ValueError: - return _json_result({"error": f"Invalid location '{location}'."}) + return _error_result(f"Invalid location '{location}'.") if category: try: doc_category = DocumentCategory(category) except ValueError: - return _json_result({"error": f"Invalid category '{category}'."}) + return _error_result(f"Invalid category '{category}'.") - dt_after = _parse_iso_datetime(updated_after) - query_lower = query.lower() if query else None + search = DocumentSearch.model_construct( + location=doc_location, + category=doc_category, + updated_after=_parse_iso_datetime(updated_after), + tags=tuple(tags or ()), + query=query, + limit=limit, + ) async with _client() as client: try: - results: list[dict[str, Any]] = [] - async for doc in client.v3.list_documents( - location=doc_location, - category=doc_category, - updated_after=dt_after, - tags=tags, - ): - if query_lower and doc.title and query_lower not in doc.title.lower(): - continue - results.append(_doc_summary(doc)) - if len(results) >= limit: - break - return _json_result(results) + result = await _service(client).documents.search(search) + return _json_result([_doc_summary(doc) for doc in result.items]) except ReadwiseError as e: - return _json_result({"error": str(e)}) + return _error_result(e) @mcp.tool() @@ -304,14 +250,14 @@ async def get_document(document_id: str) -> str: """ async with _client() as client: try: - doc = await client.v3.get_document(document_id, with_content=True) + doc = await _service(client).documents.get(document_id, with_content=True) if doc is None: - return _json_result({"error": f"Document '{document_id}' not found."}) + return _document_not_found(document_id) return _json_result(_doc_full(doc)) except NotFoundError: - return _json_result({"error": f"Document '{document_id}' not found."}) + return _document_not_found(document_id) except ReadwiseError as e: - return _json_result({"error": str(e)}) + return _error_result(e) @mcp.tool() @@ -351,7 +297,7 @@ async def update_document( try: doc_location = DocumentLocation(location) except ValueError: - return _json_result({"error": f"Invalid location '{location}'."}) + return _error_result(f"Invalid location '{location}'.") update = DocumentUpdate( title=title, @@ -364,12 +310,12 @@ async def update_document( async with _client() as client: try: - result = await client.v3.update_document(document_id, update) + result = await _service(client).documents.update(document_id, update) return _json_result({"id": result.id, "url": result.url}) except NotFoundError: - return _json_result({"error": f"Document '{document_id}' not found."}) + return _document_not_found(document_id) except ReadwiseError as e: - return _json_result({"error": str(e)}) + return _error_result(e) @mcp.tool() @@ -386,12 +332,12 @@ async def delete_document(document_id: str) -> str: """ async with _client() as client: try: - await client.v3.delete_document(document_id) + await _service(client).documents.delete(document_id) return _json_result({"deleted": document_id}) except NotFoundError: - return _json_result({"error": f"Document '{document_id}' not found."}) + return _document_not_found(document_id) except ReadwiseError as e: - return _json_result({"error": str(e)}) + return _error_result(e) # --------------------------------------------------------------------------- @@ -418,24 +364,19 @@ async def get_highlights( JSON array of highlights. """ limit = min(max(limit, 1), 200) - dt_after = _parse_iso_datetime(updated_after) - query_lower = query.lower() if query else None + search = HighlightSearch.model_construct( + book_id=book_id, + updated_after=_parse_iso_datetime(updated_after), + query=query, + limit=limit, + ) async with _client() as client: try: - results: list[dict[str, Any]] = [] - async for h in client.v2.list_highlights( - book_id=book_id, - updated_after=dt_after, - ): - if query_lower and query_lower not in h.text.lower(): - continue - results.append(_highlight_summary(h)) - if len(results) >= limit: - break - return _json_result(results) + result = await _service(client).highlights.search(search) + return _json_result([_highlight_summary(item) for item in result.items]) except ReadwiseError as e: - return _json_result({"error": str(e)}) + return _error_result(e) @mcp.tool() @@ -457,31 +398,16 @@ async def export_highlights( Returns: JSON array of books, each containing a highlights array. """ - limit = min(max(limit, 1), 100) - dt_after = _parse_iso_datetime(updated_after) - async with _client() as client: try: - results: list[dict[str, Any]] = [] - async for book in client.v2.export_highlights( - updated_after=dt_after, + result = await _service(client).highlights.export( + updated_after=_parse_iso_datetime(updated_after), book_ids=book_ids, - ): - book_data: dict[str, Any] = { - "book_id": book.user_book_id, - "title": book.title, - "author": book.author, - "category": book.category.value if book.category else None, - "source": book.source, - "source_url": book.source_url, - "highlights": [_highlight_summary(h) for h in book.highlights], - } - results.append({k: v for k, v in book_data.items() if v is not None}) - if len(results) >= limit: - break - return _json_result(results) + limit=limit, + ) + return _json_result([_export_summary(item) for item in result.items]) except ReadwiseError as e: - return _json_result({"error": str(e)}) + return _error_result(e) @mcp.tool() @@ -512,33 +438,29 @@ async def create_highlight( Returns: JSON with created highlight IDs. """ - from readwise_sdk.v2.models import BookCategory - book_category = None if category: try: book_category = BookCategory(category) except ValueError: - return _json_result( - {"error": f"Invalid category '{category}'. Use: books, articles, tweets, podcasts."} + return _error_result( + f"Invalid category '{category}'. Use: books, articles, tweets, podcasts." ) - highlight = HighlightCreate( - text=text[:8191], - title=title, - author=author, - source_url=source_url, - note=note, - category=book_category, - highlighted_at=_parse_iso_datetime(highlighted_at), - ) - async with _client() as client: try: - ids = await client.v2.create_highlights([highlight]) - return _json_result({"created_highlight_ids": ids}) + result = await _service(client).highlights.create_from_fields( + text=text, + title=title, + author=author, + source_url=source_url, + note=note, + category=book_category, + highlighted_at=_parse_iso_datetime(highlighted_at), + ) + return _json_result({"created_highlight_ids": result.ids}) except ReadwiseError as e: - return _json_result({"error": str(e)}) + return _error_result(e) # --------------------------------------------------------------------------- @@ -564,8 +486,6 @@ async def get_books( Returns: JSON array of book summaries. """ - from readwise_sdk.v2.models import BookCategory - limit = min(max(limit, 1), 100) book_category = None @@ -573,22 +493,19 @@ async def get_books( try: book_category = BookCategory(category) except ValueError: - return _json_result({"error": f"Invalid category '{category}'."}) + return _error_result(f"Invalid category '{category}'.") - query_lower = query.lower() if query else None + search = BookSearch.model_construct( + category=book_category, + source=source, + updated_after=None, + query=query, + limit=limit, + ) async with _client() as client: try: - results: list[dict[str, Any]] = [] - async for book in client.v2.list_books( - category=book_category, - source=source, - ): - if query_lower and query_lower not in book.title.lower(): - continue - results.append(_book_summary(book)) - if len(results) >= limit: - break - return _json_result(results) + result = await _service(client).books.search(search) + return _json_result([_book_summary(book) for book in result.items]) except ReadwiseError as e: - return _json_result({"error": str(e)}) + return _error_result(e) From d93407881403d9b50c0a1336c86f7d66b12e20ba Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Mon, 13 Jul 2026 23:53:56 -0500 Subject: [PATCH 12/24] feat: add AsyncReadwise SDK facade (stage 9) Additive. New sdk/async_.py: AsyncReadwise async context manager composed from the operations service, exposing concept attributes (.documents/.highlights/ .books) plus a .raw.v2/.raw.v3 low-level escape hatch. Exported from the package root alongside the unchanged AsyncReadwiseClient and all existing imports. Facade tests cover construction, lifecycle, delegation, and .raw. Nothing existing changed; gate green (665 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/__init__.py | 1 + src/readwise_sdk/sdk/__init__.py | 5 ++ src/readwise_sdk/sdk/async_.py | 120 +++++++++++++++++++++++++++++++ tests/sdk/__init__.py | 1 + tests/sdk/test_async.py | 86 ++++++++++++++++++++++ 5 files changed, 213 insertions(+) create mode 100644 src/readwise_sdk/sdk/__init__.py create mode 100644 src/readwise_sdk/sdk/async_.py create mode 100644 tests/sdk/__init__.py create mode 100644 tests/sdk/test_async.py diff --git a/src/readwise_sdk/__init__.py b/src/readwise_sdk/__init__.py index e33c773..6524919 100644 --- a/src/readwise_sdk/__init__.py +++ b/src/readwise_sdk/__init__.py @@ -18,6 +18,7 @@ SyncManager, SyncState, ) +from readwise_sdk.sdk import AsyncReadwise as AsyncReadwise from readwise_sdk.v2 import ( Book, BookCategory, diff --git a/src/readwise_sdk/sdk/__init__.py b/src/readwise_sdk/sdk/__init__.py new file mode 100644 index 0000000..de2b816 --- /dev/null +++ b/src/readwise_sdk/sdk/__init__.py @@ -0,0 +1,5 @@ +"""Preferred concept-oriented SDK facades.""" + +from readwise_sdk.sdk.async_ import AsyncReadwise + +__all__ = ["AsyncReadwise"] diff --git a/src/readwise_sdk/sdk/async_.py b/src/readwise_sdk/sdk/async_.py new file mode 100644 index 0000000..b041cbf --- /dev/null +++ b/src/readwise_sdk/sdk/async_.py @@ -0,0 +1,120 @@ +"""Preferred asynchronous SDK facade.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any + +from readwise_sdk.client import AsyncReadwiseClient +from readwise_sdk.config import DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF, DEFAULT_TIMEOUT +from readwise_sdk.operations import ( + BookOperations, + DocumentOperations, + HighlightOperations, + ReadwiseService, +) +from readwise_sdk.resources.v2 import ( + AsyncBooksResource, + AsyncExportResource, + AsyncHighlightsResource, + AsyncTagsResource, +) +from readwise_sdk.resources.v3 import AsyncDocumentsResource + +if TYPE_CHECKING: + from readwise_sdk.v2.async_client import AsyncReadwiseV2Client + from readwise_sdk.v3.async_client import AsyncReadwiseV3Client + + +class _AsyncRawClients: + """Expose the existing versioned clients through an explicit escape hatch.""" + + def __init__(self, client: AsyncReadwiseClient) -> None: + self._client = client + + @property + def v2(self) -> AsyncReadwiseV2Client: + """Return the low-level asynchronous Readwise v2 client.""" + return self._client.v2 + + @property + def v3(self) -> AsyncReadwiseV3Client: + """Return the low-level asynchronous Reader v3 client.""" + return self._client.v3 + + +class AsyncReadwise: + """Concept-oriented asynchronous Readwise SDK. + + Example:: + + from readwise_sdk import AsyncReadwise + from readwise_sdk.models import DocumentSearch + + async with AsyncReadwise() as readwise: + result = await readwise.documents.search(DocumentSearch(query="python")) + + Use ``readwise.raw.v2`` or ``readwise.raw.v3`` for low-level API access. + """ + + def __init__( + self, + api_key: str | None = None, + timeout: float = DEFAULT_TIMEOUT, + max_retries: int = DEFAULT_MAX_RETRIES, + retry_backoff: float = DEFAULT_RETRY_BACKOFF, + ) -> None: + """Compose canonical operations and raw clients over one transport.""" + self._client = AsyncReadwiseClient( + api_key, + timeout, + max_retries, + retry_backoff, + ) + transport = self._client._transport + highlights = AsyncHighlightsResource(transport) + self._service = ReadwiseService( + documents=AsyncDocumentsResource(transport), + highlights=highlights, + highlight_tags=AsyncTagsResource(transport), + export=AsyncExportResource(transport), + books=AsyncBooksResource(transport), + book_highlights=highlights, + ) + self._raw = _AsyncRawClients(self._client) + + @property + def documents(self) -> DocumentOperations: + """Return canonical Reader document operations.""" + return self._service.documents + + @property + def highlights(self) -> HighlightOperations: + """Return canonical Readwise highlight operations.""" + return self._service.highlights + + @property + def books(self) -> BookOperations: + """Return canonical Readwise book operations.""" + return self._service.books + + # tags, digests, and sync are deferred until wired to canonical ops in stages 13/14. + + @property + def raw(self) -> _AsyncRawClients: + """Return low-level versioned clients for advanced API access.""" + return self._raw + + async def close(self) -> None: + """Close the shared asynchronous transport.""" + await self._client.close() + + async def __aenter__(self) -> AsyncReadwise: + """Enter the facade context and return this instance.""" + return self + + async def __aexit__(self, *args: Any) -> None: + """Close the shared transport when leaving the facade context.""" + await self.close() + + +__all__ = ["AsyncReadwise"] diff --git a/tests/sdk/__init__.py b/tests/sdk/__init__.py new file mode 100644 index 0000000..22fc047 --- /dev/null +++ b/tests/sdk/__init__.py @@ -0,0 +1 @@ +"""Tests for the preferred SDK facades.""" diff --git a/tests/sdk/test_async.py b/tests/sdk/test_async.py new file mode 100644 index 0000000..72fcd1b --- /dev/null +++ b/tests/sdk/test_async.py @@ -0,0 +1,86 @@ +"""Public contract tests for the preferred asynchronous SDK facade.""" + +from __future__ import annotations + +import httpx +import pytest + +from readwise_sdk.operations import BookOperations, DocumentOperations, HighlightOperations +from readwise_sdk.v2.async_client import AsyncReadwiseV2Client +from readwise_sdk.v3.async_client import AsyncReadwiseV3Client + + +def test_async_readwise_is_importable_from_the_package_root() -> None: + """The preferred async facade is available through the documented import.""" + from readwise_sdk import AsyncReadwise + + assert AsyncReadwise.__module__ == "readwise_sdk.sdk.async_" + + +def test_async_readwise_constructs_canonical_operations() -> None: + """Construction composes all operation groups that exist today.""" + from readwise_sdk import AsyncReadwise + + readwise = AsyncReadwise("token", 12.5, 7, 1.25) + + assert isinstance(readwise.documents, DocumentOperations) + assert isinstance(readwise.highlights, HighlightOperations) + assert isinstance(readwise.books, BookOperations) + assert ( + readwise._client.api_key, + readwise._client.timeout, + readwise._client.max_retries, + readwise._client.retry_backoff, + ) == ("token", 12.5, 7, 1.25) + + +@pytest.mark.parametrize("name", ["documents", "highlights", "books"]) +def test_concept_attributes_delegate_to_the_canonical_service(name: str) -> None: + """Each public concept attribute is the operation group owned by the service.""" + from readwise_sdk import AsyncReadwise + + readwise = AsyncReadwise(api_key="token") + + assert getattr(readwise, name) is getattr(readwise._service, name) + + +def test_raw_exposes_cached_versioned_clients_over_the_shared_client() -> None: + """The low-level escape hatch reaches both existing resource client facades.""" + from readwise_sdk import AsyncReadwise + + readwise = AsyncReadwise(api_key="token") + + assert isinstance(readwise.raw.v2, AsyncReadwiseV2Client) + assert isinstance(readwise.raw.v3, AsyncReadwiseV3Client) + assert readwise.raw.v2 is readwise.raw.v2 + assert readwise.raw.v3 is readwise.raw.v3 + assert readwise.raw.v2._client is readwise._client + assert readwise.raw.v3._client is readwise._client + + +def test_future_operation_groups_are_deferred() -> None: + """Facades do not imply canonical operation groups that do not exist yet.""" + from readwise_sdk import AsyncReadwise + + readwise = AsyncReadwise(api_key="token") + + assert not hasattr(readwise, "tags") + assert not hasattr(readwise, "digests") + assert not hasattr(readwise, "sync") + + +@pytest.mark.asyncio +async def test_async_context_manager_returns_self_and_closes_shared_transport() -> None: + """Leaving the facade context closes the transport used by operations and raw clients.""" + from readwise_sdk import AsyncReadwise + + readwise = AsyncReadwise(api_key="token") + + async with readwise as entered: + transport = entered._client.client + assert entered is readwise + assert isinstance(transport, httpx.AsyncClient) + assert transport.is_closed is False + + assert transport.is_closed is True + assert readwise._client._client is None From 5303a637e94147edf179c873f6d72cfdd7829f58 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 00:06:10 -0500 Subject: [PATCH 13/24] feat: add synchronous Readwise facade via anyio portal (stage 10) Additive. New sdk/sync.py: Readwise sync context manager that runs the async operations service through a dedicated AnyIO blocking portal on its own event-loop thread, mirroring AsyncReadwise's surface and returning bounded results. The facade owns and closes its portal + async client. Adds anyio>=4.0 as a direct dependency. Exported from the package root; ReadwiseClient and all existing imports unchanged. Tests cover ordinary use, use from a thread with a running event loop (no deadlock), lifecycle, repeated ops, and exceptions crossing the portal. Gate green (677 passed); characterization unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- pyproject.toml | 1 + src/readwise_sdk/__init__.py | 1 + src/readwise_sdk/sdk/__init__.py | 3 +- src/readwise_sdk/sdk/sync.py | 507 +++++++++++++++++++++++++++++++ tests/sdk/test_sync.py | 297 ++++++++++++++++++ uv.lock | 4 +- 6 files changed, 811 insertions(+), 2 deletions(-) create mode 100644 src/readwise_sdk/sdk/sync.py create mode 100644 tests/sdk/test_sync.py diff --git a/pyproject.toml b/pyproject.toml index a9063d5..0c5dc29 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,6 +19,7 @@ classifiers = [ "Typing :: Typed", ] dependencies = [ + "anyio>=4.0", "httpx>=0.27.0", "pydantic>=2.0.0", ] diff --git a/src/readwise_sdk/__init__.py b/src/readwise_sdk/__init__.py index 6524919..d232218 100644 --- a/src/readwise_sdk/__init__.py +++ b/src/readwise_sdk/__init__.py @@ -19,6 +19,7 @@ SyncState, ) from readwise_sdk.sdk import AsyncReadwise as AsyncReadwise +from readwise_sdk.sdk import Readwise as Readwise from readwise_sdk.v2 import ( Book, BookCategory, diff --git a/src/readwise_sdk/sdk/__init__.py b/src/readwise_sdk/sdk/__init__.py index de2b816..e1d6637 100644 --- a/src/readwise_sdk/sdk/__init__.py +++ b/src/readwise_sdk/sdk/__init__.py @@ -1,5 +1,6 @@ """Preferred concept-oriented SDK facades.""" from readwise_sdk.sdk.async_ import AsyncReadwise +from readwise_sdk.sdk.sync import Readwise -__all__ = ["AsyncReadwise"] +__all__ = ["AsyncReadwise", "Readwise"] diff --git a/src/readwise_sdk/sdk/sync.py b/src/readwise_sdk/sdk/sync.py new file mode 100644 index 0000000..2996c0f --- /dev/null +++ b/src/readwise_sdk/sdk/sync.py @@ -0,0 +1,507 @@ +"""Preferred synchronous SDK facade over the async-first operation service.""" + +from __future__ import annotations + +import builtins +from collections.abc import Awaitable, Callable +from contextlib import AbstractContextManager +from datetime import datetime +from functools import partial +from threading import Lock +from typing import TYPE_CHECKING, Any + +from anyio.from_thread import BlockingPortal, start_blocking_portal + +from readwise_sdk.client import ReadwiseClient +from readwise_sdk.config import DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF, DEFAULT_TIMEOUT +from readwise_sdk.models import BookSearch, BulkResult, DocumentSearch, DocumentSearchResult +from readwise_sdk.models.queries import HighlightSearch +from readwise_sdk.operations import ( + BookSearchResult, + BookWithHighlights, + DocumentStatistics, + HighlightCreateResult, + HighlightDeleteResult, + HighlightExportResult, + HighlightPushInput, + HighlightPushResult, + HighlightSearchResult, + HighlightUpdateInput, + HighlightUpdateResult, + ReadingStatistics, +) +from readwise_sdk.sdk.async_ import AsyncReadwise +from readwise_sdk.v2.models import Book, BookCategory, Highlight, HighlightCreate, HighlightUpdate +from readwise_sdk.v3.models import ( + CreateDocumentResult, + Document, + DocumentCreate, + DocumentLocation, + DocumentUpdate, +) + +if TYPE_CHECKING: + from readwise_sdk.operations import BookOperations, DocumentOperations, HighlightOperations + from readwise_sdk.v2.client import ReadwiseV2Client + from readwise_sdk.v3.client import ReadwiseV3Client + + +class _SyncRawClients: + """Expose the existing native synchronous clients as the raw escape hatch.""" + + def __init__(self, client: ReadwiseClient) -> None: + self._client = client + + @property + def v2(self) -> ReadwiseV2Client: + """Return the low-level synchronous Readwise v2 client.""" + return self._client.v2 + + @property + def v3(self) -> ReadwiseV3Client: + """Return the low-level synchronous Reader v3 client.""" + return self._client.v3 + + +class _SyncOperationGroup: + """Base for explicit synchronous adapters over one async operation group.""" + + def __init__(self, owner: Readwise) -> None: + self._owner = owner + + def _call[T]( + self, + operation: Callable[..., Awaitable[T]], + *args: Any, + **kwargs: Any, + ) -> T: + return self._owner._call(operation, *args, **kwargs) + + +class _SyncDocumentOperations(_SyncOperationGroup): + """Synchronous adapter for every bounded document operation.""" + + def __init__(self, owner: Readwise, operations: DocumentOperations) -> None: + super().__init__(owner) + self._operations = operations + + def search(self, search: DocumentSearch) -> DocumentSearchResult: + return self._call(self._operations.search, search) + + def get(self, document_id: str, *, with_content: bool = False) -> Document | None: + return self._call( + self._operations.get, + document_id, + with_content=with_content, + ) + + def save(self, document: DocumentCreate) -> CreateDocumentResult: + return self._call(self._operations.save, document) + + def update( + self, + document_id: str, + update: DocumentUpdate, + ) -> CreateDocumentResult: + return self._call(self._operations.update, document_id, update) + + def delete(self, document_id: str) -> None: + return self._call(self._operations.delete, document_id) + + def move( + self, + document_id: str, + location: DocumentLocation, + ) -> CreateDocumentResult: + return self._call(self._operations.move, document_id, location) + + def set_tags(self, document_id: str, tags: list[str]) -> CreateDocumentResult: + return self._call(self._operations.set_tags, document_id, tags) + + def add_tag(self, document_id: str, tag: str) -> CreateDocumentResult: + return self._call(self._operations.add_tag, document_id, tag) + + def remove_tag(self, document_id: str, tag: str) -> CreateDocumentResult: + return self._call(self._operations.remove_tag, document_id, tag) + + def inbox( + self, + *, + limit: int | None = None, + with_content: bool = False, + ) -> list[Document]: + return self._call( + self._operations.inbox, + limit=limit, + with_content=with_content, + ) + + def later( + self, + *, + limit: int | None = None, + with_content: bool = False, + ) -> list[Document]: + return self._call( + self._operations.later, + limit=limit, + with_content=with_content, + ) + + def archive( + self, + *, + limit: int | None = None, + with_content: bool = False, + ) -> list[Document]: + return self._call( + self._operations.archive, + limit=limit, + with_content=with_content, + ) + + def statistics(self) -> DocumentStatistics: + return self._call(self._operations.statistics) + + def bulk_move( + self, + document_ids: list[str], + location: DocumentLocation, + ) -> BulkResult[str]: + return self._call(self._operations.bulk_move, document_ids, location) + + def bulk_set_tags( + self, + document_ids: list[str], + tags: list[str], + ) -> BulkResult[str]: + return self._call(self._operations.bulk_set_tags, document_ids, tags) + + +class _SyncHighlightOperations(_SyncOperationGroup): + """Synchronous adapter for every bounded highlight operation.""" + + def __init__(self, owner: Readwise, operations: HighlightOperations) -> None: + super().__init__(owner) + self._operations = operations + + def search(self, search: HighlightSearch) -> HighlightSearchResult: + return self._call(self._operations.search, search) + + def list( + self, + *, + book_id: int | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + highlighted_after: datetime | None = None, + highlighted_before: datetime | None = None, + limit: int | None = None, + ) -> builtins.list[Highlight]: + return self._call( + self._operations.list, + book_id=book_id, + updated_after=updated_after, + updated_before=updated_before, + highlighted_after=highlighted_after, + highlighted_before=highlighted_before, + limit=limit, + ) + + def get(self, highlight_id: int) -> Highlight: + return self._call(self._operations.get, highlight_id) + + def create(self, highlight: HighlightCreate) -> builtins.list[int]: + return self._call(self._operations.create, highlight) + + def create_from_fields( + self, + *, + text: str, + title: str | None = None, + author: str | None = None, + source_url: str | None = None, + note: str | None = None, + category: str | BookCategory | None = None, + highlighted_at: datetime | None = None, + ) -> HighlightCreateResult: + return self._call( + self._operations.create_from_fields, + text=text, + title=title, + author=author, + source_url=source_url, + note=note, + category=category, + highlighted_at=highlighted_at, + ) + + def push_batch( + self, + highlights: builtins.list[HighlightPushInput], + *, + auto_truncate: bool = True, + ) -> builtins.list[HighlightPushResult]: + return self._call( + self._operations.push_batch, + highlights, + auto_truncate=auto_truncate, + ) + + def update(self, highlight_id: int, update: HighlightUpdate) -> Highlight: + return self._call(self._operations.update, highlight_id, update) + + def update_batch( + self, + updates: builtins.list[HighlightUpdateInput], + *, + auto_truncate: bool = True, + ) -> builtins.list[HighlightUpdateResult]: + return self._call( + self._operations.update_batch, + updates, + auto_truncate=auto_truncate, + ) + + def delete(self, highlight_id: int) -> None: + return self._call(self._operations.delete, highlight_id) + + def delete_batch( + self, + highlight_ids: builtins.list[int], + ) -> builtins.list[HighlightDeleteResult]: + return self._call(self._operations.delete_batch, highlight_ids) + + def search_items( + self, + query: str, + *, + case_sensitive: bool = False, + ) -> builtins.list[Highlight]: + return self._call( + self._operations.search_items, + query, + case_sensitive=case_sensitive, + ) + + def since( + self, + *, + days: int | None = None, + hours: int | None = None, + since: datetime | None = None, + ) -> builtins.list[Highlight]: + return self._call( + self._operations.since, + days=days, + hours=hours, + since=since, + ) + + def with_notes(self) -> builtins.list[Highlight]: + return self._call(self._operations.with_notes) + + def count(self) -> int: + return self._call(self._operations.count) + + def bulk_tag(self, highlight_ids: builtins.list[int], tag: str) -> BulkResult[int]: + return self._call(self._operations.bulk_tag, highlight_ids, tag) + + def bulk_untag(self, highlight_ids: builtins.list[int], tag: str) -> BulkResult[int]: + return self._call(self._operations.bulk_untag, highlight_ids, tag) + + def export( + self, + *, + updated_after: datetime | None = None, + book_ids: builtins.list[int] | None = None, + limit: int = 20, + ) -> HighlightExportResult: + return self._call( + self._operations.export, + updated_after=updated_after, + book_ids=book_ids, + limit=limit, + ) + + +class _SyncBookOperations(_SyncOperationGroup): + """Synchronous adapter for every bounded book operation.""" + + def __init__(self, owner: Readwise, operations: BookOperations) -> None: + super().__init__(owner) + self._operations = operations + + def search(self, search: BookSearch) -> BookSearchResult: + return self._call(self._operations.search, search) + + def list( + self, + *, + category: BookCategory | None = None, + source: str | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + last_highlight_after: datetime | None = None, + last_highlight_before: datetime | None = None, + limit: int | None = None, + ) -> builtins.list[Book]: + return self._call( + self._operations.list, + category=category, + source=source, + updated_after=updated_after, + updated_before=updated_before, + last_highlight_after=last_highlight_after, + last_highlight_before=last_highlight_before, + limit=limit, + ) + + def get(self, book_id: int) -> Book: + return self._call(self._operations.get, book_id) + + def with_highlights(self, book_id: int) -> BookWithHighlights: + return self._call(self._operations.with_highlights, book_id) + + def recent( + self, + *, + days: int | None = None, + limit: int | None = None, + ) -> builtins.list[Book]: + return self._call(self._operations.recent, days=days, limit=limit) + + def statistics(self) -> ReadingStatistics: + return self._call(self._operations.statistics) + + def search_items( + self, + query: str, + *, + case_sensitive: bool = False, + ) -> builtins.list[Book]: + return self._call( + self._operations.search_items, + query, + case_sensitive=case_sensitive, + ) + + def count(self) -> int: + return self._call(self._operations.count) + + +class Readwise: + """Concept-oriented synchronous Readwise SDK. + + The facade owns a dedicated AnyIO blocking portal and routes every concept + operation to the canonical asynchronous service on the portal's event-loop + thread. Use the facade as a context manager so that it can close both the + asynchronous service client and the portal deterministically. + + Example:: + + from readwise_sdk import Readwise + from readwise_sdk.models import DocumentSearch + + with Readwise() as readwise: + result = readwise.documents.search(DocumentSearch(query="python")) + + ``readwise.raw`` intentionally retains the existing native synchronous + clients, including their legacy iterator APIs. + """ + + def __init__( + self, + api_key: str | None = None, + timeout: float = DEFAULT_TIMEOUT, + max_retries: int = DEFAULT_MAX_RETRIES, + retry_backoff: float = DEFAULT_RETRY_BACKOFF, + ) -> None: + """Compose sync adapters and owned clients without starting a thread yet.""" + self._async = AsyncReadwise(api_key, timeout, max_retries, retry_backoff) + raw_client = ReadwiseClient(api_key, timeout, max_retries, retry_backoff) + self._raw = _SyncRawClients(raw_client) + self._documents = _SyncDocumentOperations(self, self._async.documents) + self._highlights = _SyncHighlightOperations(self, self._async.highlights) + self._books = _SyncBookOperations(self, self._async.books) + self._portal: BlockingPortal | None = None + self._portal_context: AbstractContextManager[BlockingPortal] | None = None + self._lifecycle_lock = Lock() + + @property + def documents(self) -> _SyncDocumentOperations: + """Return synchronous canonical Reader document operations.""" + return self._documents + + @property + def highlights(self) -> _SyncHighlightOperations: + """Return synchronous canonical Readwise highlight operations.""" + return self._highlights + + @property + def books(self) -> _SyncBookOperations: + """Return synchronous canonical Readwise book operations.""" + return self._books + + # tags, digests, and sync mirror AsyncReadwise by remaining deferred. + + @property + def raw(self) -> _SyncRawClients: + """Return the existing low-level native synchronous clients.""" + return self._raw + + def _call[T]( + self, + operation: Callable[..., Awaitable[T]], + *args: Any, + **kwargs: Any, + ) -> T: + portal = self._portal + if portal is None: + raise RuntimeError("Readwise is not open; use it as a context manager") + if kwargs: + return portal.call(partial(operation, *args, **kwargs)) + return portal.call(operation, *args) + + def close(self) -> None: + """Close the async client and cancel portal work before joining its thread.""" + with self._lifecycle_lock: + portal = self._portal + portal_context = self._portal_context + if portal is None or portal_context is None: + self._raw._client.close() + return + + # Prevent new calls while the owned resources are being torn down. + self._portal = None + self._portal_context = None + try: + portal.call(self._async.close) + finally: + try: + shutdown = RuntimeError("Readwise portal is shutting down") + portal_context.__exit__( + type(shutdown), + shutdown, + shutdown.__traceback__, + ) + finally: + self._raw._client.close() + + def __enter__(self) -> Readwise: + """Start the facade's dedicated event-loop thread and return this instance.""" + with self._lifecycle_lock: + if self._portal is not None: + raise RuntimeError("Readwise is already open") + portal_context = start_blocking_portal(name="readwise-sdk-portal") + portal = portal_context.__enter__() + self._portal_context = portal_context + self._portal = portal + return self + + def __exit__(self, *args: Any) -> None: + """Close all owned lifecycle resources when leaving the context.""" + self.close() + + +__all__ = ["Readwise"] diff --git a/tests/sdk/test_sync.py b/tests/sdk/test_sync.py new file mode 100644 index 0000000..5d1a8bd --- /dev/null +++ b/tests/sdk/test_sync.py @@ -0,0 +1,297 @@ +"""Public contract tests for the preferred synchronous SDK facade.""" + +from __future__ import annotations + +import asyncio +import inspect +import threading +from concurrent.futures import CancelledError +from functools import partial + +import anyio +import httpx +import pytest +import respx + +from readwise_sdk.models import DocumentSearch, DocumentSearchResult +from readwise_sdk.v2.client import ReadwiseV2Client +from readwise_sdk.v3.client import ReadwiseV3Client + +V3_BASE = "https://readwise.io/api/v3" + + +@pytest.fixture(autouse=True) +def _wake_portal_loop_in_restricted_test_sandbox( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Keep AnyIO responsive where the sandbox blocks asyncio's self-pipe write.""" + import readwise_sdk.sdk.sync as sync_sdk + + start_blocking_portal = sync_sdk.start_blocking_portal + + def loop_factory() -> asyncio.AbstractEventLoop: + loop = asyncio.new_event_loop() + + def wakeup() -> None: + loop.call_later(0.01, wakeup) + + loop.call_soon(wakeup) + return loop + + monkeypatch.setattr( + sync_sdk, + "start_blocking_portal", + partial( + start_blocking_portal, + backend_options={"loop_factory": loop_factory}, + ), + ) + + +def test_readwise_is_importable_from_the_package_root() -> None: + """The preferred sync facade is available through the documented import.""" + from readwise_sdk import Readwise + + assert Readwise.__module__ == "readwise_sdk.sdk.sync" + + +@respx.mock +def test_ordinary_sync_use_returns_a_bounded_operation_result() -> None: + """A synchronous operation materializes the async-first service result.""" + from readwise_sdk import Readwise + + route = respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + { + "id": "doc-1", + "url": "https://reader/doc-1", + "source_url": "https://example.test/python", + "title": "Python", + } + ], + "nextPageCursor": None, + }, + ) + ) + + with Readwise(api_key="token") as readwise: + result = readwise.documents.search(DocumentSearch(query="python", limit=1)) + + assert isinstance(result, DocumentSearchResult) + assert [item.id for item in result.items] == ["doc-1"] + assert result.truncated is True + assert len(route.calls) == 1 + + +@pytest.mark.asyncio +async def test_sync_use_inside_a_running_event_loop_uses_its_own_thread( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Calling the sync facade from an active loop neither reuses nor nests that loop.""" + from readwise_sdk import Readwise + + caller_thread = threading.get_ident() + caller_loop = asyncio.get_running_loop() + + with Readwise(api_key="token") as readwise: + + async def search(search_input: DocumentSearch) -> tuple[int, asyncio.AbstractEventLoop]: + assert search_input.query == "threaded" + return threading.get_ident(), asyncio.get_running_loop() + + monkeypatch.setattr(readwise._async.documents, "search", search) + worker_thread, worker_loop = readwise.documents.search(DocumentSearch(query="threaded")) + + assert worker_thread != caller_thread + assert worker_loop is not caller_loop + + +def test_context_manager_owns_and_closes_every_lifecycle_resource() -> None: + """The facade closes its async client, portal thread, and native raw client.""" + from readwise_sdk import Readwise + + readwise = Readwise(api_key="token") + + with readwise as entered: + async_transport = entered._async._client.client + raw_transport = entered.raw._client.client + portal = entered._portal + assert entered is readwise + assert async_transport.is_closed is False + assert raw_transport.is_closed is False + assert portal is not None + + assert async_transport.is_closed is True + assert raw_transport.is_closed is True + assert readwise._async._client._client is None + assert readwise.raw._client._client is None + assert readwise._portal is None + with pytest.raises(RuntimeError, match="portal is not running"): + portal.call(lambda: None) + + +@respx.mock +def test_repeated_operations_reuse_one_facade_instance() -> None: + """One entered facade supports multiple calls through the same portal and client.""" + from readwise_sdk import Readwise + + route = respx.get(f"{V3_BASE}/list/").mock( + return_value=httpx.Response(200, json={"results": [], "nextPageCursor": None}) + ) + + with Readwise(api_key="token") as readwise: + portal = readwise._portal + async_transport = readwise._async._client.client + first = readwise.documents.search(DocumentSearch(query="first")) + second = readwise.documents.search(DocumentSearch(query="second")) + + assert readwise._portal is portal + assert readwise._async._client.client is async_transport + + assert first.items == [] + assert second.items == [] + assert len(route.calls) == 2 + + +def test_exception_crosses_the_portal_with_its_type_and_identity( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Operation exceptions are not wrapped or translated by the sync bridge.""" + from readwise_sdk import Readwise + + class PortalError(Exception): + pass + + error = PortalError("operation failed") + + with Readwise(api_key="token") as readwise: + + async def get(document_id: str, *, with_content: bool = False) -> None: + assert document_id == "doc-1" + assert with_content is True + raise error + + monkeypatch.setattr(readwise._async.documents, "get", get) + with pytest.raises(PortalError, match="operation failed") as captured: + readwise.documents.get("doc-1", with_content=True) + + assert captured.value is error + + +def test_close_cancels_an_in_flight_operation_and_is_idempotent( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Closing cannot hang behind unfinished portal work and safely tolerates repeats.""" + from readwise_sdk import Readwise + + readwise = Readwise(api_key="token") + readwise.__enter__() + started = threading.Event() + outcome: list[BaseException] = [] + + async def get(document_id: str, *, with_content: bool = False) -> None: + del document_id, with_content + started.set() + await anyio.sleep_forever() + + monkeypatch.setattr(readwise._async.documents, "get", get) + + def call_operation() -> None: + try: + readwise.documents.get("doc-1") + except BaseException as error: + outcome.append(error) + + operation_thread = threading.Thread(target=call_operation, daemon=True) + operation_thread.start() + assert started.wait(timeout=2) + + close_thread = threading.Thread(target=readwise.close, daemon=True) + close_thread.start() + close_thread.join(timeout=2) + operation_thread.join(timeout=2) + + assert close_thread.is_alive() is False + assert operation_thread.is_alive() is False + assert len(outcome) == 1 + assert isinstance(outcome[0], CancelledError) + assert readwise._portal is None + readwise.close() + + +def test_operations_require_an_open_context() -> None: + """A facade that has not entered its owned portal fails with a direct message.""" + from readwise_sdk import Readwise + + readwise = Readwise(api_key="token") + + with pytest.raises(RuntimeError, match="Readwise is not open; use it as a context manager"): + readwise.books.count() + + +def test_raw_retains_the_native_synchronous_compatibility_clients() -> None: + """The raw escape hatch retains legacy sync iterators instead of bridging streams.""" + from readwise_sdk import Readwise + + readwise = Readwise(api_key="token") + + assert isinstance(readwise.raw.v2, ReadwiseV2Client) + assert isinstance(readwise.raw.v3, ReadwiseV3Client) + assert readwise.raw.v2 is readwise.raw.v2 + assert readwise.raw.v3 is readwise.raw.v3 + assert readwise.raw.v2._client is readwise.raw._client + assert readwise.raw.v3._client is readwise.raw._client + + +def test_sync_surface_matches_the_operation_groups_available_in_stage_nine() -> None: + """No later-stage tags, digests, or sync concepts are implied prematurely.""" + from readwise_sdk import Readwise + + readwise = Readwise(api_key="token") + + assert not hasattr(readwise, "tags") + assert not hasattr(readwise, "digests") + assert not hasattr(readwise, "sync") + assert readwise.documents is readwise.documents + assert readwise.highlights is readwise.highlights + assert readwise.books is readwise.books + assert readwise.raw is readwise.raw + + +def test_sync_operation_groups_do_not_expose_async_streaming() -> None: + """The new sync API includes bounded methods but does not bridge async iterators.""" + from readwise_sdk import Readwise + + readwise = Readwise(api_key="token") + + assert not hasattr(readwise.highlights, "filter") + for operation_group in (readwise.documents, readwise.highlights, readwise.books): + assert not any( + inspect.iscoroutinefunction(value) + for name, value in vars(type(operation_group)).items() + if not name.startswith("_") and callable(value) + ) + + +def test_constructor_arguments_reach_async_operations_and_native_raw_clients() -> None: + """Both owned clients receive the facade's complete transport configuration.""" + from readwise_sdk import Readwise + + readwise = Readwise("token", 12.5, 7, 1.25) + expected = ("token", 12.5, 7, 1.25) + + assert ( + readwise._async._client.api_key, + readwise._async._client.timeout, + readwise._async._client.max_retries, + readwise._async._client.retry_backoff, + ) == expected + assert ( + readwise.raw._client.api_key, + readwise.raw._client.timeout, + readwise.raw._client.max_retries, + readwise.raw._client.retry_backoff, + ) == expected diff --git a/uv.lock b/uv.lock index 1fa7139..e07ff5f 100644 --- a/uv.lock +++ b/uv.lock @@ -9,7 +9,7 @@ resolution-markers = [ ] [options] -exclude-newer = "2026-07-07T01:43:53.664484438Z" +exclude-newer = "2026-07-07T04:53:56.535333344Z" exclude-newer-span = "P7D" [[package]] @@ -1178,6 +1178,7 @@ name = "readwise-plus" version = "0.2.1" source = { editable = "." } dependencies = [ + { name = "anyio" }, { name = "httpx" }, { name = "pydantic" }, ] @@ -1213,6 +1214,7 @@ docs = [ [package.metadata] requires-dist = [ + { name = "anyio", specifier = ">=4.0" }, { name = "httpx", specifier = ">=0.27.0" }, { name = "mcp", marker = "extra == 'mcp'", specifier = ">=1.26.0" }, { name = "pydantic", specifier = ">=2.0.0" }, From 886e1ef32b65c0ca2ec6544eded709a581a27142 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 00:27:18 -0500 Subject: [PATCH 14/24] test: add typer/rich to dev group so the CLI is tested in CI The cli extra (typer/rich) was not in the dev environment, so the CLI characterization + shell tests were silently skipped and the CLI wasn't type-checked in CI. Add them to the dev group (as done for mcp) so the CLI is a genuinely exercised surface during the restructure. No runtime deps change (typer/rich remain the optional [cli] extra for end users). Co-Authored-By: Claude Opus 4.8 (1M context) --- pyproject.toml | 2 ++ uv.lock | 6 +++++- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 0c5dc29..80294e4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -58,6 +58,8 @@ dev = [ "ruff>=0.14.0", "ty>=0.0.8", "mcp>=1.26.0", + "typer>=0.21.0", + "rich>=14.0.0", "mkdocs>=1.6.1", "mkdocs-material>=9.7.1", "mkdocstrings[python]>=1.0.0", diff --git a/uv.lock b/uv.lock index e07ff5f..8cdd922 100644 --- a/uv.lock +++ b/uv.lock @@ -9,7 +9,7 @@ resolution-markers = [ ] [options] -exclude-newer = "2026-07-07T04:53:56.535333344Z" +exclude-newer = "2026-07-07T05:26:34.329950385Z" exclude-newer-span = "P7D" [[package]] @@ -1203,8 +1203,10 @@ dev = [ { name = "pytest-asyncio" }, { name = "pytest-cov" }, { name = "respx" }, + { name = "rich" }, { name = "ruff" }, { name = "ty" }, + { name = "typer" }, ] docs = [ { name = "mkdocs" }, @@ -1234,8 +1236,10 @@ dev = [ { name = "pytest-asyncio", specifier = ">=0.24.0" }, { name = "pytest-cov", specifier = ">=6.0.0" }, { name = "respx", specifier = ">=0.22.0" }, + { name = "rich", specifier = ">=14.0.0" }, { name = "ruff", specifier = ">=0.14.0" }, { name = "ty", specifier = ">=0.0.8" }, + { name = "typer", specifier = ">=0.21.0" }, ] docs = [ { name = "mkdocs", specifier = ">=1.6.1" }, From 831823cd1919044cf9507533fa40e7f482ced105 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 00:27:18 -0500 Subject: [PATCH 15/24] refactor(cli): split shell into command modules over the operations core (stage 11) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Behavior-preserving adapter rewire. cli/main.py split into cli/commands/ {documents,highlights,books}.py + cli/context.py (service lifecycle + credential discovery) + cli/output.py (renderer). Each migrated command calls exactly one operation. Adds a global --output table|json|jsonl whose default reproduces today's Rich output byte-for-byte (machine data → stdout, notices → stderr). Existing command names/options/output/exit codes unchanged; test_cli_contracts.py and test_cli.py pass unchanged. cli/ stays ty-excluded until PR17. Gate green (767 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/cli/commands/__init__.py | 1 + src/readwise_sdk/cli/commands/books.py | 129 ++++++++ src/readwise_sdk/cli/commands/documents.py | 151 +++++++++ src/readwise_sdk/cli/commands/highlights.py | 158 ++++++++++ src/readwise_sdk/cli/context.py | 51 +++ src/readwise_sdk/cli/main.py | 327 ++------------------ src/readwise_sdk/cli/output.py | 98 ++++++ tests/test_cli_shell.py | 225 ++++++++++++++ 8 files changed, 842 insertions(+), 298 deletions(-) create mode 100644 src/readwise_sdk/cli/commands/__init__.py create mode 100644 src/readwise_sdk/cli/commands/books.py create mode 100644 src/readwise_sdk/cli/commands/documents.py create mode 100644 src/readwise_sdk/cli/commands/highlights.py create mode 100644 src/readwise_sdk/cli/context.py create mode 100644 src/readwise_sdk/cli/output.py create mode 100644 tests/test_cli_shell.py diff --git a/src/readwise_sdk/cli/commands/__init__.py b/src/readwise_sdk/cli/commands/__init__.py new file mode 100644 index 0000000..551ea95 --- /dev/null +++ b/src/readwise_sdk/cli/commands/__init__.py @@ -0,0 +1 @@ +"""Per-resource CLI command modules.""" diff --git a/src/readwise_sdk/cli/commands/books.py b/src/readwise_sdk/cli/commands/books.py new file mode 100644 index 0000000..afef31e --- /dev/null +++ b/src/readwise_sdk/cli/commands/books.py @@ -0,0 +1,129 @@ +"""Book CLI commands backed by canonical operations.""" + +from __future__ import annotations + +from typing import Annotated + +import typer +from rich.table import Table + +from readwise_sdk.cli.context import discover_api_key, run_operation +from readwise_sdk.cli.output import OutputFormat, renderer +from readwise_sdk.v2.models import BookCategory + +books_app = typer.Typer(help="Manage books") + + +def _book_data(books: list) -> list[dict]: + return [ + { + "id": book.id, + "title": book.title, + "author": book.author, + "highlights": book.num_highlights, + } + for book in books + ] + + +@books_app.command("list") +def list_books( + limit: Annotated[int, typer.Option(help="Maximum number of books")] = 20, + category: Annotated[str | None, typer.Option(help="Filter by category")] = None, + json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False, +) -> None: + """List books.""" + api_key = discover_api_key() + output = renderer(legacy_json=json_output) + parsed_category = None + if category: + try: + parsed_category = BookCategory(category) + except ValueError: + output.error("[red]Invalid category. Use: books, articles, tweets, podcasts[/red]") + raise typer.Exit(1) from None + + books = run_operation( + lambda service: service.books.list(category=parsed_category, limit=limit), + api_key=api_key, + ) + + if output.output_format is not OutputFormat.TABLE: + output.data(_book_data(books)) + return + + table = Table(title=f"Books ({len(books)} shown)") + table.add_column("ID", style="cyan") + table.add_column("Title", max_width=40) + table.add_column("Author", max_width=20) + table.add_column("Highlights", justify="right") + + for book in books: + title = book.title[:37] + "..." if len(book.title) > 40 else book.title + author = ( + book.author[:17] + "..." if book.author and len(book.author) > 20 else book.author + ) or "" + table.add_row(str(book.id), title, author, str(book.num_highlights)) + + output.table(table) + + +@books_app.command("show") +def show_book( + book_id: Annotated[int, typer.Argument(help="Book ID")], +) -> None: + """Show a single book with its highlights.""" + api_key = discover_api_key() + output = renderer() + try: + result = run_operation( + lambda service: service.books.with_highlights(book_id), + api_key=api_key, + ) + + book = result.book + if output.output_format is not OutputFormat.TABLE: + output.data( + { + "id": book.id, + "title": book.title, + "author": book.author, + "category": book.category.value if book.category else None, + "highlights": book.num_highlights, + "source": book.source, + "recent_highlights": [ + { + "id": highlight.id, + "text": ( + highlight.text[:100] + "..." + if len(highlight.text) > 100 + else highlight.text + ), + } + for highlight in result.highlights[:5] + ], + } + ) + return + + output.message(f"[bold]ID:[/bold] {book.id}") + output.message(f"[bold]Title:[/bold] {book.title}") + if book.author: + output.message(f"[bold]Author:[/bold] {book.author}") + if book.category: + output.message(f"[bold]Category:[/bold] {book.category.value}") + output.message(f"[bold]Highlights:[/bold] {book.num_highlights}") + if book.source: + output.message(f"[bold]Source:[/bold] {book.source}") + + if result.highlights: + output.message(f"\n[bold]Recent Highlights ({len(result.highlights)}):[/bold]") + for highlight in result.highlights[:5]: + text = highlight.text[:100] + "..." if len(highlight.text) > 100 else highlight.text + output.message(f" - {text}") + except Exception as error: + output.error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + +__all__ = ["books_app"] diff --git a/src/readwise_sdk/cli/commands/documents.py b/src/readwise_sdk/cli/commands/documents.py new file mode 100644 index 0000000..bf01b8c --- /dev/null +++ b/src/readwise_sdk/cli/commands/documents.py @@ -0,0 +1,151 @@ +"""Reader document CLI commands backed by canonical operations.""" + +from __future__ import annotations + +from typing import Annotated + +import typer +from rich.table import Table + +from readwise_sdk.cli.context import discover_api_key, run_operation +from readwise_sdk.cli.output import OutputFormat, renderer +from readwise_sdk.v3.models import DocumentCreate, DocumentLocation + +reader_app = typer.Typer(help="Manage Reader documents") + + +def _document_data(documents: list) -> list[dict]: + return [ + { + "id": document.id, + "title": document.title, + "url": document.url, + "category": document.category.value if document.category else None, + } + for document in documents + ] + + +@reader_app.command("inbox") +def reader_inbox( + limit: Annotated[int, typer.Option(help="Maximum number of items")] = 20, + json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False, +) -> None: + """List inbox documents.""" + api_key = discover_api_key() + documents = run_operation( + lambda service: service.documents.inbox(limit=limit), + api_key=api_key, + ) + + output = renderer(legacy_json=json_output) + if output.output_format is not OutputFormat.TABLE: + output.data(_document_data(documents)) + return + + table = Table(title=f"Inbox ({len(documents)} shown)") + table.add_column("ID", style="cyan", max_width=15) + table.add_column("Title", max_width=40) + table.add_column("Category") + + for document in documents: + title = ( + document.title[:37] + "..." + if document.title and len(document.title) > 40 + else document.title + ) or "" + category = document.category.value if document.category else "" + table.add_row(document.id[:15], title, category) + + output.table(table) + + +@reader_app.command("save") +def reader_save( + url: Annotated[str, typer.Argument(help="URL to save")], +) -> None: + """Save a URL to Reader.""" + api_key = discover_api_key() + output = renderer() + try: + result = run_operation( + lambda service: service.documents.save(DocumentCreate(url=url)), + api_key=api_key, + ) + + if output.output_format is not OutputFormat.TABLE: + output.data({"id": result.id, "url": result.url}) + return + output.message("[green]Saved![/green]") + output.message(f"[bold]ID:[/bold] {result.id}") + output.message(f"[bold]URL:[/bold] {result.url}") + except Exception as error: + output.error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + +@reader_app.command("archive") +def reader_archive( + document_id: Annotated[str, typer.Argument(help="Document ID to archive")], +) -> None: + """Archive a document.""" + api_key = discover_api_key() + output = renderer() + try: + result = run_operation( + lambda service: service.documents.move(document_id, DocumentLocation.ARCHIVE), + api_key=api_key, + ) + + if output.output_format is not OutputFormat.TABLE: + output.data({"id": result.id, "url": result.url}) + return + output.message(f"[green]Archived document {document_id}[/green]") + except Exception as error: + output.error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + +@reader_app.command("stats") +def reader_stats() -> None: + """Show reading queue statistics.""" + api_key = discover_api_key() + stats = run_operation( + lambda service: service.documents.statistics(), + api_key=api_key, + ) + + output = renderer() + if output.output_format is not OutputFormat.TABLE: + output.data( + { + "inbox_count": stats.inbox_count, + "reading_list_count": stats.reading_list_count, + "total_unread": stats.total_unread, + "oldest_item_age_days": stats.oldest_item_age_days, + "average_age_days": stats.average_age_days, + "items_older_than_30_days": stats.items_older_than_30_days, + "items_older_than_90_days": stats.items_older_than_90_days, + "by_category": stats.by_category, + } + ) + return + + output.message("[bold]Reading Queue Statistics[/bold]") + output.message(f" Inbox: {stats.inbox_count}") + output.message(f" Reading List: {stats.reading_list_count}") + output.message(f" Total Unread: {stats.total_unread}") + if stats.oldest_item_age_days is not None: + output.message(f" Oldest Item: {stats.oldest_item_age_days} days") + if stats.average_age_days is not None: + output.message(f" Average Age: {stats.average_age_days:.1f} days") + output.message(f" Items > 30 days: {stats.items_older_than_30_days}") + output.message(f" Items > 90 days: {stats.items_older_than_90_days}") + + if stats.by_category: + output.message("\n[bold]By Category:[/bold]") + for category, count in sorted(stats.by_category.items(), key=lambda item: -item[1]): + output.message(f" {category}: {count}") + + +__all__ = ["reader_app"] diff --git a/src/readwise_sdk/cli/commands/highlights.py b/src/readwise_sdk/cli/commands/highlights.py new file mode 100644 index 0000000..99fcbcc --- /dev/null +++ b/src/readwise_sdk/cli/commands/highlights.py @@ -0,0 +1,158 @@ +"""Highlight CLI commands backed by canonical operations.""" + +from __future__ import annotations + +from datetime import UTC, datetime, timedelta +from typing import Annotated + +import typer +from rich.table import Table + +from readwise_sdk.cli.context import discover_api_key, run_operation +from readwise_sdk.cli.output import OutputFormat, renderer +from readwise_sdk.workflows.digest import DigestBuilder, DigestFormat + +highlights_app = typer.Typer(help="Manage highlights") + + +def _highlight_data(highlights: list, *, truncate: bool) -> list[dict]: + return [ + { + "id": highlight.id, + "text": highlight.text[:100] + "..." + if truncate and len(highlight.text) > 100 + else highlight.text, + "note": highlight.note, + } + for highlight in highlights + ] + + +@highlights_app.command("list") +def list_highlights( + limit: Annotated[int, typer.Option(help="Maximum number of highlights")] = 20, + book_id: Annotated[int | None, typer.Option(help="Filter by book ID")] = None, + days: Annotated[int | None, typer.Option(help="Only show highlights from last N days")] = None, + json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False, +) -> None: + """List highlights.""" + api_key = discover_api_key() + since = datetime.now(UTC) - timedelta(days=days) if days else None + highlights = run_operation( + lambda service: service.highlights.list( + book_id=book_id, + updated_after=since, + limit=limit, + ), + api_key=api_key, + ) + + output = renderer(legacy_json=json_output) + if output.output_format is not OutputFormat.TABLE: + output.data(_highlight_data(highlights, truncate=json_output)) + return + + table = Table(title=f"Highlights ({len(highlights)} shown)") + table.add_column("ID", style="cyan") + table.add_column("Text", max_width=60) + table.add_column("Note", max_width=30) + + for highlight in highlights: + text = highlight.text[:57] + "..." if len(highlight.text) > 60 else highlight.text + note = ( + highlight.note[:27] + "..." + if highlight.note and len(highlight.note) > 30 + else highlight.note + ) or "" + table.add_row(str(highlight.id), text, note) + + output.table(table) + + +@highlights_app.command("show") +def show_highlight( + highlight_id: Annotated[int, typer.Argument(help="Highlight ID")], +) -> None: + """Show a single highlight.""" + api_key = discover_api_key() + output = renderer() + try: + highlight = run_operation( + lambda service: service.highlights.get(highlight_id), + api_key=api_key, + ) + + if output.output_format is not OutputFormat.TABLE: + output.data( + { + "id": highlight.id, + "text": highlight.text, + "note": highlight.note, + "location": highlight.location, + "tags": [tag.name for tag in highlight.tags], + "highlighted_at": ( + highlight.highlighted_at.isoformat() if highlight.highlighted_at else None + ), + } + ) + return + + output.message(f"[bold]ID:[/bold] {highlight.id}") + output.message(f"[bold]Text:[/bold] {highlight.text}") + if highlight.note: + output.message(f"[bold]Note:[/bold] {highlight.note}") + if highlight.location: + output.message(f"[bold]Location:[/bold] {highlight.location}") + if highlight.tags: + tag_names = ", ".join(tag.name for tag in highlight.tags) + output.message(f"[bold]Tags:[/bold] {tag_names}") + if highlight.highlighted_at: + output.message(f"[bold]Highlighted:[/bold] {highlight.highlighted_at}") + except Exception as error: + output.error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + +@highlights_app.command("export") +def export_highlights( + format_type: Annotated[str, typer.Option("--format", "-f", help="Output format")] = "markdown", + output: Annotated[str | None, typer.Option("-o", help="Output file")] = None, + days: Annotated[ + int | None, typer.Option(help="Only export highlights from last N days") + ] = None, +) -> None: + """Export highlights to a file.""" + api_key = discover_api_key() + command_output = renderer() + try: + fmt = DigestFormat(format_type) + except ValueError: + command_output.error("[red]Invalid format. Use: markdown, json, csv, text[/red]") + raise typer.Exit(1) from None + + since = datetime.now(UTC) - timedelta(days=days) if days else None + highlights = run_operation( + lambda service: service.highlights.list(updated_after=since), + api_key=api_key, + ) + + # Stage 13 moves digest presentation. Reuse the legacy formatter here so this + # adapter changes only data acquisition and preserves every output byte. + formatter = DigestBuilder.__new__(DigestBuilder) + content = formatter._format_digest( + highlights, + title="Custom Digest", + output_format=fmt, + group_by_book=True, + group_by_date=False, + ) + + if output: + with open(output, "w") as file: + file.write(content) + command_output.message(f"[green]Exported to {output}[/green]") + else: + command_output.message(content) + + +__all__ = ["highlights_app"] diff --git a/src/readwise_sdk/cli/context.py b/src/readwise_sdk/cli/context.py new file mode 100644 index 0000000..ab40b39 --- /dev/null +++ b/src/readwise_sdk/cli/context.py @@ -0,0 +1,51 @@ +"""CLI credential discovery and service lifecycle.""" + +from __future__ import annotations + +import os +from collections.abc import Awaitable, Callable + +import anyio +import typer + +from readwise_sdk.cli.output import OutputFormat, console, current_output_format, error_console +from readwise_sdk.client import ReadwiseClient +from readwise_sdk.sdk.async_ import AsyncReadwise + + +def discover_api_key() -> str: + """Return the configured API key or preserve the legacy CLI failure.""" + api_key = os.environ.get("READWISE_API_KEY") + if api_key: + return api_key + + message = "[red]Error: READWISE_API_KEY environment variable not set[/red]" + if current_output_format() is OutputFormat.TABLE: + # Characterizes current behavior: this application error is on stdout. + console.print(message) + else: + error_console.print(message) + raise typer.Exit(1) + + +def get_client() -> ReadwiseClient: + """Return the legacy client for untouched commands and import compatibility.""" + return ReadwiseClient(api_key=discover_api_key()) + + +def run_operation[ResultT]( + operation: Callable[[AsyncReadwise], Awaitable[ResultT]], + *, + api_key: str | None = None, +) -> ResultT: + """Run exactly one operation inside an owned async service lifecycle.""" + resolved_api_key = api_key or discover_api_key() + + async def invoke() -> ResultT: + async with AsyncReadwise(api_key=resolved_api_key) as service: + return await operation(service) + + return anyio.run(invoke) + + +__all__ = ["discover_api_key", "get_client", "run_operation"] diff --git a/src/readwise_sdk/cli/main.py b/src/readwise_sdk/cli/main.py index 51b3415..a0324d6 100644 --- a/src/readwise_sdk/cli/main.py +++ b/src/readwise_sdk/cli/main.py @@ -3,22 +3,28 @@ from __future__ import annotations import json -import os import sys -from datetime import UTC, datetime, timedelta from importlib.metadata import version as pkg_version from typing import Annotated try: import typer - from rich.console import Console from rich.table import Table except ImportError: print("CLI dependencies not installed. Install with: pip install readwise-plus[cli]") sys.exit(1) -from readwise_sdk.client import ReadwiseClient -from readwise_sdk.v2.models import BookCategory +from readwise_sdk.cli.commands.books import books_app +from readwise_sdk.cli.commands.documents import reader_app +from readwise_sdk.cli.commands.highlights import highlights_app +from readwise_sdk.cli.context import get_client +from readwise_sdk.cli.output import ( + CliOutputContext, + OutputFormat, + console, + current_output_format, + renderer, +) from readwise_sdk.workflows.digest import DigestBuilder, DigestFormat from readwise_sdk.workflows.tags import TagPattern, TagWorkflow @@ -27,12 +33,21 @@ help="Readwise SDK CLI - Manage your Readwise highlights and Reader documents", no_args_is_help=True, ) -console = Console() + + +@app.callback() +def cli_context( + ctx: typer.Context, + output: Annotated[ + OutputFormat, + typer.Option("--output", help="Output format: table, json, or jsonl"), + ] = OutputFormat.TABLE, +) -> None: + """Configure shared CLI invocation state.""" + ctx.obj = CliOutputContext(output_format=output) + # Sub-apps -highlights_app = typer.Typer(help="Manage highlights") -books_app = typer.Typer(help="Manage books") -reader_app = typer.Typer(help="Manage Reader documents") sync_app = typer.Typer(help="Sync operations") digest_app = typer.Typer(help="Generate digests") tags_app = typer.Typer(help="Manage tags") @@ -45,294 +60,6 @@ app.add_typer(tags_app, name="tags") -def get_client() -> ReadwiseClient: - """Get a configured Readwise client.""" - api_key = os.environ.get("READWISE_API_KEY") - if not api_key: - console.print("[red]Error: READWISE_API_KEY environment variable not set[/red]") - raise typer.Exit(1) - return ReadwiseClient(api_key=api_key) - - -# Highlights commands -@highlights_app.command("list") -def list_highlights( - limit: Annotated[int, typer.Option(help="Maximum number of highlights")] = 20, - book_id: Annotated[int | None, typer.Option(help="Filter by book ID")] = None, - days: Annotated[int | None, typer.Option(help="Only show highlights from last N days")] = None, - json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False, -) -> None: - """List highlights.""" - client = get_client() - - since = None - if days: - since = datetime.now(UTC) - timedelta(days=days) - - highlights = [] - for i, h in enumerate(client.v2.list_highlights(book_id=book_id, updated_after=since)): - if i >= limit: - break - highlights.append(h) - - if json_output: - data = [ - { - "id": h.id, - "text": h.text[:100] + "..." if len(h.text) > 100 else h.text, - "note": h.note, - } - for h in highlights - ] - console.print(json.dumps(data, indent=2)) - else: - table = Table(title=f"Highlights ({len(highlights)} shown)") - table.add_column("ID", style="cyan") - table.add_column("Text", max_width=60) - table.add_column("Note", max_width=30) - - for h in highlights: - text = h.text[:57] + "..." if len(h.text) > 60 else h.text - note = (h.note[:27] + "..." if h.note and len(h.note) > 30 else h.note) or "" - table.add_row(str(h.id), text, note) - - console.print(table) - - -@highlights_app.command("show") -def show_highlight( - highlight_id: Annotated[int, typer.Argument(help="Highlight ID")], -) -> None: - """Show a single highlight.""" - client = get_client() - - try: - h = client.v2.get_highlight(highlight_id) - console.print(f"[bold]ID:[/bold] {h.id}") - console.print(f"[bold]Text:[/bold] {h.text}") - if h.note: - console.print(f"[bold]Note:[/bold] {h.note}") - if h.location: - console.print(f"[bold]Location:[/bold] {h.location}") - if h.tags: - tag_names = ", ".join(t.name for t in h.tags) - console.print(f"[bold]Tags:[/bold] {tag_names}") - if h.highlighted_at: - console.print(f"[bold]Highlighted:[/bold] {h.highlighted_at}") - except Exception as e: - console.print(f"[red]Error: {e}[/red]") - raise typer.Exit(1) from None - - -@highlights_app.command("export") -def export_highlights( - format_type: Annotated[str, typer.Option("--format", "-f", help="Output format")] = "markdown", - output: Annotated[str | None, typer.Option("-o", help="Output file")] = None, - days: Annotated[ - int | None, typer.Option(help="Only export highlights from last N days") - ] = None, -) -> None: - """Export highlights to a file.""" - client = get_client() - builder = DigestBuilder(client) - - try: - fmt = DigestFormat(format_type) - except ValueError: - console.print("[red]Invalid format. Use: markdown, json, csv, text[/red]") - raise typer.Exit(1) from None - - if days: - content = builder.create_custom_digest( - since=datetime.now(UTC) - timedelta(days=days), - output_format=fmt, - ) - else: - content = builder.create_custom_digest(output_format=fmt) - - if output: - with open(output, "w") as f: - f.write(content) - console.print(f"[green]Exported to {output}[/green]") - else: - console.print(content) - - -# Books commands -@books_app.command("list") -def list_books( - limit: Annotated[int, typer.Option(help="Maximum number of books")] = 20, - category: Annotated[str | None, typer.Option(help="Filter by category")] = None, - json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False, -) -> None: - """List books.""" - client = get_client() - - cat = None - if category: - try: - cat = BookCategory(category) - except ValueError: - console.print("[red]Invalid category. Use: books, articles, tweets, podcasts[/red]") - raise typer.Exit(1) from None - - books = [] - for i, b in enumerate(client.v2.list_books(category=cat)): - if i >= limit: - break - books.append(b) - - if json_output: - data = [ - {"id": b.id, "title": b.title, "author": b.author, "highlights": b.num_highlights} - for b in books - ] - console.print(json.dumps(data, indent=2)) - else: - table = Table(title=f"Books ({len(books)} shown)") - table.add_column("ID", style="cyan") - table.add_column("Title", max_width=40) - table.add_column("Author", max_width=20) - table.add_column("Highlights", justify="right") - - for b in books: - title = b.title[:37] + "..." if len(b.title) > 40 else b.title - author = (b.author[:17] + "..." if b.author and len(b.author) > 20 else b.author) or "" - table.add_row(str(b.id), title, author, str(b.num_highlights)) - - console.print(table) - - -@books_app.command("show") -def show_book( - book_id: Annotated[int, typer.Argument(help="Book ID")], -) -> None: - """Show a single book with its highlights.""" - client = get_client() - - try: - b = client.v2.get_book(book_id) - console.print(f"[bold]ID:[/bold] {b.id}") - console.print(f"[bold]Title:[/bold] {b.title}") - if b.author: - console.print(f"[bold]Author:[/bold] {b.author}") - if b.category: - console.print(f"[bold]Category:[/bold] {b.category.value}") - console.print(f"[bold]Highlights:[/bold] {b.num_highlights}") - if b.source: - console.print(f"[bold]Source:[/bold] {b.source}") - - # Show recent highlights - highlights = list(client.v2.list_highlights(book_id=book_id)) - if highlights: - console.print(f"\n[bold]Recent Highlights ({len(highlights)}):[/bold]") - for h in highlights[:5]: - text = h.text[:100] + "..." if len(h.text) > 100 else h.text - console.print(f" - {text}") - except Exception as e: - console.print(f"[red]Error: {e}[/red]") - raise typer.Exit(1) from None - - -# Reader commands -@reader_app.command("inbox") -def reader_inbox( - limit: Annotated[int, typer.Option(help="Maximum number of items")] = 20, - json_output: Annotated[bool, typer.Option("--json", help="Output as JSON")] = False, -) -> None: - """List inbox documents.""" - client = get_client() - - docs = [] - for i, d in enumerate(client.v3.get_inbox()): - if i >= limit: - break - docs.append(d) - - if json_output: - data = [ - { - "id": d.id, - "title": d.title, - "url": d.url, - "category": d.category.value if d.category else None, - } - for d in docs - ] - console.print(json.dumps(data, indent=2)) - else: - table = Table(title=f"Inbox ({len(docs)} shown)") - table.add_column("ID", style="cyan", max_width=15) - table.add_column("Title", max_width=40) - table.add_column("Category") - - for d in docs: - title = (d.title[:37] + "..." if d.title and len(d.title) > 40 else d.title) or "" - cat = d.category.value if d.category else "" - table.add_row(d.id[:15], title, cat) - - console.print(table) - - -@reader_app.command("save") -def reader_save( - url: Annotated[str, typer.Argument(help="URL to save")], -) -> None: - """Save a URL to Reader.""" - client = get_client() - - try: - result = client.v3.save_url(url) - console.print("[green]Saved![/green]") - console.print(f"[bold]ID:[/bold] {result.id}") - console.print(f"[bold]URL:[/bold] {result.url}") - except Exception as e: - console.print(f"[red]Error: {e}[/red]") - raise typer.Exit(1) from None - - -@reader_app.command("archive") -def reader_archive( - document_id: Annotated[str, typer.Argument(help="Document ID to archive")], -) -> None: - """Archive a document.""" - client = get_client() - - try: - client.v3.archive(document_id) - console.print(f"[green]Archived document {document_id}[/green]") - except Exception as e: - console.print(f"[red]Error: {e}[/red]") - raise typer.Exit(1) from None - - -@reader_app.command("stats") -def reader_stats() -> None: - """Show reading queue statistics.""" - client = get_client() - - from readwise_sdk.workflows.inbox import ReadingInbox - - inbox_workflow = ReadingInbox(client) - stats = inbox_workflow.get_queue_stats() - - console.print("[bold]Reading Queue Statistics[/bold]") - console.print(f" Inbox: {stats.inbox_count}") - console.print(f" Reading List: {stats.reading_list_count}") - console.print(f" Total Unread: {stats.total_unread}") - if stats.oldest_item_age_days is not None: - console.print(f" Oldest Item: {stats.oldest_item_age_days} days") - if stats.average_age_days is not None: - console.print(f" Average Age: {stats.average_age_days:.1f} days") - console.print(f" Items > 30 days: {stats.items_older_than_30_days}") - console.print(f" Items > 90 days: {stats.items_older_than_90_days}") - - if stats.by_category: - console.print("\n[bold]By Category:[/bold]") - for cat, count in sorted(stats.by_category.items(), key=lambda x: -x[1]): - console.print(f" {cat}: {count}") - - # Sync commands @sync_app.command("full") def sync_full() -> None: @@ -745,7 +472,11 @@ def tag_report( @app.command("version") def version() -> None: """Show version information.""" - console.print(f"readwise-plus v{pkg_version('readwise-plus')}") + package_version = pkg_version("readwise-plus") + if current_output_format() is OutputFormat.TABLE: + console.print(f"readwise-plus v{package_version}") + else: + renderer().data({"version": package_version}) if __name__ == "__main__": diff --git a/src/readwise_sdk/cli/output.py b/src/readwise_sdk/cli/output.py new file mode 100644 index 0000000..6a66996 --- /dev/null +++ b/src/readwise_sdk/cli/output.py @@ -0,0 +1,98 @@ +"""Shared rendering for CLI human and machine output.""" + +from __future__ import annotations + +import json +from dataclasses import dataclass +from enum import StrEnum +from typing import Any + +import click +from rich.console import Console +from rich.table import Table + + +class OutputFormat(StrEnum): + """Supported global CLI output formats.""" + + TABLE = "table" + JSON = "json" + JSONL = "jsonl" + + +@dataclass(frozen=True, slots=True) +class CliOutputContext: + """Output selection stored on the root Click context.""" + + output_format: OutputFormat = OutputFormat.TABLE + + +console = Console() +error_console = Console(stderr=True) + + +def current_output_format() -> OutputFormat: + """Return the output mode selected on the root CLI invocation.""" + context = click.get_current_context(silent=True) + if context is None: + return OutputFormat.TABLE + root = context.find_root() + if isinstance(root.obj, CliOutputContext): + return root.obj.output_format + return OutputFormat.TABLE + + +class OutputRenderer: + """Render adapter-owned values without owning operation semantics.""" + + def __init__( + self, + output_format: OutputFormat | None = None, + *, + legacy_json: bool = False, + ) -> None: + self.output_format = output_format or current_output_format() + self.legacy_json = legacy_json + + def data(self, value: Any) -> None: + """Write structured data according to the selected machine format.""" + if self.output_format is OutputFormat.JSONL: + values = value if isinstance(value, list) else [value] + for item in values: + click.echo(json.dumps(item, separators=(",", ":"))) + return + serialized = json.dumps(value, indent=2) + if self.legacy_json: + console.print(serialized) + else: + click.echo(serialized) + + def table(self, table: Table) -> None: + """Write a Rich table using the legacy console configuration.""" + console.print(table) + + def message(self, message: str) -> None: + """Write human-facing command output with legacy Rich behavior.""" + console.print(message) + + def error(self, message: str) -> None: + """Keep legacy errors on stdout, but isolate machine-mode errors.""" + target = console if self.output_format is OutputFormat.TABLE else error_console + target.print(message) + + +def renderer(*, legacy_json: bool = False) -> OutputRenderer: + """Return a renderer, preserving a command-local legacy ``--json`` flag.""" + output_format = OutputFormat.JSON if legacy_json else current_output_format() + return OutputRenderer(output_format, legacy_json=legacy_json) + + +__all__ = [ + "CliOutputContext", + "OutputFormat", + "OutputRenderer", + "console", + "current_output_format", + "error_console", + "renderer", +] diff --git a/tests/test_cli_shell.py b/tests/test_cli_shell.py new file mode 100644 index 0000000..b7b094d --- /dev/null +++ b/tests/test_cli_shell.py @@ -0,0 +1,225 @@ +"""Focused contracts for the restructured CLI shell.""" + +from __future__ import annotations + +import json +from importlib.metadata import version +from types import SimpleNamespace +from typing import Any + +import anyio +import httpx +import pytest +import respx +from typer.testing import CliRunner + +from readwise_sdk.cli.main import app +from readwise_sdk.client import READWISE_API_V2_BASE +from readwise_sdk.operations import DocumentStatistics +from readwise_sdk.v2.models import Book, Highlight +from readwise_sdk.v3.models import CreateDocumentResult, Document + +runner = CliRunner() + + +def test_global_json_output_renders_version_as_machine_data() -> None: + """The new global output mode renders version data on stdout only.""" + result = runner.invoke(app, ["--output", "json", "version"]) + + assert result.exit_code == 0 + assert json.loads(result.stdout) == {"version": version("readwise-plus")} + assert result.stderr == "" + + +@respx.mock +def test_global_json_output_renders_highlight_list_without_legacy_flag( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Global JSON uses the existing highlight projection and stdout stream.""" + monkeypatch.setenv("READWISE_API_KEY", "token") + respx.get(f"{READWISE_API_V2_BASE}/highlights/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [{"id": 7, "text": "Exact text", "note": None}], + "next": None, + }, + ) + ) + + result = runner.invoke(app, ["--output", "json", "highlights", "list"]) + + assert result.exit_code == 0 + assert json.loads(result.stdout) == [{"id": 7, "text": "Exact text", "note": None}] + assert result.stderr == "" + + +@respx.mock +def test_global_machine_output_keeps_full_values_and_supports_jsonl( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """New machine modes avoid the legacy JSON truncation policy.""" + monkeypatch.setenv("READWISE_API_KEY", "token") + full_text = "A" * 120 + respx.get(f"{READWISE_API_V2_BASE}/highlights/").mock( + return_value=httpx.Response( + 200, + json={ + "results": [ + {"id": 1, "text": full_text, "note": None}, + {"id": 2, "text": "second", "note": "note"}, + ], + "next": None, + }, + ) + ) + + json_result = runner.invoke(app, ["--output", "json", "highlights", "list"]) + jsonl_result = runner.invoke(app, ["--output", "jsonl", "highlights", "list"]) + + assert json.loads(json_result.stdout)[0]["text"] == full_text + assert [json.loads(line)["id"] for line in jsonl_result.stdout.splitlines()] == [1, 2] + + +def test_machine_mode_routes_missing_credentials_to_stderr( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """New machine modes reserve stdout for data.""" + monkeypatch.delenv("READWISE_API_KEY", raising=False) + + result = runner.invoke(app, ["--output", "json", "highlights", "list"]) + + assert result.exit_code == 1 + assert result.stdout == "" + assert result.stderr == "Error: READWISE_API_KEY environment variable not set\n" + + +def _operation_runner(service: Any): + def run(operation, *, api_key: str | None = None): + assert api_key == "token" + + async def invoke(): + return await operation(service) + + return anyio.run(invoke) + + return run + + +def test_highlight_commands_each_call_one_highlight_operation( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Every migrated highlight handler crosses the operation seam once.""" + from readwise_sdk.cli.commands import highlights as commands + + monkeypatch.setenv("READWISE_API_KEY", "token") + calls: list[str] = [] + + class Operations: + async def list(self, **kwargs): + calls.append("list") + return [Highlight(id=1, text="Highlight")] + + async def get(self, highlight_id: int): + calls.append("get") + return Highlight(id=highlight_id, text="Highlight") + + service = SimpleNamespace(highlights=Operations()) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + + for arguments, expected in ( + (["--output", "json", "highlights", "list"], "list"), + (["--output", "json", "highlights", "show", "1"], "get"), + (["highlights", "export"], "list"), + ): + calls.clear() + result = runner.invoke(app, arguments) + assert result.exit_code == 0 + assert calls == [expected] + + +def test_book_commands_each_call_one_book_operation(monkeypatch: pytest.MonkeyPatch) -> None: + """Every migrated book handler crosses the operation seam once.""" + from readwise_sdk.cli.commands import books as commands + + monkeypatch.setenv("READWISE_API_KEY", "token") + calls: list[str] = [] + book = Book(id=1, title="Book") + + class Operations: + async def list(self, **kwargs): + calls.append("list") + return [book] + + async def with_highlights(self, book_id: int): + calls.append("with_highlights") + return SimpleNamespace(book=book, highlights=[]) + + service = SimpleNamespace(books=Operations()) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + + for arguments, expected in ( + (["--output", "json", "books", "list"], "list"), + (["--output", "json", "books", "show", "1"], "with_highlights"), + ): + calls.clear() + result = runner.invoke(app, arguments) + assert result.exit_code == 0 + assert calls == [expected] + + +def test_document_commands_each_call_one_document_operation( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Every migrated Reader handler crosses the operation seam once.""" + from readwise_sdk.cli.commands import documents as commands + + monkeypatch.setenv("READWISE_API_KEY", "token") + calls: list[str] = [] + document = Document(id="doc-1", url="https://example.com") + create_result = CreateDocumentResult(id="doc-1", url="https://example.com") + statistics = DocumentStatistics( + inbox_count=1, + reading_list_count=0, + archive_count=0, + total_count=1, + total_unread=1, + by_category={}, + oldest_inbox_item=document, + newest_inbox_item=document, + oldest_item_age_days=None, + average_age_days=None, + items_older_than_30_days=0, + items_older_than_90_days=0, + ) + + class Operations: + async def inbox(self, **kwargs): + calls.append("inbox") + return [document] + + async def save(self, request): + calls.append("save") + return create_result + + async def move(self, document_id, location): + calls.append("move") + return create_result + + async def statistics(self): + calls.append("statistics") + return statistics + + service = SimpleNamespace(documents=Operations()) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + + for arguments, expected in ( + (["--output", "json", "reader", "inbox"], "inbox"), + (["--output", "json", "reader", "save", "https://example.com"], "save"), + (["--output", "json", "reader", "archive", "doc-1"], "move"), + (["--output", "json", "reader", "stats"], "statistics"), + ): + calls.clear() + result = runner.invoke(app, arguments) + assert result.exit_code == 0 + assert calls == [expected] From f750f0747f25d97c77e63931a0a4e8928aee2b15 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 00:38:01 -0500 Subject: [PATCH 16/24] feat(cli): expand operations-backed commands + reader aliases (stage 12) Additive. New commands (each one operation): document get/update/delete/move/ tag; highlight create/update/delete/tag/untag. Adds --output jsonl streaming and global --no-color/--quiet; JSON/JSONL output stays free of color codes and notices. Deprecated `reader ...` aliases forward to `documents ...` with a stderr-only deprecation notice. Existing command behavior/output/exit codes unchanged (test_cli_contracts.py + test_cli.py green). digest custom / sync status+reset deferred to stages 13-14 (their operations don't exist yet). Gate green (807 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/cli/commands/documents.py | 221 ++++++++++++- src/readwise_sdk/cli/commands/highlights.py | 182 +++++++++++ src/readwise_sdk/cli/main.py | 13 +- src/readwise_sdk/cli/output.py | 35 +++ tests/test_cli_expansion.py | 330 ++++++++++++++++++++ 5 files changed, 771 insertions(+), 10 deletions(-) create mode 100644 tests/test_cli_expansion.py diff --git a/src/readwise_sdk/cli/commands/documents.py b/src/readwise_sdk/cli/commands/documents.py index bf01b8c..d36a973 100644 --- a/src/readwise_sdk/cli/commands/documents.py +++ b/src/readwise_sdk/cli/commands/documents.py @@ -4,12 +4,19 @@ from typing import Annotated +import click import typer from rich.table import Table from readwise_sdk.cli.context import discover_api_key, run_operation -from readwise_sdk.cli.output import OutputFormat, renderer -from readwise_sdk.v3.models import DocumentCreate, DocumentLocation +from readwise_sdk.cli.output import OutputFormat, OutputRenderer, renderer +from readwise_sdk.v3.models import ( + Document, + DocumentCategory, + DocumentCreate, + DocumentLocation, + DocumentUpdate, +) reader_app = typer.Typer(help="Manage Reader documents") @@ -26,6 +33,40 @@ def _document_data(documents: list) -> list[dict]: ] +def _document_detail(document: Document) -> dict: + return { + "id": document.id, + "title": document.title, + "author": document.author, + "url": document.source_url or document.url, + "category": document.category.value if document.category else None, + "location": document.location.value if document.location else None, + "tags": document.tags, + "summary": document.summary, + "notes": document.notes, + "content": document.content, + } + + +def _result_data(result) -> dict: + return {"id": result.id, "url": result.url} + + +def _warn_reader_alias(output: OutputRenderer) -> None: + """Warn only for the human-facing deprecated group alias.""" + context = click.get_current_context(silent=True) + parent = context.parent if context is not None else None + if ( + parent is not None + and parent.info_name == "reader" + and output.output_format is OutputFormat.TABLE + ): + output.notice( + "[yellow]Warning: 'readwise reader' is deprecated; " + "use 'readwise documents' instead.[/yellow]" + ) + + @reader_app.command("inbox") def reader_inbox( limit: Annotated[int, typer.Option(help="Maximum number of items")] = 20, @@ -33,12 +74,13 @@ def reader_inbox( ) -> None: """List inbox documents.""" api_key = discover_api_key() + output = renderer(legacy_json=json_output) + _warn_reader_alias(output) documents = run_operation( lambda service: service.documents.inbox(limit=limit), api_key=api_key, ) - output = renderer(legacy_json=json_output) if output.output_format is not OutputFormat.TABLE: output.data(_document_data(documents)) return @@ -67,6 +109,7 @@ def reader_save( """Save a URL to Reader.""" api_key = discover_api_key() output = renderer() + _warn_reader_alias(output) try: result = run_operation( lambda service: service.documents.save(DocumentCreate(url=url)), @@ -76,9 +119,9 @@ def reader_save( if output.output_format is not OutputFormat.TABLE: output.data({"id": result.id, "url": result.url}) return - output.message("[green]Saved![/green]") - output.message(f"[bold]ID:[/bold] {result.id}") - output.message(f"[bold]URL:[/bold] {result.url}") + output.success("[green]Saved![/green]") + output.success(f"[bold]ID:[/bold] {result.id}") + output.success(f"[bold]URL:[/bold] {result.url}") except Exception as error: output.error(f"[red]Error: {error}[/red]") raise typer.Exit(1) from None @@ -91,6 +134,7 @@ def reader_archive( """Archive a document.""" api_key = discover_api_key() output = renderer() + _warn_reader_alias(output) try: result = run_operation( lambda service: service.documents.move(document_id, DocumentLocation.ARCHIVE), @@ -100,7 +144,7 @@ def reader_archive( if output.output_format is not OutputFormat.TABLE: output.data({"id": result.id, "url": result.url}) return - output.message(f"[green]Archived document {document_id}[/green]") + output.success(f"[green]Archived document {document_id}[/green]") except Exception as error: output.error(f"[red]Error: {error}[/red]") raise typer.Exit(1) from None @@ -110,12 +154,13 @@ def reader_archive( def reader_stats() -> None: """Show reading queue statistics.""" api_key = discover_api_key() + output = renderer() + _warn_reader_alias(output) stats = run_operation( lambda service: service.documents.statistics(), api_key=api_key, ) - output = renderer() if output.output_format is not OutputFormat.TABLE: output.data( { @@ -148,4 +193,162 @@ def reader_stats() -> None: output.message(f" {category}: {count}") -__all__ = ["reader_app"] +@reader_app.command("get") +def get_document( + document_id: Annotated[str, typer.Argument(help="Document ID")], + with_content: Annotated[ + bool, + typer.Option("--with-content", help="Include document HTML content"), + ] = False, +) -> None: + """Get one Reader document.""" + api_key = discover_api_key() + output = renderer() + _warn_reader_alias(output) + try: + document = run_operation( + lambda service: service.documents.get(document_id, with_content=with_content), + api_key=api_key, + ) + except Exception as error: + output.strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + if document is None: + output.strict_error(f"[red]Document {document_id} not found[/red]") + raise typer.Exit(3) + if output.output_format is not OutputFormat.TABLE: + output.data(_document_detail(document)) + return + + output.message(f"[bold]ID:[/bold] {document.id}") + output.message(f"[bold]Title:[/bold] {document.title or ''}") + output.message(f"[bold]URL:[/bold] {document.source_url or document.url}") + if document.author: + output.message(f"[bold]Author:[/bold] {document.author}") + if document.category: + output.message(f"[bold]Category:[/bold] {document.category.value}") + if document.location: + output.message(f"[bold]Location:[/bold] {document.location.value}") + if document.tags: + output.message(f"[bold]Tags:[/bold] {', '.join(document.tags)}") + if with_content and document.content: + output.message(f"[bold]Content:[/bold] {document.content}") + + +@reader_app.command("update") +def update_document( + document_id: Annotated[str, typer.Argument(help="Document ID")], + title: Annotated[str | None, typer.Option(help="New title")] = None, + author: Annotated[str | None, typer.Option(help="New author")] = None, + summary: Annotated[str | None, typer.Option(help="New summary")] = None, + category: Annotated[DocumentCategory | None, typer.Option(help="New category")] = None, + tags: Annotated[ + str | None, + typer.Option(help="Comma-separated replacement tags"), + ] = None, + notes: Annotated[str | None, typer.Option(help="New document notes")] = None, +) -> None: + """Update document metadata.""" + api_key = discover_api_key() + output = renderer() + _warn_reader_alias(output) + replacement_tags = [tag.strip() for tag in tags.split(",")] if tags is not None else None + update = DocumentUpdate( + title=title, + author=author, + summary=summary, + category=category, + tags=replacement_tags, + notes=notes, + ) + try: + result = run_operation( + lambda service: service.documents.update(document_id, update), + api_key=api_key, + ) + except Exception as error: + output.strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + if output.output_format is not OutputFormat.TABLE: + output.data(_result_data(result)) + return + output.success(f"[green]Updated document {document_id}[/green]") + + +@reader_app.command("delete") +def delete_document( + document_id: Annotated[str, typer.Argument(help="Document ID")], +) -> None: + """Permanently delete a Reader document.""" + api_key = discover_api_key() + output = renderer() + _warn_reader_alias(output) + try: + run_operation( + lambda service: service.documents.delete(document_id), + api_key=api_key, + ) + except Exception as error: + output.strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + if output.output_format is not OutputFormat.TABLE: + output.data({"id": document_id, "deleted": True}) + return + output.success(f"[green]Deleted document {document_id}[/green]") + + +@reader_app.command("move") +def move_document( + document_id: Annotated[str, typer.Argument(help="Document ID")], + location: Annotated[DocumentLocation, typer.Argument(help="New location")], +) -> None: + """Move a document to another Reader location.""" + api_key = discover_api_key() + output = renderer() + _warn_reader_alias(output) + try: + result = run_operation( + lambda service: service.documents.move(document_id, location), + api_key=api_key, + ) + except Exception as error: + output.strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + if output.output_format is not OutputFormat.TABLE: + output.data(_result_data(result)) + return + output.success(f"[green]Moved document {document_id} to {location.value}[/green]") + + +@reader_app.command("tag") +def tag_document( + document_id: Annotated[str, typer.Argument(help="Document ID")], + tag: Annotated[str, typer.Argument(help="Tag to add")], +) -> None: + """Add one tag to a Reader document.""" + api_key = discover_api_key() + output = renderer() + _warn_reader_alias(output) + try: + result = run_operation( + lambda service: service.documents.add_tag(document_id, tag), + api_key=api_key, + ) + except Exception as error: + output.strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + if output.output_format is not OutputFormat.TABLE: + output.data(_result_data(result)) + return + output.success(f"[green]Tagged document {document_id} with {tag}[/green]") + + +documents_app = reader_app + + +__all__ = ["documents_app", "reader_app"] diff --git a/src/readwise_sdk/cli/commands/highlights.py b/src/readwise_sdk/cli/commands/highlights.py index 99fcbcc..6e1e4c9 100644 --- a/src/readwise_sdk/cli/commands/highlights.py +++ b/src/readwise_sdk/cli/commands/highlights.py @@ -10,6 +10,8 @@ from readwise_sdk.cli.context import discover_api_key, run_operation from readwise_sdk.cli.output import OutputFormat, renderer +from readwise_sdk.models import BulkResult +from readwise_sdk.v2.models import Highlight, HighlightColor, HighlightUpdate from readwise_sdk.workflows.digest import DigestBuilder, DigestFormat highlights_app = typer.Typer(help="Manage highlights") @@ -28,6 +30,29 @@ def _highlight_data(highlights: list, *, truncate: bool) -> list[dict]: ] +def _highlight_detail(highlight: Highlight) -> dict: + return { + "id": highlight.id, + "text": highlight.text, + "note": highlight.note, + "location": highlight.location, + "location_type": highlight.location_type, + "url": highlight.url, + "color": highlight.color.value if highlight.color else None, + "tags": [tag.name for tag in highlight.tags], + "highlighted_at": highlight.highlighted_at.isoformat() + if highlight.highlighted_at + else None, + } + + +def _bulk_data(result: BulkResult[int]) -> dict: + return { + "succeeded": result.succeeded, + "failures": [{"id": failure.item, "error": failure.message} for failure in result.failures], + } + + @highlights_app.command("list") def list_highlights( limit: Annotated[int, typer.Option(help="Maximum number of highlights")] = 20, @@ -155,4 +180,161 @@ def export_highlights( command_output.message(content) +@highlights_app.command("create") +def create_highlight( + text: Annotated[str, typer.Argument(help="Highlight text")], + title: Annotated[str | None, typer.Option(help="Source title")] = None, + author: Annotated[str | None, typer.Option(help="Source author")] = None, + source_url: Annotated[ + str | None, + typer.Option("--source-url", help="Source URL"), + ] = None, + note: Annotated[str | None, typer.Option(help="Highlight note")] = None, + category: Annotated[str | None, typer.Option(help="Source category")] = None, +) -> None: + """Create one highlight.""" + api_key = discover_api_key() + output = renderer() + try: + result = run_operation( + lambda service: service.highlights.create_from_fields( + text=text, + title=title, + author=author, + source_url=source_url, + note=note, + category=category, + ), + api_key=api_key, + ) + except Exception as error: + output.strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + data = { + "ids": result.ids, + "was_truncated": result.was_truncated, + } + if output.output_format is not OutputFormat.TABLE: + output.data(data) + return + ids = ", ".join(str(highlight_id) for highlight_id in result.ids) + output.success(f"[green]Created highlight {ids}[/green]") + + +@highlights_app.command("update") +def update_highlight( + highlight_id: Annotated[int, typer.Argument(help="Highlight ID")], + text: Annotated[str | None, typer.Option(help="Replacement text")] = None, + note: Annotated[str | None, typer.Option(help="Replacement note")] = None, + location: Annotated[int | None, typer.Option(help="Replacement location")] = None, + location_type: Annotated[ + str | None, + typer.Option("--location-type", help="Replacement location type"), + ] = None, + url: Annotated[str | None, typer.Option(help="Replacement URL")] = None, + color: Annotated[HighlightColor | None, typer.Option(help="Highlight color")] = None, +) -> None: + """Update one highlight.""" + api_key = discover_api_key() + output = renderer() + update = HighlightUpdate( + text=text, + note=note, + location=location, + location_type=location_type, + url=url, + color=color, + ) + try: + highlight = run_operation( + lambda service: service.highlights.update(highlight_id, update), + api_key=api_key, + ) + except Exception as error: + output.strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + if output.output_format is not OutputFormat.TABLE: + output.data(_highlight_detail(highlight)) + return + output.success(f"[green]Updated highlight {highlight_id}[/green]") + + +@highlights_app.command("delete") +def delete_highlight( + highlight_id: Annotated[int, typer.Argument(help="Highlight ID")], +) -> None: + """Permanently delete one highlight.""" + api_key = discover_api_key() + output = renderer() + try: + run_operation( + lambda service: service.highlights.delete(highlight_id), + api_key=api_key, + ) + except Exception as error: + output.strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + + if output.output_format is not OutputFormat.TABLE: + output.data({"id": highlight_id, "deleted": True}) + return + output.success(f"[green]Deleted highlight {highlight_id}[/green]") + + +def _render_bulk_tag_result( + result: BulkResult[int], + *, + tag: str, + action: str, +) -> None: + output = renderer() + if output.output_format is not OutputFormat.TABLE: + output.data(_bulk_data(result)) + else: + for highlight_id in result.succeeded: + output.success(f"[green]{action} highlight {highlight_id} with {tag}[/green]") + for failure in result.failures: + output.strict_error(f"[red]Error for highlight {failure.item}: {failure.message}[/red]") + if result.failures: + raise typer.Exit(4) + + +@highlights_app.command("tag") +def tag_highlight( + highlight_id: Annotated[int, typer.Argument(help="Highlight ID")], + tag: Annotated[str, typer.Argument(help="Tag to add")], +) -> None: + """Add one tag to a highlight.""" + api_key = discover_api_key() + try: + result = run_operation( + lambda service: service.highlights.bulk_tag([highlight_id], tag), + api_key=api_key, + ) + except Exception as error: + renderer().strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + _render_bulk_tag_result(result, tag=tag, action="Tagged") + + +@highlights_app.command("untag") +def untag_highlight( + highlight_id: Annotated[int, typer.Argument(help="Highlight ID")], + tag: Annotated[str, typer.Argument(help="Tag to remove")], +) -> None: + """Remove one tag from a highlight.""" + api_key = discover_api_key() + try: + result = run_operation( + lambda service: service.highlights.bulk_untag([highlight_id], tag), + api_key=api_key, + ) + except Exception as error: + renderer().strict_error(f"[red]Error: {error}[/red]") + raise typer.Exit(1) from None + _render_bulk_tag_result(result, tag=tag, action="Untagged") + + __all__ = ["highlights_app"] diff --git a/src/readwise_sdk/cli/main.py b/src/readwise_sdk/cli/main.py index a0324d6..a276968 100644 --- a/src/readwise_sdk/cli/main.py +++ b/src/readwise_sdk/cli/main.py @@ -21,6 +21,7 @@ from readwise_sdk.cli.output import ( CliOutputContext, OutputFormat, + configure_color, console, current_output_format, renderer, @@ -42,9 +43,18 @@ def cli_context( OutputFormat, typer.Option("--output", help="Output format: table, json, or jsonl"), ] = OutputFormat.TABLE, + no_color: Annotated[ + bool, + typer.Option("--no-color", help="Disable colored output"), + ] = False, + quiet: Annotated[ + bool, + typer.Option("--quiet", help="Suppress non-data notices"), + ] = False, ) -> None: """Configure shared CLI invocation state.""" - ctx.obj = CliOutputContext(output_format=output) + ctx.obj = CliOutputContext(output_format=output, no_color=no_color, quiet=quiet) + configure_color(no_color=no_color) # Sub-apps @@ -54,6 +64,7 @@ def cli_context( app.add_typer(highlights_app, name="highlights") app.add_typer(books_app, name="books") +app.add_typer(reader_app, name="documents") app.add_typer(reader_app, name="reader") app.add_typer(sync_app, name="sync") app.add_typer(digest_app, name="digest") diff --git a/src/readwise_sdk/cli/output.py b/src/readwise_sdk/cli/output.py index 6a66996..c1060f9 100644 --- a/src/readwise_sdk/cli/output.py +++ b/src/readwise_sdk/cli/output.py @@ -25,6 +25,8 @@ class CliOutputContext: """Output selection stored on the root Click context.""" output_format: OutputFormat = OutputFormat.TABLE + no_color: bool = False + quiet: bool = False console = Console() @@ -42,6 +44,23 @@ def current_output_format() -> OutputFormat: return OutputFormat.TABLE +def current_output_context() -> CliOutputContext: + """Return the complete root output context or its default value.""" + context = click.get_current_context(silent=True) + if context is None: + return CliOutputContext() + root = context.find_root() + if isinstance(root.obj, CliOutputContext): + return root.obj + return CliOutputContext() + + +def configure_color(*, no_color: bool) -> None: + """Apply one invocation's color preference to both CLI streams.""" + console.no_color = no_color + error_console.no_color = no_color + + class OutputRenderer: """Render adapter-owned values without owning operation semantics.""" @@ -75,11 +94,25 @@ def message(self, message: str) -> None: """Write human-facing command output with legacy Rich behavior.""" console.print(message) + def success(self, message: str) -> None: + """Write a suppressible success notice for mutation commands.""" + if not current_output_context().quiet: + console.print(message) + + def notice(self, message: str) -> None: + """Write a suppressible human notice to stderr.""" + if not current_output_context().quiet: + error_console.print(message) + def error(self, message: str) -> None: """Keep legacy errors on stdout, but isolate machine-mode errors.""" target = console if self.output_format is OutputFormat.TABLE else error_console target.print(message) + def strict_error(self, message: str) -> None: + """Write errors for additive commands to stderr in every output mode.""" + error_console.print(message) + def renderer(*, legacy_json: bool = False) -> OutputRenderer: """Return a renderer, preserving a command-local legacy ``--json`` flag.""" @@ -92,6 +125,8 @@ def renderer(*, legacy_json: bool = False) -> OutputRenderer: "OutputFormat", "OutputRenderer", "console", + "configure_color", + "current_output_context", "current_output_format", "error_console", "renderer", diff --git a/tests/test_cli_expansion.py b/tests/test_cli_expansion.py new file mode 100644 index 0000000..00b85ea --- /dev/null +++ b/tests/test_cli_expansion.py @@ -0,0 +1,330 @@ +"""Contracts for the additive PR 12 CLI commands and global options.""" + +from __future__ import annotations + +import json +from types import SimpleNamespace +from typing import Any + +import anyio +import pytest +from typer.testing import CliRunner + +from readwise_sdk.cli.main import app +from readwise_sdk.models import BulkResult +from readwise_sdk.operations.highlights import HighlightCreateResult +from readwise_sdk.v2.models import Highlight, HighlightColor +from readwise_sdk.v3.models import ( + CreateDocumentResult, + Document, + DocumentCategory, + DocumentLocation, +) + +runner = CliRunner() + + +@pytest.fixture(autouse=True) +def _set_api_key(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("READWISE_API_KEY", "token") + + +def _operation_runner(service: Any): + def run(operation, *, api_key: str | None = None): + assert api_key == "token" + + async def invoke(): + return await operation(service) + + return anyio.run(invoke) + + return run + + +class DocumentOperations: + def __init__(self) -> None: + self.calls: list[tuple[str, tuple, dict]] = [] + self.document = Document( + id="doc-1", + url="https://example.com/article", + title="An article", + author="Ada", + category=DocumentCategory.ARTICLE, + location=DocumentLocation.NEW, + tags=["python"], + content="

Full text

", + ) + self.result = CreateDocumentResult(id="doc-1", url=self.document.url) + + async def get(self, *args, **kwargs): + self.calls.append(("get", args, kwargs)) + return self.document + + async def update(self, *args, **kwargs): + self.calls.append(("update", args, kwargs)) + return self.result + + async def delete(self, *args, **kwargs): + self.calls.append(("delete", args, kwargs)) + + async def move(self, *args, **kwargs): + self.calls.append(("move", args, kwargs)) + return self.result + + async def add_tag(self, *args, **kwargs): + self.calls.append(("add_tag", args, kwargs)) + return self.result + + async def save(self, *args, **kwargs): + self.calls.append(("save", args, kwargs)) + return self.result + + async def inbox(self, *args, **kwargs): + self.calls.append(("inbox", args, kwargs)) + return [self.document] + + +class HighlightOperations: + def __init__(self) -> None: + self.calls: list[tuple[str, tuple, dict]] = [] + self.highlight = Highlight( + id=7, + text="A useful highlight", + note="Remember this", + location=4, + color=HighlightColor.YELLOW, + ) + + async def create_from_fields(self, *args, **kwargs): + self.calls.append(("create_from_fields", args, kwargs)) + return HighlightCreateResult(ids=[7]) + + async def update(self, *args, **kwargs): + self.calls.append(("update", args, kwargs)) + return self.highlight + + async def delete(self, *args, **kwargs): + self.calls.append(("delete", args, kwargs)) + + async def bulk_tag(self, *args, **kwargs): + self.calls.append(("bulk_tag", args, kwargs)) + return BulkResult[int](succeeded=[7]) + + async def bulk_untag(self, *args, **kwargs): + self.calls.append(("bulk_untag", args, kwargs)) + return BulkResult[int](succeeded=[7]) + + +DOCUMENT_CASES = [ + (["documents", "get", "doc-1", "--with-content"], "get"), + (["documents", "update", "doc-1", "--title", "Revised"], "update"), + (["documents", "delete", "doc-1"], "delete"), + (["documents", "move", "doc-1", "archive"], "move"), + (["documents", "tag", "doc-1", "research"], "add_tag"), +] + + +HIGHLIGHT_CASES = [ + (["highlights", "create", "New insight", "--title", "Source"], "create_from_fields"), + (["highlights", "update", "7", "--note", "Revised note"], "update"), + (["highlights", "delete", "7"], "delete"), + (["highlights", "tag", "7", "favorite"], "bulk_tag"), + (["highlights", "untag", "7", "favorite"], "bulk_untag"), +] + + +@pytest.mark.parametrize(("arguments", "expected_operation"), DOCUMENT_CASES) +@pytest.mark.parametrize("output_format", ["table", "json", "jsonl"]) +def test_each_new_document_command_calls_one_operation_and_renders_requested_output( + monkeypatch: pytest.MonkeyPatch, + arguments: list[str], + expected_operation: str, + output_format: str, +) -> None: + from readwise_sdk.cli.commands import documents as commands + + operations = DocumentOperations() + service = SimpleNamespace(documents=operations) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + cli_arguments = arguments + if output_format != "table": + cli_arguments = ["--output", output_format, *arguments] + + result = runner.invoke(app, cli_arguments) + + assert result.exit_code == 0, result.output + assert [call[0] for call in operations.calls] == [expected_operation] + assert result.stdout + assert result.stderr == "" + if output_format == "json": + assert isinstance(json.loads(result.stdout), dict) + elif output_format == "jsonl": + lines = result.stdout.splitlines() + assert len(lines) == 1 + assert isinstance(json.loads(lines[0]), dict) + + +@pytest.mark.parametrize(("arguments", "expected_operation"), HIGHLIGHT_CASES) +@pytest.mark.parametrize("output_format", ["table", "json", "jsonl"]) +def test_each_new_highlight_command_calls_one_operation_and_renders_requested_output( + monkeypatch: pytest.MonkeyPatch, + arguments: list[str], + expected_operation: str, + output_format: str, +) -> None: + from readwise_sdk.cli.commands import highlights as commands + + operations = HighlightOperations() + service = SimpleNamespace(highlights=operations) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + cli_arguments = arguments + if output_format != "table": + cli_arguments = ["--output", output_format, *arguments] + + result = runner.invoke(app, cli_arguments) + + assert result.exit_code == 0, result.output + assert [call[0] for call in operations.calls] == [expected_operation] + assert result.stdout + assert result.stderr == "" + if output_format == "json": + assert isinstance(json.loads(result.stdout), dict) + elif output_format == "jsonl": + lines = result.stdout.splitlines() + assert len(lines) == 1 + assert isinstance(json.loads(lines[0]), dict) + + +def test_documents_inbox_jsonl_streams_one_document_per_line( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from readwise_sdk.cli.commands import documents as commands + + operations = DocumentOperations() + operations.document = operations.document.model_copy(update={"id": "doc-1"}) + second = operations.document.model_copy(update={"id": "doc-2"}) + + async def inbox(*args, **kwargs): + operations.calls.append(("inbox", args, kwargs)) + return [operations.document, second] + + operations.inbox = inbox # type: ignore[method-assign] + service = SimpleNamespace(documents=operations) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + + result = runner.invoke(app, ["--output", "jsonl", "documents", "inbox"]) + + assert result.exit_code == 0 + assert [json.loads(line)["id"] for line in result.stdout.splitlines()] == ["doc-1", "doc-2"] + assert result.stderr == "" + + +@pytest.mark.parametrize( + ("arguments", "expected_operation"), + [ + (["reader", "inbox"], "inbox"), + (["reader", "save", "https://example.com/article"], "save"), + (["reader", "archive", "doc-1"], "move"), + ], +) +def test_reader_aliases_warn_on_stderr_only_in_human_mode( + monkeypatch: pytest.MonkeyPatch, + arguments: list[str], + expected_operation: str, +) -> None: + from readwise_sdk.cli.commands import documents as commands + + operations = DocumentOperations() + service = SimpleNamespace(documents=operations) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + + result = runner.invoke(app, arguments) + + assert result.exit_code == 0 + assert [call[0] for call in operations.calls] == [expected_operation] + assert "deprecated" not in result.stdout.lower() + assert "reader" in result.stderr.lower() + assert "deprecated" in result.stderr.lower() + + +@pytest.mark.parametrize( + "arguments", + [ + ["--output", "json", "reader", "inbox"], + ["--output", "jsonl", "reader", "inbox"], + ["reader", "inbox", "--json"], + ], +) +def test_reader_alias_machine_output_has_no_deprecation_notice( + monkeypatch: pytest.MonkeyPatch, + arguments: list[str], +) -> None: + from readwise_sdk.cli.commands import documents as commands + + operations = DocumentOperations() + service = SimpleNamespace(documents=operations) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + + result = runner.invoke(app, arguments) + + assert result.exit_code == 0 + assert "deprecated" not in result.stdout.lower() + assert result.stderr == "" + + +def test_books_list_jsonl_streams_one_book_per_line( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from readwise_sdk.cli.commands import books as commands + from readwise_sdk.v2.models import Book + + class Operations: + async def list(self, **kwargs): + return [Book(id=1, title="One"), Book(id=2, title="Two")] + + service = SimpleNamespace(books=Operations()) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + + result = runner.invoke(app, ["--output", "jsonl", "books", "list"]) + + assert result.exit_code == 0 + assert [json.loads(line)["id"] for line in result.stdout.splitlines()] == [1, 2] + assert result.stderr == "" + + +def test_quiet_suppresses_success_messages_but_still_runs_operation( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from readwise_sdk.cli.commands import documents as commands + + operations = DocumentOperations() + service = SimpleNamespace(documents=operations) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + + result = runner.invoke(app, ["--quiet", "documents", "delete", "doc-1"]) + + assert result.exit_code == 0 + assert [call[0] for call in operations.calls] == ["delete"] + assert result.stdout == "" + assert result.stderr == "" + + +def test_no_color_removes_ansi_codes_from_human_output( + monkeypatch: pytest.MonkeyPatch, +) -> None: + from readwise_sdk.cli.commands import documents as commands + + operations = DocumentOperations() + service = SimpleNamespace(documents=operations) + monkeypatch.setattr(commands, "run_operation", _operation_runner(service)) + + result = runner.invoke( + app, + ["--no-color", "documents", "delete", "doc-1"], + color=True, + ) + + assert result.exit_code == 0 + assert "Deleted document doc-1" in result.stdout + assert "\x1b[" not in result.stdout + assert "\x1b[" not in result.stderr From 752ea1f61b30b35419eaed29a5c707c6b082552e Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 00:51:06 -0500 Subject: [PATCH 17/24] refactor: consolidate tags + digests into operations/presenters (stage 13) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Behavior-preserving. New operations/tags.py + operations/digests.py own tag and digest data/selection/grouping; new presenters/ (json/text/markdown/csv) own digest rendering. TagWorkflow and DigestBuilder become thin shims delegating to them with unchanged public methods, return types, and output — their existing workflow tests pass unchanged. AsyncReadwise/Readwise now expose .tags and .digests; new CLI `digest custom` command added. Characterization + workflow tests unchanged; gate green (821 passed); uv.lock unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/cli/main.py | 50 ++- src/readwise_sdk/operations/__init__.py | 14 + src/readwise_sdk/operations/digests.py | 223 +++++++++++++ src/readwise_sdk/operations/service.py | 37 +++ src/readwise_sdk/operations/tags.py | 398 ++++++++++++++++++++++++ src/readwise_sdk/presenters/__init__.py | 34 ++ src/readwise_sdk/presenters/csv.py | 31 ++ src/readwise_sdk/presenters/json.py | 35 +++ src/readwise_sdk/presenters/markdown.py | 44 +++ src/readwise_sdk/presenters/text.py | 34 ++ src/readwise_sdk/sdk/async_.py | 24 +- src/readwise_sdk/sdk/sync.py | 114 ++++++- src/readwise_sdk/workflows/digest.py | 304 ++---------------- src/readwise_sdk/workflows/tags.py | 302 ++---------------- tests/operations/test_digests.py | 82 +++++ tests/operations/test_tags.py | 112 +++++++ tests/presenters/test_digests.py | 71 +++++ tests/sdk/test_async.py | 18 +- tests/sdk/test_sync.py | 16 +- tests/test_cli_expansion.py | 51 +++ 20 files changed, 1430 insertions(+), 564 deletions(-) create mode 100644 src/readwise_sdk/operations/digests.py create mode 100644 src/readwise_sdk/operations/tags.py create mode 100644 src/readwise_sdk/presenters/__init__.py create mode 100644 src/readwise_sdk/presenters/csv.py create mode 100644 src/readwise_sdk/presenters/json.py create mode 100644 src/readwise_sdk/presenters/markdown.py create mode 100644 src/readwise_sdk/presenters/text.py create mode 100644 tests/operations/test_digests.py create mode 100644 tests/operations/test_tags.py create mode 100644 tests/presenters/test_digests.py diff --git a/src/readwise_sdk/cli/main.py b/src/readwise_sdk/cli/main.py index a276968..1384dd4 100644 --- a/src/readwise_sdk/cli/main.py +++ b/src/readwise_sdk/cli/main.py @@ -4,6 +4,7 @@ import json import sys +from datetime import datetime from importlib.metadata import version as pkg_version from typing import Annotated @@ -17,7 +18,7 @@ from readwise_sdk.cli.commands.books import books_app from readwise_sdk.cli.commands.documents import reader_app from readwise_sdk.cli.commands.highlights import highlights_app -from readwise_sdk.cli.context import get_client +from readwise_sdk.cli.context import discover_api_key, get_client, run_operation from readwise_sdk.cli.output import ( CliOutputContext, OutputFormat, @@ -26,7 +27,8 @@ current_output_format, renderer, ) -from readwise_sdk.workflows.digest import DigestBuilder, DigestFormat +from readwise_sdk.presenters import DigestFormat, render_digest +from readwise_sdk.workflows.digest import DigestBuilder from readwise_sdk.workflows.tags import TagPattern, TagWorkflow app = typer.Typer( @@ -188,6 +190,50 @@ def digest_book( console.print(content) +@digest_app.command("custom") +def digest_custom( + since: Annotated[ + datetime | None, + typer.Option(help="Only include highlights updated after this time"), + ] = None, + book_id: Annotated[int | None, typer.Option(help="Only include one book ID")] = None, + format_type: Annotated[str, typer.Option("--format", "-f", help="Output format")] = "markdown", + output: Annotated[str | None, typer.Option("-o", help="Output file")] = None, + group_by_book: Annotated[ + bool, + typer.Option("--group-by-book/--no-group-by-book", help="Group highlights by book"), + ] = True, + group_by_date: Annotated[ + bool, + typer.Option("--group-by-date", help="Group highlights by highlighted date"), + ] = False, +) -> None: + """Generate a custom digest with optional selection and grouping.""" + try: + fmt = DigestFormat(format_type) + except ValueError: + console.print("[red]Invalid format. Use: markdown, json, csv, text[/red]") + raise typer.Exit(1) from None + + data = run_operation( + lambda service: service.digests.custom( + since=since, + book_id=book_id, + group_by_book=group_by_book, + group_by_date=group_by_date, + ), + api_key=discover_api_key(), + ) + content = render_digest(data, fmt) + + if output: + with open(output, "w") as file: + file.write(content) + console.print(f"[green]Saved custom digest to {output}[/green]") + else: + console.print(content) + + # Tags commands @tags_app.command("list") def list_tags( diff --git a/src/readwise_sdk/operations/__init__.py b/src/readwise_sdk/operations/__init__.py index fa255ae..13d01b4 100644 --- a/src/readwise_sdk/operations/__init__.py +++ b/src/readwise_sdk/operations/__init__.py @@ -6,6 +6,7 @@ BookWithHighlights, ReadingStatistics, ) +from readwise_sdk.operations.digests import DigestData, DigestGrouping, DigestOperations from readwise_sdk.operations.documents import DocumentOperations, DocumentStatistics from readwise_sdk.operations.highlights import ( FieldTruncation, @@ -22,6 +23,12 @@ TruncationInfo, ) from readwise_sdk.operations.service import ReadwiseService +from readwise_sdk.operations.tags import ( + TagCleanupResult, + TagOperations, + TagPattern, + TagReport, +) __all__ = [ "BookOperations", @@ -29,6 +36,9 @@ "BookWithHighlights", "DocumentOperations", "DocumentStatistics", + "DigestData", + "DigestGrouping", + "DigestOperations", "FieldTruncation", "HighlightCreateResult", "HighlightDeleteResult", @@ -42,5 +52,9 @@ "HighlightUpdateResult", "ReadingStatistics", "ReadwiseService", + "TagCleanupResult", + "TagOperations", + "TagPattern", + "TagReport", "TruncationInfo", ] diff --git a/src/readwise_sdk/operations/digests.py b/src/readwise_sdk/operations/digests.py new file mode 100644 index 0000000..b9a2833 --- /dev/null +++ b/src/readwise_sdk/operations/digests.py @@ -0,0 +1,223 @@ +"""Canonical digest data selection and grouping operations.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator, Iterator +from dataclasses import dataclass, field +from datetime import UTC, datetime, timedelta +from enum import Enum +from typing import Protocol + +from readwise_sdk.v2.models import Book, Highlight + + +class DigestHighlightsResource(Protocol): + """Highlight iteration required by canonical digest operations.""" + + def iter( + self, + *, + book_id: int | None = None, + updated_after: datetime | None = None, + ) -> AsyncIterator[Highlight]: ... + + +class DigestBooksResource(Protocol): + """Book lookup required by book-specific digests.""" + + async def get(self, book_id: int) -> Book: ... + + +class SyncDigestClient(Protocol): + """Legacy synchronous capabilities used by the workflow compatibility shim.""" + + def list_highlights( + self, + *, + updated_after: datetime | None = None, + book_id: int | None = None, + ) -> Iterator[Highlight]: ... + + def get_book(self, book_id: int) -> Book: ... + + +class DigestGrouping(str, Enum): + """Grouping already selected by digest operations for presenters.""" + + NONE = "none" + BOOK = "book" + DATE = "date" + + +@dataclass(frozen=True, slots=True) +class DigestData: + """Protocol-neutral digest data ready for a presenter.""" + + title: str + highlights: list[Highlight] = field(default_factory=list) + grouping: DigestGrouping = DigestGrouping.NONE + groups: list[tuple[str, list[Highlight]]] = field(default_factory=list) + + +def group_by_book(highlights: list[Highlight]) -> list[tuple[str, list[Highlight]]]: + """Group highlights by the legacy synthetic book label.""" + groups: dict[str, list[Highlight]] = {} + for highlight in highlights: + key = f"Book {highlight.book_id}" if highlight.book_id else "Unknown" + groups.setdefault(key, []).append(highlight) + return list(groups.items()) + + +def group_by_date(highlights: list[Highlight]) -> list[tuple[str, list[Highlight]]]: + """Group highlights by date, newest date label first.""" + groups: dict[str, list[Highlight]] = {} + for highlight in highlights: + key = ( + highlight.highlighted_at.strftime("%Y-%m-%d") + if highlight.highlighted_at + else "Unknown Date" + ) + groups.setdefault(key, []).append(highlight) + return sorted(groups.items(), reverse=True) + + +def build_digest( + highlights: list[Highlight], + *, + title: str, + group_by_book_enabled: bool = True, + group_by_date_enabled: bool = False, +) -> DigestData: + """Apply the legacy grouping precedence and return digest data.""" + if group_by_date_enabled: + grouping = DigestGrouping.DATE + groups = group_by_date(highlights) + elif group_by_book_enabled: + grouping = DigestGrouping.BOOK + groups = group_by_book(highlights) + else: + grouping = DigestGrouping.NONE + groups = [] + return DigestData(title=title, highlights=highlights, grouping=grouping, groups=groups) + + +class DigestOperations: + """Own async digest selection windows, filters, titles, and grouping.""" + + def __init__( + self, + highlights: DigestHighlightsResource, + books: DigestBooksResource, + ) -> None: + self._highlights = highlights + self._books = books + + async def daily(self, *, group_by_book: bool = True) -> DigestData: + """Select highlights updated in the last 24 hours.""" + since = datetime.now(UTC) - timedelta(days=1) + highlights = [highlight async for highlight in self._highlights.iter(updated_after=since)] + return build_digest( + highlights, + title="Daily Digest", + group_by_book_enabled=group_by_book, + ) + + async def weekly(self, *, group_by_book: bool = True) -> DigestData: + """Select highlights updated in the last seven days.""" + since = datetime.now(UTC) - timedelta(days=7) + highlights = [highlight async for highlight in self._highlights.iter(updated_after=since)] + return build_digest( + highlights, + title="Weekly Digest", + group_by_book_enabled=group_by_book, + ) + + async def book(self, book_id: int) -> DigestData: + """Select all highlights for one book and use its title.""" + book = await self._books.get(book_id) + highlights = [highlight async for highlight in self._highlights.iter(book_id=book_id)] + return build_digest( + highlights, + title=f"Highlights from: {book.title}", + group_by_book_enabled=False, + ) + + async def custom( + self, + *, + since: datetime | None = None, + book_id: int | None = None, + group_by_book: bool = True, + group_by_date: bool = False, + ) -> DigestData: + """Select and group highlights using caller-supplied filters.""" + highlights = [ + highlight + async for highlight in self._highlights.iter( + updated_after=since, + book_id=book_id, + ) + ] + return build_digest( + highlights, + title="Custom Digest", + group_by_book_enabled=group_by_book, + group_by_date_enabled=group_by_date, + ) + + +class SyncDigestOperations: + """Synchronous operation adapter used solely by the legacy workflow shim.""" + + def __init__(self, client: SyncDigestClient) -> None: + self._client = client + + def daily(self, *, group_by_book: bool = True) -> DigestData: + since = datetime.now(UTC) - timedelta(days=1) + return build_digest( + list(self._client.list_highlights(updated_after=since)), + title="Daily Digest", + group_by_book_enabled=group_by_book, + ) + + def weekly(self, *, group_by_book: bool = True) -> DigestData: + since = datetime.now(UTC) - timedelta(days=7) + return build_digest( + list(self._client.list_highlights(updated_after=since)), + title="Weekly Digest", + group_by_book_enabled=group_by_book, + ) + + def book(self, book_id: int) -> DigestData: + book = self._client.get_book(book_id) + return build_digest( + list(self._client.list_highlights(book_id=book_id)), + title=f"Highlights from: {book.title}", + group_by_book_enabled=False, + ) + + def custom( + self, + *, + since: datetime | None = None, + book_id: int | None = None, + group_by_book: bool = True, + group_by_date: bool = False, + ) -> DigestData: + return build_digest( + list(self._client.list_highlights(updated_after=since, book_id=book_id)), + title="Custom Digest", + group_by_book_enabled=group_by_book, + group_by_date_enabled=group_by_date, + ) + + +__all__ = [ + "DigestData", + "DigestGrouping", + "DigestOperations", + "SyncDigestOperations", + "build_digest", + "group_by_book", + "group_by_date", +] diff --git a/src/readwise_sdk/operations/service.py b/src/readwise_sdk/operations/service.py index 54b5cd6..1d61693 100644 --- a/src/readwise_sdk/operations/service.py +++ b/src/readwise_sdk/operations/service.py @@ -3,6 +3,11 @@ from __future__ import annotations from readwise_sdk.operations.books import BookHighlightsResource, BookOperations, BooksResource +from readwise_sdk.operations.digests import ( + DigestBooksResource, + DigestHighlightsResource, + DigestOperations, +) from readwise_sdk.operations.documents import DocumentOperations, DocumentsResource from readwise_sdk.operations.highlights import ( ExportResource, @@ -10,6 +15,10 @@ HighlightsResource, HighlightTagsResource, ) +from readwise_sdk.operations.tags import ( + HighlightTagsResource as TagMutationsResource, +) +from readwise_sdk.operations.tags import TagHighlightsResource, TagOperations class ReadwiseService: @@ -24,6 +33,10 @@ def __init__( export: ExportResource | None = None, books: BooksResource | None = None, book_highlights: BookHighlightsResource | None = None, + tag_highlights: TagHighlightsResource | None = None, + tag_mutations: TagMutationsResource | None = None, + digest_highlights: DigestHighlightsResource | None = None, + digest_books: DigestBooksResource | None = None, ) -> None: self._documents = DocumentOperations(documents) if documents is not None else None self._highlights = ( @@ -37,6 +50,16 @@ def __init__( if books is not None and highlights_for_books is not None else None ) + self._tags = ( + TagOperations(tag_highlights, tag_mutations) + if tag_highlights is not None and tag_mutations is not None + else None + ) + self._digests = ( + DigestOperations(digest_highlights, digest_books) + if digest_highlights is not None and digest_books is not None + else None + ) @property def documents(self) -> DocumentOperations: @@ -59,5 +82,19 @@ def books(self) -> BookOperations: raise RuntimeError("Book operations were not configured") return self._books + @property + def tags(self) -> TagOperations: + """Return configured tag operations.""" + if self._tags is None: + raise RuntimeError("Tag operations were not configured") + return self._tags + + @property + def digests(self) -> DigestOperations: + """Return configured digest operations.""" + if self._digests is None: + raise RuntimeError("Digest operations were not configured") + return self._digests + __all__ = ["ReadwiseService"] diff --git a/src/readwise_sdk/operations/tags.py b/src/readwise_sdk/operations/tags.py new file mode 100644 index 0000000..039aa3c --- /dev/null +++ b/src/readwise_sdk/operations/tags.py @@ -0,0 +1,398 @@ +"""Canonical tag selection, reporting, and mutation operations.""" + +from __future__ import annotations + +import re +from collections import Counter +from collections.abc import AsyncIterator, Iterator +from dataclasses import dataclass +from datetime import datetime +from typing import Protocol + +from readwise_sdk.v2.models import Highlight, Tag + + +class TagHighlightsResource(Protocol): + """Highlight iteration required by canonical tag operations.""" + + def iter( + self, + *, + page_size: int = 100, + book_id: int | None = None, + updated_after: datetime | None = None, + updated_before: datetime | None = None, + highlighted_after: datetime | None = None, + highlighted_before: datetime | None = None, + ) -> AsyncIterator[Highlight]: ... + + +class HighlightTagsResource(Protocol): + """Highlight-tag mutations required by canonical tag operations.""" + + async def create_highlight(self, highlight_id: int, name: str) -> Tag: ... + + async def update_highlight(self, highlight_id: int, tag_id: int, name: str) -> Tag: ... + + async def delete_highlight(self, highlight_id: int, tag_id: int) -> None: ... + + +class SyncTagClient(Protocol): + """Legacy synchronous capabilities used by the workflow compatibility shim.""" + + def list_highlights(self) -> Iterator[Highlight]: ... + + def create_highlight_tag(self, highlight_id: int, name: str) -> Tag: ... + + def update_highlight_tag(self, highlight_id: int, tag_id: int, name: str) -> Tag: ... + + def delete_highlight_tag(self, highlight_id: int, tag_id: int) -> None: ... + + +@dataclass +class TagPattern: + """A regular-expression rule for auto-tagging highlights.""" + + pattern: str + tag: str + case_sensitive: bool = False + match_in_notes: bool = True + match_in_text: bool = True + + def matches(self, highlight: Highlight) -> bool: + """Return whether this pattern matches the configured highlight fields.""" + flags = 0 if self.case_sensitive else re.IGNORECASE + targets: list[str] = [] + if self.match_in_text: + targets.append(highlight.text) + if self.match_in_notes and highlight.note: + targets.append(highlight.note) + return any(re.search(self.pattern, target, flags) is not None for target in targets) + + +@dataclass +class TagReport: + """Tag usage statistics with legacy-compatible fields.""" + + total_tags: int + total_usages: int + tags_by_usage: list[tuple[str, int]] + unused_tags: list[str] + duplicate_candidates: list[list[str]] + + +@dataclass +class TagCleanupResult: + """Legacy result model retained for import compatibility.""" + + merged_tags: list[tuple[list[str], str]] + deleted_tags: list[str] + renamed_tags: list[tuple[str, str]] + errors: list[str] + + +def normalize_tag(tag: str) -> str: + """Normalize a tag using the legacy duplicate-candidate rule.""" + return re.sub(r"[^a-z0-9]", "", tag.lower()) + + +def find_similar_tags(tags: list[str]) -> list[list[str]]: + """Group tag spellings that normalize to the same value.""" + groups: list[list[str]] = [] + processed: set[str] = set() + + for tag in tags: + if tag in processed: + continue + similar = [tag] + normalized = normalize_tag(tag) + for other in tags: + if other == tag or other in processed: + continue + if normalize_tag(other) == normalized: + similar.append(other) + if len(similar) > 1: + groups.append(similar) + processed.update(similar) + else: + processed.add(tag) + return groups + + +def build_tag_report(highlights: list[Highlight]) -> TagReport: + """Aggregate tag usage with the exact legacy counting policy.""" + tag_usage: Counter[str] = Counter() + all_tags: set[str] = set() + for highlight in highlights: + for tag in highlight.tags or []: + tag_usage[tag.name] += 1 + all_tags.add(tag.name) + tags_by_usage = tag_usage.most_common() + return TagReport( + total_tags=len(all_tags), + total_usages=sum(tag_usage.values()), + tags_by_usage=tags_by_usage, + unused_tags=[tag for tag, count in tags_by_usage if count == 0], + duplicate_candidates=find_similar_tags(list(all_tags)), + ) + + +def matching_auto_tags(highlight: Highlight, patterns: list[TagPattern]) -> list[str]: + """Return missing matching tags in pattern order.""" + existing = {tag.name.lower() for tag in (highlight.tags or [])} + return [ + pattern.tag + for pattern in patterns + if pattern.matches(highlight) and pattern.tag.lower() not in existing + ] + + +def matching_source_tags(highlight: Highlight, source_tags: set[str]) -> list[Tag]: + """Return source tags using the legacy set-intersection iteration order.""" + tag_map = {tag.name.lower(): tag for tag in (highlight.tags or [])} + matching_names = source_tags & set(tag_map) + return [tag_map[name] for name in matching_names] + + +class TagOperations: + """Own async tag search, reporting, auto-tagging, and cleanup semantics.""" + + def __init__( + self, + highlights: TagHighlightsResource, + tags: HighlightTagsResource, + ) -> None: + self._highlights = highlights + self._tags = tags + + async def _all_highlights(self) -> list[Highlight]: + return [highlight async for highlight in self._highlights.iter()] + + async def auto_tag_highlights( + self, + patterns: list[TagPattern], + *, + dry_run: bool = False, + ) -> dict[int, list[str]]: + """Apply missing tags to highlights matched by the supplied patterns.""" + results: dict[int, list[str]] = {} + async for highlight in self._highlights.iter(): + matching_tags = matching_auto_tags(highlight, patterns) + if not matching_tags: + continue + results[highlight.id] = matching_tags + if not dry_run: + for tag in matching_tags: + try: + await self._tags.create_highlight(highlight.id, tag) + except Exception: + pass # Characterizes current workflow behavior. + return results + + async def get_tag_report(self) -> TagReport: + """Return usage and duplicate-candidate statistics.""" + return build_tag_report(await self._all_highlights()) + + async def merge_tags( + self, + source_tags: list[str], + target_tag: str, + *, + dry_run: bool = False, + ) -> list[int]: + """Merge source tag spellings into a target tag.""" + affected: list[int] = [] + sources = {tag.lower() for tag in source_tags} + async for highlight in self._highlights.iter(): + matching = matching_source_tags(highlight, sources) + if not matching: + continue + affected.append(highlight.id) + if dry_run: + continue + existing = {tag.name.lower() for tag in (highlight.tags or [])} + if target_tag.lower() not in existing: + try: + await self._tags.create_highlight(highlight.id, target_tag) + except Exception: + pass # Characterizes current workflow behavior. + for tag in matching: + if tag.id: + try: + await self._tags.delete_highlight(highlight.id, tag.id) + except Exception: + pass # Characterizes current workflow behavior. + return affected + + async def rename_tag( + self, + old_name: str, + new_name: str, + *, + dry_run: bool = False, + ) -> list[int]: + """Rename a tag across all highlights.""" + affected: list[int] = [] + old_name_lower = old_name.lower() + async for highlight in self._highlights.iter(): + tag_map = {tag.name.lower(): tag for tag in (highlight.tags or [])} + if old_name_lower not in tag_map: + continue + affected.append(highlight.id) + tag = tag_map[old_name_lower] + if not dry_run and tag.id: + try: + await self._tags.update_highlight(highlight.id, tag.id, new_name) + except Exception: + pass # Characterizes current workflow behavior. + return affected + + async def delete_tag(self, tag_name: str, *, dry_run: bool = False) -> list[int]: + """Delete a named tag from every highlight that has it.""" + affected: list[int] = [] + tag_name_lower = tag_name.lower() + async for highlight in self._highlights.iter(): + tag_map = {tag.name.lower(): tag for tag in (highlight.tags or [])} + if tag_name_lower not in tag_map: + continue + affected.append(highlight.id) + tag = tag_map[tag_name_lower] + if not dry_run and tag.id: + try: + await self._tags.delete_highlight(highlight.id, tag.id) + except Exception: + pass # Characterizes current workflow behavior. + return affected + + async def get_highlights_by_tag(self, tag_name: str) -> list[Highlight]: + """Return highlights containing a case-insensitive tag name.""" + tag_name_lower = tag_name.lower() + return [ + highlight + async for highlight in self._highlights.iter() + if tag_name_lower in {tag.name.lower() for tag in (highlight.tags or [])} + ] + + async def get_untagged_highlights(self) -> list[Highlight]: + """Return highlights with no tags.""" + return [highlight async for highlight in self._highlights.iter() if not highlight.tags] + + +class SyncTagOperations: + """Synchronous operation adapter used solely by the legacy workflow shim.""" + + def __init__(self, client: SyncTagClient) -> None: + self._client = client + + def auto_tag_highlights( + self, + patterns: list[TagPattern], + *, + dry_run: bool = False, + ) -> dict[int, list[str]]: + results: dict[int, list[str]] = {} + for highlight in self._client.list_highlights(): + matching_tags = matching_auto_tags(highlight, patterns) + if not matching_tags: + continue + results[highlight.id] = matching_tags + if not dry_run: + for tag in matching_tags: + try: + self._client.create_highlight_tag(highlight.id, tag) + except Exception: + pass # Characterizes current workflow behavior. + return results + + def get_tag_report(self) -> TagReport: + return build_tag_report(list(self._client.list_highlights())) + + def merge_tags( + self, + source_tags: list[str], + target_tag: str, + *, + dry_run: bool = False, + ) -> list[int]: + affected: list[int] = [] + sources = {tag.lower() for tag in source_tags} + for highlight in self._client.list_highlights(): + matching = matching_source_tags(highlight, sources) + if not matching: + continue + affected.append(highlight.id) + if dry_run: + continue + existing = {tag.name.lower() for tag in (highlight.tags or [])} + if target_tag.lower() not in existing: + try: + self._client.create_highlight_tag(highlight.id, target_tag) + except Exception: + pass # Characterizes current workflow behavior. + for tag in matching: + if tag.id: + try: + self._client.delete_highlight_tag(highlight.id, tag.id) + except Exception: + pass # Characterizes current workflow behavior. + return affected + + def rename_tag( + self, + old_name: str, + new_name: str, + *, + dry_run: bool = False, + ) -> list[int]: + affected: list[int] = [] + old_name_lower = old_name.lower() + for highlight in self._client.list_highlights(): + tag_map = {tag.name.lower(): tag for tag in (highlight.tags or [])} + if old_name_lower not in tag_map: + continue + affected.append(highlight.id) + tag = tag_map[old_name_lower] + if not dry_run and tag.id: + try: + self._client.update_highlight_tag(highlight.id, tag.id, new_name) + except Exception: + pass # Characterizes current workflow behavior. + return affected + + def delete_tag(self, tag_name: str, *, dry_run: bool = False) -> list[int]: + affected: list[int] = [] + tag_name_lower = tag_name.lower() + for highlight in self._client.list_highlights(): + tag_map = {tag.name.lower(): tag for tag in (highlight.tags or [])} + if tag_name_lower not in tag_map: + continue + affected.append(highlight.id) + tag = tag_map[tag_name_lower] + if not dry_run and tag.id: + try: + self._client.delete_highlight_tag(highlight.id, tag.id) + except Exception: + pass # Characterizes current workflow behavior. + return affected + + def get_highlights_by_tag(self, tag_name: str) -> list[Highlight]: + tag_name_lower = tag_name.lower() + return [ + highlight + for highlight in self._client.list_highlights() + if tag_name_lower in {tag.name.lower() for tag in (highlight.tags or [])} + ] + + def get_untagged_highlights(self) -> list[Highlight]: + return [highlight for highlight in self._client.list_highlights() if not highlight.tags] + + +__all__ = [ + "SyncTagOperations", + "TagCleanupResult", + "TagOperations", + "TagPattern", + "TagReport", + "find_similar_tags", + "normalize_tag", +] diff --git a/src/readwise_sdk/presenters/__init__.py b/src/readwise_sdk/presenters/__init__.py new file mode 100644 index 0000000..dda9869 --- /dev/null +++ b/src/readwise_sdk/presenters/__init__.py @@ -0,0 +1,34 @@ +"""Protocol-neutral presenters for SDK operation results.""" + +from __future__ import annotations + +from enum import Enum + +from readwise_sdk.operations.digests import DigestData +from readwise_sdk.presenters import csv as csv_presenter +from readwise_sdk.presenters import json as json_presenter +from readwise_sdk.presenters import markdown as markdown_presenter +from readwise_sdk.presenters import text as text_presenter + + +class DigestFormat(str, Enum): + """Supported legacy digest output formats.""" + + MARKDOWN = "markdown" + JSON = "json" + CSV = "csv" + TEXT = "text" + + +def render_digest(digest: DigestData, output_format: DigestFormat) -> str: + """Render digest data with the selected presenter.""" + if output_format is DigestFormat.JSON: + return json_presenter.render(digest) + if output_format is DigestFormat.CSV: + return csv_presenter.render(digest) + if output_format is DigestFormat.TEXT: + return text_presenter.render(digest) + return markdown_presenter.render(digest) + + +__all__ = ["DigestFormat", "render_digest"] diff --git a/src/readwise_sdk/presenters/csv.py b/src/readwise_sdk/presenters/csv.py new file mode 100644 index 0000000..989b1c7 --- /dev/null +++ b/src/readwise_sdk/presenters/csv.py @@ -0,0 +1,31 @@ +"""CSV digest presentation.""" + +from __future__ import annotations + +import csv +from io import StringIO + +from readwise_sdk.operations.digests import DigestData + + +def render(digest: DigestData) -> str: + """Render digest data using the legacy CSV contract.""" + output = StringIO() + writer = csv.writer(output) + writer.writerow(["id", "text", "note", "location", "book_id", "highlighted_at", "tags"]) + for highlight in digest.highlights: + writer.writerow( + [ + highlight.id, + highlight.text, + highlight.note or "", + highlight.location or "", + highlight.book_id or "", + highlight.highlighted_at.isoformat() if highlight.highlighted_at else "", + ",".join(tag.name for tag in (highlight.tags or [])), + ] + ) + return output.getvalue() + + +__all__ = ["render"] diff --git a/src/readwise_sdk/presenters/json.py b/src/readwise_sdk/presenters/json.py new file mode 100644 index 0000000..c1e6b7a --- /dev/null +++ b/src/readwise_sdk/presenters/json.py @@ -0,0 +1,35 @@ +"""JSON digest presentation.""" + +from __future__ import annotations + +import json +from datetime import UTC, datetime + +from readwise_sdk.operations.digests import DigestData + + +def render(digest: DigestData) -> str: + """Render digest data using the legacy indented JSON contract.""" + data = { + "title": digest.title, + "generated_at": datetime.now(UTC).isoformat(), + "count": len(digest.highlights), + "highlights": [ + { + "id": highlight.id, + "text": highlight.text, + "note": highlight.note, + "location": highlight.location, + "book_id": highlight.book_id, + "highlighted_at": ( + highlight.highlighted_at.isoformat() if highlight.highlighted_at else None + ), + "tags": [tag.name for tag in (highlight.tags or [])], + } + for highlight in digest.highlights + ], + } + return json.dumps(data, indent=2) + + +__all__ = ["render"] diff --git a/src/readwise_sdk/presenters/markdown.py b/src/readwise_sdk/presenters/markdown.py new file mode 100644 index 0000000..9535366 --- /dev/null +++ b/src/readwise_sdk/presenters/markdown.py @@ -0,0 +1,44 @@ +"""Markdown digest presentation.""" + +from __future__ import annotations + +from readwise_sdk.operations.digests import DigestData, DigestGrouping +from readwise_sdk.v2.models import Highlight + + +def _format_highlight(highlight: Highlight, *, include_book: bool = True) -> list[str]: + lines = [f"> {highlight.text}", ""] + metadata: list[str] = [] + if include_book and highlight.book_id: + metadata.append(f"Book ID: {highlight.book_id}") + if highlight.location: + metadata.append(f"Location: {highlight.location}") + if highlight.note: + metadata.append(f"Note: {highlight.note}") + if highlight.tags: + metadata.append(f"Tags: {', '.join(tag.name for tag in highlight.tags)}") + if metadata: + lines.extend([f"*{' | '.join(metadata)}*", ""]) + return lines + + +def render(digest: DigestData) -> str: + """Render digest data using the legacy Markdown contract.""" + lines = [f"# {digest.title}", "", f"*{len(digest.highlights)} highlights*", ""] + if digest.grouping is DigestGrouping.DATE: + for name, highlights in digest.groups: + lines.extend([f"## {name}", ""]) + for highlight in highlights: + lines.extend(_format_highlight(highlight)) + elif digest.grouping is DigestGrouping.BOOK: + for name, highlights in digest.groups: + lines.extend([f"## {name}", ""]) + for highlight in highlights: + lines.extend(_format_highlight(highlight, include_book=False)) + else: + for highlight in digest.highlights: + lines.extend(_format_highlight(highlight)) + return "\n".join(lines) + + +__all__ = ["render"] diff --git a/src/readwise_sdk/presenters/text.py b/src/readwise_sdk/presenters/text.py new file mode 100644 index 0000000..b5bad49 --- /dev/null +++ b/src/readwise_sdk/presenters/text.py @@ -0,0 +1,34 @@ +"""Plain-text digest presentation.""" + +from __future__ import annotations + +from readwise_sdk.operations.digests import DigestData, DigestGrouping + + +def render(digest: DigestData) -> str: + """Render digest data using the legacy plain-text contract.""" + lines = [ + digest.title, + "=" * len(digest.title), + "", + f"{len(digest.highlights)} highlights", + "", + ] + if digest.grouping in {DigestGrouping.DATE, DigestGrouping.BOOK}: + for name, highlights in digest.groups: + lines.extend([name, "-" * len(name)]) + for highlight in highlights: + lines.append(f" {highlight.text}") + if highlight.note: + lines.append(f" Note: {highlight.note}") + lines.append("") + else: + for highlight in digest.highlights: + lines.append(highlight.text) + if highlight.note: + lines.append(f"Note: {highlight.note}") + lines.append("") + return "\n".join(lines) + + +__all__ = ["render"] diff --git a/src/readwise_sdk/sdk/async_.py b/src/readwise_sdk/sdk/async_.py index b041cbf..ffc39c1 100644 --- a/src/readwise_sdk/sdk/async_.py +++ b/src/readwise_sdk/sdk/async_.py @@ -8,9 +8,11 @@ from readwise_sdk.config import DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF, DEFAULT_TIMEOUT from readwise_sdk.operations import ( BookOperations, + DigestOperations, DocumentOperations, HighlightOperations, ReadwiseService, + TagOperations, ) from readwise_sdk.resources.v2 import ( AsyncBooksResource, @@ -72,13 +74,19 @@ def __init__( ) transport = self._client._transport highlights = AsyncHighlightsResource(transport) + tags = AsyncTagsResource(transport) + books = AsyncBooksResource(transport) self._service = ReadwiseService( documents=AsyncDocumentsResource(transport), highlights=highlights, - highlight_tags=AsyncTagsResource(transport), + highlight_tags=tags, export=AsyncExportResource(transport), - books=AsyncBooksResource(transport), + books=books, book_highlights=highlights, + tag_highlights=highlights, + tag_mutations=tags, + digest_highlights=highlights, + digest_books=books, ) self._raw = _AsyncRawClients(self._client) @@ -97,7 +105,17 @@ def books(self) -> BookOperations: """Return canonical Readwise book operations.""" return self._service.books - # tags, digests, and sync are deferred until wired to canonical ops in stages 13/14. + @property + def tags(self) -> TagOperations: + """Return canonical Readwise tag operations.""" + return self._service.tags + + @property + def digests(self) -> DigestOperations: + """Return canonical Readwise digest data operations.""" + return self._service.digests + + # sync remains deferred until stage 14. @property def raw(self) -> _AsyncRawClients: diff --git a/src/readwise_sdk/sdk/sync.py b/src/readwise_sdk/sdk/sync.py index 2996c0f..b008a29 100644 --- a/src/readwise_sdk/sdk/sync.py +++ b/src/readwise_sdk/sdk/sync.py @@ -19,6 +19,7 @@ from readwise_sdk.operations import ( BookSearchResult, BookWithHighlights, + DigestData, DocumentStatistics, HighlightCreateResult, HighlightDeleteResult, @@ -29,6 +30,8 @@ HighlightUpdateInput, HighlightUpdateResult, ReadingStatistics, + TagPattern, + TagReport, ) from readwise_sdk.sdk.async_ import AsyncReadwise from readwise_sdk.v2.models import Book, BookCategory, Highlight, HighlightCreate, HighlightUpdate @@ -41,7 +44,13 @@ ) if TYPE_CHECKING: - from readwise_sdk.operations import BookOperations, DocumentOperations, HighlightOperations + from readwise_sdk.operations import ( + BookOperations, + DigestOperations, + DocumentOperations, + HighlightOperations, + TagOperations, + ) from readwise_sdk.v2.client import ReadwiseV2Client from readwise_sdk.v3.client import ReadwiseV3Client @@ -390,6 +399,95 @@ def count(self) -> int: return self._call(self._operations.count) +class _SyncTagOperations(_SyncOperationGroup): + """Synchronous adapter for canonical tag operations.""" + + def __init__(self, owner: Readwise, operations: TagOperations) -> None: + super().__init__(owner) + self._operations = operations + + def auto_tag_highlights( + self, + patterns: builtins.list[TagPattern], + *, + dry_run: bool = False, + ) -> dict[int, builtins.list[str]]: + return self._call(self._operations.auto_tag_highlights, patterns, dry_run=dry_run) + + def get_tag_report(self) -> TagReport: + return self._call(self._operations.get_tag_report) + + def merge_tags( + self, + source_tags: builtins.list[str], + target_tag: str, + *, + dry_run: bool = False, + ) -> builtins.list[int]: + return self._call( + self._operations.merge_tags, + source_tags, + target_tag, + dry_run=dry_run, + ) + + def rename_tag( + self, + old_name: str, + new_name: str, + *, + dry_run: bool = False, + ) -> builtins.list[int]: + return self._call( + self._operations.rename_tag, + old_name, + new_name, + dry_run=dry_run, + ) + + def delete_tag(self, tag_name: str, *, dry_run: bool = False) -> builtins.list[int]: + return self._call(self._operations.delete_tag, tag_name, dry_run=dry_run) + + def get_highlights_by_tag(self, tag_name: str) -> builtins.list[Highlight]: + return self._call(self._operations.get_highlights_by_tag, tag_name) + + def get_untagged_highlights(self) -> builtins.list[Highlight]: + return self._call(self._operations.get_untagged_highlights) + + +class _SyncDigestOperations(_SyncOperationGroup): + """Synchronous adapter for canonical digest data operations.""" + + def __init__(self, owner: Readwise, operations: DigestOperations) -> None: + super().__init__(owner) + self._operations = operations + + def daily(self, *, group_by_book: bool = True) -> DigestData: + return self._call(self._operations.daily, group_by_book=group_by_book) + + def weekly(self, *, group_by_book: bool = True) -> DigestData: + return self._call(self._operations.weekly, group_by_book=group_by_book) + + def book(self, book_id: int) -> DigestData: + return self._call(self._operations.book, book_id) + + def custom( + self, + *, + since: datetime | None = None, + book_id: int | None = None, + group_by_book: bool = True, + group_by_date: bool = False, + ) -> DigestData: + return self._call( + self._operations.custom, + since=since, + book_id=book_id, + group_by_book=group_by_book, + group_by_date=group_by_date, + ) + + class Readwise: """Concept-oriented synchronous Readwise SDK. @@ -424,6 +522,8 @@ def __init__( self._documents = _SyncDocumentOperations(self, self._async.documents) self._highlights = _SyncHighlightOperations(self, self._async.highlights) self._books = _SyncBookOperations(self, self._async.books) + self._tags = _SyncTagOperations(self, self._async.tags) + self._digests = _SyncDigestOperations(self, self._async.digests) self._portal: BlockingPortal | None = None self._portal_context: AbstractContextManager[BlockingPortal] | None = None self._lifecycle_lock = Lock() @@ -443,7 +543,17 @@ def books(self) -> _SyncBookOperations: """Return synchronous canonical Readwise book operations.""" return self._books - # tags, digests, and sync mirror AsyncReadwise by remaining deferred. + @property + def tags(self) -> _SyncTagOperations: + """Return synchronous canonical tag operations.""" + return self._tags + + @property + def digests(self) -> _SyncDigestOperations: + """Return synchronous canonical digest data operations.""" + return self._digests + + # sync mirrors AsyncReadwise by remaining deferred until stage 14. @property def raw(self) -> _SyncRawClients: diff --git a/src/readwise_sdk/workflows/digest.py b/src/readwise_sdk/workflows/digest.py index 26d1f02..ec5c1b7 100644 --- a/src/readwise_sdk/workflows/digest.py +++ b/src/readwise_sdk/workflows/digest.py @@ -1,43 +1,24 @@ -"""Digest builder for creating highlight summaries.""" +"""Compatibility shim for the legacy digest builder.""" from __future__ import annotations -import csv -import json -from datetime import UTC, datetime, timedelta -from enum import Enum -from io import StringIO +from datetime import datetime from typing import TYPE_CHECKING +from readwise_sdk.operations.digests import SyncDigestOperations, build_digest +from readwise_sdk.presenters import DigestFormat, render_digest from readwise_sdk.v2.models import Highlight if TYPE_CHECKING: from readwise_sdk.client import ReadwiseClient -class DigestFormat(str, Enum): - """Output format for digests.""" - - MARKDOWN = "markdown" - JSON = "json" - CSV = "csv" - TEXT = "text" - - class DigestBuilder: - """Builder for creating highlight digests in various formats.""" + """Legacy blocking wrapper over digest operations and presenters.""" def __init__(self, client: ReadwiseClient) -> None: - """Initialize the digest builder. - - Args: - client: The Readwise client. - """ self._client = client - - def _get_highlights_since(self, since: datetime) -> list[Highlight]: - """Get highlights updated since a given time.""" - return list(self._client.v2.list_highlights(updated_after=since)) + self._operations = SyncDigestOperations(client.v2) def create_daily_digest( self, @@ -45,23 +26,9 @@ def create_daily_digest( output_format: DigestFormat = DigestFormat.MARKDOWN, group_by_book: bool = True, ) -> str: - """Create a digest of highlights from the last 24 hours. - - Args: - output_format: The output format. - group_by_book: Whether to group highlights by book. - - Returns: - Formatted digest string. - """ - since = datetime.now(UTC) - timedelta(days=1) - highlights = self._get_highlights_since(since) - return self._format_digest( - highlights, - title="Daily Digest", - output_format=output_format, - group_by_book=group_by_book, - ) + """Create a digest of highlights from the last 24 hours.""" + data = self._operations.daily(group_by_book=group_by_book) + return render_digest(data, output_format) def create_weekly_digest( self, @@ -69,23 +36,9 @@ def create_weekly_digest( output_format: DigestFormat = DigestFormat.MARKDOWN, group_by_book: bool = True, ) -> str: - """Create a digest of highlights from the last 7 days. - - Args: - output_format: The output format. - group_by_book: Whether to group highlights by book. - - Returns: - Formatted digest string. - """ - since = datetime.now(UTC) - timedelta(days=7) - highlights = self._get_highlights_since(since) - return self._format_digest( - highlights, - title="Weekly Digest", - output_format=output_format, - group_by_book=group_by_book, - ) + """Create a digest of highlights from the last seven days.""" + data = self._operations.weekly(group_by_book=group_by_book) + return render_digest(data, output_format) def create_book_digest( self, @@ -93,23 +46,8 @@ def create_book_digest( *, output_format: DigestFormat = DigestFormat.MARKDOWN, ) -> str: - """Create a digest of all highlights for a specific book. - - Args: - book_id: The book ID. - output_format: The output format. - - Returns: - Formatted digest string. - """ - book = self._client.v2.get_book(book_id) - highlights = list(self._client.v2.list_highlights(book_id=book_id)) - return self._format_digest( - highlights, - title=f"Highlights from: {book.title}", - output_format=output_format, - group_by_book=False, - ) + """Create a digest of all highlights for a specific book.""" + return render_digest(self._operations.book(book_id), output_format) def create_custom_digest( self, @@ -120,31 +58,14 @@ def create_custom_digest( group_by_book: bool = True, group_by_date: bool = False, ) -> str: - """Create a custom digest with specified filters. - - Args: - since: Only include highlights updated after this time. - book_id: Only include highlights from this book. - output_format: The output format. - group_by_book: Whether to group highlights by book. - group_by_date: Whether to group highlights by date. - - Returns: - Formatted digest string. - """ - highlights = list( - self._client.v2.list_highlights( - updated_after=since, - book_id=book_id, - ) - ) - return self._format_digest( - highlights, - title="Custom Digest", - output_format=output_format, + """Create a custom digest with specified filters and grouping.""" + data = self._operations.custom( + since=since, + book_id=book_id, group_by_book=group_by_book, group_by_date=group_by_date, ) + return render_digest(data, output_format) def _format_digest( self, @@ -155,183 +76,14 @@ def _format_digest( group_by_book: bool = True, group_by_date: bool = False, ) -> str: - """Format highlights into the specified output format. - - Args: - highlights: List of highlights. - title: Digest title. - output_format: The output format. - group_by_book: Whether to group by book. - group_by_date: Whether to group by date. - - Returns: - Formatted string. - """ - if output_format == DigestFormat.JSON: - return self._format_json(highlights, title) - elif output_format == DigestFormat.CSV: - return self._format_csv(highlights) - elif output_format == DigestFormat.TEXT: - return self._format_text(highlights, title, group_by_book, group_by_date) - else: - return self._format_markdown(highlights, title, group_by_book, group_by_date) - - def _format_markdown( - self, - highlights: list[Highlight], - title: str, - group_by_book: bool, - group_by_date: bool, - ) -> str: - """Format as Markdown.""" - lines = [f"# {title}", "", f"*{len(highlights)} highlights*", ""] - - if group_by_date: - groups = self._group_by_date(highlights) - for date_str, date_highlights in sorted(groups.items(), reverse=True): - lines.append(f"## {date_str}") - lines.append("") - for h in date_highlights: - lines.extend(self._format_highlight_md(h)) - elif group_by_book: - groups = self._group_by_book(highlights) - for book_title, book_highlights in groups.items(): - lines.append(f"## {book_title}") - lines.append("") - for h in book_highlights: - lines.extend(self._format_highlight_md(h, include_book=False)) - else: - for h in highlights: - lines.extend(self._format_highlight_md(h)) - - return "\n".join(lines) - - def _format_highlight_md( - self, - highlight: Highlight, - include_book: bool = True, - ) -> list[str]: - """Format a single highlight as Markdown.""" - lines = [f"> {highlight.text}", ""] - - metadata = [] - if include_book and highlight.book_id: - metadata.append(f"Book ID: {highlight.book_id}") - if highlight.location: - metadata.append(f"Location: {highlight.location}") - if highlight.note: - metadata.append(f"Note: {highlight.note}") - if highlight.tags: - tag_names = [t.name for t in highlight.tags] - metadata.append(f"Tags: {', '.join(tag_names)}") - - if metadata: - lines.append(f"*{' | '.join(metadata)}*") - lines.append("") - - return lines - - def _format_text( - self, - highlights: list[Highlight], - title: str, - group_by_book: bool, - group_by_date: bool, - ) -> str: - """Format as plain text.""" - lines = [title, "=" * len(title), "", f"{len(highlights)} highlights", ""] - - if group_by_date: - groups = self._group_by_date(highlights) - for date_str, date_highlights in sorted(groups.items(), reverse=True): - lines.append(date_str) - lines.append("-" * len(date_str)) - for h in date_highlights: - lines.append(f" {h.text}") - if h.note: - lines.append(f" Note: {h.note}") - lines.append("") - elif group_by_book: - groups = self._group_by_book(highlights) - for book_title, book_highlights in groups.items(): - lines.append(book_title) - lines.append("-" * len(book_title)) - for h in book_highlights: - lines.append(f" {h.text}") - if h.note: - lines.append(f" Note: {h.note}") - lines.append("") - else: - for h in highlights: - lines.append(h.text) - if h.note: - lines.append(f"Note: {h.note}") - lines.append("") - - return "\n".join(lines) - - def _format_json(self, highlights: list[Highlight], title: str) -> str: - """Format as JSON.""" - data = { - "title": title, - "generated_at": datetime.now(UTC).isoformat(), - "count": len(highlights), - "highlights": [ - { - "id": h.id, - "text": h.text, - "note": h.note, - "location": h.location, - "book_id": h.book_id, - "highlighted_at": h.highlighted_at.isoformat() if h.highlighted_at else None, - "tags": [t.name for t in (h.tags or [])], - } - for h in highlights - ], - } - return json.dumps(data, indent=2) - - def _format_csv(self, highlights: list[Highlight]) -> str: - """Format as CSV.""" - output = StringIO() - writer = csv.writer(output) - writer.writerow(["id", "text", "note", "location", "book_id", "highlighted_at", "tags"]) - - for h in highlights: - tags = ",".join(t.name for t in (h.tags or [])) - writer.writerow( - [ - h.id, - h.text, - h.note or "", - h.location or "", - h.book_id or "", - h.highlighted_at.isoformat() if h.highlighted_at else "", - tags, - ] - ) - - return output.getvalue() + """Preserve the formatter seam used by the existing highlights CLI.""" + data = build_digest( + highlights, + title=title, + group_by_book_enabled=group_by_book, + group_by_date_enabled=group_by_date, + ) + return render_digest(data, output_format) - def _group_by_book(self, highlights: list[Highlight]) -> dict[str, list[Highlight]]: - """Group highlights by book.""" - groups: dict[str, list[Highlight]] = {} - for h in highlights: - key = f"Book {h.book_id}" if h.book_id else "Unknown" - if key not in groups: - groups[key] = [] - groups[key].append(h) - return groups - def _group_by_date(self, highlights: list[Highlight]) -> dict[str, list[Highlight]]: - """Group highlights by date.""" - groups: dict[str, list[Highlight]] = {} - for h in highlights: - if h.highlighted_at: - key = h.highlighted_at.strftime("%Y-%m-%d") - else: - key = "Unknown Date" - if key not in groups: - groups[key] = [] - groups[key].append(h) - return groups +__all__ = ["DigestBuilder", "DigestFormat"] diff --git a/src/readwise_sdk/workflows/tags.py b/src/readwise_sdk/workflows/tags.py index df32b78..3feb850 100644 --- a/src/readwise_sdk/workflows/tags.py +++ b/src/readwise_sdk/workflows/tags.py @@ -1,75 +1,29 @@ -"""Tag workflow utilities for automated tagging and cleanup.""" +"""Compatibility shims for legacy tag workflow imports.""" from __future__ import annotations -import re -from collections import Counter -from dataclasses import dataclass from typing import TYPE_CHECKING +from readwise_sdk.operations.tags import ( + SyncTagOperations, + TagCleanupResult, + TagPattern, + TagReport, + find_similar_tags, + normalize_tag, +) from readwise_sdk.v2.models import Highlight if TYPE_CHECKING: from readwise_sdk.client import ReadwiseClient -@dataclass -class TagPattern: - """A pattern for auto-tagging highlights.""" - - pattern: str - tag: str - case_sensitive: bool = False - match_in_notes: bool = True - match_in_text: bool = True - - def matches(self, highlight: Highlight) -> bool: - """Check if a highlight matches this pattern.""" - flags = 0 if self.case_sensitive else re.IGNORECASE - - targets = [] - if self.match_in_text: - targets.append(highlight.text) - if self.match_in_notes and highlight.note: - targets.append(highlight.note) - - for target in targets: - if re.search(self.pattern, target, flags): - return True - return False - - -@dataclass -class TagReport: - """Report of tag usage statistics.""" - - total_tags: int - total_usages: int - tags_by_usage: list[tuple[str, int]] - unused_tags: list[str] - duplicate_candidates: list[list[str]] - - -@dataclass -class TagCleanupResult: - """Result of a tag cleanup operation.""" - - merged_tags: list[tuple[list[str], str]] - deleted_tags: list[str] - renamed_tags: list[tuple[str, str]] - errors: list[str] - - class TagWorkflow: - """Workflow utilities for tag management.""" + """Legacy blocking wrapper over operation-owned tag behavior.""" def __init__(self, client: ReadwiseClient) -> None: - """Initialize the tag workflow. - - Args: - client: The Readwise client. - """ self._client = client + self._operations = SyncTagOperations(client.v2) def auto_tag_highlights( self, @@ -77,102 +31,20 @@ def auto_tag_highlights( *, dry_run: bool = False, ) -> dict[int, list[str]]: - """Apply automatic tagging based on patterns. - - Args: - patterns: List of TagPattern rules to apply. - dry_run: If True, don't actually apply tags, just report matches. - - Returns: - Dict mapping highlight ID to list of tags that were/would be applied. - """ - results: dict[int, list[str]] = {} - - for highlight in self._client.v2.list_highlights(): - matching_tags = [] - existing_tag_names = {t.name.lower() for t in (highlight.tags or [])} - - for pattern in patterns: - if pattern.matches(highlight): - # Only add if not already tagged - if pattern.tag.lower() not in existing_tag_names: - matching_tags.append(pattern.tag) - - if matching_tags: - results[highlight.id] = matching_tags - if not dry_run: - for tag in matching_tags: - try: - self._client.v2.create_highlight_tag(highlight.id, tag) - except Exception: - pass # Tag may already exist - - return results + """Apply automatic tagging based on patterns.""" + return self._operations.auto_tag_highlights(patterns, dry_run=dry_run) def get_tag_report(self) -> TagReport: - """Generate a report of tag usage statistics. - - Returns: - TagReport with usage statistics. - """ - # Get all highlights to count tag usage - tag_usage: Counter[str] = Counter() - all_tags: set[str] = set() - - for highlight in self._client.v2.list_highlights(): - for tag in highlight.tags or []: - tag_usage[tag.name] += 1 - all_tags.add(tag.name) - - # Sort by usage - tags_by_usage = tag_usage.most_common() - - # Find unused tags (tags that exist but have no highlights) - # Note: This requires knowing all defined tags, which may not be fully accurate - unused_tags = [tag for tag, count in tags_by_usage if count == 0] - - # Find potential duplicates (similar names) - duplicate_candidates = self._find_similar_tags(list(all_tags)) - - return TagReport( - total_tags=len(all_tags), - total_usages=sum(tag_usage.values()), - tags_by_usage=tags_by_usage, - unused_tags=unused_tags, - duplicate_candidates=duplicate_candidates, - ) + """Generate a report of tag usage statistics.""" + return self._operations.get_tag_report() def _find_similar_tags(self, tags: list[str]) -> list[list[str]]: - """Find tags that might be duplicates based on similarity.""" - groups: list[list[str]] = [] - processed: set[str] = set() - - for tag in tags: - if tag in processed: - continue - - similar = [tag] - normalized = self._normalize_tag(tag) - - for other in tags: - if other == tag or other in processed: - continue - if self._normalize_tag(other) == normalized: - similar.append(other) - - if len(similar) > 1: - groups.append(similar) - processed.update(similar) - else: - processed.add(tag) - - return groups + """Preserve the existing private compatibility seam.""" + return find_similar_tags(tags) def _normalize_tag(self, tag: str) -> str: - """Normalize a tag for comparison.""" - # Remove special characters, lowercase, strip whitespace - normalized = re.sub(r"[^a-z0-9]", "", tag.lower()) - return normalized + """Preserve the existing private compatibility seam.""" + return normalize_tag(tag) def merge_tags( self, @@ -181,46 +53,8 @@ def merge_tags( *, dry_run: bool = False, ) -> list[int]: - """Merge multiple tags into one. - - Args: - source_tags: Tags to merge from (will be removed). - target_tag: Tag to merge into. - dry_run: If True, don't actually merge, just report affected highlights. - - Returns: - List of highlight IDs that were affected. - """ - affected_highlights: list[int] = [] - source_tags_lower = {t.lower() for t in source_tags} - - for highlight in self._client.v2.list_highlights(): - highlight_tag_names = {t.name.lower(): t for t in (highlight.tags or [])} - - # Check if this highlight has any of the source tags - matching_source_tags = source_tags_lower & set(highlight_tag_names.keys()) - - if matching_source_tags: - affected_highlights.append(highlight.id) - - if not dry_run: - # Add the target tag if not present - if target_tag.lower() not in highlight_tag_names: - try: - self._client.v2.create_highlight_tag(highlight.id, target_tag) - except Exception: - pass - - # Remove the source tags - for source_tag_name in matching_source_tags: - tag = highlight_tag_names.get(source_tag_name) - if tag and tag.id: - try: - self._client.v2.delete_highlight_tag(highlight.id, tag.id) - except Exception: - pass - - return affected_highlights + """Merge multiple tags into one.""" + return self._operations.merge_tags(source_tags, target_tag, dry_run=dry_run) def rename_tag( self, @@ -229,92 +63,20 @@ def rename_tag( *, dry_run: bool = False, ) -> list[int]: - """Rename a tag across all highlights. + """Rename a tag across all highlights.""" + return self._operations.rename_tag(old_name, new_name, dry_run=dry_run) - Args: - old_name: Current tag name. - new_name: New tag name. - dry_run: If True, don't actually rename, just report affected highlights. - - Returns: - List of highlight IDs that were affected. - """ - affected_highlights: list[int] = [] - old_name_lower = old_name.lower() - - for highlight in self._client.v2.list_highlights(): - highlight_tag_map = {t.name.lower(): t for t in (highlight.tags or [])} - - if old_name_lower in highlight_tag_map: - affected_highlights.append(highlight.id) - - if not dry_run: - tag = highlight_tag_map[old_name_lower] - if tag.id: - try: - self._client.v2.update_highlight_tag(highlight.id, tag.id, new_name) - except Exception: - pass - - return affected_highlights - - def delete_tag( - self, - tag_name: str, - *, - dry_run: bool = False, - ) -> list[int]: - """Delete a tag from all highlights. - - Args: - tag_name: Tag to delete. - dry_run: If True, don't actually delete, just report affected highlights. - - Returns: - List of highlight IDs that were affected. - """ - affected_highlights: list[int] = [] - tag_name_lower = tag_name.lower() - - for highlight in self._client.v2.list_highlights(): - highlight_tag_map = {t.name.lower(): t for t in (highlight.tags or [])} - - if tag_name_lower in highlight_tag_map: - affected_highlights.append(highlight.id) - - if not dry_run: - tag = highlight_tag_map[tag_name_lower] - if tag.id: - try: - self._client.v2.delete_highlight_tag(highlight.id, tag.id) - except Exception: - pass - - return affected_highlights + def delete_tag(self, tag_name: str, *, dry_run: bool = False) -> list[int]: + """Delete a tag from all highlights.""" + return self._operations.delete_tag(tag_name, dry_run=dry_run) def get_highlights_by_tag(self, tag_name: str) -> list[Highlight]: - """Get all highlights with a specific tag. - - Args: - tag_name: The tag name to filter by. - - Returns: - List of highlights with the tag. - """ - tag_name_lower = tag_name.lower() - results = [] - - for highlight in self._client.v2.list_highlights(): - tag_names = {t.name.lower() for t in (highlight.tags or [])} - if tag_name_lower in tag_names: - results.append(highlight) - - return results + """Get all highlights with a specific tag.""" + return self._operations.get_highlights_by_tag(tag_name) def get_untagged_highlights(self) -> list[Highlight]: - """Get all highlights without any tags. + """Get all highlights without any tags.""" + return self._operations.get_untagged_highlights() + - Returns: - List of untagged highlights. - """ - return [h for h in self._client.v2.list_highlights() if not h.tags] +__all__ = ["TagCleanupResult", "TagPattern", "TagReport", "TagWorkflow"] diff --git a/tests/operations/test_digests.py b/tests/operations/test_digests.py new file mode 100644 index 0000000..9ceec6e --- /dev/null +++ b/tests/operations/test_digests.py @@ -0,0 +1,82 @@ +"""Direct contracts for canonical digest selection and grouping.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from datetime import UTC, datetime, timedelta + +import pytest + +from readwise_sdk.operations.digests import DigestGrouping, DigestOperations +from readwise_sdk.v2.models import Book, Highlight + + +class HighlightResource: + def __init__(self, highlights: list[Highlight]) -> None: + self.highlights = highlights + self.calls: list[dict[str, object]] = [] + + async def iter(self, **kwargs: object) -> AsyncIterator[Highlight]: + self.calls.append(kwargs) + for highlight in self.highlights: + yield highlight + + +class BookResource: + async def get(self, book_id: int) -> Book: + assert book_id == 42 + return Book(id=42, title="The Book") + + +@pytest.mark.asyncio +async def test_custom_digest_owns_filtering_and_date_grouping() -> None: + now = datetime(2025, 1, 2, 3, 4, tzinfo=UTC) + highlights = [ + Highlight(id=1, text="Known", book_id=42, highlighted_at=now), + Highlight(id=2, text="Unknown", book_id=42), + ] + resource = HighlightResource(highlights) + operations = DigestOperations(resource, BookResource()) + since = now - timedelta(days=3) + + digest = await operations.custom( + since=since, + book_id=42, + group_by_book=False, + group_by_date=True, + ) + + assert resource.calls == [{"updated_after": since, "book_id": 42}] + assert digest.title == "Custom Digest" + assert digest.grouping is DigestGrouping.DATE + assert [(name, [item.id for item in items]) for name, items in digest.groups] == [ + ("Unknown Date", [2]), + ("2025-01-02", [1]), + ] + + +@pytest.mark.asyncio +async def test_book_digest_uses_book_title_and_disables_grouping() -> None: + resource = HighlightResource([Highlight(id=1, text="Book highlight", book_id=42)]) + operations = DigestOperations(resource, BookResource()) + + digest = await operations.book(42) + + assert resource.calls == [{"book_id": 42}] + assert digest.title == "Highlights from: The Book" + assert digest.grouping is DigestGrouping.NONE + assert digest.groups == [] + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("method", "days"), [("daily", 1), ("weekly", 7)]) +async def test_relative_digests_select_the_expected_time_window(method: str, days: int) -> None: + resource = HighlightResource([]) + operations = DigestOperations(resource, BookResource()) + before = datetime.now(UTC) - timedelta(days=days, seconds=1) + + await getattr(operations, method)() + + updated_after = resource.calls[0]["updated_after"] + assert isinstance(updated_after, datetime) + assert before < updated_after <= datetime.now(UTC) - timedelta(days=days) diff --git a/tests/operations/test_tags.py b/tests/operations/test_tags.py new file mode 100644 index 0000000..2fb72e6 --- /dev/null +++ b/tests/operations/test_tags.py @@ -0,0 +1,112 @@ +"""Direct contracts for canonical tag operations.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator + +import pytest + +from readwise_sdk.operations.tags import TagOperations, TagPattern +from readwise_sdk.v2.models import Highlight, Tag + + +class HighlightResource: + def __init__(self, highlights: list[Highlight]) -> None: + self.highlights = highlights + + async def iter(self, **kwargs: object) -> AsyncIterator[Highlight]: + assert kwargs == {} + for highlight in self.highlights: + yield highlight + + +class TagResource: + def __init__(self) -> None: + self.calls: list[tuple[object, ...]] = [] + + async def create_highlight(self, highlight_id: int, name: str) -> Tag: + self.calls.append(("create", highlight_id, name)) + if name == "fails": + raise RuntimeError("characterizes suppressed tag failures") + return Tag(id=99, name=name) + + async def update_highlight(self, highlight_id: int, tag_id: int, name: str) -> Tag: + self.calls.append(("update", highlight_id, tag_id, name)) + return Tag(id=tag_id, name=name) + + async def delete_highlight(self, highlight_id: int, tag_id: int) -> None: + self.calls.append(("delete", highlight_id, tag_id)) + + +def _highlight( + highlight_id: int, + text: str, + *tags: tuple[int, str], + note: str | None = None, +) -> Highlight: + return Highlight( + id=highlight_id, + text=text, + note=note, + tags=[Tag(id=tag_id, name=name) for tag_id, name in tags], + ) + + +@pytest.mark.asyncio +async def test_tag_search_report_and_untagged_selection_match_workflow_semantics() -> None: + highlights = [ + _highlight(1, "One", (10, "Python"), (11, "python!")), + _highlight(2, "Two", (12, "Python")), + _highlight(3, "Three"), + ] + operations = TagOperations(HighlightResource(highlights), TagResource()) + + report = await operations.get_tag_report() + + assert report.total_tags == 2 + assert report.total_usages == 3 + assert report.tags_by_usage == [("Python", 2), ("python!", 1)] + assert len(report.duplicate_candidates) == 1 + assert set(report.duplicate_candidates[0]) == {"Python", "python!"} + assert [item.id for item in await operations.get_highlights_by_tag("PYTHON")] == [1, 2] + assert [item.id for item in await operations.get_untagged_highlights()] == [3] + + +@pytest.mark.asyncio +async def test_auto_tag_preserves_matching_order_and_suppresses_apply_failures() -> None: + tags = TagResource() + operations = TagOperations( + HighlightResource([_highlight(1, "Python and Rust", note="important")]), + tags, + ) + patterns = [ + TagPattern("python", "language"), + TagPattern("important", "fails", match_in_text=False), + TagPattern("rust", "systems"), + ] + + result = await operations.auto_tag_highlights(patterns) + + assert result == {1: ["language", "fails", "systems"]} + assert tags.calls == [ + ("create", 1, "language"), + ("create", 1, "fails"), + ("create", 1, "systems"), + ] + + +@pytest.mark.asyncio +async def test_merge_rename_and_delete_preserve_legacy_mutation_semantics() -> None: + highlight = _highlight(1, "One", (10, "Old"), (11, "Keep")) + tags = TagResource() + operations = TagOperations(HighlightResource([highlight]), tags) + + assert await operations.merge_tags(["old"], "New") == [1] + assert await operations.rename_tag("OLD", "Renamed") == [1] + assert await operations.delete_tag("old") == [1] + assert tags.calls == [ + ("create", 1, "New"), + ("delete", 1, 10), + ("update", 1, 10, "Renamed"), + ("delete", 1, 10), + ] diff --git a/tests/presenters/test_digests.py b/tests/presenters/test_digests.py new file mode 100644 index 0000000..a0461d8 --- /dev/null +++ b/tests/presenters/test_digests.py @@ -0,0 +1,71 @@ +"""Exact rendering contracts for digest presenters.""" + +from __future__ import annotations + +import json +from datetime import UTC, datetime + +from readwise_sdk.operations.digests import DigestData, DigestGrouping +from readwise_sdk.presenters import DigestFormat, render_digest +from readwise_sdk.v2.models import Highlight, Tag + + +def _digest(grouping: DigestGrouping) -> DigestData: + highlight = Highlight( + id=1, + text="A useful idea", + note="Remember it", + location=7, + book_id=42, + highlighted_at=datetime(2025, 1, 2, 3, 4, tzinfo=UTC), + tags=[Tag(id=9, name="favorite")], + ) + groups = [("Book 42", [highlight])] if grouping is DigestGrouping.BOOK else [] + return DigestData( + title="Custom Digest", + highlights=[highlight], + grouping=grouping, + groups=groups, + ) + + +def test_markdown_presenter_preserves_exact_grouped_output() -> None: + assert render_digest(_digest(DigestGrouping.BOOK), DigestFormat.MARKDOWN) == ( + "# Custom Digest\n\n" + "*1 highlights*\n\n" + "## Book 42\n\n" + "> A useful idea\n\n" + "*Location: 7 | Note: Remember it | Tags: favorite*\n" + ) + + +def test_text_presenter_preserves_exact_ungrouped_output() -> None: + assert render_digest(_digest(DigestGrouping.NONE), DigestFormat.TEXT) == ( + "Custom Digest\n=============\n\n1 highlights\n\nA useful idea\nNote: Remember it\n" + ) + + +def test_json_presenter_preserves_fields_and_values() -> None: + data = json.loads(render_digest(_digest(DigestGrouping.NONE), DigestFormat.JSON)) + + assert data["title"] == "Custom Digest" + assert data["count"] == 1 + assert datetime.fromisoformat(data["generated_at"]).tzinfo is UTC + assert data["highlights"] == [ + { + "id": 1, + "text": "A useful idea", + "note": "Remember it", + "location": 7, + "book_id": 42, + "highlighted_at": "2025-01-02T03:04:00+00:00", + "tags": ["favorite"], + } + ] + + +def test_csv_presenter_preserves_exact_output() -> None: + assert render_digest(_digest(DigestGrouping.NONE), DigestFormat.CSV) == ( + "id,text,note,location,book_id,highlighted_at,tags\r\n" + "1,A useful idea,Remember it,7,42,2025-01-02T03:04:00+00:00,favorite\r\n" + ) diff --git a/tests/sdk/test_async.py b/tests/sdk/test_async.py index 72fcd1b..a6a40c4 100644 --- a/tests/sdk/test_async.py +++ b/tests/sdk/test_async.py @@ -5,7 +5,13 @@ import httpx import pytest -from readwise_sdk.operations import BookOperations, DocumentOperations, HighlightOperations +from readwise_sdk.operations import ( + BookOperations, + DigestOperations, + DocumentOperations, + HighlightOperations, + TagOperations, +) from readwise_sdk.v2.async_client import AsyncReadwiseV2Client from readwise_sdk.v3.async_client import AsyncReadwiseV3Client @@ -26,6 +32,8 @@ def test_async_readwise_constructs_canonical_operations() -> None: assert isinstance(readwise.documents, DocumentOperations) assert isinstance(readwise.highlights, HighlightOperations) assert isinstance(readwise.books, BookOperations) + assert isinstance(readwise.tags, TagOperations) + assert isinstance(readwise.digests, DigestOperations) assert ( readwise._client.api_key, readwise._client.timeout, @@ -34,7 +42,7 @@ def test_async_readwise_constructs_canonical_operations() -> None: ) == ("token", 12.5, 7, 1.25) -@pytest.mark.parametrize("name", ["documents", "highlights", "books"]) +@pytest.mark.parametrize("name", ["documents", "highlights", "books", "tags", "digests"]) def test_concept_attributes_delegate_to_the_canonical_service(name: str) -> None: """Each public concept attribute is the operation group owned by the service.""" from readwise_sdk import AsyncReadwise @@ -58,14 +66,12 @@ def test_raw_exposes_cached_versioned_clients_over_the_shared_client() -> None: assert readwise.raw.v3._client is readwise._client -def test_future_operation_groups_are_deferred() -> None: - """Facades do not imply canonical operation groups that do not exist yet.""" +def test_sync_operation_group_remains_deferred() -> None: + """Only synchronization remains deferred after tag and digest consolidation.""" from readwise_sdk import AsyncReadwise readwise = AsyncReadwise(api_key="token") - assert not hasattr(readwise, "tags") - assert not hasattr(readwise, "digests") assert not hasattr(readwise, "sync") diff --git a/tests/sdk/test_sync.py b/tests/sdk/test_sync.py index 5d1a8bd..167251d 100644 --- a/tests/sdk/test_sync.py +++ b/tests/sdk/test_sync.py @@ -246,14 +246,14 @@ def test_raw_retains_the_native_synchronous_compatibility_clients() -> None: assert readwise.raw.v3._client is readwise.raw._client -def test_sync_surface_matches_the_operation_groups_available_in_stage_nine() -> None: - """No later-stage tags, digests, or sync concepts are implied prematurely.""" +def test_sync_surface_exposes_stage_thirteen_operation_groups() -> None: + """Tags and digests are synchronous adapters while sync remains deferred.""" from readwise_sdk import Readwise readwise = Readwise(api_key="token") - assert not hasattr(readwise, "tags") - assert not hasattr(readwise, "digests") + assert readwise.tags is readwise.tags + assert readwise.digests is readwise.digests assert not hasattr(readwise, "sync") assert readwise.documents is readwise.documents assert readwise.highlights is readwise.highlights @@ -268,7 +268,13 @@ def test_sync_operation_groups_do_not_expose_async_streaming() -> None: readwise = Readwise(api_key="token") assert not hasattr(readwise.highlights, "filter") - for operation_group in (readwise.documents, readwise.highlights, readwise.books): + for operation_group in ( + readwise.documents, + readwise.highlights, + readwise.books, + readwise.tags, + readwise.digests, + ): assert not any( inspect.iscoroutinefunction(value) for name, value in vars(type(operation_group)).items() diff --git a/tests/test_cli_expansion.py b/tests/test_cli_expansion.py index 00b85ea..c16ebf2 100644 --- a/tests/test_cli_expansion.py +++ b/tests/test_cli_expansion.py @@ -3,6 +3,7 @@ from __future__ import annotations import json +from datetime import datetime from types import SimpleNamespace from typing import Any @@ -12,6 +13,7 @@ from readwise_sdk.cli.main import app from readwise_sdk.models import BulkResult +from readwise_sdk.operations.digests import DigestData, DigestGrouping from readwise_sdk.operations.highlights import HighlightCreateResult from readwise_sdk.v2.models import Highlight, HighlightColor from readwise_sdk.v3.models import ( @@ -328,3 +330,52 @@ def test_no_color_removes_ansi_codes_from_human_output( assert "Deleted document doc-1" in result.stdout assert "\x1b[" not in result.stdout assert "\x1b[" not in result.stderr + + +def test_digest_custom_calls_digest_operation_and_markdown_presenter( + monkeypatch: pytest.MonkeyPatch, +) -> None: + import readwise_sdk.cli.main as main + + class Digests: + def __init__(self) -> None: + self.calls: list[dict[str, object]] = [] + + async def custom(self, **kwargs: object) -> DigestData: + self.calls.append(kwargs) + highlight = Highlight(id=7, text="A custom highlight", book_id=42) + return DigestData( + title="Custom Digest", + highlights=[highlight], + grouping=DigestGrouping.NONE, + groups=[], + ) + + digests = Digests() + service = SimpleNamespace(digests=digests) + monkeypatch.setattr(main, "run_operation", _operation_runner(service)) + + result = runner.invoke( + app, + [ + "digest", + "custom", + "--since", + "2025-01-02T03:04:05", + "--book-id", + "42", + "--no-group-by-book", + ], + ) + + assert result.exit_code == 0, result.output + assert "# Custom Digest" in result.stdout + assert "A custom highlight" in result.stdout + assert digests.calls == [ + { + "since": datetime(2025, 1, 2, 3, 4, 5), + "book_id": 42, + "group_by_book": False, + "group_by_date": False, + } + ] From 3f1a692b7d2ca0795f4029bc32b466d383fae4d5 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 01:10:08 -0500 Subject: [PATCH 18/24] refactor: unify sync + persistence behind StateStore (stage 14) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Behavior-preserving. New operations/sync.py (full/incremental/poll-once/batch/ background scheduling) + state/ (StateStore protocol + JsonFileStateStore). SyncManager, BatchSync, and BackgroundPoller become shims delegating to the unified sync operation, preserving public methods, return types, callback (and exception-suppression) semantics, and — critically — the on-disk JSON formats (state-contract tests green). New writes carry a version field; migration readers load all legacy formats; malformed state is never silently reset. .sync exposed on both facades; new `sync status`/`sync reset` commands (existing sync full/incremental unchanged). Characterization unchanged; gate green (835 passed); uv.lock unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/cli/main.py | 57 ++ src/readwise_sdk/contrib/batch_sync.py | 489 +++++-------- src/readwise_sdk/managers/async_managers.py | 130 ++-- src/readwise_sdk/managers/sync.py | 126 ++-- src/readwise_sdk/operations/__init__.py | 3 + src/readwise_sdk/operations/service.py | 23 + src/readwise_sdk/operations/sync.py | 762 ++++++++++++++++++++ src/readwise_sdk/sdk/async_.py | 12 +- src/readwise_sdk/sdk/sync.py | 79 +- src/readwise_sdk/state/__init__.py | 6 + src/readwise_sdk/state/json_file.py | 101 +++ src/readwise_sdk/state/store.py | 38 + src/readwise_sdk/workflows/poller.py | 215 +++--- tests/operations/test_sync.py | 134 ++++ tests/sdk/test_async.py | 10 +- tests/sdk/test_sync.py | 7 +- tests/state/__init__.py | 1 + tests/state/test_json_file.py | 118 +++ tests/test_cli.py | 36 + 19 files changed, 1747 insertions(+), 600 deletions(-) create mode 100644 src/readwise_sdk/operations/sync.py create mode 100644 src/readwise_sdk/state/__init__.py create mode 100644 src/readwise_sdk/state/json_file.py create mode 100644 src/readwise_sdk/state/store.py create mode 100644 tests/operations/test_sync.py create mode 100644 tests/state/__init__.py create mode 100644 tests/state/test_json_file.py diff --git a/src/readwise_sdk/cli/main.py b/src/readwise_sdk/cli/main.py index 1384dd4..fc67f64 100644 --- a/src/readwise_sdk/cli/main.py +++ b/src/readwise_sdk/cli/main.py @@ -113,6 +113,63 @@ def sync_incremental( console.print(f" Total syncs: {manager.state.total_syncs}") +@sync_app.command("status") +def sync_status( + state_file: Annotated[ + str, + typer.Option(help="State file for persistence"), + ] = "sync_state.json", +) -> None: + """Show the current synchronization checkpoint.""" + from readwise_sdk.operations.sync import SyncOperations + from readwise_sdk.state import JsonFileStateStore + + checkpoint = SyncOperations(state_store=JsonFileStateStore(state_file)).status() + data = { + "last_highlight_sync": ( + checkpoint.last_highlight_sync.isoformat() + if checkpoint.last_highlight_sync is not None + else None + ), + "last_book_sync": ( + checkpoint.last_book_sync.isoformat() if checkpoint.last_book_sync is not None else None + ), + "last_document_sync": ( + checkpoint.last_document_sync.isoformat() + if checkpoint.last_document_sync is not None + else None + ), + "last_sync_time": ( + checkpoint.last_sync_time.isoformat() if checkpoint.last_sync_time is not None else None + ), + } + if current_output_format() is not OutputFormat.TABLE: + renderer().data(data) + return + + table = Table(title="Sync Status") + table.add_column("Checkpoint") + table.add_column("Timestamp") + for name, value in data.items(): + table.add_row(name.replace("_", " ").title(), value or "Never") + console.print(table) + + +@sync_app.command("reset") +def sync_reset( + state_file: Annotated[ + str, + typer.Option(help="State file for persistence"), + ] = "sync_state.json", +) -> None: + """Reset the synchronization checkpoint.""" + from readwise_sdk.operations.sync import SyncOperations + from readwise_sdk.state import JsonFileStateStore + + SyncOperations(state_store=JsonFileStateStore(state_file)).reset() + renderer().success("[green]Sync state reset.[/green]") + + # Digest commands @digest_app.command("daily") def digest_daily( diff --git a/src/readwise_sdk/contrib/batch_sync.py b/src/readwise_sdk/contrib/batch_sync.py index 91f1ba6..523cd32 100644 --- a/src/readwise_sdk/contrib/batch_sync.py +++ b/src/readwise_sdk/contrib/batch_sync.py @@ -28,13 +28,20 @@ def on_highlight(highlight): from __future__ import annotations -import json from dataclasses import dataclass, field from datetime import UTC, datetime from pathlib import Path -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, cast from readwise_sdk._utils import parse_datetime_string +from readwise_sdk.models import SyncCheckpoint +from readwise_sdk.operations.sync import ( + AsyncSyncClient, + BatchSyncOutcome, + SyncClient, + SyncOperations, +) +from readwise_sdk.state import JsonFileStateStore, MemoryStateStore from readwise_sdk.v2.models import Book, Highlight from readwise_sdk.v3.models import Document @@ -136,23 +143,24 @@ def __init__( self._client = client self._config = config or BatchSyncConfig() self._state_file = Path(self._config.state_file) if self._config.state_file else None + self._file_store = JsonFileStateStore(self._state_file) if self._state_file else None self._state = self._load_state() + self._checkpoint_store = MemoryStateStore(self._checkpoint()) + self._operation = SyncOperations( + sync_client=cast(SyncClient, self._client), + state_store=self._checkpoint_store, + ) def _load_state(self) -> SyncState: """Load state from file if it exists.""" - if self._state_file and self._state_file.exists(): - try: - data = json.loads(self._state_file.read_text()) - return SyncState.from_dict(data) - except Exception: - pass + if self._file_store is not None: + return self._file_store.load_legacy(SyncState.from_dict, SyncState) return SyncState() def _save_state(self) -> None: """Save state to file if configured.""" - if self._state_file: - self._state_file.parent.mkdir(parents=True, exist_ok=True) - self._state_file.write_text(json.dumps(self._state.to_dict(), indent=2)) + if self._file_store is not None: + self._file_store.save_legacy(self._state.to_dict()) @property def state(self) -> SyncState: @@ -176,53 +184,15 @@ def sync_highlights( Returns: BatchSyncResult with sync statistics. """ - now = datetime.now(UTC) - result = BatchSyncResult(success=True, sync_time=now) - - since = None if full_sync else self._state.last_highlight_sync - - batch: list[Highlight] = [] - - try: - for highlight in self._client.v2.list_highlights(updated_after=since): - try: - if on_item: - on_item(highlight) - - batch.append(highlight) - result.new_items += 1 - - # Process batch when full - if len(batch) >= self._config.batch_size: - if on_batch: - on_batch(batch) - batch = [] - - except Exception as e: - result.failed_items += 1 - error_msg = f"Error processing highlight {highlight.id}: {e}" - result.errors.append(error_msg) - self._state.errors.append(error_msg) - - if not self._config.continue_on_error: - result.success = False - break - - # Process remaining batch - if batch and on_batch: - on_batch(batch) - - # Update state - self._state.last_highlight_sync = now - self._state.total_highlights_synced += result.new_items - self._state.last_sync_time = now - self._save_state() - - except Exception as e: - result.success = False - result.errors.append(f"Sync failed: {e}") - - return result + self._checkpoint_store.save(self._checkpoint()) + outcome = self._operation.batch_highlights_sync( + on_item=on_item, + on_batch=on_batch, + batch_size=self._config.batch_size, + continue_on_error=self._config.continue_on_error, + full_sync=full_sync, + ) + return self._finish(outcome, "highlight") def sync_books( self, @@ -241,53 +211,15 @@ def sync_books( Returns: BatchSyncResult with sync statistics. """ - now = datetime.now(UTC) - result = BatchSyncResult(success=True, sync_time=now) - - since = None if full_sync else self._state.last_book_sync - - batch: list[Book] = [] - - try: - for book in self._client.v2.list_books(updated_after=since): - try: - if on_item: - on_item(book) - - batch.append(book) - result.new_items += 1 - - # Process batch when full - if len(batch) >= self._config.batch_size: - if on_batch: - on_batch(batch) - batch = [] - - except Exception as e: - result.failed_items += 1 - error_msg = f"Error processing book {book.id}: {e}" - result.errors.append(error_msg) - self._state.errors.append(error_msg) - - if not self._config.continue_on_error: - result.success = False - break - - # Process remaining batch - if batch and on_batch: - on_batch(batch) - - # Update state - self._state.last_book_sync = now - self._state.total_books_synced += result.new_items - self._state.last_sync_time = now - self._save_state() - - except Exception as e: - result.success = False - result.errors.append(f"Sync failed: {e}") - - return result + self._checkpoint_store.save(self._checkpoint()) + outcome = self._operation.batch_books_sync( + on_item=on_item, + on_batch=on_batch, + batch_size=self._config.batch_size, + continue_on_error=self._config.continue_on_error, + full_sync=full_sync, + ) + return self._finish(outcome, "book") def sync_documents( self, @@ -306,53 +238,15 @@ def sync_documents( Returns: BatchSyncResult with sync statistics. """ - now = datetime.now(UTC) - result = BatchSyncResult(success=True, sync_time=now) - - since = None if full_sync else self._state.last_document_sync - - batch: list[Document] = [] - - try: - for document in self._client.v3.list_documents(updated_after=since): - try: - if on_item: - on_item(document) - - batch.append(document) - result.new_items += 1 - - # Process batch when full - if len(batch) >= self._config.batch_size: - if on_batch: - on_batch(batch) - batch = [] - - except Exception as e: - result.failed_items += 1 - error_msg = f"Error processing document {document.id}: {e}" - result.errors.append(error_msg) - self._state.errors.append(error_msg) - - if not self._config.continue_on_error: - result.success = False - break - - # Process remaining batch - if batch and on_batch: - on_batch(batch) - - # Update state - self._state.last_document_sync = now - self._state.total_documents_synced += result.new_items - self._state.last_sync_time = now - self._save_state() - - except Exception as e: - result.success = False - result.errors.append(f"Sync failed: {e}") - - return result + self._checkpoint_store.save(self._checkpoint()) + outcome = self._operation.batch_documents_sync( + on_item=on_item, + on_batch=on_batch, + batch_size=self._config.batch_size, + continue_on_error=self._config.continue_on_error, + full_sync=full_sync, + ) + return self._finish(outcome, "document") def sync_all( self, @@ -381,6 +275,7 @@ def sync_all( def reset_state(self) -> None: """Reset sync state (next sync will be full sync).""" self._state = SyncState() + self._checkpoint_store.save(SyncCheckpoint()) self._save_state() def get_stats(self) -> dict: @@ -400,6 +295,45 @@ def get_stats(self) -> dict: "last_sync_time": self._state.last_sync_time, } + def _checkpoint(self) -> SyncCheckpoint: + return SyncCheckpoint( + last_highlight_sync=self._state.last_highlight_sync, + last_book_sync=self._state.last_book_sync, + last_document_sync=self._state.last_document_sync, + last_sync_time=self._state.last_sync_time, + ) + + def _finish( + self, + outcome: BatchSyncOutcome, + resource: str, + ) -> BatchSyncResult: + processing_errors = [ + error for error in outcome.errors if error.startswith("Error processing ") + ] + self._state.errors.extend(processing_errors) + if not any(error.startswith("Sync failed: ") for error in outcome.errors): + checkpoint = self._checkpoint_store.load() + self._state.last_sync_time = checkpoint.last_sync_time + if resource == "highlight": + self._state.last_highlight_sync = checkpoint.last_highlight_sync + self._state.total_highlights_synced += outcome.new_items + elif resource == "book": + self._state.last_book_sync = checkpoint.last_book_sync + self._state.total_books_synced += outcome.new_items + else: + self._state.last_document_sync = checkpoint.last_document_sync + self._state.total_documents_synced += outcome.new_items + self._save_state() + return BatchSyncResult( + success=outcome.success, + new_items=outcome.new_items, + updated_items=outcome.updated_items, + failed_items=outcome.failed_items, + errors=outcome.errors, + sync_time=outcome.sync_time, + ) + class AsyncBatchSync: """Async version of BatchSync for efficient batch synchronization. @@ -443,23 +377,24 @@ def __init__( self._client = client self._config = config or BatchSyncConfig() self._state_file = Path(self._config.state_file) if self._config.state_file else None + self._file_store = JsonFileStateStore(self._state_file) if self._state_file else None self._state = self._load_state() + self._checkpoint_store = MemoryStateStore(self._checkpoint()) + self._operation = SyncOperations( + async_client=cast(AsyncSyncClient, self._client), + state_store=self._checkpoint_store, + ) def _load_state(self) -> SyncState: """Load state from file if it exists.""" - if self._state_file and self._state_file.exists(): - try: - data = json.loads(self._state_file.read_text()) - return SyncState.from_dict(data) - except Exception: - pass + if self._file_store is not None: + return self._file_store.load_legacy(SyncState.from_dict, SyncState) return SyncState() def _save_state(self) -> None: """Save state to file if configured.""" - if self._state_file: - self._state_file.parent.mkdir(parents=True, exist_ok=True) - self._state_file.write_text(json.dumps(self._state.to_dict(), indent=2)) + if self._file_store is not None: + self._file_store.save_legacy(self._state.to_dict()) @property def state(self) -> SyncState: @@ -485,61 +420,15 @@ async def sync_highlights( Returns: BatchSyncResult with sync statistics. """ - import inspect - - now = datetime.now(UTC) - result = BatchSyncResult(success=True, sync_time=now) - - since = None if full_sync else self._state.last_highlight_sync - - batch: list[Highlight] = [] - - try: - async for highlight in self._client.v2.list_highlights(updated_after=since): - try: - if on_item: - cb_result = on_item(highlight) - if inspect.isawaitable(cb_result): - await cb_result - - batch.append(highlight) - result.new_items += 1 - - # Process batch when full - if len(batch) >= self._config.batch_size: - if on_batch: - batch_result = on_batch(batch) - if inspect.isawaitable(batch_result): - await batch_result - batch = [] - - except Exception as e: - result.failed_items += 1 - error_msg = f"Error processing highlight {highlight.id}: {e}" - result.errors.append(error_msg) - self._state.errors.append(error_msg) - - if not self._config.continue_on_error: - result.success = False - break - - # Process remaining batch - if batch and on_batch: - batch_result = on_batch(batch) - if inspect.isawaitable(batch_result): - await batch_result - - # Update state - self._state.last_highlight_sync = now - self._state.total_highlights_synced += result.new_items - self._state.last_sync_time = now - self._save_state() - - except Exception as e: - result.success = False - result.errors.append(f"Sync failed: {e}") - - return result + self._checkpoint_store.save(self._checkpoint()) + outcome = await self._operation.batch_highlights( + on_item=on_item, + on_batch=on_batch, + batch_size=self._config.batch_size, + continue_on_error=self._config.continue_on_error, + full_sync=full_sync, + ) + return self._finish(outcome, "highlight") async def sync_books( self, @@ -560,61 +449,15 @@ async def sync_books( Returns: BatchSyncResult with sync statistics. """ - import inspect - - now = datetime.now(UTC) - result = BatchSyncResult(success=True, sync_time=now) - - since = None if full_sync else self._state.last_book_sync - - batch: list[Book] = [] - - try: - async for book in self._client.v2.list_books(updated_after=since): - try: - if on_item: - cb_result = on_item(book) - if inspect.isawaitable(cb_result): - await cb_result - - batch.append(book) - result.new_items += 1 - - # Process batch when full - if len(batch) >= self._config.batch_size: - if on_batch: - batch_result = on_batch(batch) - if inspect.isawaitable(batch_result): - await batch_result - batch = [] - - except Exception as e: - result.failed_items += 1 - error_msg = f"Error processing book {book.id}: {e}" - result.errors.append(error_msg) - self._state.errors.append(error_msg) - - if not self._config.continue_on_error: - result.success = False - break - - # Process remaining batch - if batch and on_batch: - batch_result = on_batch(batch) - if inspect.isawaitable(batch_result): - await batch_result - - # Update state - self._state.last_book_sync = now - self._state.total_books_synced += result.new_items - self._state.last_sync_time = now - self._save_state() - - except Exception as e: - result.success = False - result.errors.append(f"Sync failed: {e}") - - return result + self._checkpoint_store.save(self._checkpoint()) + outcome = await self._operation.batch_books( + on_item=on_item, + on_batch=on_batch, + batch_size=self._config.batch_size, + continue_on_error=self._config.continue_on_error, + full_sync=full_sync, + ) + return self._finish(outcome, "book") async def sync_documents( self, @@ -635,61 +478,15 @@ async def sync_documents( Returns: BatchSyncResult with sync statistics. """ - import inspect - - now = datetime.now(UTC) - result = BatchSyncResult(success=True, sync_time=now) - - since = None if full_sync else self._state.last_document_sync - - batch: list[Document] = [] - - try: - async for document in self._client.v3.list_documents(updated_after=since): - try: - if on_item: - cb_result = on_item(document) - if inspect.isawaitable(cb_result): - await cb_result - - batch.append(document) - result.new_items += 1 - - # Process batch when full - if len(batch) >= self._config.batch_size: - if on_batch: - batch_result = on_batch(batch) - if inspect.isawaitable(batch_result): - await batch_result - batch = [] - - except Exception as e: - result.failed_items += 1 - error_msg = f"Error processing document {document.id}: {e}" - result.errors.append(error_msg) - self._state.errors.append(error_msg) - - if not self._config.continue_on_error: - result.success = False - break - - # Process remaining batch - if batch and on_batch: - batch_result = on_batch(batch) - if inspect.isawaitable(batch_result): - await batch_result - - # Update state - self._state.last_document_sync = now - self._state.total_documents_synced += result.new_items - self._state.last_sync_time = now - self._save_state() - - except Exception as e: - result.success = False - result.errors.append(f"Sync failed: {e}") - - return result + self._checkpoint_store.save(self._checkpoint()) + outcome = await self._operation.batch_documents( + on_item=on_item, + on_batch=on_batch, + batch_size=self._config.batch_size, + continue_on_error=self._config.continue_on_error, + full_sync=full_sync, + ) + return self._finish(outcome, "document") async def sync_all( self, @@ -722,6 +519,7 @@ async def sync_all( def reset_state(self) -> None: """Reset sync state (next sync will be full sync).""" self._state = SyncState() + self._checkpoint_store.save(SyncCheckpoint()) self._save_state() def get_stats(self) -> dict: @@ -740,3 +538,42 @@ def get_stats(self) -> dict: "error_count": len(self._state.errors), "last_sync_time": self._state.last_sync_time, } + + def _checkpoint(self) -> SyncCheckpoint: + return SyncCheckpoint( + last_highlight_sync=self._state.last_highlight_sync, + last_book_sync=self._state.last_book_sync, + last_document_sync=self._state.last_document_sync, + last_sync_time=self._state.last_sync_time, + ) + + def _finish( + self, + outcome: BatchSyncOutcome, + resource: str, + ) -> BatchSyncResult: + processing_errors = [ + error for error in outcome.errors if error.startswith("Error processing ") + ] + self._state.errors.extend(processing_errors) + if not any(error.startswith("Sync failed: ") for error in outcome.errors): + checkpoint = self._checkpoint_store.load() + self._state.last_sync_time = checkpoint.last_sync_time + if resource == "highlight": + self._state.last_highlight_sync = checkpoint.last_highlight_sync + self._state.total_highlights_synced += outcome.new_items + elif resource == "book": + self._state.last_book_sync = checkpoint.last_book_sync + self._state.total_books_synced += outcome.new_items + else: + self._state.last_document_sync = checkpoint.last_document_sync + self._state.total_documents_synced += outcome.new_items + self._save_state() + return BatchSyncResult( + success=outcome.success, + new_items=outcome.new_items, + updated_items=outcome.updated_items, + failed_items=outcome.failed_items, + errors=outcome.errors, + sync_time=outcome.sync_time, + ) diff --git a/src/readwise_sdk/managers/async_managers.py b/src/readwise_sdk/managers/async_managers.py index ee1279b..cf7f273 100644 --- a/src/readwise_sdk/managers/async_managers.py +++ b/src/readwise_sdk/managers/async_managers.py @@ -11,15 +11,18 @@ from __future__ import annotations -import json from collections import Counter from datetime import UTC, datetime, timedelta from pathlib import Path -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, cast from readwise_sdk.managers.books import BookWithHighlights, ReadingStats from readwise_sdk.managers.documents import InboxStats from readwise_sdk.managers.sync import SyncResult, SyncState +from readwise_sdk.models import SyncCheckpoint +from readwise_sdk.models import SyncResult as CanonicalSyncResult +from readwise_sdk.operations.sync import AsyncSyncClient, SyncOperations +from readwise_sdk.state import JsonFileStateStore, MemoryStateStore from readwise_sdk.v2.models import Book, BookCategory, Highlight, HighlightCreate from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation @@ -644,24 +647,25 @@ def __init__( """ self._client = client self._state_file = Path(state_file) if state_file else None + self._file_store = JsonFileStateStore(self._state_file) if self._state_file else None self._state = self._load_state() self._callbacks: list[Callable[[SyncResult], None]] = [] + self._checkpoint_store = MemoryStateStore(self._checkpoint()) + self._operation = SyncOperations( + async_client=cast(AsyncSyncClient, self._client), + state_store=self._checkpoint_store, + ) def _load_state(self) -> SyncState: """Load state from file if it exists.""" - if self._state_file and self._state_file.exists(): - try: - data = json.loads(self._state_file.read_text()) - return SyncState.from_dict(data) - except Exception: - pass + if self._file_store is not None: + return self._file_store.load_legacy(SyncState.from_dict, SyncState) return SyncState() def _save_state(self) -> None: """Save state to file if configured.""" - if self._state_file: - self._state_file.parent.mkdir(parents=True, exist_ok=True) - self._state_file.write_text(json.dumps(self._state.to_dict(), indent=2)) + if self._file_store is not None: + self._file_store.save_legacy(self._state.to_dict()) @property def state(self) -> SyncState: @@ -678,11 +682,7 @@ def on_sync(self, callback: Callable[[SyncResult], None]) -> None: def _notify_callbacks(self, result: SyncResult) -> None: """Notify all registered callbacks.""" - for callback in self._callbacks: - try: - callback(result) - except Exception: - pass + self._operation.notify_callbacks(self._callbacks, result) async def full_sync( self, @@ -701,27 +701,13 @@ async def full_sync( Returns: SyncResult with all synced data. """ - now = datetime.now(UTC) - result = SyncResult(sync_time=now) - - if include_highlights: - result.highlights = [h async for h in self._client.v2.list_highlights()] - self._state.last_highlight_sync = now - - if include_books: - result.books = [b async for b in self._client.v2.list_books()] - self._state.last_book_sync = now - - if include_documents: - result.documents = [d async for d in self._client.v3.list_documents()] - self._state.last_document_sync = now - - self._state.total_syncs += 1 - self._state.last_sync_time = now - self._save_state() - self._notify_callbacks(result) - - return result + self._checkpoint_store.save(self._checkpoint()) + canonical = await self._operation.full( + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + return self._finish(canonical) async def incremental_sync( self, @@ -740,43 +726,13 @@ async def incremental_sync( Returns: SyncResult with newly synced data. """ - now = datetime.now(UTC) - result = SyncResult(sync_time=now) - - if include_highlights: - since = self._state.last_highlight_sync - if since: - result.highlights = [ - h async for h in self._client.v2.list_highlights(updated_after=since) - ] - else: - result.highlights = [h async for h in self._client.v2.list_highlights()] - self._state.last_highlight_sync = now - - if include_books: - since = self._state.last_book_sync - if since: - result.books = [b async for b in self._client.v2.list_books(updated_after=since)] - else: - result.books = [b async for b in self._client.v2.list_books()] - self._state.last_book_sync = now - - if include_documents: - since = self._state.last_document_sync - if since: - result.documents = [ - d async for d in self._client.v3.list_documents(updated_after=since) - ] - else: - result.documents = [d async for d in self._client.v3.list_documents()] - self._state.last_document_sync = now - - self._state.total_syncs += 1 - self._state.last_sync_time = now - self._save_state() - self._notify_callbacks(result) - - return result + self._checkpoint_store.save(self._checkpoint()) + canonical = await self._operation.incremental( + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + return self._finish(canonical) async def sync_highlights_only(self) -> SyncResult: """Sync only highlights. @@ -797,4 +753,30 @@ async def sync_documents_only(self) -> SyncResult: def reset_state(self) -> None: """Reset the sync state (next sync will be full).""" self._state = SyncState() + self._checkpoint_store.save(SyncCheckpoint()) self._save_state() + + def _checkpoint(self) -> SyncCheckpoint: + return SyncCheckpoint( + last_highlight_sync=self._state.last_highlight_sync, + last_book_sync=self._state.last_book_sync, + last_document_sync=self._state.last_document_sync, + last_sync_time=self._state.last_sync_time, + ) + + def _finish(self, canonical: CanonicalSyncResult) -> SyncResult: + checkpoint = canonical.checkpoint + self._state.last_highlight_sync = checkpoint.last_highlight_sync + self._state.last_book_sync = checkpoint.last_book_sync + self._state.last_document_sync = checkpoint.last_document_sync + self._state.last_sync_time = checkpoint.last_sync_time + self._state.total_syncs += 1 + self._save_state() + result = SyncResult( + highlights=canonical.highlights, + books=canonical.books, + documents=canonical.documents, + sync_time=checkpoint.last_sync_time or datetime.now(UTC), + ) + self._notify_callbacks(result) + return result diff --git a/src/readwise_sdk/managers/sync.py b/src/readwise_sdk/managers/sync.py index 7468234..3d85b95 100644 --- a/src/readwise_sdk/managers/sync.py +++ b/src/readwise_sdk/managers/sync.py @@ -2,13 +2,16 @@ from __future__ import annotations -import json from dataclasses import dataclass, field from datetime import UTC, datetime from pathlib import Path -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, cast from readwise_sdk._utils import parse_datetime_string +from readwise_sdk.models import SyncCheckpoint +from readwise_sdk.models import SyncResult as CanonicalSyncResult +from readwise_sdk.operations.sync import SyncClient, SyncOperations +from readwise_sdk.state import JsonFileStateStore, MemoryStateStore from readwise_sdk.v2.models import Book, Highlight from readwise_sdk.v3.models import Document @@ -86,24 +89,25 @@ def __init__( """ self._client = client self._state_file = Path(state_file) if state_file else None + self._file_store = JsonFileStateStore(self._state_file) if self._state_file else None self._state = self._load_state() self._callbacks: list[Callable[[SyncResult], None]] = [] + self._checkpoint_store = MemoryStateStore(self._checkpoint()) + self._operation = SyncOperations( + sync_client=cast(SyncClient, self._client), + state_store=self._checkpoint_store, + ) def _load_state(self) -> SyncState: """Load state from file if it exists.""" - if self._state_file and self._state_file.exists(): - try: - data = json.loads(self._state_file.read_text()) - return SyncState.from_dict(data) - except Exception: - pass + if self._file_store is not None: + return self._file_store.load_legacy(SyncState.from_dict, SyncState) return SyncState() def _save_state(self) -> None: """Save state to file if configured.""" - if self._state_file: - self._state_file.parent.mkdir(parents=True, exist_ok=True) - self._state_file.write_text(json.dumps(self._state.to_dict(), indent=2)) + if self._file_store is not None: + self._file_store.save_legacy(self._state.to_dict()) @property def state(self) -> SyncState: @@ -120,11 +124,7 @@ def on_sync(self, callback: Callable[[SyncResult], None]) -> None: def _notify_callbacks(self, result: SyncResult) -> None: """Notify all registered callbacks.""" - for callback in self._callbacks: - try: - callback(result) - except Exception: - pass # Don't let callback errors break the sync + self._operation.notify_callbacks(self._callbacks, result) def full_sync( self, @@ -143,27 +143,13 @@ def full_sync( Returns: SyncResult with all synced data. """ - now = datetime.now(UTC) - result = SyncResult(sync_time=now) - - if include_highlights: - result.highlights = list(self._client.v2.list_highlights()) - self._state.last_highlight_sync = now - - if include_books: - result.books = list(self._client.v2.list_books()) - self._state.last_book_sync = now - - if include_documents: - result.documents = list(self._client.v3.list_documents()) - self._state.last_document_sync = now - - self._state.total_syncs += 1 - self._state.last_sync_time = now - self._save_state() - self._notify_callbacks(result) - - return result + self._checkpoint_store.save(self._checkpoint()) + canonical = self._operation.full_sync( + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + return self._finish(canonical) def incremental_sync( self, @@ -182,39 +168,13 @@ def incremental_sync( Returns: SyncResult with newly synced data. """ - now = datetime.now(UTC) - result = SyncResult(sync_time=now) - - if include_highlights: - since = self._state.last_highlight_sync - if since: - result.highlights = list(self._client.v2.list_highlights(updated_after=since)) - else: - result.highlights = list(self._client.v2.list_highlights()) - self._state.last_highlight_sync = now - - if include_books: - since = self._state.last_book_sync - if since: - result.books = list(self._client.v2.list_books(updated_after=since)) - else: - result.books = list(self._client.v2.list_books()) - self._state.last_book_sync = now - - if include_documents: - since = self._state.last_document_sync - if since: - result.documents = list(self._client.v3.list_documents(updated_after=since)) - else: - result.documents = list(self._client.v3.list_documents()) - self._state.last_document_sync = now - - self._state.total_syncs += 1 - self._state.last_sync_time = now - self._save_state() - self._notify_callbacks(result) - - return result + self._checkpoint_store.save(self._checkpoint()) + canonical = self._operation.incremental_sync( + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + return self._finish(canonical) def sync_highlights_only(self) -> SyncResult: """Sync only highlights. @@ -235,4 +195,30 @@ def sync_documents_only(self) -> SyncResult: def reset_state(self) -> None: """Reset the sync state (next sync will be full).""" self._state = SyncState() + self._checkpoint_store.save(SyncCheckpoint()) self._save_state() + + def _checkpoint(self) -> SyncCheckpoint: + return SyncCheckpoint( + last_highlight_sync=self._state.last_highlight_sync, + last_book_sync=self._state.last_book_sync, + last_document_sync=self._state.last_document_sync, + last_sync_time=self._state.last_sync_time, + ) + + def _finish(self, canonical: CanonicalSyncResult) -> SyncResult: + checkpoint = canonical.checkpoint + self._state.last_highlight_sync = checkpoint.last_highlight_sync + self._state.last_book_sync = checkpoint.last_book_sync + self._state.last_document_sync = checkpoint.last_document_sync + self._state.last_sync_time = checkpoint.last_sync_time + self._state.total_syncs += 1 + self._save_state() + result = SyncResult( + highlights=canonical.highlights, + books=canonical.books, + documents=canonical.documents, + sync_time=checkpoint.last_sync_time or datetime.now(UTC), + ) + self._notify_callbacks(result) + return result diff --git a/src/readwise_sdk/operations/__init__.py b/src/readwise_sdk/operations/__init__.py index 13d01b4..9dc761b 100644 --- a/src/readwise_sdk/operations/__init__.py +++ b/src/readwise_sdk/operations/__init__.py @@ -23,6 +23,7 @@ TruncationInfo, ) from readwise_sdk.operations.service import ReadwiseService +from readwise_sdk.operations.sync import BatchSyncOutcome, SyncOperations from readwise_sdk.operations.tags import ( TagCleanupResult, TagOperations, @@ -52,6 +53,8 @@ "HighlightUpdateResult", "ReadingStatistics", "ReadwiseService", + "BatchSyncOutcome", + "SyncOperations", "TagCleanupResult", "TagOperations", "TagPattern", diff --git a/src/readwise_sdk/operations/service.py b/src/readwise_sdk/operations/service.py index 1d61693..6962919 100644 --- a/src/readwise_sdk/operations/service.py +++ b/src/readwise_sdk/operations/service.py @@ -15,6 +15,16 @@ HighlightsResource, HighlightTagsResource, ) +from readwise_sdk.operations.sync import ( + AsyncBooksResource as SyncBooksResource, +) +from readwise_sdk.operations.sync import ( + AsyncDocumentsResource as SyncDocumentsResource, +) +from readwise_sdk.operations.sync import ( + AsyncHighlightsResource as SyncHighlightsResource, +) +from readwise_sdk.operations.sync import SyncOperations from readwise_sdk.operations.tags import ( HighlightTagsResource as TagMutationsResource, ) @@ -37,6 +47,9 @@ def __init__( tag_mutations: TagMutationsResource | None = None, digest_highlights: DigestHighlightsResource | None = None, digest_books: DigestBooksResource | None = None, + sync_highlights: SyncHighlightsResource | None = None, + sync_books: SyncBooksResource | None = None, + sync_documents: SyncDocumentsResource | None = None, ) -> None: self._documents = DocumentOperations(documents) if documents is not None else None self._highlights = ( @@ -60,6 +73,11 @@ def __init__( if digest_highlights is not None and digest_books is not None else None ) + self._sync = SyncOperations( + highlights=sync_highlights, + books=sync_books, + documents=sync_documents, + ) @property def documents(self) -> DocumentOperations: @@ -96,5 +114,10 @@ def digests(self) -> DigestOperations: raise RuntimeError("Digest operations were not configured") return self._digests + @property + def sync(self) -> SyncOperations: + """Return configured synchronization operations.""" + return self._sync + __all__ = ["ReadwiseService"] diff --git a/src/readwise_sdk/operations/sync.py b/src/readwise_sdk/operations/sync.py new file mode 100644 index 0000000..2823cdc --- /dev/null +++ b/src/readwise_sdk/operations/sync.py @@ -0,0 +1,762 @@ +"""Canonical synchronization, batching, polling, and scheduling behavior.""" + +from __future__ import annotations + +import inspect +import threading +from collections.abc import AsyncIterator, Callable, Iterator +from dataclasses import dataclass, field +from datetime import UTC, datetime +from typing import Any, Literal, Protocol, cast + +from readwise_sdk.models import SyncCheckpoint +from readwise_sdk.models.results import SyncResult +from readwise_sdk.state import MemoryStateStore, StateStore +from readwise_sdk.v2.models import Book, Highlight +from readwise_sdk.v3.models import Document + + +class AsyncHighlightsResource(Protocol): + """Highlight stream required by synchronization.""" + + def iter(self, *, updated_after: datetime | None = None) -> AsyncIterator[Highlight]: + """Yield highlights, optionally after a cursor.""" + ... + + +class AsyncBooksResource(Protocol): + """Book stream required by synchronization.""" + + def iter(self, *, updated_after: datetime | None = None) -> AsyncIterator[Book]: + """Yield books, optionally after a cursor.""" + ... + + +class AsyncDocumentsResource(Protocol): + """Document stream required by synchronization.""" + + def iter(self, *, updated_after: datetime | None = None) -> AsyncIterator[Document]: + """Yield documents, optionally after a cursor.""" + ... + + +class SyncV2Client(Protocol): + """Legacy synchronous v2 streams used by compatibility shims.""" + + def list_highlights( + self, *, updated_after: datetime | None = None, **kwargs: Any + ) -> Iterator[Highlight]: + """Yield highlights.""" + ... + + def list_books(self, *, updated_after: datetime | None = None, **kwargs: Any) -> Iterator[Book]: + """Yield books.""" + ... + + +class SyncV3Client(Protocol): + """Legacy synchronous v3 streams used by compatibility shims.""" + + def list_documents( + self, *, updated_after: datetime | None = None, **kwargs: Any + ) -> Iterator[Document]: + """Yield documents.""" + ... + + +class SyncClient(Protocol): + """Legacy synchronous client shape used at the operation seam.""" + + @property + def v2(self) -> SyncV2Client: + """Return v2 streams.""" + ... + + @property + def v3(self) -> SyncV3Client: + """Return v3 streams.""" + ... + + +class AsyncV2Client(Protocol): + """Legacy asynchronous v2 streams used by compatibility shims.""" + + def list_highlights( + self, *, updated_after: datetime | None = None, **kwargs: Any + ) -> AsyncIterator[Highlight]: + """Yield highlights.""" + ... + + def list_books( + self, *, updated_after: datetime | None = None, **kwargs: Any + ) -> AsyncIterator[Book]: + """Yield books.""" + ... + + +class AsyncV3Client(Protocol): + """Legacy asynchronous v3 streams used by compatibility shims.""" + + def list_documents( + self, *, updated_after: datetime | None = None, **kwargs: Any + ) -> AsyncIterator[Document]: + """Yield documents.""" + ... + + +class AsyncSyncClient(Protocol): + """Legacy asynchronous client shape used at the operation seam.""" + + @property + def v2(self) -> AsyncV2Client: + """Return v2 streams.""" + ... + + @property + def v3(self) -> AsyncV3Client: + """Return v3 streams.""" + ... + + +@dataclass +class BatchSyncOutcome: + """Statistics and errors from one resource batch synchronization.""" + + success: bool + new_items: int = 0 + updated_items: int = 0 + failed_items: int = 0 + errors: list[str] = field(default_factory=list) + sync_time: datetime = field(default_factory=lambda: datetime.now(UTC)) + + +class SyncOperations: + """Run every synchronization mode over shared checkpoint behavior.""" + + def __init__( + self, + *, + highlights: AsyncHighlightsResource | None = None, + books: AsyncBooksResource | None = None, + documents: AsyncDocumentsResource | None = None, + state_store: StateStore | None = None, + sync_client: SyncClient | None = None, + async_client: AsyncSyncClient | None = None, + ) -> None: + self._highlights = highlights + self._books = books + self._documents = documents + self._state_store = state_store or MemoryStateStore() + self._sync_client = sync_client + self._async_client = async_client + + def status(self) -> SyncCheckpoint: + """Return the current persisted checkpoint.""" + return self._state_store.load() + + def reset(self) -> None: + """Persist an empty checkpoint so the next incremental sync is full.""" + self._state_store.save(SyncCheckpoint()) + + async def full( + self, + *, + include_highlights: bool = True, + include_books: bool = True, + include_documents: bool = True, + ) -> SyncResult: + """Fetch complete streams and advance included resource cursors.""" + return await self._sync_async( + checkpoint=self._state_store.load(), + incremental=False, + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + + async def incremental( + self, + *, + include_highlights: bool = True, + include_books: bool = True, + include_documents: bool = True, + ) -> SyncResult: + """Fetch streams after the current resource-specific cursors.""" + return await self._sync_async( + checkpoint=self._state_store.load(), + incremental=True, + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + + async def poll_once( + self, + *, + include_highlights: bool = True, + include_documents: bool = True, + ) -> SyncResult: + """Poll once, coupling books to the highlight cursor as the legacy poller did.""" + checkpoint = self._state_store.load() + now = datetime.now(UTC) + highlights: list[Highlight] = [] + books: list[Book] = [] + documents: list[Document] = [] + updates: dict[str, datetime | None] = {"last_sync_time": now} + + if include_highlights: + since = checkpoint.last_highlight_sync + highlights = [item async for item in self._iter_highlights(since)] + books = [item async for item in self._iter_books(since)] + updates["last_highlight_sync"] = now + + if include_documents: + documents = [item async for item in self._iter_documents(checkpoint.last_document_sync)] + updates["last_document_sync"] = now + + next_checkpoint = checkpoint.model_copy(update=updates) + self._state_store.save(next_checkpoint) + return SyncResult( + highlights=highlights, + books=books, + documents=documents, + checkpoint=next_checkpoint, + ) + + async def batch_highlights( + self, + *, + on_item: Callable[[Highlight], object] | None = None, + on_batch: Callable[[list[Highlight]], object] | None = None, + batch_size: int = 100, + continue_on_error: bool = True, + full_sync: bool = False, + ) -> BatchSyncOutcome: + """Synchronize highlights with item and batch callbacks.""" + checkpoint = self._state_store.load() + return await self._batch_async( + self._iter_highlights( + None if full_sync else checkpoint.last_highlight_sync, + always_pass_cursor=True, + ), + resource_name="highlight", + on_item=on_item, + on_batch=on_batch, + batch_size=batch_size, + continue_on_error=continue_on_error, + checkpoint=checkpoint, + checkpoint_field="last_highlight_sync", + ) + + async def batch_books( + self, + *, + on_item: Callable[[Book], object] | None = None, + on_batch: Callable[[list[Book]], object] | None = None, + batch_size: int = 100, + continue_on_error: bool = True, + full_sync: bool = False, + ) -> BatchSyncOutcome: + """Synchronize books with item and batch callbacks.""" + checkpoint = self._state_store.load() + return await self._batch_async( + self._iter_books( + None if full_sync else checkpoint.last_book_sync, + always_pass_cursor=True, + ), + resource_name="book", + on_item=on_item, + on_batch=on_batch, + batch_size=batch_size, + continue_on_error=continue_on_error, + checkpoint=checkpoint, + checkpoint_field="last_book_sync", + ) + + async def batch_documents( + self, + *, + on_item: Callable[[Document], object] | None = None, + on_batch: Callable[[list[Document]], object] | None = None, + batch_size: int = 100, + continue_on_error: bool = True, + full_sync: bool = False, + ) -> BatchSyncOutcome: + """Synchronize documents with item and batch callbacks.""" + checkpoint = self._state_store.load() + return await self._batch_async( + self._iter_documents( + None if full_sync else checkpoint.last_document_sync, + always_pass_cursor=True, + ), + resource_name="document", + on_item=on_item, + on_batch=on_batch, + batch_size=batch_size, + continue_on_error=continue_on_error, + checkpoint=checkpoint, + checkpoint_field="last_document_sync", + ) + + def full_sync( + self, + *, + include_highlights: bool = True, + include_books: bool = True, + include_documents: bool = True, + ) -> SyncResult: + """Native synchronous full sync used by compatibility adapters.""" + return self._sync_native( + checkpoint=self._state_store.load(), + incremental=False, + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + + def incremental_sync( + self, + *, + include_highlights: bool = True, + include_books: bool = True, + include_documents: bool = True, + ) -> SyncResult: + """Native synchronous incremental sync used by compatibility adapters.""" + return self._sync_native( + checkpoint=self._state_store.load(), + incremental=True, + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + + def poll_once_sync( + self, + *, + include_highlights: bool = True, + include_documents: bool = True, + ) -> SyncResult: + """Native synchronous poll-once behavior used by BackgroundPoller.""" + client = self._require(self._sync_client, "synchronous client") + checkpoint = self._state_store.load() + now = datetime.now(UTC) + highlights: list[Highlight] = [] + books: list[Book] = [] + documents: list[Document] = [] + updates: dict[str, datetime | None] = {"last_sync_time": now} + + if include_highlights: + since = checkpoint.last_highlight_sync + if since is None: + highlights = list(client.v2.list_highlights()) + books = list(client.v2.list_books()) + else: + highlights = list(client.v2.list_highlights(updated_after=since)) + books = list(client.v2.list_books(updated_after=since)) + updates["last_highlight_sync"] = now + if include_documents: + since = checkpoint.last_document_sync + if since is None: + documents = list(client.v3.list_documents()) + else: + documents = list(client.v3.list_documents(updated_after=since)) + updates["last_document_sync"] = now + + next_checkpoint = checkpoint.model_copy(update=updates) + self._state_store.save(next_checkpoint) + return SyncResult( + highlights=highlights, + books=books, + documents=documents, + checkpoint=next_checkpoint, + ) + + def batch_highlights_sync( + self, + *, + on_item: Callable[[Highlight], None] | None = None, + on_batch: Callable[[list[Highlight]], None] | None = None, + batch_size: int = 100, + continue_on_error: bool = True, + full_sync: bool = False, + ) -> BatchSyncOutcome: + """Native synchronous highlight batching for BatchSync.""" + client = self._require(self._sync_client, "synchronous client") + checkpoint = self._state_store.load() + return self._batch_native( + client.v2.list_highlights( + updated_after=None if full_sync else checkpoint.last_highlight_sync + ), + resource_name="highlight", + on_item=on_item, + on_batch=on_batch, + batch_size=batch_size, + continue_on_error=continue_on_error, + checkpoint=checkpoint, + checkpoint_field="last_highlight_sync", + ) + + def batch_books_sync( + self, + *, + on_item: Callable[[Book], None] | None = None, + on_batch: Callable[[list[Book]], None] | None = None, + batch_size: int = 100, + continue_on_error: bool = True, + full_sync: bool = False, + ) -> BatchSyncOutcome: + """Native synchronous book batching for BatchSync.""" + client = self._require(self._sync_client, "synchronous client") + checkpoint = self._state_store.load() + return self._batch_native( + client.v2.list_books(updated_after=None if full_sync else checkpoint.last_book_sync), + resource_name="book", + on_item=on_item, + on_batch=on_batch, + batch_size=batch_size, + continue_on_error=continue_on_error, + checkpoint=checkpoint, + checkpoint_field="last_book_sync", + ) + + def batch_documents_sync( + self, + *, + on_item: Callable[[Document], None] | None = None, + on_batch: Callable[[list[Document]], None] | None = None, + batch_size: int = 100, + continue_on_error: bool = True, + full_sync: bool = False, + ) -> BatchSyncOutcome: + """Native synchronous document batching for BatchSync.""" + client = self._require(self._sync_client, "synchronous client") + checkpoint = self._state_store.load() + return self._batch_native( + client.v3.list_documents( + updated_after=None if full_sync else checkpoint.last_document_sync + ), + resource_name="document", + on_item=on_item, + on_batch=on_batch, + batch_size=batch_size, + continue_on_error=continue_on_error, + checkpoint=checkpoint, + checkpoint_field="last_document_sync", + ) + + @staticmethod + def notify_callbacks[ValueT]( + callbacks: list[Callable[[ValueT], None]], + value: ValueT, + ) -> None: + """Invoke every callback while suppressing each callback exception.""" + for callback in callbacks: + try: + callback(value) + except Exception: + pass + + async def _sync_async( + self, + *, + checkpoint: SyncCheckpoint, + incremental: bool, + include_highlights: bool, + include_books: bool, + include_documents: bool, + ) -> SyncResult: + now = datetime.now(UTC) + highlights: list[Highlight] = [] + books: list[Book] = [] + documents: list[Document] = [] + updates: dict[str, datetime | None] = {"last_sync_time": now} + + if include_highlights: + since = checkpoint.last_highlight_sync if incremental else None + highlights = [item async for item in self._iter_highlights(since)] + updates["last_highlight_sync"] = now + if include_books: + since = checkpoint.last_book_sync if incremental else None + books = [item async for item in self._iter_books(since)] + updates["last_book_sync"] = now + if include_documents: + since = checkpoint.last_document_sync if incremental else None + documents = [item async for item in self._iter_documents(since)] + updates["last_document_sync"] = now + + next_checkpoint = checkpoint.model_copy(update=updates) + self._state_store.save(next_checkpoint) + return SyncResult( + highlights=highlights, + books=books, + documents=documents, + checkpoint=next_checkpoint, + ) + + def _sync_native( + self, + *, + checkpoint: SyncCheckpoint, + incremental: bool, + include_highlights: bool, + include_books: bool, + include_documents: bool, + ) -> SyncResult: + client = self._require(self._sync_client, "synchronous client") + now = datetime.now(UTC) + highlights: list[Highlight] = [] + books: list[Book] = [] + documents: list[Document] = [] + updates: dict[str, datetime | None] = {"last_sync_time": now} + + if include_highlights: + since = checkpoint.last_highlight_sync if incremental else None + if since is None: + highlights = list(client.v2.list_highlights()) + else: + highlights = list(client.v2.list_highlights(updated_after=since)) + updates["last_highlight_sync"] = now + if include_books: + since = checkpoint.last_book_sync if incremental else None + if since is None: + books = list(client.v2.list_books()) + else: + books = list(client.v2.list_books(updated_after=since)) + updates["last_book_sync"] = now + if include_documents: + since = checkpoint.last_document_sync if incremental else None + if since is None: + documents = list(client.v3.list_documents()) + else: + documents = list(client.v3.list_documents(updated_after=since)) + updates["last_document_sync"] = now + + next_checkpoint = checkpoint.model_copy(update=updates) + self._state_store.save(next_checkpoint) + return SyncResult( + highlights=highlights, + books=books, + documents=documents, + checkpoint=next_checkpoint, + ) + + async def _batch_async[ItemT]( + self, + items: AsyncIterator[ItemT], + *, + resource_name: str, + on_item: Callable[[ItemT], object] | None, + on_batch: Callable[[list[ItemT]], object] | None, + batch_size: int, + continue_on_error: bool, + checkpoint: SyncCheckpoint, + checkpoint_field: Literal["last_highlight_sync", "last_book_sync", "last_document_sync"], + ) -> BatchSyncOutcome: + now = datetime.now(UTC) + result = BatchSyncOutcome(success=True, sync_time=now) + batch: list[ItemT] = [] + try: + async for item in items: + try: + if on_item is not None: + callback_result = on_item(item) + if inspect.isawaitable(callback_result): + await callback_result + batch.append(item) + result.new_items += 1 + if len(batch) >= batch_size: + if on_batch is not None: + batch_result = on_batch(batch) + if inspect.isawaitable(batch_result): + await batch_result + batch = [] + except Exception as error: + result.failed_items += 1 + result.errors.append( + f"Error processing {resource_name} {cast(Any, item).id}: {error}" + ) + if not continue_on_error: + result.success = False + break + if batch and on_batch is not None: + batch_result = on_batch(batch) + if inspect.isawaitable(batch_result): + await batch_result + next_checkpoint = checkpoint.model_copy( + update={checkpoint_field: now, "last_sync_time": now} + ) + self._state_store.save(next_checkpoint) + except Exception as error: + result.success = False + result.errors.append(f"Sync failed: {error}") + return result + + def _batch_native[ItemT]( + self, + items: Iterator[ItemT], + *, + resource_name: str, + on_item: Callable[[ItemT], None] | None, + on_batch: Callable[[list[ItemT]], None] | None, + batch_size: int, + continue_on_error: bool, + checkpoint: SyncCheckpoint, + checkpoint_field: Literal["last_highlight_sync", "last_book_sync", "last_document_sync"], + ) -> BatchSyncOutcome: + now = datetime.now(UTC) + result = BatchSyncOutcome(success=True, sync_time=now) + batch: list[ItemT] = [] + try: + for item in items: + try: + if on_item is not None: + on_item(item) + batch.append(item) + result.new_items += 1 + if len(batch) >= batch_size: + if on_batch is not None: + on_batch(batch) + batch = [] + except Exception as error: + result.failed_items += 1 + result.errors.append( + f"Error processing {resource_name} {cast(Any, item).id}: {error}" + ) + if not continue_on_error: + result.success = False + break + if batch and on_batch is not None: + on_batch(batch) + next_checkpoint = checkpoint.model_copy( + update={checkpoint_field: now, "last_sync_time": now} + ) + self._state_store.save(next_checkpoint) + except Exception as error: + result.success = False + result.errors.append(f"Sync failed: {error}") + return result + + @staticmethod + def _require[ValueT](value: ValueT | None, name: str) -> ValueT: + if value is None: + raise RuntimeError(f"{name.capitalize()} synchronization was not configured") + return value + + def _iter_highlights( + self, + updated_after: datetime | None, + *, + always_pass_cursor: bool = False, + ) -> AsyncIterator[Highlight]: + if self._highlights is not None: + return self._highlights.iter(updated_after=updated_after) + client = self._require(self._async_client, "highlight") + if updated_after is None and not always_pass_cursor: + return client.v2.list_highlights() + return client.v2.list_highlights(updated_after=updated_after) + + def _iter_books( + self, + updated_after: datetime | None, + *, + always_pass_cursor: bool = False, + ) -> AsyncIterator[Book]: + if self._books is not None: + return self._books.iter(updated_after=updated_after) + client = self._require(self._async_client, "book") + if updated_after is None and not always_pass_cursor: + return client.v2.list_books() + return client.v2.list_books(updated_after=updated_after) + + def _iter_documents( + self, + updated_after: datetime | None, + *, + always_pass_cursor: bool = False, + ) -> AsyncIterator[Document]: + if self._documents is not None: + return self._documents.iter(updated_after=updated_after) + client = self._require(self._async_client, "document") + if updated_after is None and not always_pass_cursor: + return client.v3.list_documents() + return client.v3.list_documents(updated_after=updated_after) + + +class BackgroundSyncScheduler: + """Run a synchronous poll callback repeatedly with legacy backoff semantics.""" + + def __init__( + self, + poll: Callable[[], object], + *, + poll_interval: int, + max_consecutive_errors: int, + backoff_multiplier: float, + max_backoff: int, + on_success: Callable[[object], None], + on_error: Callable[[Exception], None], + on_running_change: Callable[[bool], None], + ) -> None: + self._poll = poll + self._poll_interval = poll_interval + self._max_consecutive_errors = max_consecutive_errors + self._backoff_multiplier = backoff_multiplier + self._max_backoff = max_backoff + self._on_success = on_success + self._on_error = on_error + self._on_running_change = on_running_change + self.stop_event = threading.Event() + self.thread: threading.Thread | None = None + self.consecutive_errors = 0 + self.current_backoff: float = poll_interval + + def run(self) -> None: + """Poll until stopped or the consecutive error limit is reached.""" + while not self.stop_event.is_set(): + try: + result = self._poll() + self.consecutive_errors = 0 + self.current_backoff = self._poll_interval + self._on_success(result) + except Exception as error: + self.consecutive_errors += 1 + self.current_backoff = min( + self.current_backoff * self._backoff_multiplier, + self._max_backoff, + ) + self._on_error(error) + if self.consecutive_errors >= self._max_consecutive_errors: + self._on_running_change(False) + return + wait_time = self.current_backoff if self.consecutive_errors > 0 else self._poll_interval + self.stop_event.wait(wait_time) + self._on_running_change(False) + + def start(self, *, blocking: bool = False) -> None: + """Start in the current thread or a daemon background thread.""" + self.stop_event.clear() + self._on_running_change(True) + if blocking: + self.run() + else: + self.thread = threading.Thread(target=self.run, daemon=True) + self.thread.start() + + def stop(self, *, timeout: float | None = None) -> None: + """Request shutdown and join a running background thread.""" + self.stop_event.set() + if self.thread and self.thread.is_alive(): + self.thread.join(timeout=timeout) + self._on_running_change(False) + + def reset_errors(self) -> None: + """Reset consecutive errors and the current backoff.""" + self.consecutive_errors = 0 + self.current_backoff = self._poll_interval + + +__all__ = [ + "BackgroundSyncScheduler", + "BatchSyncOutcome", + "SyncOperations", +] diff --git a/src/readwise_sdk/sdk/async_.py b/src/readwise_sdk/sdk/async_.py index ffc39c1..9ff6c36 100644 --- a/src/readwise_sdk/sdk/async_.py +++ b/src/readwise_sdk/sdk/async_.py @@ -12,6 +12,7 @@ DocumentOperations, HighlightOperations, ReadwiseService, + SyncOperations, TagOperations, ) from readwise_sdk.resources.v2 import ( @@ -76,8 +77,9 @@ def __init__( highlights = AsyncHighlightsResource(transport) tags = AsyncTagsResource(transport) books = AsyncBooksResource(transport) + documents = AsyncDocumentsResource(transport) self._service = ReadwiseService( - documents=AsyncDocumentsResource(transport), + documents=documents, highlights=highlights, highlight_tags=tags, export=AsyncExportResource(transport), @@ -87,6 +89,9 @@ def __init__( tag_mutations=tags, digest_highlights=highlights, digest_books=books, + sync_highlights=highlights, + sync_books=books, + sync_documents=documents, ) self._raw = _AsyncRawClients(self._client) @@ -115,7 +120,10 @@ def digests(self) -> DigestOperations: """Return canonical Readwise digest data operations.""" return self._service.digests - # sync remains deferred until stage 14. + @property + def sync(self) -> SyncOperations: + """Return canonical synchronization operations.""" + return self._service.sync @property def raw(self) -> _AsyncRawClients: diff --git a/src/readwise_sdk/sdk/sync.py b/src/readwise_sdk/sdk/sync.py index b008a29..cd2612a 100644 --- a/src/readwise_sdk/sdk/sync.py +++ b/src/readwise_sdk/sdk/sync.py @@ -14,7 +14,14 @@ from readwise_sdk.client import ReadwiseClient from readwise_sdk.config import DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF, DEFAULT_TIMEOUT -from readwise_sdk.models import BookSearch, BulkResult, DocumentSearch, DocumentSearchResult +from readwise_sdk.models import ( + BookSearch, + BulkResult, + DocumentSearch, + DocumentSearchResult, + SyncCheckpoint, + SyncResult, +) from readwise_sdk.models.queries import HighlightSearch from readwise_sdk.operations import ( BookSearchResult, @@ -33,6 +40,7 @@ TagPattern, TagReport, ) +from readwise_sdk.operations.sync import BatchSyncOutcome, SyncOperations from readwise_sdk.sdk.async_ import AsyncReadwise from readwise_sdk.v2.models import Book, BookCategory, Highlight, HighlightCreate, HighlightUpdate from readwise_sdk.v3.models import ( @@ -488,6 +496,69 @@ def custom( ) +class _SyncSyncOperations(_SyncOperationGroup): + """Synchronous adapter for canonical synchronization operations.""" + + def __init__(self, owner: Readwise, operations: SyncOperations) -> None: + super().__init__(owner) + self._operations = operations + + def full( + self, + *, + include_highlights: bool = True, + include_books: bool = True, + include_documents: bool = True, + ) -> SyncResult: + return self._call( + self._operations.full, + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + + def incremental( + self, + *, + include_highlights: bool = True, + include_books: bool = True, + include_documents: bool = True, + ) -> SyncResult: + return self._call( + self._operations.incremental, + include_highlights=include_highlights, + include_books=include_books, + include_documents=include_documents, + ) + + def poll_once( + self, + *, + include_highlights: bool = True, + include_documents: bool = True, + ) -> SyncResult: + return self._call( + self._operations.poll_once, + include_highlights=include_highlights, + include_documents=include_documents, + ) + + def batch_highlights(self, **kwargs: Any) -> BatchSyncOutcome: + return self._call(self._operations.batch_highlights, **kwargs) + + def batch_books(self, **kwargs: Any) -> BatchSyncOutcome: + return self._call(self._operations.batch_books, **kwargs) + + def batch_documents(self, **kwargs: Any) -> BatchSyncOutcome: + return self._call(self._operations.batch_documents, **kwargs) + + def status(self) -> SyncCheckpoint: + return self._operations.status() + + def reset(self) -> None: + self._operations.reset() + + class Readwise: """Concept-oriented synchronous Readwise SDK. @@ -524,6 +595,7 @@ def __init__( self._books = _SyncBookOperations(self, self._async.books) self._tags = _SyncTagOperations(self, self._async.tags) self._digests = _SyncDigestOperations(self, self._async.digests) + self._sync = _SyncSyncOperations(self, self._async.sync) self._portal: BlockingPortal | None = None self._portal_context: AbstractContextManager[BlockingPortal] | None = None self._lifecycle_lock = Lock() @@ -553,7 +625,10 @@ def digests(self) -> _SyncDigestOperations: """Return synchronous canonical digest data operations.""" return self._digests - # sync mirrors AsyncReadwise by remaining deferred until stage 14. + @property + def sync(self) -> _SyncSyncOperations: + """Return synchronous canonical synchronization operations.""" + return self._sync @property def raw(self) -> _SyncRawClients: diff --git a/src/readwise_sdk/state/__init__.py b/src/readwise_sdk/state/__init__.py new file mode 100644 index 0000000..461b739 --- /dev/null +++ b/src/readwise_sdk/state/__init__.py @@ -0,0 +1,6 @@ +"""Synchronization checkpoint persistence.""" + +from readwise_sdk.state.json_file import JsonFileStateStore +from readwise_sdk.state.store import MemoryStateStore, StateStore + +__all__ = ["JsonFileStateStore", "MemoryStateStore", "StateStore"] diff --git a/src/readwise_sdk/state/json_file.py b/src/readwise_sdk/state/json_file.py new file mode 100644 index 0000000..e5db754 --- /dev/null +++ b/src/readwise_sdk/state/json_file.py @@ -0,0 +1,101 @@ +"""JSON file persistence for synchronization checkpoints.""" + +from __future__ import annotations + +import json +from collections.abc import Callable, Mapping +from pathlib import Path +from typing import Any + +from pydantic import ValidationError + +from readwise_sdk.models import SyncCheckpoint + +STATE_VERSION = 1 + +_CHECKPOINT_KEYS = { + "last_highlight_sync", + "last_book_sync", + "last_document_sync", + "last_sync_time", +} +_SYNC_MANAGER_KEYS = {"total_syncs"} +_BATCH_SYNC_KEYS = { + "total_highlights_synced", + "total_books_synced", + "total_documents_synced", + "errors", +} +_POLLER_KEYS = {"last_poll_time", "poll_count", "error_count", "last_error"} +_LEGACY_KEYS = _CHECKPOINT_KEYS | _SYNC_MANAGER_KEYS | _BATCH_SYNC_KEYS | _POLLER_KEYS + + +class JsonFileStateStore: + """Persist versioned checkpoints and migrate every existing JSON schema.""" + + def __init__(self, path: Path | str) -> None: + self.path = Path(path) + + def load(self) -> SyncCheckpoint: + """Load canonical or recognized legacy state without masking bad files.""" + if not self.path.exists(): + return SyncCheckpoint() + + try: + data = json.loads(self.path.read_text()) + except (OSError, json.JSONDecodeError) as error: + raise ValueError(f"Unable to load sync state from {self.path}") from error + + if not isinstance(data, dict): + raise ValueError(f"Unknown sync state schema in {self.path}") + + version = data.get("version") + if version is not None: + if type(version) is not int or version != STATE_VERSION: + raise ValueError(f"Unknown sync state version {version!r} in {self.path}") + elif not (_LEGACY_KEYS & data.keys()): + raise ValueError(f"Unknown sync state schema in {self.path}") + + checkpoint_data = {key: data.get(key) for key in _CHECKPOINT_KEYS} + if "last_poll_time" in data and checkpoint_data["last_sync_time"] is None: + checkpoint_data["last_sync_time"] = data.get("last_poll_time") + + try: + return SyncCheckpoint.model_validate(checkpoint_data) + except ValidationError as error: + raise ValueError(f"Invalid sync checkpoint in {self.path}") from error + + def save(self, checkpoint: SyncCheckpoint) -> None: + """Write the canonical versioned JSON schema with legacy ISO formatting.""" + data: dict[str, object] = {"version": STATE_VERSION} + for key in _CHECKPOINT_KEYS: + value = getattr(checkpoint, key) + data[key] = value.isoformat() if value is not None else None + self._write(data) + + def load_legacy[StateT]( + self, + factory: Callable[[dict[str, Any]], StateT], + default: Callable[[], StateT], + ) -> StateT: + """Load a compatibility state using its historical error suppression.""" + if self.path.exists(): + try: + data = json.loads(self.path.read_text()) + if not isinstance(data, dict): + return default() + return factory(data) + except Exception: + pass + return default() + + def save_legacy(self, data: Mapping[str, object]) -> None: + """Write an unversioned compatibility schema exactly as supplied.""" + self._write(data) + + def _write(self, data: Mapping[str, object]) -> None: + self.path.parent.mkdir(parents=True, exist_ok=True) + self.path.write_text(json.dumps(dict(data), indent=2)) + + +__all__ = ["JsonFileStateStore", "STATE_VERSION"] diff --git a/src/readwise_sdk/state/store.py b/src/readwise_sdk/state/store.py new file mode 100644 index 0000000..dc1a424 --- /dev/null +++ b/src/readwise_sdk/state/store.py @@ -0,0 +1,38 @@ +"""Persistence contract for synchronization checkpoints.""" + +from __future__ import annotations + +from typing import Protocol, runtime_checkable + +from readwise_sdk.models import SyncCheckpoint + + +@runtime_checkable +class StateStore(Protocol): + """Load and save the checkpoint used by synchronization operations.""" + + def load(self) -> SyncCheckpoint: + """Return the persisted checkpoint, or an empty checkpoint when absent.""" + ... + + def save(self, checkpoint: SyncCheckpoint) -> None: + """Persist a checkpoint.""" + ... + + +class MemoryStateStore: + """Keep a synchronization checkpoint in memory.""" + + def __init__(self, checkpoint: SyncCheckpoint | None = None) -> None: + self._checkpoint = checkpoint or SyncCheckpoint() + + def load(self) -> SyncCheckpoint: + """Return the current in-memory checkpoint.""" + return self._checkpoint + + def save(self, checkpoint: SyncCheckpoint) -> None: + """Replace the current in-memory checkpoint.""" + self._checkpoint = checkpoint + + +__all__ = ["MemoryStateStore", "StateStore"] diff --git a/src/readwise_sdk/workflows/poller.py b/src/readwise_sdk/workflows/poller.py index 6a40fa1..a4fa63d 100644 --- a/src/readwise_sdk/workflows/poller.py +++ b/src/readwise_sdk/workflows/poller.py @@ -2,16 +2,22 @@ from __future__ import annotations -import json import signal -import threading from dataclasses import dataclass from datetime import UTC, datetime from pathlib import Path -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, cast from readwise_sdk._utils import parse_datetime_string from readwise_sdk.managers.sync import SyncResult +from readwise_sdk.models import SyncCheckpoint +from readwise_sdk.models import SyncResult as CanonicalSyncResult +from readwise_sdk.operations.sync import ( + BackgroundSyncScheduler, + SyncClient, + SyncOperations, +) +from readwise_sdk.state import JsonFileStateStore, MemoryStateStore if TYPE_CHECKING: from collections.abc import Callable @@ -89,30 +95,39 @@ def __init__( """ self._client = client self._config = config or PollerConfig() + self._file_store = ( + JsonFileStateStore(self._config.state_file) if self._config.state_file else None + ) self._state = self._load_state() self._callbacks: list[Callable[[SyncResult], None]] = [] self._error_callbacks: list[Callable[[Exception], None]] = [] - self._stop_event = threading.Event() - self._thread: threading.Thread | None = None - self._consecutive_errors = 0 - self._current_backoff = self._config.poll_interval - self._lock = threading.Lock() + self._checkpoint_store = MemoryStateStore(self._checkpoint()) + self._operation = SyncOperations( + sync_client=cast(SyncClient, self._client), + state_store=self._checkpoint_store, + ) + self._scheduler = BackgroundSyncScheduler( + self._do_poll, + poll_interval=self._config.poll_interval, + max_consecutive_errors=self._config.max_consecutive_errors, + backoff_multiplier=self._config.backoff_multiplier, + max_backoff=self._config.max_backoff, + on_success=self._handle_poll_success, + on_error=self._handle_poll_error, + on_running_change=self._set_running, + ) + self._stop_event = self._scheduler.stop_event def _load_state(self) -> PollerState: """Load state from file if it exists.""" - if self._config.state_file and self._config.state_file.exists(): - try: - data = json.loads(self._config.state_file.read_text()) - return PollerState.from_dict(data) - except Exception: - pass + if self._file_store is not None: + return self._file_store.load_legacy(PollerState.from_dict, PollerState) return PollerState() def _save_state(self) -> None: """Save state to file if configured.""" - if self._config.state_file: - self._config.state_file.parent.mkdir(parents=True, exist_ok=True) - self._config.state_file.write_text(json.dumps(self._state.to_dict(), indent=2)) + if self._file_store is not None: + self._file_store.save_legacy(self._state.to_dict()) @property def state(self) -> PollerState: @@ -142,98 +157,27 @@ def on_error(self, callback: Callable[[Exception], None]) -> None: def _notify_callbacks(self, result: SyncResult) -> None: """Notify all registered callbacks.""" - for callback in self._callbacks: - try: - callback(result) - except Exception: - pass + self._operation.notify_callbacks(self._callbacks, result) def _notify_error_callbacks(self, error: Exception) -> None: """Notify all error callbacks.""" - for callback in self._error_callbacks: - try: - callback(error) - except Exception: - pass + self._operation.notify_callbacks(self._error_callbacks, error) def _do_poll(self) -> SyncResult: """Perform a single poll operation.""" - from readwise_sdk.managers.sync import SyncResult as SR - - now = datetime.now(UTC) - result = SR(sync_time=now) - - if self._config.include_highlights: - since = self._state.last_highlight_sync - if since: - result.highlights = list(self._client.v2.list_highlights(updated_after=since)) - else: - result.highlights = list(self._client.v2.list_highlights()) - - # Also fetch books if we're fetching highlights - if since: - result.books = list(self._client.v2.list_books(updated_after=since)) - else: - result.books = list(self._client.v2.list_books()) - - self._state.last_highlight_sync = now - - if self._config.include_documents: - since = self._state.last_document_sync - if since: - result.documents = list(self._client.v3.list_documents(updated_after=since)) - else: - result.documents = list(self._client.v3.list_documents()) - self._state.last_document_sync = now - - return result + self._checkpoint_store.save(self._checkpoint()) + canonical = self._operation.poll_once_sync( + include_highlights=self._config.include_highlights, + include_documents=self._config.include_documents, + ) + checkpoint = canonical.checkpoint + self._state.last_highlight_sync = checkpoint.last_highlight_sync + self._state.last_document_sync = checkpoint.last_document_sync + return self._legacy_result(canonical) def _poll_loop(self) -> None: """Main polling loop.""" - while not self._stop_event.is_set(): - try: - result = self._do_poll() - - with self._lock: - self._state.last_poll_time = datetime.now(UTC) - self._state.poll_count += 1 - self._consecutive_errors = 0 - self._current_backoff = self._config.poll_interval - - self._save_state() - self._notify_callbacks(result) - - except Exception as e: - with self._lock: - self._state.error_count += 1 - self._state.last_error = str(e) - self._consecutive_errors += 1 - - # Calculate backoff - self._current_backoff = min( - self._current_backoff * self._config.backoff_multiplier, - self._config.max_backoff, - ) - - self._save_state() - self._notify_error_callbacks(e) - - # Check if we should stop due to too many errors - if self._consecutive_errors >= self._config.max_consecutive_errors: - self._state.is_running = False - self._save_state() - return - - # Wait for next poll or stop event - wait_time = ( - self._current_backoff - if self._consecutive_errors > 0 - else self._config.poll_interval - ) - self._stop_event.wait(wait_time) - - self._state.is_running = False - self._save_state() + self._scheduler.run() def start(self, *, blocking: bool = False) -> None: """Start the background poller. @@ -244,16 +188,7 @@ def start(self, *, blocking: bool = False) -> None: """ if self._state.is_running: return - - self._stop_event.clear() - self._state.is_running = True - self._save_state() - - if blocking: - self._poll_loop() - else: - self._thread = threading.Thread(target=self._poll_loop, daemon=True) - self._thread.start() + self._scheduler.start(blocking=blocking) def stop(self, *, timeout: float | None = None) -> None: """Stop the background poller. @@ -261,11 +196,7 @@ def stop(self, *, timeout: float | None = None) -> None: Args: timeout: Maximum time to wait for the poller to stop. """ - self._stop_event.set() - if self._thread and self._thread.is_alive(): - self._thread.join(timeout=timeout) - self._state.is_running = False - self._save_state() + self._scheduler.stop(timeout=timeout) def poll_once(self) -> SyncResult: """Perform a single poll operation (for manual triggering). @@ -282,10 +213,8 @@ def poll_once(self) -> SyncResult: def reset_errors(self) -> None: """Reset the error count and backoff.""" - with self._lock: - self._consecutive_errors = 0 - self._current_backoff = self._config.poll_interval - self._state.last_error = None + self._scheduler.reset_errors() + self._state.last_error = None self._save_state() def setup_signal_handlers(self) -> None: @@ -299,3 +228,51 @@ def handler(signum: int, frame: object) -> None: signal.signal(signal.SIGINT, handler) signal.signal(signal.SIGTERM, handler) + + @property + def _consecutive_errors(self) -> int: + return self._scheduler.consecutive_errors + + @_consecutive_errors.setter + def _consecutive_errors(self, value: int) -> None: + self._scheduler.consecutive_errors = value + + @property + def _current_backoff(self) -> float: + return self._scheduler.current_backoff + + @_current_backoff.setter + def _current_backoff(self, value: float) -> None: + self._scheduler.current_backoff = value + + def _checkpoint(self) -> SyncCheckpoint: + return SyncCheckpoint( + last_highlight_sync=self._state.last_highlight_sync, + last_document_sync=self._state.last_document_sync, + last_sync_time=self._state.last_poll_time, + ) + + @staticmethod + def _legacy_result(canonical: CanonicalSyncResult) -> SyncResult: + return SyncResult( + highlights=canonical.highlights, + books=canonical.books, + documents=canonical.documents, + sync_time=canonical.checkpoint.last_sync_time or datetime.now(UTC), + ) + + def _handle_poll_success(self, result: object) -> None: + self._state.last_poll_time = datetime.now(UTC) + self._state.poll_count += 1 + self._save_state() + self._notify_callbacks(cast(SyncResult, result)) + + def _handle_poll_error(self, error: Exception) -> None: + self._state.error_count += 1 + self._state.last_error = str(error) + self._save_state() + self._notify_error_callbacks(error) + + def _set_running(self, is_running: bool) -> None: + self._state.is_running = is_running + self._save_state() diff --git a/tests/operations/test_sync.py b/tests/operations/test_sync.py new file mode 100644 index 0000000..181a3c9 --- /dev/null +++ b/tests/operations/test_sync.py @@ -0,0 +1,134 @@ +"""Tests for canonical synchronization operations.""" + +from __future__ import annotations + +from collections.abc import AsyncIterator +from datetime import UTC, datetime +from typing import Any + +import pytest + +from readwise_sdk.models import SyncCheckpoint +from readwise_sdk.operations.sync import SyncOperations +from readwise_sdk.state import JsonFileStateStore +from readwise_sdk.v2.models import Book, Highlight +from readwise_sdk.v3.models import Document + +STAMP = datetime(2025, 2, 3, 4, 5, 6, tzinfo=UTC) + + +class FakeAsyncResource[ItemT]: + """Record incremental cursors while yielding fixed items.""" + + def __init__(self, items: list[ItemT]) -> None: + self.items = items + self.updated_after_calls: list[datetime | None] = [] + + async def iter(self, **kwargs: Any) -> AsyncIterator[ItemT]: + self.updated_after_calls.append(kwargs.get("updated_after")) + for item in self.items: + yield item + + +@pytest.mark.asyncio +async def test_full_sync_fetches_all_resources_and_persists_checkpoint(tmp_path) -> None: + """A full sync materializes all resource streams through one operation.""" + highlights = FakeAsyncResource([Highlight(id=1, text="Passage")]) + books = FakeAsyncResource([Book(id=2, title="Book")]) + documents = FakeAsyncResource([Document(id="doc-1", url="https://example.com")]) + store = JsonFileStateStore(tmp_path / "checkpoint.json") + sync = SyncOperations( + highlights=highlights, + books=books, + documents=documents, + state_store=store, + ) + + result = await sync.full() + + assert [item.id for item in result.highlights] == [1] + assert [item.id for item in result.books] == [2] + assert [item.id for item in result.documents] == ["doc-1"] + assert highlights.updated_after_calls == [None] + assert books.updated_after_calls == [None] + assert documents.updated_after_calls == [None] + assert store.load() == result.checkpoint + + +@pytest.mark.asyncio +async def test_incremental_sync_uses_each_saved_resource_cursor(tmp_path) -> None: + """Incremental sync reads the checkpoint and advances only included resources.""" + store = JsonFileStateStore(tmp_path / "checkpoint.json") + store.save( + SyncCheckpoint( + last_highlight_sync=STAMP, + last_book_sync=STAMP, + last_document_sync=STAMP, + last_sync_time=STAMP, + ) + ) + highlights: FakeAsyncResource[Highlight] = FakeAsyncResource([]) + books: FakeAsyncResource[Book] = FakeAsyncResource([]) + documents: FakeAsyncResource[Document] = FakeAsyncResource([]) + sync = SyncOperations( + highlights=highlights, + books=books, + documents=documents, + state_store=store, + ) + + result = await sync.incremental(include_books=False) + + assert highlights.updated_after_calls == [STAMP] + assert books.updated_after_calls == [] + assert documents.updated_after_calls == [STAMP] + assert result.checkpoint.last_book_sync == STAMP + assert result.checkpoint.last_highlight_sync is not None + assert result.checkpoint.last_document_sync is not None + assert result.checkpoint.last_highlight_sync > STAMP + assert result.checkpoint.last_document_sync > STAMP + + +@pytest.mark.asyncio +async def test_poll_once_fetches_books_with_the_highlight_cursor(tmp_path) -> None: + """Poll-once retains the poller's coupled highlight/book incremental behavior.""" + store = JsonFileStateStore(tmp_path / "checkpoint.json") + store.save(SyncCheckpoint(last_highlight_sync=STAMP, last_document_sync=STAMP)) + highlights: FakeAsyncResource[Highlight] = FakeAsyncResource([]) + books: FakeAsyncResource[Book] = FakeAsyncResource([]) + documents: FakeAsyncResource[Document] = FakeAsyncResource([]) + sync = SyncOperations( + highlights=highlights, + books=books, + documents=documents, + state_store=store, + ) + + await sync.poll_once() + + assert highlights.updated_after_calls == [STAMP] + assert books.updated_after_calls == [STAMP] + assert documents.updated_after_calls == [STAMP] + + +@pytest.mark.asyncio +async def test_batch_callbacks_preserve_continue_on_error_semantics() -> None: + """Item callback failures are counted and later items continue when configured.""" + highlights = FakeAsyncResource( + [Highlight(id=1, text="one"), Highlight(id=2, text="two"), Highlight(id=3, text="three")] + ) + sync = SyncOperations(highlights=highlights) + received: list[int] = [] + + async def on_item(highlight: Highlight) -> None: + received.append(highlight.id) + if highlight.id == 2: + raise RuntimeError("callback failed") + + result = await sync.batch_highlights(on_item=on_item, continue_on_error=True) + + assert received == [1, 2, 3] + assert result.success is True + assert result.new_items == 2 + assert result.failed_items == 1 + assert result.errors == ["Error processing highlight 2: callback failed"] diff --git a/tests/sdk/test_async.py b/tests/sdk/test_async.py index a6a40c4..5ff48a2 100644 --- a/tests/sdk/test_async.py +++ b/tests/sdk/test_async.py @@ -10,6 +10,7 @@ DigestOperations, DocumentOperations, HighlightOperations, + SyncOperations, TagOperations, ) from readwise_sdk.v2.async_client import AsyncReadwiseV2Client @@ -34,6 +35,7 @@ def test_async_readwise_constructs_canonical_operations() -> None: assert isinstance(readwise.books, BookOperations) assert isinstance(readwise.tags, TagOperations) assert isinstance(readwise.digests, DigestOperations) + assert isinstance(readwise.sync, SyncOperations) assert ( readwise._client.api_key, readwise._client.timeout, @@ -42,7 +44,7 @@ def test_async_readwise_constructs_canonical_operations() -> None: ) == ("token", 12.5, 7, 1.25) -@pytest.mark.parametrize("name", ["documents", "highlights", "books", "tags", "digests"]) +@pytest.mark.parametrize("name", ["documents", "highlights", "books", "tags", "digests", "sync"]) def test_concept_attributes_delegate_to_the_canonical_service(name: str) -> None: """Each public concept attribute is the operation group owned by the service.""" from readwise_sdk import AsyncReadwise @@ -66,13 +68,13 @@ def test_raw_exposes_cached_versioned_clients_over_the_shared_client() -> None: assert readwise.raw.v3._client is readwise._client -def test_sync_operation_group_remains_deferred() -> None: - """Only synchronization remains deferred after tag and digest consolidation.""" +def test_sync_operation_group_is_exposed() -> None: + """Synchronization is available from the preferred asynchronous facade.""" from readwise_sdk import AsyncReadwise readwise = AsyncReadwise(api_key="token") - assert not hasattr(readwise, "sync") + assert isinstance(readwise.sync, SyncOperations) @pytest.mark.asyncio diff --git a/tests/sdk/test_sync.py b/tests/sdk/test_sync.py index 167251d..b9c6688 100644 --- a/tests/sdk/test_sync.py +++ b/tests/sdk/test_sync.py @@ -246,15 +246,15 @@ def test_raw_retains_the_native_synchronous_compatibility_clients() -> None: assert readwise.raw.v3._client is readwise.raw._client -def test_sync_surface_exposes_stage_thirteen_operation_groups() -> None: - """Tags and digests are synchronous adapters while sync remains deferred.""" +def test_sync_surface_exposes_stage_fourteen_operation_groups() -> None: + """The synchronous facade exposes synchronization with the other groups.""" from readwise_sdk import Readwise readwise = Readwise(api_key="token") assert readwise.tags is readwise.tags assert readwise.digests is readwise.digests - assert not hasattr(readwise, "sync") + assert readwise.sync is readwise.sync assert readwise.documents is readwise.documents assert readwise.highlights is readwise.highlights assert readwise.books is readwise.books @@ -274,6 +274,7 @@ def test_sync_operation_groups_do_not_expose_async_streaming() -> None: readwise.books, readwise.tags, readwise.digests, + readwise.sync, ): assert not any( inspect.iscoroutinefunction(value) diff --git a/tests/state/__init__.py b/tests/state/__init__.py new file mode 100644 index 0000000..950713e --- /dev/null +++ b/tests/state/__init__.py @@ -0,0 +1 @@ +"""Tests for synchronization state stores.""" diff --git a/tests/state/test_json_file.py b/tests/state/test_json_file.py new file mode 100644 index 0000000..8fd642a --- /dev/null +++ b/tests/state/test_json_file.py @@ -0,0 +1,118 @@ +"""Tests for the canonical JSON synchronization state store.""" + +from __future__ import annotations + +import json +from datetime import UTC, datetime + +import pytest + +from readwise_sdk.models import SyncCheckpoint +from readwise_sdk.state import JsonFileStateStore, StateStore + +STAMP = datetime(2025, 2, 3, 4, 5, 6, tzinfo=UTC) + + +def test_json_file_state_store_writes_a_versioned_checkpoint(tmp_path) -> None: + """New canonical writes are versioned without changing ISO formatting.""" + path = tmp_path / "checkpoint.json" + store = JsonFileStateStore(path) + checkpoint = SyncCheckpoint( + last_highlight_sync=STAMP, + last_book_sync=None, + last_document_sync=STAMP, + last_sync_time=STAMP, + ) + + store.save(checkpoint) + + assert isinstance(store, StateStore) + assert json.loads(path.read_text()) == { + "version": 1, + "last_highlight_sync": "2025-02-03T04:05:06+00:00", + "last_book_sync": None, + "last_document_sync": "2025-02-03T04:05:06+00:00", + "last_sync_time": "2025-02-03T04:05:06+00:00", + } + assert store.load() == checkpoint + + +@pytest.mark.parametrize( + ("legacy_state", "expected"), + [ + pytest.param( + { + "last_highlight_sync": STAMP.isoformat(), + "last_book_sync": None, + "last_document_sync": STAMP.isoformat(), + "total_syncs": 7, + "last_sync_time": STAMP.isoformat(), + }, + SyncCheckpoint( + last_highlight_sync=STAMP, + last_document_sync=STAMP, + last_sync_time=STAMP, + ), + id="sync-manager", + ), + pytest.param( + { + "last_highlight_sync": STAMP.isoformat(), + "last_book_sync": STAMP.isoformat(), + "last_document_sync": None, + "total_highlights_synced": 11, + "total_books_synced": 12, + "total_documents_synced": 13, + "last_sync_time": STAMP.isoformat(), + "errors": ["first"], + }, + SyncCheckpoint( + last_highlight_sync=STAMP, + last_book_sync=STAMP, + last_sync_time=STAMP, + ), + id="batch-sync", + ), + pytest.param( + { + "last_poll_time": STAMP.isoformat(), + "last_highlight_sync": STAMP.isoformat(), + "last_document_sync": None, + "poll_count": 9, + "error_count": 2, + "last_error": "boom", + }, + SyncCheckpoint(last_highlight_sync=STAMP, last_sync_time=STAMP), + id="background-poller", + ), + ], +) +def test_json_file_state_store_loads_each_legacy_schema( + tmp_path, + legacy_state: dict[str, object], + expected: SyncCheckpoint, +) -> None: + """Every current persisted schema migrates to one checkpoint model.""" + path = tmp_path / "legacy.json" + path.write_text(json.dumps(legacy_state)) + + assert JsonFileStateStore(path).load() == expected + + +@pytest.mark.parametrize( + "contents", + [ + pytest.param("not valid json {{{", id="malformed-json"), + pytest.param('{"version": 999}', id="unknown-version"), + pytest.param('{"unrecognized": true}', id="unknown-schema"), + ], +) +def test_json_file_state_store_rejects_and_preserves_bad_state(tmp_path, contents: str) -> None: + """Malformed or unknown state is never silently reset or overwritten while loading.""" + path = tmp_path / "bad.json" + path.write_text(contents) + + with pytest.raises(ValueError): + JsonFileStateStore(path).load() + + assert path.read_text() == contents diff --git a/tests/test_cli.py b/tests/test_cli.py index 653498d..e1f3f3e 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -631,6 +631,42 @@ def test_sync_incremental_with_state_file(self, tmp_path) -> None: state_data = json.loads(state_file.read_text()) assert state_data["total_syncs"] == 1 + def test_sync_status_reads_a_legacy_state_file(self, tmp_path) -> None: + """sync status reports checkpoints from existing unversioned state.""" + state_file = tmp_path / "sync.json" + state_file.write_text( + json.dumps( + { + "last_highlight_sync": "2025-02-03T04:05:06+00:00", + "last_book_sync": None, + "last_document_sync": None, + "total_syncs": 7, + "last_sync_time": "2025-02-03T04:05:06+00:00", + } + ) + ) + + result = runner.invoke(app, ["sync", "status", "--state-file", str(state_file)]) + + assert result.exit_code == 0 + assert "2025-02-03T04:05:06+00:00" in result.output + + def test_sync_reset_writes_new_versioned_state(self, tmp_path) -> None: + """sync reset clears the checkpoint through the canonical state store.""" + state_file = tmp_path / "sync.json" + + result = runner.invoke(app, ["sync", "reset", "--state-file", str(state_file)]) + + assert result.exit_code == 0 + assert "Sync state reset" in result.output + assert json.loads(state_file.read_text()) == { + "version": 1, + "last_highlight_sync": None, + "last_book_sync": None, + "last_document_sync": None, + "last_sync_time": None, + } + # --------------------------------------------------------------------------- # Digest commands From e7bb8ca7f69aa6ed0de6cda3c196a9d6c6057b62 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 01:27:11 -0500 Subject: [PATCH 19/24] refactor: managers/contrib/workflows delegate to operations; delete duplication (stage 15) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Behavior-preserving. HighlightManager/BookManager/DocumentManager, async_managers, HighlightPusher, DocumentImporter, and ReadingInbox now delegate to the operations layer; ~1,770 net lines of duplicated legacy implementation (incl. the ~800-line parallel async manager copy) deleted. Legacy return shapes preserved exactly — lists, lazy iterators, dict[id,bool], dataclasses, None, formatted output, broad exception suppression, and partial-failure behavior (BulkResult converted back to legacy boolean maps). No direct .v2/.v3 calls remain in these layers. Manager/contrib/async + characterization tests pass UNCHANGED; gate green (835 passed); uv.lock unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/contrib/document_import.py | 548 +++---------- src/readwise_sdk/contrib/highlight_push.py | 803 ++++---------------- src/readwise_sdk/managers/async_managers.py | 614 +++------------ src/readwise_sdk/managers/books.py | 168 +--- src/readwise_sdk/managers/documents.py | 235 +----- src/readwise_sdk/managers/highlights.py | 178 +---- src/readwise_sdk/operations/auth.py | 22 + src/readwise_sdk/operations/compat.py | 276 +++++++ src/readwise_sdk/operations/documents.py | 58 +- src/readwise_sdk/operations/imports.py | 210 +++++ src/readwise_sdk/operations/inbox.py | 180 +++++ src/readwise_sdk/workflows/inbox.py | 332 ++------ 12 files changed, 1270 insertions(+), 2354 deletions(-) create mode 100644 src/readwise_sdk/operations/auth.py create mode 100644 src/readwise_sdk/operations/compat.py create mode 100644 src/readwise_sdk/operations/imports.py create mode 100644 src/readwise_sdk/operations/inbox.py diff --git a/src/readwise_sdk/contrib/document_import.py b/src/readwise_sdk/contrib/document_import.py index 9ee3768..997e792 100644 --- a/src/readwise_sdk/contrib/document_import.py +++ b/src/readwise_sdk/contrib/document_import.py @@ -1,51 +1,30 @@ -"""Document importing interface with metadata extraction. - -Designed for sane_reader and similar projects that need to pull documents -FROM Readwise Reader with extracted metadata. - -Example: - from readwise_sdk import ReadwiseClient - from readwise_sdk.contrib import DocumentImporter - - client = ReadwiseClient() - importer = DocumentImporter(client) - - # Import a single document with full content - doc = importer.import_document("doc_id_here", with_content=True) - print(f"Title: {doc.title}") - print(f"Clean text: {doc.clean_text[:200]}...") - print(f"Domain: {doc.domain}") - print(f"Reading time: {doc.reading_time_minutes} mins") - - # Import multiple documents - results = importer.import_batch(["doc1", "doc2", "doc3"]) - for result in results: - if result.success: - print(f"Imported: {result.document.title}") -""" +"""Legacy Reader document-import compatibility shims.""" from __future__ import annotations -import re from dataclasses import dataclass from datetime import datetime -from typing import TYPE_CHECKING -from urllib.parse import urlparse - +from typing import TYPE_CHECKING, Any + +from readwise_sdk.operations.compat import AsyncDocumentsResource, SyncDocumentsResource, run_sync +from readwise_sdk.operations.imports import ( + DocumentImportOperations, + DocumentImportResult, + ImportedDocumentData, + extract_domain, + html_to_text, + import_document_data, +) from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation if TYPE_CHECKING: from readwise_sdk.client import AsyncReadwiseClient, ReadwiseClient -# Average reading speed (words per minute) WORDS_PER_MINUTE = 200 @dataclass class ImportedDocument: - """A document imported from Readwise Reader with extracted metadata.""" - - # Core fields from Document id: str url: str title: str | None @@ -55,19 +34,13 @@ class ImportedDocument: tags: list[str] created_at: datetime | None updated_at: datetime | None - - # Content html_content: str | None = None clean_text: str | None = None - - # Extracted metadata domain: str | None = None word_count: int | None = None reading_time_minutes: int | None = None summary: str | None = None image_url: str | None = None - - # Reading progress reading_progress: float | None = None first_opened_at: datetime | None = None last_opened_at: datetime | None = None @@ -80,49 +53,17 @@ def from_document( extract_metadata: bool = True, clean_html: bool = True, ) -> ImportedDocument: - """Create from a Document with optional metadata extraction.""" - imported = cls( - id=doc.id, - url=doc.url, - title=doc.title, - author=doc.author, - category=doc.category, - location=doc.location, - tags=doc.tags, - created_at=doc.created_at, - updated_at=doc.updated_at, - html_content=doc.content, - summary=doc.summary, - image_url=doc.image_url, - reading_progress=doc.reading_progress, - first_opened_at=doc.first_opened_at, - last_opened_at=doc.last_opened_at, - word_count=doc.word_count, - reading_time_minutes=doc.reading_time, + return _legacy_document( + import_document_data( + doc, + extract_metadata=extract_metadata, + clean_html=clean_html, + ) ) - # Extract domain from URL - if extract_metadata and doc.url: - imported.domain = _extract_domain(doc.url) - - # Clean HTML to text - if clean_html and doc.content: - imported.clean_text = _html_to_text(doc.content) - - # Calculate word count and reading time if not provided - if extract_metadata and imported.clean_text: - if imported.word_count is None: - imported.word_count = len(imported.clean_text.split()) - if imported.reading_time_minutes is None and imported.word_count: - imported.reading_time_minutes = max(1, imported.word_count // WORDS_PER_MINUTE) - - return imported - @dataclass class ImportResult: - """Result of importing a document.""" - success: bool document: ImportedDocument | None = None document_id: str | None = None @@ -130,67 +71,48 @@ class ImportResult: def _extract_domain(url: str) -> str | None: - """Extract domain from URL.""" - try: - parsed = urlparse(url) - domain = parsed.netloc - # Remove www. prefix - if domain.startswith("www."): - domain = domain[4:] - return domain or None - except Exception: - return None + return extract_domain(url) def _html_to_text(html: str) -> str: - """Convert HTML to clean text. - - Uses regex-based extraction for simplicity (no BeautifulSoup dependency). - For more robust extraction, install beautifulsoup4. - """ - try: - # Try to use BeautifulSoup if available - from bs4 import BeautifulSoup # type: ignore[import-not-found] - - soup = BeautifulSoup(html, "html.parser") - - # Remove script and style elements - for script in soup(["script", "style", "nav", "footer", "header"]): - script.decompose() - - text = soup.get_text(separator=" ", strip=True) - except ImportError: - # Fallback to regex-based extraction - # Remove script and style blocks - text = re.sub(r"]*>.*?", "", html, flags=re.DOTALL | re.I) - text = re.sub(r"]*>.*?", "", text, flags=re.DOTALL | re.I) - - # Remove HTML tags - text = re.sub(r"<[^>]+>", " ", text) - - # Decode common HTML entities - text = text.replace(" ", " ") - text = text.replace("&", "&") - text = text.replace("<", "<") - text = text.replace(">", ">") - text = text.replace(""", '"') - text = text.replace("'", "'") - - # Collapse whitespace - text = re.sub(r"\s+", " ", text).strip() - - return text + return html_to_text(html) + + +def _legacy_document(document: ImportedDocumentData) -> ImportedDocument: + return ImportedDocument( + id=document.id, + url=document.url, + title=document.title, + author=document.author, + category=document.category, + location=document.location, + tags=document.tags, + created_at=document.created_at, + updated_at=document.updated_at, + html_content=document.html_content, + clean_text=document.clean_text, + domain=document.domain, + word_count=document.word_count, + reading_time_minutes=document.reading_time_minutes, + summary=document.summary, + image_url=document.image_url, + reading_progress=document.reading_progress, + first_opened_at=document.first_opened_at, + last_opened_at=document.last_opened_at, + ) + + +def _legacy_result(result: DocumentImportResult) -> ImportResult: + return ImportResult( + success=result.success, + document=_legacy_document(result.document) if result.document is not None else None, + document_id=result.document_id, + error=str(result.error) if result.error is not None else None, + ) class DocumentImporter: - """Interface for importing documents from Readwise Reader. - - Provides: - - Automatic HTML to text conversion - - Metadata extraction (domain, word count, reading time) - - Batch operations with individual error handling - - Rate limit aware operations - """ + """Synchronous compatibility wrapper over document import operations.""" def __init__( self, @@ -199,16 +121,14 @@ def __init__( extract_metadata: bool = True, clean_html: bool = True, ) -> None: - """Initialize the document importer. - - Args: - client: The Readwise client. - extract_metadata: Extract domain, word count, etc. - clean_html: Convert HTML content to clean text. - """ self._client = client self._extract_metadata = extract_metadata self._clean_html = clean_html + self._operations = DocumentImportOperations( + SyncDocumentsResource(client), + extract_metadata=extract_metadata, + clean_html=clean_html, + ) def import_document( self, @@ -216,25 +136,8 @@ def import_document( *, with_content: bool = True, ) -> ImportedDocument: - """Import a single document with optional content. - - Args: - document_id: The document ID. - with_content: Whether to fetch HTML content. - - Returns: - ImportedDocument with extracted metadata. - - Raises: - NotFoundError: If the document doesn't exist. - """ - doc = self._client.v3.get_document(document_id, with_content=with_content) - if doc is None: - raise ValueError(f"Document {document_id} not found") - return ImportedDocument.from_document( - doc, - extract_metadata=self._extract_metadata, - clean_html=self._clean_html, + return _legacy_document( + run_sync(self._operations.import_document(document_id, with_content=with_content)) ) def import_batch( @@ -243,39 +146,12 @@ def import_batch( *, with_content: bool = True, ) -> list[ImportResult]: - """Import multiple documents. - - Each document is fetched independently - failures don't affect others. - - Args: - document_ids: List of document IDs. - with_content: Whether to fetch HTML content. - - Returns: - List of ImportResults in the same order as input. - """ - results: list[ImportResult] = [] - - for doc_id in document_ids: - try: - imported = self.import_document(doc_id, with_content=with_content) - results.append( - ImportResult( - success=True, - document=imported, - document_id=doc_id, - ) - ) - except Exception as e: - results.append( - ImportResult( - success=False, - document_id=doc_id, - error=str(e), - ) - ) - - return results + return [ + _legacy_result(result) + for result in run_sync( + self._operations.import_batch(document_ids, with_content=with_content) + ) + ] def list_inbox( self, @@ -283,15 +159,6 @@ def list_inbox( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List inbox documents with optional metadata extraction. - - Args: - limit: Maximum number of documents to return. - with_content: Whether to fetch HTML content (slower). - - Returns: - List of ImportedDocuments. - """ return self._list_location(DocumentLocation.NEW, limit=limit, with_content=with_content) def list_reading_list( @@ -300,15 +167,6 @@ def list_reading_list( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List reading list documents with optional metadata extraction. - - Args: - limit: Maximum number of documents to return. - with_content: Whether to fetch HTML content (slower). - - Returns: - List of ImportedDocuments. - """ return self._list_location(DocumentLocation.LATER, limit=limit, with_content=with_content) def list_archive( @@ -317,15 +175,6 @@ def list_archive( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List archived documents with optional metadata extraction. - - Args: - limit: Maximum number of documents to return. - with_content: Whether to fetch HTML content (slower). - - Returns: - List of ImportedDocuments. - """ return self._list_location(DocumentLocation.ARCHIVE, limit=limit, with_content=with_content) def _list_location( @@ -335,21 +184,16 @@ def _list_location( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List documents from a specific location.""" - results = [] - for i, doc in enumerate( - self._client.v3.list_documents(location=location, with_content=with_content) - ): - if limit and i >= limit: - break - results.append( - ImportedDocument.from_document( - doc, - extract_metadata=self._extract_metadata, - clean_html=self._clean_html, + return [ + _legacy_document(document) + for document in run_sync( + self._operations.list( + location=location, + limit=limit, + with_content=with_content, ) ) - return results + ] def list_updated_since( self, @@ -358,62 +202,23 @@ def list_updated_since( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List documents updated since a timestamp. - - Args: - since: Only return documents updated after this time. - limit: Maximum number of documents to return. - with_content: Whether to fetch HTML content (slower). - - Returns: - List of ImportedDocuments. - """ - results = [] - for i, doc in enumerate( - self._client.v3.list_documents(updated_after=since, with_content=with_content) - ): - if limit and i >= limit: - break - results.append( - ImportedDocument.from_document( - doc, - extract_metadata=self._extract_metadata, - clean_html=self._clean_html, + return [ + _legacy_document(document) + for document in run_sync( + self._operations.list( + updated_after=since, + limit=limit, + with_content=with_content, ) ) - return results - - def save_url(self, url: str, **kwargs) -> str: - """Save a URL to Readwise Reader. + ] - Args: - url: The URL to save. - **kwargs: Additional arguments passed to create_document. - - Returns: - The document ID of the created document. - """ - result = self._client.v3.save_url(url, **kwargs) - return result.id + def save_url(self, url: str, **kwargs: Any) -> str: + return run_sync(self._operations.save_url(url, **kwargs)) class AsyncDocumentImporter: - """Async interface for importing documents from Readwise Reader. - - Provides the same functionality as DocumentImporter but with async/await - support for use with async frameworks like FastAPI or aiohttp. - - Example: - from readwise_sdk import AsyncReadwiseClient - from readwise_sdk.contrib import AsyncDocumentImporter - - async with AsyncReadwiseClient() as client: - importer = AsyncDocumentImporter(client) - - # Import a single document with full content - doc = await importer.import_document("doc_id_here", with_content=True) - print(f"Title: {doc.title}") - """ + """Asynchronous compatibility wrapper over document import operations.""" def __init__( self, @@ -422,16 +227,14 @@ def __init__( extract_metadata: bool = True, clean_html: bool = True, ) -> None: - """Initialize the async document importer. - - Args: - client: The async Readwise client. - extract_metadata: Extract domain, word count, etc. - clean_html: Convert HTML content to clean text. - """ self._client = client self._extract_metadata = extract_metadata self._clean_html = clean_html + self._operations = DocumentImportOperations( + AsyncDocumentsResource(client), + extract_metadata=extract_metadata, + clean_html=clean_html, + ) async def import_document( self, @@ -439,25 +242,8 @@ async def import_document( *, with_content: bool = True, ) -> ImportedDocument: - """Import a single document with optional content. - - Args: - document_id: The document ID. - with_content: Whether to fetch HTML content. - - Returns: - ImportedDocument with extracted metadata. - - Raises: - ValueError: If the document doesn't exist. - """ - doc = await self._client.v3.get_document(document_id, with_content=with_content) - if doc is None: - raise ValueError(f"Document {document_id} not found") - return ImportedDocument.from_document( - doc, - extract_metadata=self._extract_metadata, - clean_html=self._clean_html, + return _legacy_document( + await self._operations.import_document(document_id, with_content=with_content) ) async def import_batch( @@ -466,39 +252,13 @@ async def import_batch( *, with_content: bool = True, ) -> list[ImportResult]: - """Import multiple documents. - - Each document is fetched independently - failures don't affect others. - - Args: - document_ids: List of document IDs. - with_content: Whether to fetch HTML content. - - Returns: - List of ImportResults in the same order as input. - """ - results: list[ImportResult] = [] - - for doc_id in document_ids: - try: - imported = await self.import_document(doc_id, with_content=with_content) - results.append( - ImportResult( - success=True, - document=imported, - document_id=doc_id, - ) - ) - except Exception as e: - results.append( - ImportResult( - success=False, - document_id=doc_id, - error=str(e), - ) - ) - - return results + return [ + _legacy_result(result) + for result in await self._operations.import_batch( + document_ids, + with_content=with_content, + ) + ] async def list_inbox( self, @@ -506,17 +266,10 @@ async def list_inbox( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List inbox documents with optional metadata extraction. - - Args: - limit: Maximum number of documents to return. - with_content: Whether to fetch HTML content (slower). - - Returns: - List of ImportedDocuments. - """ return await self._list_location( - DocumentLocation.NEW, limit=limit, with_content=with_content + DocumentLocation.NEW, + limit=limit, + with_content=with_content, ) async def list_reading_list( @@ -525,17 +278,10 @@ async def list_reading_list( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List reading list documents with optional metadata extraction. - - Args: - limit: Maximum number of documents to return. - with_content: Whether to fetch HTML content (slower). - - Returns: - List of ImportedDocuments. - """ return await self._list_location( - DocumentLocation.LATER, limit=limit, with_content=with_content + DocumentLocation.LATER, + limit=limit, + with_content=with_content, ) async def list_archive( @@ -544,17 +290,10 @@ async def list_archive( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List archived documents with optional metadata extraction. - - Args: - limit: Maximum number of documents to return. - with_content: Whether to fetch HTML content (slower). - - Returns: - List of ImportedDocuments. - """ return await self._list_location( - DocumentLocation.ARCHIVE, limit=limit, with_content=with_content + DocumentLocation.ARCHIVE, + limit=limit, + with_content=with_content, ) async def _list_location( @@ -564,23 +303,14 @@ async def _list_location( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List documents from a specific location.""" - results = [] - i = 0 - async for doc in self._client.v3.list_documents( - location=location, with_content=with_content - ): - if limit and i >= limit: - break - results.append( - ImportedDocument.from_document( - doc, - extract_metadata=self._extract_metadata, - clean_html=self._clean_html, - ) + return [ + _legacy_document(document) + for document in await self._operations.list( + location=location, + limit=limit, + with_content=with_content, ) - i += 1 - return results + ] async def list_updated_since( self, @@ -589,42 +319,14 @@ async def list_updated_since( limit: int | None = None, with_content: bool = False, ) -> list[ImportedDocument]: - """List documents updated since a timestamp. - - Args: - since: Only return documents updated after this time. - limit: Maximum number of documents to return. - with_content: Whether to fetch HTML content (slower). - - Returns: - List of ImportedDocuments. - """ - results = [] - i = 0 - async for doc in self._client.v3.list_documents( - updated_after=since, with_content=with_content - ): - if limit and i >= limit: - break - results.append( - ImportedDocument.from_document( - doc, - extract_metadata=self._extract_metadata, - clean_html=self._clean_html, - ) + return [ + _legacy_document(document) + for document in await self._operations.list( + updated_after=since, + limit=limit, + with_content=with_content, ) - i += 1 - return results - - async def save_url(self, url: str, **kwargs) -> str: - """Save a URL to Readwise Reader. - - Args: - url: The URL to save. - **kwargs: Additional arguments passed to create_document. + ] - Returns: - The document ID of the created document. - """ - result = await self._client.v3.save_url(url, **kwargs) - return result.id + async def save_url(self, url: str, **kwargs: Any) -> str: + return await self._operations.save_url(url, **kwargs) diff --git a/src/readwise_sdk/contrib/highlight_push.py b/src/readwise_sdk/contrib/highlight_push.py index f0455f1..7f21a00 100644 --- a/src/readwise_sdk/contrib/highlight_push.py +++ b/src/readwise_sdk/contrib/highlight_push.py @@ -1,31 +1,4 @@ -"""Simplified interface for pushing highlights to Readwise. - -Designed for highlight_helper and similar projects that need to sync -user-created highlights TO Readwise. - -Example: - from readwise_sdk import ReadwiseClient - from readwise_sdk.contrib import HighlightPusher, SimpleHighlight - - client = ReadwiseClient() - pusher = HighlightPusher(client) - - # Push a single highlight - result = pusher.push( - text="This is my highlight", - title="Article Title", - author="John Doe", - note="My note about this", - ) - print(f"Created highlight {result.highlight_id}") - - # Push multiple highlights - highlights = [ - SimpleHighlight(text="First highlight", title="Book 1"), - SimpleHighlight(text="Second highlight", title="Book 2"), - ] - results = pusher.push_batch(highlights) -""" +"""Legacy highlight-pushing compatibility shims.""" from __future__ import annotations @@ -33,59 +6,55 @@ from datetime import datetime from typing import TYPE_CHECKING -from readwise_sdk._utils import truncate_string -from readwise_sdk.v2.models import BookCategory, Highlight, HighlightCreate, HighlightUpdate +from readwise_sdk.operations.auth import AuthOperations +from readwise_sdk.operations.compat import ( + AsyncHighlightsResource, + SyncHighlightsResource, + run_sync, +) +from readwise_sdk.operations.highlights import ( + MAX_AUTHOR_LENGTH, + MAX_NOTE_LENGTH, + MAX_TEXT_LENGTH, + MAX_TITLE_LENGTH, + HighlightDeleteResult, + HighlightOperations, + HighlightPushInput, + HighlightPushResult, + HighlightUpdateInput, + HighlightUpdateResult, +) +from readwise_sdk.operations.highlights import ( + TruncationInfo as OperationTruncationInfo, +) +from readwise_sdk.v2.models import BookCategory, Highlight if TYPE_CHECKING: from readwise_sdk.client import AsyncReadwiseClient, ReadwiseClient -# Readwise field limits -MAX_TEXT_LENGTH = 8191 -MAX_NOTE_LENGTH = 8191 -MAX_TITLE_LENGTH = 511 -MAX_AUTHOR_LENGTH = 1024 - @dataclass class FieldTruncation: - """Truncation details for a single field.""" - field_name: str original_length: int truncated_length: int @property def chars_removed(self) -> int: - """Number of characters removed by truncation.""" return self.original_length - self.truncated_length @dataclass class TruncationInfo: - """Detailed information about which fields were truncated and by how much. - - Provides per-field truncation details when ``PushResult.was_truncated`` - or ``UpdateResult.was_truncated`` is ``True``. - - Example: - result = pusher.push(text="x" * 10000, title="Test") - if result.truncation_info: - for ft in result.truncation_info.fields: - print(f"{ft.field_name}: {ft.original_length} -> {ft.truncated_length}") - """ - fields: list[FieldTruncation] = field(default_factory=list) @property def truncated_field_names(self) -> list[str]: - """List of field names that were truncated.""" - return [f.field_name for f in self.fields] + return [item.field_name for item in self.fields] @dataclass class SimpleHighlight: - """A simplified highlight for pushing to Readwise.""" - text: str title: str author: str | None = None @@ -101,8 +70,6 @@ class SimpleHighlight: @dataclass class PushResult: - """Result of pushing a highlight to Readwise.""" - success: bool highlight_id: int | None = None book_id: int | None = None @@ -114,8 +81,6 @@ class PushResult: @dataclass class UpdateResult: - """Result of updating a highlight in Readwise.""" - success: bool highlight_id: int highlight: Highlight | None = None @@ -126,173 +91,82 @@ class UpdateResult: @dataclass class DeleteResult: - """Result of deleting a highlight from Readwise.""" - success: bool highlight_id: int error: str | None = None -def _to_create_request( - highlight: SimpleHighlight, auto_truncate: bool -) -> tuple[HighlightCreate, bool, TruncationInfo | None]: - """Convert SimpleHighlight to HighlightCreate, optionally truncating. +def _operation_input(highlight: SimpleHighlight) -> HighlightPushInput: + return HighlightPushInput( + text=highlight.text, + title=highlight.title, + author=highlight.author, + source_url=highlight.source_url, + source_type=highlight.source_type, + category=highlight.category, + note=highlight.note, + location=highlight.location, + location_type=highlight.location_type, + highlighted_at=highlight.highlighted_at, + tags=tuple(highlight.tags), + ) - Args: - highlight: The highlight to convert. - auto_truncate: Whether to truncate fields to API limits. - Returns: - Tuple of (HighlightCreate, was_truncated, truncation_info). - """ - was_truncated = False - truncation_info: TruncationInfo | None = None +def _legacy_truncation(info: OperationTruncationInfo | None) -> TruncationInfo | None: + if info is None: + return None + return TruncationInfo( + fields=[ + FieldTruncation( + field_name=item.field_name, + original_length=item.original_length, + truncated_length=item.truncated_length, + ) + for item in info.fields + ] + ) + - text = highlight.text - note = highlight.note - title = highlight.title - author = highlight.author - - if auto_truncate: - original_lengths = { - "text": len(text) if text is not None else 0, - "note": len(note) if note is not None else 0, - "title": len(title) if title is not None else 0, - "author": len(author) if author is not None else 0, - } - - text, t1 = truncate_string(text, MAX_TEXT_LENGTH) - note, t2 = truncate_string(note, MAX_NOTE_LENGTH) - title, t3 = truncate_string(title, MAX_TITLE_LENGTH) - author, t4 = truncate_string(author, MAX_AUTHOR_LENGTH) - was_truncated = any([t1, t2, t3, t4]) - - if was_truncated: - field_truncations: list[FieldTruncation] = [] - for field_name, flag, max_len in [ - ("text", t1, MAX_TEXT_LENGTH), - ("note", t2, MAX_NOTE_LENGTH), - ("title", t3, MAX_TITLE_LENGTH), - ("author", t4, MAX_AUTHOR_LENGTH), - ]: - if flag: - field_truncations.append( - FieldTruncation( - field_name=field_name, - original_length=original_lengths[field_name], - truncated_length=max_len, - ) - ) - truncation_info = TruncationInfo(fields=field_truncations) - - # Text must not be None after truncation - if text is None: - text = "" - - return ( - HighlightCreate( - text=text, - title=title, - author=author, - source_url=highlight.source_url, - source_type=highlight.source_type, - category=highlight.category, - note=note, - location=highlight.location, - location_type=highlight.location_type, - highlighted_at=highlight.highlighted_at, - ), - was_truncated, - truncation_info, +def _legacy_push(result: HighlightPushResult, original: SimpleHighlight) -> PushResult: + return PushResult( + success=result.success, + highlight_id=result.highlight_id, + book_id=None, + error=result.error_message, + original=original, + was_truncated=result.was_truncated, + truncation_info=_legacy_truncation(result.truncation_info), ) -def _to_update_request( - text: str | None, - note: str | None, - location: int | None, - location_type: str | None, - auto_truncate: bool, -) -> tuple[HighlightUpdate, bool, TruncationInfo | None]: - """Create HighlightUpdate, optionally truncating text fields. - - Args: - text: New highlight text. - note: New note. - location: New location. - location_type: New location type. - auto_truncate: Whether to truncate fields to API limits. - - Returns: - Tuple of (HighlightUpdate, was_truncated, truncation_info). - """ - was_truncated = False - truncation_info: TruncationInfo | None = None +def _legacy_update(result: HighlightUpdateResult) -> UpdateResult: + return UpdateResult( + success=result.success, + highlight_id=result.highlight_id, + highlight=result.highlight, + error=str(result.error) if result.error is not None else None, + was_truncated=result.was_truncated, + truncation_info=_legacy_truncation(result.truncation_info), + ) + - if auto_truncate: - field_truncations: list[FieldTruncation] = [] - if text is not None: - original_len = len(text) - text, t1 = truncate_string(text, MAX_TEXT_LENGTH) - if t1: - was_truncated = True - field_truncations.append( - FieldTruncation( - field_name="text", - original_length=original_len, - truncated_length=MAX_TEXT_LENGTH, - ) - ) - if note is not None: - original_len = len(note) - note, t2 = truncate_string(note, MAX_NOTE_LENGTH) - if t2: - was_truncated = True - field_truncations.append( - FieldTruncation( - field_name="note", - original_length=original_len, - truncated_length=MAX_NOTE_LENGTH, - ) - ) - if was_truncated: - truncation_info = TruncationInfo(fields=field_truncations) - - return ( - HighlightUpdate( - text=text, - note=note, - location=location, - location_type=location_type, - ), - was_truncated, - truncation_info, +def _legacy_delete(result: HighlightDeleteResult) -> DeleteResult: + return DeleteResult( + success=result.success, + highlight_id=result.highlight_id, + error=str(result.error) if result.error is not None else None, ) class HighlightPusher: - """Simplified interface for pushing highlights to Readwise. - - Provides: - - Automatic field truncation to Readwise limits - - Batch operations with individual error handling - - Simple dataclass-based input - """ + """Synchronous compatibility wrapper over highlight operations.""" - def __init__( - self, - client: ReadwiseClient, - *, - auto_truncate: bool = True, - ) -> None: - """Initialize the highlight pusher. - - Args: - client: The Readwise client. - auto_truncate: Automatically truncate fields to Readwise limits. - """ + def __init__(self, client: ReadwiseClient, *, auto_truncate: bool = True) -> None: self._client = client self._auto_truncate = auto_truncate + resource = SyncHighlightsResource(client) + self._operations = HighlightOperations(resource, resource, resource) + self._auth = AuthOperations(resource) def push( self, @@ -308,126 +182,35 @@ def push( highlighted_at: datetime | None = None, tags: list[str] | None = None, ) -> PushResult: - """Push a single highlight to Readwise. - - Args: - text: The highlight text. - title: Title of the source (book/article name). - author: Author of the source. - source_url: URL of the source. - source_type: Type identifier for the source. - category: Category (articles, books, tweets, etc.). Defaults to None - to let the Readwise API decide. - note: Note attached to the highlight. - location: Location in the source (page number, etc.). - highlighted_at: When the highlight was made. - tags: Tags to apply to the highlight. - - Returns: - PushResult with success status and IDs. - """ - highlight = SimpleHighlight( - text=text, - title=title, - author=author, - source_url=source_url, - source_type=source_type, - category=category, - note=note, - location=location, - highlighted_at=highlighted_at, - tags=tags or [], + return self.push_highlight( + SimpleHighlight( + text=text, + title=title, + author=author, + source_url=source_url, + source_type=source_type, + category=category, + note=note, + location=location, + highlighted_at=highlighted_at, + tags=tags or [], + ) ) - return self.push_highlight(highlight) def push_highlight(self, highlight: SimpleHighlight) -> PushResult: - """Push a SimpleHighlight to Readwise. - - Args: - highlight: The highlight to push. - - Returns: - PushResult with success status and IDs. - """ - results = self.push_batch([highlight]) - return results[0] + return self.push_batch([highlight])[0] def push_batch(self, highlights: list[SimpleHighlight]) -> list[PushResult]: - """Push multiple highlights to Readwise. - - Each highlight is processed independently - failures don't affect others. - - Args: - highlights: List of highlights to push. - - Returns: - List of PushResults in the same order as input. - """ - if not highlights: - return [] - - # Convert to create requests - create_requests = [] - truncation_flags: list[bool] = [] - truncation_infos: list[TruncationInfo | None] = [] - for h in highlights: - req, was_truncated, trunc_info = _to_create_request(h, self._auto_truncate) - create_requests.append(req) - truncation_flags.append(was_truncated) - truncation_infos.append(trunc_info) - - # Push to API - results: list[PushResult] = [] - try: - # create_highlights returns list[int] (highlight IDs) - highlight_ids = self._client.v2.create_highlights(create_requests) - - # Map results back to highlights - for i, h in enumerate(highlights): - if i < len(highlight_ids): - highlight_id = highlight_ids[i] - results.append( - PushResult( - success=True, - highlight_id=highlight_id, - book_id=None, # Not returned by API - original=h, - was_truncated=truncation_flags[i], - truncation_info=truncation_infos[i], - ) - ) - else: - results.append( - PushResult( - success=False, - error="No API result returned", - original=h, - was_truncated=truncation_flags[i], - truncation_info=truncation_infos[i], - ) - ) - except Exception as e: - # If batch fails, mark all as failed - for i, h in enumerate(highlights): - results.append( - PushResult( - success=False, - error=str(e), - original=h, - was_truncated=truncation_flags[i], - truncation_info=truncation_infos[i], - ) - ) - - return results + canonical = run_sync( + self._operations.push_batch( + [_operation_input(item) for item in highlights], + auto_truncate=self._auto_truncate, + ) + ) + return [_legacy_push(result, highlights[index]) for index, result in enumerate(canonical)] def validate_token(self) -> bool: - """Validate the API token. - - Returns: - True if the token is valid. - """ - return self._client.validate_token() + return run_sync(self._auth.validate_token()) def update( self, @@ -438,138 +221,39 @@ def update( location: int | None = None, location_type: str | None = None, ) -> UpdateResult: - """Update an existing highlight. - - Args: - highlight_id: The ID of the highlight to update. - text: New highlight text. - note: New note. - location: New location in the source. - location_type: Type of location (e.g., "page"). - - Returns: - UpdateResult with success status and updated highlight. - """ - results = self.update_batch([(highlight_id, text, note, location, location_type)]) - return results[0] + return self.update_batch([(highlight_id, text, note, location, location_type)])[0] def update_batch( self, updates: list[tuple[int, str | None, str | None, int | None, str | None]], ) -> list[UpdateResult]: - """Update multiple highlights. - - Args: - updates: List of tuples (highlight_id, text, note, location, location_type). - Pass None for fields you don't want to update. - - Returns: - List of UpdateResults in the same order as input. - """ - results: list[UpdateResult] = [] - - for highlight_id, text, note, location, location_type in updates: - try: - update_req, was_truncated, trunc_info = _to_update_request( - text, note, location, location_type, self._auto_truncate - ) - highlight = self._client.v2.update_highlight(highlight_id, update_req) - results.append( - UpdateResult( - success=True, - highlight_id=highlight_id, - highlight=highlight, - was_truncated=was_truncated, - truncation_info=trunc_info, - ) - ) - except Exception as e: - results.append( - UpdateResult( - success=False, - highlight_id=highlight_id, - error=str(e), - ) - ) - - return results + canonical = run_sync( + self._operations.update_batch( + [HighlightUpdateInput(*item) for item in updates], + auto_truncate=self._auto_truncate, + ) + ) + return [_legacy_update(result) for result in canonical] def delete(self, highlight_id: int) -> DeleteResult: - """Delete a highlight. - - Args: - highlight_id: The ID of the highlight to delete. - - Returns: - DeleteResult with success status. - """ - results = self.delete_batch([highlight_id]) - return results[0] + return self.delete_batch([highlight_id])[0] def delete_batch(self, highlight_ids: list[int]) -> list[DeleteResult]: - """Delete multiple highlights. - - Args: - highlight_ids: List of highlight IDs to delete. - - Returns: - List of DeleteResults in the same order as input. - """ - results: list[DeleteResult] = [] - - for highlight_id in highlight_ids: - try: - self._client.v2.delete_highlight(highlight_id) - results.append( - DeleteResult( - success=True, - highlight_id=highlight_id, - ) - ) - except Exception as e: - results.append( - DeleteResult( - success=False, - highlight_id=highlight_id, - error=str(e), - ) - ) - - return results + return [ + _legacy_delete(result) + for result in run_sync(self._operations.delete_batch(highlight_ids)) + ] class AsyncHighlightPusher: - """Async interface for pushing highlights to Readwise. + """Asynchronous compatibility wrapper over highlight operations.""" - Provides the same functionality as HighlightPusher but with async/await - support for use with async frameworks like FastAPI or aiohttp. - - Example: - from readwise_sdk import AsyncReadwiseClient - from readwise_sdk.contrib import AsyncHighlightPusher - - async with AsyncReadwiseClient() as client: - pusher = AsyncHighlightPusher(client) - result = await pusher.push( - text="This is my highlight", - title="Article Title", - ) - """ - - def __init__( - self, - client: AsyncReadwiseClient, - *, - auto_truncate: bool = True, - ) -> None: - """Initialize the async highlight pusher. - - Args: - client: The async Readwise client. - auto_truncate: Automatically truncate fields to Readwise limits. - """ + def __init__(self, client: AsyncReadwiseClient, *, auto_truncate: bool = True) -> None: self._client = client self._auto_truncate = auto_truncate + resource = AsyncHighlightsResource(client) + self._operations = HighlightOperations(resource, resource, resource) + self._auth = AuthOperations(resource) async def push( self, @@ -585,123 +269,33 @@ async def push( highlighted_at: datetime | None = None, tags: list[str] | None = None, ) -> PushResult: - """Push a single highlight to Readwise. - - Args: - text: The highlight text. - title: Title of the source (book/article name). - author: Author of the source. - source_url: URL of the source. - source_type: Type identifier for the source. - category: Category (articles, books, tweets, etc.). Defaults to None - to let the Readwise API decide. - note: Note attached to the highlight. - location: Location in the source (page number, etc.). - highlighted_at: When the highlight was made. - tags: Tags to apply to the highlight. - - Returns: - PushResult with success status and IDs. - """ - highlight = SimpleHighlight( - text=text, - title=title, - author=author, - source_url=source_url, - source_type=source_type, - category=category, - note=note, - location=location, - highlighted_at=highlighted_at, - tags=tags or [], + return await self.push_highlight( + SimpleHighlight( + text=text, + title=title, + author=author, + source_url=source_url, + source_type=source_type, + category=category, + note=note, + location=location, + highlighted_at=highlighted_at, + tags=tags or [], + ) ) - return await self.push_highlight(highlight) async def push_highlight(self, highlight: SimpleHighlight) -> PushResult: - """Push a SimpleHighlight to Readwise. - - Args: - highlight: The highlight to push. - - Returns: - PushResult with success status and IDs. - """ - results = await self.push_batch([highlight]) - return results[0] + return (await self.push_batch([highlight]))[0] async def push_batch(self, highlights: list[SimpleHighlight]) -> list[PushResult]: - """Push multiple highlights to Readwise. - - Each highlight is processed independently - failures don't affect others. - - Args: - highlights: List of highlights to push. - - Returns: - List of PushResults in the same order as input. - """ - if not highlights: - return [] - - # Convert to create requests - create_requests = [] - truncation_flags: list[bool] = [] - truncation_infos: list[TruncationInfo | None] = [] - for h in highlights: - req, was_truncated, trunc_info = _to_create_request(h, self._auto_truncate) - create_requests.append(req) - truncation_flags.append(was_truncated) - truncation_infos.append(trunc_info) - - # Push to API - results: list[PushResult] = [] - try: - highlight_ids = await self._client.v2.create_highlights(create_requests) - - for i, h in enumerate(highlights): - if i < len(highlight_ids): - highlight_id = highlight_ids[i] - results.append( - PushResult( - success=True, - highlight_id=highlight_id, - book_id=None, - original=h, - was_truncated=truncation_flags[i], - truncation_info=truncation_infos[i], - ) - ) - else: - results.append( - PushResult( - success=False, - error="No API result returned", - original=h, - was_truncated=truncation_flags[i], - truncation_info=truncation_infos[i], - ) - ) - except Exception as e: - for i, h in enumerate(highlights): - results.append( - PushResult( - success=False, - error=str(e), - original=h, - was_truncated=truncation_flags[i], - truncation_info=truncation_infos[i], - ) - ) - - return results + canonical = await self._operations.push_batch( + [_operation_input(item) for item in highlights], + auto_truncate=self._auto_truncate, + ) + return [_legacy_push(result, highlights[index]) for index, result in enumerate(canonical)] async def validate_token(self) -> bool: - """Validate the API token. - - Returns: - True if the token is valid. - """ - return await self._client.validate_token() + return await self._auth.validate_token() async def update( self, @@ -712,101 +306,38 @@ async def update( location: int | None = None, location_type: str | None = None, ) -> UpdateResult: - """Update an existing highlight. - - Args: - highlight_id: The ID of the highlight to update. - text: New highlight text. - note: New note. - location: New location in the source. - location_type: Type of location (e.g., "page"). - - Returns: - UpdateResult with success status and updated highlight. - """ - results = await self.update_batch([(highlight_id, text, note, location, location_type)]) - return results[0] + return (await self.update_batch([(highlight_id, text, note, location, location_type)]))[0] async def update_batch( self, updates: list[tuple[int, str | None, str | None, int | None, str | None]], ) -> list[UpdateResult]: - """Update multiple highlights. - - Args: - updates: List of tuples (highlight_id, text, note, location, location_type). - Pass None for fields you don't want to update. - - Returns: - List of UpdateResults in the same order as input. - """ - results: list[UpdateResult] = [] - - for highlight_id, text, note, location, location_type in updates: - try: - update_req, was_truncated, trunc_info = _to_update_request( - text, note, location, location_type, self._auto_truncate - ) - highlight = await self._client.v2.update_highlight(highlight_id, update_req) - results.append( - UpdateResult( - success=True, - highlight_id=highlight_id, - highlight=highlight, - was_truncated=was_truncated, - truncation_info=trunc_info, - ) - ) - except Exception as e: - results.append( - UpdateResult( - success=False, - highlight_id=highlight_id, - error=str(e), - ) - ) - - return results + canonical = await self._operations.update_batch( + [HighlightUpdateInput(*item) for item in updates], + auto_truncate=self._auto_truncate, + ) + return [_legacy_update(result) for result in canonical] async def delete(self, highlight_id: int) -> DeleteResult: - """Delete a highlight. - - Args: - highlight_id: The ID of the highlight to delete. - - Returns: - DeleteResult with success status. - """ - results = await self.delete_batch([highlight_id]) - return results[0] + return (await self.delete_batch([highlight_id]))[0] async def delete_batch(self, highlight_ids: list[int]) -> list[DeleteResult]: - """Delete multiple highlights. - - Args: - highlight_ids: List of highlight IDs to delete. - - Returns: - List of DeleteResults in the same order as input. - """ - results: list[DeleteResult] = [] - - for highlight_id in highlight_ids: - try: - await self._client.v2.delete_highlight(highlight_id) - results.append( - DeleteResult( - success=True, - highlight_id=highlight_id, - ) - ) - except Exception as e: - results.append( - DeleteResult( - success=False, - highlight_id=highlight_id, - error=str(e), - ) - ) - - return results + return [ + _legacy_delete(result) for result in await self._operations.delete_batch(highlight_ids) + ] + + +__all__ = [ + "AsyncHighlightPusher", + "DeleteResult", + "FieldTruncation", + "HighlightPusher", + "MAX_AUTHOR_LENGTH", + "MAX_NOTE_LENGTH", + "MAX_TEXT_LENGTH", + "MAX_TITLE_LENGTH", + "PushResult", + "SimpleHighlight", + "TruncationInfo", + "UpdateResult", +] diff --git a/src/readwise_sdk/managers/async_managers.py b/src/readwise_sdk/managers/async_managers.py index cf7f273..5e03f2e 100644 --- a/src/readwise_sdk/managers/async_managers.py +++ b/src/readwise_sdk/managers/async_managers.py @@ -1,18 +1,8 @@ -"""Async versions of high-level manager classes. - -These managers provide the same functionality as their synchronous counterparts -but use async/await for all I/O operations. - -Example: - async with AsyncReadwiseClient() as client: - manager = AsyncHighlightManager(client) - highlights = await manager.get_highlights_since(days=7) -""" +"""Legacy asynchronous manager compatibility shims.""" from __future__ import annotations -from collections import Counter -from datetime import UTC, datetime, timedelta +from datetime import UTC, datetime from pathlib import Path from typing import TYPE_CHECKING, cast @@ -21,6 +11,15 @@ from readwise_sdk.managers.sync import SyncResult, SyncState from readwise_sdk.models import SyncCheckpoint from readwise_sdk.models import SyncResult as CanonicalSyncResult +from readwise_sdk.operations.books import BookOperations +from readwise_sdk.operations.compat import ( + AsyncBooksResource, + AsyncDocumentsResource, + AsyncHighlightsResource, + bulk_result_map, +) +from readwise_sdk.operations.documents import DocumentOperations +from readwise_sdk.operations.highlights import HighlightOperations from readwise_sdk.operations.sync import AsyncSyncClient, SyncOperations from readwise_sdk.state import JsonFileStateStore, MemoryStateStore from readwise_sdk.v2.models import Book, BookCategory, Highlight, HighlightCreate @@ -33,23 +32,15 @@ class AsyncHighlightManager: - """Async high-level operations for managing highlights.""" + """Compatibility wrapper over canonical highlight operations.""" def __init__(self, client: AsyncReadwiseClient) -> None: - """Initialize the async highlight manager. - - Args: - client: The async Readwise client. - """ self._client = client + resource = AsyncHighlightsResource(client) + self._operations = HighlightOperations(resource, resource, resource) async def get_all_highlights(self) -> list[Highlight]: - """Get all highlights, exhausting pagination. - - Returns: - List of all highlights. - """ - return [h async for h in self._client.v2.list_highlights()] + return await self._operations.list() async def get_highlights_since( self, @@ -58,44 +49,13 @@ async def get_highlights_since( hours: int | None = None, since: datetime | None = None, ) -> list[Highlight]: - """Get highlights updated since a given time. - - Args: - days: Number of days to look back. - hours: Number of hours to look back. - since: Specific datetime to look back to. - - Returns: - List of highlights updated since the given time. - """ - if since is None: - if days is not None: - since = datetime.now(UTC) - timedelta(days=days) - elif hours is not None: - since = datetime.now(UTC) - timedelta(hours=hours) - else: - raise ValueError("Must specify days, hours, or since") - - return [h async for h in self._client.v2.list_highlights(updated_after=since)] + return await self._operations.since(days=days, hours=hours, since=since) async def get_highlights_by_book(self, book_id: int) -> list[Highlight]: - """Get all highlights for a specific book. - - Args: - book_id: The book ID. - - Returns: - List of highlights for the book. - """ - return [h async for h in self._client.v2.list_highlights(book_id=book_id)] + return await self._operations.list(book_id=book_id) async def get_highlights_with_notes(self) -> list[Highlight]: - """Get all highlights that have notes/annotations. - - Returns: - List of highlights with notes. - """ - return [h async for h in self._client.v2.list_highlights() if h.note] + return await self._operations.with_notes() async def search_highlights( self, @@ -103,92 +63,19 @@ async def search_highlights( *, case_sensitive: bool = False, ) -> list[Highlight]: - """Search highlights by text content. - - Args: - query: The search query. - case_sensitive: Whether to perform case-sensitive search. - - Returns: - List of matching highlights. - """ - if not case_sensitive: - query = query.lower() - - results = [] - async for highlight in self._client.v2.list_highlights(): - text = highlight.text if case_sensitive else highlight.text.lower() - note = (highlight.note or "") if case_sensitive else (highlight.note or "").lower() - - if query in text or query in note: - results.append(highlight) + return await self._operations.search_items(query, case_sensitive=case_sensitive) - return results - - async def filter_highlights( + def filter_highlights( self, predicate: Callable[[Highlight], bool], ) -> AsyncIterator[Highlight]: - """Filter highlights using a custom predicate. + return self._operations.filter(predicate) - Args: - predicate: A function that returns True for highlights to include. + async def bulk_tag(self, highlight_ids: list[int], tag: str) -> dict[int, bool]: + return bulk_result_map(highlight_ids, await self._operations.bulk_tag(highlight_ids, tag)) - Yields: - Highlights that match the predicate. - """ - async for highlight in self._client.v2.list_highlights(): - if predicate(highlight): - yield highlight - - async def bulk_tag( - self, - highlight_ids: list[int], - tag: str, - ) -> dict[int, bool]: - """Add a tag to multiple highlights. - - Args: - highlight_ids: List of highlight IDs to tag. - tag: The tag name to add. - - Returns: - Dict mapping highlight ID to success status. - """ - results: dict[int, bool] = {} - for hid in highlight_ids: - try: - await self._client.v2.create_highlight_tag(hid, tag) - results[hid] = True - except Exception: - results[hid] = False - return results - - async def bulk_untag( - self, - highlight_ids: list[int], - tag: str, - ) -> dict[int, bool]: - """Remove a tag from multiple highlights. - - Args: - highlight_ids: List of highlight IDs. - tag: The tag name to remove. - - Returns: - Dict mapping highlight ID to success status. - """ - results: dict[int, bool] = {} - for hid in highlight_ids: - try: - tags = [t async for t in self._client.v2.list_highlight_tags(hid)] - tag_obj = next((t for t in tags if t.name == tag), None) - if tag_obj: - await self._client.v2.delete_highlight_tag(hid, tag_obj.id) - results[hid] = True - except Exception: - results[hid] = False - return results + async def bulk_untag(self, highlight_ids: list[int], tag: str) -> dict[int, bool]: + return bulk_result_map(highlight_ids, await self._operations.bulk_untag(highlight_ids, tag)) async def create_highlight( self, @@ -199,93 +86,43 @@ async def create_highlight( note: str | None = None, source_url: str | None = None, ) -> int: - """Create a single highlight (convenience method). - - Args: - text: The highlight text. - title: The source title. - author: The source author. - note: An optional note/annotation. - source_url: The source URL. - - Returns: - The created highlight ID. - """ - highlight = HighlightCreate( - text=text, - title=title, - author=author, - note=note, - source_url=source_url, + ids = await self._operations.create( + HighlightCreate( + text=text, + title=title, + author=author, + note=note, + source_url=source_url, + ) ) - ids = await self._client.v2.create_highlights([highlight]) return ids[0] if ids else 0 async def get_highlight_count(self) -> int: - """Get the total number of highlights. - - Returns: - Total highlight count. - """ - count = 0 - async for _ in self._client.v2.list_highlights(): - count += 1 - return count + return await self._operations.count() class AsyncBookManager: - """Async high-level operations for managing books.""" + """Compatibility wrapper over canonical book operations.""" def __init__(self, client: AsyncReadwiseClient) -> None: - """Initialize the async book manager. - - Args: - client: The async Readwise client. - """ self._client = client + self._operations = BookOperations( + AsyncBooksResource(client), + AsyncHighlightsResource(client), + ) async def get_all_books(self) -> list[Book]: - """Get all books, exhausting pagination. - - Returns: - List of all books. - """ - return [b async for b in self._client.v2.list_books()] + return await self._operations.list() async def get_books_by_category(self, category: BookCategory) -> list[Book]: - """Get books filtered by category. - - Args: - category: The category to filter by. - - Returns: - List of books in the category. - """ - return [b async for b in self._client.v2.list_books(category=category)] + return await self._operations.list(category=category) async def get_books_by_source(self, source: str) -> list[Book]: - """Get books filtered by source. - - Args: - source: The source to filter by (e.g., "kindle", "instapaper"). - - Returns: - List of books from the source. - """ - return [b async for b in self._client.v2.list_books(source=source)] + return await self._operations.list(source=source) async def get_book_with_highlights(self, book_id: int) -> BookWithHighlights: - """Get a book with all its highlights. - - Args: - book_id: The book ID. - - Returns: - BookWithHighlights containing the book and its highlights. - """ - book = await self._client.v2.get_book(book_id) - highlights = [h async for h in self._client.v2.list_highlights(book_id=book_id)] - return BookWithHighlights(book=book, highlights=highlights) + result = await self._operations.with_highlights(book_id) + return BookWithHighlights(book=result.book, highlights=result.highlights) async def get_recent_books( self, @@ -293,140 +130,42 @@ async def get_recent_books( days: int | None = None, limit: int | None = None, ) -> list[Book]: - """Get recently updated books. - - Args: - days: Only include books updated in the last N days. - limit: Maximum number of books to return. - - Returns: - List of recent books. - """ - since = None - if days is not None: - since = datetime.now(UTC) - timedelta(days=days) - - books = [b async for b in self._client.v2.list_books(updated_after=since)] - - books.sort( - key=lambda b: b.last_highlight_at or datetime.min.replace(tzinfo=UTC), - reverse=True, - ) - - if limit: - books = books[:limit] - - return books + return await self._operations.recent(days=days, limit=limit) async def get_reading_stats(self) -> ReadingStats: - """Get aggregated reading statistics. - - Returns: - ReadingStats with various aggregations. - """ - books = await self.get_all_books() - - books_by_category: Counter[str] = Counter() - highlights_by_category: Counter[str] = Counter() - highlights_by_source: Counter[str] = Counter() - - for book in books: - cat = book.category.value if book.category else "unknown" - books_by_category[cat] += 1 - highlights_by_category[cat] += book.num_highlights - - source = book.source or "unknown" - highlights_by_source[source] += book.num_highlights - - most_highlighted = sorted( - [(b.title, b.num_highlights) for b in books], - key=lambda x: x[1], - reverse=True, - )[:10] - - recent = await self.get_recent_books(days=30, limit=10) - + result = await self._operations.statistics() return ReadingStats( - total_books=len(books), - total_highlights=sum(b.num_highlights for b in books), - books_by_category=dict(books_by_category), - highlights_by_category=dict(highlights_by_category), - highlights_by_source=dict(highlights_by_source), - most_highlighted_books=most_highlighted, - recent_books=recent, + total_books=result.total_books, + total_highlights=result.total_highlights, + books_by_category=result.books_by_category, + highlights_by_category=result.highlights_by_category, + highlights_by_source=result.highlights_by_source, + most_highlighted_books=result.most_highlighted_books, + recent_books=result.recent_books, ) - async def search_books( - self, - query: str, - *, - case_sensitive: bool = False, - ) -> list[Book]: - """Search books by title or author. - - Args: - query: The search query. - case_sensitive: Whether to perform case-sensitive search. - - Returns: - List of matching books. - """ - if not case_sensitive: - query = query.lower() - - results = [] - async for book in self._client.v2.list_books(): - title = book.title if case_sensitive else book.title.lower() - author = (book.author or "") if case_sensitive else (book.author or "").lower() - - if query in title or query in author: - results.append(book) - - return results + async def search_books(self, query: str, *, case_sensitive: bool = False) -> list[Book]: + return await self._operations.search_items(query, case_sensitive=case_sensitive) async def get_book_count(self) -> int: - """Get the total number of books. - - Returns: - Total book count. - """ - return len(await self.get_all_books()) + return await self._operations.count() class AsyncDocumentManager: - """Async high-level operations for managing Reader documents.""" + """Compatibility wrapper over canonical document operations.""" def __init__(self, client: AsyncReadwiseClient) -> None: - """Initialize the async document manager. - - Args: - client: The async Readwise client. - """ self._client = client + self._operations = DocumentOperations(AsyncDocumentsResource(client, manager_compat=True)) async def get_inbox(self) -> list[Document]: - """Get all documents in the inbox. - - Returns: - List of inbox documents. - """ - return [d async for d in self._client.v3.get_inbox()] + return await self._operations.inbox() async def get_reading_list(self) -> list[Document]: - """Get all documents in the reading list. - - Returns: - List of reading list documents. - """ - return [d async for d in self._client.v3.get_reading_list()] + return await self._operations.later() async def get_archive(self) -> list[Document]: - """Get all archived documents. - - Returns: - List of archived documents. - """ - return [d async for d in self._client.v3.get_archive()] + return await self._operations.archive() async def get_documents_since( self, @@ -435,109 +174,38 @@ async def get_documents_since( hours: int | None = None, since: datetime | None = None, ) -> list[Document]: - """Get documents updated since a given time. - - Args: - days: Number of days to look back. - hours: Number of hours to look back. - since: Specific datetime to look back to. - - Returns: - List of documents updated since the given time. - """ - if since is None: - if days is not None: - since = datetime.now(UTC) - timedelta(days=days) - elif hours is not None: - since = datetime.now(UTC) - timedelta(hours=hours) - else: - raise ValueError("Must specify days, hours, or since") - - return [d async for d in self._client.v3.list_documents(updated_after=since)] + return await self._operations.since(days=days, hours=hours, since=since) async def move_to_later(self, document_id: str) -> None: - """Move a document to the reading list. - - Args: - document_id: The document ID. - """ - await self._client.v3.move_to_later(document_id) + await self._operations.move(document_id, DocumentLocation.LATER) async def archive(self, document_id: str) -> None: - """Archive a document. - - Args: - document_id: The document ID. - """ - await self._client.v3.archive(document_id) + await self._operations.move(document_id, DocumentLocation.ARCHIVE) async def move_to_inbox(self, document_id: str) -> None: - """Move a document back to the inbox. - - Args: - document_id: The document ID. - """ - await self._client.v3.move_to_inbox(document_id) + await self._operations.move(document_id, DocumentLocation.NEW) async def bulk_archive(self, document_ids: list[str]) -> dict[str, bool]: - """Archive multiple documents. - - Args: - document_ids: List of document IDs. - - Returns: - Dict mapping document ID to success status. - """ - results: dict[str, bool] = {} - for doc_id in document_ids: - try: - await self._client.v3.archive(doc_id) - results[doc_id] = True - except Exception: - results[doc_id] = False - return results + result = await self._operations.bulk_move(document_ids, DocumentLocation.ARCHIVE) + return bulk_result_map(document_ids, result) async def bulk_tag_documents( self, document_ids: list[str], tags: list[str], ) -> dict[str, bool]: - """Set tags on multiple documents. - - Args: - document_ids: List of document IDs. - tags: Tags to set on all documents. - - Returns: - Dict mapping document ID to success status. - """ - results: dict[str, bool] = {} - for doc_id in document_ids: - try: - await self._client.v3.tag_document(doc_id, tags) - results[doc_id] = True - except Exception: - results[doc_id] = False - return results - - async def filter_documents( + return bulk_result_map( + document_ids, + await self._operations.bulk_set_tags(document_ids, tags), + ) + + def filter_documents( self, predicate: Callable[[Document], bool], *, location: DocumentLocation | None = None, ) -> AsyncIterator[Document]: - """Filter documents using a custom predicate. - - Args: - predicate: A function that returns True for documents to include. - location: Optional location to filter by first. - - Yields: - Documents that match the predicate. - """ - async for doc in self._client.v3.list_documents(location=location): - if predicate(doc): - yield doc + return self._operations.filter(predicate, location=location) async def search_documents( self, @@ -546,92 +214,36 @@ async def search_documents( case_sensitive: bool = False, location: DocumentLocation | None = None, ) -> list[Document]: - """Search documents by title, author, or summary. - - Args: - query: The search query. - case_sensitive: Whether to perform case-sensitive search. - location: Optional location to filter by. - - Returns: - List of matching documents. - """ - if not case_sensitive: - query = query.lower() - - results = [] - async for doc in self._client.v3.list_documents(location=location): - title = (doc.title or "") if case_sensitive else (doc.title or "").lower() - author = (doc.author or "") if case_sensitive else (doc.author or "").lower() - summary = (doc.summary or "") if case_sensitive else (doc.summary or "").lower() - - if query in title or query in author or query in summary: - results.append(doc) - - return results + return await self._operations.search_items( + query, + case_sensitive=case_sensitive, + location=location, + ) async def get_inbox_stats(self) -> InboxStats: - """Get statistics about the reading inbox. - - Returns: - InboxStats with counts and oldest/newest items. - """ - inbox = [d async for d in self._client.v3.get_inbox()] - reading_list = [d async for d in self._client.v3.get_reading_list()] - archive = [d async for d in self._client.v3.get_archive()] - - by_category: Counter[str] = Counter() - for doc in inbox + reading_list: - cat = doc.category.value if doc.category else "unknown" - by_category[cat] += 1 - - oldest = None - newest = None - if inbox: - sorted_inbox = sorted( - inbox, - key=lambda d: d.created_at or datetime.min.replace(tzinfo=UTC), - ) - oldest = sorted_inbox[0] - newest = sorted_inbox[-1] - + result = await self._operations.statistics() return InboxStats( - inbox_count=len(inbox), - reading_list_count=len(reading_list), - archive_count=len(archive), - total_count=len(inbox) + len(reading_list) + len(archive), - by_category=dict(by_category), - oldest_inbox_item=oldest, - newest_inbox_item=newest, + inbox_count=result.inbox_count, + reading_list_count=result.reading_list_count, + archive_count=result.archive_count, + total_count=result.total_count, + by_category=result.by_category, + oldest_inbox_item=result.oldest_inbox_item, + newest_inbox_item=result.newest_inbox_item, ) async def get_documents_by_category( self, category: DocumentCategory, ) -> list[Document]: - """Get all documents of a specific category. - - Args: - category: The category to filter by. - - Returns: - List of documents in the category. - """ - return [d async for d in self._client.v3.list_documents(category=category)] + return await self._operations.by_category(category) async def get_unread_count(self) -> int: - """Get the count of unread documents (inbox + reading list). - - Returns: - Count of unread documents. - """ - inbox = len([d async for d in self._client.v3.get_inbox()]) - reading_list = len([d async for d in self._client.v3.get_reading_list()]) - return inbox + reading_list + return await self._operations.unread_count() class AsyncSyncManager: - """Async manager for syncing Readwise data with state persistence.""" + """Async compatibility wrapper over canonical synchronization operations.""" def __init__( self, @@ -639,12 +251,6 @@ def __init__( *, state_file: Path | str | None = None, ) -> None: - """Initialize the async sync manager. - - Args: - client: The async Readwise client. - state_file: Optional path to persist sync state. - """ self._client = client self._state_file = Path(state_file) if state_file else None self._file_store = JsonFileStateStore(self._state_file) if self._state_file else None @@ -657,31 +263,22 @@ def __init__( ) def _load_state(self) -> SyncState: - """Load state from file if it exists.""" if self._file_store is not None: return self._file_store.load_legacy(SyncState.from_dict, SyncState) return SyncState() def _save_state(self) -> None: - """Save state to file if configured.""" if self._file_store is not None: self._file_store.save_legacy(self._state.to_dict()) @property def state(self) -> SyncState: - """Get the current sync state.""" return self._state def on_sync(self, callback: Callable[[SyncResult], None]) -> None: - """Register a callback for sync events. - - Args: - callback: Function to call with sync results. - """ self._callbacks.append(callback) def _notify_callbacks(self, result: SyncResult) -> None: - """Notify all registered callbacks.""" self._operation.notify_callbacks(self._callbacks, result) async def full_sync( @@ -691,16 +288,6 @@ async def full_sync( include_books: bool = True, include_documents: bool = True, ) -> SyncResult: - """Perform a full sync of all data. - - Args: - include_highlights: Whether to sync highlights. - include_books: Whether to sync books. - include_documents: Whether to sync documents. - - Returns: - SyncResult with all synced data. - """ self._checkpoint_store.save(self._checkpoint()) canonical = await self._operation.full( include_highlights=include_highlights, @@ -716,16 +303,6 @@ async def incremental_sync( include_books: bool = True, include_documents: bool = True, ) -> SyncResult: - """Perform an incremental sync since the last sync. - - Args: - include_highlights: Whether to sync highlights. - include_books: Whether to sync books. - include_documents: Whether to sync documents. - - Returns: - SyncResult with newly synced data. - """ self._checkpoint_store.save(self._checkpoint()) canonical = await self._operation.incremental( include_highlights=include_highlights, @@ -735,23 +312,12 @@ async def incremental_sync( return self._finish(canonical) async def sync_highlights_only(self) -> SyncResult: - """Sync only highlights. - - Returns: - SyncResult with synced highlights. - """ return await self.incremental_sync(include_books=False, include_documents=False) async def sync_documents_only(self) -> SyncResult: - """Sync only documents. - - Returns: - SyncResult with synced documents. - """ return await self.incremental_sync(include_highlights=False, include_books=False) def reset_state(self) -> None: - """Reset the sync state (next sync will be full).""" self._state = SyncState() self._checkpoint_store.save(SyncCheckpoint()) self._save_state() diff --git a/src/readwise_sdk/managers/books.py b/src/readwise_sdk/managers/books.py index 16390ed..7f897de 100644 --- a/src/readwise_sdk/managers/books.py +++ b/src/readwise_sdk/managers/books.py @@ -1,12 +1,12 @@ -"""High-level book management operations.""" +"""Legacy book manager compatibility shim.""" from __future__ import annotations -from collections import Counter from dataclasses import dataclass -from datetime import UTC, datetime, timedelta from typing import TYPE_CHECKING +from readwise_sdk.operations.books import BookOperations +from readwise_sdk.operations.compat import SyncBooksResource, SyncHighlightsResource, run_sync from readwise_sdk.v2.models import Book, BookCategory, Highlight if TYPE_CHECKING: @@ -15,16 +15,12 @@ @dataclass class BookWithHighlights: - """A book with its associated highlights.""" - book: Book highlights: list[Highlight] @dataclass class ReadingStats: - """Aggregated reading statistics.""" - total_books: int total_highlights: int books_by_category: dict[str, int] @@ -35,58 +31,27 @@ class ReadingStats: class BookManager: - """High-level operations for managing books.""" + """Compatibility wrapper over canonical book operations.""" def __init__(self, client: ReadwiseClient) -> None: - """Initialize the book manager. - - Args: - client: The Readwise client. - """ self._client = client + self._operations = BookOperations( + SyncBooksResource(client), + SyncHighlightsResource(client), + ) def get_all_books(self) -> list[Book]: - """Get all books, exhausting pagination. - - Returns: - List of all books. - """ - return list(self._client.v2.list_books()) + return run_sync(self._operations.list()) def get_books_by_category(self, category: BookCategory) -> list[Book]: - """Get books filtered by category. - - Args: - category: The category to filter by. - - Returns: - List of books in the category. - """ - return list(self._client.v2.list_books(category=category)) + return run_sync(self._operations.list(category=category)) def get_books_by_source(self, source: str) -> list[Book]: - """Get books filtered by source. - - Args: - source: The source to filter by (e.g., "kindle", "instapaper"). - - Returns: - List of books from the source. - """ - return list(self._client.v2.list_books(source=source)) + return run_sync(self._operations.list(source=source)) def get_book_with_highlights(self, book_id: int) -> BookWithHighlights: - """Get a book with all its highlights. - - Args: - book_id: The book ID. - - Returns: - BookWithHighlights containing the book and its highlights. - """ - book = self._client.v2.get_book(book_id) - highlights = list(self._client.v2.list_highlights(book_id=book_id)) - return BookWithHighlights(book=book, highlights=highlights) + result = run_sync(self._operations.with_highlights(book_id)) + return BookWithHighlights(book=result.book, highlights=result.highlights) def get_recent_books( self, @@ -94,105 +59,22 @@ def get_recent_books( days: int | None = None, limit: int | None = None, ) -> list[Book]: - """Get recently updated books. - - Args: - days: Only include books updated in the last N days. - limit: Maximum number of books to return. - - Returns: - List of recent books. - """ - since = None - if days is not None: - since = datetime.now(UTC) - timedelta(days=days) - - books = list(self._client.v2.list_books(updated_after=since)) - - # Sort by last_highlight_at descending - books.sort( - key=lambda b: b.last_highlight_at or datetime.min.replace(tzinfo=UTC), - reverse=True, - ) - - if limit: - books = books[:limit] - - return books + return run_sync(self._operations.recent(days=days, limit=limit)) def get_reading_stats(self) -> ReadingStats: - """Get aggregated reading statistics. - - Returns: - ReadingStats with various aggregations. - """ - books = self.get_all_books() - - # Aggregate by category - books_by_category: Counter[str] = Counter() - highlights_by_category: Counter[str] = Counter() - highlights_by_source: Counter[str] = Counter() - - for book in books: - cat = book.category.value if book.category else "unknown" - books_by_category[cat] += 1 - highlights_by_category[cat] += book.num_highlights - - source = book.source or "unknown" - highlights_by_source[source] += book.num_highlights - - # Most highlighted books - most_highlighted = sorted( - [(b.title, b.num_highlights) for b in books], - key=lambda x: x[1], - reverse=True, - )[:10] - - # Recent books - recent = self.get_recent_books(days=30, limit=10) - + result = run_sync(self._operations.statistics()) return ReadingStats( - total_books=len(books), - total_highlights=sum(b.num_highlights for b in books), - books_by_category=dict(books_by_category), - highlights_by_category=dict(highlights_by_category), - highlights_by_source=dict(highlights_by_source), - most_highlighted_books=most_highlighted, - recent_books=recent, + total_books=result.total_books, + total_highlights=result.total_highlights, + books_by_category=result.books_by_category, + highlights_by_category=result.highlights_by_category, + highlights_by_source=result.highlights_by_source, + most_highlighted_books=result.most_highlighted_books, + recent_books=result.recent_books, ) - def search_books( - self, - query: str, - *, - case_sensitive: bool = False, - ) -> list[Book]: - """Search books by title or author. - - Args: - query: The search query. - case_sensitive: Whether to perform case-sensitive search. - - Returns: - List of matching books. - """ - if not case_sensitive: - query = query.lower() - - results = [] - for book in self._client.v2.list_books(): - title = book.title if case_sensitive else book.title.lower() - author = (book.author or "") if case_sensitive else (book.author or "").lower() - - if query in title or query in author: - results.append(book) - - return results + def search_books(self, query: str, *, case_sensitive: bool = False) -> list[Book]: + return run_sync(self._operations.search_items(query, case_sensitive=case_sensitive)) def get_book_count(self) -> int: - """Get the total number of books. - - Returns: - Total book count. - """ - return len(self.get_all_books()) + return run_sync(self._operations.count()) diff --git a/src/readwise_sdk/managers/documents.py b/src/readwise_sdk/managers/documents.py index 21d5665..712f23b 100644 --- a/src/readwise_sdk/managers/documents.py +++ b/src/readwise_sdk/managers/documents.py @@ -1,12 +1,18 @@ -"""High-level document management operations for Reader.""" +"""Legacy Reader document manager compatibility shim.""" from __future__ import annotations -from collections import Counter from dataclasses import dataclass -from datetime import UTC, datetime, timedelta +from datetime import datetime from typing import TYPE_CHECKING +from readwise_sdk.operations.compat import ( + SyncDocumentsResource, + bulk_result_map, + iter_sync, + run_sync, +) +from readwise_sdk.operations.documents import DocumentOperations from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation if TYPE_CHECKING: @@ -17,8 +23,6 @@ @dataclass class InboxStats: - """Statistics about the reading inbox.""" - inbox_count: int reading_list_count: int archive_count: int @@ -29,39 +33,20 @@ class InboxStats: class DocumentManager: - """High-level operations for managing Reader documents.""" + """Compatibility wrapper over canonical document operations.""" def __init__(self, client: ReadwiseClient) -> None: - """Initialize the document manager. - - Args: - client: The Readwise client. - """ self._client = client + self._operations = DocumentOperations(SyncDocumentsResource(client, manager_compat=True)) def get_inbox(self) -> list[Document]: - """Get all documents in the inbox. - - Returns: - List of inbox documents. - """ - return list(self._client.v3.get_inbox()) + return run_sync(self._operations.inbox()) def get_reading_list(self) -> list[Document]: - """Get all documents in the reading list. - - Returns: - List of reading list documents. - """ - return list(self._client.v3.get_reading_list()) + return run_sync(self._operations.later()) def get_archive(self) -> list[Document]: - """Get all archived documents. - - Returns: - List of archived documents. - """ - return list(self._client.v3.get_archive()) + return run_sync(self._operations.archive()) def get_documents_since( self, @@ -70,90 +55,24 @@ def get_documents_since( hours: int | None = None, since: datetime | None = None, ) -> list[Document]: - """Get documents updated since a given time. - - Args: - days: Number of days to look back. - hours: Number of hours to look back. - since: Specific datetime to look back to. - - Returns: - List of documents updated since the given time. - """ - if since is None: - if days is not None: - since = datetime.now(UTC) - timedelta(days=days) - elif hours is not None: - since = datetime.now(UTC) - timedelta(hours=hours) - else: - raise ValueError("Must specify days, hours, or since") - - return list(self._client.v3.list_documents(updated_after=since)) + return run_sync(self._operations.since(days=days, hours=hours, since=since)) def move_to_later(self, document_id: str) -> None: - """Move a document to the reading list. - - Args: - document_id: The document ID. - """ - self._client.v3.move_to_later(document_id) + run_sync(self._operations.move(document_id, DocumentLocation.LATER)) def archive(self, document_id: str) -> None: - """Archive a document. - - Args: - document_id: The document ID. - """ - self._client.v3.archive(document_id) + run_sync(self._operations.move(document_id, DocumentLocation.ARCHIVE)) def move_to_inbox(self, document_id: str) -> None: - """Move a document back to the inbox. - - Args: - document_id: The document ID. - """ - self._client.v3.move_to_inbox(document_id) + run_sync(self._operations.move(document_id, DocumentLocation.NEW)) def bulk_archive(self, document_ids: list[str]) -> dict[str, bool]: - """Archive multiple documents. - - Args: - document_ids: List of document IDs. + result = run_sync(self._operations.bulk_move(document_ids, DocumentLocation.ARCHIVE)) + return bulk_result_map(document_ids, result) - Returns: - Dict mapping document ID to success status. - """ - results: dict[str, bool] = {} - for doc_id in document_ids: - try: - self._client.v3.archive(doc_id) - results[doc_id] = True - except Exception: - results[doc_id] = False - return results - - def bulk_tag_documents( - self, - document_ids: list[str], - tags: list[str], - ) -> dict[str, bool]: - """Set tags on multiple documents. - - Args: - document_ids: List of document IDs. - tags: Tags to set on all documents. - - Returns: - Dict mapping document ID to success status. - """ - results: dict[str, bool] = {} - for doc_id in document_ids: - try: - self._client.v3.tag_document(doc_id, tags) - results[doc_id] = True - except Exception: - results[doc_id] = False - return results + def bulk_tag_documents(self, document_ids: list[str], tags: list[str]) -> dict[str, bool]: + result = run_sync(self._operations.bulk_set_tags(document_ids, tags)) + return bulk_result_map(document_ids, result) def filter_documents( self, @@ -161,18 +80,7 @@ def filter_documents( *, location: DocumentLocation | None = None, ) -> Iterator[Document]: - """Filter documents using a custom predicate. - - Args: - predicate: A function that returns True for documents to include. - location: Optional location to filter by first. - - Yields: - Documents that match the predicate. - """ - for doc in self._client.v3.list_documents(location=location): - if predicate(doc): - yield doc + return iter_sync(self._operations.filter(predicate, location=location)) def search_documents( self, @@ -181,87 +89,28 @@ def search_documents( case_sensitive: bool = False, location: DocumentLocation | None = None, ) -> list[Document]: - """Search documents by title, author, or summary. - - Args: - query: The search query. - case_sensitive: Whether to perform case-sensitive search. - location: Optional location to filter by. - - Returns: - List of matching documents. - """ - if not case_sensitive: - query = query.lower() - - results = [] - for doc in self._client.v3.list_documents(location=location): - title = (doc.title or "") if case_sensitive else (doc.title or "").lower() - author = (doc.author or "") if case_sensitive else (doc.author or "").lower() - summary = (doc.summary or "") if case_sensitive else (doc.summary or "").lower() - - if query in title or query in author or query in summary: - results.append(doc) - - return results - - def get_inbox_stats(self) -> InboxStats: - """Get statistics about the reading inbox. - - Returns: - InboxStats with counts and oldest/newest items. - """ - inbox = list(self._client.v3.get_inbox()) - reading_list = list(self._client.v3.get_reading_list()) - archive = list(self._client.v3.get_archive()) - - # Count by category - by_category: Counter[str] = Counter() - for doc in inbox + reading_list: - cat = doc.category.value if doc.category else "unknown" - by_category[cat] += 1 - - # Find oldest/newest inbox items - oldest = None - newest = None - if inbox: - sorted_inbox = sorted( - inbox, - key=lambda d: d.created_at or datetime.min.replace(tzinfo=UTC), + return run_sync( + self._operations.search_items( + query, + case_sensitive=case_sensitive, + location=location, ) - oldest = sorted_inbox[0] - newest = sorted_inbox[-1] + ) + def get_inbox_stats(self) -> InboxStats: + result = run_sync(self._operations.statistics()) return InboxStats( - inbox_count=len(inbox), - reading_list_count=len(reading_list), - archive_count=len(archive), - total_count=len(inbox) + len(reading_list) + len(archive), - by_category=dict(by_category), - oldest_inbox_item=oldest, - newest_inbox_item=newest, + inbox_count=result.inbox_count, + reading_list_count=result.reading_list_count, + archive_count=result.archive_count, + total_count=result.total_count, + by_category=result.by_category, + oldest_inbox_item=result.oldest_inbox_item, + newest_inbox_item=result.newest_inbox_item, ) - def get_documents_by_category( - self, - category: DocumentCategory, - ) -> list[Document]: - """Get all documents of a specific category. - - Args: - category: The category to filter by. - - Returns: - List of documents in the category. - """ - return list(self._client.v3.list_documents(category=category)) + def get_documents_by_category(self, category: DocumentCategory) -> list[Document]: + return run_sync(self._operations.by_category(category)) def get_unread_count(self) -> int: - """Get the count of unread documents (inbox + reading list). - - Returns: - Count of unread documents. - """ - inbox = len(list(self._client.v3.get_inbox())) - reading_list = len(list(self._client.v3.get_reading_list())) - return inbox + reading_list + return run_sync(self._operations.unread_count()) diff --git a/src/readwise_sdk/managers/highlights.py b/src/readwise_sdk/managers/highlights.py index ff20417..a5a6942 100644 --- a/src/readwise_sdk/managers/highlights.py +++ b/src/readwise_sdk/managers/highlights.py @@ -1,10 +1,17 @@ -"""High-level highlight management operations.""" +"""Legacy highlight manager compatibility shim.""" from __future__ import annotations -from datetime import UTC, datetime, timedelta +from datetime import datetime from typing import TYPE_CHECKING +from readwise_sdk.operations.compat import ( + SyncHighlightsResource, + bulk_result_map, + iter_sync, + run_sync, +) +from readwise_sdk.operations.highlights import HighlightOperations from readwise_sdk.v2.models import Highlight, HighlightCreate if TYPE_CHECKING: @@ -14,23 +21,15 @@ class HighlightManager: - """High-level operations for managing highlights.""" + """Compatibility wrapper over canonical highlight operations.""" def __init__(self, client: ReadwiseClient) -> None: - """Initialize the highlight manager. - - Args: - client: The Readwise client. - """ self._client = client + resource = SyncHighlightsResource(client) + self._operations = HighlightOperations(resource, resource, resource) def get_all_highlights(self) -> list[Highlight]: - """Get all highlights, exhausting pagination. - - Returns: - List of all highlights. - """ - return list(self._client.v2.list_highlights()) + return run_sync(self._operations.list()) def get_highlights_since( self, @@ -39,44 +38,13 @@ def get_highlights_since( hours: int | None = None, since: datetime | None = None, ) -> list[Highlight]: - """Get highlights updated since a given time. - - Args: - days: Number of days to look back. - hours: Number of hours to look back. - since: Specific datetime to look back to. - - Returns: - List of highlights updated since the given time. - """ - if since is None: - if days is not None: - since = datetime.now(UTC) - timedelta(days=days) - elif hours is not None: - since = datetime.now(UTC) - timedelta(hours=hours) - else: - raise ValueError("Must specify days, hours, or since") - - return list(self._client.v2.list_highlights(updated_after=since)) + return run_sync(self._operations.since(days=days, hours=hours, since=since)) def get_highlights_by_book(self, book_id: int) -> list[Highlight]: - """Get all highlights for a specific book. - - Args: - book_id: The book ID. - - Returns: - List of highlights for the book. - """ - return list(self._client.v2.list_highlights(book_id=book_id)) + return run_sync(self._operations.list(book_id=book_id)) def get_highlights_with_notes(self) -> list[Highlight]: - """Get all highlights that have notes/annotations. - - Returns: - List of highlights with notes. - """ - return [h for h in self._client.v2.list_highlights() if h.note] + return run_sync(self._operations.with_notes()) def search_highlights( self, @@ -84,93 +52,21 @@ def search_highlights( *, case_sensitive: bool = False, ) -> list[Highlight]: - """Search highlights by text content. - - Args: - query: The search query. - case_sensitive: Whether to perform case-sensitive search. - - Returns: - List of matching highlights. - """ - if not case_sensitive: - query = query.lower() - - results = [] - for highlight in self._client.v2.list_highlights(): - text = highlight.text if case_sensitive else highlight.text.lower() - note = (highlight.note or "") if case_sensitive else (highlight.note or "").lower() - - if query in text or query in note: - results.append(highlight) - - return results + return run_sync(self._operations.search_items(query, case_sensitive=case_sensitive)) def filter_highlights( self, predicate: Callable[[Highlight], bool], ) -> Iterator[Highlight]: - """Filter highlights using a custom predicate. + return iter_sync(self._operations.filter(predicate)) - Args: - predicate: A function that returns True for highlights to include. + def bulk_tag(self, highlight_ids: list[int], tag: str) -> dict[int, bool]: + result = run_sync(self._operations.bulk_tag(highlight_ids, tag)) + return bulk_result_map(highlight_ids, result) - Yields: - Highlights that match the predicate. - """ - for highlight in self._client.v2.list_highlights(): - if predicate(highlight): - yield highlight - - def bulk_tag( - self, - highlight_ids: list[int], - tag: str, - ) -> dict[int, bool]: - """Add a tag to multiple highlights. - - Args: - highlight_ids: List of highlight IDs to tag. - tag: The tag name to add. - - Returns: - Dict mapping highlight ID to success status. - """ - results: dict[int, bool] = {} - for hid in highlight_ids: - try: - self._client.v2.create_highlight_tag(hid, tag) - results[hid] = True - except Exception: - results[hid] = False - return results - - def bulk_untag( - self, - highlight_ids: list[int], - tag: str, - ) -> dict[int, bool]: - """Remove a tag from multiple highlights. - - Args: - highlight_ids: List of highlight IDs. - tag: The tag name to remove. - - Returns: - Dict mapping highlight ID to success status. - """ - results: dict[int, bool] = {} - for hid in highlight_ids: - try: - # Find the tag ID first - tags = list(self._client.v2.list_highlight_tags(hid)) - tag_obj = next((t for t in tags if t.name == tag), None) - if tag_obj: - self._client.v2.delete_highlight_tag(hid, tag_obj.id) - results[hid] = True - except Exception: - results[hid] = False - return results + def bulk_untag(self, highlight_ids: list[int], tag: str) -> dict[int, bool]: + result = run_sync(self._operations.bulk_untag(highlight_ids, tag)) + return bulk_result_map(highlight_ids, result) def create_highlight( self, @@ -181,35 +77,15 @@ def create_highlight( note: str | None = None, source_url: str | None = None, ) -> int: - """Create a single highlight (convenience method). - - Args: - text: The highlight text. - title: The source title. - author: The source author. - note: An optional note/annotation. - source_url: The source URL. - - Returns: - The created highlight ID. - """ - highlight = HighlightCreate( + request = HighlightCreate( text=text, title=title, author=author, note=note, source_url=source_url, ) - ids = self._client.v2.create_highlights([highlight]) + ids = run_sync(self._operations.create(request)) return ids[0] if ids else 0 def get_highlight_count(self) -> int: - """Get the total number of highlights. - - Returns: - Total highlight count. - """ - count = 0 - for _ in self._client.v2.list_highlights(): - count += 1 - return count + return run_sync(self._operations.count()) diff --git a/src/readwise_sdk/operations/auth.py b/src/readwise_sdk/operations/auth.py new file mode 100644 index 0000000..7095ed9 --- /dev/null +++ b/src/readwise_sdk/operations/auth.py @@ -0,0 +1,22 @@ +"""Canonical authentication operations.""" + +from __future__ import annotations + +from typing import Protocol + + +class TokenResource(Protocol): + async def validate_token(self) -> bool: ... + + +class AuthOperations: + """Own authentication checks independently of compatibility adapters.""" + + def __init__(self, resource: TokenResource) -> None: + self._resource = resource + + async def validate_token(self) -> bool: + return await self._resource.validate_token() + + +__all__ = ["AuthOperations", "TokenResource"] diff --git a/src/readwise_sdk/operations/compat.py b/src/readwise_sdk/operations/compat.py new file mode 100644 index 0000000..741f983 --- /dev/null +++ b/src/readwise_sdk/operations/compat.py @@ -0,0 +1,276 @@ +"""Compatibility adapters that let legacy clients use canonical operations. + +The canonical operation classes are async-first. These adapters expose the +existing sync and async versioned clients through the resource protocols those +operations consume. Sync adapters deliberately never suspend, which lets the +legacy synchronous shims drive them in the caller's thread. +""" + +from __future__ import annotations + +from collections.abc import AsyncIterator, Awaitable, Iterator +from typing import Any, cast + +from readwise_sdk.models import BulkResult +from readwise_sdk.v2.models import HighlightCreate, HighlightUpdate +from readwise_sdk.v3.models import DocumentCreate, DocumentLocation, DocumentUpdate + + +def run_sync[ResultT](awaitable: Awaitable[ResultT]) -> ResultT: + """Drive a non-suspending compatibility coroutine in the current thread.""" + iterator = awaitable.__await__() + try: + next(iterator) + except StopIteration as completed: + return cast(ResultT, completed.value) + finally: + iterator.close() + raise RuntimeError("A synchronous compatibility resource unexpectedly suspended") + + +def iter_sync[ItemT](iterator: AsyncIterator[ItemT]) -> Iterator[ItemT]: + """Adapt a non-suspending async iterator without sacrificing laziness.""" + while True: + try: + yield run_sync(iterator.__anext__()) + except StopAsyncIteration: + return + + +def bulk_result_map[ItemT](items: list[ItemT], result: BulkResult[ItemT]) -> dict[ItemT, bool]: + """Convert a typed bulk result to the complete ordered legacy bool map.""" + failed = {cast(ItemT, failure.item) for failure in result.failures} + return {item: item not in failed for item in items} + + +class SyncHighlightsResource: + """Expose a synchronous legacy v2 client as async-first resources.""" + + def __init__(self, client: Any) -> None: + self._client = client + + async def iter(self, **kwargs: Any) -> AsyncIterator[Any]: + kwargs.pop("page_size", None) + for item in self._client.v2.list_highlights(**_without_none(kwargs)): + yield item + + async def get(self, highlight_id: int) -> Any: + return self._client.v2.get_highlight(highlight_id) + + async def create(self, highlights: list[HighlightCreate]) -> list[int]: + return self._client.v2.create_highlights(highlights) + + async def update(self, highlight_id: int, update: HighlightUpdate) -> Any: + return self._client.v2.update_highlight(highlight_id, update) + + async def delete(self, highlight_id: int) -> None: + self._client.v2.delete_highlight(highlight_id) + + async def iter_highlight(self, highlight_id: int) -> AsyncIterator[Any]: + for item in self._client.v2.list_highlight_tags(highlight_id): + yield item + + async def create_highlight(self, highlight_id: int, name: str) -> Any: + return self._client.v2.create_highlight_tag(highlight_id, name) + + async def delete_highlight(self, highlight_id: int, tag_id: int) -> None: + self._client.v2.delete_highlight_tag(highlight_id, tag_id) + + async def export(self, **kwargs: Any) -> AsyncIterator[Any]: + for item in self._client.v2.export_highlights(**_without_none(kwargs)): + yield item + + async def validate_token(self) -> bool: + return self._client.validate_token() + + +class AsyncHighlightsResource: + """Expose an asynchronous legacy v2 client as canonical resources.""" + + def __init__(self, client: Any) -> None: + self._client = client + + async def iter(self, **kwargs: Any) -> AsyncIterator[Any]: + kwargs.pop("page_size", None) + async for item in self._client.v2.list_highlights(**_without_none(kwargs)): + yield item + + async def get(self, highlight_id: int) -> Any: + return await self._client.v2.get_highlight(highlight_id) + + async def create(self, highlights: list[HighlightCreate]) -> list[int]: + return await self._client.v2.create_highlights(highlights) + + async def update(self, highlight_id: int, update: HighlightUpdate) -> Any: + return await self._client.v2.update_highlight(highlight_id, update) + + async def delete(self, highlight_id: int) -> None: + await self._client.v2.delete_highlight(highlight_id) + + async def iter_highlight(self, highlight_id: int) -> AsyncIterator[Any]: + async for item in self._client.v2.list_highlight_tags(highlight_id): + yield item + + async def create_highlight(self, highlight_id: int, name: str) -> Any: + return await self._client.v2.create_highlight_tag(highlight_id, name) + + async def delete_highlight(self, highlight_id: int, tag_id: int) -> None: + await self._client.v2.delete_highlight_tag(highlight_id, tag_id) + + async def export(self, **kwargs: Any) -> AsyncIterator[Any]: + async for item in self._client.v2.export_highlights(**_without_none(kwargs)): + yield item + + async def validate_token(self) -> bool: + return await self._client.validate_token() + + +class SyncBooksResource: + def __init__(self, client: Any) -> None: + self._client = client + + async def iter(self, **kwargs: Any) -> AsyncIterator[Any]: + kwargs.pop("page_size", None) + for item in self._client.v2.list_books(**_without_none(kwargs)): + yield item + + async def get(self, book_id: int) -> Any: + return self._client.v2.get_book(book_id) + + +class AsyncBooksResource: + def __init__(self, client: Any) -> None: + self._client = client + + async def iter(self, **kwargs: Any) -> AsyncIterator[Any]: + kwargs.pop("page_size", None) + async for item in self._client.v2.list_books(**_without_none(kwargs)): + yield item + + async def get(self, book_id: int) -> Any: + return await self._client.v2.get_book(book_id) + + +class SyncDocumentsResource: + def __init__(self, client: Any, *, manager_compat: bool = False) -> None: + self._client = client + self._manager_compat = manager_compat + + async def iter(self, **kwargs: Any) -> AsyncIterator[Any]: + source = self._document_iterator(kwargs) + for item in source: + yield item + + def _document_iterator(self, kwargs: dict[str, Any]) -> Iterator[Any]: + location = kwargs.get("location") + if self._manager_compat and _is_plain_view(kwargs): + if location == DocumentLocation.NEW: + return self._client.v3.get_inbox() + if location == DocumentLocation.LATER: + return self._client.v3.get_reading_list() + if location == DocumentLocation.ARCHIVE: + return self._client.v3.get_archive() + return self._client.v3.list_documents(**_without_none(kwargs)) + + async def get(self, document_id: str, *, with_content: bool = False) -> Any: + return self._client.v3.get_document(document_id, with_content=with_content) + + async def create(self, document: DocumentCreate) -> Any: + return self._client.v3.create_document(document) + + async def save_url(self, url: str, **kwargs: Any) -> Any: + return self._client.v3.save_url(url, **kwargs) + + async def update(self, document_id: str, update: DocumentUpdate) -> Any: + if self._manager_compat: + fields = update.model_dump(exclude_none=True) + if set(fields) == {"location"}: + location = update.location + if location == DocumentLocation.NEW: + return self._client.v3.move_to_inbox(document_id) + if location == DocumentLocation.LATER: + return self._client.v3.move_to_later(document_id) + if location == DocumentLocation.ARCHIVE: + return self._client.v3.archive(document_id) + if set(fields) == {"tags"}: + return self._client.v3.tag_document(document_id, update.tags or []) + return self._client.v3.update_document(document_id, update) + + async def delete(self, document_id: str) -> None: + self._client.v3.delete_document(document_id) + + +class AsyncDocumentsResource: + def __init__(self, client: Any, *, manager_compat: bool = False) -> None: + self._client = client + self._manager_compat = manager_compat + + async def iter(self, **kwargs: Any) -> AsyncIterator[Any]: + source = self._document_iterator(kwargs) + async for item in source: + yield item + + def _document_iterator(self, kwargs: dict[str, Any]) -> AsyncIterator[Any]: + location = kwargs.get("location") + if self._manager_compat and _is_plain_view(kwargs): + if location == DocumentLocation.NEW: + return self._client.v3.get_inbox() + if location == DocumentLocation.LATER: + return self._client.v3.get_reading_list() + if location == DocumentLocation.ARCHIVE: + return self._client.v3.get_archive() + return self._client.v3.list_documents(**_without_none(kwargs)) + + async def get(self, document_id: str, *, with_content: bool = False) -> Any: + return await self._client.v3.get_document(document_id, with_content=with_content) + + async def create(self, document: DocumentCreate) -> Any: + return await self._client.v3.create_document(document) + + async def save_url(self, url: str, **kwargs: Any) -> Any: + return await self._client.v3.save_url(url, **kwargs) + + async def update(self, document_id: str, update: DocumentUpdate) -> Any: + if self._manager_compat: + fields = update.model_dump(exclude_none=True) + if set(fields) == {"location"}: + location = update.location + if location == DocumentLocation.NEW: + return await self._client.v3.move_to_inbox(document_id) + if location == DocumentLocation.LATER: + return await self._client.v3.move_to_later(document_id) + if location == DocumentLocation.ARCHIVE: + return await self._client.v3.archive(document_id) + if set(fields) == {"tags"}: + return await self._client.v3.tag_document(document_id, update.tags or []) + return await self._client.v3.update_document(document_id, update) + + async def delete(self, document_id: str) -> None: + await self._client.v3.delete_document(document_id) + + +def _without_none(values: dict[str, Any]) -> dict[str, Any]: + return {key: value for key, value in values.items() if value is not None} + + +def _is_plain_view(kwargs: dict[str, Any]) -> bool: + return ( + kwargs.get("location") is not None + and kwargs.get("category") is None + and kwargs.get("updated_after") is None + and kwargs.get("tags") is None + and not kwargs.get("with_content", False) + ) + + +__all__ = [ + "AsyncBooksResource", + "AsyncDocumentsResource", + "AsyncHighlightsResource", + "SyncBooksResource", + "SyncDocumentsResource", + "SyncHighlightsResource", + "bulk_result_map", + "iter_sync", + "run_sync", +] diff --git a/src/readwise_sdk/operations/documents.py b/src/readwise_sdk/operations/documents.py index fd7ed13..d39e371 100644 --- a/src/readwise_sdk/operations/documents.py +++ b/src/readwise_sdk/operations/documents.py @@ -3,9 +3,9 @@ from __future__ import annotations from collections import Counter -from collections.abc import AsyncIterator +from collections.abc import AsyncIterator, Callable from dataclasses import dataclass -from datetime import UTC, datetime +from datetime import UTC, datetime, timedelta from typing import Protocol from readwise_sdk.errors import NotFoundError @@ -266,6 +266,60 @@ async def statistics(self) -> DocumentStatistics: items_older_than_90_days=sum(age > 90 for age in ages_days), ) + async def since( + self, + *, + days: int | None = None, + hours: int | None = None, + since: datetime | None = None, + ) -> list[Document]: + """Reproduce the manager's time-window precedence and validation.""" + if since is None: + if days is not None: + since = datetime.now(UTC) - timedelta(days=days) + elif hours is not None: + since = datetime.now(UTC) - timedelta(hours=hours) + else: + raise ValueError("Must specify days, hours, or since") + return [item async for item in self._resource.iter(updated_after=since)] + + async def filter( + self, + predicate: Callable[[Document], bool], + *, + location: DocumentLocation | None = None, + ) -> AsyncIterator[Document]: + """Retain manager-compatible lazy predicate filtering.""" + async for document in self._resource.iter(location=location): + if predicate(document): + yield document + + async def search_items( + self, + query: str, + *, + case_sensitive: bool = False, + location: DocumentLocation | None = None, + ) -> list[Document]: + """Search the title, author, and summary using legacy semantics.""" + normalized = query if case_sensitive else query.lower() + results: list[Document] = [] + async for document in self._resource.iter(location=location): + fields = (document.title or "", document.author or "", document.summary or "") + if not case_sensitive: + fields = tuple(field.lower() for field in fields) + if any(normalized in field for field in fields): + results.append(document) + return results + + async def by_category(self, category: DocumentCategory) -> list[Document]: + """Materialize documents in one Reader category.""" + return [item async for item in self._resource.iter(category=category)] + + async def unread_count(self) -> int: + """Count inbox and reading-list documents using legacy requests.""" + return len(await self.inbox()) + len(await self.later()) + async def bulk_move( self, document_ids: list[str], diff --git a/src/readwise_sdk/operations/imports.py b/src/readwise_sdk/operations/imports.py new file mode 100644 index 0000000..53993db --- /dev/null +++ b/src/readwise_sdk/operations/imports.py @@ -0,0 +1,210 @@ +"""Canonical Reader document import operations.""" + +from __future__ import annotations + +import builtins +import re +from collections.abc import AsyncIterator +from dataclasses import dataclass +from datetime import datetime +from typing import Any, Protocol +from urllib.parse import urlparse + +from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation + +WORDS_PER_MINUTE = 200 + + +class ImportDocumentsResource(Protocol): + async def get(self, document_id: str, *, with_content: bool = False) -> Document | None: ... + + def iter(self, **kwargs: Any) -> AsyncIterator[Document]: ... + + async def save_url(self, url: str, **kwargs: Any) -> Any: ... + + +@dataclass(frozen=True, slots=True) +class ImportedDocumentData: + id: str + url: str + title: str | None + author: str | None + category: DocumentCategory | None + location: DocumentLocation | None + tags: list[str] + created_at: datetime | None + updated_at: datetime | None + html_content: str | None = None + clean_text: str | None = None + domain: str | None = None + word_count: int | None = None + reading_time_minutes: int | None = None + summary: str | None = None + image_url: str | None = None + reading_progress: float | None = None + first_opened_at: datetime | None = None + last_opened_at: datetime | None = None + + +@dataclass(frozen=True, slots=True) +class DocumentImportResult: + document_id: str + document: ImportedDocumentData | None = None + error: Exception | None = None + + @property + def success(self) -> bool: + return self.error is None and self.document is not None + + +def extract_domain(url: str) -> str | None: + """Extract a domain using the importer's pinned lenient behavior.""" + try: + domain = urlparse(url).netloc + if domain.startswith("www."): + domain = domain[4:] + return domain or None + except Exception: + return None + + +def html_to_text(html: str) -> str: + """Convert HTML to text using BeautifulSoup when it is installed.""" + try: + from bs4 import BeautifulSoup # type: ignore[import-not-found] + + soup = BeautifulSoup(html, "html.parser") + for script in soup(["script", "style", "nav", "footer", "header"]): + script.decompose() + return soup.get_text(separator=" ", strip=True) + except ImportError: + text = re.sub(r"]*>.*?", "", html, flags=re.DOTALL | re.I) + text = re.sub(r"]*>.*?", "", text, flags=re.DOTALL | re.I) + text = re.sub(r"<[^>]+>", " ", text) + text = text.replace(" ", " ") + text = text.replace("&", "&") + text = text.replace("<", "<") + text = text.replace(">", ">") + text = text.replace(""", '"') + text = text.replace("'", "'") + return re.sub(r"\s+", " ", text).strip() + + +def import_document_data( + document: Document, + *, + extract_metadata: bool = True, + clean_html: bool = True, +) -> ImportedDocumentData: + """Project a Reader document into the importer contract.""" + clean_text = html_to_text(document.content) if clean_html and document.content else None + word_count = document.word_count + reading_time = document.reading_time + if extract_metadata and clean_text: + if word_count is None: + word_count = len(clean_text.split()) + if reading_time is None and word_count: + reading_time = max(1, word_count // WORDS_PER_MINUTE) + return ImportedDocumentData( + id=document.id, + url=document.url, + title=document.title, + author=document.author, + category=document.category, + location=document.location, + tags=document.tags, + created_at=document.created_at, + updated_at=document.updated_at, + html_content=document.content, + clean_text=clean_text, + domain=extract_domain(document.url) if extract_metadata and document.url else None, + word_count=word_count, + reading_time_minutes=reading_time, + summary=document.summary, + image_url=document.image_url, + reading_progress=document.reading_progress, + first_opened_at=document.first_opened_at, + last_opened_at=document.last_opened_at, + ) + + +class DocumentImportOperations: + """Own import projection, batching, limits, and partial failures.""" + + def __init__( + self, + resource: ImportDocumentsResource, + *, + extract_metadata: bool = True, + clean_html: bool = True, + ) -> None: + self._resource = resource + self._extract_metadata = extract_metadata + self._clean_html = clean_html + + def project(self, document: Document) -> ImportedDocumentData: + return import_document_data( + document, + extract_metadata=self._extract_metadata, + clean_html=self._clean_html, + ) + + async def import_document( + self, + document_id: str, + *, + with_content: bool = True, + ) -> ImportedDocumentData: + document = await self._resource.get(document_id, with_content=with_content) + if document is None: + raise ValueError(f"Document {document_id} not found") + return self.project(document) + + async def import_batch( + self, + document_ids: builtins.list[str], + *, + with_content: bool = True, + ) -> builtins.list[DocumentImportResult]: + results: builtins.list[DocumentImportResult] = [] + for document_id in document_ids: + try: + document = await self.import_document(document_id, with_content=with_content) + results.append(DocumentImportResult(document_id, document=document)) + except Exception as error: + results.append(DocumentImportResult(document_id, error=error)) + return results + + async def list( + self, + *, + location: DocumentLocation | None = None, + updated_after: datetime | None = None, + limit: int | None = None, + with_content: bool = False, + ) -> builtins.list[ImportedDocumentData]: + results: builtins.list[ImportedDocumentData] = [] + index = 0 + async for document in self._resource.iter( + location=location, + updated_after=updated_after, + with_content=with_content, + ): + if limit and index >= limit: + break + results.append(self.project(document)) + index += 1 + return results + + async def save_url(self, url: str, **kwargs: Any) -> str: + return (await self._resource.save_url(url, **kwargs)).id + + +__all__ = [ + "DocumentImportOperations", + "DocumentImportResult", + "ImportedDocumentData", + "extract_domain", + "html_to_text", + "import_document_data", +] diff --git a/src/readwise_sdk/operations/inbox.py b/src/readwise_sdk/operations/inbox.py new file mode 100644 index 0000000..ed14941 --- /dev/null +++ b/src/readwise_sdk/operations/inbox.py @@ -0,0 +1,180 @@ +"""Canonical reading-inbox workflow operations.""" + +from __future__ import annotations + +from collections.abc import Callable +from dataclasses import dataclass +from datetime import UTC, datetime, timedelta +from typing import Protocol + +from readwise_sdk.models import BulkResult +from readwise_sdk.operations.documents import DocumentOperations +from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation + + +class ArchiveRuleLike(Protocol): + name: str + condition: Callable[[Document], bool] + enabled: bool + + +@dataclass(frozen=True, slots=True) +class QueueStatistics: + inbox_count: int + reading_list_count: int + total_unread: int + oldest_item_age_days: int | None + average_age_days: float | None + by_category: dict[str, int] + items_older_than_30_days: int + items_older_than_90_days: int + + +@dataclass(frozen=True, slots=True) +class InboxTriageAction: + document_id: str + document_title: str | None + action: str + reason: str | None = None + + +class ReadingInboxOperations: + """Own rules, queue selection, triage, and suppression semantics.""" + + def __init__(self, documents: DocumentOperations) -> None: + self._documents = documents + self._archive_rules: list[ArchiveRuleLike] = [] + + def add_archive_rule(self, rule: ArchiveRuleLike) -> None: + self._archive_rules.append(rule) + + def remove_archive_rule(self, name: str) -> bool: + for index, rule in enumerate(self._archive_rules): + if rule.name == name: + self._archive_rules.pop(index) + return True + return False + + def get_archive_rules(self) -> list[ArchiveRuleLike]: + return list(self._archive_rules) + + async def queue_statistics(self) -> QueueStatistics: + statistics = await self._documents.statistics() + return QueueStatistics( + inbox_count=statistics.inbox_count, + reading_list_count=statistics.reading_list_count, + total_unread=statistics.total_unread, + oldest_item_age_days=statistics.oldest_item_age_days, + average_age_days=statistics.average_age_days, + by_category=statistics.by_category, + items_older_than_30_days=statistics.items_older_than_30_days, + items_older_than_90_days=statistics.items_older_than_90_days, + ) + + async def smart_archive(self, *, dry_run: bool = False) -> list[InboxTriageAction]: + actions: list[InboxTriageAction] = [] + for document in await self._documents.inbox(): + for rule in self._archive_rules: + if not rule.enabled: + continue + if rule.condition(document): + actions.append( + InboxTriageAction( + document.id, + document.title, + "archive", + f"Matched rule: {rule.name}", + ) + ) + if not dry_run: + try: + await self._documents.move(document.id, DocumentLocation.ARCHIVE) + except Exception: + pass + break + return actions + + async def stale_items( + self, + *, + days: int = 30, + location: DocumentLocation | None = None, + ) -> list[Document]: + cutoff = datetime.now(UTC) - timedelta(days=days) + return [ + document + async for document in self._documents.filter( + lambda item: item.created_at is not None and item.created_at < cutoff, + location=location, + ) + ] + + async def archive_stale( + self, + *, + days: int = 90, + dry_run: bool = False, + ) -> list[InboxTriageAction]: + stale = await self.stale_items(days=days, location=DocumentLocation.NEW) + stale.extend(await self.stale_items(days=days, location=DocumentLocation.LATER)) + actions: list[InboxTriageAction] = [] + for document in stale: + actions.append( + InboxTriageAction( + document.id, + document.title, + "archive", + f"Older than {days} days", + ) + ) + if not dry_run: + try: + await self._documents.move(document.id, DocumentLocation.ARCHIVE) + except Exception: + pass + return actions + + async def move_to_reading_list(self, document_ids: list[str]) -> BulkResult[str]: + return await self._documents.bulk_move(document_ids, DocumentLocation.LATER) + + async def inbox_by_priority(self) -> list[Document]: + documents = await self._documents.inbox() + + def priority_key(document: Document) -> tuple[int, int, int]: + category_priority = { + DocumentCategory.ARTICLE: 0, + DocumentCategory.EMAIL: 1, + DocumentCategory.RSS: 2, + DocumentCategory.PDF: 3, + DocumentCategory.EPUB: 4, + DocumentCategory.TWEET: 5, + DocumentCategory.VIDEO: 6, + } + category = category_priority.get(document.category, 99) if document.category else 99 + age = (datetime.now(UTC) - document.created_at).days if document.created_at else 0 + title_length = len(document.title) if document.title else 0 + return category, age, title_length + + return sorted(documents, key=priority_key) + + async def search_inbox( + self, + query: str, + *, + case_sensitive: bool = False, + ) -> list[Document]: + return await self._documents.search_items( + query, + case_sensitive=case_sensitive, + location=DocumentLocation.NEW, + ) + + async def inbox_categories(self) -> dict[DocumentCategory, list[Document]]: + groups: dict[DocumentCategory, list[Document]] = {} + for document in await self._documents.inbox(): + if document.category: + groups.setdefault(document.category, []).append(document) + return groups + + +__all__ = ["InboxTriageAction", "QueueStatistics", "ReadingInboxOperations"] diff --git a/src/readwise_sdk/workflows/inbox.py b/src/readwise_sdk/workflows/inbox.py index d40318b..ab8c229 100644 --- a/src/readwise_sdk/workflows/inbox.py +++ b/src/readwise_sdk/workflows/inbox.py @@ -1,12 +1,15 @@ -"""Reading inbox management workflows.""" +"""Legacy reading-inbox workflow compatibility shim.""" from __future__ import annotations import re from dataclasses import dataclass -from datetime import UTC, datetime, timedelta -from typing import TYPE_CHECKING +from datetime import UTC, datetime +from typing import TYPE_CHECKING, cast +from readwise_sdk.operations.compat import SyncDocumentsResource, bulk_result_map, run_sync +from readwise_sdk.operations.documents import DocumentOperations +from readwise_sdk.operations.inbox import InboxTriageAction, ReadingInboxOperations from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation if TYPE_CHECKING: @@ -17,8 +20,6 @@ @dataclass class ArchiveRule: - """A rule for auto-archiving documents.""" - name: str condition: Callable[[Document], bool] enabled: bool = True @@ -26,8 +27,6 @@ class ArchiveRule: @dataclass class QueueStats: - """Statistics about the reading queue.""" - inbox_count: int reading_list_count: int total_unread: int @@ -40,139 +39,51 @@ class QueueStats: @dataclass class TriageAction: - """An action taken during triage.""" - document_id: str document_title: str | None - action: str # "archive", "later", "keep", "skip" + action: str reason: str | None = None +def _legacy_action(action: InboxTriageAction) -> TriageAction: + return TriageAction(action.document_id, action.document_title, action.action, action.reason) + + class ReadingInbox: - """Workflow utilities for managing the reading inbox.""" + """Compatibility wrapper over canonical reading-inbox operations.""" def __init__(self, client: ReadwiseClient) -> None: - """Initialize the reading inbox workflow. - - Args: - client: The Readwise client. - """ self._client = client - self._archive_rules: list[ArchiveRule] = [] + documents = DocumentOperations(SyncDocumentsResource(client, manager_compat=True)) + self._operations = ReadingInboxOperations(documents) def add_archive_rule(self, rule: ArchiveRule) -> None: - """Add an auto-archive rule. - - Args: - rule: The archive rule to add. - """ - self._archive_rules.append(rule) + self._operations.add_archive_rule(rule) def remove_archive_rule(self, name: str) -> bool: - """Remove an archive rule by name. - - Args: - name: Name of the rule to remove. - - Returns: - True if the rule was found and removed. - """ - for i, rule in enumerate(self._archive_rules): - if rule.name == name: - self._archive_rules.pop(i) - return True - return False + return self._operations.remove_archive_rule(name) def get_archive_rules(self) -> list[ArchiveRule]: - """Get all configured archive rules. - - Returns: - List of archive rules. - """ - return list(self._archive_rules) + return cast(list[ArchiveRule], self._operations.get_archive_rules()) def get_queue_stats(self) -> QueueStats: - """Get statistics about the reading queue. - - Returns: - QueueStats with queue information. - """ - inbox = list(self._client.v3.get_inbox()) - reading_list = list(self._client.v3.get_reading_list()) - - all_unread = inbox + reading_list - now = datetime.now(UTC) - - # Calculate ages - ages_days = [] - for doc in all_unread: - if doc.created_at: - age = (now - doc.created_at).days - ages_days.append(age) - - oldest_age = max(ages_days) if ages_days else None - average_age = sum(ages_days) / len(ages_days) if ages_days else None - - # Count by category - by_category: dict[str, int] = {} - for doc in all_unread: - cat = doc.category.value if doc.category else "unknown" - by_category[cat] = by_category.get(cat, 0) + 1 - - # Count old items - items_older_than_30 = sum(1 for age in ages_days if age > 30) - items_older_than_90 = sum(1 for age in ages_days if age > 90) - + result = run_sync(self._operations.queue_statistics()) return QueueStats( - inbox_count=len(inbox), - reading_list_count=len(reading_list), - total_unread=len(all_unread), - oldest_item_age_days=oldest_age, - average_age_days=average_age, - by_category=by_category, - items_older_than_30_days=items_older_than_30, - items_older_than_90_days=items_older_than_90, + result.inbox_count, + result.reading_list_count, + result.total_unread, + result.oldest_item_age_days, + result.average_age_days, + result.by_category, + result.items_older_than_30_days, + result.items_older_than_90_days, ) - def smart_archive( - self, - *, - dry_run: bool = False, - ) -> list[TriageAction]: - """Apply archive rules to inbox items. - - Args: - dry_run: If True, don't actually archive, just report matches. - - Returns: - List of actions taken/would be taken. - """ - actions: list[TriageAction] = [] - inbox = list(self._client.v3.get_inbox()) - - for doc in inbox: - for rule in self._archive_rules: - if not rule.enabled: - continue - - if rule.condition(doc): - actions.append( - TriageAction( - document_id=doc.id, - document_title=doc.title, - action="archive", - reason=f"Matched rule: {rule.name}", - ) - ) - - if not dry_run: - try: - self._client.v3.archive(doc.id) - except Exception: - pass - break # Only apply first matching rule - - return actions + def smart_archive(self, *, dry_run: bool = False) -> list[TriageAction]: + return [ + _legacy_action(item) + for item in run_sync(self._operations.smart_archive(dry_run=dry_run)) + ] def get_stale_items( self, @@ -180,24 +91,7 @@ def get_stale_items( days: int = 30, location: DocumentLocation | None = None, ) -> list[Document]: - """Get documents older than a specified number of days. - - Args: - days: Age threshold in days. - location: Optional location to filter by. - - Returns: - List of stale documents. - """ - cutoff = datetime.now(UTC) - timedelta(days=days) - results = [] - - docs = self._client.v3.list_documents(location=location) - for doc in docs: - if doc.created_at and doc.created_at < cutoff: - results.append(doc) - - return results + return run_sync(self._operations.stale_items(days=days, location=location)) def batch_archive_stale( self, @@ -205,95 +99,17 @@ def batch_archive_stale( days: int = 90, dry_run: bool = False, ) -> list[TriageAction]: - """Archive items older than a specified number of days. - - Args: - days: Age threshold in days. - dry_run: If True, don't actually archive. - - Returns: - List of actions taken/would be taken. - """ - stale = self.get_stale_items(days=days, location=DocumentLocation.NEW) - stale.extend(self.get_stale_items(days=days, location=DocumentLocation.LATER)) - - actions = [] - for doc in stale: - actions.append( - TriageAction( - document_id=doc.id, - document_title=doc.title, - action="archive", - reason=f"Older than {days} days", - ) - ) - - if not dry_run: - try: - self._client.v3.archive(doc.id) - except Exception: - pass - - return actions - - def move_to_reading_list( - self, - document_ids: list[str], - ) -> dict[str, bool]: - """Move documents to reading list. - - Args: - document_ids: List of document IDs to move. - - Returns: - Dict mapping document ID to success status. - """ - results: dict[str, bool] = {} - for doc_id in document_ids: - try: - self._client.v3.move_to_later(doc_id) - results[doc_id] = True - except Exception: - results[doc_id] = False - return results + return [ + _legacy_action(item) + for item in run_sync(self._operations.archive_stale(days=days, dry_run=dry_run)) + ] + + def move_to_reading_list(self, document_ids: list[str]) -> dict[str, bool]: + result = run_sync(self._operations.move_to_reading_list(document_ids)) + return bulk_result_map(document_ids, result) def get_inbox_by_priority(self) -> list[Document]: - """Get inbox items sorted by a priority heuristic. - - Priority is based on: - - Newer items first - - Articles over other categories - - Shorter content over longer (estimated by title length as proxy) - - Returns: - Sorted list of inbox documents. - """ - inbox = list(self._client.v3.get_inbox()) - - def priority_key(doc: Document) -> tuple: - # Category priority (lower is higher priority) - category_priority = { - DocumentCategory.ARTICLE: 0, - DocumentCategory.EMAIL: 1, - DocumentCategory.RSS: 2, - DocumentCategory.PDF: 3, - DocumentCategory.EPUB: 4, - DocumentCategory.TWEET: 5, - DocumentCategory.VIDEO: 6, - } - cat_pri = category_priority.get(doc.category, 99) if doc.category else 99 - - # Age (newer is higher priority, so negative days) - age_days = 0 - if doc.created_at: - age_days = (datetime.now(UTC) - doc.created_at).days - - # Title length as proxy for complexity (shorter is higher priority) - title_len = len(doc.title) if doc.title else 0 - - return (cat_pri, age_days, title_len) - - return sorted(inbox, key=priority_key) + return run_sync(self._operations.inbox_by_priority()) def search_inbox( self, @@ -301,85 +117,37 @@ def search_inbox( *, case_sensitive: bool = False, ) -> list[Document]: - """Search inbox documents by title, author, or summary. - - Args: - query: Search query. - case_sensitive: Whether to perform case-sensitive search. - - Returns: - List of matching documents. - """ - if not case_sensitive: - query = query.lower() - - results = [] - for doc in self._client.v3.get_inbox(): - title = (doc.title or "") if case_sensitive else (doc.title or "").lower() - author = (doc.author or "") if case_sensitive else (doc.author or "").lower() - summary = (doc.summary or "") if case_sensitive else (doc.summary or "").lower() - - if query in title or query in author or query in summary: - results.append(doc) - - return results + return run_sync(self._operations.search_inbox(query, case_sensitive=case_sensitive)) def get_inbox_categories(self) -> dict[DocumentCategory, list[Document]]: - """Get inbox documents grouped by category. - - Returns: - Dict mapping category to list of documents. - """ - groups: dict[DocumentCategory, list[Document]] = {} + return run_sync(self._operations.inbox_categories()) - for doc in self._client.v3.get_inbox(): - if doc.category: - if doc.category not in groups: - groups[doc.category] = [] - groups[doc.category].append(doc) - return groups - - -# Predefined archive rules def create_old_item_rule(days: int = 90) -> ArchiveRule: - """Create a rule to archive items older than N days.""" - def condition(doc: Document) -> bool: if not doc.created_at: return False - age = (datetime.now(UTC) - doc.created_at).days - return age > days + return (datetime.now(UTC) - doc.created_at).days > days return ArchiveRule(name=f"older_than_{days}_days", condition=condition) def create_category_rule(category: DocumentCategory) -> ArchiveRule: - """Create a rule to archive items of a specific category.""" - - def condition(doc: Document) -> bool: - return doc.category == category - - return ArchiveRule(name=f"category_{category.value}", condition=condition) + return ArchiveRule( + name=f"category_{category.value}", + condition=lambda doc: doc.category == category, + ) def create_title_pattern_rule(pattern: str, name: str) -> ArchiveRule: - """Create a rule to archive items matching a title pattern.""" - def condition(doc: Document) -> bool: - if not doc.title: - return False - return bool(re.search(pattern, doc.title, re.IGNORECASE)) + return bool(doc.title and re.search(pattern, doc.title, re.IGNORECASE)) return ArchiveRule(name=name, condition=condition) def create_domain_rule(domain: str) -> ArchiveRule: - """Create a rule to archive items from a specific domain.""" - def condition(doc: Document) -> bool: - if not doc.url: - return False - return domain.lower() in doc.url.lower() + return bool(doc.url and domain.lower() in doc.url.lower()) return ArchiveRule(name=f"domain_{domain}", condition=condition) From 0bf6f6d0402b3b64ff1591957c6bd5971527ca8c Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 01:34:48 -0500 Subject: [PATCH 20/24] refactor: canonicalize model paths to models/ (stage 16) Behavior-preserving. Model definitions moved to models/readwise.py (v2 concepts) and models/reader.py (v3 concepts); v2/models.py and v3/models.py become identity-preserving re-export shims (verified v2.models.HighlightCreate is models.readwise.HighlightCreate, and the v3 equivalent). Internal imports across resources/operations/sdk and mcp/server.py now use canonical paths. Every legacy model import path still resolves to the same class object. Characterization unchanged; gate green (835 passed); deps/uv.lock/Justfile untouched. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/mcp/server.py | 14 +- src/readwise_sdk/models/reader.py | 266 ++++++++++++++++++ src/readwise_sdk/models/readwise.py | 241 +++++++++++++++++ src/readwise_sdk/operations/books.py | 2 +- src/readwise_sdk/operations/compat.py | 4 +- src/readwise_sdk/operations/digests.py | 2 +- src/readwise_sdk/operations/documents.py | 4 +- src/readwise_sdk/operations/highlights.py | 4 +- src/readwise_sdk/operations/imports.py | 2 +- src/readwise_sdk/operations/inbox.py | 2 +- src/readwise_sdk/operations/sync.py | 4 +- src/readwise_sdk/operations/tags.py | 2 +- src/readwise_sdk/resources/v2/books.py | 2 +- src/readwise_sdk/resources/v2/export.py | 2 +- src/readwise_sdk/resources/v2/highlights.py | 2 +- src/readwise_sdk/resources/v2/review.py | 2 +- src/readwise_sdk/resources/v2/tags.py | 2 +- src/readwise_sdk/resources/v3/documents.py | 6 +- src/readwise_sdk/resources/v3/tags.py | 2 +- src/readwise_sdk/sdk/sync.py | 22 +- src/readwise_sdk/v2/models.py | 264 +++--------------- src/readwise_sdk/v3/models.py | 285 ++------------------ 22 files changed, 606 insertions(+), 530 deletions(-) create mode 100644 src/readwise_sdk/models/reader.py create mode 100644 src/readwise_sdk/models/readwise.py diff --git a/src/readwise_sdk/mcp/server.py b/src/readwise_sdk/mcp/server.py index 19adee9..86cfb2c 100644 --- a/src/readwise_sdk/mcp/server.py +++ b/src/readwise_sdk/mcp/server.py @@ -30,6 +30,13 @@ _json_result, ) from readwise_sdk.models import BookSearch, DocumentSearch, HighlightSearch +from readwise_sdk.models.reader import ( + DocumentCategory, + DocumentCreate, + DocumentLocation, + DocumentUpdate, +) +from readwise_sdk.models.readwise import BookCategory from readwise_sdk.operations import ReadwiseService from readwise_sdk.resources.v2 import ( AsyncBooksResource, @@ -38,13 +45,6 @@ AsyncTagsResource, ) from readwise_sdk.resources.v3 import AsyncDocumentsResource -from readwise_sdk.v2.models import BookCategory -from readwise_sdk.v3.models import ( - DocumentCategory, - DocumentCreate, - DocumentLocation, - DocumentUpdate, -) # --------------------------------------------------------------------------- # Server + client setup diff --git a/src/readwise_sdk/models/reader.py b/src/readwise_sdk/models/reader.py new file mode 100644 index 0000000..5ecf95b --- /dev/null +++ b/src/readwise_sdk/models/reader.py @@ -0,0 +1,266 @@ +"""Canonical Pydantic models for the Readwise Reader (v3) API. + +These are the source-of-truth model definitions. ``readwise_sdk.v3.models`` +re-exports them for backward compatibility; import from here internally. +""" + +from __future__ import annotations + +import re +from datetime import datetime +from enum import Enum +from typing import Any + +from pydantic import BaseModel, Field, field_validator, model_validator + +from readwise_sdk._utils import parse_datetime_string + + +class DocumentLocation(str, Enum): + """Location/status of a document in Reader.""" + + NEW = "new" + LATER = "later" + ARCHIVE = "archive" + FEED = "feed" + + +class DocumentCategory(str, Enum): + """Category of a document in Reader.""" + + ARTICLE = "article" + EMAIL = "email" + RSS = "rss" + HIGHLIGHT = "highlight" + NOTE = "note" + PDF = "pdf" + EPUB = "epub" + TWEET = "tweet" + VIDEO = "video" + + +class DocumentTag(BaseModel): + """A tag in Reader.""" + + key: str # The tag identifier/key + name: str # The display name + + model_config = {"extra": "ignore"} + + +class Document(BaseModel): + """A document in Readwise Reader.""" + + id: str + url: str + source_url: str | None = None + title: str | None = None + author: str | None = None + source: str | None = None + category: DocumentCategory | None = None + location: DocumentLocation | None = None + tags: list[str] = Field(default_factory=list) # Tags are just strings in v3 + site_name: str | None = None + word_count: int | None = None + reading_time: int | None = None # In minutes + created_at: datetime | None = None + updated_at: datetime | None = None + published_date: datetime | None = None + summary: str | None = None + image_url: str | None = None + content: str | None = None # HTML content, only when requested + html_content: str | None = None # HTML content (alternate API field name) + notes: str | None = None + parent_id: str | None = None + reading_progress: float | None = None + first_opened_at: datetime | None = None + last_opened_at: datetime | None = None + saved_at: datetime | None = None + last_moved_at: datetime | None = None + + model_config = {"extra": "ignore"} + + @model_validator(mode="before") + @classmethod + def merge_html_content(cls, data: Any) -> Any: + """Readwise API returns HTML in 'html_content' when withHtmlContent=true, + but also has a 'content' field. Merge html_content into content.""" + if isinstance(data, dict): + html_content = data.get("html_content") + if html_content and not data.get("content"): + data["content"] = html_content + return data + + @field_validator("category", mode="before") + @classmethod + def parse_category(cls, v: Any) -> DocumentCategory | None: + """Parse category string to enum.""" + if v is None or v == "": + return None + try: + return DocumentCategory(v) + except ValueError: + return None + + @field_validator("location", mode="before") + @classmethod + def parse_location(cls, v: Any) -> DocumentLocation | None: + """Parse location string to enum.""" + if v is None or v == "": + return None + try: + return DocumentLocation(v) + except ValueError: + return None + + @field_validator( + "created_at", + "updated_at", + "published_date", + "first_opened_at", + "last_opened_at", + "saved_at", + "last_moved_at", + mode="before", + ) + @classmethod + def parse_datetime(cls, v: Any) -> datetime | None: + """Parse datetime strings.""" + return parse_datetime_string(v) + + @field_validator("tags", mode="before") + @classmethod + def parse_tags(cls, v: Any) -> list[str]: + """Parse tags which can be dicts or strings.""" + if v is None: + return [] + if isinstance(v, list): + result = [] + for item in v: + if isinstance(item, str): + result.append(item) + elif isinstance(item, dict) and "name" in item: + result.append(item["name"]) + return result + return [] + + @field_validator("reading_time", mode="before") + @classmethod + def parse_reading_time(cls, v: Any) -> int | None: + """Parse reading_time which can be int or string like '22 mins'.""" + if v is None: + return None + if isinstance(v, int): + return v + if isinstance(v, str): + # Parse strings like "22 mins", "5 min", "1 minute" + match = re.match(r"(\d+)", v) + if match: + return int(match.group(1)) + return None + return None + + +class DocumentCreate(BaseModel): + """Data for creating a new document in Reader.""" + + url: str = Field(..., description="Unique identifier URL for the document") + html: str | None = Field(default=None, description="HTML content (omit to scrape URL)") + should_clean_html: bool | None = Field( + default=None, description="Auto-clean HTML and extract metadata" + ) + title: str | None = Field(default=None, description="Override parsed title") + author: str | None = Field(default=None, description="Override parsed author") + summary: str | None = Field(default=None, description="Document summary") + published_date: datetime | None = Field(default=None, description="ISO 8601 format") + image_url: str | None = Field(default=None, description="Cover image URL") + location: DocumentLocation | None = Field( + default=None, description="new, later, archive, or feed" + ) + category: DocumentCategory | None = Field(default=None, description="Document category") + saved_using: str | None = Field(default=None, description="Source identifier") + tags: list[str] | None = Field(default=None, description="Array of tag strings") + notes: str | None = Field(default=None, description="Top-level document note") + + model_config = {"extra": "ignore"} + + def to_api_dict(self) -> dict[str, Any]: + """Convert to API request format.""" + data: dict[str, Any] = {"url": self.url} + + if self.html is not None: + data["html"] = self.html + if self.should_clean_html is not None: + data["should_clean_html"] = self.should_clean_html + if self.title is not None: + data["title"] = self.title + if self.author is not None: + data["author"] = self.author + if self.summary is not None: + data["summary"] = self.summary + if self.published_date is not None: + data["published_date"] = self.published_date.isoformat() + if self.image_url is not None: + data["image_url"] = self.image_url + if self.location is not None: + data["location"] = self.location.value + if self.category is not None: + data["category"] = self.category.value + if self.saved_using is not None: + data["saved_using"] = self.saved_using + if self.tags is not None: + data["tags"] = self.tags + if self.notes is not None: + data["notes"] = self.notes + + return data + + +class DocumentUpdate(BaseModel): + """Data for updating a document in Reader.""" + + title: str | None = None + author: str | None = None + summary: str | None = None + published_date: datetime | None = None + image_url: str | None = None + location: DocumentLocation | None = None + category: DocumentCategory | None = None + tags: list[str] | None = None + notes: str | None = None + + model_config = {"extra": "ignore"} + + def to_api_dict(self) -> dict[str, Any]: + """Convert to API request format, only including set fields.""" + data: dict[str, Any] = {} + + if self.title is not None: + data["title"] = self.title + if self.author is not None: + data["author"] = self.author + if self.summary is not None: + data["summary"] = self.summary + if self.published_date is not None: + data["published_date"] = self.published_date.isoformat() + if self.image_url is not None: + data["image_url"] = self.image_url + if self.location is not None: + data["location"] = self.location.value + if self.category is not None: + data["category"] = self.category.value + if self.tags is not None: + data["tags"] = self.tags + if self.notes is not None: + data["notes"] = self.notes + + return data + + +class CreateDocumentResult(BaseModel): + """Result of creating a document.""" + + id: str + url: str + + model_config = {"extra": "ignore"} diff --git a/src/readwise_sdk/models/readwise.py b/src/readwise_sdk/models/readwise.py new file mode 100644 index 0000000..200c99a --- /dev/null +++ b/src/readwise_sdk/models/readwise.py @@ -0,0 +1,241 @@ +"""Canonical Pydantic models for the Readwise (v2) API. + +These are the source-of-truth model definitions. ``readwise_sdk.v2.models`` +re-exports them for backward compatibility; import from here internally. +""" + +from __future__ import annotations + +from datetime import datetime +from enum import Enum +from typing import Any + +from pydantic import BaseModel, Field, field_validator + +from readwise_sdk._utils import parse_datetime_string + + +class BookCategory(str, Enum): + """Categories for books/sources in Readwise.""" + + BOOKS = "books" + ARTICLES = "articles" + TWEETS = "tweets" + PODCASTS = "podcasts" + SUPPLEMENTALS = "supplementals" + + +class HighlightColor(str, Enum): + """Available highlight colors.""" + + YELLOW = "yellow" + BLUE = "blue" + PINK = "pink" + ORANGE = "orange" + GREEN = "green" + PURPLE = "purple" + + +class Tag(BaseModel): + """A tag attached to a highlight or book.""" + + id: int + name: str + + model_config = {"extra": "ignore"} + + +class Highlight(BaseModel): + """A highlight from a book or article.""" + + id: int + text: str + note: str | None = None + location: int | None = None + location_type: str | None = None + url: str | None = None + color: HighlightColor | None = None + highlighted_at: datetime | None = None + created_at: datetime | None = None + updated_at: datetime | None = None + book_id: int | None = None + tags: list[Tag] = Field(default_factory=list) + + model_config = {"extra": "ignore"} + + @field_validator("color", mode="before") + @classmethod + def parse_color(cls, v: Any) -> HighlightColor | None: + """Parse color string to enum, returning None if invalid.""" + if v is None or v == "": + return None + try: + return HighlightColor(v) + except ValueError: + return None + + @field_validator("highlighted_at", "created_at", "updated_at", mode="before") + @classmethod + def parse_datetime(cls, v: Any) -> datetime | None: + """Parse datetime strings.""" + return parse_datetime_string(v) + + +class Book(BaseModel): + """A book or source containing highlights.""" + + id: int + title: str + author: str | None = None + category: BookCategory | None = None + source: str | None = None + num_highlights: int = 0 + last_highlight_at: datetime | None = None + updated: datetime | None = None + cover_image_url: str | None = None + highlights_url: str | None = None + source_url: str | None = None + asin: str | None = None + tags: list[Tag] = Field(default_factory=list) + + model_config = {"extra": "ignore"} + + @field_validator("category", mode="before") + @classmethod + def parse_category(cls, v: Any) -> BookCategory | None: + """Parse category string to enum, returning None if invalid.""" + if v is None or v == "": + return None + try: + return BookCategory(v) + except ValueError: + return None + + @field_validator("last_highlight_at", "updated", mode="before") + @classmethod + def parse_datetime(cls, v: Any) -> datetime | None: + """Parse datetime strings.""" + return parse_datetime_string(v) + + +class DailyReview(BaseModel): + """A daily review containing selected highlights.""" + + review_id: int + review_url: str + review_completed: bool = False + highlights: list[Highlight] = Field(default_factory=list) + + model_config = {"extra": "ignore"} + + +class HighlightCreate(BaseModel): + """Data for creating a new highlight.""" + + text: str = Field(..., max_length=8191) + title: str | None = Field(default=None, max_length=511) + author: str | None = Field(default=None, max_length=1024) + source_url: str | None = Field(default=None, max_length=2047) + source_type: str | None = Field(default=None, min_length=3, max_length=64) + category: BookCategory | None = None + note: str | None = Field(default=None, max_length=8191) + location: int | None = None + location_type: str | None = None + highlighted_at: datetime | None = None + highlight_url: str | None = None + image_url: str | None = None + + model_config = {"extra": "ignore"} + + def to_api_dict(self) -> dict[str, Any]: + """Convert to API request format.""" + data: dict[str, Any] = {"text": self.text} + + if self.title: + data["title"] = self.title + if self.author: + data["author"] = self.author + if self.source_url: + data["source_url"] = self.source_url + if self.source_type: + data["source_type"] = self.source_type + if self.category: + data["category"] = self.category.value + if self.note: + data["note"] = self.note + if self.location is not None: + data["location"] = self.location + if self.location_type: + data["location_type"] = self.location_type + if self.highlighted_at: + data["highlighted_at"] = self.highlighted_at.isoformat() + if self.highlight_url: + data["highlight_url"] = self.highlight_url + if self.image_url: + data["image_url"] = self.image_url + + return data + + +class HighlightUpdate(BaseModel): + """Data for updating an existing highlight.""" + + text: str | None = Field(default=None, max_length=8191) + note: str | None = Field(default=None, max_length=8191) + location: int | None = None + location_type: str | None = None + url: str | None = None + color: HighlightColor | None = None + + model_config = {"extra": "ignore"} + + def to_api_dict(self) -> dict[str, Any]: + """Convert to API request format, only including set fields.""" + data: dict[str, Any] = {} + + if self.text is not None: + data["text"] = self.text + if self.note is not None: + data["note"] = self.note + if self.location is not None: + data["location"] = self.location + if self.location_type is not None: + data["location_type"] = self.location_type + if self.url is not None: + data["url"] = self.url + if self.color is not None: + data["color"] = self.color.value + + return data + + +class ExportBook(BaseModel): + """A book with highlights from the export endpoint.""" + + user_book_id: int + title: str + author: str | None = None + readable_title: str | None = None + source: str | None = None + cover_image_url: str | None = None + unique_url: str | None = None + book_tags: list[Tag] = Field(default_factory=list) + category: BookCategory | None = None + document_note: str | None = None + readwise_url: str | None = None + source_url: str | None = None + asin: str | None = None + highlights: list[Highlight] = Field(default_factory=list) + + model_config = {"extra": "ignore"} + + @field_validator("category", mode="before") + @classmethod + def parse_category(cls, v: Any) -> BookCategory | None: + """Parse category string to enum.""" + if v is None or v == "": + return None + try: + return BookCategory(v) + except ValueError: + return None diff --git a/src/readwise_sdk/operations/books.py b/src/readwise_sdk/operations/books.py index f9f9ac1..7223986 100644 --- a/src/readwise_sdk/operations/books.py +++ b/src/readwise_sdk/operations/books.py @@ -10,7 +10,7 @@ from typing import Protocol from readwise_sdk.models import BookSearch, BookSummary -from readwise_sdk.v2.models import Book, BookCategory, Highlight +from readwise_sdk.models.readwise import Book, BookCategory, Highlight class BooksResource(Protocol): diff --git a/src/readwise_sdk/operations/compat.py b/src/readwise_sdk/operations/compat.py index 741f983..ccbf771 100644 --- a/src/readwise_sdk/operations/compat.py +++ b/src/readwise_sdk/operations/compat.py @@ -12,8 +12,8 @@ from typing import Any, cast from readwise_sdk.models import BulkResult -from readwise_sdk.v2.models import HighlightCreate, HighlightUpdate -from readwise_sdk.v3.models import DocumentCreate, DocumentLocation, DocumentUpdate +from readwise_sdk.models.reader import DocumentCreate, DocumentLocation, DocumentUpdate +from readwise_sdk.models.readwise import HighlightCreate, HighlightUpdate def run_sync[ResultT](awaitable: Awaitable[ResultT]) -> ResultT: diff --git a/src/readwise_sdk/operations/digests.py b/src/readwise_sdk/operations/digests.py index b9a2833..aaf7982 100644 --- a/src/readwise_sdk/operations/digests.py +++ b/src/readwise_sdk/operations/digests.py @@ -8,7 +8,7 @@ from enum import Enum from typing import Protocol -from readwise_sdk.v2.models import Book, Highlight +from readwise_sdk.models.readwise import Book, Highlight class DigestHighlightsResource(Protocol): diff --git a/src/readwise_sdk/operations/documents.py b/src/readwise_sdk/operations/documents.py index d39e371..7e54bb5 100644 --- a/src/readwise_sdk/operations/documents.py +++ b/src/readwise_sdk/operations/documents.py @@ -10,8 +10,7 @@ from readwise_sdk.errors import NotFoundError from readwise_sdk.models import BulkResult, DocumentSearch, DocumentSearchResult, DocumentSummary -from readwise_sdk.models.results import OperationFailure -from readwise_sdk.v3.models import ( +from readwise_sdk.models.reader import ( CreateDocumentResult, Document, DocumentCategory, @@ -19,6 +18,7 @@ DocumentLocation, DocumentUpdate, ) +from readwise_sdk.models.results import OperationFailure class DocumentsResource(Protocol): diff --git a/src/readwise_sdk/operations/highlights.py b/src/readwise_sdk/operations/highlights.py index 88ac5f0..7f89ebe 100644 --- a/src/readwise_sdk/operations/highlights.py +++ b/src/readwise_sdk/operations/highlights.py @@ -9,8 +9,7 @@ from typing import Protocol, cast from readwise_sdk.models import BulkResult, HighlightSearch, HighlightSummary -from readwise_sdk.models.results import OperationFailure -from readwise_sdk.v2.models import ( +from readwise_sdk.models.readwise import ( BookCategory, ExportBook, Highlight, @@ -18,6 +17,7 @@ HighlightUpdate, Tag, ) +from readwise_sdk.models.results import OperationFailure MAX_TEXT_LENGTH = 8191 MAX_NOTE_LENGTH = 8191 diff --git a/src/readwise_sdk/operations/imports.py b/src/readwise_sdk/operations/imports.py index 53993db..0e2e475 100644 --- a/src/readwise_sdk/operations/imports.py +++ b/src/readwise_sdk/operations/imports.py @@ -10,7 +10,7 @@ from typing import Any, Protocol from urllib.parse import urlparse -from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation +from readwise_sdk.models.reader import Document, DocumentCategory, DocumentLocation WORDS_PER_MINUTE = 200 diff --git a/src/readwise_sdk/operations/inbox.py b/src/readwise_sdk/operations/inbox.py index ed14941..d439af6 100644 --- a/src/readwise_sdk/operations/inbox.py +++ b/src/readwise_sdk/operations/inbox.py @@ -8,8 +8,8 @@ from typing import Protocol from readwise_sdk.models import BulkResult +from readwise_sdk.models.reader import Document, DocumentCategory, DocumentLocation from readwise_sdk.operations.documents import DocumentOperations -from readwise_sdk.v3.models import Document, DocumentCategory, DocumentLocation class ArchiveRuleLike(Protocol): diff --git a/src/readwise_sdk/operations/sync.py b/src/readwise_sdk/operations/sync.py index 2823cdc..4346d87 100644 --- a/src/readwise_sdk/operations/sync.py +++ b/src/readwise_sdk/operations/sync.py @@ -10,10 +10,10 @@ from typing import Any, Literal, Protocol, cast from readwise_sdk.models import SyncCheckpoint +from readwise_sdk.models.reader import Document +from readwise_sdk.models.readwise import Book, Highlight from readwise_sdk.models.results import SyncResult from readwise_sdk.state import MemoryStateStore, StateStore -from readwise_sdk.v2.models import Book, Highlight -from readwise_sdk.v3.models import Document class AsyncHighlightsResource(Protocol): diff --git a/src/readwise_sdk/operations/tags.py b/src/readwise_sdk/operations/tags.py index 039aa3c..bbc9015 100644 --- a/src/readwise_sdk/operations/tags.py +++ b/src/readwise_sdk/operations/tags.py @@ -9,7 +9,7 @@ from datetime import datetime from typing import Protocol -from readwise_sdk.v2.models import Highlight, Tag +from readwise_sdk.models.readwise import Highlight, Tag class TagHighlightsResource(Protocol): diff --git a/src/readwise_sdk/resources/v2/books.py b/src/readwise_sdk/resources/v2/books.py index 5fbe398..3c0f97a 100644 --- a/src/readwise_sdk/resources/v2/books.py +++ b/src/readwise_sdk/resources/v2/books.py @@ -6,9 +6,9 @@ from datetime import datetime from typing import Any +from readwise_sdk.models.readwise import Book, BookCategory from readwise_sdk.transport.async_ import AsyncTransport from readwise_sdk.transport.pagination import StandardV2Page, paginate_async -from readwise_sdk.v2.models import Book, BookCategory class AsyncBooksResource: diff --git a/src/readwise_sdk/resources/v2/export.py b/src/readwise_sdk/resources/v2/export.py index 5ece16f..e739924 100644 --- a/src/readwise_sdk/resources/v2/export.py +++ b/src/readwise_sdk/resources/v2/export.py @@ -6,9 +6,9 @@ from datetime import datetime from typing import Any +from readwise_sdk.models.readwise import ExportBook from readwise_sdk.transport.async_ import AsyncTransport from readwise_sdk.transport.pagination import ExportV2Page, paginate_async -from readwise_sdk.v2.models import ExportBook class AsyncExportResource: diff --git a/src/readwise_sdk/resources/v2/highlights.py b/src/readwise_sdk/resources/v2/highlights.py index d1a5c82..05edec0 100644 --- a/src/readwise_sdk/resources/v2/highlights.py +++ b/src/readwise_sdk/resources/v2/highlights.py @@ -6,9 +6,9 @@ from datetime import datetime from typing import Any +from readwise_sdk.models.readwise import Highlight, HighlightCreate, HighlightUpdate from readwise_sdk.transport.async_ import AsyncTransport from readwise_sdk.transport.pagination import StandardV2Page, paginate_async -from readwise_sdk.v2.models import Highlight, HighlightCreate, HighlightUpdate class AsyncHighlightsResource: diff --git a/src/readwise_sdk/resources/v2/review.py b/src/readwise_sdk/resources/v2/review.py index 0e94e18..090c126 100644 --- a/src/readwise_sdk/resources/v2/review.py +++ b/src/readwise_sdk/resources/v2/review.py @@ -2,8 +2,8 @@ from __future__ import annotations +from readwise_sdk.models.readwise import DailyReview from readwise_sdk.transport.async_ import AsyncTransport -from readwise_sdk.v2.models import DailyReview class AsyncReviewResource: diff --git a/src/readwise_sdk/resources/v2/tags.py b/src/readwise_sdk/resources/v2/tags.py index 3c84d01..1bf9f03 100644 --- a/src/readwise_sdk/resources/v2/tags.py +++ b/src/readwise_sdk/resources/v2/tags.py @@ -4,9 +4,9 @@ from collections.abc import AsyncIterator +from readwise_sdk.models.readwise import Tag from readwise_sdk.transport.async_ import AsyncTransport from readwise_sdk.transport.pagination import StandardV2Page, paginate_async -from readwise_sdk.v2.models import Tag class AsyncTagsResource: diff --git a/src/readwise_sdk/resources/v3/documents.py b/src/readwise_sdk/resources/v3/documents.py index c0ca685..26f8ee5 100644 --- a/src/readwise_sdk/resources/v3/documents.py +++ b/src/readwise_sdk/resources/v3/documents.py @@ -6,9 +6,7 @@ from datetime import datetime from typing import Any -from readwise_sdk.transport.async_ import AsyncTransport -from readwise_sdk.transport.pagination import ReaderV3Page, paginate_async -from readwise_sdk.v3.models import ( +from readwise_sdk.models.reader import ( CreateDocumentResult, Document, DocumentCategory, @@ -16,6 +14,8 @@ DocumentLocation, DocumentUpdate, ) +from readwise_sdk.transport.async_ import AsyncTransport +from readwise_sdk.transport.pagination import ReaderV3Page, paginate_async class AsyncDocumentsResource: diff --git a/src/readwise_sdk/resources/v3/tags.py b/src/readwise_sdk/resources/v3/tags.py index bde022a..61f94c3 100644 --- a/src/readwise_sdk/resources/v3/tags.py +++ b/src/readwise_sdk/resources/v3/tags.py @@ -4,9 +4,9 @@ from collections.abc import AsyncIterator +from readwise_sdk.models.reader import DocumentTag from readwise_sdk.transport.async_ import AsyncTransport from readwise_sdk.transport.pagination import ReaderV3Page, paginate_async -from readwise_sdk.v3.models import DocumentTag class AsyncTagsResource: diff --git a/src/readwise_sdk/sdk/sync.py b/src/readwise_sdk/sdk/sync.py index cd2612a..b063cda 100644 --- a/src/readwise_sdk/sdk/sync.py +++ b/src/readwise_sdk/sdk/sync.py @@ -23,6 +23,20 @@ SyncResult, ) from readwise_sdk.models.queries import HighlightSearch +from readwise_sdk.models.reader import ( + CreateDocumentResult, + Document, + DocumentCreate, + DocumentLocation, + DocumentUpdate, +) +from readwise_sdk.models.readwise import ( + Book, + BookCategory, + Highlight, + HighlightCreate, + HighlightUpdate, +) from readwise_sdk.operations import ( BookSearchResult, BookWithHighlights, @@ -42,14 +56,6 @@ ) from readwise_sdk.operations.sync import BatchSyncOutcome, SyncOperations from readwise_sdk.sdk.async_ import AsyncReadwise -from readwise_sdk.v2.models import Book, BookCategory, Highlight, HighlightCreate, HighlightUpdate -from readwise_sdk.v3.models import ( - CreateDocumentResult, - Document, - DocumentCreate, - DocumentLocation, - DocumentUpdate, -) if TYPE_CHECKING: from readwise_sdk.operations import ( diff --git a/src/readwise_sdk/v2/models.py b/src/readwise_sdk/v2/models.py index 6b6cc56..4f2ea58 100644 --- a/src/readwise_sdk/v2/models.py +++ b/src/readwise_sdk/v2/models.py @@ -1,237 +1,33 @@ -"""Pydantic models for Readwise API v2.""" +"""Pydantic models for Readwise API v2. -from __future__ import annotations - -from datetime import datetime -from enum import Enum -from typing import Any - -from pydantic import BaseModel, Field, field_validator - -from readwise_sdk._utils import parse_datetime_string - - -class BookCategory(str, Enum): - """Categories for books/sources in Readwise.""" - - BOOKS = "books" - ARTICLES = "articles" - TWEETS = "tweets" - PODCASTS = "podcasts" - SUPPLEMENTALS = "supplementals" - - -class HighlightColor(str, Enum): - """Available highlight colors.""" - - YELLOW = "yellow" - BLUE = "blue" - PINK = "pink" - ORANGE = "orange" - GREEN = "green" - PURPLE = "purple" - - -class Tag(BaseModel): - """A tag attached to a highlight or book.""" - - id: int - name: str - - model_config = {"extra": "ignore"} - - -class Highlight(BaseModel): - """A highlight from a book or article.""" - - id: int - text: str - note: str | None = None - location: int | None = None - location_type: str | None = None - url: str | None = None - color: HighlightColor | None = None - highlighted_at: datetime | None = None - created_at: datetime | None = None - updated_at: datetime | None = None - book_id: int | None = None - tags: list[Tag] = Field(default_factory=list) - - model_config = {"extra": "ignore"} - - @field_validator("color", mode="before") - @classmethod - def parse_color(cls, v: Any) -> HighlightColor | None: - """Parse color string to enum, returning None if invalid.""" - if v is None or v == "": - return None - try: - return HighlightColor(v) - except ValueError: - return None - - @field_validator("highlighted_at", "created_at", "updated_at", mode="before") - @classmethod - def parse_datetime(cls, v: Any) -> datetime | None: - """Parse datetime strings.""" - return parse_datetime_string(v) - - -class Book(BaseModel): - """A book or source containing highlights.""" - - id: int - title: str - author: str | None = None - category: BookCategory | None = None - source: str | None = None - num_highlights: int = 0 - last_highlight_at: datetime | None = None - updated: datetime | None = None - cover_image_url: str | None = None - highlights_url: str | None = None - source_url: str | None = None - asin: str | None = None - tags: list[Tag] = Field(default_factory=list) - - model_config = {"extra": "ignore"} +Re-exports the canonical model definitions from +``readwise_sdk.models.readwise`` for backward compatibility. This module is +identity-preserving: every name below is the *same object* as its +counterpart in ``readwise_sdk.models.readwise``, not a copy. +""" - @field_validator("category", mode="before") - @classmethod - def parse_category(cls, v: Any) -> BookCategory | None: - """Parse category string to enum, returning None if invalid.""" - if v is None or v == "": - return None - try: - return BookCategory(v) - except ValueError: - return None - - @field_validator("last_highlight_at", "updated", mode="before") - @classmethod - def parse_datetime(cls, v: Any) -> datetime | None: - """Parse datetime strings.""" - return parse_datetime_string(v) - - -class DailyReview(BaseModel): - """A daily review containing selected highlights.""" - - review_id: int - review_url: str - review_completed: bool = False - highlights: list[Highlight] = Field(default_factory=list) - - model_config = {"extra": "ignore"} - - -class HighlightCreate(BaseModel): - """Data for creating a new highlight.""" - - text: str = Field(..., max_length=8191) - title: str | None = Field(default=None, max_length=511) - author: str | None = Field(default=None, max_length=1024) - source_url: str | None = Field(default=None, max_length=2047) - source_type: str | None = Field(default=None, min_length=3, max_length=64) - category: BookCategory | None = None - note: str | None = Field(default=None, max_length=8191) - location: int | None = None - location_type: str | None = None - highlighted_at: datetime | None = None - highlight_url: str | None = None - image_url: str | None = None - - model_config = {"extra": "ignore"} - - def to_api_dict(self) -> dict[str, Any]: - """Convert to API request format.""" - data: dict[str, Any] = {"text": self.text} - - if self.title: - data["title"] = self.title - if self.author: - data["author"] = self.author - if self.source_url: - data["source_url"] = self.source_url - if self.source_type: - data["source_type"] = self.source_type - if self.category: - data["category"] = self.category.value - if self.note: - data["note"] = self.note - if self.location is not None: - data["location"] = self.location - if self.location_type: - data["location_type"] = self.location_type - if self.highlighted_at: - data["highlighted_at"] = self.highlighted_at.isoformat() - if self.highlight_url: - data["highlight_url"] = self.highlight_url - if self.image_url: - data["image_url"] = self.image_url - - return data - - -class HighlightUpdate(BaseModel): - """Data for updating an existing highlight.""" - - text: str | None = Field(default=None, max_length=8191) - note: str | None = Field(default=None, max_length=8191) - location: int | None = None - location_type: str | None = None - url: str | None = None - color: HighlightColor | None = None - - model_config = {"extra": "ignore"} - - def to_api_dict(self) -> dict[str, Any]: - """Convert to API request format, only including set fields.""" - data: dict[str, Any] = {} - - if self.text is not None: - data["text"] = self.text - if self.note is not None: - data["note"] = self.note - if self.location is not None: - data["location"] = self.location - if self.location_type is not None: - data["location_type"] = self.location_type - if self.url is not None: - data["url"] = self.url - if self.color is not None: - data["color"] = self.color.value - - return data - - -class ExportBook(BaseModel): - """A book with highlights from the export endpoint.""" - - user_book_id: int - title: str - author: str | None = None - readable_title: str | None = None - source: str | None = None - cover_image_url: str | None = None - unique_url: str | None = None - book_tags: list[Tag] = Field(default_factory=list) - category: BookCategory | None = None - document_note: str | None = None - readwise_url: str | None = None - source_url: str | None = None - asin: str | None = None - highlights: list[Highlight] = Field(default_factory=list) - - model_config = {"extra": "ignore"} +from __future__ import annotations - @field_validator("category", mode="before") - @classmethod - def parse_category(cls, v: Any) -> BookCategory | None: - """Parse category string to enum.""" - if v is None or v == "": - return None - try: - return BookCategory(v) - except ValueError: - return None +from readwise_sdk.models.readwise import ( + Book, + BookCategory, + DailyReview, + ExportBook, + Highlight, + HighlightColor, + HighlightCreate, + HighlightUpdate, + Tag, +) + +__all__ = [ + "Book", + "BookCategory", + "DailyReview", + "ExportBook", + "Highlight", + "HighlightColor", + "HighlightCreate", + "HighlightUpdate", + "Tag", +] diff --git a/src/readwise_sdk/v3/models.py b/src/readwise_sdk/v3/models.py index b198566..3e0728a 100644 --- a/src/readwise_sdk/v3/models.py +++ b/src/readwise_sdk/v3/models.py @@ -1,262 +1,29 @@ -"""Pydantic models for Readwise Reader API v3.""" +"""Pydantic models for Readwise Reader API v3. -from __future__ import annotations - -import re -from datetime import datetime -from enum import Enum -from typing import Any - -from pydantic import BaseModel, Field, field_validator, model_validator - -from readwise_sdk._utils import parse_datetime_string - - -class DocumentLocation(str, Enum): - """Location/status of a document in Reader.""" - - NEW = "new" - LATER = "later" - ARCHIVE = "archive" - FEED = "feed" - - -class DocumentCategory(str, Enum): - """Category of a document in Reader.""" - - ARTICLE = "article" - EMAIL = "email" - RSS = "rss" - HIGHLIGHT = "highlight" - NOTE = "note" - PDF = "pdf" - EPUB = "epub" - TWEET = "tweet" - VIDEO = "video" - - -class DocumentTag(BaseModel): - """A tag in Reader.""" - - key: str # The tag identifier/key - name: str # The display name - - model_config = {"extra": "ignore"} - - -class Document(BaseModel): - """A document in Readwise Reader.""" - - id: str - url: str - source_url: str | None = None - title: str | None = None - author: str | None = None - source: str | None = None - category: DocumentCategory | None = None - location: DocumentLocation | None = None - tags: list[str] = Field(default_factory=list) # Tags are just strings in v3 - site_name: str | None = None - word_count: int | None = None - reading_time: int | None = None # In minutes - created_at: datetime | None = None - updated_at: datetime | None = None - published_date: datetime | None = None - summary: str | None = None - image_url: str | None = None - content: str | None = None # HTML content, only when requested - html_content: str | None = None # HTML content (alternate API field name) - notes: str | None = None - parent_id: str | None = None - reading_progress: float | None = None - first_opened_at: datetime | None = None - last_opened_at: datetime | None = None - saved_at: datetime | None = None - last_moved_at: datetime | None = None - - model_config = {"extra": "ignore"} - - @model_validator(mode="before") - @classmethod - def merge_html_content(cls, data: Any) -> Any: - """Readwise API returns HTML in 'html_content' when withHtmlContent=true, - but also has a 'content' field. Merge html_content into content.""" - if isinstance(data, dict): - html_content = data.get("html_content") - if html_content and not data.get("content"): - data["content"] = html_content - return data - - @field_validator("category", mode="before") - @classmethod - def parse_category(cls, v: Any) -> DocumentCategory | None: - """Parse category string to enum.""" - if v is None or v == "": - return None - try: - return DocumentCategory(v) - except ValueError: - return None - - @field_validator("location", mode="before") - @classmethod - def parse_location(cls, v: Any) -> DocumentLocation | None: - """Parse location string to enum.""" - if v is None or v == "": - return None - try: - return DocumentLocation(v) - except ValueError: - return None +Re-exports the canonical model definitions from +``readwise_sdk.models.reader`` for backward compatibility. This module is +identity-preserving: every name below is the *same object* as its +counterpart in ``readwise_sdk.models.reader``, not a copy. +""" - @field_validator( - "created_at", - "updated_at", - "published_date", - "first_opened_at", - "last_opened_at", - "saved_at", - "last_moved_at", - mode="before", - ) - @classmethod - def parse_datetime(cls, v: Any) -> datetime | None: - """Parse datetime strings.""" - return parse_datetime_string(v) - - @field_validator("tags", mode="before") - @classmethod - def parse_tags(cls, v: Any) -> list[str]: - """Parse tags which can be dicts or strings.""" - if v is None: - return [] - if isinstance(v, list): - result = [] - for item in v: - if isinstance(item, str): - result.append(item) - elif isinstance(item, dict) and "name" in item: - result.append(item["name"]) - return result - return [] - - @field_validator("reading_time", mode="before") - @classmethod - def parse_reading_time(cls, v: Any) -> int | None: - """Parse reading_time which can be int or string like '22 mins'.""" - if v is None: - return None - if isinstance(v, int): - return v - if isinstance(v, str): - # Parse strings like "22 mins", "5 min", "1 minute" - match = re.match(r"(\d+)", v) - if match: - return int(match.group(1)) - return None - return None - - -class DocumentCreate(BaseModel): - """Data for creating a new document in Reader.""" - - url: str = Field(..., description="Unique identifier URL for the document") - html: str | None = Field(default=None, description="HTML content (omit to scrape URL)") - should_clean_html: bool | None = Field( - default=None, description="Auto-clean HTML and extract metadata" - ) - title: str | None = Field(default=None, description="Override parsed title") - author: str | None = Field(default=None, description="Override parsed author") - summary: str | None = Field(default=None, description="Document summary") - published_date: datetime | None = Field(default=None, description="ISO 8601 format") - image_url: str | None = Field(default=None, description="Cover image URL") - location: DocumentLocation | None = Field( - default=None, description="new, later, archive, or feed" - ) - category: DocumentCategory | None = Field(default=None, description="Document category") - saved_using: str | None = Field(default=None, description="Source identifier") - tags: list[str] | None = Field(default=None, description="Array of tag strings") - notes: str | None = Field(default=None, description="Top-level document note") - - model_config = {"extra": "ignore"} - - def to_api_dict(self) -> dict[str, Any]: - """Convert to API request format.""" - data: dict[str, Any] = {"url": self.url} - - if self.html is not None: - data["html"] = self.html - if self.should_clean_html is not None: - data["should_clean_html"] = self.should_clean_html - if self.title is not None: - data["title"] = self.title - if self.author is not None: - data["author"] = self.author - if self.summary is not None: - data["summary"] = self.summary - if self.published_date is not None: - data["published_date"] = self.published_date.isoformat() - if self.image_url is not None: - data["image_url"] = self.image_url - if self.location is not None: - data["location"] = self.location.value - if self.category is not None: - data["category"] = self.category.value - if self.saved_using is not None: - data["saved_using"] = self.saved_using - if self.tags is not None: - data["tags"] = self.tags - if self.notes is not None: - data["notes"] = self.notes - - return data - - -class DocumentUpdate(BaseModel): - """Data for updating a document in Reader.""" - - title: str | None = None - author: str | None = None - summary: str | None = None - published_date: datetime | None = None - image_url: str | None = None - location: DocumentLocation | None = None - category: DocumentCategory | None = None - tags: list[str] | None = None - notes: str | None = None - - model_config = {"extra": "ignore"} - - def to_api_dict(self) -> dict[str, Any]: - """Convert to API request format, only including set fields.""" - data: dict[str, Any] = {} - - if self.title is not None: - data["title"] = self.title - if self.author is not None: - data["author"] = self.author - if self.summary is not None: - data["summary"] = self.summary - if self.published_date is not None: - data["published_date"] = self.published_date.isoformat() - if self.image_url is not None: - data["image_url"] = self.image_url - if self.location is not None: - data["location"] = self.location.value - if self.category is not None: - data["category"] = self.category.value - if self.tags is not None: - data["tags"] = self.tags - if self.notes is not None: - data["notes"] = self.notes - - return data - - -class CreateDocumentResult(BaseModel): - """Result of creating a document.""" - - id: str - url: str +from __future__ import annotations - model_config = {"extra": "ignore"} +from readwise_sdk.models.reader import ( + CreateDocumentResult, + Document, + DocumentCategory, + DocumentCreate, + DocumentLocation, + DocumentTag, + DocumentUpdate, +) + +__all__ = [ + "CreateDocumentResult", + "Document", + "DocumentCategory", + "DocumentCreate", + "DocumentLocation", + "DocumentTag", + "DocumentUpdate", +] From eb88eccde7e5a0daa21f84dac7466bcd451fd5d4 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 01:41:09 -0500 Subject: [PATCH 21/24] chore: type-check all modules + packaging hardening (stage 17) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Removes the cli/ and mcp/ (and stale test) ty exclusions — the `type` recipe is now `uv run ty check .`, checking every module; the restructure left cli/ and mcp/ type-clean, so zero fixes were needed (verified ty is not no-opping). Adds a core-import isolation test proving `import readwise_sdk` pulls no typer/rich/mcp (subprocess + meta_path blocker to simulate a core-only install past httpx's own optional-CLI fallback). Adds py.typed (shipped in the wheel) and .gitattributes (eol=lf). Wheel builds with py.typed + both console scripts (readwise, readwise-mcp). Gate green (836 passed); deps/uv.lock unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- .gitattributes | 2 ++ Justfile | 2 +- src/readwise_sdk/py.typed | 0 tests/test_import_isolation.py | 62 ++++++++++++++++++++++++++++++++++ 4 files changed, 65 insertions(+), 1 deletion(-) create mode 100644 .gitattributes create mode 100644 src/readwise_sdk/py.typed create mode 100644 tests/test_import_isolation.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..4fd0a56 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,2 @@ +* text=auto eol=lf +*.svg binary diff --git a/Justfile b/Justfile index 555b058..7197b2b 100644 --- a/Justfile +++ b/Justfile @@ -16,7 +16,7 @@ lint-fix: uv run ruff check . --fix type: - uv run ty check . --exclude "src/readwise_sdk/cli/" --exclude "src/readwise_sdk/mcp/" --exclude "tests/test_cli.py" --exclude "tests/mcp/" --exclude "tests/conftest.py" + uv run ty check . test: uv run pytest diff --git a/src/readwise_sdk/py.typed b/src/readwise_sdk/py.typed new file mode 100644 index 0000000..e69de29 diff --git a/tests/test_import_isolation.py b/tests/test_import_isolation.py new file mode 100644 index 0000000..4f510f0 --- /dev/null +++ b/tests/test_import_isolation.py @@ -0,0 +1,62 @@ +"""Guard the dependency boundary: importing the core package must not pull in +the optional CLI (Typer/Rich) or MCP (FastMCP) dependencies. + +Run in a fresh subprocess rather than in-process: by the time this test would +run inside the main pytest session, other test modules (e.g. ``tests/mcp/``) +have almost certainly already imported ``typer``/``rich``/``mcp`` into +``sys.modules``, which would make an in-process check meaningless. + +The subprocess also blocks ``typer``/``rich``/``mcp`` (and their transitive +CLI-only helpers ``click``/``pygments``) at import time before importing the +core package. This is deliberate: ``httpx`` itself has an optional bundled +CLI (the ``httpx`` command) that opportunistically imports ``click``/``rich``/ +``pygments`` *if they happen to already be installed*, wrapped in its own +``try/except ImportError``. In this project's dev environment they ARE +installed (as CLI/MCP test dependencies), so a plain "was it imported" +check would fail on that unrelated httpx behavior rather than on anything +readwise_sdk does. Blocking the imports simulates the real-world case of a +core-only install (no ``[cli]``/``[mcp]`` extras) and lets httpx's own +graceful fallback do its job, while still failing loudly if any +readwise_sdk core module tries to import one of these names directly. +""" + +from __future__ import annotations + +import subprocess +import sys + +_PROBE = """ +import sys + +_BLOCKED = {"typer", "rich", "mcp", "fastmcp", "click", "pygments"} + + +class _BlockOptionalAdapterDeps: + def find_spec(self, fullname, path, target=None): + if fullname.split(".")[0] in _BLOCKED: + raise ImportError(f"blocked for core-isolation probe: {fullname}") + return None + + +sys.meta_path.insert(0, _BlockOptionalAdapterDeps()) + +import readwise_sdk # noqa: F401 +import readwise_sdk.operations # noqa: F401 +from readwise_sdk.sdk import AsyncReadwise, Readwise # noqa: F401 + +leaked = sorted(name for name in ("typer", "rich", "mcp") if name in sys.modules) +print(",".join(leaked)) +""" + + +def test_core_import_does_not_load_cli_or_mcp_dependencies() -> None: + result = subprocess.run( + [sys.executable, "-c", _PROBE], + capture_output=True, + text=True, + ) + assert result.returncode == 0, ( + f"importing readwise_sdk core requires an optional CLI/MCP dependency:\n{result.stderr}" + ) + leaked = result.stdout.strip() + assert leaked == "", f"importing readwise_sdk core pulled in optional dependencies: {leaked}" From 99d3dc0823b7af96120dd738f9056ae4902bbf4b Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Tue, 14 Jul 2026 01:57:22 -0500 Subject: [PATCH 22/24] docs: document the 0.3 concept-facade architecture + migration guide (stage 18) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrites README around the new Readwise/AsyncReadwise facade (.documents/ .highlights/.books/.tags/.digests/.sync + .raw escape hatch), with accurate CLI (expanded tree + --output) and MCP sections and a Compatibility APIs section for the still-supported ReadwiseClient/managers/workflows/contrib. Adds MIGRATION.md (old→new mapping + deprecation timeline to 1.0) and a short docs/architecture.md contributor note; refreshes llms.txt/llms-full.txt. Every snippet was executed under respx mocks, which also corrected several pre-existing doc inaccuracies. Removes the refactor working docs (ARCHITECTURE_PLAN.md, REFACTORING_DISCIPLINE.md). Docs only; gate green (836 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- ARCHITECTURE_PLAN.md | 1407 ------------------------------------- MIGRATION.md | 53 ++ README.md | 411 ++++------- REFACTORING_DISCIPLINE.md | 21 - docs/architecture.md | 29 + llms-full.txt | 335 ++++++--- llms.txt | 257 ++----- 7 files changed, 528 insertions(+), 1985 deletions(-) delete mode 100644 ARCHITECTURE_PLAN.md create mode 100644 MIGRATION.md delete mode 100644 REFACTORING_DISCIPLINE.md create mode 100644 docs/architecture.md diff --git a/ARCHITECTURE_PLAN.md b/ARCHITECTURE_PLAN.md deleted file mode 100644 index f398ad1..0000000 --- a/ARCHITECTURE_PLAN.md +++ /dev/null @@ -1,1407 +0,0 @@ -# Target Architecture for `readwise-plus` - -## Executive Decision - -**Introduce one canonical, async-first operations layer and make the SDK facade, CLI, and MCP server thin adapters over it.** - -The existing v2/v3 clients should become low-level resource clients, not the primary place where user-facing behavior is composed. Managers, workflows, contrib helpers, CLI commands, and MCP tools should progressively delegate to the operations layer. - -I recommend **Option A: an aggressive internal restructure released as `0.3.0`**, while retaining inexpensive compatibility shims throughout the `0.x` series. Remove deprecated APIs only at `1.0.0`. - -The primary target API becomes: - -```python -from readwise_sdk import AsyncReadwise - -async with AsyncReadwise() as readwise: - documents = await readwise.documents.search( - query="python", - location="later", - limit=20, - ) -``` - -And synchronously: - -```python -from readwise_sdk import Readwise - -with Readwise() as readwise: - documents = readwise.documents.search( - query="python", - location="later", - limit=20, - ) -``` - -The CLI and MCP server call those same operations. - ---- - -# 1. Current-State Assessment - -## Strengths - -### Clear external API boundaries - -The repository correctly recognizes that Readwise v2 and Reader v3 are different APIs: - -- v2 highlights, books, tags, export, and review live in `src/readwise_sdk/v2/client.py:24`. -- Reader documents and Reader tags live in `src/readwise_sdk/v3/client.py:23`. -- Their models are separated in `src/readwise_sdk/v2/models.py:14` and `src/readwise_sdk/v3/models.py:15`. - -That distinction should remain at the resource layer. - -### Useful typed models - -The Pydantic models provide: - -- Typed enums. -- Tolerant parsing of unknown categories and colors. -- API payload conversion through `to_api_dict()`. -- Normalization of Reader tags and HTML content. - -Examples include: - -- `HighlightCreate.to_api_dict()` in `src/readwise_sdk/v2/models.py:146`. -- `Document.merge_html_content()` in `src/readwise_sdk/v3/models.py:79`. -- `DocumentCreate.to_api_dict()` in `src/readwise_sdk/v3/models.py:183`. - -These are good foundations. They need relocation and clearer naming more than replacement. - -### Shared basic transport behavior - -Authentication, retrying, response handling, and pagination are at least partially centralized: - -- Retry behavior: `src/readwise_sdk/client.py:103` and `src/readwise_sdk/client.py:424`. -- HTTP status translation: `src/readwise_sdk/_utils.py:24`. -- Cursor parsing: `src/readwise_sdk/_utils.py:72`. -- Pagination: `src/readwise_sdk/client.py:245` and `src/readwise_sdk/client.py:487`. - -### Strong behavioral coverage - -Tests cover each major layer separately: - -- Low-level clients. -- Sync and async managers. -- Workflows. -- Contrib helpers. -- CLI commands. -- All nine MCP tools. - -That makes a staged restructuring practical, provided characterization tests are added before moving public contracts. - -### Packaging boundaries are already sound - -The package keeps optional surfaces separate: - -- Core: `httpx`, `pydantic`. -- CLI: Typer and Rich. -- MCP: FastMCP. -- Console scripts remain distinct in `pyproject.toml`. - -The target architecture should preserve those dependency boundaries. - ---- - -## Structural Problems - -### 1. `client.py` combines too many responsibilities - -`src/readwise_sdk/client.py` currently owns: - -- Authentication configuration. -- HTTP client construction. -- Retry policy. -- response handling. -- pagination. -- API client composition through `.v2` and `.v3`. -- public context-manager lifecycle. -- both sync and async implementations. - -The sync and async implementations repeat almost the same request and pagination algorithms at `src/readwise_sdk/client.py:103` and `src/readwise_sdk/client.py:424`. - -This is simultaneously a transport, client facade, retry engine, pagination engine, and dependency container. - -### 2. Sync and async code are maintained as parallel copies - -The duplication is substantial: - -- `src/readwise_sdk/v2/client.py`: 395 lines. -- `src/readwise_sdk/v2/async_client.py`: 418 lines. -- `src/readwise_sdk/v3/client.py`: 311 lines. -- `src/readwise_sdk/v3/async_client.py`: 336 lines. -- `src/readwise_sdk/managers/async_managers.py`: 800 lines, largely mirroring the four synchronous manager modules. - -For example, `HighlightManager.search_highlights()` at `src/readwise_sdk/managers/highlights.py:81` is repeated asynchronously at `src/readwise_sdk/managers/async_managers.py:97`. - -Any semantic fix must currently be made at least twice, often more. - -### 3. Managers are mostly alternate client APIs, not a distinct layer - -Many manager methods simply materialize low-level iterators or rename an existing operation: - -```python -return list(self._client.v2.list_highlights()) -``` - -That pattern appears in `src/readwise_sdk/managers/highlights.py:27`, with similar wrappers for books and documents. - -Other manager methods introduce business behavior, such as: - -- Local text search. -- Bulk operations. -- Statistics. -- Date-range calculation. -- partial-failure handling. - -Those two categories are mixed together. The result is an ambiguous layer: users cannot tell whether a manager is required, optional, or merely another spelling of `.v2`. - -### 4. Workflows, managers, and contrib overlap heavily - -There are multiple implementations of synchronization: - -- `SyncManager` in `src/readwise_sdk/managers/sync.py:74`. -- `BackgroundPoller` in `src/readwise_sdk/workflows/poller.py:75`. -- `BatchSync` in `src/readwise_sdk/contrib/batch_sync.py:113`. -- Async counterparts in `async_managers.py` and `batch_sync.py`. - -They each maintain related state, JSON persistence, timestamps, and callbacks, but with separate data models and behavior. - -Other overlaps include: - -- `HighlightManager.create_highlight()` versus `HighlightPusher`. -- `DocumentManager` versus `DocumentImporter`. -- Manager search methods versus MCP-local search. -- `TagWorkflow` versus manager bulk tagging and low-level tag methods. - -The current directory names describe historical intent rather than architectural roles. - -### 5. CLI and MCP implement operations independently - -The CLI directly queries low-level clients: - -- Highlight filtering and limiting: `src/readwise_sdk/cli/main.py:68`. -- Book listing: `src/readwise_sdk/cli/main.py:180`. -- Reader inbox listing: `src/readwise_sdk/cli/main.py:247`. -- Reader save/archive: `src/readwise_sdk/cli/main.py:285` and `src/readwise_sdk/cli/main.py:302`. - -The MCP server independently implements: - -- Enum validation. -- limit clamping. -- datetime parsing. -- local substring search. -- result projections. -- error translation. -- operation composition. - -For example, document search is defined locally in `src/readwise_sdk/mcp/server.py:231`; highlight search repeats the same pattern at `src/readwise_sdk/mcp/server.py:402`; book search does so again at `src/readwise_sdk/mcp/server.py:549`. - -These are operations, not MCP protocol concerns. - -### 6. Presentation logic is mixed into business objects - -`DigestBuilder` both queries data and renders Markdown, JSON, CSV, and text in `src/readwise_sdk/workflows/digest.py:27`. - -Similarly: - -- The CLI constructs bespoke JSON objects and Rich tables. -- MCP constructs different summary dictionaries in `src/readwise_sdk/mcp/server.py:79`. -- Neither output shape is a declared, reusable contract. - -Data acquisition, business composition, and rendering should be independently testable. - -### 7. Error behavior is inconsistent and sometimes hidden - -Observed patterns include: - -- `get_document()` returns `None` for missing documents at `src/readwise_sdk/v3/client.py:78`. -- Update and delete raise `NotFoundError`. -- Bulk manager operations catch `Exception` and return `False`. -- Tag workflows silently suppress tag failures at `src/readwise_sdk/workflows/tags.py:103`. -- Sync callbacks silently suppress arbitrary callback exceptions at `src/readwise_sdk/managers/sync.py:121`. -- MCP converts SDK errors into JSON strings. -- CLI frequently allows exceptions to escape through Typer. - -There is no declared rule for whether an operation raises, returns a partial result, or suppresses errors. - -### 8. Pagination is nominally generic but still ad hoc - -`paginate()` accepts arbitrary result and cursor keys, and `parse_pagination_cursor()` handles URLs and cursor values. However, endpoint-specific assumptions leak into callers: - -- V2 standard pagination uses `next`. -- V2 export uses integer cursors. -- V3 uses `nextPageCursor`. -- Reader filters accept a tag list, but `list_documents()` only sends the first tag at `src/readwise_sdk/v3/client.py:65`. - -Pagination semantics should be represented by endpoint-specific page decoders, not string arguments passed around the package. - -### 9. High-level code leaks API-version terminology - -High-level operations import directly from `v2.models` and `v3.models`. The MCP server does this at `src/readwise_sdk/mcp/server.py:24`. - -Versions are appropriate at the transport/resource boundary. User concepts should normally be called `highlights`, `books`, `documents`, and `reader_tags`. - -### 10. The adapter layers are excluded from type checking - -`just type` excludes the CLI and MCP packages in `Justfile:18`. - -These are now first-class published surfaces. Their exclusion makes drift between the core, CLI, and MCP more likely. - -### 11. One documented MCP parameter is currently ignored - -`save_to_reader()` accepts `category` at `src/readwise_sdk/mcp/server.py:179`, but the constructed `DocumentCreate` at `src/readwise_sdk/mcp/server.py:211` does not include it. - -Because MCP behavior must remain identical during restructuring, this discrepancy should first receive a characterization test. Fixing it should be a separate, explicit behavior-change PR. - ---- - -# 2. Target Architecture - -## Layering - -```text -Public models and errors - ↓ -Transport and pagination - ↓ -Low-level resource clients - ↓ -Operations / service core - ↓ -SDK facade | CLI adapter | MCP adapter -``` - -Dependencies must point downward only. - -The CLI and MCP packages must not call resource clients directly. Managers, workflows, and contrib compatibility classes should delegate to operations rather than reach into `.v2` or `.v3`. - ---- - -## Proposed Layout - -```text -src/readwise_sdk/ -├── __init__.py -├── config.py -├── errors.py -├── models/ -│ ├── __init__.py -│ ├── readwise.py -│ ├── reader.py -│ ├── queries.py -│ └── results.py -├── transport/ -│ ├── __init__.py -│ ├── config.py -│ ├── errors.py -│ ├── retry.py -│ ├── pagination.py -│ ├── sync.py -│ └── async_.py -├── resources/ -│ ├── __init__.py -│ ├── v2/ -│ │ ├── highlights.py -│ │ ├── books.py -│ │ ├── tags.py -│ │ ├── export.py -│ │ └── review.py -│ └── v3/ -│ ├── documents.py -│ └── tags.py -├── operations/ -│ ├── __init__.py -│ ├── service.py -│ ├── documents.py -│ ├── highlights.py -│ ├── books.py -│ ├── tags.py -│ ├── digests.py -│ ├── imports.py -│ └── sync.py -├── state/ -│ ├── __init__.py -│ ├── store.py -│ └── json_file.py -├── sdk/ -│ ├── __init__.py -│ ├── async_.py -│ └── sync.py -├── presenters/ -│ ├── __init__.py -│ ├── json.py -│ ├── tables.py -│ └── digests.py -├── cli/ -│ ├── main.py -│ ├── context.py -│ ├── output.py -│ └── commands/ -│ ├── documents.py -│ ├── highlights.py -│ ├── books.py -│ ├── tags.py -│ ├── digests.py -│ └── sync.py -├── mcp/ -│ ├── server.py -│ ├── context.py -│ ├── output.py -│ └── tools/ -│ ├── documents.py -│ ├── highlights.py -│ └── books.py -└── compat/ - ├── clients.py - ├── managers.py - ├── workflows.py - └── contrib.py -``` - -Compatibility modules at the current paths should re-export or wrap these implementations. - ---- - -## Core Abstractions - -### `ClientConfig` - -One immutable configuration object should own: - -- API key. -- timeout. -- retry count. -- retry backoff. -- user agent. -- optional base-URL overrides for testing. - -```python -@dataclass(frozen=True, slots=True) -class ClientConfig: - api_key: str - timeout: float = 30.0 - max_retries: int = 3 - retry_backoff: float = 0.5 -``` - -CLI and MCP credential resolution may differ, but both must ultimately produce this same configuration. - -### Transport - -Provide native sync and async transports with identical interfaces: - -```python -class AsyncTransport(Protocol): - async def request(self, request: Request) -> Response: ... - -class SyncTransport(Protocol): - def request(self, request: Request) -> Response: ... -``` - -Shared components should own: - -- Header construction. -- retry classification. -- backoff calculation. -- HTTP-to-SDK exception mapping. -- page decoding rules. - -Only the actual `httpx.Client.request()` versus `httpx.AsyncClient.request()` call and sleeping mechanism should differ. - -### Resource clients - -Resources represent the exact remote APIs. They should: - -- Build endpoint-specific requests. -- Decode API models. -- Expose raw pagination. -- Perform no local text search. -- Perform no Rich/JSON formatting. -- Perform no multi-resource workflow. -- Avoid broad exception suppression. - -Examples: - -```python -await resources.documents.get(document_id, with_content=True) -resources.highlights.iter(updated_after=...) -await resources.documents.update(document_id, update) -``` - -The v2/v3 distinction remains inside `resources/`. - -### Operation inputs - -Use explicit Pydantic input models or frozen dataclasses: - -```python -class DocumentSearch: - location: DocumentLocation | None - category: DocumentCategory | None - updated_after: datetime | None - tags: tuple[str, ...] - query: str | None - limit: int -``` - -These types provide one place for: - -- limit bounds. -- whitespace normalization. -- semantic validation. -- mutually exclusive options. -- default behavior. - -Do not use Typer or FastMCP parameter objects in this layer. - -### Operation results - -Operations should return typed domain models or declared result types, never Rich objects or JSON strings. - -Examples: - -```python -class DocumentSearchResult(BaseModel): - items: list[DocumentSummary] - truncated: bool - -class BulkResult[T](BaseModel): - succeeded: list[T] - failures: list[OperationFailure] - -class SyncResult(BaseModel): - highlights: list[Highlight] - books: list[Book] - documents: list[Document] - checkpoint: SyncCheckpoint -``` - -`DocumentSummary`, `HighlightSummary`, and `BookSummary` are legitimate shared read models because CLI and MCP need the same semantic projection. Protocol-specific JSON shaping remains in the adapters. - -### `ReadwiseService` - -The service is the single public operation container: - -```python -class ReadwiseService: - documents: DocumentOperations - highlights: HighlightOperations - books: BookOperations - tags: TagOperations - digests: DigestOperations - sync: SyncOperations -``` - -Representative operation definitions: - -```python -result = await service.documents.search(input) -document = await service.documents.get(document_id, with_content=True) -created = await service.documents.save(input) -updated = await service.documents.update(document_id, input) - -result = await service.highlights.search(input) -export = await service.highlights.export(input) -created = await service.highlights.create(input) - -result = await service.books.search(input) -``` - -Each is defined once and used from three surfaces. - ---- - -## What Belongs in the Operations Layer - -Operations should own: - -- Search filtering. -- result limits. -- bulk operation semantics. -- date-window calculation. -- multi-request composition. -- partial-failure policy. -- tag merging and normalization. -- digest data selection and grouping. -- synchronization and checkpoints. -- import and truncation policies. - -Adapters should own: - -- Reading command-line or MCP arguments. -- credential discovery. -- human rendering. -- JSON serialization. -- exit codes or MCP error envelopes. -- protocol lifecycle. - -Resource clients should own only API calls. - ---- - -## SDK as an Adapter - -The SDK public API is itself an adapter over the service core. - -### New preferred facade - -```python -from readwise_sdk import AsyncReadwise, Readwise -``` - -Expose concept-oriented attributes: - -```python -readwise.documents -readwise.highlights -readwise.books -readwise.tags -readwise.digests -readwise.sync -``` - -For advanced users, provide an explicitly low-level escape hatch: - -```python -readwise.raw.v2 -readwise.raw.v3 -``` - -Do not retain `.v2` and `.v3` as the primary recommended API. They force users to know endpoint versions and encourage bypassing the operation core. - ---- - -# 3. CLI Design - -## Keep Typer - -Retain Typer because: - -- It already supports the current nested command structure. -- It is a published optional dependency. -- Existing tests use `CliRunner`. -- Replacing it would create migration cost without solving the architectural problem. - -The problem is not Typer. The problem is that `cli/main.py` currently contains command declaration, client creation, API calls, formatting, and error behavior in one 752-line module. - -Split command modules and make each command invoke exactly one service operation. - ---- - -## Proposed Command Tree - -```text -readwise -├── auth -│ └── check -├── documents -│ ├── list -│ ├── get -│ ├── save -│ ├── update -│ ├── delete -│ ├── move -│ └── tag -├── highlights -│ ├── list -│ ├── get -│ ├── create -│ ├── update -│ ├── delete -│ ├── export -│ ├── tag -│ └── untag -├── books -│ ├── list -│ └── get -├── tags -│ ├── list -│ ├── search -│ ├── report -│ ├── auto -│ ├── rename -│ ├── merge -│ └── delete -├── digest -│ ├── daily -│ ├── weekly -│ ├── book -│ └── custom -├── sync -│ ├── full -│ ├── incremental -│ ├── status -│ └── reset -└── version -``` - -### Compatibility aliases - -Retain `readwise reader ...` as a deprecated alias for `readwise documents ...` throughout `0.x`. - -Existing commands such as `reader inbox`, `reader save`, and `reader archive` should continue to work but emit a warning to stderr in human mode. - ---- - -## Global Output Contract - -Add a consistent global option: - -```text ---output table|json|jsonl -``` - -Recommended defaults: - -- Interactive terminal: `table`. -- Redirected stdout: still `table` unless explicitly requested; avoid surprising scripts. -- Automation and agents: `--output json` or `--output jsonl`. - -Additional options: - -```text ---pretty / --no-pretty ---no-color ---quiet ---api-key -``` - -### Output rules - -- Machine-readable data goes to stdout. -- Warnings, progress, and errors go to stderr. -- JSON output never contains Rich markup or progress text. -- JSON contains full values; truncation is only a human-table concern. -- JSON uses stable named fields from result models. -- Streaming list commands support JSONL. -- Exit codes are consistent: - - `0`: success. - - `1`: SDK/API failure. - - `2`: invalid command input. - - `3`: not found. - - `4`: partial bulk failure. - -### Command implementation pattern - -```python -@documents_app.command("list") -def list_documents(options: DocumentOptions) -> None: - result = run_operation( - lambda service: service.documents.search(options.to_input()) - ) - output.render(result) -``` - -No command should directly call `.v2`, `.v3`, or an HTTP client. - ---- - -# 4. MCP Mapping - -The nine existing MCP tool names and return behavior remain unchanged. - -| Existing MCP tool | Core operation | -|---|---| -| `save_to_reader` | `service.documents.save()` | -| `search_documents` | `service.documents.search()` | -| `get_document` | `service.documents.get()` | -| `update_document` | `service.documents.update()` | -| `delete_document` | `service.documents.delete()` | -| `get_highlights` | `service.highlights.search()` | -| `export_highlights` | `service.highlights.export()` | -| `create_highlight` | `service.highlights.create()` | -| `get_books` | `service.books.search()` | - -Each MCP function should contain only: - -1. Protocol argument adaptation. -2. One service call. -3. Existing JSON-envelope rendering. -4. Existing MCP-compatible error translation. - -Example target: - -```python -@mcp.tool() -async def search_documents(...) -> str: - try: - result = await get_service().documents.search( - DocumentSearchInput(...) - ) - return render_mcp_documents(result) - except ReadwiseError as error: - return render_mcp_error(error) -``` - -## Behavior that must remain identical - -Characterization tests should lock: - -- Tool names and argument names. -- default and maximum limits. -- compact JSON strings. -- omission of `None` fields. -- not-found message text. -- invalid-enum error envelopes. -- current lenient datetime parsing. -- current summary fields. -- per-call client lifecycle, unless tests establish that reuse is invisible. -- current `save_to_reader(category=...)` behavior until separately approved. - -The MCP-specific projections in `_doc_summary`, `_highlight_summary`, and `_book_summary` may remain MCP presenters. They are presentation policy, not duplicated operation logic. - ---- - -# 5. Sync Versus Async - -## Recommendation: Async canonical core, explicit sync bridge - -MCP is async, and network operations are naturally async. Therefore the canonical operations implementation should be async. - -The new `Readwise` synchronous facade should execute the async service through a dedicated blocking portal running on its own event-loop thread. `anyio` is the most suitable implementation dependency. - -```python -with Readwise() as readwise: - result = readwise.documents.search(...) -``` - -Internally: - -```python -portal.call(async_service.documents.search, input) -``` - -## Why not `asyncio.run()` per method? - -It fails when called from a thread already running an event loop, and it repeatedly creates clients and event loops. That is unsuitable for notebooks and mixed async applications. - -## Why not keep handwritten parallel operation layers? - -That is the current failure mode. It guarantees semantic drift across: - -- managers. -- async managers. -- workflows. -- contrib. -- CLI. -- MCP. - -## Caveat: streaming - -Bridging an async iterator to a synchronous iterator requires queueing across the portal and complicates lifecycle management. - -Therefore: - -- Core user-facing operations should normally return bounded result objects. -- Advanced raw resources may retain native sync and async iterators. -- Sync streaming can be added deliberately later if required. -- Existing generator APIs remain available through compatibility clients. - -## Transitional strategy - -During `0.3`: - -- New `AsyncReadwise` uses the canonical operations directly. -- New `Readwise` uses the blocking portal. -- Existing `ReadwiseClient` and `AsyncReadwiseClient` remain as compatibility facades. -- Existing low-level sync clients continue working until `1.0`. - -This avoids forcing the transport/resource migration and public sync migration into one risky step. - ---- - -# 6. Migration Options - -## Option A — Aggressive Restructure - -### Description - -Introduce the new concept-oriented API and move all new development to it. Existing modules become compatibility layers. - -### Breaking-change inventory - -Without shims, the following are public breaks. - -#### Root imports - -Current imports include: - -```python -from readwise_sdk import ReadwiseClient, AsyncReadwiseClient -from readwise_sdk import HighlightManager, DigestBuilder -``` - -Target imports become: - -```python -from readwise_sdk import Readwise, AsyncReadwise -``` - -#### Client attributes - -Current: - -```python -client.v2.list_highlights() -client.v3.list_documents() -``` - -Target: - -```python -client.highlights.search() -client.documents.search() -client.raw.v2... -client.raw.v3... -``` - -#### Versioned client imports - -These paths would move: - -```python -readwise_sdk.v2.client.ReadwiseV2Client -readwise_sdk.v2.async_client.AsyncReadwiseV2Client -readwise_sdk.v3.client.ReadwiseV3Client -readwise_sdk.v3.async_client.AsyncReadwiseV3Client -``` - -#### Models - -Current MCP and external users may import: - -```python -from readwise_sdk.v2.models import HighlightCreate -from readwise_sdk.v3.models import DocumentCreate, DocumentUpdate -``` - -Target canonical paths: - -```python -from readwise_sdk.models.readwise import HighlightCreate -from readwise_sdk.models.reader import DocumentCreate, DocumentUpdate -``` - -The existing paths should remain re-export modules until `1.0`. - -#### Managers and workflows - -These become deprecated operation wrappers: - -```python -readwise_sdk.managers.* -readwise_sdk.workflows.* -readwise_sdk.contrib.* -``` - -#### Return and failure semantics - -Some current APIs return: - -- iterators. -- lists. -- `None`. -- `dict[id, bool]`. -- formatted strings. - -The target operations return declared typed result objects. Compatibility wrappers must preserve old return values. - -#### MCP internal imports - -The MCP server currently imports `AsyncReadwiseClient` from the package root and request models from `v2.models`/`v3.models` at `src/readwise_sdk/mcp/server.py:19`. - -It should migrate to `AsyncReadwise` and canonical model/input paths, while compatibility re-exports preserve external integrations. - -### Deprecation plan - -- `0.3.0`: add the new API and aggressively restructure internals. -- `0.3.x`: emit `DeprecationWarning` for legacy constructors and manager/workflow creation. -- Keep old module paths as re-exports. -- Keep `.v2` and `.v3` functional but document them as low-level compatibility APIs. -- `0.4+`: no new features on deprecated surfaces. -- `1.0.0`: remove deprecated managers/workflows and old client names after a documented migration window. - -Warnings should be emitted on object construction or deprecated method use, not merely importing a module. Import-time warnings are noisy and difficult for downstream users to control. - -### Version - -Use **`0.3.0`**, not `1.0.0`. - -The project is currently `0.2.1` and classified as alpha. A breaking minor release is semantically legitimate before 1.0. The new architecture should prove itself across one or more `0.x` releases before declaring a stable 1.0 contract. - ---- - -## Option B — Conservative Refactor - -### Description - -Keep `ReadwiseClient`, `.v2`, `.v3`, managers, workflows, and contrib as the documented API. Internally route CLI and MCP through a newly added service layer. - -### Advantages - -- Minimal downstream migration. -- Lower short-term release risk. -- Documentation changes can be incremental. -- Existing users see little disruption. - -### Disadvantages - -- The package retains two competing public abstractions. -- `.v2/.v3` remains the easiest and most visible route. -- Manager/workflow naming remains ambiguous. -- New service capabilities must coexist indefinitely with obsolete organization. -- It becomes harder to remove sync/async duplication later. -- The “single source of truth” exists internally but not conceptually for users. - ---- - -## Recommendation - -**Choose Option A.** - -This package is still at `0.2.1`, the codebase is modest in size, and MCP has exposed the cost of the current architecture. This is the correct time to establish a coherent public model. - -Be aggressive about internal organization and the new recommended API, but pragmatic about compatibility: - -- Preserve old imports through re-exports. -- Preserve old return values through wrappers. -- Do not preserve old internals. -- Remove the compatibility surface only at 1.0. - ---- - -# 7. Staged Execution Plan - -Each stage is intended to be one PR or a small cluster of tightly related PRs. Every stage ends with `just fc` passing. - -## PR 1 — Add characterization contracts - -Before moving code, lock observable behavior. - -Add tests for: - -- Root exports and import paths. -- `ReadwiseClient` constructor, context manager, `.v2`, `.v3`, and `create_optional()`. -- Sync and async pagination cursor behavior. -- Existing manager return types. -- sync-state JSON file formats. -- CLI stdout, stderr, exit codes, and JSON structures. -- All nine MCP tools, including exact error envelopes and field omission. -- MCP limit clamping and lenient invalid-datetime behavior. -- `save_to_reader(category=...)` request payload as currently implemented. -- callback exception suppression where currently documented by behavior. -- bulk-operation partial-failure maps. - -No production behavior changes. - -## PR 2 — Introduce canonical config and errors - -Add: - -- `config.py`. -- `errors.py`. -- immutable client configuration. -- credential resolution utilities shared where appropriate. -- error classification helpers. - -Keep `exceptions.py` as a re-export. - -Existing clients delegate to the new configuration and exception definitions. - -## PR 3 — Extract retry and pagination infrastructure - -Move shared logic from `client.py` and `_utils.py` into: - -- `transport/retry.py`. -- `transport/pagination.py`. -- `transport/errors.py`. - -Introduce endpoint-aware page decoders: - -```python -StandardV2Page -ExportV2Page -ReaderV3Page -``` - -Keep `ReadwiseClient.paginate()` and `AsyncReadwiseClient.paginate()` as compatibility wrappers. - -Characterization tests must confirm identical requests and retry timing decisions. - -## PR 4 — Introduce async transport and resources - -Create canonical async resources for: - -- v2 highlights. -- v2 books. -- v2 tags. -- v2 export/review. -- v3 documents. -- v3 tags. - -Make `AsyncReadwiseV2Client` and `AsyncReadwiseV3Client` delegate to them. - -Do not change public methods or return types. - -## PR 5 — Add operation inputs and result models - -Introduce: - -- search input models. -- create/update inputs where existing API models are insufficient. -- summary read models. -- `BulkResult`. -- `OperationFailure`. -- unified `SyncCheckpoint` and `SyncResult`. - -This PR should be mostly additive and model-level. - -## PR 6 — Implement document operations - -Create canonical operations for: - -- search. -- get. -- save. -- update. -- delete. -- move. -- set/add/remove tags. -- inbox/archive/later views. -- statistics. - -Port semantics from: - -- `DocumentManager`. -- `ReadingInbox`. -- `DocumentImporter`. -- MCP document tools. -- CLI Reader commands. - -Test operations directly with fake resources where possible and with `respx` integration tests where transport behavior matters. - -## PR 7 — Implement highlight and book operations - -Create canonical operations for: - -- highlight search/list/get/create/update/delete. -- bulk tag and untag. -- export. -- book search/list/get. -- book-with-highlights. -- reading statistics. -- highlight truncation and partial-failure policies. - -Port semantics from: - -- highlight and book managers. -- `HighlightPusher`. -- CLI. -- MCP. - -Do not yet delete legacy implementations. - -## PR 8 — Migrate the nine MCP tools - -Change each MCP tool to call one operation. - -Move presentation helpers to `mcp/output.py`. - -Preserve: - -- names. -- argument schemas. -- return strings. -- error JSON. -- summary fields. -- limits. -- documented per-tool behavior. - -Run the MCP tool tests after migrating each tool group rather than waiting for all nine. - -## PR 9 — Add the new async SDK facade - -Add `AsyncReadwise` composed from the canonical service. - -Expose: - -```python -.documents -.highlights -.books -.tags -.digests -.sync -.raw -``` - -Add public facade tests and documentation examples. - -Keep `AsyncReadwiseClient` unchanged externally but let it share resources. - -## PR 10 — Add the synchronous SDK facade - -Add `Readwise` using a dedicated AnyIO blocking portal. - -Test: - -- ordinary synchronous use. -- use from a thread with an already running event loop. -- context-manager cleanup. -- repeated operations. -- exceptions crossing the portal. -- cancellation and close behavior. - -Do not convert legacy synchronous iterators yet. - -## PR 11 — Rebuild the CLI shell - -Split `cli/main.py` into command modules. - -Add: - -- global `--output`. -- common output renderer. -- consistent errors and exit codes. -- service context/lifecycle. -- strict stdout/stderr separation. - -Initially migrate direct equivalents only: - -- documents. -- highlights. -- books. -- version/auth. - -Keep old command names and output defaults. - -## PR 12 — Expand the CLI - -Add missing core-backed commands: - -- document get/update/delete/move/tag. -- highlight create/update/delete/tag/untag. -- custom digest. -- sync status/reset. -- JSONL output. -- global no-color and quiet behavior. - -Add deprecated `reader` aliases for `documents`. - -## PR 13 — Consolidate tags and digests - -Move: - -- `TagWorkflow`. -- digest data selection. -- grouping logic. - -into operations. - -Move Markdown, text, CSV, and JSON rendering into presenters. - -`DigestBuilder` becomes a compatibility wrapper that calls digest operations plus a presenter. - -## PR 14 — Consolidate synchronization and persistence - -Replace duplicated state handling with: - -```python -class StateStore(Protocol): - def load(self) -> SyncCheckpoint: ... - def save(self, checkpoint: SyncCheckpoint) -> None: ... -``` - -Provide `JsonFileStateStore`. - -Rebuild: - -- full sync. -- incremental sync. -- poll-once. -- batch callbacks. -- background scheduling. - -on the same sync operation. - -Keep legacy state-file readers capable of loading current formats. - -## PR 15 — Convert managers, workflows, and contrib to shims - -Replace implementation bodies with delegation. - -For example: - -```python -class HighlightManager: - def search_highlights(...): - warn_deprecated(...) - return self._client.operations.highlights.search_legacy(...) -``` - -Preserve old return types and failure behavior. - -Once delegation is complete, delete duplicated implementation code. - -## PR 16 — Canonicalize model paths - -Move canonical definitions to: - -- `models/readwise.py`. -- `models/reader.py`. - -Keep: - -- `v2/models.py`. -- `v3/models.py`. - -as re-export modules. - -Update internal code, including MCP, to import only canonical paths. - -## PR 17 — Tighten typing and packaging - -- Remove CLI and MCP exclusions from `Justfile:18`. -- Type-check adapters. -- Ensure importing core does not import Typer, Rich, or MCP. -- Verify wheels with core only, `[cli]`, and `[mcp]`. -- Verify both console scripts. -- Add a `py.typed` marker if not already included. -- Build with Hatchling and inspect wheel contents. - -## PR 18 — Documentation and deprecation release - -Update: - -- README. -- `llms.txt`. -- API guides. -- CLI documentation. -- migration guide. -- deprecation timeline. -- architecture contributor guide. - -Release as: - -```text -feat!: introduce unified Readwise operations architecture -``` - -Version: `0.3.0`. - ---- - -# 8. Risks and De-Risking - -## Public API breakage - -**Risk:** Downstream users may import undocumented-but-accessible classes and models. - -**Mitigation:** - -- Keep old modules as re-exports. -- Add import-contract tests. -- Search README, docs, tests, and release history for every promoted import. -- Publish a migration table. -- Delay removals until 1.0. - -## Behavioral drift in MCP - -**Risk:** Moving validation, filtering, and serialization changes tool output. - -**Mitigation:** - -- Treat current MCP JSON as a wire contract. -- Add exact characterization tests before migration. -- Migrate one tool group at a time. -- Keep MCP presenters separate from general JSON presenters. -- Make behavior fixes in separate PRs after the refactor. - -## Sync bridge complexity - -**Risk:** Threaded portal lifecycle, exceptions, and streaming can be subtle. - -**Mitigation:** - -- Keep the sync facade deliberately small. -- Avoid sync streaming in the new operation API initially. -- Retain legacy native-sync raw clients. -- Add tests for running-event-loop environments. -- Make ownership explicit: the facade owns and closes its portal and async client. - -## State-file incompatibility - -**Risk:** Users may have persisted `SyncManager`, `BatchSync`, or poller state. - -**Mitigation:** - -- Add version fields to new state files. -- Write migration readers for all existing structures. -- Never silently reset malformed or unknown state. -- Back up or preserve legacy files before rewriting. -- Characterize current datetime formatting. - -## Loss of partial-failure semantics - -**Risk:** Existing bulk methods frequently suppress exceptions and return booleans. - -**Mitigation:** - -- Introduce a typed `BulkResult`. -- Compatibility wrappers convert it back to current dictionaries/lists. -- Record the original exception in the new result. -- Do not continue broad `except Exception` in canonical operations. - -## Over-generalized operation framework - -**Risk:** A command bus, registry, or generated metaprogramming system could obscure simple calls. - -**Mitigation:** - -- Use explicit service classes and ordinary methods. -- Do not derive CLI or MCP schemas automatically from operation signatures. -- Share behavior, not protocol metadata. -- Prefer duplicated five-line adapter declarations over a clever universal decorator. - -## Dependency leakage - -**Risk:** Core imports may accidentally require CLI or MCP extras. - -**Mitigation:** - -- Keep adapters at the outermost layer. -- Test importing `readwise_sdk` with only core dependencies installed. -- Keep FastMCP imports entirely under `readwise_sdk.mcp`. -- Keep Rich and Typer imports entirely under `readwise_sdk.cli`. - -## Type-checking expansion - -**Risk:** Enabling `ty` for CLI and MCP may expose many existing issues. - -**Mitigation:** - -- Add adapter typing after splitting the large modules. -- Remove exclusions directory by directory. -- Use typed context objects and result presenters. -- Avoid `Any` in operation boundaries even if protocol adapters require it. - ---- - -# Final Recommendation - -Proceed with an **aggressive `0.3.0` architecture migration** built around an async `ReadwiseService`. - -The key rule should be: - -> Resource clients know Readwise endpoints. Operations know user intent. Adapters know presentation and protocol. - -Under that rule: - -- `.v2` and `.v3` become low-level compatibility access. -- Managers, workflows, and contrib stop owning behavior. -- CLI commands and MCP tools call the same operation methods. -- Async behavior is canonical. -- Sync is a deliberate facade, not a second implementation. -- Existing imports and observable behavior survive through tested shims until `1.0`. \ No newline at end of file diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..d254fd2 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,53 @@ +# Migrating to the 0.3 concept-oriented API + +`readwise-plus` `0.3` introduces `Readwise` and `AsyncReadwise` as the preferred SDK entry points, backed by a shared async-first operations layer that the CLI and MCP server now also call. **Nothing is removed.** Every import, class, and method that worked before `0.3` still works — the old surfaces (`ReadwiseClient`, `.v2`/`.v3`, managers, workflows, contrib) are now documented as compatibility APIs rather than the primary path. + +You do not need to migrate existing code. Migrate incrementally, or only when touching a piece of code anyway. + +## Why change + +Before `0.3`, the SDK exposed multiple overlapping ways to do the same thing (`.v2.list_highlights()` vs. `HighlightManager.get_all_highlights()` vs. `HighlightPusher`), and the CLI and MCP server each reimplemented their own filtering, limits, and error handling on top of the low-level clients. `0.3` introduces one canonical operations layer — `readwise.documents`, `readwise.highlights`, `readwise.books`, `readwise.tags`, `readwise.digests`, `readwise.sync` — that the SDK facade, CLI, and MCP server all call, so behavior is consistent across every surface. `.v2`/`.v3` remain available as an explicit, documented low-level escape hatch (`.raw.v2` / `.raw.v3` from the new facade). + +## Mapping: old → new + +| Old | New | Notes | +|---|---|---| +| `from readwise_sdk import ReadwiseClient, AsyncReadwiseClient` | `from readwise_sdk import Readwise, AsyncReadwise` | Both old and new root imports work; `Readwise`/`AsyncReadwise` are now the documented entry points. | +| `client.v2.list_highlights(...)` | `readwise.highlights.search(HighlightSearch(...))` or `.list(...)` | `search()` takes a validated `HighlightSearch` input and returns a `HighlightSearchResult`; `.list()` takes the same filters as plain keyword arguments and returns `list[Highlight]`. | +| `client.v2.list_books(...)` | `readwise.books.search(BookSearch(...))` or `.list(...)` | Same pattern as highlights. | +| `client.v3.list_documents(...)` | `readwise.documents.search(DocumentSearch(...))` | Returns a `DocumentSearchResult` of `DocumentSummary` items (bounded, projected) rather than an unbounded iterator of full `Document` objects. Use `readwise.documents.get(id, with_content=True)` for the full document. | +| `client.v3.save_url(url, ...)` | `readwise.documents.save(DocumentCreate(url=url, ...))` | | +| `client.v3.update_document(id, update)` | `readwise.documents.update(id, update)` | | +| `client.v2.export_highlights(...)` | `readwise.highlights.export(...)` | | +| `client.v2.get_daily_review()` | No direct operation yet — use `readwise.raw.v2.get_daily_review()` | Daily review has not been ported to the operations layer; the low-level client still exposes it. | +| `HighlightManager(client)` / `BookManager(client)` / `DocumentManager(client)` | `readwise.highlights` / `readwise.books` / `readwise.documents` | Managers are now thin synchronous compatibility wrappers that delegate to the same operations the facade uses. | +| `DigestBuilder(client)` | `readwise.digests` (data) + `readwise_sdk.presenters.render_digest` (formatting) | `DigestBuilder` is now a compatibility wrapper combining a digest operation call with a presenter call. | +| `TagWorkflow(client)` | `readwise.tags` | | +| `ReadingInbox(client)` | `readwise.documents` (`.inbox()`, `.later()`, `.archive()`, `.statistics()`) | | +| `BackgroundPoller(client)` | `readwise.sync` (`.poll_once()`, `.full()`, `.incremental()`) | | +| `HighlightPusher(client)` | `readwise.highlights.push_batch(...)` / `.create_from_fields(...)` | | +| `DocumentImporter(client)` | `readwise.documents.save(...)` / `.get(..., with_content=True)` | | +| `BatchSync(client, config=...)` | `readwise.sync.batch_highlights(...)` / `.batch_books(...)` / `.batch_documents(...)` | | +| `readwise_sdk.v2.models.HighlightCreate` | `readwise_sdk.models.readwise.HighlightCreate` | `v2.models` and `v3.models` are now identity-preserving re-export modules — the same classes, importable from either path. | +| `readwise_sdk.v3.models.DocumentCreate` | `readwise_sdk.models.reader.DocumentCreate` | Same re-export relationship as above. | + +### CLI + +The command tree is unchanged in spirit and additive in practice — every pre-0.3 command still works with its original defaults (human-readable table output, no `--output` flag needed). New in `0.3`: + +- A global `--output table|json|jsonl` option (must precede the subcommand, e.g. `readwise --output json sync full`), plus `--no-color` and `--quiet`. +- `readwise documents ...` alongside the original `readwise reader ...` (kept as a deprecated alias — it still works, and emits a stderr warning in table mode). +- New subcommands: `documents get/update/delete/move/tag`, `highlights update/delete/tag/untag`, `books show` (with highlights), `digest custom`, `sync status/reset`, `tags untagged/report`. + +### MCP server + +Unchanged. All nine tool names, argument schemas, and JSON return shapes are the same as before `0.3` — the tools now call the shared operations layer internally, but this is not observable from the MCP client side. + +## Deprecation timeline + +- **`0.3.0`** (this release): adds `Readwise`/`AsyncReadwise` and the operations layer; every pre-existing import, class, and method keeps working unchanged as a compatibility surface. No warnings are emitted yet. +- **Later `0.3.x`**: a `DeprecationWarning` will be added on construction of the legacy `ReadwiseClient`/`AsyncReadwiseClient` and the managers/workflows/contrib classes, pointing at the equivalent `Readwise`/`AsyncReadwise` operation. Import paths (`readwise_sdk.v2.models`, `readwise_sdk.managers`, etc.) keep working with no warning. +- **`0.4+`**: no new features land on the compatibility surface; new capabilities are added to the operations layer and facade only. +- **`1.0.0`**: the compatibility surface (`ReadwiseClient`/`AsyncReadwiseClient`, managers, workflows, contrib, and the `v2.models`/`v3.models` re-export modules) is removed. `.raw.v2`/`.raw.v3` on the facade remain as the supported low-level access path. + +If you have code depending on the compatibility surface, there is no urgency: it is fully supported through the entire `0.x` series and will only be removed at a `1.0.0` release announced separately. diff --git a/README.md b/README.md index c40f2d7..6b94fd6 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![Python versions](https://img.shields.io/pypi/pyversions/readwise-plus)](https://pypi.org/project/readwise-plus/) [![License](https://img.shields.io/github/license/EvanOman/readwise-plus)](https://github.com/EvanOman/readwise-plus/blob/main/LICENSE) -Comprehensive Python SDK for [Readwise](https://readwise.io) with high-level workflow abstractions. Supports both the Readwise API (v2) for highlights/books and the Reader API (v3) for documents. +Comprehensive Python SDK for [Readwise](https://readwise.io), covering both the Readwise API (v2) for highlights/books and the Reader API (v3) for documents behind one concept-oriented interface. ## Table of Contents @@ -14,10 +14,8 @@ Comprehensive Python SDK for [Readwise](https://readwise.io) with high-level wor - [Installation](#installation) - [Quick Start](#quick-start) - [Architecture](#architecture) -- [Core API Usage](#core-api-usage) -- [Managers](#managers) -- [Workflows](#workflows) -- [Contrib Interfaces](#contrib-interfaces) +- [Concept Operations](#concept-operations) +- [Compatibility APIs](#compatibility-apis) - [CLI](#cli) - [MCP Server](#mcp-server) - [Development](#development) @@ -26,12 +24,11 @@ Comprehensive Python SDK for [Readwise](https://readwise.io) with high-level wor ## Features -- **V2 API (Readwise)**: Full support for highlights, books, tags, and daily review -- **V3 API (Reader)**: Full support for documents, inbox, reading list, and archive -- **Managers**: High-level abstractions for common operations -- **Workflows**: Pre-built workflows for digests, tagging, and syncing -- **Contrib**: Convenience interfaces for common integration patterns -- **CLI**: Command-line interface for quick operations +- **Concept-oriented facade**: `Readwise` / `AsyncReadwise` expose `.documents`, `.highlights`, `.books`, `.tags`, `.digests`, and `.sync` — one place to call each operation, shared by the SDK, CLI, and MCP server +- **Raw escape hatch**: `.raw.v2` / `.raw.v3` for direct, low-level Readwise/Reader API access when you need it +- **CLI**: full command tree (`documents`, `highlights`, `books`, `tags`, `digest`, `sync`) with `--output table|json|jsonl` +- **MCP server**: nine tools for AI agents (Claude Code, Claude Desktop, or any MCP client) +- **Compatibility APIs**: the pre-0.3 `ReadwiseClient`, managers, workflows, and contrib helpers keep working unchanged — see [Compatibility APIs](#compatibility-apis) and [MIGRATION.md](MIGRATION.md) ## Installation @@ -54,370 +51,240 @@ pip install readwise-plus[mcp] ## Quick Start ```python -from readwise_sdk import ReadwiseClient - -# Initialize with your API token -client = ReadwiseClient(api_key="your_token_here") +from readwise_sdk import Readwise +from readwise_sdk.models import DocumentSearch -# Or use environment variable READWISE_API_KEY -client = ReadwiseClient() +with Readwise() as readwise: # reads READWISE_API_KEY from the environment + result = readwise.documents.search(DocumentSearch(query="python", limit=20)) + for doc in result.items: + print(doc.title) +``` -# Validate your token -client.validate_token() +Async, for agent runtimes and async apps: -# Get all highlights -for highlight in client.v2.highlights.list(): - print(highlight.text) +```python +from readwise_sdk import AsyncReadwise +from readwise_sdk.models import DocumentSearch -# Get Reader inbox -for doc in client.v3.documents.list(location="new"): - print(doc.title) +async with AsyncReadwise() as readwise: + result = await readwise.documents.search(DocumentSearch(query="python", limit=20)) + for doc in result.items: + print(doc.title) ``` -## Architecture +`Readwise` and `AsyncReadwise` are the preferred entry points as of `0.3`. New code should start here — see [Concept Operations](#concept-operations) below. Everything under [Compatibility APIs](#compatibility-apis) (`ReadwiseClient`, `.v2`/`.v3`, managers, workflows, contrib) still works and is not scheduled for removal before `1.0`; if you have existing code using it, there is no need to migrate immediately. -The SDK is organized into layers of increasing abstraction: +## Architecture ``` readwise-plus/ -├── Core Layer -│ ├── V2 Client → client.v2.* (Readwise API) -│ └── V3 Client → client.v3.* (Reader API) -├── Manager Layer -│ ├── HighlightManager → Highlight operations -│ ├── BookManager → Book operations -│ ├── DocumentManager → Document operations -│ └── SyncManager → Sync state tracking -├── Workflow Layer -│ ├── DigestBuilder → Create highlight digests -│ ├── ReadingInbox → Inbox management -│ ├── TagWorkflow → Auto-tagging -│ └── BackgroundPoller → Background sync -└── Contrib Layer - ├── HighlightPusher → Push highlights to Readwise - ├── DocumentImporter → Import documents to Reader - └── BatchSync → Batch synchronization +├── Concept facade → Readwise | AsyncReadwise +│ ├── .documents Reader documents (v3) +│ ├── .highlights Readwise highlights (v2) +│ ├── .books Readwise books/sources (v2) +│ ├── .tags Tag reports, auto-tag, merge/rename/delete +│ ├── .digests Daily/weekly/book/custom digest data +│ ├── .sync Full/incremental sync, checkpoints +│ └── .raw.v2 / .raw.v3 Low-level escape hatch (same clients as below) +├── Operations layer → async-first; shared by the facade, CLI, and MCP server +├── Resource clients → readwise_sdk.resources.v2 / .v3 (endpoint-only) +└── Compatibility layer → ReadwiseClient/.v2/.v3, managers, workflows, contrib ``` -## Core API Usage +The CLI and MCP server call the same operations layer as the `Readwise`/`AsyncReadwise` facade, so behavior (limits, filtering, error handling) is consistent across all three surfaces. See [docs/architecture.md](docs/architecture.md) for a short contributor-facing note on the layering, and [MIGRATION.md](MIGRATION.md) for the old→new API mapping and deprecation timeline. -### V2 API (Readwise Highlights) +## Concept Operations + +Each concept attribute exposes the same methods on both `Readwise` (sync) and `AsyncReadwise` (`await`-prefixed): ```python -from readwise_sdk import ReadwiseClient -from datetime import datetime - -client = ReadwiseClient() - -# List highlights with filtering -highlights = client.v2.highlights.list( - book_id=123, - updated_after=datetime(2024, 1, 1), -) - -# Get a specific highlight -highlight = client.v2.highlights.get(highlight_id=456) - -# Create a highlight -new_highlight = client.v2.highlights.create( - text="Important quote from the book", - title="Book Title", - author="Author Name", - source_type="book", -) - -# Export all highlights with full book metadata -for book in client.v2.export_highlights(): - print(f"{book.title}: {len(book.highlights)} highlights") - for h in book.highlights: - print(f" - {h.text[:50]}...") - -# Get daily review highlights -review = client.v2.get_daily_review() -for highlight in review.highlights: - print(highlight.text) -``` +from readwise_sdk import Readwise +from readwise_sdk.models import BookSearch, DocumentSearch, HighlightSearch -### V3 API (Reader Documents) +with Readwise() as readwise: + # Documents (Reader v3) + docs = readwise.documents.search(DocumentSearch(location="later", query="python")) + doc = readwise.documents.get(docs.items[0].id, with_content=True) + readwise.documents.add_tag(doc.id, "to-review") -```python -# List inbox documents -for doc in client.v3.documents.list(location="new"): - print(f"{doc.title} ({doc.category})") + # Highlights (Readwise v2) + highlights = readwise.highlights.search(HighlightSearch(query="python")) + created = readwise.highlights.create_from_fields( + text="Important quote", title="Book Title", author="Author Name" + ) -# Save a URL to Reader -result = client.v3.save_url("https://example.com/article") -print(f"Saved: {result.id}") + # Books (Readwise v2) + books = readwise.books.search(BookSearch(query="python")) + with_highlights = readwise.books.with_highlights(books.items[0].id) -# Get document with full content -doc = client.v3.documents.get(doc_id, with_html=True) -print(doc.html) + # Tags + report = readwise.tags.get_tag_report() -# Move document to archive -client.v3.documents.update(doc_id, location="archive") + # Digests + daily = readwise.digests.daily() -# Filter by category -articles = client.v3.documents.list(category="article") -pdfs = client.v3.documents.list(category="pdf") + # Sync + checkpoint = readwise.sync.status() ``` -## Managers +For advanced or low-level use, `readwise.raw.v2` and `readwise.raw.v3` return the same client objects documented under [Compatibility APIs](#compatibility-apis). -Managers provide higher-level operations with better ergonomics. +## Compatibility APIs -### HighlightManager +Everything below predates the `0.3` concept facade. It is unchanged and fully supported — these are not "legacy" in the sense of being broken or scheduled for imminent removal, just no longer the recommended starting point for new code. See [MIGRATION.md](MIGRATION.md) for the full old→new mapping and the deprecation timeline through `1.0`. + +### `ReadwiseClient` / `AsyncReadwiseClient` ```python -from readwise_sdk.managers import HighlightManager +from readwise_sdk import ReadwiseClient +from readwise_sdk.v3.models import DocumentLocation -highlights = HighlightManager(client) +client = ReadwiseClient(api_key="your_token_here") # or READWISE_API_KEY env var +client.validate_token() -# Get recent highlights -recent = highlights.get_highlights_since(days=7) +# V2 API (Readwise) — highlights and books +for highlight in client.v2.list_highlights(): + print(highlight.text) -# Search highlights -results = highlights.search("python programming") +review = client.v2.get_daily_review() -# Bulk operations -highlights.bulk_tag(highlight_ids, "to-review") -highlights.bulk_delete(highlight_ids) +# V3 API (Reader) — documents +for doc in client.v3.list_documents(location=DocumentLocation.LATER): + print(doc.title) -# Get highlights by book -book_highlights = highlights.get_by_book(book_id=123) +result = client.v3.save_url("https://example.com/article") +client.close() ``` -### BookManager +### Managers ```python -from readwise_sdk.managers import BookManager - -books = BookManager(client) - -# List all books -all_books = books.list() - -# Get books by category -articles = books.get_by_category("articles") - -# Get book with highlights -book = books.get_with_highlights(book_id=123) -``` +from readwise_sdk.managers import BookManager, DocumentManager, HighlightManager +from readwise_sdk import BookCategory -### DocumentManager +highlights = HighlightManager(client) +recent = highlights.get_highlights_since(days=7) +matches = highlights.search_highlights("python programming") -```python -from readwise_sdk.managers import DocumentManager +books = BookManager(client) +python_books = books.get_books_by_category(BookCategory.BOOKS) +book_with_highlights = books.get_book_with_highlights(book_id=123) docs = DocumentManager(client) - -# Get inbox inbox = docs.get_inbox() - -# Archive a document -docs.archive(doc_id) - -# Get reading stats -stats = docs.get_stats() -print(f"Inbox: {stats.inbox_count}, Archive: {stats.archive_count}") +docs.archive(inbox[0].id) ``` -## Workflows - -Pre-built workflows for common use cases. - -### DigestBuilder +### Workflows ```python -from readwise_sdk.workflows import DigestBuilder +from readwise_sdk.workflows import DigestBuilder, TagWorkflow +from readwise_sdk.workflows.tags import TagPattern digest = DigestBuilder(client) - -# Daily digest -daily = digest.build_daily() -print(daily.to_markdown()) - -# Weekly digest -weekly = digest.build_weekly() - -# Book-specific digest -book_digest = digest.build_for_book(book_id=123) -book_digest.save("book-notes.md") -``` - -### TagWorkflow - -```python -from readwise_sdk.workflows.tags import TagWorkflow, TagPattern +print(digest.create_daily_digest()) workflow = TagWorkflow(client) - -# Define tagging patterns patterns = [ TagPattern(r"\bpython\b", "python", case_sensitive=False), - TagPattern(r"\bmachine learning\b", "ml", case_sensitive=False), - TagPattern(r"TODO:", "actionable", search_in_notes=True), + TagPattern(r"TODO:", "actionable", match_in_notes=True), ] - -# Auto-tag highlights result = workflow.auto_tag_highlights(patterns, dry_run=True) -print(f"Would tag {result.matched_count} highlights") - -# Apply tags -result = workflow.auto_tag_highlights(patterns, dry_run=False) - -# Rename a tag -workflow.rename_tag(old_name="todo", new_name="actionable") +print(f"Would tag {len(result)} highlights") ``` -### ReadingInbox +### Contrib ```python -from readwise_sdk.workflows import ReadingInbox - -inbox = ReadingInbox(client) - -# Get prioritized inbox -prioritized = inbox.get_prioritized(limit=10) - -# Triage inbox items -for doc in inbox.get_untriaged(): - if doc.word_count < 500: - inbox.archive(doc.id) - else: - inbox.move_to_later(doc.id) -``` - -## Contrib Interfaces - -Simplified interfaces for common integration patterns. - -### HighlightPusher - -```python -from readwise_sdk.contrib import HighlightPusher +from readwise_sdk.contrib import BatchSync, BatchSyncConfig, DocumentImporter, HighlightPusher pusher = HighlightPusher(client) - -# Push a single highlight -pusher.push( - text="Great quote from the article", - title="Article Title", - source_url="https://example.com/article", -) - -# Push multiple highlights -pusher.push_batch([ - {"text": "Quote 1", "title": "Book 1"}, - {"text": "Quote 2", "title": "Book 2"}, -]) -``` - -### DocumentImporter - -```python -from readwise_sdk.contrib import DocumentImporter +pusher.push(text="Great quote from the article", title="Article Title", source_url="https://example.com/article") importer = DocumentImporter(client) +doc_id = importer.save_url("https://example.com/article", tags=["to-read", "python"]) -# Import a URL -doc = importer.import_url("https://example.com/article") - -# Import with tags -doc = importer.import_url( - "https://example.com/article", - tags=["to-read", "python"], -) +sync = BatchSync(client, config=BatchSyncConfig(batch_size=100, state_file="sync_state.json")) +result = sync.sync_highlights(on_item=lambda h: print(h.text)) ``` -### BatchSync - -```python -from readwise_sdk.contrib import BatchSync, BatchSyncConfig - -config = BatchSyncConfig( - batch_size=100, - state_file="sync_state.json", -) -sync = BatchSync(client, config=config) - -# Sync with callback -def on_highlight(highlight): - save_to_database(highlight) +## CLI -result = sync.sync_highlights(on_item=on_highlight) -print(f"Synced {result.synced_count} highlights") +```bash +readwise [--output table|json|jsonl] [--no-color] [--quiet] ... ``` -## CLI - -The CLI provides quick access to common operations. +`--output` defaults to `table`; use `json` or `jsonl` for scripting and agent use. `--no-color` disables Rich styling; `--quiet` suppresses non-data notices. ### Highlights ```bash -# List recent highlights -readwise highlights list --limit 10 - -# Show a specific highlight +readwise highlights list --limit 10 --book-id 123 readwise highlights show 123456 - -# Export highlights +readwise highlights create "Important quote" --title "Book Title" --author "Author Name" +readwise highlights update 123456 --note "revised note" +readwise highlights delete 123456 +readwise highlights tag 123456 to-review +readwise highlights untag 123456 to-review readwise highlights export -f markdown -o highlights.md -readwise highlights export -f json -o highlights.json ``` ### Books ```bash -# List books -readwise books list --limit 20 - -# Show book details +readwise books list --limit 20 --category books readwise books show 123 ``` -### Reader +### Documents ```bash -# View inbox -readwise reader inbox --limit 50 +readwise documents inbox --limit 50 +readwise documents get abc123 --with-content +readwise documents save "https://example.com/article" +readwise documents update abc123 --title "New title" +readwise documents move abc123 archive +readwise documents tag abc123 to-review +readwise documents delete abc123 +readwise documents stats +``` -# Save a URL -readwise reader save "https://example.com/article" +`readwise reader ...` remains as a deprecated alias for `readwise documents ...` (`inbox`, `save`, `archive`, `stats`, plus every `documents` subcommand); it emits a stderr warning in table mode. -# Archive a document -readwise reader archive abc123 +### Tags -# Get reading stats -readwise reader stats +```bash +readwise tags list +readwise tags search python --limit 20 +readwise tags untagged --limit 20 +readwise tags auto-tag --pattern '\bpython\b' --tag python --dry-run +readwise tags rename old-name new-name --dry-run +readwise tags merge "tag-a,tag-b" --into merged-tag --dry-run +readwise tags delete old-tag --dry-run +readwise tags report ``` ### Digests ```bash -# Generate daily digest readwise digest daily -f markdown - -# Generate weekly digest readwise digest weekly -o weekly.md - -# Generate book digest readwise digest book 12345 -o book-notes.md +readwise digest custom --since 2024-01-01 --group-by-date ``` ### Sync ```bash -# Full sync -readwise sync full --output-dir ./data - -# Incremental sync +readwise --output json sync full readwise sync incremental --state-file sync.json +readwise sync status --state-file sync.json +readwise sync reset --state-file sync.json ``` ## MCP Server -`readwise-plus` ships an optional [MCP](https://modelcontextprotocol.io) server that exposes Readwise and Reader operations as tools for AI agents (Claude Code, Claude Desktop, or any MCP client). It's a thin layer over the SDK — install the `mcp` extra and register the `readwise-mcp` command. +`readwise-plus` ships an optional [MCP](https://modelcontextprotocol.io) server that exposes Readwise and Reader operations as tools for AI agents (Claude Code, Claude Desktop, or any MCP client). It's a thin layer over the same operations layer used by the SDK facade and CLI — install the `mcp` extra and register the `readwise-mcp` command. ### Register with Claude Code @@ -484,7 +351,7 @@ Contributions are welcome! Please follow these guidelines: 4. **Write tests** for new functionality 5. **Submit a pull request** with a clear description -See [AGENTS.md](AGENTS.md) for detailed development guidelines. +See [AGENTS.md](AGENTS.md) for detailed development guidelines and [docs/architecture.md](docs/architecture.md) for the layering contributors should preserve. ## License diff --git a/REFACTORING_DISCIPLINE.md b/REFACTORING_DISCIPLINE.md deleted file mode 100644 index f1ae49b..0000000 --- a/REFACTORING_DISCIPLINE.md +++ /dev/null @@ -1,21 +0,0 @@ -# Refactoring Discipline — Michael Feathers, *Working Effectively with Legacy Code* - -This restructure is a legacy-code exercise. Every stage MUST honor these rules. They override speed, cleverness, and convenience. A stage that cannot follow them is too big — split it. - -1. **Legacy code is code without tests.** No structural change ships without a test that would fail if behavior regressed. If code isn't covered, cover it *before* moving it. - -2. **Characterization tests pin ACTUAL behavior, not intended behavior.** They record what the code does *today* — quirks and bugs included. When a test captures surprising or wrong behavior, keep it and annotate `# characterizes current (buggy) behavior`. Do not "correct" it in the same breath. - -3. **Cover and Modify — never Edit and Pray.** Get code under test first, then change it. If it's untestable as written, introduce a *seam* (a place to substitute behavior without editing in place) and break the dependency minimally, rather than rewriting blind. - -4. **Refactoring preserves behavior — full stop.** Never change structure and behavior in the same commit. Move / rename / extract / re-layer are behavior-neutral. Bug fixes and feature changes are SEPARATE, clearly-labeled commits, each with a test that *demonstrates* the change. (Example: the `save_to_reader(category=…)` bug is fixed in its own commit, only after a characterization test locks the current — broken — payload.) - -5. **Small steps, always green.** Every step ends with `just fc` passing (format, lint, type, test). Prefer many tiny verifiable moves to one big leap. Never weaken the Justfile, delete/skip a test, or widen a `ty` exclusion to make a step "pass." - -6. **Preserve the public contract with shims, not by freezing internals.** Old imports and return values survive through re-exports and compatibility wrappers whose behavior is pinned by characterization tests. Internals may change freely; the observable surface may not — until 1.0. - -7. **The Legacy Change Algorithm**, applied to each move: identify change points → find test points → break dependencies (seams) → write tests → make the change → refactor. - -8. **When in doubt, add a test.** A refactor you can't cover is a refactor you shouldn't make yet. - -> Resource clients know endpoints. Operations know intent. Adapters know protocol. Tests know what must not change. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..5eabdac --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,29 @@ +# Architecture + +A short map of the `0.3` layering for contributors. Dependencies point downward only — nothing in a lower layer imports from a higher one. + +``` +Public models and errors + ↓ +Transport and pagination (readwise_sdk.transport) + ↓ +Low-level resource clients (readwise_sdk.resources.v2 / .v3) + ↓ +Operations / service core (readwise_sdk.operations, readwise_sdk.operations.service.ReadwiseService) + ↓ +SDK facade | CLI adapter | MCP adapter + (readwise_sdk.sdk) (readwise_sdk.cli) (readwise_sdk.mcp) +``` + +- **Resource clients** (`readwise_sdk.resources.v2`, `readwise_sdk.resources.v3`) know Readwise/Reader endpoints only: build requests, decode models, expose raw pagination. No filtering, formatting, or multi-request composition. +- **Operations** (`readwise_sdk.operations.*`, composed by `ReadwiseService`) own everything that used to be scattered across managers, workflows, contrib, the CLI, and the MCP server: search filtering, limits, bulk-operation semantics, digest data selection, sync checkpoints. Operations return typed result models (`DocumentSearchResult`, `HighlightSearchResult`, `BulkResult`, `SyncResult`, ...), never Rich objects or JSON strings. +- **Adapters** — the `Readwise`/`AsyncReadwise` facade (`readwise_sdk.sdk`), the CLI (`readwise_sdk.cli`), and the MCP server (`readwise_sdk.mcp`) — each call the same operations and own only their own protocol concerns: argument parsing, credential discovery, human/JSON rendering, exit codes or MCP error envelopes. +- **`readwise.raw.v2` / `readwise.raw.v3`** on the facade are an explicit low-level escape hatch onto the same resource clients used everywhere else — not a second implementation. + +## Compatibility layer + +`ReadwiseClient`/`AsyncReadwiseClient`, the `managers`, `workflows`, and `contrib` packages, and the `v2.models`/`v3.models` modules are compatibility wrappers: they delegate to the operations layer (often through a synchronous `run_sync` bridge) and translate results back into their original pre-0.3 return shapes. They are not a parallel implementation to keep in sync by hand. New behavior is added to the operations layer first; a compatibility method is added only if it needs to preserve an existing pre-0.3 signature. See [MIGRATION.md](../MIGRATION.md) for the full old→new mapping and removal timeline. + +## Sync vs. async + +The operations layer is async-first (MCP and network I/O are naturally async). `AsyncReadwise` uses it directly. `Readwise` runs the same async operations through a dedicated `anyio` blocking portal on its own event-loop thread (`readwise_sdk.sdk.sync`) rather than reimplementing each operation synchronously — so `Readwise` and `AsyncReadwise` cannot drift from each other by construction. The portal is owned and closed by the facade's context manager; using `Readwise` outside a `with` block raises rather than silently leaking a thread. diff --git a/llms-full.txt b/llms-full.txt index a19abee..46488f2 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,17 +1,17 @@ # readwise-plus -> Comprehensive Python SDK for Readwise with high-level workflow abstractions. Provides both low-level API access and high-level managers for common operations on highlights, books, and documents. +> Comprehensive Python SDK for Readwise. Wraps the Readwise API (v2, highlights/books/tags) and the Reader API (v3, documents) in type-safe Pydantic models, behind a concept-oriented facade, a CLI, and an MCP server. This SDK wraps the Readwise API (v2) and Reader API (v3) in type-safe Pydantic models with automatic pagination, rate limit handling, and error recovery. Built for Python 3.12+ using modern Python patterns. ## Architecture Overview -The SDK is organized in layers: +The SDK is organized in layers, dependencies pointing downward only: -1. **Core Layer** (`client.py`, `v2/`, `v3/`): Direct API access with Pydantic models -2. **Managers Layer** (`managers/`): High-level abstractions for common operations -3. **Workflows Layer** (`workflows/`): Task-oriented utilities for specific use cases -4. **Contrib Layer** (`contrib/`): Convenience interfaces for integration patterns +1. **Transport & resource clients** (`readwise_sdk.transport`, `readwise_sdk.resources.v2`/`.v3`): direct API access — build requests, decode Pydantic models, expose raw pagination. No filtering or formatting. +2. **Operations layer** (`readwise_sdk.operations`, composed by `ReadwiseService`): the single place that owns search filtering, limits, bulk semantics, digest selection, and sync checkpoints. Returns typed result models. Shared by every adapter below. +3. **Adapters**: the `Readwise`/`AsyncReadwise` SDK facade (`readwise_sdk.sdk`), the CLI (`readwise_sdk.cli`), and the MCP server (`readwise_sdk.mcp`) each call the operations layer and own only their own protocol concerns (argument parsing, rendering, error envelopes). +4. **Compatibility layer** (`readwise_sdk.managers`, `.workflows`, `.contrib`, `ReadwiseClient`/`AsyncReadwiseClient`, `.v2`/`.v3`): pre-0.3 classes, now thin wrappers that delegate to the operations layer and translate results back to their original return shapes. Fully supported, not scheduled for removal before `1.0`. See `MIGRATION.md`. ## Installation @@ -24,33 +24,196 @@ With CLI support: pip install readwise-plus[cli] ``` +As an MCP server: +```bash +pip install readwise-plus[mcp] +``` + ## Quick Start ```python -from readwise_sdk import ReadwiseClient +from readwise_sdk import Readwise +from readwise_sdk.models import DocumentSearch + +with Readwise() as readwise: # reads READWISE_API_KEY from the environment + result = readwise.documents.search(DocumentSearch(query="python", limit=20)) + for doc in result.items: + print(doc.title) +``` -# Initialize with API token -client = ReadwiseClient(api_key="your_token_here") +Async: -# Or use READWISE_API_KEY environment variable -client = ReadwiseClient() +```python +from readwise_sdk import AsyncReadwise +from readwise_sdk.models import DocumentSearch + +async with AsyncReadwise() as readwise: + result = await readwise.documents.search(DocumentSearch(query="python", limit=20)) +``` -# Validate token -assert client.validate_token() +The pre-0.3 client keeps working unchanged: + +```python +from readwise_sdk import ReadwiseClient -# Context manager support with ReadwiseClient() as client: highlights = list(client.v2.list_highlights()) ``` --- +## Preferred API: `Readwise` / `AsyncReadwise` + +The concept-oriented facade. `AsyncReadwise` uses the operations layer directly; `Readwise` runs the same operations through a dedicated `anyio` blocking portal, so both expose identical methods (the sync ones are plain, non-`await`-prefixed mirrors). Use either as a context manager — it owns and closes the underlying transport (and, for `Readwise`, the portal thread). + +```python +from readwise_sdk import Readwise +from readwise_sdk.config import DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF, DEFAULT_TIMEOUT + +readwise = Readwise( + api_key="your_token", # optional if READWISE_API_KEY is set + timeout=DEFAULT_TIMEOUT, # 30.0 + max_retries=DEFAULT_MAX_RETRIES, # 3 + retry_backoff=DEFAULT_RETRY_BACKOFF, # 0.5 +) +with readwise: + ... +``` + +### `.documents` — Reader (v3) + +```python +from readwise_sdk.models import DocumentSearch +from readwise_sdk.models.reader import DocumentCreate, DocumentUpdate +from readwise_sdk.v3.models import DocumentLocation + +with Readwise() as readwise: + result = readwise.documents.search( + DocumentSearch(location=DocumentLocation.LATER, query="python", limit=20) + ) + for summary in result.items: # bounded DocumentSummary projections + print(summary.title, summary.url) + + doc = readwise.documents.get(result.items[0].id, with_content=True) + created = readwise.documents.save(DocumentCreate(url="https://example.com/article")) + readwise.documents.update(created.id, DocumentUpdate(title="New title")) + readwise.documents.move(created.id, DocumentLocation.ARCHIVE) + readwise.documents.add_tag(created.id, "to-review") + readwise.documents.remove_tag(created.id, "to-review") + + inbox = readwise.documents.inbox(limit=20) + later = readwise.documents.later(limit=20) + archived = readwise.documents.archive(limit=20) + stats = readwise.documents.statistics() + print(stats.inbox_count, stats.reading_list_count, stats.by_category) + + bulk = readwise.documents.bulk_move([created.id], DocumentLocation.ARCHIVE) + print(bulk.succeeded, bulk.failures) +``` + +### `.highlights` — Readwise (v2) + +```python +from readwise_sdk.models import HighlightSearch +from readwise_sdk.models.readwise import HighlightUpdate + +with Readwise() as readwise: + result = readwise.highlights.search(HighlightSearch(query="python", limit=50)) + for summary in result.items: # HighlightSummary + print(summary.text) + + highlight = readwise.highlights.get(result.items[0].id) + created = readwise.highlights.create_from_fields( + text="Important quote", title="Book Title", author="Author Name" + ) + readwise.highlights.update(highlight.id, HighlightUpdate(note="revised")) + readwise.highlights.delete(highlight.id) + + recent = readwise.highlights.since(days=7) + with_notes = readwise.highlights.with_notes() + count = readwise.highlights.count() + + bulk = readwise.highlights.bulk_tag([1, 2, 3], "to-review") + export = readwise.highlights.export(limit=20) +``` + +### `.books` — Readwise (v2) + +```python +from readwise_sdk.models import BookSearch +from readwise_sdk.models.readwise import BookCategory + +with Readwise() as readwise: + result = readwise.books.search(BookSearch(category=BookCategory.BOOKS, query="python")) + book_id = result.items[0].id + + with_highlights = readwise.books.with_highlights(book_id) + print(with_highlights.book.title, len(with_highlights.highlights)) + + recent = readwise.books.recent(days=30, limit=10) + stats = readwise.books.statistics() + print(stats.total_books, stats.total_highlights) +``` + +### `.tags` + +```python +from readwise_sdk.operations import TagPattern + +with Readwise() as readwise: + report = readwise.tags.get_tag_report() + print(report.total_tags, report.total_usages, report.duplicate_candidates) + + patterns = [TagPattern(r"\bpython\b", "python", case_sensitive=False)] + tagged = readwise.tags.auto_tag_highlights(patterns, dry_run=True) # dict[int, list[str]] + + readwise.tags.rename_tag("old-name", "new-name", dry_run=True) + readwise.tags.merge_tags(["tag-a", "tag-b"], "merged-tag", dry_run=True) + readwise.tags.delete_tag("stale-tag", dry_run=True) +``` + +### `.digests` + +```python +with Readwise() as readwise: + daily = readwise.digests.daily() + weekly = readwise.digests.weekly(group_by_book=False) + book_digest = readwise.digests.book(book_id=123) + custom = readwise.digests.custom(group_by_date=True) +``` + +Digest data (`DigestData`) is presentation-agnostic; render it with `readwise_sdk.presenters.render_digest(data, DigestFormat.MARKDOWN)` (formats: `MARKDOWN`, `JSON`, `CSV`, `TEXT`). + +### `.sync` + +```python +with Readwise() as readwise: + result = readwise.sync.full() # SyncResult + result = readwise.sync.incremental() + result = readwise.sync.poll_once() + outcome = readwise.sync.batch_highlights(on_item=lambda h: print(h.text)) + checkpoint = readwise.sync.status() # SyncCheckpoint + readwise.sync.reset() +``` + +### `.raw` — low-level escape hatch + +```python +with Readwise() as readwise: + readwise.raw.v2 # ReadwiseV2Client — same object as ReadwiseClient(...).v2 + readwise.raw.v3 # ReadwiseV3Client — same object as ReadwiseClient(...).v3 +``` + +--- + +## Compatibility API (`ReadwiseClient` / `AsyncReadwiseClient`) + +Unchanged since before `0.3`. All classes and methods below still work — see `MIGRATION.md` for the mapping onto the preferred facade above and the deprecation timeline. + ## Core Client ### ReadwiseClient -The main entry point for all SDK operations. - ```python from readwise_sdk import ReadwiseClient @@ -60,16 +223,11 @@ client = ReadwiseClient( max_retries=3, # Number of retries on failure ) -# Access V2 API (Readwise) -client.v2 # Returns V2Client - -# Access V3 API (Reader) -client.v3 # Returns V3Client +client.v2 # Returns ReadwiseV2Client +client.v3 # Returns ReadwiseV3Client -# Validate token is_valid = client.validate_token() # Returns bool -# Context manager with client: # client is automatically closed on exit pass @@ -203,11 +361,11 @@ book = client.v2.get_book(book_id=123) # Tag operations tags = client.v2.list_highlight_tags(highlight_id=123) -client.v2.create_highlight_tag(highlight_id=123, tag_name="important") +client.v2.create_highlight_tag(highlight_id=123, name="important") client.v2.delete_highlight_tag(highlight_id=123, tag_id=456) tags = client.v2.list_book_tags(book_id=123) -client.v2.create_book_tag(book_id=123, tag_name="favorites") +client.v2.create_book_tag(book_id=123, name="favorites") # Export highlights (includes full book data) for export_book in client.v2.export_highlights( @@ -331,7 +489,7 @@ client.v3.move_to_inbox(document_id="uuid") # Back to inbox # Tag operations tags = list(client.v3.list_tags()) -client.v3.tag_document(document_id="uuid", tag="important") +client.v3.tag_document(document_id="uuid", tags=["important"]) # Convenience methods inbox = list(client.v3.get_inbox()) @@ -359,8 +517,8 @@ all_highlights = manager.get_all_highlights() # Get highlights for a specific book book_highlights = manager.get_highlights_by_book(book_id=123) -# Get recent highlights -recent = manager.get_recent_highlights(days=7) +# Get highlights from the last N days (or hours, or since a datetime) +recent = manager.get_highlights_since(days=7) # Get highlights with notes with_notes = manager.get_highlights_with_notes() @@ -371,16 +529,15 @@ results = manager.search_highlights("machine learning") # Bulk tag operation manager.bulk_tag( highlight_ids=[1, 2, 3], - tag_name="to-review", + tag="to-review", ) -# Create new highlight +# Create new highlight (returns the new highlight ID) highlight_id = manager.create_highlight( text="Important quote", title="Book Title", author="Author", note="My thoughts", - category=BookCategory.BOOKS, ) # Get total count @@ -393,6 +550,7 @@ High-level book operations. ```python from readwise_sdk import ReadwiseClient, BookManager +from readwise_sdk.managers.books import BookCategory client = ReadwiseClient() manager = BookManager(client) @@ -404,7 +562,8 @@ all_books = manager.get_all_books() articles = manager.get_books_by_category(BookCategory.ARTICLES) # Get book with all highlights -book, highlights = manager.get_book_with_highlights(book_id=123) +result = manager.get_book_with_highlights(book_id=123) +print(result.book.title, len(result.highlights)) # Get recently updated books recent = manager.get_recent_books(days=30, limit=10) @@ -417,7 +576,7 @@ stats = manager.get_reading_stats() print(f"Total books: {stats.total_books}") print(f"Total highlights: {stats.total_highlights}") print(f"By category: {stats.books_by_category}") -print(f"Top book: {stats.top_book_by_highlights}") +print(f"Most highlighted: {stats.most_highlighted_books}") # list[(title, count)] ``` ### DocumentManager @@ -426,6 +585,7 @@ High-level Reader document operations. ```python from readwise_sdk import ReadwiseClient, DocumentManager +from readwise_sdk.managers.documents import DocumentCategory client = ReadwiseClient() manager = DocumentManager(client) @@ -439,7 +599,7 @@ archive = manager.get_archive() articles = manager.get_documents_by_category(DocumentCategory.ARTICLE) # Move operations -manager.move_to_reading_list(document_id="uuid") +manager.move_to_later(document_id="uuid") manager.bulk_archive(document_ids=["uuid1", "uuid2", "uuid3"]) # Search documents @@ -484,9 +644,9 @@ result = manager.incremental_sync( ) # Check sync state -print(f"Last sync: {manager.state.last_sync}") +print(f"Last sync: {manager.state.last_sync_time}") print(f"Total syncs: {manager.state.total_syncs}") -print(f"Total highlights synced: {manager.state.total_highlights}") +print(f"Last highlight sync: {manager.state.last_highlight_sync}") # Reset state (next sync will be full) manager.reset_state() @@ -527,7 +687,7 @@ Inbox management and smart archiving. ```python from readwise_sdk import ReadwiseClient -from readwise_sdk.workflows.inbox import ReadingInbox, ArchiveRules +from readwise_sdk.workflows.inbox import ArchiveRule, ReadingInbox client = ReadwiseClient() inbox = ReadingInbox(client) @@ -547,20 +707,13 @@ prioritized = inbox.get_inbox_by_priority() # Search inbox results = inbox.search_inbox("machine learning") -# Smart archive with rules -rules = [ - ArchiveRules.create_old_item_rule(days=90), - ArchiveRules.create_category_rule(DocumentCategory.TWEET), - ArchiveRules.create_domain_rule("twitter.com"), - ArchiveRules.create_title_pattern_rule(r"^Weekly\s"), -] - -# Dry run first -dry_run_result = inbox.smart_archive(rules, dry_run=True) -print(f"Would archive: {len(dry_run_result.archived_ids)} items") - -# Execute -result = inbox.smart_archive(rules, dry_run=False) +# Register an archive rule, then run it (dry run first) +inbox.add_archive_rule( + ArchiveRule(name="old-items", condition=lambda doc: doc.word_count is not None and doc.word_count < 200) +) +dry_run_actions = inbox.smart_archive(dry_run=True) # list[TriageAction] +print(f"Would archive: {len(dry_run_actions)} items") +actions = inbox.smart_archive(dry_run=False) # Move to reading list inbox.move_to_reading_list(document_ids=["uuid1", "uuid2"]) @@ -568,45 +721,34 @@ inbox.move_to_reading_list(document_ids=["uuid1", "uuid2"]) ### BackgroundPoller -Background polling for new content. +Background polling for new content, with error backoff. ```python from readwise_sdk import ReadwiseClient -from readwise_sdk.workflows.poller import BackgroundPoller +from readwise_sdk.workflows.poller import BackgroundPoller, PollerConfig client = ReadwiseClient() poller = BackgroundPoller( client, - state_file="poller_state.json", - poll_highlights=True, - poll_books=True, - poll_documents=True, + config=PollerConfig( + state_file="poller_state.json", + poll_interval=300, # seconds + include_highlights=True, + include_documents=True, + ), ) -# Register callbacks -@poller.on_new_highlight -def handle_highlight(highlight): - print(f"New highlight: {highlight.text[:50]}") - -@poller.on_new_book -def handle_book(book): - print(f"New book: {book.title}") - -@poller.on_new_document -def handle_document(doc): - print(f"New document: {doc.title}") - -@poller.on_error -def handle_error(error): - print(f"Error: {error}") +# Register callbacks — receive the full SyncResult / the raised exception +poller.on_sync(lambda result: print(f"Synced {len(result.highlights)} highlights")) +poller.on_error(lambda error: print(f"Error: {error}")) # Poll once manually poller.poll_once() -# Start background polling (runs in separate thread) -poller.start(interval_seconds=300) # Every 5 minutes +# Start background polling (runs in a separate thread; poll_interval from config) +poller.start() -# Check if running +# Check if running (property, not a method call) print(f"Is running: {poller.is_running}") # Stop polling @@ -619,21 +761,21 @@ Tag management and auto-tagging. ```python from readwise_sdk import ReadwiseClient -from readwise_sdk.workflows.tags import TagWorkflow, TagPattern +from readwise_sdk.workflows.tags import TagPattern, TagWorkflow client = ReadwiseClient() workflow = TagWorkflow(client) -# Auto-tag based on patterns +# Auto-tag based on patterns: TagPattern(pattern, tag, case_sensitive=, match_in_notes=, match_in_text=) patterns = [ - TagPattern(pattern=r"\bmachine learning\b", tag_name="ml"), - TagPattern(pattern=r"\bpython\b", tag_name="python", case_sensitive=False), - TagPattern(pattern=r"TODO:", tag_name="actionable", search_in_notes=True), + TagPattern(r"\bmachine learning\b", "ml"), + TagPattern(r"\bpython\b", "python", case_sensitive=False), + TagPattern(r"TODO:", "actionable", match_in_notes=True), ] -# Dry run +# Dry run — returns dict[highlight_id, list[tags_that_would_be_applied]] result = workflow.auto_tag_highlights(patterns, dry_run=True) -print(f"Would tag {len(result.tagged_highlights)} highlights") +print(f"Would tag {len(result)} highlights") # Execute result = workflow.auto_tag_highlights(patterns, dry_run=False) @@ -762,7 +904,7 @@ archive = importer.list_archive(limit=10) since = datetime.now() - timedelta(days=7) updated = importer.list_updated_since(since, limit=50) -# Save URL to Reader +# Save URL to Reader (returns the new document ID) doc_id = importer.save_url("https://example.com/article") ``` @@ -804,8 +946,8 @@ print(f"Failed: {result.failed_items}") # Sync books result = sync.sync_books(full_sync=False) -# Sync both -highlight_result, book_result = sync.sync_all( +# Sync all three (returns a 3-tuple) +highlight_result, book_result, document_result = sync.sync_all( on_highlight=on_highlight, full_sync=False, ) @@ -854,12 +996,31 @@ except ReadwiseError as e: --- +## CLI + +```bash +readwise [--output table|json|jsonl] [--no-color] [--quiet] +``` + +Groups: `highlights` (list/show/create/update/delete/tag/untag/export), `books` (list/show), `documents` (inbox/save/archive/stats/get/update/delete/move/tag — alias `reader`), `tags` (list/search/untagged/auto-tag/rename/merge/delete/report), `digest` (daily/weekly/book/custom), `sync` (full/incremental/status/reset), `version`. `--output` is a root option and must precede the group, e.g. `readwise --output json sync full`. + +## MCP Server + +Install the `mcp` extra and run `readwise-mcp` (console script) or `python -m readwise_sdk.mcp`. Nine tools, all backed by the same operations layer as the SDK facade and CLI: + +- Documents (Reader v3): `save_to_reader`, `search_documents`, `get_document`, `update_document`, `delete_document` +- Highlights (Readwise v2): `get_highlights`, `export_highlights`, `create_highlight` +- Books (Readwise v2): `get_books` + +Auth via `READWISE_API_KEY` (environment variable, or a `READWISE_API_KEY=` line in `~/.env`). + ## Environment Variables -- `READWISE_API_KEY`: Default API token (used if not provided to client) +- `READWISE_API_KEY`: Default API token (used if not provided to `Readwise`/`AsyncReadwise`/`ReadwiseClient`) ## Links - GitHub: https://github.com/EvanOman/readwise-plus +- Migration guide (old → new API, deprecation timeline): https://github.com/EvanOman/readwise-plus/blob/main/MIGRATION.md - Readwise API: https://readwise.io/api_deets - Reader API: https://readwise.io/reader_api diff --git a/llms.txt b/llms.txt index d6e77cc..4b5f8fa 100644 --- a/llms.txt +++ b/llms.txt @@ -1,232 +1,93 @@ # readwise-plus -> Comprehensive Python SDK for Readwise with high-level workflow abstractions. Provides both low-level API access and high-level managers for common operations on highlights, books, and documents. +> Comprehensive Python SDK for Readwise. Wraps the Readwise API (v2, highlights/books) and the Reader API (v3, documents) behind one concept-oriented interface, plus a CLI and an MCP server. Built for Python 3.12+. -This SDK wraps the Readwise API (v2) and Reader API (v3) in type-safe Pydantic models with automatic pagination, rate limit handling, and error recovery. Built for Python 3.12+. +The preferred entry points are `Readwise` (sync) and `AsyncReadwise` (async): concept-oriented facades with `.documents`, `.highlights`, `.books`, `.tags`, `.digests`, `.sync`, and a `.raw.v2`/`.raw.v3` escape hatch for the low-level clients. The CLI and MCP server call the same underlying operations layer, so behavior is consistent everywhere. The pre-0.3 `ReadwiseClient`/`.v2`/`.v3`/managers/workflows/contrib API still works unchanged as a compatibility surface — see MIGRATION.md for the mapping and deprecation timeline. ## Core Concepts -- **ReadwiseClient**: Main entry point that provides access to both v2 and v3 API clients -- **V2 API**: Readwise API for highlights, books, tags, exports, and daily review -- **V3 API**: Reader API for documents, reading list management, and document tagging -- **Managers**: High-level abstractions for common workflows (HighlightManager, BookManager, etc.) -- **Workflows**: Task-oriented utilities for digests, inbox management, background polling, and tag operations -- **Contrib**: Convenience interfaces designed for specific integration patterns +- **Readwise / AsyncReadwise**: preferred SDK facades; concept-oriented attributes over one shared operations layer +- **Operations layer**: `documents`, `highlights`, `books`, `tags`, `digests`, `sync` — async-first, shared by the facade, CLI, and MCP server +- **Raw escape hatch**: `.raw.v2` / `.raw.v3` for direct low-level API access +- **Compatibility API**: `ReadwiseClient`/`AsyncReadwiseClient`, managers, workflows, contrib — unchanged pre-0.3 surfaces, not scheduled for removal before 1.0 ## Quick Start ```python -from readwise_sdk import ReadwiseClient +from readwise_sdk import Readwise +from readwise_sdk.models import DocumentSearch -# Initialize with API token (or use READWISE_API_KEY env var) -client = ReadwiseClient(api_key="your_token") +with Readwise() as readwise: # reads READWISE_API_KEY from the environment + result = readwise.documents.search(DocumentSearch(query="python", limit=20)) + for doc in result.items: + print(doc.title) -# V2 API - Highlights and books -for highlight in client.v2.list_highlights(): - print(highlight.text) +# Async +from readwise_sdk import AsyncReadwise -# V3 API - Reader documents -for doc in client.v3.get_inbox(): - print(doc.title) - -# High-level managers -from readwise_sdk import HighlightManager -manager = HighlightManager(client) -recent = manager.get_recent_highlights(days=7) +async with AsyncReadwise() as readwise: + result = await readwise.documents.search(DocumentSearch(query="python")) ``` ## API Reference -### Client - -- ReadwiseClient: Main client class with `v2` and `v3` properties for API access -- AsyncReadwiseClient: Async version of the client - -### V2 API (Readwise) - -Models: -- Highlight: A highlight with text, notes, location, tags, and metadata -- Book: A source (book, article, tweet, podcast) containing highlights -- Tag: A tag attached to highlights or books -- BookCategory: Enum for source categories (books, articles, tweets, podcasts, supplementals) -- HighlightColor: Enum for highlight colors (yellow, blue, pink, orange, green, purple) -- DailyReview: Container for daily review highlights -- HighlightCreate: Data for creating new highlights -- HighlightUpdate: Data for updating existing highlights - -Methods (client.v2.*): -- list_highlights(updated_after, book_id, page_size): Iterate all highlights -- get_highlight(highlight_id): Get single highlight by ID -- create_highlights(highlights): Create multiple highlights -- update_highlight(highlight_id, update): Update a highlight -- delete_highlight(highlight_id): Delete a highlight -- list_books(category, updated_after, page_size): Iterate all books -- get_book(book_id): Get single book by ID -- list_highlight_tags(highlight_id): Get tags for a highlight -- create_highlight_tag(highlight_id, tag_name): Add tag to highlight -- delete_highlight_tag(highlight_id, tag_id): Remove tag from highlight -- list_book_tags(book_id): Get tags for a book -- create_book_tag(book_id, tag_name): Add tag to book -- export_highlights(updated_after, ids): Export highlights with full book data -- get_daily_review(): Get today's daily review highlights - -### V3 API (Reader) - -Models: -- Document: A Reader document with content, location, tags, and reading progress -- DocumentTag: A tag on a Reader document -- DocumentCategory: Enum (article, email, rss, highlight, note, pdf, epub, tweet, video) -- DocumentLocation: Enum (new, later, shortlist, archive, feed) -- DocumentCreate: Data for creating documents -- DocumentUpdate: Data for updating documents -- CreateDocumentResult: Result of document creation with ID and URL - -Methods (client.v3.*): -- list_documents(location, category, updated_after, with_content): Iterate documents -- get_document(document_id, with_content): Get single document -- create_document(document): Create new document -- save_url(url, location, tags, notes, author, title): Quick URL save -- update_document(document_id, update): Update document -- delete_document(document_id): Delete document -- move_to_later(document_id): Move to reading list -- archive(document_id): Archive document -- move_to_inbox(document_id): Move back to inbox -- list_tags(): List all document tags -- tag_document(document_id, tag): Add tag to document -- add_tag(document_id, tag): Alias for tag_document -- get_inbox(): Get inbox documents -- get_reading_list(): Get reading list documents -- get_archive(): Get archived documents - -### Managers - -HighlightManager: -- get_all_highlights(): Get all highlights -- get_highlights_by_book(book_id): Get highlights for a specific book -- get_recent_highlights(days): Get highlights from last N days -- get_highlights_with_notes(): Get highlights that have notes -- search_highlights(query): Search highlight text -- bulk_tag(highlight_ids, tag_name): Add tag to multiple highlights -- create_highlight(text, title, author, source_url, note, category): Create new highlight -- get_highlight_count(): Get total highlight count - -BookManager: -- get_all_books(): Get all books -- get_books_by_category(category): Filter by category -- get_book_with_highlights(book_id): Get book with all its highlights -- get_recent_books(days, limit): Get recently updated books -- search_books(query): Search book titles and authors -- get_reading_stats(): Get aggregate statistics - -DocumentManager: -- get_inbox(): Get inbox documents -- get_reading_list(): Get reading list documents -- get_archive(): Get archived documents -- get_documents_by_category(category): Filter by category -- move_to_reading_list(document_id): Move to reading list -- bulk_archive(document_ids): Archive multiple documents -- search_documents(query): Search document titles -- get_unread_count(): Get count of unread documents -- get_inbox_stats(): Get inbox statistics - -SyncManager: -- full_sync(include_highlights, include_books, include_documents): Full data sync -- incremental_sync(...): Sync only changes since last sync -- reset_state(): Reset sync state for fresh start -- state: SyncState property with sync timestamps and totals - -### Workflows - -DigestBuilder: -- create_daily_digest(output_format): Create digest of today's highlights -- create_weekly_digest(output_format): Create digest of week's highlights -- create_book_digest(book_id, output_format): Create digest for specific book -- DigestFormat: Enum (MARKDOWN, JSON, CSV) - -ReadingInbox: -- get_queue_stats(): Get inbox statistics -- get_stale_items(days): Get items older than N days -- get_inbox_by_priority(): Get prioritized inbox -- search_inbox(query): Search inbox -- smart_archive(rules, dry_run): Archive by rules -- move_to_reading_list(document_ids): Move items to reading list -- add_archive_rule(rule): Add archiving rule -- ArchiveRules.create_old_item_rule(days): Create age-based rule -- ArchiveRules.create_category_rule(category): Create category-based rule -- ArchiveRules.create_title_pattern_rule(pattern): Create pattern-based rule -- ArchiveRules.create_domain_rule(domain): Create domain-based rule - -BackgroundPoller: -- poll_once(): Manually trigger one poll cycle -- start(interval_seconds): Start background polling -- stop(): Stop polling -- on_new_highlight(callback): Register highlight callback -- on_new_book(callback): Register book callback -- on_new_document(callback): Register document callback -- on_error(callback): Register error callback - -TagWorkflow: -- auto_tag_highlights(patterns, dry_run): Auto-tag based on patterns -- get_tag_report(): Get tag usage statistics -- get_highlights_by_tag(tag_name): Get highlights with specific tag -- get_untagged_highlights(): Get highlights without tags -- merge_tags(source_tags, target_tag, dry_run): Merge tags -- rename_tag(old_name, new_name, dry_run): Rename tag -- delete_tag(tag_name, dry_run): Delete tag -- TagPattern(pattern, tag_name, search_in_notes): Pattern for auto-tagging - -### Contrib Interfaces - -HighlightPusher (for pushing highlights TO Readwise): -- push(text, title, author, note, category, ...): Push single highlight -- push_highlight(highlight): Push SimpleHighlight object -- push_batch(highlights): Push multiple highlights -- validate_token(): Validate API token -- SimpleHighlight: Dataclass for highlight data -- PushResult: Result with success status and IDs - -DocumentImporter (for pulling documents FROM Reader): -- import_document(document_id, with_content): Import single document -- import_batch(document_ids, with_content): Import multiple documents -- list_inbox(limit, with_content): List inbox with metadata extraction -- list_reading_list(limit, with_content): List reading list -- list_archive(limit, with_content): List archive -- list_updated_since(since, limit, with_content): List by update time -- save_url(url, **kwargs): Save URL to Reader -- ImportedDocument: Document with extracted metadata (domain, word_count, reading_time) -- ImportResult: Result with success status and document - -BatchSync (for efficient synchronization with state tracking): -- sync_highlights(on_item, on_batch, full_sync): Sync highlights with callbacks -- sync_books(on_item, on_batch, full_sync): Sync books with callbacks -- sync_all(on_highlight, on_book, full_sync): Sync both -- reset_state(): Reset sync state -- get_stats(): Get sync statistics -- state: SyncState property -- BatchSyncConfig: Configuration (batch_size, state_file, continue_on_error) -- BatchSyncResult: Result with counts and errors +### Facade (`Readwise` / `AsyncReadwise`) + +- `.documents.search(DocumentSearch)`, `.get(id, with_content=)`, `.save(DocumentCreate)`, `.update(id, DocumentUpdate)`, `.delete(id)`, `.move(id, location)`, `.set_tags`/`.add_tag`/`.remove_tag`, `.inbox()`/`.later()`/`.archive()`, `.statistics()`, `.bulk_move`, `.bulk_set_tags` +- `.highlights.search(HighlightSearch)`, `.list(...)`, `.get(id)`, `.create(HighlightCreate)`, `.create_from_fields(...)`, `.update(id, HighlightUpdate)`, `.delete(id)`, `.search_items(query)`, `.since(days=)`, `.with_notes()`, `.bulk_tag`/`.bulk_untag`, `.export(...)`, `.push_batch(...)`, `.update_batch(...)`, `.delete_batch(...)` +- `.books.search(BookSearch)`, `.list(...)`, `.get(id)`, `.with_highlights(id)`, `.recent(...)`, `.statistics()`, `.search_items(query)` +- `.tags.auto_tag_highlights(patterns)`, `.get_tag_report()`, `.merge_tags`, `.rename_tag`, `.delete_tag`, `.get_highlights_by_tag`, `.get_untagged_highlights` +- `.digests.daily()`, `.weekly()`, `.book(id)`, `.custom(...)` +- `.sync.full(...)`, `.incremental(...)`, `.poll_once(...)`, `.batch_highlights/.batch_books/.batch_documents(...)`, `.status()`, `.reset()` +- `.raw.v2`, `.raw.v3`: the same low-level clients described under Compatibility API below + +Models: import search inputs from `readwise_sdk.models` (`DocumentSearch`, `HighlightSearch`, `BookSearch`); import result/domain types from `readwise_sdk.models.reader` (`Document`, `DocumentCreate`, `DocumentUpdate`, `DocumentCategory`, `DocumentLocation`) and `readwise_sdk.models.readwise` (`Highlight`, `HighlightCreate`, `HighlightUpdate`, `Book`, `BookCategory`, `HighlightColor`, `Tag`). + +### Compatibility API + +`ReadwiseClient`/`AsyncReadwiseClient` (`from readwise_sdk import ReadwiseClient`): + +- `client.v2.list_highlights(updated_after, book_id, page_size)`, `.get_highlight(id)`, `.create_highlights(highlights)`, `.update_highlight(id, update)`, `.delete_highlight(id)`, `.list_books(...)`, `.get_book(id)`, `.export_highlights(...)`, `.get_daily_review()` +- `client.v3.list_documents(location, category, updated_after, with_content)`, `.get_document(id, with_content)`, `.create_document(...)`, `.save_url(url, ...)`, `.update_document(id, update)`, `.delete_document(id)`, `.move_to_later/.archive/.move_to_inbox(id)`, `.get_inbox/.get_reading_list/.get_archive()` + +Managers (`from readwise_sdk.managers import ...`): `HighlightManager` (`get_highlights_since`, `get_highlights_by_book`, `search_highlights`, `bulk_tag`), `BookManager` (`get_books_by_category`, `get_book_with_highlights`, `get_reading_stats`), `DocumentManager` (`get_inbox`, `archive`, `get_inbox_stats`), `SyncManager` (`full_sync`, `incremental_sync`). + +Workflows (`from readwise_sdk.workflows import ...`): `DigestBuilder` (`create_daily_digest`, `create_weekly_digest`, `create_book_digest`, `create_custom_digest`), `TagWorkflow` (`auto_tag_highlights` with `TagPattern(pattern, tag, case_sensitive=, match_in_notes=, match_in_text=)`, `merge_tags`, `rename_tag`), `ReadingInbox` (`get_queue_stats`, `smart_archive`, `get_inbox_by_priority`), `BackgroundPoller` (`poll_once`, `start`, `stop`). + +Contrib (`from readwise_sdk.contrib import ...`): `HighlightPusher` (`push`, `push_batch`), `DocumentImporter` (`import_document`, `save_url`), `BatchSync` (`sync_highlights`, `sync_books`, `sync_all`). ## Exceptions -- ReadwiseError: Base exception for all SDK errors -- AuthenticationError: Invalid API token (HTTP 401) -- RateLimitError: Rate limit exceeded (HTTP 429), includes retry_after -- NotFoundError: Resource not found (HTTP 404) -- ValidationError: Invalid request data (HTTP 400) -- ServerError: Server error (HTTP 5xx) +- `ReadwiseError`: base exception for all SDK errors +- `AuthenticationError`: invalid API token (HTTP 401) +- `RateLimitError`: rate limit exceeded (HTTP 429), includes `retry_after` +- `NotFoundError`: resource not found (HTTP 404) +- `ValidationError`: invalid request data (HTTP 400) +- `ServerError`: server error (HTTP 5xx) + +## CLI + +`readwise [--output table|json|jsonl] [--no-color] [--quiet] ` with groups `highlights`, `books`, `documents` (alias `reader`), `tags`, `digest`, `sync`, plus `version`. + +## MCP Server + +Install the `mcp` extra and run `readwise-mcp` (or `python -m readwise_sdk.mcp`). Nine tools: `save_to_reader`, `search_documents`, `get_document`, `update_document`, `delete_document`, `get_highlights`, `export_highlights`, `create_highlight`, `get_books`. Auth via `READWISE_API_KEY` (env var or `~/.env`). ## Installation ```bash -pip install readwise-plus +pip install readwise-plus # core +pip install readwise-plus[cli] # + CLI +pip install readwise-plus[mcp] # + MCP server ``` ## Environment Variables -- READWISE_API_KEY: Default API token if not provided to client +- `READWISE_API_KEY`: default API token if not provided to `Readwise`/`AsyncReadwise`/`ReadwiseClient` ## Links - [GitHub Repository](https://github.com/EvanOman/readwise-plus) +- [MIGRATION.md](https://github.com/EvanOman/readwise-plus/blob/main/MIGRATION.md) — old→new API mapping and deprecation timeline - [Readwise API Documentation](https://readwise.io/api_deets) - [Reader API Documentation](https://readwise.io/reader_api) From 32eb337ff1b4f8b3d4cb2394ff83e5010d48ca7c Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Wed, 15 Jul 2026 00:16:23 -0500 Subject: [PATCH 23/24] fix(mcp): include category in save_to_reader payload MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit save_to_reader accepted a `category` argument but never forwarded it — the MCP tool didn't parse it, and the document save operation deliberately stripped it to preserve the pre-refactor bug. Now the tool validates category (returning an "Invalid category" envelope on bad input) and passes it through; the save operation forwards it unchanged. This is a deliberate, isolated behavior change: the three tests that pinned the dropped-category behavior are flipped to assert the fix (plus a new invalid-category rejection test). Gate green (837 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- src/readwise_sdk/mcp/server.py | 8 ++++++++ src/readwise_sdk/operations/documents.py | 7 ++----- tests/characterization/test_mcp_contracts.py | 20 +++++++++++++++++--- tests/operations/test_documents.py | 7 +++---- tests/operations/test_documents_transport.py | 5 +++-- 5 files changed, 33 insertions(+), 14 deletions(-) diff --git a/src/readwise_sdk/mcp/server.py b/src/readwise_sdk/mcp/server.py index 86cfb2c..a99493a 100644 --- a/src/readwise_sdk/mcp/server.py +++ b/src/readwise_sdk/mcp/server.py @@ -161,6 +161,13 @@ async def save_to_reader( except ValueError: return _error_result(f"Invalid location '{location}'. Use: new, later, archive, feed.") + doc_category = None + if category: + try: + doc_category = DocumentCategory(category) + except ValueError: + return _error_result(f"Invalid category '{category}'.") + doc = DocumentCreate( url=url, title=title, @@ -169,6 +176,7 @@ async def save_to_reader( html=html, tags=tags, notes=notes, + category=doc_category, location=doc_location, saved_using="readwise-mcp", ) diff --git a/src/readwise_sdk/operations/documents.py b/src/readwise_sdk/operations/documents.py index 7e54bb5..64daac2 100644 --- a/src/readwise_sdk/operations/documents.py +++ b/src/readwise_sdk/operations/documents.py @@ -116,11 +116,8 @@ async def get(self, document_id: str, *, with_content: bool = False) -> Document return await self._resource.get(document_id, with_content=with_content) async def save(self, document: DocumentCreate) -> CreateDocumentResult: - """Save a document while preserving the current dropped-category bug.""" - # Characterizes current (buggy) save_to_reader behavior. A later stage - # deliberately restores category after the operation contract is established. - without_category = document.model_copy(update={"category": None}) - return await self._resource.create(without_category) + """Save a document (including its category) to Reader.""" + return await self._resource.create(document) async def update( self, diff --git a/tests/characterization/test_mcp_contracts.py b/tests/characterization/test_mcp_contracts.py index fff4f92..62ebe0b 100644 --- a/tests/characterization/test_mcp_contracts.py +++ b/tests/characterization/test_mcp_contracts.py @@ -49,8 +49,8 @@ async def test_save_to_reader_returns_exact_compact_json() -> None: @respx.mock @pytest.mark.asyncio -async def test_save_to_reader_category_is_currently_dropped_from_payload() -> None: - """The accepted category argument is not copied into DocumentCreate today.""" +async def test_save_to_reader_includes_category_in_payload() -> None: + """The category argument is validated and copied into the save payload.""" route = respx.post(f"{V3_BASE}/save/").mock( return_value=httpx.Response(201, json={"id": "doc-1", "url": "reader-url"}) ) @@ -67,7 +67,6 @@ async def test_save_to_reader_category_is_currently_dropped_from_payload() -> No location="later", ) - # NOTE: characterizes current (possibly buggy) behavior; category is dropped. assert json.loads(route.calls.last.request.content) == { "url": "https://example.com", "html": "

Body

", @@ -75,12 +74,27 @@ async def test_save_to_reader_category_is_currently_dropped_from_payload() -> No "author": "Author", "summary": "Summary", "location": "later", + "category": "article", "saved_using": "readwise-mcp", "tags": ["tag"], "notes": "Note", } +@respx.mock +@pytest.mark.asyncio +async def test_save_to_reader_rejects_invalid_category() -> None: + """An unknown category returns an error envelope and makes no request.""" + route = respx.post(f"{V3_BASE}/save/").mock( + return_value=httpx.Response(201, json={"id": "doc-1", "url": "reader-url"}) + ) + + result = await save_to_reader("https://example.com", category="bogus") + + assert json.loads(result) == {"error": "Invalid category 'bogus'."} + assert not route.called + + @respx.mock @pytest.mark.asyncio async def test_search_documents_returns_exact_compact_json_and_omits_none() -> None: diff --git a/tests/operations/test_documents.py b/tests/operations/test_documents.py index ee0f4be..63a7cd0 100644 --- a/tests/operations/test_documents.py +++ b/tests/operations/test_documents.py @@ -201,8 +201,8 @@ async def test_get_save_update_delete_and_move_delegate_typed_results() -> None: @pytest.mark.asyncio -async def test_save_intentionally_drops_category_to_preserve_current_mcp_bug() -> None: - """The accepted save category remains absent from the resource payload in PR 6.""" +async def test_save_preserves_category() -> None: + """The save category is passed through to the resource payload.""" resource = FakeDocumentsResource() operations = DocumentOperations(resource) create = DocumentCreate( @@ -214,8 +214,7 @@ async def test_save_intentionally_drops_category_to_preserve_current_mcp_bug() - await operations.save(create) - # Characterizes current (buggy) behavior; a later stage fixes category handling. - assert resource.create_calls[0].category is None + assert resource.create_calls[0].category is DocumentCategory.ARTICLE assert resource.create_calls[0].location is DocumentLocation.LATER assert resource.create_calls[0].saved_using == "readwise-mcp" diff --git a/tests/operations/test_documents_transport.py b/tests/operations/test_documents_transport.py index 10cb85e..79a5694 100644 --- a/tests/operations/test_documents_transport.py +++ b/tests/operations/test_documents_transport.py @@ -67,8 +67,8 @@ async def test_search_transport_keeps_single_tag_query_quirk_and_mcp_projection( @respx.mock @pytest.mark.asyncio -async def test_save_transport_preserves_buggy_category_omission() -> None: - """The real save payload omits category while retaining the other MCP fields.""" +async def test_save_transport_includes_category() -> None: + """The real save payload includes category alongside the other fields.""" route = respx.post(f"{V3_BASE}/save/").mock( return_value=httpx.Response(201, json={"id": "doc-1", "url": "reader-url"}) ) @@ -93,6 +93,7 @@ async def test_save_transport_preserves_buggy_category_omission() -> None: "url": "https://example.com", "title": "Title", "location": "later", + "category": "article", "saved_using": "readwise-mcp", "tags": ["tag"], } From 6c2d5dee0862285f0a088c5ce9629149c05d8208 Mon Sep 17 00:00:00 2001 From: Evan Oman Date: Wed, 15 Jul 2026 00:21:32 -0500 Subject: [PATCH 24/24] test: make CLI parse-error contract robust to ANSI color MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit test_typer_parse_error_is_exit_two_and_routed_to_stderr asserted a plain substring, but typer/rich colorizes its error box when color is forced (GitHub Actions enables it; a plain terminal doesn't), which split "--bad-option" with escape codes and failed only on CI's 3.14 job. Strip ANSI before the content assertions — the exit code, empty stdout, and stderr routing contract is unchanged; only the incidental coloring is normalized. Gate green (837 passed). Co-Authored-By: Claude Opus 4.8 (1M context) --- tests/characterization/test_cli_contracts.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tests/characterization/test_cli_contracts.py b/tests/characterization/test_cli_contracts.py index 64b15b7..15c02fd 100644 --- a/tests/characterization/test_cli_contracts.py +++ b/tests/characterization/test_cli_contracts.py @@ -3,6 +3,7 @@ from __future__ import annotations import importlib +import re from importlib.metadata import version import httpx @@ -121,8 +122,11 @@ def test_invalid_book_category_is_an_exit_one_message_on_stdout( def test_typer_parse_error_is_exit_two_and_routed_to_stderr() -> None: """Framework-level argument errors differ from application errors.""" result = runner.invoke(app, ["highlights", "list", "--bad-option"]) + # Strip ANSI so the assertion holds whether or not the runner forces color + # (GitHub Actions enables it; a plain terminal does not). + stderr = re.sub(r"\x1b\[[0-9;]*m", "", result.stderr) assert result.exit_code == 2 assert result.stdout == "" - assert "No such option: --bad-option" in result.stderr - assert "Usage: readwise highlights list [OPTIONS]" in result.stderr + assert "No such option: --bad-option" in stderr + assert "Usage: readwise highlights list [OPTIONS]" in stderr