Metadata-Version: 2.4
Name: bookshare
Version: 0.13.0
Summary: Bookshare API wrapper
Author-email: Q <q@q-continuum.net>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.7
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: hypothesis>=6.70.0; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
Requires-Dist: pytest-recording>=0.12.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: responses>=0.23.0; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: test
Requires-Dist: hypothesis>=6.70.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest-recording>=0.12.0; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: responses>=0.23.0; extra == 'test'
Description-Content-Type: text/markdown

# Bookshare API Wrapper

[![Tests](https://github.com/accessibleapps/bookshare/actions/workflows/test.yml/badge.svg)](https://github.com/accessibleapps/bookshare/actions/workflows/test.yml)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

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

## Installation

```bash
uv add bookshare
```

## Authentication

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

```python
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

```python
# 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.

```bash
# 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`:

```bash
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

```bash
# 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 .
```