Making ASS Arguments Definitions

Last updated: October 9, 2026

Making ASS Arguments Definitions

ASS (Argument Searcher of Sophie) is used for parsing command arguments in the Sophie Bot. This guide explains how to create custom argument types.

Core Concepts

CMDFilter

ignores underscores and hyphens when matching literal command names and respects its

ignore_case

setting. It passes a

CommandObject

containing the matched registered literal to later filters, magic filters, ASS argument definitions, and handlers. Each alias keeps its own registered name, including silent variants such as

sfban

. The prefix, mention, and argument text are preserved; mention validation runs before command matching. Regex commands match the raw spelling and retain it, along with the regex match object.

Literal comparison uses

sophie_bot.utils.command_names.normalize_command_name

. Do not normalize command names again in handlers.

Use

sophie_bot.middlewares.args.ArgsMiddleware

for Sophie routers. It rebases text or caption entities to the unchanged argument suffix using Telegram's UTF-16 offsets, including the raw command spelling and any

@mention

. Both dictionary schemas and argument fabrics receive argument-relative entities and the canonical command; dynamic schema callbacks also see the canonical command. The original message and its entities remain unchanged. Do not wrap schemas in ASS's

CutCommandEntitiesArg

, which derives offsets from the canonical command name and omits mentions.

ASS arguments inherit from

ArgFabric

and parse user input into structured data. The framework handles:

Validation of input format
Entity checking (prevents formatting/mentions in sensitive arguments)
Returning typed values instead of strings
Automatic error messages

Required Methods

check(text: str, entities: ArgEntities) -> bool

Validates the input before parsing. Return

True

if valid, or raise an exception if invalid.

Use cases:

Format validation (e.g., UUIDs, special characters)
Entity checking (prevent formatting in sensitive args)

Example:

parse(text: str, offset: int, entities: ArgEntities) -> tuple[int, T]

Parses the text and returns a tuple of

(length, value)

length: How many characters were consumed (for multi-argument parsing)
value: The parsed value (can be any type)

Important:

Strip extra text using
split(maxsplit=1)
to consume only what's needed
Return length of consumed text, not entire input
Raise
ArgStrictError
for "not found" or lookup errors

Example:

needed_type() -> tuple[LazyProxy, LazyProxy]

Returns a tuple of singular and plural descriptions for error messages.

Example:

Optional Methods

unparse(data: Any, **kwargs) -> str

Converts a value back to text representation.

Example:

examples

property

Returns a dictionary of example values with optional descriptions.

Example:

Common Base Classes

TextArg

For plain text arguments.

OneWordArgFabricABC

For arguments that consume exactly one word.

MarkdownLinkArgument

For parsing markdown links

[text](data)

Entity Handling

ArgEntities

is a list of Telegram

MessageEntity

objects representing formatting (bold, italic, mentions, links, etc.).

Checking for entities

Ignored entity types

Some entity types can be ignored (e.g.,

hashtag

cashtag

Common Patterns

Consuming only the first word

Use

split(maxsplit=1)

to consume only what's needed:

The

or (text,)

handles the case where there's no space to split.

Database lookups

Return objects from database instead of strings:

Working with i18n

Always translate user-facing messages:

Exception Types

ArgStrictError
: Hard validation errors (e.g., format errors, not found)
ArgSimpleTypeError
: Type errors (e.g., wrong format, bad type)
ArgCustomError
: Custom errors with custom messages
ArgTypeError
: Full type error with details (used by framework)

Complete Example

Using in Handlers

Key Takeaways

Always use
split(maxsplit=1)
to strip extra text from arguments
Return correct length - length of consumed text, not entire input
Check for entities to prevent formatting in sensitive arguments
Raise appropriate exceptions -
ArgStrictError
for validation,
ArgSimpleTypeError
for format
Return typed values from
parse()
- objects, not strings
Use i18n for all user-facing messages