Welcome to Grace Framework

Grace Framework is an opinionated, extensible Discord bot framework built on top of discord.py. It is designed to help developers rapidly build scalable, feature-rich Discord bots with minimal boilerplate.

Key Features

• Quick to start: generate a full-featured bot in seconds
• Modular architecture: clean separation of features via extensions (cogs)
• Database integration: opt-in, per-project persistence with a single config
• Built-in generators: create extensions, models, and migrations with a single command

Inspiration

Grace Framework was inspired by the community Discord bot, Grace, that evolved into a modular and powerful bot — it began to resemble a standalone framework. Recognizing its potential, the developers extracted its architecture into Grace Framework, making its ease-of-use and flexibility available to other developers.

What These Guides Cover

Throughout these guides, we build a bot called task-bot — a simple task manager. It will be able to:

• List all current tasks — /list
• Add new tasks — /add <task name> <task description>
• Remove existing tasks — /delete <task id>
• Mark tasks as complete — /done <task id>

Along the way you'll learn:

• Installation — installing Grace Framework and its requirements
• Creating a Bot — scaffolding a project, the generated layout, and running your bot
• Configuration — how config/*.cfg files and environments work
• Models & Migrations — defining database models and evolving your schema with Alembic
• Extensions — organizing commands into cogs
• Database Management — creating, dropping, and seeding your database from the CLI
• Writing Generators — extending grace generate with your own generators

Quick Start

Install Grace Framework:

pip install grace-framework

Generate a new bot:

grace new task-bot
cd task-bot

Set your bot token in .env:

DISCORD_TOKEN=your token here

Run it:

grace run

For the full walkthrough — including models, migrations, and cogs — start with Installation.

Resources

Here's a list of resources that might be useful when working with Grace Framework:

• Python's Docs
• discord.py
• Discord Developer Portal
• SQLAlchemy
• SQLModel
• Alembic
• Pytest

Contributing

We welcome any contributions, whether it's fixing bugs, suggesting features, or improving the docs — every bit helps:

• Submit an issue
• Open a pull request
• Or hop into our Discord community and say hi!

If you intend to contribute, please read the CONTRIBUTING.md first. Additionally, every contributor is expected to follow the code of conduct.