{"id":51400690,"url":"https://github.com/groda/gutenberg-books","last_synced_at":"2026-07-04T06:07:30.803Z","repository":{"id":354037720,"uuid":"1221882975","full_name":"groda/gutenberg-books","owner":"groda","description":"Easy access to the Project Gutenberg catalog and books","archived":false,"fork":false,"pushed_at":"2026-04-26T20:35:36.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T22:09:15.328Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/groda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-26T19:56:23.000Z","updated_at":"2026-04-26T20:35:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/groda/gutenberg-books","commit_stats":null,"previous_names":["groda/gutenberg-books"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/groda/gutenberg-books","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groda%2Fgutenberg-books","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groda%2Fgutenberg-books/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groda%2Fgutenberg-books/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groda%2Fgutenberg-books/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/groda","download_url":"https://codeload.github.com/groda/gutenberg-books/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groda%2Fgutenberg-books/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35111488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-04T06:07:29.880Z","updated_at":"2026-07-04T06:07:30.797Z","avatar_url":"https://github.com/groda.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gutenberg-books\n\n**Easy access to the entire Project Gutenberg catalog + book downloading**\n\nA lightweight, modern Python library that lets you explore **70,000+** public-domain books from Project Gutenberg with zero hassle.\n\n- Search by subject, author, language, title, or year  \n- Weighted random sampling (realistic distribution)  \n- Polite book downloading with built-in delays (respects Gutenberg's robot policy)  \n- Fully offline after the first run  \n\n[![PyPI version](https://img.shields.io/pypi/v/gutenberg-books.svg)](https://pypi.org/project/gutenberg-books/)\n[![Python versions](https://img.shields.io/pypi/pyversions/gutenberg-books.svg)](https://pypi.org/project/gutenberg-books/)\n[![License](https://img.shields.io/pypi/l/gutenberg-books.svg)](https://github.com/groda/gutenberg-books/blob/main/LICENSE)\n\n## Installation\n\n```bash\npip install gutenberg-books\n```\n\n## Quick Start\n\n```python\nfrom gutenberg_books import GutenbergBooks\n\n# Initialize (downloads ~12 MB catalog on first run and caches it)\ngb = GutenbergBooks()                    # default cache: ./GutenbergBooks\n\n# Explore the catalog\nprint(gb.topn_subjects(5))\nprint(gb.topn_authors(5))\n\n# Random books (weighted by popularity)\nprint(gb.random_books(n=3, seed=42))\n\n# Search\nresults = gb.search_books(subject=\"Pride and Prejudice\")\nprint(results[[\"Title\", \"Authors\", \"Language\"]])\n\n# Books whose authors were alive in a specific year\nprint(gb.books_matching_year(1813))   # e.g. Jane Austen era\n\n# Download books (safe \u0026 polite)\ngb.download_book(1342)                    # Pride and Prejudice\npaths = gb.download_n_books(10, subject=\"Science Fiction\", random_delay_sec=5)\npaths = gb.download_size_books(size_mb=16, random_delay_sec=5)\n```\n\nAll returned data are **pandas DataFrames** — easy to filter, save to CSV, or use in ML pipelines.\n\n## Main Features\n\n| Feature                        | Method                              | Description |\n|--------------------------------|-------------------------------------|-------------|\n| Top-N lists                    | `topn_subjects(n)`, `topn_authors(n)` etc. | Most frequent subjects, authors, languages, bookshelves |\n| Weighted random                | `random_subjects(n, seed)`, `random_authors(n, seed)` | Realistic sampling |\n| Search                         | `search_books(...)`                 | Multi-criteria search |\n| Subject / Author filter        | `books_matching_subject(substr)`    | Case-insensitive |\n| Year-based search              | `books_matching_year(year)`         | Authors alive in that year |\n| Download single book           | `download_book(book_id, random_delay_sec=5)` | Returns `Path` to file |\n| Download multiple books        | `download_books(book_ids, ...)`     | List of IDs |\n| Download by subject            | `download_n_books(n, subject, ...)` | First N matching books |\n| Download until total size      | `download_size_books(size_mb, ...)` | Great for big-data test sets |\n\n**Important**: The download methods include random delays by default to respect [Project Gutenberg's robot access policy](https://www.gutenberg.org/policy/robot_access.html).\n\n## Advanced Usage\n\n```python\n# Use custom cache location\ngb = GutenbergBooks(cache_dir=\"~/my_gutenberg_cache\")\n\n# Refresh catalog\ngb.refresh_catalog()\n\n# All unique values (pre-computed)\nprint(gb.all_subjects[:10])\nprint(gb.all_authors[:10])\n```\n\n## Development\n\nSee the [Development section](https://github.com/groda/gutenberg-books#development) in the repository for how to run tests, build the package, and contribute.\n\n## License\n\nMIT © groda\n\n---\n\n**Made with ❤️ for book lovers, data scientists, and developers.**\n\nWant to contribute? Open a PR on GitHub!\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroda%2Fgutenberg-books","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroda%2Fgutenberg-books","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroda%2Fgutenberg-books/lists"}