Chapter by Chapter

A Python bot that serializes classic literature to Mastodon, posting one chapter at a time in a daily schedule.

Overview

Chapter by Chapter is a Mastodon bot built as a plug for the robotooter framework. It takes classic literature from Project Gutenberg and posts it chapter by chapter to social media. The bot processes text files, extracts chapters, and creates engaging daily posts with customizable templates.

Features

• Automated Chapter Processing: Converts full books into individual chapters with metadata
• Customizable Templates: Flexible templating system for post formatting
• Daily Scheduling: Posts chapters on a configurable schedule
• Project Gutenberg Integration: Direct support for Project Gutenberg text files
• Rich Content Creation: Generates engaging introductions and endings.
• Mastodon Integration: Built on robotooter for reliable social media posting

Examples

• Chapter By Chapter] The reason I created this. Posts a chapter a day from Public Domain litereature. Victorian-era Netflix.

Installation

Prerequisites

• Python 3.12+
• RoboTooter 0.2.2
• Poetry for dependency management

Installation

Via pip

# Create a virtual environment
mkdir my_bot
cd my_bot
python3 -m venv .venv
# Activate the environment
. .venv/bin/activate
# And install...
pip install chapter_by_chapter

From source

1. Clone the repository:

git clone <repository-url>
cd chapter-by-chapter

2. Install dependencies:

just init
# or manually: poetry install

Usage

Setup

You will need to register the plugin, and then create a new bot.

❯ robotooter plugins register --plugin chapter_by_chapter
chapter_by_chapter plugin registered

# You will now see the new bot installed
❯ robotooter info
RobotoTooter info
Version: 0.2.0
Root directory: /Users/bryan.fordham/.robotooter
Filters:
  BlankLineFilter
  GutenbergFilter
  ParagraphCombiningFilter
Tooters:
  MarkovBot
  ChapterByChapterBot

And now create the bot, selecting ChapterByChapter as the bot you want to use.

❯ robotooter create
Let's get your bot's information.
Enter the bot name: test
Enter the username, such as 'mybot@mastodon.social': test@not.real
1. ChapterByChapterBot
2. MarkovBot
Select an option: 1
...

Setting up a Book

To configure a new book for serialization:

robotooter -b <botname> setup --book KEY --file PATH
# or
robotooter -b <botname> setup --book KEY --url URL

• KEY will be how you refer to the book, and will also be the directory name for its files.
  • So, for example, for A Study in Scarlet I used a_study_in_scarlet but you can use anything.
• PATH A local file path to a Project Gutenberg text file
• URL A URL to download a text file

Example:

robotooter -b my_literature_bot setup -f /path/to/book.txt -bk "scarlet"
robotooter -b my_literature_bot setup -u "https://gutenberg.org/files/244/244.txt" -bk "study"

Setting the Book

This bot is mean to do most things automatically. So you have to tell it which book to post.

Examples:

# Defaults to chapter 1
robotooter --book a_study_in_scarlet

# You can set a specific chapter to start from, if you want
robotooter --book a_study_in_scarlet --chapter 2

Posting Content

After you've told it which book to use, it will post the next chapter automatically.

robotooter -b <botname> toot 

If you run the command again, it will post the next chapter.

Book Queue

You have the ability to set a queue of books. If set, the bot will automatically move to the next book in the queue when the current one finishes.

$ robotooter -b beta queue --add frankenstein
Added frankenstein to the book queue.

$ robotooter -b beta queue
1 books are currently present in the book queue.
1. Frankenstein; Or, The Modern Prometheus

# And obviously you can also remove books
$ robotooter -b beta queue --remove frankenstein
Removed frankenstein from the book queue.

Periodic Messages

This plugin has the ability to send messages outside the regular book posts.

To send periodic messages (if necessary) run

robotooter -b beta periodic

Next book reminders

If turned on, you will receive private messages from the bot when you are a few days from the end of the book.

# To enable
$ robotooter -b beta periodic --enable

# to disable
$ robotooter -b beta periodic --disable

# to send messages, if needed
$ robotooter -b beta periodic

Development

Code Quality

Run linting and type checking:

just lint    # Run ruff linter with auto-fix
just type    # Run mypy type checker
just build   # Run both lint and type checks, then build

Testing

Run the test suite:

poetry run pytest

Project Structure

src/chapter_by_chapter/
    bot.py              # Main bot implementation
    content_creator.py  # Content generation and templating
    greeter.py         # User interaction handling
    models.py          # Data models and configuration
    processor.py       # Text processing and chapter extraction
    util.py           # Utility functions
        resources/
        templates/     # Post templates
        word_choices.json

Configuration

The bot uses a configuration system based on robotooter's BotConfig. Key configuration options include:

• Book Processing: Chapter extraction settings
• Content Templates: Customizable post formatting
• Scheduling: Daily posting configuration
• Social Media: Mastodon API credentials

Templates

The bot includes several customizable templates. When you create a new both they are copied to the bot's resources directory. So, if you create "chapter_bot" you will find the templates in <robotooter_root>/chapter_bot/resources/templates/:

• chapter_text.txt - Main chapter content format
• book_intro/ - Book introduction variations
• daily_intro/ - Daily post introductions
• book_ending/ - Book conclusion formats
• chapter_spoiler.txt - Spoiler warning template

The templates use jinja2 as the template engine.

When a specific template is called for, it will first to see if there is a template directory that matches. If so, it will randomly pick one of the files in the directoy as the template to use. This allows for some variety.

If there is not a directory that matches, it will look for "{template_name}.txt".

So, as an example, if you try to render the template book_intro, out of the box it will look in the templates/book_intro directory and pick a template. If you want to always use the same template, remove the directory and create templates/book_intro.txt.

Contributing

If you would like to add features, please feel free. If you use this yourself, please let me know!

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.

The AGPL-3.0 is a copyleft license that requires anyone who distributes the code or runs it on a server to make the source code available under the same license terms.

Author

Bryan L. Fordham bfordham@naughtybaptist.com