shelfinventory 0.1.0__tar.gz

shelfinventory-0.1.0/LICENSE

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

shelfinventory-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: shelfinventory
+Version: 0.1.0
+Summary: Export an Audiobookshelf library to CSV, one row per book, with the columns people asked for. Read only, no dependencies.
+Author: Younes Z.
+License: MIT
+Project-URL: Homepage, https://github.com/Rezarys/shelfinventory
+Project-URL: Issues, https://github.com/Rezarys/shelfinventory/issues
+Keywords: audiobookshelf,audiobook,library,inventory,csv,export,catalog,selfhosted
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# shelfinventory
+
+```
+pip install shelfinventory
+```
+
+Export an Audiobookshelf library to CSV, one row per book, with the columns people actually asked for on the upstream request thread. It reads over the HTTP API and writes nothing back to your server.
+
+Why it exists: the request thread [advplyr/audiobookshelf#2085](https://github.com/advplyr/audiobookshelf/issues/2085) asks for a CSV inventory of what is really in the library. The workarounds described there are exporting from another tool, which reflects a different catalog, or opening the SQLite database with a generic client. This does the same job in one command, through the API, without touching the database file.
+
+## Use
+
+Set a token, then run it.
+
+```
+export AUDIOBOOKSHELF_TOKEN=your-api-token
+```
+
+```
+shelfinventory --url https://abs.example
+```
+
+That prints the CSV on standard output. To write a file instead:
+
+```
+shelfinventory --url https://abs.example --out books.csv
+```
+
+The token is the API token from your Audiobookshelf account settings. It is read from the environment only, never from an argument, so it does not land in your shell history. The server address can also come from `AUDIOBOOKSHELF_URL`.
+
+Titles contain commas, so the delimiter is yours to choose:
+
+```
+shelfinventory --url https://abs.example --delimiter tab
+```
+
+`--delimiter` takes one character, or one of `comma`, `semicolon`, `tab`, `pipe`, `colon`. Fields are quoted properly whatever you pick, so a comma inside a title never splits a row.
+
+## Columns
+
+Eighteen columns, in this order:
+
+- `title`
+- `subtitle`
+- `authors`
+- `narrators`
+- `series_name`
+- `series_sequence`
+- `genres`
+- `tags`
+- `published_date`
+- `published_year`
+- `publisher`
+- `asin`
+- `isbn`
+- `duration`
+- `date_added`
+- `library_name`
+- `relative_path`
+- `explicit`
+
+That list is not mine. It is the list written on the request thread, in the same order, with one change: the single "published date or year" entry became two columns, because the server stores those as two separate fields and merging them would throw one away.
+
+Multiple genres, tags or series are joined with `; ` inside one cell. Multiple authors and narrators get that same `; ` join only when you pass `--exact`; without it, they keep whatever separator the server itself used to join them. `duration` is `H:MM:SS` by default, or a number of seconds with `--duration seconds`. `date_added` is an ISO 8601 instant in UTC.
+
+Every run, unless you pass `--quiet`, prints a short report on standard error saying how many books were exported and which columns your server left empty for every one of them. That report is the honest answer to whether your library really carries this metadata, and it never mixes into the CSV.
+
+With no `--library`, every book library goes into the same CSV, and the `library_name` column says which one each row came from.
+
+## Series sequences, and one honest caveat
+
+The paginated library endpoint does not expose a series sequence as its own field. It exposes one joined string per book, built by the server as `"<name> #<sequence>"` entries separated by a comma. This tool splits that back apart, which is a guess and not a reading: a series whose own name contains a comma cannot be recovered that way.
+
+If exact series and author fields matter to you, use:
+
+```
+shelfinventory --url https://abs.example --exact
+```
+
+That reads each book a second time, through the endpoint that returns real lists, so nothing has to be split. It costs one extra request per book, which is why it is not the default.
+
+## Other options
+
+- `--library NAME` picks one library by name or id, and repeats.
+- `--list-libraries` prints what the token can read, then stops.
+- `--page-size N` sets how many books are fetched per request.
+- `--timeout SECONDS` sets the request timeout.
+- `--quiet` drops the column report.
+
+Podcast libraries are never exported. The columns above are book columns.
+
+## What is not verified
+
+Being plain about this matters more than looking finished:
+
+- No real Audiobookshelf instance has been read with this tool. The response shapes it expects come from the upstream public source code, read on 2026-09-30: `server/models/Book.js`, `server/models/LibraryItem.js` and `server/controllers/LibraryController.js`.
+- The tests run on sample payloads written for the tests, not on captured traffic from a live server.
+- Whether your server fills all eighteen columns is not something anyone has measured. The report printed on standard error is there so you can see it for yourself on the first run.
+
+If you run it on a real library, please say so on the issue tracker, whether it worked or not. The paragraph above gets corrected the day someone reports a first-hand result.
+
+## Requirements
+
+Python 3.9 or newer. The standard library only, no dependencies.
+
+## License
+
+MIT. Built with AI assistance, reviewed and tested by me.
+
+Younes Z.

shelfinventory-0.1.0/README.md

@@ -0,0 +1,110 @@
+# shelfinventory
+
+```
+pip install shelfinventory
+```
+
+Export an Audiobookshelf library to CSV, one row per book, with the columns people actually asked for on the upstream request thread. It reads over the HTTP API and writes nothing back to your server.
+
+Why it exists: the request thread [advplyr/audiobookshelf#2085](https://github.com/advplyr/audiobookshelf/issues/2085) asks for a CSV inventory of what is really in the library. The workarounds described there are exporting from another tool, which reflects a different catalog, or opening the SQLite database with a generic client. This does the same job in one command, through the API, without touching the database file.
+
+## Use
+
+Set a token, then run it.
+
+```
+export AUDIOBOOKSHELF_TOKEN=your-api-token
+```
+
+```
+shelfinventory --url https://abs.example
+```
+
+That prints the CSV on standard output. To write a file instead:
+
+```
+shelfinventory --url https://abs.example --out books.csv
+```
+
+The token is the API token from your Audiobookshelf account settings. It is read from the environment only, never from an argument, so it does not land in your shell history. The server address can also come from `AUDIOBOOKSHELF_URL`.
+
+Titles contain commas, so the delimiter is yours to choose:
+
+```
+shelfinventory --url https://abs.example --delimiter tab
+```
+
+`--delimiter` takes one character, or one of `comma`, `semicolon`, `tab`, `pipe`, `colon`. Fields are quoted properly whatever you pick, so a comma inside a title never splits a row.
+
+## Columns
+
+Eighteen columns, in this order:
+
+- `title`
+- `subtitle`
+- `authors`
+- `narrators`
+- `series_name`
+- `series_sequence`
+- `genres`
+- `tags`
+- `published_date`
+- `published_year`
+- `publisher`
+- `asin`
+- `isbn`
+- `duration`
+- `date_added`
+- `library_name`
+- `relative_path`
+- `explicit`
+
+That list is not mine. It is the list written on the request thread, in the same order, with one change: the single "published date or year" entry became two columns, because the server stores those as two separate fields and merging them would throw one away.
+
+Multiple genres, tags or series are joined with `; ` inside one cell. Multiple authors and narrators get that same `; ` join only when you pass `--exact`; without it, they keep whatever separator the server itself used to join them. `duration` is `H:MM:SS` by default, or a number of seconds with `--duration seconds`. `date_added` is an ISO 8601 instant in UTC.
+
+Every run, unless you pass `--quiet`, prints a short report on standard error saying how many books were exported and which columns your server left empty for every one of them. That report is the honest answer to whether your library really carries this metadata, and it never mixes into the CSV.
+
+With no `--library`, every book library goes into the same CSV, and the `library_name` column says which one each row came from.
+
+## Series sequences, and one honest caveat
+
+The paginated library endpoint does not expose a series sequence as its own field. It exposes one joined string per book, built by the server as `"<name> #<sequence>"` entries separated by a comma. This tool splits that back apart, which is a guess and not a reading: a series whose own name contains a comma cannot be recovered that way.
+
+If exact series and author fields matter to you, use:
+
+```
+shelfinventory --url https://abs.example --exact
+```
+
+That reads each book a second time, through the endpoint that returns real lists, so nothing has to be split. It costs one extra request per book, which is why it is not the default.
+
+## Other options
+
+- `--library NAME` picks one library by name or id, and repeats.
+- `--list-libraries` prints what the token can read, then stops.
+- `--page-size N` sets how many books are fetched per request.
+- `--timeout SECONDS` sets the request timeout.
+- `--quiet` drops the column report.
+
+Podcast libraries are never exported. The columns above are book columns.
+
+## What is not verified
+
+Being plain about this matters more than looking finished:
+
+- No real Audiobookshelf instance has been read with this tool. The response shapes it expects come from the upstream public source code, read on 2026-09-30: `server/models/Book.js`, `server/models/LibraryItem.js` and `server/controllers/LibraryController.js`.
+- The tests run on sample payloads written for the tests, not on captured traffic from a live server.
+- Whether your server fills all eighteen columns is not something anyone has measured. The report printed on standard error is there so you can see it for yourself on the first run.
+
+If you run it on a real library, please say so on the issue tracker, whether it worked or not. The paragraph above gets corrected the day someone reports a first-hand result.
+
+## Requirements
+
+Python 3.9 or newer. The standard library only, no dependencies.
+
+## License
+
+MIT. Built with AI assistance, reviewed and tested by me.
+
+Younes Z.

shelfinventory-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "shelfinventory"
+version = "0.1.0"
+description = "Export an Audiobookshelf library to CSV, one row per book, with the columns people asked for. Read only, no dependencies."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Younes Z." }]
+keywords = [
+  "audiobookshelf",
+  "audiobook",
+  "library",
+  "inventory",
+  "csv",
+  "export",
+  "catalog",
+  "selfhosted",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Rezarys/shelfinventory"
+Issues = "https://github.com/Rezarys/shelfinventory/issues"
+
+[project.scripts]
+shelfinventory = "shelfinventory.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

shelfinventory-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

shelfinventory-0.1.0/src/shelfinventory/__init__.py

@@ -0,0 +1,8 @@
+"""Export an Audiobookshelf library as one CSV row per book.
+
+Read only. The package never sends anything but HTTP GET requests.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

shelfinventory-0.1.0/src/shelfinventory/api.py

@@ -0,0 +1,130 @@
+"""Minimal read-only client for the Audiobookshelf HTTP API.
+
+Only GET requests exist here. There is no method that writes, patches or deletes
+anything on the server, by design.
+
+Endpoints used, with the upstream source that documents their shape:
+
+* ``GET /api/libraries`` returns ``{"libraries": [...]}``
+  (``server/controllers/LibraryController.js``).
+* ``GET /api/libraries/{id}/items?limit=&page=`` returns
+  ``{"results": [...], "total": N, "limit": N, "page": N}`` and each entry is the
+  minified library item JSON (``server/models/LibraryItem.js``,
+  ``toOldJSONMinified``).
+* ``GET /api/items/{id}`` returns the expanded library item JSON, which is the
+  only place where series sequences and author lists are separate fields
+  (``server/models/Book.js``, ``oldMetadataToJSON``).
+
+Authentication is a bearer token in the ``Authorization`` header
+(``server/Auth.js``, ``fromAuthHeaderAsBearerToken``).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DEFAULT_PAGE_SIZE = 500
+DEFAULT_TIMEOUT = 30.0
+
+
+class ApiError(Exception):
+    """Any failure while talking to the server, with a readable message."""
+
+
+def _default_opener(request, timeout):
+    return urllib.request.urlopen(request, timeout=timeout)
+
+
+class Client:
+    """A read-only Audiobookshelf client.
+
+    ``opener`` exists so the tests can answer requests from sample payloads
+    instead of reaching a server. It takes ``(request, timeout)`` and returns a
+    file-like object, exactly like :func:`urllib.request.urlopen`.
+    """
+
+    def __init__(self, base_url, token, timeout=DEFAULT_TIMEOUT, opener=None):
+        if not base_url:
+            raise ApiError("no server address was given")
+        if not token:
+            raise ApiError("no API token was given")
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._opener = opener or _default_opener
+
+    def get_json(self, path, params=None):
+        url = self.base_url + path
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        request = urllib.request.Request(
+            url,
+            method="GET",
+            headers={
+                "Authorization": "Bearer " + self.token,
+                "Accept": "application/json",
+            },
+        )
+        try:
+            response = self._opener(request, self.timeout)
+        except urllib.error.HTTPError as error:
+            raise ApiError(_http_message(error, url)) from error
+        except urllib.error.URLError as error:
+            raise ApiError("could not reach %s: %s" % (url, error.reason)) from error
+        with response:
+            raw = response.read()
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, ValueError) as error:
+            raise ApiError("%s did not answer with JSON" % url) from error
+
+    def libraries(self):
+        """Every library the token can see, as a list of dicts."""
+        payload = self.get_json("/api/libraries")
+        libraries = payload.get("libraries")
+        if not isinstance(libraries, list):
+            raise ApiError("the server did not return a list of libraries")
+        return libraries
+
+    def library_items(self, library_id, page_size=DEFAULT_PAGE_SIZE):
+        """Yield every library item of one library, walking the pages."""
+        if page_size < 1:
+            raise ApiError("the page size must be at least 1")
+        page = 0
+        seen = 0
+        while True:
+            payload = self.get_json(
+                "/api/libraries/%s/items" % urllib.parse.quote(str(library_id)),
+                {"limit": page_size, "page": page},
+            )
+            results = payload.get("results")
+            if not isinstance(results, list):
+                raise ApiError("the server did not return a list of items")
+            if not results:
+                return
+            for entry in results:
+                yield entry
+            seen += len(results)
+            total = payload.get("total")
+            if isinstance(total, int) and seen >= total:
+                return
+            if len(results) < page_size:
+                return
+            page += 1
+
+    def item(self, item_id):
+        """One library item in its expanded form."""
+        return self.get_json("/api/items/%s" % urllib.parse.quote(str(item_id)))
+
+
+def _http_message(error, url):
+    if error.code == 401:
+        return "the server rejected the token (401) for %s" % url
+    if error.code == 403:
+        return "the token is not allowed to read %s (403)" % url
+    if error.code == 404:
+        return "%s does not exist on this server (404)" % url
+    return "%s answered %s %s" % (url, error.code, error.reason)