0
# Sopel
1

2
A simple, lightweight, and extensible IRC bot framework written in Python. Sopel provides a comprehensive platform for building IRC bots with a plugin architecture, built-in database support, configuration management, and extensive IRC protocol handling. It's designed to be easy to use, run, and extend with custom plugins.
3

4
## Package Information
5

6
- **Package Name**: sopel
7
- **Language**: Python
8
- **Installation**: `pip install sopel`
9
- **Python Version**: 3.8+
10

11
## Core Imports
12

13
```python
14
import sopel
15
```
16

17
For plugin development:
18

19
```python
20
from sopel import plugin, config, db, tools
21
from sopel.bot import Sopel, SopelWrapper
22
```
23

24
For configuration management:
25

26
```python
27
from sopel.config import Config, types
28
```
29

30
## Basic Usage
31

32
### Running the Bot
33

34
```python
35
# Create a basic bot instance
36
from sopel import config, bot
37

38
# Load configuration and create bot
39
settings = config.Config('/path/to/config.cfg')
40
sopel_bot = bot.Sopel(settings)
41

42
# Start the bot
43
sopel_bot.run()
44
```
45

46
### Simple Plugin Development
47

48
```python
49
from sopel import plugin
50

51
@plugin.command('hello')
52
def hello_command(bot, trigger):
53
    """Say hello to a user."""
54
    bot.say(f"Hello, {trigger.nick}!")
55

56
@plugin.rule(r'.*how are you.*')
57
def how_are_you(bot, trigger):
58
    """Respond when someone asks how we are."""
59
    bot.say("I'm doing great, thanks for asking!")
60
```
61

62
### Configuration Setup
63

64
```python
65
from sopel.config import Config, types
66

67
class MyPluginSection(types.StaticSection):
68
    api_key = types.ValidatedAttribute('api_key')
69
    timeout = types.ValidatedAttribute('timeout', int, default=30)
70

71
# Register the configuration section
72
config.define_section('myplugin', MyPluginSection)
73
```
74

75
## Architecture
76

77
Sopel is built around several key architectural components:
78

79
- **Bot Core**: The `Sopel` class manages IRC connections, plugin loading, and message routing
80
- **Plugin System**: Decorator-based plugin architecture with automatic function registration
81
- **Configuration**: Hierarchical configuration system with validation and environment variable support
82
- **Database**: SQLAlchemy-based ORM for persistent data storage across multiple database backends
83
- **IRC Protocol**: Complete IRC protocol implementation with capability negotiation and mode parsing
84
- **Trigger System**: Contextual message processing with pattern matching and user privilege handling
85

86
This modular design enables developers to create everything from simple utility bots to complex IRC automation systems with minimal setup while maintaining full extensibility.
87

88
## Capabilities
89

90
### Plugin Development
91

92
Complete plugin development system with decorators for commands, rules, events, and advanced features like rate limiting, privilege checking, and capability negotiation.
93

94
```python { .api }
95
# Core plugin decorators
96
def command(command_name: str): ...
97
def rule(pattern: str): ...
98
def event(event_types: list): ...
99
def interval(seconds: int): ...
100

101
# Access control decorators  
102
def require_admin(): ...
103
def require_privilege(level: AccessLevel): ...
104
def require_chanmsg(): ...
105

106
# Rate limiting decorators
107
def rate(user: int = 0, channel: int = 0, global_rate: int = 0): ...
108
```
109

110
[Plugin Development](./plugin-development.md)
111

112
### Bot Configuration
113

114
Powerful configuration system with section-based organization, type validation, environment variable overrides, and runtime configuration management.
115

116
```python { .api }
117
class Config:
118
    def __init__(self, filename: str, validate: bool = True): ...
119
    def define_section(self, name: str, cls_, validate: bool = True): ...
120
    def save(self): ...
121

122
class StaticSection:
123
    pass
124

125
# Configuration attribute types
126
class ValidatedAttribute: ...
127
class ListAttribute: ...
128
class ChoiceAttribute: ...
129
```
130

131
[Bot Configuration](./configuration.md)
132

133
### Database Operations
134

135
SQLAlchemy-based database layer supporting multiple backends (SQLite, MySQL, PostgreSQL, etc.) with convenient methods for storing user, channel, and plugin data.
136

137
```python { .api }
138
class SopelDB:
139
    def get_nick_value(self, nick: str, key: str): ...
140
    def set_nick_value(self, nick: str, key: str, value): ...
141
    def get_channel_value(self, channel: str, key: str): ...
142
    def set_channel_value(self, channel: str, key: str, value): ...
143
    def get_plugin_value(self, plugin: str, key: str): ...
144
    def set_plugin_value(self, plugin: str, key: str, value): ...
145
```
146

147
[Database Operations](./database.md)
148

149
### IRC Protocol Handling
150

151
Complete IRC client implementation with connection management, capability negotiation, mode parsing, and user/channel tracking.
152

153
```python { .api }
154
class Sopel:
155
    def say(self, text: str, destination: str = None): ...
156
    def action(self, text: str, destination: str = None): ...
157
    def notice(self, text: str, destination: str = None): ...
158
    def join(self, channel: str, password: str = None): ...
159
    def part(self, channel: str, message: str = None): ...
160
    def kick(self, nick: str, channel: str, message: str = None): ...
161
```
162

163
[IRC Protocol](./irc-protocol.md)
164

165
### Utilities and Tools
166

167
Comprehensive utility functions for IRC formatting, time handling, web operations, mathematical calculations, and logging.
168

169
```python { .api }
170
# Formatting utilities
171
def bold(text: str) -> str: ...
172
def color(text: str, fg: int = None, bg: int = None) -> str: ...
173
def plain(text: str) -> str: ...
174

175
# Time utilities  
176
def format_time(dt, zone=None, format=None): ...
177
def seconds_to_human(seconds: int, precision: int = 2) -> str: ...
178

179
# Web utilities
180
def get_user_agent(): ...
181
def get_session(): ...
182

183
# Identifier handling
184
class Identifier(str): ...
185
```
186

187
[Utilities and Tools](./utilities.md)
188

189
## Command-Line Interface
190

191
Sopel provides command-line tools for running bots, managing configuration, and handling plugins:
192

193
- **`sopel`**: Main bot runner with daemon support and configuration options
194
- **`sopel-config`**: Interactive configuration wizard and management tool
195
- **`sopel-plugins`**: Plugin installation, management, and information tool
196

197
## Types
198

199
### Core Types
200

201
```python { .api }
202
# Access levels for privilege checking
203
class AccessLevel(enum.IntFlag):
204
    VOICE: int
205
    HALFOP: int  
206
    OP: int
207
    ADMIN: int
208
    OWNER: int
209
    OPER: int
210

211
# Plugin capability negotiation
212
class CapabilityNegotiation(enum.Enum):
213
    NONE: str
214
    OPTIONAL: str
215
    REQUIRED: str
216

217
# Trigger context for plugin functions
218
class Trigger:
219
    nick: str
220
    user: str
221
    host: str
222
    sender: str
223
    args: list
224
    event: str
225
    raw: str
226
    is_privmsg: bool
227
    hostmask: str
228
    account: str
229
    
230
    def group(self, n: int) -> str: ...
231
    def groups(self) -> tuple: ...
232

233
# Bot wrapper for plugin functions  
234
class SopelWrapper:
235
    nick: str
236
    channels: dict
237
    users: dict
238
    db: SopelDB
239
    settings: Config
240
    
241
    def say(self, text: str, destination: str = None): ...
242
    def reply(self, text: str, destination: str = None): ...
243
    def action(self, text: str, destination: str = None): ...
244
```