pyolivetree 2.0.0__py3-none-any.whl

pyolivetree/__init__.py

@@ -0,0 +1,37 @@
+"""Python client for the Olive Tree Bible.
+
+Example:
+    >>> from pyolivetree import OliveTree       # doctest: +SKIP
+    >>> with OliveTree() as ot:
+    ...     ot.sync.status()
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from pyolivetree._http import sign_body
+from pyolivetree.async_client import AsyncOliveTree, AsyncOliveTreeClient
+from pyolivetree.client import OliveTree, OliveTreeClient
+from pyolivetree.constants import DataSet
+from pyolivetree.exceptions import OliveTreeAPIError, OliveTreeAuthError, OliveTreeError
+from pyolivetree.notes import annotations, backup, to_markdown, verse_ref
+
+try:
+    __version__ = version("pyolivetree")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0"
+
+__all__ = [
+    "AsyncOliveTree",
+    "AsyncOliveTreeClient",
+    "DataSet",
+    "OliveTree",
+    "OliveTreeAPIError",
+    "OliveTreeAuthError",
+    "OliveTreeClient",
+    "OliveTreeError",
+    "annotations",
+    "backup",
+    "sign_body",
+    "to_markdown",
+    "verse_ref",
+]

pyolivetree/__main__.py

@@ -0,0 +1,3 @@
+from pyolivetree.cli import main
+
+main()

pyolivetree/_http.py

@@ -0,0 +1,116 @@
+"""Small helpers: .env loading, request signing and response parsing."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from pyolivetree.constants import HMAC_KEYS
+from pyolivetree.exceptions import OliveTreeAPIError, OliveTreeAuthError
+
+
+def load_dotenv(path: str = ".env") -> None:
+    """Load ``KEY=VALUE`` lines into :data:`os.environ`, keeping values already set.
+
+    Args:
+        path: File to read. Missing files are ignored.
+    """
+    if not os.path.isfile(path):
+        return
+    for line in Path(path).read_text().splitlines():
+        key, sep, val = line.partition("=")
+        if sep and not line.lstrip().startswith("#"):
+            os.environ.setdefault(key.strip(), val.strip().strip("\"'"))
+
+
+def sign_body(body: bytes, profile: str = "telemetry", key: bytes | None = None) -> str:
+    """Compute the ``signature`` header required by signed endpoints.
+
+    Args:
+        body: Exact request body bytes.
+        profile: Key name in :data:`~pyolivetree.constants.HMAC_KEYS`
+            (``"telemetry"``, ``"ai"``, ``"consent"`` or ``"features"``).
+        key: Use this key instead of the profile's key.
+
+    Returns:
+        Uppercase hex HMAC-SHA512 digest.
+
+    Raises:
+        OliveTreeAuthError: If ``profile`` is unknown and no ``key`` is given.
+    """
+    if key is None:
+        try:
+            key = HMAC_KEYS[profile]
+        except KeyError:
+            raise OliveTreeAuthError(f"Unknown HMAC profile: {profile!r}") from None
+    return hmac.new(key, body, hashlib.sha512).hexdigest().upper()
+
+
+def parse_hmac_key(raw: str | bytes | None) -> bytes | None:
+    """Decode an HMAC key given as hex, base64 or raw bytes.
+
+    Args:
+        raw: Key material, e.g. from ``OLIVE_TREE_HMAC_KEY``. Empty means no override.
+
+    Returns:
+        Key bytes, or ``None`` if ``raw`` is empty.
+
+    Raises:
+        ValueError: If a string is neither hex nor base64.
+    """
+    if not raw:
+        return None
+    if isinstance(raw, bytes):
+        return raw
+    text = raw.strip()
+    try:
+        return bytes.fromhex(text)
+    except ValueError:
+        pass
+    try:
+        return base64.b64decode(text, validate=True)
+    except binascii.Error:
+        raise ValueError("OLIVE_TREE_HMAC_KEY must be hex or base64") from None
+
+
+def parse_response(r: httpx.Response) -> Any:
+    """Decode a response by content type and raise on errors.
+
+    Args:
+        r: The HTTP response.
+
+    Returns:
+        Parsed JSON, ``str`` for text/XML/HTML, otherwise ``bytes``.
+
+    Raises:
+        OliveTreeAuthError: On HTTP 401 or ``{"authenticated": false}``.
+        OliveTreeAPIError: On any other HTTP status >= 400.
+    """
+    ctype = r.headers.get("content-type", "")
+    body: Any = r.content
+    if "json" in ctype or r.content[:1] in (b"{", b"["):
+        try:
+            body = r.json()
+        except ValueError:
+            body = r.text
+    elif ctype.startswith("text/") or "xml" in ctype or "html" in ctype:
+        body = r.text
+    failed = isinstance(body, dict) and body.get("authenticated") is False
+    if r.status_code >= 400 or failed:
+        code = body.get("errorCode") if isinstance(body, dict) else None
+        msg = body.get("error") if isinstance(body, dict) else str(body)[:200]
+        cls = OliveTreeAuthError if failed or r.status_code == 401 else OliveTreeAPIError
+        raise cls(
+            f"{r.request.method} {r.request.url.path}: HTTP {r.status_code}: {msg}",
+            r.status_code,
+            code,
+            body,
+        )
+    return body

pyolivetree/async_client.py

@@ -0,0 +1,131 @@
+"""The :class:`AsyncOliveTree` client: the same API as :class:`~pyolivetree.OliveTree`, with ``await``."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+from typing import Any
+
+from pyolivetree.client import OliveTree
+
+#: Endpoint groups mirrored from :class:`~pyolivetree.OliveTree`.
+GROUPS = (
+    "account",
+    "store",
+    "products",
+    "sync",
+    "ai",
+    "reading",
+    "media",
+    "messages",
+    "telemetry",
+    "web",
+    "firebase",
+)
+
+
+class AsyncGroup:
+    """Async view of one endpoint group. Every method becomes a coroutine.
+
+    Methods that yield (``sync.pull``, ``store.all_products``) return a list instead.
+    The 1.x names with an ``a`` prefix (``ahome``, ``asearch``) also work.
+    """
+
+    def __init__(self, group: Any) -> None:
+        self._group = group
+
+    def __getattr__(self, name: str) -> Any:
+        fn = getattr(self._group, name, None)
+        if fn is None and name.startswith("a"):
+            fn = getattr(self._group, name[1:], None)
+        if fn is None:
+            raise AttributeError(name)
+        if not callable(fn):
+            return fn
+
+        @functools.wraps(fn)
+        async def call(*args: Any, **kwargs: Any) -> Any:
+            if inspect.isgeneratorfunction(fn):
+                return await asyncio.to_thread(lambda: list(fn(*args, **kwargs)))
+            return await asyncio.to_thread(fn, *args, **kwargs)
+
+        return call
+
+
+class AsyncOliveTree:
+    """Async client. Takes the same arguments as :class:`~pyolivetree.OliveTree`.
+
+    Example:
+        >>> async with AsyncOliveTree() as ot:            # doctest: +SKIP
+        ...     home = await ot.store.home()
+        ...     notes = await ot.sync.pull("annotations")
+
+    NOTE: each call runs the synchronous client in a worker thread (``asyncio.to_thread``), so
+    concurrency is limited by the default thread pool and calls share one connection pool and token.
+    Upgrade path if that becomes a bottleneck: a native ``httpx.AsyncClient`` transport.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        #: The wrapped synchronous client (token, device id, settings live here).
+        self.client = OliveTree(*args, **kwargs)
+        for name in GROUPS:
+            setattr(self, name, AsyncGroup(getattr(self.client, name)))
+
+    def __getattr__(self, name: str) -> Any:
+        # Settings such as token, device_id and app_fields come from the wrapped client.
+        return getattr(self.client, name)
+
+    async def __aenter__(self) -> AsyncOliveTree:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await asyncio.to_thread(self.client.close)
+
+    async def login(self) -> dict:
+        """Log in. See :meth:`OliveTree.login`."""
+        return await asyncio.to_thread(self.client.login)
+
+    async def refresh(self) -> dict:
+        """Renew the access token. See :meth:`OliveTree.refresh`."""
+        return await asyncio.to_thread(self.client.refresh)
+
+    async def ensure_auth(self) -> None:
+        """Log in now if there is no token yet."""
+        await asyncio.to_thread(self.client.ensure_auth)
+
+    async def backup(self, *args: Any, **kwargs: Any) -> dict[str, int]:
+        """Back up sync data to SQLite. See :meth:`OliveTree.backup`."""
+        return await asyncio.to_thread(self.client.backup, *args, **kwargs)
+
+    async def notes(self, *args: Any, **kwargs: Any) -> list[dict]:
+        """Your notes. See :meth:`OliveTree.notes`."""
+        return await asyncio.to_thread(self.client.notes, *args, **kwargs)
+
+    async def highlights(self, *args: Any, **kwargs: Any) -> list[dict]:
+        """Your highlights. See :meth:`OliveTree.highlights`."""
+        return await asyncio.to_thread(self.client.highlights, *args, **kwargs)
+
+    async def clips(self, *args: Any, **kwargs: Any) -> list[dict]:
+        """Saved verse text. See :meth:`OliveTree.clips`."""
+        return await asyncio.to_thread(self.client.clips, *args, **kwargs)
+
+    async def status(self) -> dict:
+        """Sync status. See :meth:`OliveTree.status`."""
+        return await asyncio.to_thread(self.client.status)
+
+    async def library(self) -> list[dict]:
+        """Every product you own. See :meth:`OliveTree.library`."""
+        return await asyncio.to_thread(self.client.library)
+
+    async def request(self, method: str, url: str, **kwargs: Any) -> Any:
+        """Send one request. Same arguments as :meth:`OliveTree.request`."""
+        return await asyncio.to_thread(self.client.request, method, url, **kwargs)
+
+
+#: Name used by pyolivetree 1.x.
+AsyncOliveTreeClient = AsyncOliveTree

pyolivetree/cli.py

@@ -0,0 +1,42 @@
+"""Command line: ``pyolivetree backup|notes|highlights|clips|status|library``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from pyolivetree.client import OliveTree
+from pyolivetree.exceptions import OliveTreeError
+from pyolivetree.notes import to_markdown
+
+COMMANDS = ("backup", "notes", "highlights", "clips", "status", "library")
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Run the command line. ``argv`` defaults to ``sys.argv[1:]``.
+
+    ``notes``, ``highlights`` and ``clips`` print Markdown from the local backup (add ``--refresh``
+    to sync first). ``backup``, ``status`` and ``library`` print JSON.
+    """
+    p = argparse.ArgumentParser(prog="pyolivetree", description="Back up and export your Olive Tree notes.")
+    p.add_argument("command", choices=COMMANDS)
+    p.add_argument("--db", default="olivetree.db", help="local backup file (default: olivetree.db)")
+    p.add_argument("--out", help="write output to this file instead of stdout")
+    p.add_argument("--refresh", action="store_true", help="sync changes before exporting")
+    a = p.parse_args(argv)
+
+    try:
+        text = _run(a)
+    except OliveTreeError as e:
+        p.exit(1, f"pyolivetree: error: {e}\n")
+    Path(a.out).write_text(text) if a.out else print(text)
+
+
+def _run(a: argparse.Namespace) -> str:
+    with OliveTree() as ot:
+        if a.command in ("notes", "highlights", "clips"):
+            return to_markdown(getattr(ot, a.command)(a.db, refresh=a.refresh))
+        if a.command == "backup":
+            return json.dumps(ot.backup(a.db), indent=2)
+        return json.dumps(getattr(ot, a.command)(), indent=2)

pyolivetree/client.py

@@ -0,0 +1,273 @@
+"""The :class:`OliveTree` client: auth, request signing and endpoint groups."""
+
+from __future__ import annotations
+
+import json as jsonlib
+import os
+import platform
+import uuid
+from collections.abc import Iterable
+from typing import Any
+
+import httpx
+
+from pyolivetree import notes as _notes
+from pyolivetree._http import load_dotenv, parse_hmac_key, parse_response, sign_body
+from pyolivetree.constants import DATA_SETS, PLATFORM_ID, TOKEN_ERRORS, WWW, DataSet
+from pyolivetree.exceptions import OliveTreeAuthError, OliveTreeError
+from pyolivetree.resources import (
+    AI,
+    Account,
+    Firebase,
+    Media,
+    Messages,
+    Products,
+    Reading,
+    Store,
+    Sync,
+    Telemetry,
+    Web,
+)
+
+
+class OliveTree:
+    """Client for the Olive Tree Bible app APIs.
+
+    Endpoints are grouped as attributes: :attr:`account`, :attr:`store`, :attr:`products`,
+    :attr:`sync`, :attr:`ai`, :attr:`reading`, :attr:`media`, :attr:`messages`,
+    :attr:`telemetry`, :attr:`web` and :attr:`firebase`. The client logs in on the
+    first call that needs it. :class:`AsyncOliveTree` offers the same API with ``await``.
+
+    Convenience methods cover the common jobs: :meth:`backup`, :meth:`notes`,
+    :meth:`highlights`, :meth:`clips`, :meth:`status` and :meth:`library`.
+
+    Example:
+        >>> with OliveTree() as ot:                       # doctest: +SKIP
+        ...     notes = list(ot.sync.pull("annotations"))
+        ...     owned = list(ot.store.all_products(ot.store.purchased()))
+
+    Args:
+        username: Olive Tree email. Defaults to ``OLIVE_TREE_USERNAME`` (env or ``.env``).
+        password: Password. Defaults to ``OLIVE_TREE_PASSWORD``.
+        device_id: Install id sent to the server. Defaults to ``OLIVE_TREE_INSTALL_ID`` or a new UUID.
+        install_id: Same as ``device_id`` (1.x name).
+        token: An existing ``authentication_token`` to reuse instead of logging in.
+        hmac_key: Signing key (hex, base64 or bytes) used for every signed endpoint instead of the
+            built-in per-service keys. Defaults to ``OLIVE_TREE_HMAC_KEY``.
+        transport: Custom :mod:`httpx` transport (e.g. :class:`httpx.MockTransport` in tests).
+        timeout: Request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        username: str | None = None,
+        password: str | None = None,
+        *,
+        device_id: str | None = None,
+        install_id: str | None = None,
+        token: str | None = None,
+        hmac_key: str | bytes | None = None,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 300,
+    ) -> None:
+        load_dotenv()
+        self.username = username or os.environ.get("OLIVE_TREE_USERNAME", "")
+        self.password = password or os.environ.get("OLIVE_TREE_PASSWORD", "")
+        self.device_id = (
+            device_id or install_id or os.environ.get("OLIVE_TREE_INSTALL_ID") or str(uuid.uuid4())
+        )
+        #: Current access token (``authentication_token``), or ``None`` before login.
+        self.token: str | None = token
+        #: Refresh token from the last login, used by :meth:`refresh`.
+        self.refresh_token: str | None = None
+        #: Signing key override, or ``None`` to use the built-in per-service keys.
+        self.hmac_key: bytes | None = parse_hmac_key(
+            hmac_key if hmac_key is not None else os.environ.get("OLIVE_TREE_HMAC_KEY")
+        )
+        self.reader_version = f"pyolivetree_OS_{platform.release()}"
+        #: Standard client fields sent with every store/account form post.
+        #: Without them some endpoints, e.g. ``store.purchased``, return empty results.
+        self.app_fields: dict[str, Any] = {
+            "platform": PLATFORM_ID,
+            "platudid": self.device_id,
+            "OS": "14",
+            "language": "en",
+            "install_id": self.device_id,
+            "supportsAccessToken": 1,
+            "ReaderVersion": "7.20",
+            "model": "pyolivetree",
+            "supportsOtPub": 1,
+            "supportsProductDRM": 1,
+            "supportsAudio": 1,
+            "supportsSubscription": 1,
+            "supportsBookSets": 1,
+        }
+        self.http = httpx.Client(
+            timeout=timeout,
+            transport=transport,
+            follow_redirects=True,
+            headers={"Accept": "application/json, */*"},
+        )
+
+        self.account = Account(self)  #: Login, tokens, signup, subscriptions.
+        self.store = Store(self)  #: Catalog, search, purchases, wishlists.
+        self.products = Products(self)  #: XML product info and download links.
+        self.sync = Sync(self)  #: Notes, highlights, library and reading-plan data.
+        self.ai = AI(self)  #: Smart Search AI.
+        self.reading = Reading(self)  #: Reading plans, devotionals, verse of the day.
+        self.media = Media(self)  #: Covers and media streams.
+        self.messages = Messages(self)  #: In-app message center.
+        self.telemetry = Telemetry(self)  #: Analytics, experiments, consent.
+        self.web = Web(self)  #: Web pages and app config files.
+        self.firebase = Firebase(self)  #: Firebase Realtime Database.
+
+    def __enter__(self) -> OliveTree:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self.http.close()
+
+    def login(self) -> dict:
+        """Log in with the configured credentials. Same as :meth:`Account.login`.
+
+        Raises:
+            OliveTreeAuthError: If credentials are missing or rejected.
+        """
+        if not (self.username and self.password):
+            raise OliveTreeAuthError("Set OLIVE_TREE_USERNAME and OLIVE_TREE_PASSWORD (or pass them in).")
+        return self.account.login()
+
+    def refresh(self) -> dict:
+        """Renew the access token with the stored refresh token. Same as :meth:`Account.refresh_token`."""
+        return self.account.refresh_token()
+
+    def ensure_auth(self) -> None:
+        """Log in now if there is no token yet."""
+        if not self.token:
+            self.login()
+
+    # --- convenience --------------------------------------------------------
+
+    def backup(
+        self, db: str = "olivetree.db", data_sets: Iterable[DataSet | str] = DATA_SETS
+    ) -> dict[str, int]:
+        """Mirror your sync data into a local SQLite file, fetching only changes since the last run.
+
+        Args:
+            db: SQLite file to create or update.
+            data_sets: Data sets to back up (:class:`~pyolivetree.DataSet` members or names).
+
+        Returns:
+            Rows fetched per data set, e.g. ``{"annotations": 12, "library": 0, ...}``.
+        """
+        return _notes.backup(self, db, data_sets)
+
+    def notes(self, db: str = "olivetree.db", *, refresh: bool = True) -> list[dict]:
+        """Your notes, in Bible order.
+
+        Args:
+            db: Local backup file (created if missing).
+            refresh: Sync annotation changes into ``db`` first. ``False`` reads ``db`` offline.
+
+        Returns:
+            One dict per note: the row's fields (``title``, ``content``, ``created_date``, ...) plus
+            ``type``, ``ref`` (e.g. ``"John 3:16-17"``) and ``color``.
+        """
+        return self._annotations("note", db, refresh)
+
+    def highlights(self, db: str = "olivetree.db", *, refresh: bool = True) -> list[dict]:
+        """Your highlights, in Bible order. ``color`` is the highlighter name. See :meth:`notes`."""
+        return self._annotations("highlight", db, refresh)
+
+    def clips(self, db: str = "olivetree.db", *, refresh: bool = True) -> list[dict]:
+        """Verse text you saved, in Bible order. See :meth:`notes`."""
+        return self._annotations("clip", db, refresh)
+
+    def status(self) -> dict:
+        """Sync server status and latest change numbers. Same as ``sync.status()``."""
+        return self.sync.status()
+
+    def library(self) -> list[dict]:
+        """Every product you own, across all pages (``productId``, ``title``, ...)."""
+        return list(self.store.all_products(self.store.purchased()))
+
+    def _annotations(self, kind: str, db: str, refresh: bool) -> list[dict]:
+        if refresh:
+            _notes.backup(self, db, [DataSet.ANNOTATIONS])
+        return _notes.annotations(db, kind)
+
+    def _take_tokens(self, data: dict) -> None:
+        self.token = data.get("authentication_token") or self.token
+        self.refresh_token = data.get("refresh_token") or self.refresh_token
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict | None = None,
+        data: dict | None = None,
+        json: Any = None,
+        headers: dict | None = None,
+        auth: bool = True,
+        sign: str | None = None,
+        basic: bool = False,
+    ) -> Any:
+        """Send one request. Every endpoint method goes through here; use it for anything unwrapped.
+
+        ``None`` values in ``params`` and ``data`` are dropped.
+
+        Args:
+            method: HTTP method.
+            url: Full URL.
+            params: Query string values.
+            data: Form fields. Store/account URLs also get :attr:`app_fields`.
+            json: JSON body (sent compact, so the signature matches the bytes sent).
+            headers: Extra headers.
+            auth: Send ``OTAuthorization: Bearer <token>``, logging in first if needed.
+            sign: HMAC key profile for a ``signature`` header (``"telemetry"``, ``"ai"``, ...).
+            basic: Send HTTP Basic auth with :attr:`username` / :attr:`password`.
+
+        Returns:
+            Parsed JSON, ``str`` for text/XML/HTML, or ``bytes``.
+
+        Raises:
+            OliveTreeError: On HTTP errors. After a token error the client logs in again and
+                retries once before raising.
+        """
+        if url.startswith(f"{WWW}/store/br5/app/") and json is None:
+            data = {**self.app_fields, **(data or {})}
+        params, data, hdrs = _drop_none(params), _drop_none(data), dict(headers or {})
+        content = None
+        if json is not None:
+            content = jsonlib.dumps(json, separators=(",", ":")).encode()
+            hdrs["Content-Type"] = "application/json"
+        if sign:
+            hdrs["signature"] = sign_body(content or b"", sign, self.hmac_key)
+        basic_auth = (self.username, self.password) if basic else None
+        for attempt in (1, 2):
+            if auth:
+                self.ensure_auth()
+                hdrs["OTAuthorization"] = f"Bearer {self.token}"
+            r = self.http.request(
+                method, url, params=params, data=data, content=content, headers=hdrs, auth=basic_auth
+            )
+            try:
+                return parse_response(r)
+            except OliveTreeError as e:
+                stale = e.code in TOKEN_ERRORS or e.status == 401
+                if not (auth and attempt == 1 and stale):
+                    raise
+                self.token = None  # log in again and retry once
+
+
+def _drop_none(d: dict | None) -> dict | None:
+    return {k: v for k, v in d.items() if v is not None} if d else None
+
+
+#: Name used by pyolivetree 1.x.
+OliveTreeClient = OliveTree