goodscraps

goodscraps is a standalone, read-only Python client for public Goodreads metadata, including books, authors, works, series, editions, and cover images.

Goodreads has no supported public developer API. These endpoints are unofficial and may change or become unavailable. The package does not log in, read cookies, mutate shelves, submit ratings, or fetch review text.

Development

poetry install
poetry run pytest
poetry run ruff check .
poetry run mypy src/

The test suite runs the live Goodreads smoke test by default. Set GOODSCRAPS_LIVE=0 to run completely offline:

GOODSCRAPS_LIVE=0 poetry run pytest

CI and PyPI releases

GitHub Actions runs offline tests, Ruff, and mypy on pushes to main and on pull requests. Live Goodreads requests are intentionally disabled in CI. After those checks pass, a change to the package version on main automatically creates the matching GitHub release, which triggers PyPI publishing.

To release a new version:

# Bump the package version, then commit and push it. CI handles the tag,
# GitHub release, and PyPI publication.
poetry version patch
git add pyproject.toml
git commit -m "Bump package version"
git push origin main

Usage

Install the package and create a ~/.local/bin/goodscraps command:

./install.sh

If needed, add ~/.local/bin to your PATH.

Help and usage output uses Tinta ANSI colors when displayed in a terminal. Set NO_COLOR=1 to disable them.

from goodscraps import Goodscraps

with Goodscraps() as client:
    matches = client.search("Elantris", limit=5)
    book = client.book(matches[0].book_id)
    work = client.work(book.book_id)
    editions = client.editions(book.book_id, limit=5)
    series = client.series(book.series[0].series_id) if book.series else None
    client.download_cover(book.book_id, "/tmp/elantris.jpg")

The optional smoke CLI is available as:

poetry run goodscraps search "Elantris" --limit 5
poetry run goodscraps book 68427

Lookup failures return readable JSON by default:

{
  "error": {
    "type": "NotFound",
    "message": "No author matched 'Unknown'"
  }
}

Use --raise-errors when debugging or when a shell traceback is preferred:

goodscraps --raise-errors author "Unknown"

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for brandonscript from gravatar.com brandonscript

Credits

Author: Brandon Shelley

License

MIT License (MIT)

Requires

Python <4.0, >=3.12

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

goodscraps-0.1.0.tar.gz (12.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

goodscraps-0.1.0-py3-none-any.whl (15.7 kB view details)

Uploaded Python 3

File details

Details for the file goodscraps-0.1.0.tar.gz.

File metadata

  • Download URL: goodscraps-0.1.0.tar.gz
  • Upload date:
  • Size: 12.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for goodscraps-0.1.0.tar.gz
Algorithm Hash digest
SHA256 27c5fe381cae3daf869f73e519fcdaeacb8983f8a5f27277c418ddc00fcfc1b8
MD5 3b9dd6230359134b103f1f6e10b84ffa
BLAKE2b-256 bd16b19d515609feeb185c0c8eff21483c1ac39325e1cfa330ba70b1b25897b1

See more details on using hashes here.

Provenance

The following attestation bundles were made for goodscraps-0.1.0.tar.gz:

Publisher: publish.yml on brandonscript/goodscraps

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file goodscraps-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: goodscraps-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 15.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for goodscraps-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 45acefcdd159450b3d06b3b6a89971d64a05dbf9b52994fe7976b01e234c2f31
MD5 5a42d5fc4b8901f9643d9f10eeab7b76
BLAKE2b-256 fdc18a092e14dae658c2ba5833c41aec89f31bfd0d766ac0da26de66cb3f7f29

See more details on using hashes here.

Provenance

The following attestation bundles were made for goodscraps-0.1.0-py3-none-any.whl:

Publisher: publish.yml on brandonscript/goodscraps

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page