models ¶

Bases: SQLModel, TimestampMixin

Base SQLModel class with automatic timestamp management.

This class provides automatic created_at and updated_at timestamp fields that are managed by the database, along with serialization utilities for JSON responses.

Attributes:

• created_at ((datetime, optional)) –

  Timestamp when the record was created (database-managed).

• updated_at ((datetime, optional)) –

  Timestamp when the record was last updated (database-managed).

Methods:

• serialize_datetimes –

  Serialize datetime objects to ISO format strings.

• model_post_init –

  Ensure timestamp fields are always present in dict for compatibility.

• to_dict –

  Convert model instance to dictionary with relationship support.

serialize_datetimes(value: datetime | None) -> str | None

model_post_init(__context: Any) -> None

to_dict(
    include_relationships: bool = False, relationships: list[str] | None = None
) -> dict[str, Any]

Bases: SQLModel

Mixin for soft delete functionality.

Provides: - deleted_at: Timestamp when record was soft-deleted - is_deleted: Boolean flag for soft delete status

Methods:

• serialize_deleted_at –

  Serialize deleted_at field to ISO format string.

• soft_delete –

  Mark record as soft-deleted.

• restore –

  Restore a soft-deleted record.

serialize_deleted_at(value: datetime | None) -> str | None

soft_delete() -> None

restore() -> None

Bases: SQLModel

Mixin for models that need UUID primary keys.

Provides: - id: UUID primary key with auto-generation - Proper indexing for performance

Bases: str, Enum

Types of moderation cases that can be recorded in the system.

Bases: str, Enum

Types of permissions that can be configured in the system.

Bases: SQLModel

Away From Keyboard status for users.

Tracks when users set themselves as AFK and provides a reason for their absence.

Attributes:

• member_id (int) –

  Discord user ID (primary key).

• guild_id (int) –

  Guild ID (primary key, foreign key to guild table).

• nickname (str) –

  User's nickname when they went AFK.

• reason (str) –

  Reason for being AFK.

• since (datetime) –

  When the user went AFK.

• until ((datetime, optional)) –

  When the AFK status expires (for scheduled AFK).

• enforced (bool) –

  Whether AFK is enforced (user can't remove it themselves).

• perm_afk (bool) –

  Whether this is a permanent AFK status.

Methods:

• __repr__ –

  Return string representation showing member and guild.

__repr__() -> str

Bases: BaseModel

Moderation case records.

Represents individual moderation actions taken against users, such as bans, kicks, timeouts, warnings, etc.

Attributes:

• id (int) –

  Unique case identifier for the guild.

• case_status (bool) –

  Whether the case is valid or voided.

• case_processed (bool) –

  Whether expiration has been processed.

• case_type (CaseType) –

  Type of moderation action taken.

• case_reason (str) –

  Reason for the moderation action.

• case_moderator_id (int) –

  Discord user ID of the moderator who took action.

• case_user_id (int) –

  Discord user ID of the moderated user.

• case_user_roles (list[int]) –

  User's roles at the time of the case.

• case_number ((int, optional)) –

  Sequential case number for the guild.

• case_expires_at ((datetime, optional)) –

  When temporary action expires.

• case_metadata ((dict, optional)) –

  Additional case-specific metadata.

• mod_log_message_id ((int, optional)) –

  Discord message ID in mod log.

• guild_id (int) –

  Discord guild ID where the case occurred.

Methods:

• __repr__ –

  Return string representation showing guild, case number, type and target user.

• serialize_datetimes –

  Serialize datetime objects to ISO format strings.

• model_post_init –

  Ensure timestamp fields are always present in dict for compatibility.

• to_dict –

  Convert model instance to dictionary with relationship support.

__repr__() -> str

serialize_datetimes(value: datetime | None) -> str | None

model_post_init(__context: Any) -> None

to_dict(
    include_relationships: bool = False, relationships: list[str] | None = None
) -> dict[str, Any]

Bases: BaseModel

Discord guild/server model with metadata and relationships.

Represents a Discord guild (server) with associated metadata and relationships to other entities like snippets, cases, reminders, etc.

Attributes:

• id (int) –

  Discord guild ID (primary key).

• guild_joined_at ((datetime, optional)) –

  When the bot joined this guild.

• case_count (int) –

  Running count of moderation cases for this guild.

Methods:

• __repr__ –

  Return string representation showing guild ID.

• serialize_datetimes –

  Serialize datetime objects to ISO format strings.

• model_post_init –

  Ensure timestamp fields are always present in dict for compatibility.

• to_dict –

  Convert model instance to dictionary with relationship support.

__repr__() -> str

serialize_datetimes(value: datetime | None) -> str | None

model_post_init(__context: Any) -> None

to_dict(
    include_relationships: bool = False, relationships: list[str] | None = None
) -> dict[str, Any]

Bases: BaseModel

Guild-specific configuration settings.

Stores configuration options and settings for each Discord guild, controlling bot behavior and feature availability.

Attributes:

• id (int) –

  Discord guild ID (primary key, foreign key to guild table).

• prefix (str) –

  Command prefix for this guild.

• mod_log_id ((int, optional)) –

  Channel ID for moderation logs.

• audit_log_id ((int, optional)) –

  Channel ID for audit logs.

• join_log_id ((int, optional)) –

  Channel ID for member join/leave logs.

• private_log_id ((int, optional)) –

  Channel ID for private moderation logs.

• report_log_id ((int, optional)) –

  Channel ID for user reports.

• dev_log_id ((int, optional)) –

  Channel ID for development/debug logs.

• jail_channel_id ((int, optional)) –

  Channel ID for jailed users.

• jail_role_id ((int, optional)) –

  Role ID assigned to jailed users.

• onboarding_completed (bool) –

  Whether guild onboarding setup is complete.

• onboarding_stage ((OnboardingStage, optional)) –

  Current stage of guild onboarding process.

Methods:

• __repr__ –

  Return string representation showing guild ID and prefix.

• serialize_datetimes –

  Serialize datetime objects to ISO format strings.

• model_post_init –

  Ensure timestamp fields are always present in dict for compatibility.

• to_dict –

  Convert model instance to dictionary with relationship support.

__repr__() -> str

serialize_datetimes(value: datetime | None) -> str | None

model_post_init(__context: Any) -> None

to_dict(
    include_relationships: bool = False, relationships: list[str] | None = None
) -> dict[str, Any]

Bases: SQLModel

User experience and leveling data.

Tracks user experience points and level progression within guilds.

Attributes:

• member_id (int) –

  Discord user ID (primary key).

• guild_id (int) –

  Guild ID (primary key, foreign key to guild table).

• xp (float) –

  Experience points accumulated by the user.

• level (int) –

  Current level derived from XP.

• blacklisted (bool) –

  Whether user is blacklisted from gaining XP.

• last_message (datetime) –

  Timestamp of last message for XP cooldown.

Methods:

• __repr__ –

  Return string representation showing member, guild, level and XP.

__repr__() -> str

Bases: BaseModel

Assigns permission ranks to Discord roles in each server.

Maps Discord roles to permission ranks, granting all members with that role the associated permission level.

Attributes:

• id ((int, optional)) –

  Auto-generated primary key.

• guild_id (int) –

  Guild ID where this assignment exists.

• permission_rank_id (int) –

  ID of the permission rank being assigned.

• role_id (int) –

  Discord role ID receiving the permission rank.

Methods:

• __repr__ –

  Return string representation showing guild, role and rank assignment.

• serialize_datetimes –

  Serialize datetime objects to ISO format strings.

• model_post_init –

  Ensure timestamp fields are always present in dict for compatibility.

• to_dict –

  Convert model instance to dictionary with relationship support.

__repr__() -> str

serialize_datetimes(value: datetime | None) -> str | None

model_post_init(__context: Any) -> None

to_dict(
    include_relationships: bool = False, relationships: list[str] | None = None
) -> dict[str, Any]

Bases: BaseModel

Assigns permission requirements to specific commands.

Allows guilds to customize the permission rank required for specific commands, overriding default permission requirements.

Attributes:

• id ((int, optional)) –

  Auto-generated primary key.

• guild_id (int) –

  Guild ID where this command permission is set.

• command_name (str) –

  Name of the command.

• required_rank (int) –

  Minimum permission rank required (0-10).

• description ((str, optional)) –

  Optional description of the command.

Methods:

• __repr__ –

  Return string representation showing guild, command and rank requirement.

• serialize_datetimes –

  Serialize datetime objects to ISO format strings.

• model_post_init –

  Ensure timestamp fields are always present in dict for compatibility.

• to_dict –

  Convert model instance to dictionary with relationship support.

__repr__() -> str

serialize_datetimes(value: datetime | None) -> str | None

model_post_init(__context: Any) -> None

to_dict(
    include_relationships: bool = False, relationships: list[str] | None = None
) -> dict[str, Any]

Bases: BaseModel

Permission ranks for guild role-based access control.

Defines hierarchical permission ranks that can be assigned to roles within a guild, controlling access to bot commands and features.

Attributes:

• id ((int, optional)) –

  Auto-generated primary key.

• guild_id (int) –

  Guild ID this permission rank belongs to.

• rank (int) –

  Numeric permission rank (0-100, higher = more permissions).

• name (str) –

  Human-readable name for the permission rank.

• description ((str, optional)) –

  Optional description of the rank's purpose and permissions.

Methods:

• __repr__ –

  Return string representation showing guild, rank and name.

• serialize_datetimes –

  Serialize datetime objects to ISO format strings.

• model_post_init –

  Ensure timestamp fields are always present in dict for compatibility.

• to_dict –

  Convert model instance to dictionary with relationship support.

__repr__() -> str

serialize_datetimes(value: datetime | None) -> str | None

model_post_init(__context: Any) -> None

to_dict(
    include_relationships: bool = False, relationships: list[str] | None = None
) -> dict[str, Any]

Bases: SQLModel

Scheduled reminders for users.

Represents reminders that users can set to be notified about at a specific time.

Attributes:

• id ((int, optional)) –

  Auto-generated primary key.

• reminder_content (str) –

  Content of the reminder message.

• reminder_expires_at (datetime) –

  When the reminder should trigger.

• reminder_channel_id (int) –

  Channel ID where reminder should be sent.

• reminder_user_id (int) –

  Discord user ID who set the reminder.

• reminder_sent (bool) –

  Whether the reminder has been sent.

• guild_id (int) –

  Guild ID where the reminder was set.

Methods:

• __repr__ –

  Return string representation showing guild, user and expiration.

__repr__() -> str

Bases: SQLModel

Custom command snippets for guilds.

Represents user-defined text snippets that can be triggered by custom commands within a Discord guild.

Attributes:

• id ((int, optional)) –

  Auto-generated primary key.

• snippet_name (str) –

  Name of the snippet command.

• snippet_content ((str, optional)) –

  Content/text of the snippet.

• snippet_user_id (int) –

  Discord user ID who created the snippet.

• guild_id (int) –

  ID of the guild this snippet belongs to.

• uses (int) –

  Number of times this snippet has been used.

• locked (bool) –

  Whether the snippet is locked (prevents editing/deletion).

• alias ((str, optional)) –

  Optional alias name for the snippet.

Methods:

• __repr__ –

  Return string representation showing ID and name.

__repr__() -> str

Bases: SQLModel

Starboard configuration for guilds.

Defines the starboard channel and emoji settings for a guild, allowing messages to be highlighted when they receive enough reactions.

Attributes:

• id (int) –

  Guild ID (primary key, foreign key to guild table).

• starboard_channel_id (int) –

  Discord channel ID where starred messages are posted.

• starboard_emoji (str) –

  Emoji used for starring messages.

• starboard_threshold (int) –

  Number of reactions needed to appear on starboard.

Methods:

• __repr__ –

  Return string representation showing guild and channel.

__repr__() -> str

Bases: SQLModel

Messages that have been starred on the starboard.

Tracks individual messages that have been posted to the starboard along with their star counts and original message information.

Attributes:

• id (int) –

  Original Discord message ID (primary key).

• message_content (str) –

  Content of the original message.

• message_expires_at (datetime) –

  When the starboard entry expires.

• message_channel_id (int) –

  Original channel ID where message was posted.

• message_user_id (int) –

  Discord user ID of the message author.

• message_guild_id (int) –

  Guild ID where the starboard is configured.

• star_count (int) –

  Current number of star reactions.

• starboard_message_id (int) –

  ID of the starboard message in the starboard channel.

Methods:

• __repr__ –

  Return string representation showing guild, original message and user.

__repr__() -> str