Repository navigation
Modules Context
Every handler receives a context object as its only argument. There are four context types, but they all provide access to the same core services. The difference is what triggered the handler and what extra data is carried alongside those services.
ModuleContext is the root context. It is created once per module at load time and holds all shared services. @on_setup and @on_teardown functions receive this directly:
from owlbot.api import ModuleContext, on_setup
@on_setup
async def setup(ctx: ModuleContext) -> None:
ctx.logger.info("Module loaded!")| Field | Type | Description |
|---|---|---|
module_name |
str |
The module's name (filename without .py for single-file modules, or directory name for packages). |
config |
ModuleConfig |
Module-scoped configuration (details). |
owncast_client |
OwncastClient |
Owncast Integration API client (details). |
storage |
ModuleStorage |
Per-module SQLite storage (details). |
commands |
ModuleCommands |
Dynamic command registration and lookup (details). |
events |
ModuleEvents |
Dynamic event handler registration (details). |
routes |
ModuleRoutes |
HTTP route registration and URL building (details). |
http |
HttpClient |
Shared HTTP client for external requests (details). |
admin_client |
OwncastAdminClient | None |
Owncast Admin API client, or None if admin is not enabled in config (details). |
logger |
logging.Logger |
Logger named owlbot.modules.<module_name>. Auto-derived from module_name. |
ModuleContext is a dataclass. All fields except logger are set during construction. logger is derived from module_name in __post_init__.
The service wrapper types (ModuleCommands, ModuleEvents, ModuleRoutes) are importable from owlbot.api for use in type annotations on helper functions:
Event handlers receive an EventContext parameterized by the event type. It wraps the event data and provides access to all services from ModuleContext:
from owlbot.api import EventContext, EventType, ChatEvent, on_event
@on_event(EventType.CHAT)
async def on_chat(ctx: EventContext[ChatEvent]) -> None:
# The event itself:
message = ctx.event.body
user = ctx.event.user.display_name
# Services (proxied from ModuleContext):
await ctx.owncast_client.send_message(f"{user} said: {message}")| Field | Type | Description |
|---|---|---|
event |
E |
The event that triggered this handler (e.g., ChatEvent, UserJoinedEvent). |
module |
ModuleContext |
The full module context with all services. |
propagation_stopped |
bool |
Whether propagation has been stopped for this event. |
| Method | Description |
|---|---|
stop_propagation(reason=None) |
Stops the event from reaching remaining handlers. See Event System. |
All ModuleContext services are available directly on ctx (see Proxied Properties below).
Command handlers receive a CommandContext with parsed command data, access to the underlying chat event, and all module services:
from owlbot.api import CommandContext, on_command
@on_command("greet", aliases=["hello", "hi"])
async def greet(ctx: CommandContext) -> None:
name = ctx.user.display_name
args = ctx.args # Everything after the command name
await ctx.owncast_client.send_message(f"Hey {name}! Args: {args}")| Field | Type | Description |
|---|---|---|
command_event |
CommandEvent |
The parsed command data (command name, args, prefix, original chat event). |
event_context |
EventContext[ChatEvent] |
The event context from the CHAT event that triggered this command. |
module |
ModuleContext |
The full module context with all services. |
CommandContext provides shortcuts into command_event for common data:
| Property | Type | Description |
|---|---|---|
command |
str |
The canonical command name (not the alias used to invoke it). |
args |
str |
Raw argument string after the command name. |
args_list |
list[str] |
Arguments split into a list by whitespace. |
prefix |
str |
The command prefix (e.g., "!"). |
chat_event |
ChatEvent |
The original chat event. |
user |
User |
The user who invoked the command (shortcut to chat_event.user). |
All ModuleContext services are available directly on ctx (see Proxied Properties below).
Route handlers receive a RouteContext with the aiohttp request and module services:
from owlbot.api import RouteContext, on_route
@on_route("/stats")
async def stats_page(ctx: RouteContext) -> dict:
query = ctx.request.query.get("format", "json")
return {"viewers": 42, "format": query}| Field | Type | Description |
|---|---|---|
request |
aiohttp.web.Request |
The aiohttp request object. Access query params, body, headers, path info, etc. |
match_info |
dict[str, str] |
Captured path parameters from {name} patterns. Empty dict for plain routes. |
module |
ModuleContext |
The full module context with all services. |
All ModuleContext services are available directly on ctx (see Proxied Properties below).
EventContext, CommandContext, and RouteContext all proxy the services from ModuleContext directly onto ctx. This means ctx.owncast_client and ctx.module.owncast_client return the same object. The full set of proxied properties:
module_name, config, owncast_client, storage, commands, events, routes, logger, http, admin_client
The only differences between the three context types are the handler-specific fields:
-
EventContext adds
.event(the triggering event) and propagation control. -
CommandContext adds
.command_event(parsed command data) and convenience properties for command/args/user. -
RouteContext adds
.request(the HTTP request).
Utility functions that need to work across handler types can accept ModuleContext directly, since all three contexts expose it via .module.
Built-in Modules
Creating New Modules