unjail ¶

User unjailing commands for Discord moderation.

This module provides functionality to remove jail status from users, restoring their roles and permissions in Discord servers.

Classes:

Unjail –

Discord cog for removing jail status from users.

Functions:

setup –

Set up the Unjail cog.

Classes¶

Unjail ¶

Python

Unjail(bot: Tux)

Bases: ModerationCogBase

Discord cog for removing jail status from users.

Initialize the Unjail cog.

Parameters:

bot (Tux) –

The bot instance to attach this cog to.

Methods:

get_jail_role –

Get the jail role for the guild.
get_latest_jail_case –

Get the latest jail case for a user.
moderate_user –

Execute moderation action using the service architecture.
restore_roles –

Restore roles to a member with error handling.
is_jailed –

Check if a user is jailed.
is_pollbanned –

Check if a user is poll banned.
unjail –

Remove a member from jail.
is_snippetbanned –

Check if a user is snippet banned.
get_config –

Get a configuration value from CONFIG with support for nested keys.
__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¶

get_jail_role `async` ¶

Python

get_jail_role(guild: Guild) -> Role | None

Get the jail role for the guild.

Parameters:

guild (Guild) –

The guild to get the jail role for.

Returns:

Optional[Role] –

The jail role, or None if not found.

get_latest_jail_case `async` ¶

Python

get_latest_jail_case(guild_id: int, user_id: int) -> Case | None

Get the latest jail case for a user.

Parameters:

guild_id (int) –

The ID of the guild to check in.
user_id (int) –

The ID of the user to check.

Returns:

Optional[Case] –

The latest jail case, or None if not found.

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

restore_roles `async` ¶

Python

restore_roles(
    member: Member, role_ids: list[int], reason: str
) -> tuple[bool, list[Role]]

Restore roles to a member with error handling.

Parameters:

member (Member) –

The member to restore roles to.
role_ids (List[int]) –

The IDs of the roles to restore.
reason (str) –

The reason for restoring the roles.

Returns:

Tuple[bool, List[Role]] –

A tuple containing whether the operation was successful and which roles were restored.

_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

unjail `async` ¶

Python

unjail(ctx: Context[Tux], member: Member, *, flags: UnjailFlags) -> None

Remove a member from jail.

Parameters:

ctx (Context[Tux]) –

The context in which the command is being invoked.
member (Member) –

The member to unjail.
flags (UnjailFlags) –

The flags for the command. (reason: str, silent: bool)

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

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.

repr ¶

Python

__repr__() -> str

Return a string representation of the cog instance.

Returns:

str –

String representation in format <CogName bot=BotUser>.

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.

_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.

Functions¶

setup `async` ¶

Python

setup(bot: Tux) -> None

Set up the Unjail cog.

Parameters:

bot (Tux) –

The bot instance to add the cog to.

unjail ¶

Classes¶

Unjail ¶

Attributes¶

db property ¶

Functions¶

get_jail_role async ¶

get_latest_jail_case async ¶

moderate_user async ¶

restore_roles async ¶

_setup_command_usage ¶

is_jailed async ¶

_generate_usage ¶

is_pollbanned async ¶

unjail async ¶

is_snippetbanned async ¶

get_config ¶

__repr__ ¶

unload_if_missing_config ¶

_unload_self async ¶

Functions¶

setup async ¶

db `property` ¶

get_jail_role `async` ¶

get_latest_jail_case `async` ¶

moderate_user `async` ¶

restore_roles `async` ¶

is_jailed `async` ¶

is_pollbanned `async` ¶

unjail `async` ¶

is_snippetbanned `async` ¶

repr ¶

_unload_self `async` ¶

setup `async` ¶