pyolivetree 2.0.0__py3-none-any.whl

pyolivetree-2.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,28 @@
+pyolivetree/__init__.py,sha256=MhUOuNhSX1teoMyLV4JbE92Dq7BA11IREqhx4zseBFI,1038
+pyolivetree/__main__.py,sha256=1LmbyB6YnxgI4WbgBkuBhUngNqwZLnc_P9Q3PT8j3uQ,41
+pyolivetree/_http.py,sha256=rZDmkIaZZi_MJYkdCQ-aTc2WbcX2IwchNtiU1ywxs68,3631
+pyolivetree/async_client.py,sha256=Q-BSI6tBH_iF24HK4I50V5NLeDXYeeOKrI5AliDJLkw,4732
+pyolivetree/cli.py,sha256=uW8jDA5ndhEu47AOa73J6U7e3FM-0kAIokugGZaoMhU,1670
+pyolivetree/client.py,sha256=urKIbQn-A3qwrh-BcLJQ8qIMFtMd8EgP9Pe1GRUXuu8,11157
+pyolivetree/constants.py,sha256=f9sk39RSOkn0zVTddn9zS5FNIfIxCqiFSH3Gu_uwkAc,3629
+pyolivetree/exceptions.py,sha256=b08Ps9zBX0zwJ6V0Lhb8C6Kx4bVtdxcX4dqRsxeOMvk,1071
+pyolivetree/notes.py,sha256=KyQf9v534FRI_5CGjKpLW4YsIBY-ytpXEMifPlSUjUY,7271
+pyolivetree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyolivetree/resources/__init__.py,sha256=_IyYNLpU9FX8SHW-ZqnQqbuGuJP9aHYW2U8QhbJoEVQ,790
+pyolivetree/resources/_base.py,sha256=nsfBXK12Y7bQAcnAN5Ap-mK0BSAR6kw-SNNncWNJdJI,527
+pyolivetree/resources/account.py,sha256=8vnsX-lJi5anPK1LrZwfeiO0THnKAp9UtynyQw29Sbg,3961
+pyolivetree/resources/ai.py,sha256=587HCvOCjHc1OD_YymihIpzIYhmfeWEFCqsf8MSMHAE,1528
+pyolivetree/resources/firebase.py,sha256=PujbJm8sgpXaz8RftkSwEDAQJduGWtcX4uwt6DsLC58,693
+pyolivetree/resources/media.py,sha256=BlOPmBVedKIZUQhGxSzEqE-23JjUYmoCAOYe0lPyA5Y,1668
+pyolivetree/resources/messages.py,sha256=YjNe2bYnIjFqXcOXYILm-_H_iJv-jpotmCeFqNgmI1M,1400
+pyolivetree/resources/products.py,sha256=stlhImANVCeNo_KTUe5nzDwXDH7aYEtJngW01Fv-bEU,1989
+pyolivetree/resources/reading.py,sha256=Cmy1gn92Nz2_lUVR8Su0TKFLLWktUegJOMOBtdHIp3Y,2044
+pyolivetree/resources/store.py,sha256=fK-SPPySXUD-4G6T6nUuu4HnA5rLcpPL87EjSqr4XDw,7126
+pyolivetree/resources/sync.py,sha256=74DRDTtbIwZ96hyWsrS4kl7sBpTBHEKBwKurA3DBOG0,6597
+pyolivetree/resources/telemetry.py,sha256=3PXDi0A3CE3C3AT0mgzkFkHAPRiVjC2QO6Ang10BGMY,2608
+pyolivetree/resources/web.py,sha256=yxci1Xd62YGRsiD11apl0mhSUrKYAN_Tk6K-QEYXEHE,2252
+pyolivetree-2.0.0.dist-info/METADATA,sha256=apynkA2Oj23f6OZGVZ-n8FVOwaiyPW4TykOdb4CnOJg,9014
+pyolivetree-2.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pyolivetree-2.0.0.dist-info/entry_points.txt,sha256=Pvaq9gTQuNOxPeHAs3_mrjIc77fmZJp9zOGXSBlkg3c,53
+pyolivetree-2.0.0.dist-info/licenses/LICENSE,sha256=9heS9i1effcI8SNUPf-C967kg50ouwjyd8kJ72Fz6Oc,1069
+pyolivetree-2.0.0.dist-info/RECORD,,

pyolivetree-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyolivetree-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyolivetree = pyolivetree.cli:main

pyolivetree-2.0.0.dist-info/licenses/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.