Wiki logo

Sophie wiki

WikiSophie bot

Making ASS Arguments Definitions

Last updated: February 13, 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

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