Skip to content

tux.cogs.snippets.create_snippet

Classes:

Name Description
CreateSnippet

Classes

CreateSnippet(bot: Tux)

Bases: SnippetsBaseCog

Methods:

Name Description
create_snippet

Create a new snippet or an alias.
is_snippetbanned

Check if a user is currently snippet banned in a guild.
check_if_user_has_mod_override

Check if the user invoking the command has moderator permissions (PL >= configured level).
snippet_check

Check if a user is allowed to modify or delete a snippet.
send_snippet_error

Send a standardized snippet error embed.
Source code in tux/cogs/snippets/create_snippet.py
Python
def __init__(self, bot: Tux) -> None:
    super().__init__(bot)
    self.create_snippet.usage = generate_usage(self.create_snippet)

Functions

create_snippet(ctx: commands.Context[Tux], name: str, *, content: str) -> None async

Create a new snippet or an alias.

If the provided content exactly matches the name of an existing snippet, an alias pointing to that snippet will be created instead.

Snippet names must be alphanumeric (allowing dashes) and under a configured length.

Parameters:

Name Type Description Default
ctx Context[Tux]

The context of the command.

 required
name str

The desired name for the new snippet.

 required
content str

The content of the snippet, or the name of a snippet to alias.

 required
Source code in tux/cogs/snippets/create_snippet.py
Python
@commands.command(
    name="createsnippet",
    aliases=["cs"],
)
@commands.guild_only()
async def create_snippet(self, ctx: commands.Context[Tux], name: str, *, content: str) -> None:
    """Create a new snippet or an alias.

    If the provided content exactly matches the name of an existing snippet,
    an alias pointing to that snippet will be created instead.

    Snippet names must be alphanumeric (allowing dashes) and under a configured length.

    Parameters
    ----------
    ctx : commands.Context[Tux]
        The context of the command.
    name : str
        The desired name for the new snippet.
    content : str
        The content of the snippet, or the name of a snippet to alias.
    """
    assert ctx.guild

    # Check permissions (role, ban status)
    can_create, reason = await self.snippet_check(ctx)

    if not can_create:
        await self.send_snippet_error(ctx, description=reason)
        return

    created_at = datetime.now(UTC)
    author_id = ctx.author.id
    guild_id = ctx.guild.id

    # Check if a snippet with this name already exists
    if await self.db.snippet.get_snippet_by_name_and_guild_id(name, guild_id) is not None:
        await self.send_snippet_error(ctx, description="Snippet with this name already exists.")
        return

    # Validate snippet name format and length
    if len(name) > CONST.SNIPPET_MAX_NAME_LENGTH or not re.match(CONST.SNIPPET_ALLOWED_CHARS_REGEX, name):
        await self.send_snippet_error(
            ctx,
            description=f"Snippet name must be alphanumeric (allows dashes only) and less than {CONST.SNIPPET_MAX_NAME_LENGTH} characters.",
        )
        return

    # Check if content matches another snippet name to automatically create an alias
    existing_snippet_for_alias = await self.db.snippet.get_snippet_by_name_and_guild_id(
        content,
        guild_id,
    )

    if existing_snippet_for_alias:
        await self.db.snippet.create_snippet_alias(
            snippet_name=name,
            snippet_alias=content,
            snippet_created_at=created_at,
            snippet_user_id=author_id,
            guild_id=guild_id,
        )

        await ctx.send(
            f"Snippet `{name}` created as an alias pointing to `{content}`.",
            delete_after=CONST.DEFAULT_DELETE_AFTER,
            ephemeral=True,
        )

        logger.info(f"{ctx.author} created snippet '{name}' as an alias to '{content}'.")
        return

    # Create the new snippet
    await self.db.snippet.create_snippet(
        snippet_name=name,
        snippet_content=content,
        snippet_created_at=created_at,
        snippet_user_id=author_id,
        guild_id=guild_id,
    )

    await ctx.send("Snippet created.", delete_after=CONST.DEFAULT_DELETE_AFTER, ephemeral=True)

    logger.info(f"{ctx.author} created snippet '{name}'.")
is_snippetbanned(guild_id: int, user_id: int) -> bool async

Check if a user is currently snippet banned in a guild.

Parameters:

Name Type Description Default
guild_id int

The ID of the guild to check.

 required
user_id int

The ID of the user to check.

 required

Returns:

Type Description
bool

True if the user is snippet banned, False otherwise.
Source code in tux/cogs/snippets/create_snippet.py
Python
"""Create a new snippet or an alias.

If the provided content exactly matches the name of an existing snippet,
an alias pointing to that snippet will be created instead.

Snippet names must be alphanumeric (allowing dashes) and under a configured length.

Parameters
----------
ctx : commands.Context[Tux]
    The context of the command.
name : str
    The desired name for the new snippet.
content : str
    The content of the snippet, or the name of a snippet to alias.
"""
assert ctx.guild

# Check permissions (role, ban status)
can_create, reason = await self.snippet_check(ctx)

if not can_create:
    await self.send_snippet_error(ctx, description=reason)
    return

created_at = datetime.now(UTC)
author_id = ctx.author.id
guild_id = ctx.guild.id

# Check if a snippet with this name already exists
if await self.db.snippet.get_snippet_by_name_and_guild_id(name, guild_id) is not None:
    await self.send_snippet_error(ctx, description="Snippet with this name already exists.")
    return

# Validate snippet name format and length
if len(name) > CONST.SNIPPET_MAX_NAME_LENGTH or not re.match(CONST.SNIPPET_ALLOWED_CHARS_REGEX, name):
    await self.send_snippet_error(
        ctx,
        description=f"Snippet name must be alphanumeric (allows dashes only) and less than {CONST.SNIPPET_MAX_NAME_LENGTH} characters.",
    )
    return

# Check if content matches another snippet name to automatically create an alias
existing_snippet_for_alias = await self.db.snippet.get_snippet_by_name_and_guild_id(
    content,
    guild_id,
_create_snippets_list_embed(ctx: commands.Context[Tux], snippets: list[Snippet], total_snippets: int, search_query: str | None = None) -> discord.Embed

Create an embed for displaying a paginated list of snippets.

Parameters:

Name Type Description Default
ctx Context[Tux]

The context object.

 required
snippets list[Snippet]

The list of snippets for the current page.

 required
total_snippets int

The total number of snippets matching the query.

 required
search_query str | None

The search query used, if any.

 None

Returns:

Type Description
Embed

The generated embed.
Source code in tux/cogs/snippets/create_snippet.py
Python
        if existing_snippet_for_alias:
            await self.db.snippet.create_snippet_alias(
                snippet_name=name,
                snippet_alias=content,
                snippet_created_at=created_at,
                snippet_user_id=author_id,
                guild_id=guild_id,
            )

            await ctx.send(
                f"Snippet `{name}` created as an alias pointing to `{content}`.",
                delete_after=CONST.DEFAULT_DELETE_AFTER,
                ephemeral=True,
            )

            logger.info(f"{ctx.author} created snippet '{name}' as an alias to '{content}'.")
            return

        # Create the new snippet
        await self.db.snippet.create_snippet(
            snippet_name=name,
            snippet_content=content,
            snippet_created_at=created_at,
            snippet_user_id=author_id,
            guild_id=guild_id,
        )

        await ctx.send("Snippet created.", delete_after=CONST.DEFAULT_DELETE_AFTER, ephemeral=True)

        logger.info(f"{ctx.author} created snippet '{name}'.")


async def setup(bot: Tux) -> None:
    await bot.add_cog(CreateSnippet(bot))
check_if_user_has_mod_override(ctx: commands.Context[Tux]) -> bool async

Check if the user invoking the command has moderator permissions (PL >= configured level).

snippet_check(ctx: commands.Context[Tux], snippet_locked: bool = False, snippet_user_id: int = 0) -> tuple[bool, str] async

Check if a user is allowed to modify or delete a snippet.

Checks for moderator override, snippet bans, role restrictions, snippet lock status, and snippet ownership.

Parameters:

Name Type Description Default
ctx Context[Tux]

The context object.

 required
snippet_locked bool

Whether the snippet is locked. Checked only if True. Defaults to False.

 False
snippet_user_id int

The ID of the snippet's author. Checked only if non-zero. Defaults to 0.

 0

Returns:

Type Description
tuple[bool, str]

A tuple containing a boolean indicating permission status and a reason string.
_get_snippet_or_error(ctx: commands.Context[Tux], name: str) -> Snippet | None async

Fetch a snippet by name and guild, sending an error embed if not found.

Parameters:

Name Type Description Default
ctx Context[Tux]

The context object.

 required
name str

The name of the snippet to fetch.

 required

Returns:

Type Description
Snippet | None

The fetched Snippet object, or None if not found.
send_snippet_error(ctx: commands.Context[Tux], description: str) -> None async

Send a standardized snippet error embed.

Parameters:

Name Type Description Default
ctx Context[Tux]

The context object.

 required
description str

The error message description.

 required

Functions