Discord Cogs for Small Servers

A collection of Discord cogs designed for small, tight-knit communities (< 50 members).

These cogs focus on fostering connections between friends and family in small Discord servers. While currently tailored to my specific server's style, contributions to make them more customizable are welcome!

Available Cogs

Schedule movie nights more easily by conducting polls and managing movie suggestions.

Features:

• 🎯 Add movies to consider: !movieclub movie add {film title}
• 📅 Find available dates: !movieclub poll date start
• 🗳️ Vote on movies: !movieclub poll movie start
• 💬 Auto-create discussion threads: !movieclub movie thread {film title}

Next:

• Event Scheduler: Plan and coordinate Discord events, RSVPs, and send reminders.
• Member Stats: Track and display user activity and engagement on the server.

---

Automatically assign and remove roles based on specified holidays and events.

• Assigns and removes roles based on defined holidays (currently semi-fictitious holidays)
• Includes a way to dry run changes and force holidays, for one-offs
• Allows users to opt-out of seasonal roles

---

SocialLink (WIP)

An in-server Discord game inspired by the Persona video game series that encourages users to connect with each other. It works by lightly tracking key events (e.g., hanging out in VC channels for a while) and then assigning points to their "connection."

• /confidants command to list all confidants and their scores
• /journal command to view a log of events that increased links between users
• /rank command to see a leaderboard of who has the deepest connections with other users

---

A simple command to display users' local weather together at a specific time. Currently, you'll need to load the locations in a .env file like:

WX_LOCATIONS={"San Francisco": ["weather-gov", "37.7749,-122.4194"], "New York City": ["weather-gov", "40.730610,-73.935242"]}

• Fetch Weather Data: Retrieve weather forecasts from the WeatherGovAPI.
• Display Weather Information: Show current weather for individual or all default locations using !weather today [location].
• Set Weather Channel: Designate which channel to post weather updates in.
• Scheduled Updates: Automatically post daily weather updates at 6 AM Eastern Time.

Next:

• Weather Alerts: Incorporate weather alerts into the daily updates.
• User Customization: Allow users to customize their preferred weather information and notification settings.
• Support Additional APIs: Expand support to include more weather data sources for increased reliability and feature diversity.

EmojiLocker

Keep your server's custom emojis organized and exclusive by controlling which roles can use them. Perfect for creating VIP perks or managing themed channels.

• Easy Emoji Creation: Add new emojis by simply pasting an image URL, uploading a file, or copying from other servers with !emojilocker create {name} {source}.
• Role-Based Access: Restrict multiple emojis to specific roles (e.g., VIP members, event participants) with !emojilocker set {emoji1} {emoji2} ....
• Remove Restrictions: Unrestrict emojis to allow all roles to use them with !emojilocker unset.
• Bulk Management: View and manage all restricted emojis in one place with !emojilocker list.
• Admin Override: Admins always retain access to restricted emojis.

Development

Prerequisites

• Python 3.9+
• Docker (recommended)
• A Discord Bot Token
• Git

Local Development

1. Set up a virtual environment:

   python -m venv venv
   source venv/bin/activate  # or `venv\Scripts\activate` on Windows

2. Install dependencies:

   pip install -r cogs/requirements.txt

3. Install pre-commit hooks:

   pre-commit install

Testing

Run tests using Docker (recommended):

docker compose up tests --build

Or locally:

export PYTHONPATH=./cogs
pytest

Run static analysis:

cd cogs
ruff .
mypy .

Integration & Docker Testing

Although this repository contains the cogs and associated tests, you'll need to set up a Docker testing configuration is maintained in the Redbot root folder (not in this cog folder). In practice, this means:

1. Docker Configuration Location:
   The docker-compose.yml and dockerfile.test files are located in the Redbot root directory. They are used to build a testing environment that mounts this repository's cogs/ directory (and its tests) as read-only.

2. Running Tests:
   To run the test suite using Docker, execute the following command from the Redbot root folder:

docker-compose run tests --build

This command builds the test container and runs the test suite, which by default is set up to collect tests from the cogs/seasonalroles/tests directory. (Other directories that depend on external modules are intentionally ignored.)

Note: If you ever need to run tests for a specific cog or isolate problematic tests, you can pass additional arguments to pytest. For example, to run only the seasonal roles tests:

docker-compose run tests pytest --ignore=cogs/__tests__ --ignore=tests cogs/seasonalroles/tests

3. Local Testing Without Docker:
   Alternatively, if you'd like to run tests locally (outside of Docker), set your PYTHONPATH to include the cogs directory and then run:

export PYTHONPATH=./cogs    # For macOS/Linux (use set on Windows)
pytest

4. Static Analysis and Linting:
   You can also perform code quality checks using Docker, run:

docker-compose run lint

Project Structure

cogs/
├── movieclub/          # Movie night coordination
├── weatherchannel/     # Weather updates and alerts
├── sociallink/         # Social game mechanics
├── emojilocker/        # Emoji management
├── utilities/          # Shared utilities
└── tests/             # Test suite

Code Style

• All Python code is formatted with black and checked with ruff
• Type hints are required and checked with mypy
• Pre-commit hooks ensure consistent style

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Acknowledgments

• Red-DiscordBot - Discord bot framework
• discord.py - Discord API library
• holidays - Holiday data management

---

_{Not affiliated with Discord Inc. or any associated entities.}