API Reference#

You can import as from telegram_text import ... following elements:

telegram_text.bases.Chain
telegram_text.bases.PlainText
telegram_text.styles.Bold
telegram_text.styles.Code
telegram_text.styles.InlineCode
telegram_text.styles.Italic
telegram_text.styles.Quote
telegram_text.styles.Spoiler
telegram_text.styles.Strikethrough
telegram_text.styles.Underline
telegram_text.elements.Emoji
telegram_text.elements.Hashtag
telegram_text.elements.InlineUser
telegram_text.elements.Link
telegram_text.elements.User
telegram_text.markdown.OrderedList
telegram_text.markdown.UnorderedList
telegram_text.custom.TOMLSection

telegram_text.bases#

telegram_text.bases.NEW_LINE = '\n'#: New line character constant.

telegram_text.bases.SPACE = ' '#: Space character constant.

class telegram_text.bases.AbstractElement#

Bases: ABC

The interface every component implements.

abstract __add__(other: str | Element) → Chain#: Return a new Chain object when sum <Element object> + <Element object>. You can also use it with str object, then this method will wrap a str with PlainText object.

abstract to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

abstract to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

abstract to_html() → str#: Format the element to html according to Telegram specification.

class telegram_text.bases.Element#

Bases: AbstractElement, ABC

Base class every component must inherit.

__add__(other: str | Element) → Chain#: Return a new Chain object when sum <Element object> + <Element object>. You can also use it with str object, then this method will wrap a str with PlainText object.

__eq__(other: object) → bool#: Equality function to write <Element object> == <Element object>.

__str__() → str#: Call to_markdown() function.

abstract to_html() → str#: Format the element to html according to Telegram specification.

abstract to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

abstract to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.bases.Text(text: str | Element)#

Bases: Element

Basic text component. We don’t recommend you use this outside the code of this module because this class doesn’t include escaping logic, it means Telegram API may reject you.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

to_markdown() → str#: Return original text without escaping.

to_html() → str#: Format the element to html according to Telegram specification.

class telegram_text.bases.PlainText(text: str | Element)#

Bases: Text

Basic text element you can safely use. This element implements escaping logic.

escaping_chars = ('_', '*', '[', ']', '(', ')', '~', '`', '>', '#', '+', '-', '=', '|', '{', '}', '.', '!')#: Tuple of character that will be escaped according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_html() → str#: Format the element to html according to Telegram specification.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.bases.Chain(*elements: Element, sep: str = ' ')#

Bases: Element

Combination between a few elements.

Parameters:

elements (Tuple[Element]) – Any objects with AbstractElement interface.
sep (str) – The separator between elements. SPACE by default.

__contains__(item: Element) → bool#: Magic method to write if <Element object> in <Chain object>.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_html() → str#: Format the element to html according to Telegram specification.

telegram_text.styles#

class telegram_text.styles.Style(text: str | Element)#

Bases: Element, ABC

Class that inherits each style. it isolates a part of logic how to render styles.

Parameters:: text (Union[str, telegram_text.bases.Element]) – Text or Element to which the style will be applied.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_html() → str#: Format the element to html according to Telegram specification.

class telegram_text.styles.Bold(text: str | Element)#

Bases: Style

Bold text. Example: bold text.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.styles.Italic(text: str | Element)#

Bases: Style

Italic text. Example: italic text.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.styles.Underline(text: str | Element)#

Bases: Style

Underline text. Example: underline text.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.styles.Strikethrough(text: str | Element)#

Bases: Style

Strikethrough text. Example: strikethrough text.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.styles.Spoiler(text: str | Element)#

Bases: Style

Spoiler text. We can’t provide an example because it’s a very specific for Telegram messenger formatting.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.styles.InlineCode(text: str | Element)#

Bases: Style

Inline code text. Example: inline code.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.styles.Code(text: str, language: str | None = None)#

Bases: Style

Code block for many lines of text. Telegram doesn’t support frontend language-specific highlights, but according to documentation, it provides an opportunity to specify a language. Perhaps, the Telegram team will add support for this in the future.

Parameters:

text (str) – Text of code block.
language (Optional[str]) – Leave it empty if you don’t want to specify a language.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_html() → str#: Format the element to html according to Telegram specification.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.styles.Quote(text: str | Element)#

Bases: Style

Quote block. See an example below.

Block quotation started

Block quotation continued

The last line of the block quotation

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_html() → str#: Format the element to html according to Telegram specification.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

telegram_text.elements#

All classes in this file provide similar signatures.

They all have text: str and style: Callable[[Union[str, Element]], Element]) arguments.

style is a factory that will be applied to the element.

class telegram_text.elements.Link(text: str, url: str, style: ~typing.Callable[[str | ~telegram_text.bases.Element], ~telegram_text.bases.Element] = <class 'telegram_text.bases.PlainText'>)#

Bases: Element

Inline link element.

Parameters:

text (str) – Text of link.
url (str) – Web address on the internet.
style (Callable[[Union[str, Element]], Element]) – Style factory which will be applied to the element. telegram_text.bases.PlainText by default.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_html() → str#: Format the element to html according to Telegram specification.

class telegram_text.elements.InlineUser(text: str, user_id: int, style: ~typing.Callable[[str | ~telegram_text.bases.Element], ~telegram_text.bases.Element] = <class 'telegram_text.bases.Text'>)#

Bases: Link

Inline link to user with specific for Telegram url (tg://user?id={}).

Parameters:

text (str) – Text of link.
user_id (int) – Identifier of user.
style (Callable[[Union[str, Element]], Element]) – Style factory which will be applied to the element. telegram_text.bases.PlainText by default.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.elements.User(text: str, style: ~typing.Callable[[str | ~telegram_text.bases.Element], ~telegram_text.bases.Element] = <class 'telegram_text.bases.PlainText'>)#

Bases: _Reference

Link to user by nickname.

Parameters:

text (str) – Nickname of user.
style (Callable[[Union[str, Element]], Element]) – Style factory which will be applied to the element. telegram_text.bases.PlainText by default.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.elements.Hashtag(text: str, style: ~typing.Callable[[str | ~telegram_text.bases.Element], ~telegram_text.bases.Element] = <class 'telegram_text.bases.PlainText'>)#

Bases: _Reference

Hashtag link element.

Parameters:

text (str) – Hashtag name.
style (Callable[[Union[str, Element]], Element]) – Style factory which will be applied to the element. telegram_text.bases.PlainText by default.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.elements.Emoji(emoji_id: int, default: str)#

Bases: Element

Custom Telegram emoji.

Custom emoji entities can only be used by bots that purchased additional usernames on Fragment.

Parameters:

emoji_id (int) – Id of the custom emoji.
default (str) – Alternative value for the custom emoji. The emoji will be shown instead of the custom emoji in places where a custom emoji cannot be displayed (e.g., system notifications) or if the message is forwarded by a non-premium user.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_html() → str#: Format the element to html according to Telegram specification.

telegram_text.markdown#

Telegram markdown and official markdown standards are very different. Telegram markdown has new elements and hasn’t some main old elements from the official markdown format. This file is a compromise that adds missing elements to Telegram.

class telegram_text.markdown.UnorderedList(*elements: ~telegram_text.bases.Element, style: ~typing.Callable[[str], ~telegram_text.bases.Element] = <class 'telegram_text.styles.Bold'>, sep: str = '\n')#

Bases: Chain

Unordered (bullet) list.

Example:

First element.
Second element.
Third element.

Parameters:

elements (Tuple[Element]) – Elements for the list. Every element is a single point.
style (Callable[[str], Element]) – Style factory that will be applied to every point (only special characters of list, not passed elements). telegram_text.styles.Bold by default.
sep (str) – Separator between every point. telegram_text.bases.NEW_LINE by default.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

class telegram_text.markdown.OrderedList(*elements: ~telegram_text.bases.Element, style: ~typing.Callable[[str], ~telegram_text.bases.Element] = <class 'telegram_text.bases.PlainText'>, sep: str = '\n')#

Bases: Chain

Ordered (numbered) list.

Example:

First element.
Second element.
Third element.

Parameters:

elements (Tuple[Element]) – Elements for the list. Every element is a single point.
style (Callable[[str], Element]) – Style factory that will be applied to every point (only special characters of list, not passed elements). telegram_text.bases.PlainText by default.
sep (str) – Separator between every point. telegram_text.bases.NEW_LINE by default.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.

telegram_text.custom#

This file contains unofficial, but very useful markup elements.

class telegram_text.custom.TOMLSection(text: str, *elements: ~telegram_text.bases.Element, style: ~typing.Callable[[str], ~telegram_text.bases.Element] = <class 'telegram_text.styles.InlineCode'>)#

Bases: Chain

Section element in .toml format.

Parameters:

text (str) – Section name.
elements (Tuple[Element]) – Sections elements. Separator is telegram_text.bases.NEW_LINE.
style (Callable[[str], Element]) – Style factory that will be applied to name. telegram_text.styles.InlineCode by default.

to_html() → str#: Format the element to html according to Telegram specification.

to_markdown() → str#: Format the element to Markdown/MarkdownV2 format according to Telegram specification with escaping if necessary.

to_plain_text() → str#: Format the element to plain text without escaping, tags or special characters.