Wiki logo

Sophie wiki

WikiSophie bot

Using STFU Formatting Tools

Last updated: February 13, 2026

Using STFU Formatting Tools

STFU (Sophie Text Formatting Utility) is used to build structured, formatted messages for Telegram. It handles HTML/Markdown conversion and provides reusable components.

Important: Never Use .format()

CRITICAL: Never use Python's
.format()
method when formatting user input with STFU elements.
Why? When you pass STFU elements (like
Bold()
,
Code()
) to
.format()
, their string representation includes HTML tags that get embedded literally.
Template
properly escapes HTML when converting, preventing XSS issues and malformed output.

Basic Concept

All STFU components implement the
Element
base class and provide:
  • to_html()
    - Convert to HTML format
  • to_md()
    - Convert to Markdown format
Important: Always use
doc.to_html()
instead of
str(doc)
when sending messages. This is the preferred, non-legacy approach.

Doc - Container for Elements

The main container that holds multiple elements.
Outputs:

Title - Headings

Creates title/headings for sections.
Parameters:
  • item
    - Title text
  • bold
    - Make bold (HTML mode, default:
    True
    )
  • level
    - Heading level 1-6 (Markdown mode, default:
    1
    )
  • prefix
    /
    postfix
    - Custom delimiters (HTML mode, default:
    [
    /
    ]
    )

Section - Grouped Content

Groups related content with optional title and indentation.
Parameters:
  • *items
    - Content items to include
  • title
    - Section title (default:
    ''
    )
  • title_bold
    - Bold the title (default:
    False
    )
  • title_underline
    - Underline the title (default:
    True
    )
  • indent
    - Indentation level (default:
    1
    )
  • indent_text
    - Indentation text (default:
    ' '
    )
  • title_postfix
    - Text after title (default:
    ':'
    )

KeyValue - Key-Value Pairs

Displays labeled values with formatting.
Parameters:
  • title
    - Label for the key
  • value
    - The value to display
  • suffix
    - Text between title and value (default:
    ': '
    )
  • title_bold
    - Bold the title (default:
    True
    )

HList - Horizontal List

Displays items horizontally with optional prefix/divider.
Parameters:
  • *args
    - Items to display
  • prefix
    - Text before each item (default:
    ''
    )
  • divider
    - Text between items (default:
    ' '
    )

VList - Vertical List

Displays items vertically with bullets and indentation.
Parameters:
  • *items
    - List items
  • indent
    - Indentation level (default:
    0
    )
  • prefix
    - Bullet/bullet text (default:
    '- '
    )

Template - String Templates

Replaces placeholders in a string with values. This is the preferred way to format strings with STFU elements.
Important: Always use
Template()
instead of
.format()
when your template includes STFU elements.
Template
properly handles HTML escaping.
Parameters:
  • item
    - Template string with
    {placeholder}
    markers
  • **kwargs
    - Placeholder replacements (values can be strings or STFU elements)

Special Components

InvisibleSymbol

An invisible character for spacing/hiding content.

Spacer

A space character (useful for forcing spacing in lists).

PreformattedHTML

Pass through HTML without escaping (use when you have valid HTML).

EscapedStr

Automatically escapes HTML when converting. (Used internally, usually not needed directly).
Creates a clickable user link.

Basic Formatting Elements

These wrap text in Telegram's basic formatting.

Combining Components

STFU elements can be nested and combined.

Real-World Examples

Command Status Response

AI Provider Selection

Statistics Display

Nested Sections

Key Takeaways

  • Use
    Doc
    as main container     for messages with multiple elements
  • Nest components freely - Sections can contain other Sections, VLists, etc.
  • Use
    Template
    for string interpolation     with
    {placeholder}
    syntax
  • NEVER use
    .format()
    with STFU elements     - use
    Template
    instead for proper HTML escaping
  • Section
    provides structure     with titles and indentation
  • KeyValue
    for labeled data     with consistent formatting
  • HList
    for horizontal layouts    ,
    VList
    for vertical lists
  • Title
    for headings     - supports both HTML and Markdown modes
  • All components auto-escape HTML (except
    PreformattedHTML
    )
  • Combine with formatting - Bold, Code, Italic work inside all components
  • Use
    doc.to_html()
    instead of
    str(doc)
     - preferred method for clarity and explicit format