slfhstd/PointsBot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

readme

Browse Source
This commit is contained in:
Self Hosted
2026-02-25 19:32:51 +00:00
parent 6b3d087285
commit d883bd4596
1 changed files with 47 additions and 170 deletions
Download Patch File Download Diff File Expand all files Collapse all files

217
README.md
View File

@@ -1,182 +1,59 @@
# PointsBot
## Table of Contents
## Overview
PointsBot is a Reddit bot that monitors posts in a subreddit, awards points to users who solve problems, and updates their flair to reflect their achievement levels. When the original poster marks a comment as solved (e.g., by replying "!Solved"), the bot awards a point to the solver, tracks their progress, and notifies them with a reply comment. Points accumulate to unlock new levels, and progress is visually represented with stars and progress bars.
* [Description](#description)
* [Installation](#installation)
* [Prerequisites & Configuration](#prerequisites--configuration)
* [Usage](#usage)
* [Terms of Use for a bot for Reddit](#terms-of-use-for-a-bot-for-reddit)
* [License](#license)
## Features
- Monitors subreddit posts for solutions
- Awards points to users whose comments are marked as solved
- Updates user flair based on their point level
- Notifies users of their progress and next level
- Prevents awarding points to moderators
- Consolidates points into stars for easier progress tracking
## Description
## Installation (Docker Compose)
This is a bot for Reddit that monitors solutions to questions or problems in a
subreddit and awards points to the user responsible for the solution.
### Prerequisites
- [Docker](https://docs.docker.com/get-docker/)
- [Docker Compose](https://docs.docker.com/compose/install/)
This bot was conceived as a response to
[this request](https://www.reddit.com/r/RequestABot/comments/emdeim/expert_level_bot_coding/).
### Steps
1. Clone this repository:
```bash
git clone https://github.com/slfhstd/MCH-PointsBot.git
cd MCH-PointsBot
```
2. Create a `docker-compose.yml` file in the project root with the following content:
```yaml
version: '3.8'
services:
pointsbot:
build: .
container_name: pointsbot
environment:
- PYTHONUNBUFFERED=1
volumes:
- ./.pointsbot:/root/.pointsbot
restart: unless-stopped
```
3. Configure the bot:
- Pre-create the config file using the sample config.
For more information about running bots for Reddit made with the Python
programming language,
[see this pinned post in r/RequestABot](https://www.reddit.com/r/RequestABot/comments/cyll80/a_comprehensive_guide_to_running_your_reddit_bot/).
The bot will award a point to a redditor when the OP of a submission includes
"!Solved" or "!solved" somewhere in a reply to the redditor's comment on that
submission. These points will allow the redditor to advance to different
levels.
At each level, the redditor's flair for the subreddit will be updated to reflect
their current level. However, the bot should not change a mod's flair.
Each time a point is awarded, the bot will reply to the solution comment to
notify the redditor of their total points, with a progress bar to show how many
points they need to reach the next level and a reminder of the title of the next
level.
In order to prevent the progress bar from being excessively long, some points
will be consolidated into stars instead. Right now, stars are hard-coded to
represent 100 points each, but this behavior may be configurable in the future.
The first time a point is awarded, the bot's reply comment will also include a
brief message detailing the points system.
Only the submission OP's first "!Solved" comment should result in a point being
awarded for each submission.
## Installation
### Basic Installation
**IN PROGRESS**
### Advanced Installation
Requirements:
* [Python 3](https://www.python.org/downloads/) (specifically version 3.7 or greater)
* pip (should be installed automatically with Python)
* [pipenv](https://pipenv.readthedocs.io/en/latest/)
* After installying Python & pip, install by running `pip install pipenv`
* For other installation options,
[see here](https://pipenv.readthedocs.io/en/latest/install/#installing-pipenv)
First, download this project using `git` or by downloading a ZIP archive from
the Github repository using the green `Clone or download` button. If ZIP, be
sure to extract the files from the archive before moving on.
To install the packages necessary for running the bot, navigate to the project
root directory and run `pipenv install`.
To uninstall (i.e. delete the project's virtual environment and the installed
python packages), navigate to the project root directory and instead run
`pipenv --rm`.
## Prerequisites & Configuration
### Bot account
In order to make a bot, you must first have a bot account. This could be a
personal account, but it is recommended to create a dedicated account for the
bot, especially one with the word "bot" somewhere in the name.
Once you have that, you can create a Reddit app for the bot. This is needed for
authenticating with Reddit.
1. First, go to your [app preferences](https://www.reddit.com/prefs/apps).
2. Select the "are you a developer? create an app..." button.
3. Provide a name for the bot, which could probably be the same as the account's
username.
4. Select the "script" radio button.
5. Provide a brief description.
6. For the "about url", you can provide a link to the Github repository:
https://github.com/cur33/PointsBot
7. Since it is unused, the "redirect uri" can be set to something like:
http://www.example.com/unused/redirect/uri
8. Select "create app".
You should be redirected to a page which contains the credentials you will need;
under the name of the bot is the unlabeled `client_id`, and below that with the
label "secret" is the `client_secret`.
If you have already done this in the past, the `client_id` and `client_secret`
can be found by navigating to your
[app preferences](https://www.reddit.com/prefs/apps) and selecting the "edit"
button for the app under the "developed applications" section.
### Make the bot a mod in your subreddit
Some of the bot's behaviors, e.g. altering redditor flairs, require moderator
permissions. It should require just the "Flair" and "Posts" permissions and
perhaps the "Access" permission, so you don't need to grant it full permissions.
### Configuration file
The bot will store its configuration file in a `.pointsbot` directory under the
home directory for your user on your machine. By default, this directory is also
where it will store its database and log files, but you can alter this behavior
by specifying other locations for those in the configuration process.
If this is your first time running the bot, then it will fail to detect a
configuration file and will prompt you for the necessary fields. This includes
the credentials for the Reddit account and Reddit app which you created for the
bot in the [Prerequisites & Configuration](#prerequisites--configuration) step
above. The bot will create the configuration file and save this information for
future use.
At the moment, there is not a good way to edit the existing configuration unless
you want to edit the configuration file yourself (see next paragraph). This is
the recommended process for editing the configuration until this feature is
added:
1. Go to your home directory and open the `.pointsbot` directory.
2. Either rename the `pointsbot.toml` file to something else, or move it to a
different directory.
3. Open that file in a text editor (if you haven't installed one, you can use
the default text editor for your operating system, like Notepad on Windows).
4. Run the bot and walk through the configuration process again, copying and
pasting any unchanged values from the original configuration file.
5. Once you are finished, you can either keep the old configuration file for a
while just in case, or you can delete it.
If you'd prefer, you can instead create and edit the configuration file
yourself. You will need to copy `pointsbot.sample.toml` to a new file called
`pointsbot.toml` located in the `.pointsbot` directory mentioned above. Any
instances of the word "REDACTED" should be replaced with the appropriate values;
other values should work as-is, but can be changed as needed.
This is because the config file can contain sensitive information, and
maintaining only sample versions of these files in this repository helps
developers to avoid accidentally uploading that sensitive information to a
public (or even private) code repository.
More information on the specific config options can be found in the comments in
the sample config file.
You shouldn't have to worry about it, but if you need it, information on the
TOML syntax used for the file can be found on
[TOML's Github page](https://github.com/toml-lang/toml).
4. Build and start the bot:
```bash
docker-compose up --build -d
```
## Usage
### Basic Usage
**IN PROGRESS**
### Advanced Usage
The simplest way to run the bot is to navigate to the project root directory and
run:
```bash
pipenv run python PointsBot.py
```
## Terms of use for a bot for Reddit
Since this is an open-source, unmonetized program, it should be considered
non-commercial, and is thus allowed to use the Reddit API without registration.
However, this bot is provided under the permissive MIT license, so if your use
of the bot becomes commercial, you should
[read the Reddit API terms and register here](https://www.reddit.com/wiki/api).
- The bot will run in the background and monitor your subreddit.
- Configuration and logs are stored in the `.pointsbot` directory.
- To stop the bot:
```bash
docker-compose down
```
## License
MIT License. See LICENSE.md for details.
Copyright ©2020 Collin U. Rapp. This repository is released under the MIT
license.
## Credits
Original author: Collin U. Rapp (u/GlipGlorp7)