cases ¶

Moderation case management and viewing commands.

This module provides comprehensive case management functionality for Discord moderation, including viewing, modifying, and managing moderation cases with interactive menus and detailed information display.

Classes:

UserLike –

Protocol for objects that behave like Discord users.
MockUser –

A mock user object for cases where we can't find the real user.
Cases –

Discord cog for moderation case management and viewing.

Functions:

setup –

Set up the Cases cog.

Classes¶

UserLike ¶

Bases: Protocol

Protocol for objects that behave like Discord users.

Attributes:

id (int) –

The user's unique identifier.
name (str) –

The user's display name.
avatar (Any) –

The user's avatar.

Methods:

__str__ –

Return a string representation of the user.

Functions¶

str ¶

Python

__str__() -> str

Return a string representation of the user.

Returns:

str –

String representation of the user.

MockUser ¶

Python

MockUser(user_id: int)

A mock user object for cases where we can't find the real user.

Initialize a mock user object.

Parameters:

user_id (int) –

The ID of the user this mock represents.

Returned by:

cases Classes Cases Functions
- _resolve_moderator
- _resolve_user

Used by:

cases Classes Cases Functions
- _create_case_fields
- _send_case_embed

Methods:

__str__ –

Return a string representation of the mock user.

Functions¶

str ¶

Python

__str__() -> str

Return a string representation of the mock user.

Returns:

str –

String representation in the format 'Unknown User#0000'.

Cases ¶

Python

Cases(bot: Tux)

Bases: ModerationCogBase

Discord cog for moderation case management and viewing.

This cog provides comprehensive case management functionality including viewing, modifying, and managing moderation cases with interactive menus.

Initialize the Cases cog.

Parameters:

bot (Tux) –

The bot instance to attach this cog to.

Methods:

moderate_user –

Execute moderation action using the service architecture.
is_jailed –

Check if a user is jailed.
is_pollbanned –

Check if a user is poll banned.
cases –

View all moderation cases in the server.
is_snippetbanned –

Check if a user is snippet banned.
cases_view –

View a specific moderation case by its number.
cases_search –

Search/filter moderation cases by criteria.
get_config –

Get a configuration value from CONFIG with support for nested keys.
cases_modify –

Modify a moderation case.
__repr__ –

Return a string representation of the cog instance.
unload_if_missing_config –

Check if required configuration is missing and log warning.

Attributes:

db (DatabaseCoordinator) –

Get the database coordinator for accessing database controllers.

Attributes¶

db `property` ¶

Python

db: DatabaseCoordinator

Get the database coordinator for accessing database controllers.

Returns:

DatabaseCoordinator –

Coordinator providing access to all database controllers.

Examples:

Python Console Session

>>> await self.db.guild_config.get_guild_config(guild_id)
>>> await self.db.cases.create_case(...)

Notes

This property provides convenient access to database operations without needing to access self.bot.db directly.

Functions¶

moderate_user `async` ¶

Python

moderate_user(
    ctx: Context[Tux],
    case_type: CaseType,
    user: Member | User,
    reason: str,
    silent: bool = False,
    dm_action: str | None = None,
    actions: Sequence[tuple[Any, type[Any]]] | None = None,
    duration: int | None = None,
    **kwargs: Any,
) -> None

Execute moderation action using the service architecture.

Parameters:

ctx (Context[Tux]) –

Command context
case_type (CaseType) –

Type of moderation action
user (Member | User) –

Target user
reason (str) –

Reason for the action
silent (bool, default: False ) –

Whether to suppress DM to user, by default False
dm_action (str | None, default: None ) –

Custom DM action description, by default None
actions (Sequence[tuple[Any, type[Any]]] | None, default: None ) –

Discord API actions to execute, by default None
duration (int | None, default: None ) –

Duration in seconds for temporary actions, by default None
**kwargs (Any, default: {} ) –

Additional case data

_setup_command_usage ¶

Python

_setup_command_usage() -> None

Generate usage strings for all commands in this cog that lack explicit usage.

The generated usage follows the pattern: <qualified_name> <param tokens>

Where: - Required parameters are denoted as <name: Type> - Optional parameters are denoted as [name: Type] - The prefix is intentionally omitted (provided by ctx.prefix)

Examples:

ban <member: Member> [reason: str] config set <key: str> <value: str>

Notes

Respects explicit usage strings if already set on a command. Errors during generation are logged but don't prevent cog loading.

is_jailed `async` ¶

Python

is_jailed(guild_id: int, user_id: int) -> bool

Check if a user is jailed.

Parameters:

guild_id (int) –

Guild ID to check
user_id (int) –

User ID to check

Returns:

bool –

True if user is jailed, False otherwise

_generate_usage ¶

Python

_generate_usage(command: Command[Any, ..., Any]) -> str

Generate a usage string with support for flags and positional parameters.

This method inspects the command's callback signature to detect: - FlagConverter parameters (e.g., --flag value) - Positional parameters (e.g., <required> or [optional])

Parameters:

command (Command) –

The command to generate usage for.

Returns:

str –

Generated usage string, or qualified command name as fallback.

Notes

Delegates to shared usage generator for consistency across all cogs. Falls back gracefully to command name if generation fails.

is_pollbanned `async` ¶

Python

is_pollbanned(guild_id: int, user_id: int) -> bool

Check if a user is poll banned.

Parameters:

guild_id (int) –

Guild ID to check
user_id (int) –

User ID to check

Returns:

bool –

True if user is poll banned, False otherwise

cases `async` ¶

Python

cases(ctx: Context[Tux], case_number: int | None = None) -> None

View all moderation cases in the server.

Use subcommands to view specific cases or filter by criteria.

is_snippetbanned `async` ¶

Python

is_snippetbanned(guild_id: int, user_id: int) -> bool

Check if a user is snippet banned.

Parameters:

guild_id (int) –

Guild ID to check
user_id (int) –

User ID to check

Returns:

bool –

True if user is snippet banned, False otherwise

cases_view `async` ¶

Python

cases_view(ctx: Context[Tux], case_number: int) -> None

View a specific moderation case by its number.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
case_number (int) –

The case number to view (e.g., 123).

cases_search `async` ¶

Python

cases_search(ctx: Context[Tux], *, flags: CasesViewFlags) -> None

Search/filter moderation cases by criteria.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
flags (CasesViewFlags) –

Filter criteria (--type, --user, --moderator).

get_config ¶

Python

get_config(key: str, default: Any = None) -> Any

Get a configuration value from CONFIG with support for nested keys.

Parameters:

key (str) –

The configuration key to retrieve. Supports dot notation for nested values (e.g., "BOT_INFO.BOT_NAME").
default (Any, default: None ) –

Default value to return if key is not found, by default None.

Returns:

Any –

The configuration value or default if not found.

Examples:

Python Console Session

>>> self.get_config("BOT_INFO.BOT_NAME")
'Tux'
>>> self.get_config("MISSING_KEY", "fallback")
'fallback'

Notes

Errors during retrieval are logged but don't raise exceptions. Returns the default value on any error.

cases_modify `async` ¶

Python

cases_modify(ctx: Context[Tux], case_number: int, *, flags: CaseModifyFlags) -> None

Modify a moderation case.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
case_number (int) –

The case number to modify.
flags (CaseModifyFlags) –

Modification options (--status, --reason).

repr ¶

Python

__repr__() -> str

Return a string representation of the cog instance.

Returns:

str –

String representation in format <CogName bot=BotUser>.

_has_valid_changes ¶

Python

_has_valid_changes(case: Case, flags: CaseModifyFlags) -> bool

Check if the modification flags contain valid changes.

Parameters:

case (Case) –

The case to check against.
flags (CaseModifyFlags) –

The modification flags.

Returns:

bool –

True if valid changes are present, False otherwise.

unload_if_missing_config ¶

Python

unload_if_missing_config(condition: bool, config_name: str) -> bool

Check if required configuration is missing and log warning.

This allows cogs to detect missing configuration at load time and return early from init to prevent partial initialization.

Parameters:

condition (bool) –

True if config is missing (should unload), False otherwise.
config_name (str) –

Name of the missing configuration for logging purposes.

Returns:

bool –

True if config is missing (caller should return early), False if config is present.

Examples:

Python Console Session

>>> def __init__(self, bot: Tux):
...     super().__init__(bot)
...     if self.unload_if_missing_config(not CONFIG.GITHUB_TOKEN, "GITHUB_TOKEN"):
...         return  # Exit early, cog will be partially loaded but won't register commands
...     self.github_client = GitHubClient()

Notes

When this returns True, the cog's init should return early to avoid initializing services that depend on the missing config. The cog will be loaded but commands won't be registered properly, preventing runtime errors.

For complete cog unloading, the bot owner should remove the cog from the modules directory or use the reload system to unload it programmatically.

_view_all_cases `async` ¶

Python

_view_all_cases(ctx: Context[Tux]) -> None

View all cases in the server.

_view_single_case `async` ¶

Python

_view_single_case(ctx: Context[Tux], case_number: int) -> None

View a single case by its number.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
case_number (int) –

The number of the case to view.

_unload_self `async` ¶

Python

_unload_self(extension_name: str) -> None

Perform the actual cog unload operation.

Parameters:

extension_name (str) –

Full extension name to unload.

Notes

This is called as a background task by unload_if_missing_config(). Errors during unload are logged but don't raise exceptions.

_view_cases_with_flags `async` ¶

Python

_view_cases_with_flags(ctx: Context[Tux], flags: CasesViewFlags) -> None

View cases with the provided flags.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
flags (CasesViewFlags) –

The flags for the command. (type, user, moderator)

_update_case `async` ¶

Python

_update_case(ctx: Context[Tux], case: Case, flags: CaseModifyFlags) -> None

Update a case with the provided flags.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
case (Case) –

The case to update.
flags (CaseModifyFlags) –

The flags for the command. (status, reason)

_update_mod_log_embed `async` ¶

Python

_update_mod_log_embed(ctx: Context[Tux], case: Case) -> None

Update the mod log embed for a modified case.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
case (Case) –

The updated case to reflect in the mod log.

_resolve_user `async` ¶

Python

_resolve_user(user_id: int) -> User | MockUser

Resolve a user ID to a User object or MockUser if not found.

Parameters:

user_id (int) –

The ID of the user to resolve.

Returns:

Union[User, MockUser] –

The resolved user or a mock user if not found.

_resolve_moderator `async` ¶

Python

_resolve_moderator(moderator_id: int) -> User | MockUser

Resolve a moderator ID to a User object or MockUser if not found.

We use a separate function to potentially add admin-specific resolution in the future.

Parameters:

moderator_id (int) –

The ID of the moderator to resolve.

Returns:

Union[User, MockUser] –

The resolved moderator or a mock user if not found.

_send_case_embed `async` ¶

Python

_send_case_embed(
    ctx: Context[Tux],
    case: Case | None,
    action: str,
    reason: str,
    user: User | MockUser,
) -> None

Send an embed response for a case.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
case (Optional[Case]) –

The case to send the response for.
action (str) –

The action being performed on the case.
reason (str) –

The reason for the case.
user (Union[User, MockUser]) –

The target of the case.

_handle_case_list_response `async` ¶

Python

_handle_case_list_response(
    ctx: Context[Tux], cases: list[Case], total_cases: int
) -> None

Handle the response for a case list.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
cases (list[Case]) –

The cases to handle the response for.
total_cases (int) –

The total number of cases.

_create_case_fields `staticmethod` ¶

Python

_create_case_fields(
    moderator: User | MockUser, user: User | MockUser, reason: str
) -> list[tuple[str, str, bool]]

Create the fields for a case.

Parameters:

moderator (Union[User, MockUser]) –

The moderator of the case.
user (Union[User, MockUser]) –

The user of the case.
reason (str) –

The reason for the case.

Returns:

list[tuple[str, str, bool]] –

The fields for the case.

_create_case_list_embed ¶

Python

_create_case_list_embed(
    ctx: Context[Tux], cases: list[Case], total_cases: int
) -> Embed

Create the embed for a case list.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
cases (list[Case]) –

The cases to create the embed for.
total_cases (int) –

The total number of cases.

Returns:

Embed –

The embed for the case list.

Functions¶

setup `async` ¶

Python

setup(bot: Tux) -> None

Set up the Cases cog.

Parameters:

bot (Tux) –

The bot instance to add the cog to.

cases ¶

Classes¶

UserLike ¶

Functions¶

__str__ ¶

MockUser ¶

Functions¶

__str__ ¶

Cases ¶

Attributes¶

db property ¶

Functions¶

moderate_user async ¶

_setup_command_usage ¶

is_jailed async ¶

_generate_usage ¶

is_pollbanned async ¶

cases async ¶

is_snippetbanned async ¶

cases_view async ¶

cases_search async ¶

get_config ¶

cases_modify async ¶

__repr__ ¶

_has_valid_changes ¶

unload_if_missing_config ¶

_view_all_cases async ¶

_view_single_case async ¶

_unload_self async ¶

_view_cases_with_flags async ¶

_update_case async ¶

_update_mod_log_embed async ¶

_resolve_user async ¶

_resolve_moderator async ¶

_send_case_embed async ¶

_handle_case_list_response async ¶

_create_case_fields staticmethod ¶

_create_case_list_embed ¶

Functions¶

setup async ¶

str ¶

str ¶

db `property` ¶

moderate_user `async` ¶

is_jailed `async` ¶

is_pollbanned `async` ¶

cases `async` ¶

is_snippetbanned `async` ¶

cases_view `async` ¶

cases_search `async` ¶

cases_modify `async` ¶

repr ¶

_view_all_cases `async` ¶

_view_single_case `async` ¶

_unload_self `async` ¶

_view_cases_with_flags `async` ¶

_update_case `async` ¶

_update_mod_log_embed `async` ¶

_resolve_user `async` ¶

_resolve_moderator `async` ¶

_send_case_embed `async` ¶

_handle_case_list_response `async` ¶

_create_case_fields `staticmethod` ¶

setup `async` ¶