libex-core 0.20.0__tar.gz

libex_core-0.20.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LibexHQ
+
+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.

libex_core-0.20.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: libex-core
+Version: 0.20.0
+Summary: Audible metadata fetched and normalized into data shaped after AudiMeta's.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: httpx>=0.28.1,<0.29
+Requires-Dist: pydantic>=2.13.4,<3
+Requires-Dist: libex-core[storage] ; extra == "postgres"
+Requires-Dist: asyncpg>=0.31,<0.32 ; extra == "postgres"
+Requires-Dist: sqlalchemy>=2.0.46,<2.1 ; extra == "storage"
+Requires-Dist: alembic>=1.18.4,<1.19 ; extra == "storage"
+Requires-Dist: aiosqlite>=0.22.1,<0.23 ; extra == "storage"
+Project-URL: Changelog, https://github.com/LibexHQ/Libex/blob/main/libex_core/CHANGELOG.md
+Project-URL: Homepage, https://github.com/LibexHQ/Libex
+Project-URL: Issues, https://github.com/LibexHQ/Libex/issues
+Project-URL: Source, https://github.com/LibexHQ/Libex
+Provides-Extra: postgres
+Provides-Extra: storage
+Import-Name: libex_core
+
+# libex-core
+
+The Audible metadata library and `libex-core` command line behind
+[Libex](https://github.com/LibexHQ/Libex). It runs on your own machine,
+fetches from Audible, and returns the same JSON shapes the Libex API
+publishes: books, chapters, series, authors, narrators, search and new
+releases, in all eleven Audible marketplaces (`us uk ca au de fr it es jp in br`).
+
+Libex also runs as a hosted API, and a free public instance is at
+[libexdb.com](https://libexdb.com). You do not need it to use this package.
+
+`pip install libex` is a different, unrelated project. This one is
+`libex-core`.
+
+## Install
+
+```
+pip install libex-core
+pip install "libex-core[storage]"    # adds the optional local store (SQLite)
+pip install "libex-core[postgres]"   # the store, with Postgres as well
+```
+
+Python 3.12 or newer. The base install depends on `httpx` and `pydantic`
+only. The `libex-core` command is installed with the package, extras or not.
+
+## Set up the network first
+
+Every request goes to Audible from this machine. Audible sees the address it
+comes from together with what you look up, which is part of your reading
+history tied to your connection, so the package makes you decide how to
+connect before it sends anything. The command line reads two environment
+variables, never an option, because a proxy URL can carry credentials that
+other processes could read from a command line:
+
+| Variable | Meaning |
+|---|---|
+| `LIBEX_CORE_PROXY_URL` | An `http://` or `https://` proxy every request goes through. May carry credentials. |
+| `LIBEX_CORE_ALLOW_DIRECT_EGRESS` | `1`, `true`, `yes` or `on` lets requests leave from this machine's own address when no proxy is set. Anything else, or unset, refuses. |
+
+```
+export LIBEX_CORE_PROXY_URL="http://user:password@proxy.example:8080"
+libex-core config        # {"transport":{"mode":"proxy","host":"proxy.example"}}
+
+# or, knowing what it means:
+export LIBEX_CORE_ALLOW_DIRECT_EGRESS=1
+```
+
+With neither set, a command that needs Audible exits with status 5 and says
+what to set. `libex-core config` makes no request and never prints the proxy
+URL. What Audible and a proxy can see is described in the
+[privacy notice](https://github.com/LibexHQ/Libex/blob/main/PRIVACY.md#the-embeddable-library).
+
+## Command line
+
+Results are JSON on standard output; logs and errors go to standard error.
+`--region` defaults to `us`. Book ASINs belong to one marketplace, so use the
+region the book was published in.
+
+```
+libex-core book get ASIN --region us
+libex-core book bulk ASIN1 ASIN2 --sort rating --order desc
+libex-core book bulk --file asins.txt --language english
+libex-core book chapters ASIN
+
+libex-core series get SERIES_ASIN
+libex-core series books SERIES_ASIN
+libex-core series search "Mistborn"
+
+libex-core author get B001IGFHW6
+libex-core author search "Sanderson"
+libex-core author books B001IGFHW6 --sort releaseDate
+libex-core author books-by-name "Brandon Sanderson"
+
+libex-core narrator books "Michael Kramer"
+
+libex-core search --title "Hobbit" --author "Tolkien" --limit 5
+libex-core quick-search "project hail mary"
+libex-core abs search --title "Hobbit"
+libex-core abs quick-search --keywords "project hail mary"
+
+libex-core releases new --days 30
+libex-core releases coming-soon --days 90 --category ID
+libex-core releases categories --flat
+```
+
+`libex-core COMMAND --help` lists every option, including the filters
+(`--language`, `--genre`, `--longer-than` and others) and `--sort` / `--order`
+that the list commands share. `libex-core completion bash` (also `zsh`,
+`fish`) prints a completion script.
+
+When a list of books may not be whole, it is still printed, a notice naming
+why goes to standard error, and the status is 0.
+
+### Exit status
+
+| Status | Meaning |
+|---|---|
+| 0 | Succeeded. |
+| 1 | Unexpected error. Rerun with `-vv` for a traceback. |
+| 2 | The command line was not understood, or an argument was rejected. |
+| 3 | The requested item does not exist, or nothing matched. |
+| 4 | Audible could not be reached or did not answer. Retrying later may succeed. |
+| 5 | Configuration is missing or invalid, or the local store is off, missing its extra, unreachable or not ready. |
+| 130 | Interrupted. |
+| 141 | The reader of standard output went away. |
+
+## Local store
+
+By default nothing is kept. Setting `LIBEX_CORE_STORAGE` turns on a local
+database that lookups write what Audible answered into, under the same merge
+rules as the hosted service, and that serves the stored copy when Audible is
+unreachable. It needs the
+`storage` extra.
+
+| `LIBEX_CORE_STORAGE` | Store |
+|---|---|
+| unset, empty or `off` | none (default) |
+| `sqlite` | `libex.db` in your user data directory: `~/.local/share/libex-core/` on Linux (or under `$XDG_DATA_HOME`), `~/Library/Application Support/libex-core/` on macOS, `%LOCALAPPDATA%\libex-core\` on Windows |
+| an absolute path | that SQLite file |
+| a `sqlite:///` or `postgresql://` URL | that database (`postgres` extra for Postgres) |
+
+```
+export LIBEX_CORE_STORAGE=sqlite
+libex-core db upgrade     # creates the file; the only command that changes the schema
+libex-core db status      # exits 0 only when the store is ready
+libex-core book get ASIN   # now also stored
+libex-core db book ASIN    # read back from the store, no request to Audible
+```
+
+The other `db` commands read what is stored without contacting Audible:
+`books`, `chapters`, `author`, `author-books`, `series`, `series-books`,
+`narrators`, `narrator-books`, `genres`, `plans`, `plan`, `vvab`,
+`new-releases`, `coming-soon` and `stats`. Each prints the shape of the hosted
+API's `/db` route of the same name and exits 3 when it finds nothing. The
+store is never upgraded implicitly, and a database that holds tables this
+package did not create is refused untouched.
+
+**The store is a plaintext record of what you have looked up.** On Linux and
+macOS a new SQLite file is created readable by you only. The storage setting
+can carry database credentials, so it is read from the environment, never
+accepted as an option, and never printed. To delete a SQLite store, remove
+the file and its `-wal` and `-shm` companions beside it.
+
+## Use it as a library
+
+```python
+import asyncio
+
+from libex_core.audible.client import LibexClient
+from libex_core.exceptions import LibexException
+from libex_core.lookup import get_book, search
+
+
+async def main() -> None:
+    # The proxy decision is explicit and has no default: pass a proxy URL,
+    # or allow_direct_egress=True to send from this machine's own address.
+    asin = "..."  # the book's ASIN
+    async with LibexClient(proxy_url="http://proxy.example:8080") as client:
+        try:
+            book = await get_book(client.get, asin, region="us")
+            print(book.title)
+            for hit in await search(client.get, title="Hobbit", limit=5):
+                print(hit.asin, hit.title)
+        except LibexException as exc:
+            print(exc.code, exc.message)
+
+
+asyncio.run(main())
+```
+
+The library reads no environment variable; every setting is an argument.
+Each lookup in `libex_core.lookup` takes the request callable (`client.get`)
+first and `region` as a keyword, and returns a model from `libex_core.models`
+(pydantic). Pass `store=` a `libex_core.storage.LocalStore` to use the local
+store as above; without it nothing is persisted. Importing `libex_core`
+itself imports nothing else, and the storage libraries load only when
+`libex_core.storage` is used.
+
+## Links
+
+- Source and issues: <https://github.com/LibexHQ/Libex>
+- Changelog: <https://github.com/LibexHQ/Libex/blob/main/libex_core/CHANGELOG.md>
+- Privacy: <https://github.com/LibexHQ/Libex/blob/main/PRIVACY.md>
+- Hosted API: <https://libexdb.com>
+- License: MIT
+

libex_core-0.20.0/PYPI.md

@@ -0,0 +1,185 @@
+# libex-core
+
+The Audible metadata library and `libex-core` command line behind
+[Libex](https://github.com/LibexHQ/Libex). It runs on your own machine,
+fetches from Audible, and returns the same JSON shapes the Libex API
+publishes: books, chapters, series, authors, narrators, search and new
+releases, in all eleven Audible marketplaces (`us uk ca au de fr it es jp in br`).
+
+Libex also runs as a hosted API, and a free public instance is at
+[libexdb.com](https://libexdb.com). You do not need it to use this package.
+
+`pip install libex` is a different, unrelated project. This one is
+`libex-core`.
+
+## Install
+
+```
+pip install libex-core
+pip install "libex-core[storage]"    # adds the optional local store (SQLite)
+pip install "libex-core[postgres]"   # the store, with Postgres as well
+```
+
+Python 3.12 or newer. The base install depends on `httpx` and `pydantic`
+only. The `libex-core` command is installed with the package, extras or not.
+
+## Set up the network first
+
+Every request goes to Audible from this machine. Audible sees the address it
+comes from together with what you look up, which is part of your reading
+history tied to your connection, so the package makes you decide how to
+connect before it sends anything. The command line reads two environment
+variables, never an option, because a proxy URL can carry credentials that
+other processes could read from a command line:
+
+| Variable | Meaning |
+|---|---|
+| `LIBEX_CORE_PROXY_URL` | An `http://` or `https://` proxy every request goes through. May carry credentials. |
+| `LIBEX_CORE_ALLOW_DIRECT_EGRESS` | `1`, `true`, `yes` or `on` lets requests leave from this machine's own address when no proxy is set. Anything else, or unset, refuses. |
+
+```
+export LIBEX_CORE_PROXY_URL="http://user:password@proxy.example:8080"
+libex-core config        # {"transport":{"mode":"proxy","host":"proxy.example"}}
+
+# or, knowing what it means:
+export LIBEX_CORE_ALLOW_DIRECT_EGRESS=1
+```
+
+With neither set, a command that needs Audible exits with status 5 and says
+what to set. `libex-core config` makes no request and never prints the proxy
+URL. What Audible and a proxy can see is described in the
+[privacy notice](https://github.com/LibexHQ/Libex/blob/main/PRIVACY.md#the-embeddable-library).
+
+## Command line
+
+Results are JSON on standard output; logs and errors go to standard error.
+`--region` defaults to `us`. Book ASINs belong to one marketplace, so use the
+region the book was published in.
+
+```
+libex-core book get ASIN --region us
+libex-core book bulk ASIN1 ASIN2 --sort rating --order desc
+libex-core book bulk --file asins.txt --language english
+libex-core book chapters ASIN
+
+libex-core series get SERIES_ASIN
+libex-core series books SERIES_ASIN
+libex-core series search "Mistborn"
+
+libex-core author get B001IGFHW6
+libex-core author search "Sanderson"
+libex-core author books B001IGFHW6 --sort releaseDate
+libex-core author books-by-name "Brandon Sanderson"
+
+libex-core narrator books "Michael Kramer"
+
+libex-core search --title "Hobbit" --author "Tolkien" --limit 5
+libex-core quick-search "project hail mary"
+libex-core abs search --title "Hobbit"
+libex-core abs quick-search --keywords "project hail mary"
+
+libex-core releases new --days 30
+libex-core releases coming-soon --days 90 --category ID
+libex-core releases categories --flat
+```
+
+`libex-core COMMAND --help` lists every option, including the filters
+(`--language`, `--genre`, `--longer-than` and others) and `--sort` / `--order`
+that the list commands share. `libex-core completion bash` (also `zsh`,
+`fish`) prints a completion script.
+
+When a list of books may not be whole, it is still printed, a notice naming
+why goes to standard error, and the status is 0.
+
+### Exit status
+
+| Status | Meaning |
+|---|---|
+| 0 | Succeeded. |
+| 1 | Unexpected error. Rerun with `-vv` for a traceback. |
+| 2 | The command line was not understood, or an argument was rejected. |
+| 3 | The requested item does not exist, or nothing matched. |
+| 4 | Audible could not be reached or did not answer. Retrying later may succeed. |
+| 5 | Configuration is missing or invalid, or the local store is off, missing its extra, unreachable or not ready. |
+| 130 | Interrupted. |
+| 141 | The reader of standard output went away. |
+
+## Local store
+
+By default nothing is kept. Setting `LIBEX_CORE_STORAGE` turns on a local
+database that lookups write what Audible answered into, under the same merge
+rules as the hosted service, and that serves the stored copy when Audible is
+unreachable. It needs the
+`storage` extra.
+
+| `LIBEX_CORE_STORAGE` | Store |
+|---|---|
+| unset, empty or `off` | none (default) |
+| `sqlite` | `libex.db` in your user data directory: `~/.local/share/libex-core/` on Linux (or under `$XDG_DATA_HOME`), `~/Library/Application Support/libex-core/` on macOS, `%LOCALAPPDATA%\libex-core\` on Windows |
+| an absolute path | that SQLite file |
+| a `sqlite:///` or `postgresql://` URL | that database (`postgres` extra for Postgres) |
+
+```
+export LIBEX_CORE_STORAGE=sqlite
+libex-core db upgrade     # creates the file; the only command that changes the schema
+libex-core db status      # exits 0 only when the store is ready
+libex-core book get ASIN   # now also stored
+libex-core db book ASIN    # read back from the store, no request to Audible
+```
+
+The other `db` commands read what is stored without contacting Audible:
+`books`, `chapters`, `author`, `author-books`, `series`, `series-books`,
+`narrators`, `narrator-books`, `genres`, `plans`, `plan`, `vvab`,
+`new-releases`, `coming-soon` and `stats`. Each prints the shape of the hosted
+API's `/db` route of the same name and exits 3 when it finds nothing. The
+store is never upgraded implicitly, and a database that holds tables this
+package did not create is refused untouched.
+
+**The store is a plaintext record of what you have looked up.** On Linux and
+macOS a new SQLite file is created readable by you only. The storage setting
+can carry database credentials, so it is read from the environment, never
+accepted as an option, and never printed. To delete a SQLite store, remove
+the file and its `-wal` and `-shm` companions beside it.
+
+## Use it as a library
+
+```python
+import asyncio
+
+from libex_core.audible.client import LibexClient
+from libex_core.exceptions import LibexException
+from libex_core.lookup import get_book, search
+
+
+async def main() -> None:
+    # The proxy decision is explicit and has no default: pass a proxy URL,
+    # or allow_direct_egress=True to send from this machine's own address.
+    asin = "..."  # the book's ASIN
+    async with LibexClient(proxy_url="http://proxy.example:8080") as client:
+        try:
+            book = await get_book(client.get, asin, region="us")
+            print(book.title)
+            for hit in await search(client.get, title="Hobbit", limit=5):
+                print(hit.asin, hit.title)
+        except LibexException as exc:
+            print(exc.code, exc.message)
+
+
+asyncio.run(main())
+```
+
+The library reads no environment variable; every setting is an argument.
+Each lookup in `libex_core.lookup` takes the request callable (`client.get`)
+first and `region` as a keyword, and returns a model from `libex_core.models`
+(pydantic). Pass `store=` a `libex_core.storage.LocalStore` to use the local
+store as above; without it nothing is persisted. Importing `libex_core`
+itself imports nothing else, and the storage libraries load only when
+`libex_core.storage` is used.
+
+## Links
+
+- Source and issues: <https://github.com/LibexHQ/Libex>
+- Changelog: <https://github.com/LibexHQ/Libex/blob/main/libex_core/CHANGELOG.md>
+- Privacy: <https://github.com/LibexHQ/Libex/blob/main/PRIVACY.md>
+- Hosted API: <https://libexdb.com>
+- License: MIT