bookshare 0.13.0

Bookshare API wrapper

Bookshare API Wrapper

Python wrapper for Bookshare API v1. Note: API v1 is officially sunset but still functional.

Installation

uv add bookshare

Authentication

All three required: API key, Bookshare username, and Bookshare password.

from bookshare import BookshareAPI

# Pass all credentials at initialization
api = BookshareAPI(
    API_key="bookshare_api_key",
    username="bookshare_username",
    password="bookshare_password"
)

# Or set username/password separately
api = BookshareAPI(API_key="bookshare_api_key")
api.set_credentials("bookshare_username", "bookshare_password")  # Required before use

Usage

# Search
results = api.title_search("python programming", page=1)
results = api.author_search("asimov", page=1)
results = api.full_text_search("robotics", page=1)

# Lookup
book = api.isbn_lookup("9780134685991")
book = api.book_lookup("12345")

# Browse
latest = api.latest(page=1)
popular = api.popular(page=1)

# Download
content = api.download(id="12345", version=1, chunk_size=8192)
for chunk in content:
    # Process chunk
    pass

Command-Line Interface

Installing the package also provides a bookshare command. Credentials come from --api-key / --username / --password flags, or the BOOKSHARE_API_KEY, BOOKSHARE_USERNAME, and BOOKSHARE_PASSWORD environment variables.

# Search the catalog (default --by title; also author, fts, all, isbn)
bookshare search "python programming"
bookshare search "asimov" --by author
bookshare search "9780134685991" --by isbn

# Machine-readable output (raw book records)
bookshare search "robotics" --by fts --json

# Download a book by its numeric id (from search results)
bookshare download 12345 -o book.epub          # write to a file
bookshare download 12345 > book.epub           # or stream to stdout

Run it without installing via uvx:

BOOKSHARE_API_KEY=... uvx bookshare search "asimov" --by author --json

API Methods

Search:

• title_search(title, page=1)
• author_search(author, page=1)
• author_and_title_search(text, page=1)
• full_text_search(text, page=1)
• category_search(category, page=1)
• grade_search(grade, page=1)

Lookup:

• isbn_lookup(isbn)
• book_lookup(id)
• periodical_lookup(id)
• periodical_edition_lookup(id, edition)

Browse:

• latest(page=1)
• popular(page=1)
• periodical_list(page=1, limit=100)

Reference:

• category_list()
• grade_list()

Content:

• download(id, version=1, chunk_size=8192) - Returns iterator

User:

• user_info()

Development

# Setup
git clone https://github.com/accessibleapps/bookshare.git
cd bookshare
uv sync --extra dev

# Test
uv run pytest
uv run pytest --cov=bookshare

# Lint
uv run ruff check .
uv run ruff format .