Botterino
Botterino automates hosting and posting of /r/picturegame coordinate rounds.
- 🏁 Win a round, and your next round is posted automatically as soon as you are approved to host
- ✅ Replies
+corrector❌to guesses with configurable distance tolerances, multiple coordinates or text matching - 🖼️ Post image links or upload images straight from your computer
- 💡 Scheduled hints, messages when a round starts or ends, and automatic series numbering
- 🗺️ A live map of everyone's guesses saved for every round
- 🔍 Checks your round files for mistakes before you win, not after
Install
- Install Python 3.8 or newer
- on windows it is easiest to install python from the microsoft store
- Open a terminal (or command prompt) and run
pip install botterino - Run
python -m botterino. The first time, a short setup asks where botterino should keep its files and where your round images are. Press enter to accept the defaults. You can run the setup again any time withpython -m botterino.configure
All the files you interact with live in the botterino-config folder. By default that is:
| OS | Location |
|---|---|
| windows | C:\Users\<your username>\botterino-config |
| mac | /Users/<your username>/botterino-config |
| linux | ~/botterino-config |
To keep it somewhere else, choose a different folder in the setup or set the BOTTERINO_CONFIG environment variable.
botterino-config/
├── praw.ini reddit login
├── config.ini settings
├── hints.yaml scheduled hints
├── images/ images for 'path:' rounds (configurable)
├── maps/ maps of guesses for each round
└── rounds/
├── rounds.yaml rounds waiting to be posted
└── archive.yaml rounds that have been posted
Reddit login
Create a Reddit app and add its details to botterino-config/praw.ini
(see sample-praw.ini):
- Give the app any name, such as 'botterino'
- Choose 'script' as the app type
- Fill in 'redirect URI' with
http://localhost:8080 - Once created, copy the 'secret' into
client_secret - Copy the client id (under the app name and the words 'personal use script') into
client_id - Fill in your Reddit
username,passwordand anything you like foruser_agent
Accounts with 2fa: leave out username and password. When you run botterino, log in through the browser
window that opens, then paste the refresh_token it prints into praw.ini so you don't have to log in again.
Usage
- Add rounds to
botterino-config/rounds/rounds.yaml. Seesample-rounds.yamlfor every kind of round botterino supports. - Run
python -m botterino - Win! Until you win, botterino just waits. When you are approved to host, the top round in
rounds.yamlis posted.
vegas_round:
title: 'What are my coordinates?'
url: https://i.imgur.com/qBRRrbD.jpg
answer: 36.170439, -115.139889
tolerance: 50
Rounds added to rounds.yaml while botterino is running are picked up automatically, no need to restart.
Once a round is posted it moves to rounds/archive.yaml.
Uploading images
Use path instead of url to upload an image from your computer:
upload_round:
title: 'What are my coordinates?'
path: vegas.jpg
answer: 36.170439, -115.139889
tolerance: 50
Relative paths are looked up in your images folder first (botterino-config/images unless you picked another
folder in the setup), then in botterino-config/rounds, then in the folder you started botterino from.
Absolute paths work too; on windows write them in single quotes ('C:\Users\me\Pictures\vegas.jpg') or with forward
slashes. png, jpg and gif images up to 20MB are supported.
Checking your rounds
Botterino checks rounds.yaml and hints.yaml when it starts and every time you save them while it is waiting,
and warns you about problems like invalid yaml, missing titles, bad coordinates, images that don't exist,
typos in field names and rounds with duplicate names. If the next round has an error when you win, botterino waits
for you to fix it instead of posting something broken.
You can also check them yourself at any time:
python -m botterino.validate
Hints
Botterino can post hints on a schedule. Entries in botterino-config/hints.yaml are matched to rounds by name.
See sample-hints.yaml for the syntax. hints.yaml can be edited while a round is running.
Map of guesses
For coordinate rounds, every guess is plotted on a map with the answer and its tolerance, saved to
botterino-config/maps. The map is updated after every guess, so you can refresh it in your browser during the round.
When the round ends it opens in your browser, set open_map = false in config.ini to turn that off.
Live rounds
Botterino can take over a round that is already live, for example if you posted manually or botterino crashed while hosting.
- Make sure the round is at the top of
rounds.yaml - Run
python -m botterino.failure
Botterino replies to the guesses it missed, then continues hosting as usual.
UI
python -m botterino.ui opens a small window to add rounds to rounds.yaml (including picking an image to upload)
and to start and stop the bot.
Settings
Settings live in botterino-config/config.ini. New settings are added automatically with their defaults when you update.
| Setting | Default | Description |
|---|---|---|
correct_message |
+correct |
reply to correct guesses |
incorrect_message |
❌ |
reply to incorrect guesses |
images_dir |
(empty) | folder searched first for image paths, empty means botterino-config/images |
open_map |
true |
open the map of guesses in your browser when a round ends |
save_map |
true |
save a map of guesses for coordinate rounds |
color |
auto |
colored output: auto, always or never. The NO_COLOR environment variable also turns it off |
hyperlinks |
auto |
clickable links in the terminal: auto, always or never |
ignore_users |
(empty) | comma separated usernames botterino never replies to |
subreddit |
picturegame |
only change this for testing |
Commands
| Command | What it does |
|---|---|
python -m botterino |
run the bot |
python -m botterino.validate |
check rounds.yaml and hints.yaml for mistakes |
python -m botterino.configure |
run the setup again (config folder, images folder, map) |
python -m botterino.failure |
take over a round that is already live |
python -m botterino.ui |
open the UI |
The same commands are also installed as botterino, botterino-check, botterino-setup, botterino-failure and botterino-ui.
Update
pip install --upgrade botterino
Troubleshooting
- Bot does not run, crash message shows a 403 error, everything in praw.ini looks correct: try a different
user_agent praw.inierrors about a duplicate section: only one[botterino]section may be uncommented- Strange characters instead of colors on windows: botterino turns on color support in the windows console
automatically. If you still see codes like
[38;5;...m, use Windows Terminal or setcolor = neverinconfig.ini
1 maintainer
Metadata
1 maintainer
Release files for botterino 0.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| botterino-0.6.2.tar.gz | 31.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| botterino-0.6.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 65.7 kB
Release files / botterino-0.6.2.tar.gz
| Download URL | botterino-0.6.2.tar.gz |
|---|---|
| Size | 31.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
075da61c3f20e1bfea8a397f760c7fb1d15747f8846febf9aa2df8b13a5af19b
|
|
BLAKE2b-256 checksum How to use checksums |
2be21d083a5347be42fc239197d96da6a4893d47980a1fb40458379a5305c41f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
Release files / botterino-0.6.2-py3-none-any.whl
| Download URL | botterino-0.6.2-py3-none-any.whl |
|---|---|
| Size | 34.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3bbf4c7fe185684ad533995b3f8fa97c052b2a29b475fb6a7630f9c1fc1b734c
|
|
BLAKE2b-256 checksum How to use checksums |
dcaf83b835168b8009e3ddb40cf84c9d04bce794518e9c6ba3e83bf53d4c6a70
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.8
|
