README.md

Heraldtron

A heraldry-related bot, designed for the Heraldry Community.

Requirements

• Python 3.10+

• discord.py

• aiohttp (comes installed with discord.py)

• Pillow

• aiosqlite

• docx2python

• python-dateutil

• jishaku

• thefuzz

• Developer credentials (see below)

cchardet and aiodns are also recommended to improve performance.

For convenience, these can all be installed with pip install -r requirements/main.txt.

Setup

As one may expect, this bot requires a bot account to run. Refer to the discord.py instructions on creating one for more information. This account requires the Presence, Server Members, and Message Contents privileged intents.

For some functionality, a Google Cloud Platform account is required, with the Custom Search and Google Drive APIs enabled. Custom search features additionally require a Programmable Search engine, since Google has discontinued general search APIs. This must have image search enabled, and it is strongly recommended that you enable the "Search the entire web" setting.

Before running, the bot requires an config.json file in the root directory containing data that it needs to run:

• DISCORD_TOKEN: The Discord Developer API token.
• GCS_TOKEN: The Google Cloud Platform API key. Custom Search and Google Drive must be enabled for this key.

This is adequate for most use cases, but for a few commands, additional information is required:

• GCS_CX: The Programmable Search engine identifier.
• AR_RIJKS: The key for the Rijksmuseum API.
• AR_EURO: The key for the Europeana Pro API.
• AR_DGTNZ: The key for the Digital NZ API.
• AR_SMTHS: The key for the Smithsonian API, provided by data.gov.
• AR_DDBTK: The key for the German Digital Library/Deutsche Digitale Bibliothek API

Additionally, there are a number of optional settings that can be specified:

• OWNER_ONLY: If true, disable usage of the bot for members that are not the owner.
• LOG_LEVEL: The numeric logging level for the bot. Defaults to 20 (INFO).
• DB_PATH: An alternate path for the SQLite file to use, instead of the default data/db/heraldtron.db.
• PREFIX: The bot's prefix, by fefault !. Note that as this is primarily designed for testing, changes may not be reflected everywhere.

Usage

Once your bot is set up, use the standard Python package initialisation method (of course, use python3 if there is an overlapping python2 install):

cd path/to/heraldtron
python -m ht

Run the !help command for information about the bot's functionality.