snippet ¶

Code snippet storage and management controller.

This controller manages reusable code snippets for Discord guilds, allowing users to save and retrieve frequently used code blocks and text templates.

Classes:

SnippetController –

Clean Snippet controller using the new BaseController pattern.

Classes¶

SnippetController ¶

Python

SnippetController(db: DatabaseService | None = None)

Bases: BaseController[Snippet]

Clean Snippet controller using the new BaseController pattern.

Initialize the snippet controller.

Parameters:

db (DatabaseService | None, default: None ) –

The database service instance. If None, uses the default service.

Returned by:

controllers Classes DatabaseCoordinator Attributes snippet

Methods:

get_snippet_by_id –

Get a snippet by its ID.
get_snippet_by_name_and_guild –

Get a snippet by name and guild.
get_snippets_by_guild –

Get all snippets in a guild.
create_snippet –

Create a new snippet.
update_snippet –

Update a snippet by ID.
update_snippet_by_id –

Update a snippet by ID - alias for update_snippet.
delete_snippet –

Delete a snippet by ID.
delete_snippet_by_id –

Delete a snippet by ID - alias for delete_snippet.
get_snippets_by_creator –

Get all snippets created by a specific user in a guild.
search_snippets –

Search snippets by name or content in a guild.
create –

Create a new record.
get_snippet_count_by_guild –

Get the total number of snippets in a guild.
get_by_id –

Get a record by ID.
find_many –

Find many snippets with optional filters - alias for find_all.
update_by_id –

Update a record by ID.
get_snippet_by_name_and_guild_id –

Get a snippet by name and guild ID.
delete_by_id –

Delete a record by ID.
create_snippet_alias –

Create a snippet alias.
exists –

Check if a record exists.
find_one –

Find one record.
find_all –

Find all records with performance optimizations.
get_snippet_count_by_creator –

Get the number of snippets created by a user in a guild.
toggle_snippet_lock –

Toggle the locked status of a snippet.
find_all_with_options –

Find all records with relationship loading options.
toggle_snippet_lock_by_id –

Toggle the locked status of a snippet by ID - alias for toggle_snippet_lock.
count –

Count records.
increment_snippet_uses –

Increment the usage count of a snippet.
get_all –

Get all records (alias for find_all without pagination).
get_popular_snippets –

Get the most popular snippets in a guild by usage count.
execute_query –

Execute a custom query.
get_snippets_by_alias –

Get snippets by alias in a guild.
find_with_json_query –

Find records using JSON column queries.
get_all_aliases –

Get all aliases in a guild.
find_with_array_contains –

Find records where array column contains value.
get_all_snippets_by_guild_id –

Get all snippets in a guild - alias for get_snippets_by_guild.
find_with_full_text_search –

Find records using full-text search.
paginate –

Paginate records with metadata.
find_paginated –

Find paginated records with relationship loading.
bulk_create –

Create multiple records in bulk.
bulk_update –

Update multiple records in bulk.
bulk_delete –

Delete multiple records in bulk.
update_where –

Update records matching filters.
delete_where –

Delete records matching filters.
bulk_upsert_with_conflict_resolution –

Bulk upsert with conflict resolution.
with_session –

Execute operation within a session context.
with_transaction –

Execute operation within a transaction context.
execute_transaction –

Execute a callback within a transaction.
get_table_statistics –

Get comprehensive table statistics.
explain_query_performance –

Explain query performance with optional analysis.
upsert_by_field –

Upsert a record by a specific field.
upsert_by_id –

Upsert a record by ID.
get_or_create_by_field –

Get existing record or create new one by field.
get_or_create –

Get existing record or create new one.
upsert –

Upsert a record.

Attributes:

db_service (DatabaseService) –

Database service property for test compatibility.
model_class (type[ModelT]) –

Model class property for test compatibility.

Attributes¶

db_service `property` ¶

Python

db_service: DatabaseService

Database service property for test compatibility.

Returns:

DatabaseService –

The database service instance.

model_class `property` ¶

Python

model_class: type[ModelT]

Model class property for test compatibility.

Returns:

type[ModelT] –

The SQLModel class.

Functions¶

get_snippet_by_id `async` ¶

Python

get_snippet_by_id(snippet_id: int) -> Snippet | None

Get a snippet by its ID.

Returns:

Snippet | None –

The snippet if found, None otherwise.

get_snippet_by_name_and_guild `async` ¶

Python

get_snippet_by_name_and_guild(snippet_name: str, guild_id: int) -> Snippet | None

Get a snippet by name and guild.

Returns:

Snippet | None –

The snippet if found, None otherwise.

get_snippets_by_guild `async` ¶

Python

get_snippets_by_guild(guild_id: int) -> list[Snippet]

Get all snippets in a guild.

Returns:

list[Snippet] –

List of all snippets for the guild.

create_snippet `async` ¶

Python

create_snippet(
    snippet_name: str,
    snippet_content: str,
    guild_id: int,
    snippet_user_id: int,
    alias: str | None = None,
    **kwargs: Any,
) -> Snippet

Create a new snippet.

Returns:

Snippet –

The newly created snippet.

update_snippet `async` ¶

Python

update_snippet(snippet_id: int, **kwargs: Any) -> Snippet | None

Update a snippet by ID.

Returns:

Snippet | None –

The updated snippet, or None if not found.

_get_pagination ¶

Python

_get_pagination() -> PaginationController[ModelT]

Get or create pagination controller.

Returns:

PaginationController[ModelT] –

The pagination controller instance.

update_snippet_by_id `async` ¶

Python

update_snippet_by_id(snippet_id: int, **kwargs: Any) -> Snippet | None

Update a snippet by ID - alias for update_snippet.

Returns:

Snippet | None –

The updated snippet, or None if not found.

_get_bulk ¶

Python

_get_bulk() -> BulkOperationsController[ModelT]

Get or create bulk operations controller.

Returns:

BulkOperationsController[ModelT] –

The bulk operations controller instance.

delete_snippet `async` ¶

Python

delete_snippet(snippet_id: int) -> bool

Delete a snippet by ID.

Returns:

bool –

True if deleted successfully, False otherwise.

_get_transaction ¶

Python

_get_transaction() -> TransactionController[ModelT]

Get or create transaction controller.

Returns:

TransactionController[ModelT] –

The transaction controller instance.

delete_snippet_by_id `async` ¶

Python

delete_snippet_by_id(snippet_id: int) -> bool

Delete a snippet by ID - alias for delete_snippet.

Returns:

bool –

True if deleted successfully, False otherwise.

_get_performance ¶

Python

_get_performance() -> PerformanceController[ModelT]

Get or create performance controller.

Returns:

PerformanceController[ModelT] –

The performance controller instance.

get_snippets_by_creator `async` ¶

Python

get_snippets_by_creator(creator_id: int, guild_id: int) -> list[Snippet]

Get all snippets created by a specific user in a guild.

Returns:

list[Snippet] –

List of snippets created by the user.

_get_upsert ¶

Python

_get_upsert() -> UpsertController[ModelT]

Get or create upsert controller.

Returns:

UpsertController[ModelT] –

The upsert controller instance.

search_snippets `async` ¶

Python

search_snippets(guild_id: int, search_term: str) -> list[Snippet]

Search snippets by name or content in a guild.

Returns:

list[Snippet] –

List of snippets matching the search term.

create `async` ¶

Python

create(**kwargs: Any) -> ModelT

Create a new record.

Returns:

ModelT –

The newly created record.

get_snippet_count_by_guild `async` ¶

Python

get_snippet_count_by_guild(guild_id: int) -> int

Get the total number of snippets in a guild.

Returns:

int –

The total count of snippets in the guild.

get_by_id `async` ¶

Python

get_by_id(record_id: Any) -> ModelT | None

Get a record by ID.

Returns:

ModelT | None –

The record if found, None otherwise.

find_many `async` ¶

Python

find_many(**filters: Any) -> list[Snippet]

Find many snippets with optional filters - alias for find_all.

Returns:

list[Snippet] –

List of snippets matching the filters.

update_by_id `async` ¶

Python

update_by_id(record_id: Any, **values: Any) -> ModelT | None

Update a record by ID.

Returns:

ModelT | None –

The updated record, or None if not found.

get_snippet_by_name_and_guild_id `async` ¶

Python

get_snippet_by_name_and_guild_id(name: str, guild_id: int) -> Snippet | None

Get a snippet by name and guild ID.

Returns:

Snippet | None –

The snippet if found, None otherwise.

delete_by_id `async` ¶

Python

delete_by_id(record_id: Any) -> bool

Delete a record by ID.

Returns:

bool –

True if deleted successfully, False otherwise.

create_snippet_alias `async` ¶

Python

create_snippet_alias(original_name: str, alias_name: str, guild_id: int) -> Snippet

Create a snippet alias.

Returns:

Snippet –

The newly created alias snippet.

Raises:

ValueError –

If the original snippet is not found.

exists `async` ¶

Python

exists(filters: Any) -> bool

Check if a record exists.

Returns:

bool –

True if record exists, False otherwise.

find_one `async` ¶

Python

find_one(filters: Any | None = None, order_by: Any | None = None) -> ModelT | None

Find one record.

Returns:

ModelT | None –

The found record, or None if not found.

find_all `async` ¶

Python

find_all(
    filters: Any | None = None,
    order_by: Any | None = None,
    limit: int | None = None,
    offset: int | None = None,
) -> list[ModelT]

Find all records with performance optimizations.

Returns:

list[ModelT] –

List of found records.

get_snippet_count_by_creator `async` ¶

Python

get_snippet_count_by_creator(creator_id: int, guild_id: int) -> int

Get the number of snippets created by a user in a guild.

Returns:

int –

The count of snippets created by the user.

toggle_snippet_lock `async` ¶

Python

toggle_snippet_lock(snippet_id: int) -> Snippet | None

Toggle the locked status of a snippet.

Returns:

Snippet | None –

The updated snippet, or None if not found.

find_all_with_options `async` ¶

Python

find_all_with_options(
    filters: Any | None = None,
    order_by: Any | None = None,
    limit: int | None = None,
    offset: int | None = None,
    load_relationships: list[str] | None = None,
) -> list[ModelT]

Find all records with relationship loading options.

Returns:

list[ModelT] –

List of found records with loaded relationships.

toggle_snippet_lock_by_id `async` ¶

Python

toggle_snippet_lock_by_id(snippet_id: int) -> Snippet | None

Toggle the locked status of a snippet by ID - alias for toggle_snippet_lock.

Returns:

Snippet | None –

The updated snippet, or None if not found.

count `async` ¶

Python

count(filters: Any | None = None) -> int

Count records.

Returns:

int –

The count of matching records.

increment_snippet_uses `async` ¶

Python

increment_snippet_uses(snippet_id: int) -> Snippet | None

Increment the usage count of a snippet.

Returns:

Snippet | None –

The updated snippet, or None if not found.

get_all `async` ¶

Python

get_all(filters: Any | None = None, order_by: Any | None = None) -> list[ModelT]

Get all records (alias for find_all without pagination).

Returns:

list[ModelT] –

List of all matching records.

get_popular_snippets `async` ¶

Python

get_popular_snippets(guild_id: int, limit: int = 10) -> list[Snippet]

Get the most popular snippets in a guild by usage count.

Returns:

list[Snippet] –

List of snippets sorted by usage count (most popular first).

execute_query `async` ¶

Python

execute_query(query: Any) -> Any

Execute a custom query.

Returns:

Any –

The query result.

get_snippets_by_alias `async` ¶

Python

get_snippets_by_alias(alias: str, guild_id: int) -> list[Snippet]

Get snippets by alias in a guild.

Returns:

list[Snippet] –

List of snippets with the specified alias.

find_with_json_query `async` ¶

Python

find_with_json_query(
    json_column: str, json_path: str, value: Any, filters: Any | None = None
) -> list[ModelT]

Find records using JSON column queries.

Returns:

list[ModelT] –

List of records matching the JSON query.

get_all_aliases `async` ¶

Python

get_all_aliases(guild_id: int) -> list[Snippet]

Get all aliases in a guild.

Returns:

list[Snippet] –

List of all alias snippets.

find_with_array_contains `async` ¶

Python

find_with_array_contains(
    array_column: str, value: Any, filters: Any | None = None
) -> list[ModelT]

Find records where array column contains value.

Returns:

list[ModelT] –

List of records with matching array values.

get_all_snippets_by_guild_id `async` ¶

Python

get_all_snippets_by_guild_id(guild_id: int) -> list[Snippet]

Get all snippets in a guild - alias for get_snippets_by_guild.

Returns:

list[Snippet] –

List of all snippets for the guild.

find_with_full_text_search `async` ¶

Python

find_with_full_text_search(
    search_columns: list[str], search_term: str, filters: Any | None = None
) -> list[ModelT]

Find records using full-text search.

Returns:

list[ModelT] –

List of records matching the search term.

paginate `async` ¶

Python

paginate(
    page: int = 1,
    per_page: int = 20,
    filters: Any | None = None,
    order_by: Any | None = None,
) -> PaginationResult[ModelT]

Paginate records with metadata.

Returns:

PaginationResult[ModelT] –

Pagination result with items, total, and page info.

find_paginated `async` ¶

Python

find_paginated(
    page: int = 1,
    per_page: int = 20,
    filters: Any | None = None,
    order_by: Any | None = None,
    load_relationships: list[str] | None = None,
) -> PaginationResult[ModelT]

Find paginated records with relationship loading.

Returns:

PaginationResult[ModelT] –

Pagination result with items and relationships loaded.

bulk_create `async` ¶

Python

bulk_create(items: list[dict[str, Any]]) -> list[ModelT]

Create multiple records in bulk.

Returns:

list[ModelT] –

List of created records.

bulk_update `async` ¶

Python

bulk_update(updates: list[tuple[Any, dict[str, Any]]]) -> int

Update multiple records in bulk.

Returns:

int –

Number of records updated.

bulk_delete `async` ¶

Python

bulk_delete(record_ids: list[Any]) -> int

Delete multiple records in bulk.

Returns:

int –

Number of records deleted.

update_where `async` ¶

Python

update_where(filters: Any, values: dict[str, Any]) -> int

Update records matching filters.

Returns:

int –

Number of records updated.

delete_where `async` ¶

Python

delete_where(filters: Any) -> int

Delete records matching filters.

Returns:

int –

Number of records deleted.

bulk_upsert_with_conflict_resolution `async` ¶

Python

bulk_upsert_with_conflict_resolution(
    items: list[dict[str, Any]],
    conflict_columns: list[str],
    update_columns: list[str] | None = None,
) -> list[ModelT]

Bulk upsert with conflict resolution.

Returns:

list[ModelT] –

List of upserted records.

with_session `async` ¶

Python

with_session[R](operation: Callable[[Any], Awaitable[R]]) -> R

Execute operation within a session context.

Returns:

R –

The result of the operation.

with_transaction `async` ¶

Python

with_transaction[R](operation: Callable[[Any], Awaitable[R]]) -> R

Execute operation within a transaction context.

Returns:

R –

The result of the operation.

execute_transaction `async` ¶

Python

execute_transaction(callback: Callable[[], Any]) -> Any

Execute a callback within a transaction.

Returns:

Any –

The result of the callback.

get_table_statistics `async` ¶

Python

get_table_statistics() -> dict[str, Any]

Get comprehensive table statistics.

Returns:

dict[str, Any] –

Dictionary containing table statistics.

explain_query_performance `async` ¶

Python

explain_query_performance(
    query: Any, analyze: bool = False, buffers: bool = False
) -> dict[str, Any]

Explain query performance with optional analysis.

Returns:

dict[str, Any] –

Dictionary containing query execution plan and statistics.

upsert_by_field `async` ¶

Python

upsert_by_field(
    field_name: str,
    field_value: Any,
    defaults: dict[str, Any] | None = None,
    **kwargs: Any,
) -> tuple[ModelT, bool]

Upsert a record by a specific field.

Returns:

tuple[ModelT, bool] –

Tuple of (record, created) where created is True if new record was created.

upsert_by_id `async` ¶

Python

upsert_by_id(
    record_id: Any, defaults: dict[str, Any] | None = None, **kwargs: Any
) -> tuple[ModelT, bool]

Upsert a record by ID.

Returns:

tuple[ModelT, bool] –

Tuple of (record, created) where created is True if new record was created.

get_or_create_by_field `async` ¶

Python

get_or_create_by_field(
    field_name: str,
    field_value: Any,
    defaults: dict[str, Any] | None = None,
    **kwargs: Any,
) -> tuple[ModelT, bool]

Get existing record or create new one by field.

Returns:

tuple[ModelT, bool] –

Tuple of (record, created) where created is True if new record was created.

get_or_create `async` ¶

Python

get_or_create(
    defaults: dict[str, Any] | None = None, **filters: Any
) -> tuple[ModelT, bool]

Get existing record or create new one.

Returns:

tuple[ModelT, bool] –

Tuple of (record, created) where created is True if new record was created.

upsert `async` ¶

Python

upsert(
    filters: dict[str, Any], defaults: dict[str, Any] | None = None, **kwargs: Any
) -> tuple[ModelT, bool]

Upsert a record.

Returns:

tuple[ModelT, bool] –

Tuple of (record, created) where created is True if new record was created.

snippet ¶

Classes¶

SnippetController ¶

Attributes¶

db_service property ¶

model_class property ¶

Functions¶

get_snippet_by_id async ¶

get_snippet_by_name_and_guild async ¶

get_snippets_by_guild async ¶

create_snippet async ¶

update_snippet async ¶

_get_pagination ¶

update_snippet_by_id async ¶

_get_bulk ¶

delete_snippet async ¶

_get_transaction ¶

delete_snippet_by_id async ¶

_get_performance ¶

get_snippets_by_creator async ¶

_get_upsert ¶

search_snippets async ¶

create async ¶

get_snippet_count_by_guild async ¶

get_by_id async ¶

find_many async ¶

update_by_id async ¶

get_snippet_by_name_and_guild_id async ¶

delete_by_id async ¶

create_snippet_alias async ¶

exists async ¶

find_one async ¶

find_all async ¶

get_snippet_count_by_creator async ¶

toggle_snippet_lock async ¶

find_all_with_options async ¶

toggle_snippet_lock_by_id async ¶

count async ¶

increment_snippet_uses async ¶

get_all async ¶

get_popular_snippets async ¶

execute_query async ¶

get_snippets_by_alias async ¶

find_with_json_query async ¶

get_all_aliases async ¶

find_with_array_contains async ¶

get_all_snippets_by_guild_id async ¶

find_with_full_text_search async ¶

paginate async ¶

find_paginated async ¶

bulk_create async ¶

bulk_update async ¶

bulk_delete async ¶

update_where async ¶

delete_where async ¶

bulk_upsert_with_conflict_resolution async ¶

with_session async ¶

with_transaction async ¶

execute_transaction async ¶

get_table_statistics async ¶

explain_query_performance async ¶

upsert_by_field async ¶

upsert_by_id async ¶

get_or_create_by_field async ¶

get_or_create async ¶

upsert async ¶

db_service `property` ¶

model_class `property` ¶

get_snippet_by_id `async` ¶

get_snippet_by_name_and_guild `async` ¶

get_snippets_by_guild `async` ¶

create_snippet `async` ¶

update_snippet `async` ¶

update_snippet_by_id `async` ¶

delete_snippet `async` ¶

delete_snippet_by_id `async` ¶

get_snippets_by_creator `async` ¶

search_snippets `async` ¶

create `async` ¶

get_snippet_count_by_guild `async` ¶

get_by_id `async` ¶

find_many `async` ¶

update_by_id `async` ¶

get_snippet_by_name_and_guild_id `async` ¶

delete_by_id `async` ¶

create_snippet_alias `async` ¶

exists `async` ¶

find_one `async` ¶

find_all `async` ¶

get_snippet_count_by_creator `async` ¶

toggle_snippet_lock `async` ¶

find_all_with_options `async` ¶

toggle_snippet_lock_by_id `async` ¶

count `async` ¶

increment_snippet_uses `async` ¶

get_all `async` ¶

get_popular_snippets `async` ¶

execute_query `async` ¶

get_snippets_by_alias `async` ¶

find_with_json_query `async` ¶

get_all_aliases `async` ¶

find_with_array_contains `async` ¶

get_all_snippets_by_guild_id `async` ¶

find_with_full_text_search `async` ¶

paginate `async` ¶

find_paginated `async` ¶

bulk_create `async` ¶

bulk_update `async` ¶

bulk_delete `async` ¶

update_where `async` ¶

delete_where `async` ¶

bulk_upsert_with_conflict_resolution `async` ¶

with_session `async` ¶

with_transaction `async` ¶

execute_transaction `async` ¶

get_table_statistics `async` ¶

explain_query_performance `async` ¶

upsert_by_field `async` ¶

upsert_by_id `async` ¶

get_or_create_by_field `async` ¶

get_or_create `async` ¶

upsert `async` ¶