Config API & Settings
Relevant source files
The following files were used as context for generating this wiki page:
The Config API provides a structured interface for persistent data storage. It manages settings across multiple scopes, including global, guild, channel, and user levels. This system replaces standard file I/O for settings and ensures data consistency across different storage drivers. Sources: redbot/core/core_commands.py, redbot/cogs/permissions/permissions.py:109-114
Core Architecture and Scopes
The Config API organizes data into hierarchical scopes. Developers register defaults for these scopes during cog initialization. The system supports custom groups for specialized data structures. Sources: redbot/cogs/permissions/permissions.py:112-117, redbot/cogs/audio/core/commands/audioset.py:535-550
Configuration Scopes
| Scope | Description | Use Case Example |
|---|---|---|
| Global | Shared across all servers | Bot owner notifications, global prefixes |
| Guild | Specific to a Discord server | Admin roles, server-specific prefixes |
| Channel | Specific to a text/voice channel | Embed overrides for specific channels |
| User | Specific to a Discord user | Personal locale, personal embed settings |
| Member | Specific to a user within a guild | Server-specific user data |
| Custom | User-defined grouping | Permission Access Control Lists (ACL) |
Sources: redbot/core/core_commands.py:840-855, redbot/cogs/permissions/permissions.py:114-117
Data Flow for Settings Updates
The following diagram illustrates how a setting travels from a user command to persistent storage.
Implementation in Cogs
Cogs utilize config.Config.get_conf() to instantiate a configuration object. This object requires a unique identifier to prevent data collisions between different cogs. Sources: redbot/cogs/permissions/permissions.py:109-111
Registration and Defaults
Developers must register default values before accessing scoped data. The API provides methods like register_global() and register_guild(). If no value exists in storage, the API returns these defaults. Sources: redbot/cogs/permissions/permissions.py:112-114, redbot/core/commands/help.py:90-95
# Example of configuration initialization
self.config = config.Config.get_conf(self, identifier=78631113035100160)
self.config.register_global(version="")
self.config.init_custom("COG", 1)
Sources: redbot/cogs/permissions/permissions.py:109-113
Setting Evaluation Hierarchy
The bot evaluates settings using a "most-specific to least-specific" priority. For features like embeds, the bot checks channel overrides before falling back to guild or global settings. Sources: redbot/core/core_commands.py:840-854
Sources: redbot/core/core_commands.py:843-855
Help System Configuration
The Help system uses a specialized HelpSettings dataclass to interface with the Config API. This ensures per-context help settings while maintaining performance. Sources: redbot/core/commands/help.py:85-100
HelpSettings Properties
| Property | Type | Description |
|---|---|---|
page_char_limit | int | Maximum characters per help page |
use_menus | Enum | Determines if help uses buttons or reactions |
verify_checks | bool | Filters commands the user cannot run |
delete_delay | int | Delay before help messages are auto-deleted |
Sources: redbot/core/commands/help.py:101-111
Audio and Music Configuration
The Audio module demonstrates complex Config API usage for server-specific music environments. It manages toggles for auto-play, disconnect timers, and volume limits. Sources: redbot/cogs/audio/core/commands/audioset.py:532-545
Audio Setting Groups
- Restrictions: Manages global and guild-level keyword whitelists.
- Auto-play: Configures playlists used when the queue ends.
- Connectivity: Controls
emptydisconnectandemptypausetimers. - Jukebox: Sets prices for track queueing.
Sources: redbot/cogs/audio/core/commands/audioset.py:30-100, redbot/cogs/audio/core/commands/audioset.py:475-490
Permission Management (ACL)
The Permissions cog uses the Config API's custom scope to implement Access Control Lists. It maps Cog or Command names to specific models (Users, Roles, Channels) with boolean rules. Sources: redbot/cogs/permissions/permissions.py:112-125
Custom Group Hierarchy
Summary
The Config API & Settings system centralizes state management. It provides a standardized way for the bot core and cogs to persist settings across restarts. By utilizing scoped access and default registration, the API maintains data integrity while allowing granular customization for server administrators and bot owners. Sources: redbot/core/core_commands.py:898-905, redbot/core/_events.py:220-230