Formatting API

aiogram-style composable formatting built on Peyk’s RichText IR.

The composition objects are platform-neutral. Rendering happens only when a target platform is known, so application code does not carry platform names.

class peyk.formatting.Text(*body: str | RichText | Text, sep: str = '')

Bases: object

A composable sequence of text fragments and formatting nodes.

body: tuple[str | RichText | Text, ...]

to_rich_text() → RichText

Compile this composition into Peyk’s platform-neutral IR.

line() → Text

Append a newline and return a new composition.

bold(*body: str | RichText | Text) → Text

Append a bold fragment and return a new composition.

italic(*body: str | RichText | Text) → Text

Append an italic fragment and return a new composition.

underline(*body: str | RichText | Text) → Text

Append an underlined fragment and return a new composition.

strikethrough(*body: str | RichText | Text) → Text

Append a strikethrough fragment and return a new composition.

spoiler(*body: str | RichText | Text) → Text

Append a spoiler fragment and return a new composition.

code(*body: str | RichText | Text) → Text

Append an inline-code fragment and return a new composition.

pre(*body: str | RichText | Text, language: str | None = None) → Text

Append a preformatted fragment and return a new composition.

link(text: str | RichText | Text, url: str) → Text

Append a URL link and return a new composition.

mention(text: str | RichText | Text, user_id: int | str) → Text

Append a Telegram user mention and return a new composition.

blockquote(*body: str | RichText | Text) → Text

Append a block quote and return a new composition.

expandable_blockquote(*body: str | RichText | Text) → Text

Append an expandable block quote and return a new composition.

render(target: PlatformCapabilities | str) → str

Render this composition for a platform or audited capability object.

as_kwargs(target: PlatformCapabilities | str) → dict[str, object]

Return the exact text-bearing keyword arguments for target.

class peyk.formatting.Bold(*body: str | RichText | Text, sep: str = '')

Bases: Text

Render children in bold.

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

class peyk.formatting.Italic(*body: str | RichText | Text, sep: str = '')

Bases: Text

Render children in italics.

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

class peyk.formatting.Underline(*body: str | RichText | Text, sep: str = '')

Bases: Text

Render children with an underline where the target supports it.

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

class peyk.formatting.Strikethrough(*body: str | RichText | Text, sep: str = '')

Bases: Text

Render children with a strikethrough where the target supports it.

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

class peyk.formatting.Spoiler(*body: str | RichText | Text, sep: str = '')

Bases: Text

Render children as a spoiler where the target supports it.

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

class peyk.formatting.Code(*body: str | RichText | Text, sep: str = '')

Bases: Text

Render children as inline code.

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

class peyk.formatting.Pre(*body: str | RichText | Text, language: str | None = None)

Bases: Text

Render children as a preformatted block.

language: str | None

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

body: tuple[str | RichText | Text, ...]

class peyk.formatting.TextLink(*body: str | RichText | Text, url: str)

Bases: Text

Render children as a URL link.

url: str

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

body: tuple[str | RichText | Text, ...]

class peyk.formatting.TextMention(*body: str | RichText | Text, user_id: int | str)

Bases: Text

Render children as a Telegram user mention.

user_id: int | str

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

body: tuple[str | RichText | Text, ...]

class peyk.formatting.BlockQuote(*body: str | RichText | Text, sep: str = '')

Bases: Text

Render children as a block quote.

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

class peyk.formatting.ExpandableBlockQuote(*body: str | RichText | Text, sep: str = '')

Bases: Text

Render children as an expandable block quote.

to_rich_text() → RichText

Provides the to rich text operation for the peyk integration.

Returns:

Result produced by the operation.

peyk.formatting.as_line(*items: str | RichText | Text, sep: str = ' ') → Text

Join items on one line.

peyk.formatting.as_list(*items: str | RichText | Text | Iterable[str | RichText | Text], sep: str = '\n') → Text

Join items as a list separated by sep; one iterable is also accepted.

peyk.formatting.as_marked_list(*items: str | ~peyk.utils.text_formatting.RichText | ~peyk.formatting.Text | ~typing.Iterable[str | ~peyk.utils.text_formatting.RichText | ~peyk.formatting.Text], marker: str = '▫️', se, sep: str = ) ->) → Text

Prefix each item with marker.

peyk.formatting.as_numbered_list(*items: str | RichText | Text | Iterable[str | RichText | Text], sep: str = '\n') → Text

Prefix each item with its one-based position.

peyk.formatting.as_section(title: str | RichText | Text, *body: str | RichText | Text, sep: str = '\n') → Text

Return a title followed by body lines.

peyk.formatting.as_marked_section(title: str | ~peyk.utils.text_formatting.RichText | ~peyk.formatting.Text, *body: str | ~peyk.utils.text_formatting.RichText | ~peyk.formatting.Text, marker: str = '▫️', se, sep: str = ) ->) → Text

Return a title followed by a marked list.

peyk.formatting.as_key_value(key: str | RichText | Text, value: str | RichText | Text, sep: str = ': ') → Text

Join a key and value with sep.

peyk.formatting.resolve_text(content: str | RichText | Text, platform_caps: PlatformCapabilities, policy: UnsupportedPolicy, defaults: TextDefaults) → tuple[str, dict[str, object]]

Resolve text once at send time into target text and native keyword arguments.

Plain strings remain plain unless a default parse mode is configured. Rich compositions are rendered from the neutral IR; Rubika additionally receives its structured metadata. Explicit parse-mode handling is applied by peyk.Bot before this resolver is called.

class peyk.formatting.TextDefaults(*args, **kwargs)

Bases: Protocol

Minimal defaults contract required by resolve_text().

parse_mode: ParseMode | str | None

peyk.formatting.bold(text: str | RichText) → RichText

Performs the bold operation for the utility client.

Parameters:

text – Text content supplied to the operation.

Returns:

Result produced by the utility operation.

peyk.formatting.italic(text: str | RichText) → RichText

Performs the italic operation for the utility client.

Parameters:

text – Text content supplied to the operation.

Returns:

Result produced by the utility operation.

peyk.formatting.underline(text: str | RichText) → RichText

Performs the underline operation for the utility client.

Parameters:

text – Text content supplied to the operation.

Returns:

Result produced by the utility operation.

peyk.formatting.strikethrough(text: str | RichText) → RichText

Performs the strikethrough operation for the utility client.

Parameters:

text – Text content supplied to the operation.

Returns:

Result produced by the utility operation.

peyk.formatting.spoiler(text: str | RichText) → RichText

Performs the spoiler operation for the utility client.

Parameters:

text – Text content supplied to the operation.

Returns:

Result produced by the utility operation.

peyk.formatting.code(text: str | RichText) → RichText

Performs the code operation for the utility client.

Parameters:

text – Text content supplied to the operation.

Returns:

Result produced by the utility operation.

peyk.formatting.pre(text: str | RichText, language: str | None = None) → RichText

Performs the pre operation for the utility client.

Parameters:

• text – Text content supplied to the operation.

• language – Value used by this operation.

Returns:

Result produced by the utility operation.

peyk.formatting.link(text: str | RichText, url: str) → RichText

Performs the link operation for the utility client.

Parameters:

• text – Text content supplied to the operation.

• url – Target URL.

Returns:

Result produced by the utility operation.

peyk.formatting.mention_user(text: str | RichText, user_id: int | str) → RichText

Performs the mention user operation for the utility client.

Parameters:

• text – Text content supplied to the operation.

• user_id – Identifier of the target user.

Returns:

Result produced by the utility operation.

peyk.formatting.mention_username(text: str | RichText, username: str) → RichText

Performs the mention username operation for the utility client.

Parameters:

• text – Text content supplied to the operation.

• username – Value used by this operation.

Returns:

Result produced by the utility operation.

peyk.formatting.bale_expandable(title: str, text: str | RichText) → RichText

Performs the bale expandable operation for the utility client.

Parameters:

• title – Title to apply to the target resource.

• text – Text content supplied to the operation.

Returns:

Result produced by the utility operation.

class peyk.formatting.ParseMode(*values)

Bases: str, Enum

ParseMode defines a public API type for peyk.

MARKDOWN = 'Markdown'

MARKDOWN_V2 = 'MarkdownV2'

HTML = 'HTML'