pyolivetree 2.0.0__tar.gz

pyolivetree-2.0.0/.gitignore

@@ -0,0 +1,25 @@
+.env
+.env.*
+!.env.example
+.venv/
+env/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+docs/_build/
+results/
+.ruff_cache/
+.mypy_cache/
+scripts/
+
+.DS_Store
+notes.md
+highlights.md
+clips.md
+*.db
+.vscode/

pyolivetree-2.0.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-11-08
+
+### Added
+
+- `ot.sync.pull`, `page`, `push` and `table_schema` for notes, highlights, library and reading-plan data.
+- `backup`, `annotations` and `to_markdown` for a local SQLite backup and Markdown export.
+- `pyolivetree` command line (`backup`, `notes`, `highlights`, `clips`, `status`, `library`).
+- `ot.store.all_products` to walk every page of a product listing.
+- Smart Search `ot.ai.query` with book filters.
+- `DataSet` enum for sync data sets; plain names still work.
+- Convenience methods `ot.backup()`, `notes()`, `highlights()`, `clips()`, `status()`, `library()` (also on `AsyncOliveTree`).
+- `--refresh` CLI flag; `library` prints every owned product; clear error when no backup exists.
+- Automatic re-login and retry on expired tokens.
+
+### Changed
+
+- Hand-written client organised by endpoint group (`account`, `store`, `products`, `sync`, `ai`,
+  `reading`, `media`, `messages`, `telemetry`, `web`, `firebase`). Main class is `OliveTree`;
+  `OliveTreeClient`, `AsyncOliveTreeClient` and `a`-prefixed async methods still work.
+- Store and account requests include standard client fields, fixing empty `purchased` results.
+- Sync requests use the bearer token.
+
+## [1.0.0] - 2026-06-27
+
+### Added
+
+- Initial release of the `pyolivetree` Python client covering the Olive Tree Bible Reader API operations in OpenAPI spec 1.0.0.
+- Synchronous `OliveTreeClient` and asynchronous `AsyncOliveTreeClient`.
+- Credential loading from constructor arguments or `.env` file.
+- Bearer, Basic, and HMAC authentication support.
+- Sphinx documentation and usage examples.

pyolivetree-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taiwo Kareem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyolivetree-2.0.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: pyolivetree
+Version: 2.0.0
+Summary: Python client for the Olive Tree Bible app APIs: notes, highlights, library, Smart Search
+Author: Taiwo Kareem
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,bible,bible-study,notes,olivetree
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Religion
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Religion
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: black>=24; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.1; extra == 'docs'
+Requires-Dist: sphinx>=7; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# pyolivetree
+
+Python client for the **Olive Tree Bible** APIs. Use it to pull your notes and highlights, browse your library, query Smart Search AI, and more.
+
+## Install
+
+```bash
+pip install pyolivetree
+cp .env.example .env             # put your Olive Tree email + password in it
+```
+
+## Client
+
+```python
+from pyolivetree import DataSet, OliveTree
+
+with OliveTree() as ot:              # logs in on first call that needs it
+    ot.sync.status()                 # latest change numbers for your data
+    for row in ot.sync.pull(DataSet.ANNOTATIONS):   # or "annotations"
+        print(row["table_name"], row["datum"].get("title"))
+
+    owned = list(ot.store.all_products(ot.store.purchased()))
+    ot.store.product(36163)          # product details
+    ot.products.download_links(36163)  # XML with product download URLs
+    ot.ai.query("What does the Bible say about patience?", books=["James"])
+    ot.reading.verse_of_the_day("2026-11-08")
+    ot.media.cover(36163)            # bytes (JPEG)
+```
+
+### Convenience methods
+
+```python
+with OliveTree() as ot:
+    ot.backup()              # mirror sync data into olivetree.db; later runs fetch only changes
+    ot.notes()               # your notes in Bible order (syncs annotation changes first)
+    ot.highlights()          # highlights, with the highlighter color
+    ot.clips()               # verse text you saved
+    ot.status()              # sync server status and change numbers
+    ot.library()             # every product you own, across all pages
+```
+
+`notes`, `highlights` and `clips` take `db="olivetree.db"` and `refresh=True`; pass `refresh=False` to read the local backup offline. Each item is the row's fields (`title`, `content`, `created_date`, …) plus `type`, `ref` (e.g. `"John 3:16-17"`) and `color`. `pyolivetree.to_markdown(items)` renders any of them as Markdown.
+
+Async, with the same groups and methods:
+
+```python
+import asyncio
+from pyolivetree import AsyncOliveTree
+
+async def main():
+    async with AsyncOliveTree() as ot:
+        home = await ot.store.home()
+        notes = await ot.sync.pull("annotations")   # list
+
+asyncio.run(main())
+```
+
+The 1.x names still work: `OliveTreeClient`, `AsyncOliveTreeClient`, `install_id=`, and `a`-prefixed async methods (`await client.store.ahome()`). See [examples/](examples/).
+
+Data sets are `DataSet.ANNOTATIONS`, `LIBRARY`, `DAILY_READING` and `BOOKSHELF`. Every sync method and `backup()` also accept the plain name (`"library"`) or the server name (`"managed_library"`).
+
+Responses come back as JSON (`dict`/`list`), `str` for XML/HTML, or `bytes` for images. Errors raise `OliveTreeAuthError` (login/401) or `OliveTreeAPIError` (other HTTP errors), both subclasses of `OliveTreeError` with `.status`, `.code` and `.body`. An expired token triggers one automatic re-login. `ot.request(method, url, ...)` reaches anything not wrapped.
+
+| Group | Methods |
+|---|---|
+| `ot.account` | `login`, `access_token`, `refresh_token`, `signup`, `forgot_password`, `web_handoff_token`, `subscription`, `add_variable_subscription_selections` |
+| `ot.store` | `home`, `banner`, `featured_categories`, `library`, `purchased`, `wishlists`, `search`, `category`, `product`, `products`, `library_details`, `all_products`, `path`, `subscriptions_available`, `first_run_*`, `need_interests`, `paid_features`, `paid_features_marketing`, `ads`, `product_manifest`, `giveaway`, `allow_subscription_purchase`, `subscription_variable_product_selection`, `wishlist_add`, `wishlist_remove`, `register_subscription`, `validate_google_in_app_purchase`, `support_delete_account` |
+| `ot.products` | `download_links`, `info`, `register`, `updates`, `email_signup`, `reading_templates` |
+| `ot.sync` | `status`, `page`, `pull`, `table_schema`, `push`, `release_lock`, `possibly_bad_annotation_data` |
+| `ot.ai` | `query`, `status`, `set_usage`, `models` |
+| `ot.reading` | `daily_reading`, `recommended`, `verse_of_the_day`, `verse_of_the_day_image`, `now_reading`, `completed_message` |
+| `ot.media` | `cover`, `cover_stack`, `product_image`, `reading_plan_image`, `reading_plan_list_image`, `stream` |
+| `ot.messages` | `list`, `register_device`, `metrics` |
+| `ot.telemetry` | `event_manifest`, `get_variant`, `set_variant`, `events`, `session_start`, `consent_receipt`, `location_settings`, `subscription_log_usage` |
+| `ot.web` | `timeouts`, `appirater_config`, `app_to_web_bridge`, `product_page`, `bible_study_packs`, `manage_subscriptions`, `eula`, `privacy_policy`, `help_articles`, `help_login` |
+| `ot.firebase` | `get`, `root` |
+
+Calls that change your account: `sync.push`, `store.wishlist_*`, `store.register_subscription`, `store.validate_google_in_app_purchase`, `store.support_delete_account` (irreversible), `account.signup`, `ai.set_usage`, and the `telemetry` POSTs.
+
+## Notes backup and export
+
+```bash
+pyolivetree backup                   # mirror your sync data into olivetree.db (re-runs fetch only changes)
+pyolivetree notes --out notes.md     # your notes as Markdown, grouped by Bible book (from the backup)
+pyolivetree notes --refresh          # sync changes first, then export
+pyolivetree highlights --out highlights.md
+pyolivetree clips                    # verse text you saved
+pyolivetree library                  # every product you own (JSON)
+pyolivetree status                   # sync server status (JSON)
+```
+
+```python
+from pyolivetree import OliveTree, to_markdown
+with OliveTree() as ot:
+    print(to_markdown(ot.notes()))
+```
+
+`olivetree.db` is SQLite: every row is in `syncables` (`table_name`, `datum` JSON).
+
+## How auth works
+
+- Login: `POST /store/br5/app/json/account/account_login` returns `authentication_token`. The client sends it as `OTAuthorization: Bearer <token>`.
+- Store/account form posts include standard client fields (`install_id`, `platform`, `ReaderVersion`, `supportsProductDRM`, …). Without them, `purchased` comes back empty.
+- Signed endpoints (`ai`, `messages`, `telemetry.events`, `session_start`) add a `signature` header: uppercase-hex HMAC-SHA512 of the body, using the client keys in `constants.py`. Set `OLIVE_TREE_HMAC_KEY` (hex or base64) or pass `hmac_key=` to use one key for everything.
+- `ot.request(..., basic=True)` sends HTTP Basic auth with your username and password.
+
+## Known gaps
+
+- `messages.list` returns 401 until a device is registered via `messages.register_device`. The body format for that call isn't confirmed.
+- `sync.possibly_bad_annotation_data` is currently rejected by the server (401/410); `firebase` reads are refused (423/401); the help-center pages may return 403 to non-browser clients.
+- Purchased books (study Bibles included) download as encrypted files. This client gets the download links but doesn't decrypt them.
+
+## Development
+
+Needs [uv](https://docs.astral.sh/uv/).
+
+```bash
+make install       # .venv with dev + docs extras
+make test          # pytest
+make coverage      # pytest with coverage report
+make lint          # ruff check
+make format        # ruff format + black
+make docs          # Sphinx HTML in docs/_build/html
+make security      # dependency vulnerability scan
+make run           # run examples/sync_basic.py
+make build check   # build sdist/wheel and validate with twine
+make publish-test  # upload to TestPyPI (token in ~/.pypirc)
+make publish       # upload to PyPI (token in ~/.pypirc)
+```
+
+Layout: `client.py` (auth, request, signing), `async_client.py`, `resources/` (one module per endpoint group),
+`notes.py` (backup + Markdown), `cli.py`, `constants.py`, `exceptions.py`. The OpenAPI description is in `swagger.yml`; the docs manual is in `docs/manual/`.

pyolivetree-2.0.0/README.md

@@ -0,0 +1,132 @@
+# pyolivetree
+
+Python client for the **Olive Tree Bible** APIs. Use it to pull your notes and highlights, browse your library, query Smart Search AI, and more.
+
+## Install
+
+```bash
+pip install pyolivetree
+cp .env.example .env             # put your Olive Tree email + password in it
+```
+
+## Client
+
+```python
+from pyolivetree import DataSet, OliveTree
+
+with OliveTree() as ot:              # logs in on first call that needs it
+    ot.sync.status()                 # latest change numbers for your data
+    for row in ot.sync.pull(DataSet.ANNOTATIONS):   # or "annotations"
+        print(row["table_name"], row["datum"].get("title"))
+
+    owned = list(ot.store.all_products(ot.store.purchased()))
+    ot.store.product(36163)          # product details
+    ot.products.download_links(36163)  # XML with product download URLs
+    ot.ai.query("What does the Bible say about patience?", books=["James"])
+    ot.reading.verse_of_the_day("2026-11-08")
+    ot.media.cover(36163)            # bytes (JPEG)
+```
+
+### Convenience methods
+
+```python
+with OliveTree() as ot:
+    ot.backup()              # mirror sync data into olivetree.db; later runs fetch only changes
+    ot.notes()               # your notes in Bible order (syncs annotation changes first)
+    ot.highlights()          # highlights, with the highlighter color
+    ot.clips()               # verse text you saved
+    ot.status()              # sync server status and change numbers
+    ot.library()             # every product you own, across all pages
+```
+
+`notes`, `highlights` and `clips` take `db="olivetree.db"` and `refresh=True`; pass `refresh=False` to read the local backup offline. Each item is the row's fields (`title`, `content`, `created_date`, …) plus `type`, `ref` (e.g. `"John 3:16-17"`) and `color`. `pyolivetree.to_markdown(items)` renders any of them as Markdown.
+
+Async, with the same groups and methods:
+
+```python
+import asyncio
+from pyolivetree import AsyncOliveTree
+
+async def main():
+    async with AsyncOliveTree() as ot:
+        home = await ot.store.home()
+        notes = await ot.sync.pull("annotations")   # list
+
+asyncio.run(main())
+```
+
+The 1.x names still work: `OliveTreeClient`, `AsyncOliveTreeClient`, `install_id=`, and `a`-prefixed async methods (`await client.store.ahome()`). See [examples/](examples/).
+
+Data sets are `DataSet.ANNOTATIONS`, `LIBRARY`, `DAILY_READING` and `BOOKSHELF`. Every sync method and `backup()` also accept the plain name (`"library"`) or the server name (`"managed_library"`).
+
+Responses come back as JSON (`dict`/`list`), `str` for XML/HTML, or `bytes` for images. Errors raise `OliveTreeAuthError` (login/401) or `OliveTreeAPIError` (other HTTP errors), both subclasses of `OliveTreeError` with `.status`, `.code` and `.body`. An expired token triggers one automatic re-login. `ot.request(method, url, ...)` reaches anything not wrapped.
+
+| Group | Methods |
+|---|---|
+| `ot.account` | `login`, `access_token`, `refresh_token`, `signup`, `forgot_password`, `web_handoff_token`, `subscription`, `add_variable_subscription_selections` |
+| `ot.store` | `home`, `banner`, `featured_categories`, `library`, `purchased`, `wishlists`, `search`, `category`, `product`, `products`, `library_details`, `all_products`, `path`, `subscriptions_available`, `first_run_*`, `need_interests`, `paid_features`, `paid_features_marketing`, `ads`, `product_manifest`, `giveaway`, `allow_subscription_purchase`, `subscription_variable_product_selection`, `wishlist_add`, `wishlist_remove`, `register_subscription`, `validate_google_in_app_purchase`, `support_delete_account` |
+| `ot.products` | `download_links`, `info`, `register`, `updates`, `email_signup`, `reading_templates` |
+| `ot.sync` | `status`, `page`, `pull`, `table_schema`, `push`, `release_lock`, `possibly_bad_annotation_data` |
+| `ot.ai` | `query`, `status`, `set_usage`, `models` |
+| `ot.reading` | `daily_reading`, `recommended`, `verse_of_the_day`, `verse_of_the_day_image`, `now_reading`, `completed_message` |
+| `ot.media` | `cover`, `cover_stack`, `product_image`, `reading_plan_image`, `reading_plan_list_image`, `stream` |
+| `ot.messages` | `list`, `register_device`, `metrics` |
+| `ot.telemetry` | `event_manifest`, `get_variant`, `set_variant`, `events`, `session_start`, `consent_receipt`, `location_settings`, `subscription_log_usage` |
+| `ot.web` | `timeouts`, `appirater_config`, `app_to_web_bridge`, `product_page`, `bible_study_packs`, `manage_subscriptions`, `eula`, `privacy_policy`, `help_articles`, `help_login` |
+| `ot.firebase` | `get`, `root` |
+
+Calls that change your account: `sync.push`, `store.wishlist_*`, `store.register_subscription`, `store.validate_google_in_app_purchase`, `store.support_delete_account` (irreversible), `account.signup`, `ai.set_usage`, and the `telemetry` POSTs.
+
+## Notes backup and export
+
+```bash
+pyolivetree backup                   # mirror your sync data into olivetree.db (re-runs fetch only changes)
+pyolivetree notes --out notes.md     # your notes as Markdown, grouped by Bible book (from the backup)
+pyolivetree notes --refresh          # sync changes first, then export
+pyolivetree highlights --out highlights.md
+pyolivetree clips                    # verse text you saved
+pyolivetree library                  # every product you own (JSON)
+pyolivetree status                   # sync server status (JSON)
+```
+
+```python
+from pyolivetree import OliveTree, to_markdown
+with OliveTree() as ot:
+    print(to_markdown(ot.notes()))
+```
+
+`olivetree.db` is SQLite: every row is in `syncables` (`table_name`, `datum` JSON).
+
+## How auth works
+
+- Login: `POST /store/br5/app/json/account/account_login` returns `authentication_token`. The client sends it as `OTAuthorization: Bearer <token>`.
+- Store/account form posts include standard client fields (`install_id`, `platform`, `ReaderVersion`, `supportsProductDRM`, …). Without them, `purchased` comes back empty.
+- Signed endpoints (`ai`, `messages`, `telemetry.events`, `session_start`) add a `signature` header: uppercase-hex HMAC-SHA512 of the body, using the client keys in `constants.py`. Set `OLIVE_TREE_HMAC_KEY` (hex or base64) or pass `hmac_key=` to use one key for everything.
+- `ot.request(..., basic=True)` sends HTTP Basic auth with your username and password.
+
+## Known gaps
+
+- `messages.list` returns 401 until a device is registered via `messages.register_device`. The body format for that call isn't confirmed.
+- `sync.possibly_bad_annotation_data` is currently rejected by the server (401/410); `firebase` reads are refused (423/401); the help-center pages may return 403 to non-browser clients.
+- Purchased books (study Bibles included) download as encrypted files. This client gets the download links but doesn't decrypt them.
+
+## Development
+
+Needs [uv](https://docs.astral.sh/uv/).
+
+```bash
+make install       # .venv with dev + docs extras
+make test          # pytest
+make coverage      # pytest with coverage report
+make lint          # ruff check
+make format        # ruff format + black
+make docs          # Sphinx HTML in docs/_build/html
+make security      # dependency vulnerability scan
+make run           # run examples/sync_basic.py
+make build check   # build sdist/wheel and validate with twine
+make publish-test  # upload to TestPyPI (token in ~/.pypirc)
+make publish       # upload to PyPI (token in ~/.pypirc)
+```
+
+Layout: `client.py` (auth, request, signing), `async_client.py`, `resources/` (one module per endpoint group),
+`notes.py` (backup + Markdown), `cli.py`, `constants.py`, `exceptions.py`. The OpenAPI description is in `swagger.yml`; the docs manual is in `docs/manual/`.

pyolivetree-2.0.0/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "pyolivetree"
+version = "2.0.0"
+description = "Python client for the Olive Tree Bible app APIs: notes, highlights, library, Smart Search"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Taiwo Kareem" }]
+keywords = ["olivetree", "bible", "bible-study", "notes", "api-client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Religion",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Religion",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6", "black>=24", "build>=1.2", "twine>=5"]
+docs = ["sphinx>=7", "furo>=2024.1"]
+
+[project.scripts]
+pyolivetree = "pyolivetree.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pyolivetree"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+exclude = ["docs", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.black]
+line-length = 110
+target-version = ["py310"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]

pyolivetree-2.0.0/src/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-2.0.0/src/pyolivetree/__main__.py

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

pyolivetree-2.0.0/src/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