https://github.com/peterrauscher/py-gutenberg
A Python library to access the Project Gutenberg API
https://github.com/peterrauscher/py-gutenberg
api-wrapper gutenberg project-gutenberg python python-libraries python3
Last synced: 4 days ago
JSON representation
A Python library to access the Project Gutenberg API
- Host: GitHub
- URL: https://github.com/peterrauscher/py-gutenberg
- Owner: peterrauscher
- License: mit
- Created: 2023-04-02T23:57:06.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-24T15:50:31.000Z (almost 3 years ago)
- Last Synced: 2026-03-10T10:46:30.247Z (about 1 month ago)
- Topics: api-wrapper, gutenberg, project-gutenberg, python, python-libraries, python3
- Language: Python
- Homepage: https://pypi.org/project/py-gutenberg
- Size: 26.4 KB
- Stars: 14
- Watchers: 1
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# py-gutenberg
[](https://pypi.org/project/py-gutenberg/) [](https://github.com/peterrauscher/py-gutenberg/actions) [](https://github.com/peterrauscher/py-gutenberg/actions) [](https://github.com/peterrauscher/py-gutenberg/blob/main/LICENSE) [](https://pypi.org/project/py-gutenberg/releases) [](https://pypi.org/project/py-gutenberg)
## Overview
The **py-gutenberg** package is a Python library that provides methods to access the [Project Gutenberg](https://www.gutenberg.org/) library. Users can search for books based on a variety of metadata, get full texts in various formats, and retrieve metadata for books by their ID number.
## Installation
> **_⚠️_** This package has only been tested on Python 3.7 and above. There are no plans for a Python 2 version.
The package can be installed using the pip package manager:
```sh
pip install py-gutenberg
```
## Usage
You should import the module like so:
```python
from gutenberg import GutenbergAPI
```
> The `GutenbergAPI` constructor defaults to using a public instance of the Gutendex API, hosted by me at `https://gutendex.devbranch.co`. If you are [self-hosting the API](#thanks), you can specify the IP address or URL of your instance with the `instance_url` parameter.
```python
# Uses the public instance
gb = GutenbergAPI()
# Uses a self-hosted instance
gb_private = GutenbergAPI(instance_url="https://gutendex.yourdomain.com")
```
### Book Lists and Searching
Here's a simple example to get a list of the most recently uploaded books:
```python
gb.get_all_books()
```
Or, to get only public domain books:
```python
gb.get_public_domain_books()
```
### Individual Books
To get an individual book's metadata:
```python
gb.get_book_metadata()
```
Or, to get the full text of a book:
```python
gb.get_book_text()
```
Full usage information is available in [the documentation](https://github.com/peterrauscher/py-gutenberg/wiki/Documentation)
## Thanks
This module is built on the **wonderful** but unofficial API built by [@garethbjohnson](https://github.com/garethbjohnson) known as [Gutendex](https://github.com/garethbjohnson/gutendex). By default, this library uses a public instance I'm hosting myself, but does not have the bandwidth to maintain more than a few concurrent users. Please be kind and limit your requests where possible. Additionally, if you intend to use this library in a production environment, I highly encourage you to self-host.
### Read about [self-hosting the API here!](https://github.com/garethbjohnson/gutendex/wiki/Installation-Guide)