PyGreece Discord Bot 🤖

A Discord bot for the PyGreece online community that handles member onboarding through a Code of Conduct acceptance flow.

✨ Features

• 👋 Automatically sends welcome messages to new members
• 📜 Implements a Code of Conduct acceptance workflow
• 🏷️ Assigns roles when members react to the Code of Conduct message
• 🗄️ Tracks member status in a database

🔧 Requirements

• 🐍 Python 3.12+
• 🐘 PostgreSQL database (for production)
• 🔑 Discord Bot Token

🚀 Setup

Discord Application

1. Go to the Discord Developer Portal
2. Create a new application
3. Go to the "Bot" tab and create a bot
4. Enable the "Server Members Intent" and "Message Content Intent" under Privileged Gateway Intents
5. Save the bot token for configuration
6. Go to the "Installation" tab and choose the "bot" option on the applications.commands dropdown for Guild Install
7. Select "Manage Roles" from permissions
8. Copy and paste the install link into your browser and invite the bot your server
9. Ensure the bot role is above the members role in the role hierarchy

This bot is used as a public bot in a Guild Install, private bot mode and user install will need testing

Environment Configuration

Copy .env.sample to a new file called .env and update the placeholder values:

DISCORD_TOKEN=<your-discord-bot-token>
DISCORD_GUILD=<your-discord-server-name>
DATABASE_URL=postgresql+asyncpg://<username>:<password>@postgres/<db>
MEMBER_ROLE_NAME=members
COC_MESSAGE_ID=<message-id-of-code-of-conduct>
COC_MESSAGE_LINK=<message-link-of-code-of-conduct>

Use compose.yml to set DB credentials

Local Development

1. Clone the repository

   git clone https://github.com/pygreece/discord.git
   cd discord

2. Install dependencies with uv

   uv venv
   source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
   uv sync

Docker Deployment 🐳

The project includes Docker configuration for easy local deployment:

docker-compose up -d

📁 Project Structure

• bot/: Main bot code
  • __main__.py: Entry point
  • cog.py: Core bot functionality
  • models.py: Database models
  • db.py: Database connection management
  • config.py: Configuration handling
  • exceptions.py: Custom exceptions
• tests/: Test suite
• alembic/: Database migrations

🧪 Testing

Run the test suite:

uv run pytest

Run with coverage:

uv run pytest --cov

👥 Contributing

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes
4. Run tests and make sure they pass ✅
5. Push your branch and create a pull request

💬 Code of Conduct

This project follows the PyGreece code of conduct. Please be respectful and inclusive when contributing to this project.