Форматування

Сделайте форматирование ваших сообщений гибким и простым

Этот инструмент работает на основе сущностей сообщений, а не используя HTML или розмитку Markdown, вы можете легко создать свое сообщения и отправить его в Telegram без необходимости помнить о парнисть тегив (открытия и закриття) или о экранирования пользовательского ввода.

Использование

Основний сценарий

Составьте свое сообщение и отправьте его в Telegram.

content = Text("Hello, ", Bold(message.from_user.full_name), "!")
await message.answer(**content.as_kwargs())

Такой самий, как следующий пример, но без использования розмитки

await message.answer(
    text=f"Hello, <b>{html.quote(message.from_user.full_name)}</b>!",
    parse_mode=ParseMode.HTML
)

Досливно, когда вы виконуете метод as_kwargs, объект Text перетворюеться в текст Hello, Alex! из списком сущностей [MessageEntity(type='bold', offset=7, length=4)] и передаеться в словарь, который может быть использован как **kwargs в API-вызова.

Повний список елементив приведено на сторинци ниже.

Розширений сценарий

На дополнение к базових елементив могут быть реализовани структуры рендерингу контенту, поэтому с коробки litegram предоставляет декилька уже реализованных функций, которые помогают форматувати ваши сообщения:

litegram.utils.formatting.as_line(*items: Any, end: str = '\n', sep: str = '') → Text

Об’еднайте несколько узлов в строку из \n в кинци рядка.

Параметры:

• items – Текст или Другое

• end – завершения рядка, по умолчанию \n

• sep – разделитель между елеменими, по умолчанию пуст строку

Результат:

Текст

litegram.utils.formatting.as_list(*items: Any, sep: str = '\n') → Text

Обгорнить каждый елемент в отдельный строку

Параметры:

• items

• sep

Результат:

litegram.utils.formatting.as_marked_list(*items: Any, marker: str = '- ') → Text

Обгорнить елементи в маркированный список

Параметры:

• items

• marker – маркер рядка, по умолчанию „- „

Результат:

Текст

litegram.utils.formatting.as_numbered_list(*items: Any, start: int = 1, fmt: str = '{}. ') → Text

Обгорнить елементи в нумерованный список

Параметры:

• items

• start – начальный номер, по умолчанию 1

• fmt – формат номера, по умолчанию „{}. „

Результат:

Текст

litegram.utils.formatting.as_section(title: Any, *body: Any) → Text

Обгорнить елементи в простой раздел, раздел имеет заголовок и тело

Параметры:

• title

• body

Результат:

Текст

litegram.utils.formatting.as_marked_section(title: Any, *body: Any, marker: str = '- ') → Text

Обгорнить елементи в раздел из маркованим списком

Параметры:

• title

• body

• marker

Результат:

litegram.utils.formatting.as_numbered_section(title: Any, *body: Any, start: int = 1, fmt: str = '{}. ') → Text

Обгорнить елементи в раздел из нумерованим списком

Параметры:

• title

• body

• start

• fmt

Результат:

litegram.utils.formatting.as_key_value(key: Any, value: Any) → Text

Обгорнить пари елементив в строку ключ-значение. (<b>{key}:</b> {value})

Параметры:

• key

• value

Результат:

Текст

и давайте завершимо их всех:

content = as_list(
    as_marked_section(
        Bold("Success:"),
        "Test 1",
        "Test 3",
        "Test 4",
        marker="✅ ",
    ),
    as_marked_section(
        Bold("Failed:"),
        "Test 2",
        marker="❌ ",
    ),
    as_marked_section(
        Bold("Summary:"),
        as_key_value("Total", 4),
        as_key_value("Success", 3),
        as_key_value("Failed", 1),
        marker="  ",
    ),
    HashTag("#test"),
    sep="\n\n",
)

Буде отрендерено в:

Успишно:

✅ Тест 1

✅ Тест 3

✅ Тест 4

Помилки:

❌ Тест 2

Пидсумки:

Загалом: 4

Успишно: 3

Помилки: 1

#тест

Або как HTML:

<b>Success:</b>
✅ Test 1
✅ Test 3
✅ Test 4

<b>Failed:</b>
❌ Test 2

<b>Summary:</b>
  <b>Total:</b> 4
  <b>Success:</b> 3
  <b>Failed:</b> 1

#test

Available methods

class litegram.utils.formatting.Text(*body: Any, **params: Any)

Базовые классы: Iterable[Any]

Simple text element

__init__(*body: Any, **params: Any) → None

render(*, _offset: int = 0, _sort: bool = True, _collect_entities: bool = True) → tuple[str, list[MessageEntity]]

Обгорнить елементи в раздел из нумерованим списком

Результат:

as_kwargs(*, text_key: str = 'text', entities_key: str = 'entities', replace_parse_mode: bool = True, parse_mode_key: str = 'parse_mode') → dict[str, Any]

Render element tree as keyword arguments for usage in an API call, for example:

entities = Text(...)
await message.answer(**entities.as_kwargs())

Параметры:

• text_key

• entities_key

• replace_parse_mode

• parse_mode_key

Результат:

as_caption_kwargs(*, replace_parse_mode: bool = True) → dict[str, Any]

Shortcut for as_kwargs() for usage with API calls that take caption as a parameter.

entities = Text(...)
await message.answer_photo(**entities.as_caption_kwargs(), photo=phot)

Параметры:

replace_parse_mode – Will be passed to as_kwargs().

Результат:

as_poll_question_kwargs(*, replace_parse_mode: bool = True) → dict[str, Any]

Shortcut for as_kwargs() for usage with method litegram.methods.send_poll.SendPoll.

entities = Text(...)
await message.answer_poll(**entities.as_poll_question_kwargs(), options=options)

Параметры:

replace_parse_mode – Will be passed to as_kwargs().

Результат:

as_poll_explanation_kwargs(*, replace_parse_mode: bool = True) → dict[str, Any]

Shortcut for as_kwargs() for usage with method litegram.methods.send_poll.SendPoll.

question_entities = Text(...)
explanation_entities = Text(...)
await message.answer_poll(
    **question_entities.as_poll_question_kwargs(),
    options=options,
    **explanation_entities.as_poll_explanation_kwargs(),
)

Параметры:

replace_parse_mode – Will be passed to as_kwargs().

Результат:

as_gift_text_kwargs(*, replace_parse_mode: bool = True) → dict[str, Any]

Shortcut for as_kwargs() for usage with method litegram.methods.send_gift.SendGift.

entities = Text(...)
await bot.send_gift(gift_id=gift_id, user_id=user_id, **entities.as_gift_text_kwargs())

Параметры:

replace_parse_mode – Will be passed to as_kwargs().

Результат:

as_html() → str

Render elements tree as HTML markup

as_markdown() → str

Render elements tree as MarkdownV2 markup

Available elements

class litegram.utils.formatting.Text(*body: Any, **params: Any)

Базовые классы: Iterable[Any]

Simple text element

class litegram.utils.formatting.HashTag(*body: Any, **params: Any)

Базовые классы: Text

Hashtag element.

Предупреждение

The value should always start with „#“ symbol

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.HASHTAG

class litegram.utils.formatting.CashTag(*body: Any, **params: Any)

Базовые классы: Text

Cashtag element.

Предупреждение

The value should always start with „$“ symbol

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.CASHTAG

class litegram.utils.formatting.BotCommand(*body: Any, **params: Any)

Базовые классы: Text

Bot command element.

Предупреждение

The value should always start with „/“ symbol

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.BOT_COMMAND

class litegram.utils.formatting.Url(*body: Any, **params: Any)

Базовые классы: Text

Url element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.URL

class litegram.utils.formatting.Email(*body: Any, **params: Any)

Базовые классы: Text

Email element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.EMAIL

class litegram.utils.formatting.PhoneNumber(*body: Any, **params: Any)

Базовые классы: Text

Phone number element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.PHONE_NUMBER

class litegram.utils.formatting.Bold(*body: Any, **params: Any)

Базовые классы: Text

Bold element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.BOLD

class litegram.utils.formatting.Italic(*body: Any, **params: Any)

Базовые классы: Text

Italic element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.ITALIC

class litegram.utils.formatting.Underline(*body: Any, **params: Any)

Базовые классы: Text

Underline element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.UNDERLINE

class litegram.utils.formatting.Strikethrough(*body: Any, **params: Any)

Базовые классы: Text

Strikethrough element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.STRIKETHROUGH

class litegram.utils.formatting.Spoiler(*body: Any, **params: Any)

Базовые классы: Text

Spoiler element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.SPOILER

class litegram.utils.formatting.Code(*body: Any, **params: Any)

Базовые классы: Text

Code element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.CODE

class litegram.utils.formatting.Pre(*body: Any, language: str | None = None, **params: Any)

Базовые классы: Text

Pre element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.PRE

class litegram.utils.formatting.TextLink(*body: Any, url: str, **params: Any)

Базовые классы: Text

Text link element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.TEXT_LINK

class litegram.utils.formatting.TextMention(*body: Any, user: User, **params: Any)

Базовые классы: Text

Text mention element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.TEXT_MENTION

class litegram.utils.formatting.CustomEmoji(*body: Any, custom_emoji_id: str, **params: Any)

Базовые классы: Text

Custom emoji element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.CUSTOM_EMOJI

class litegram.utils.formatting.BlockQuote(*body: Any, **params: Any)

Базовые классы: Text

Block quote element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.BLOCKQUOTE

class litegram.utils.formatting.ExpandableBlockQuote(*body: Any, **params: Any)

Базовые классы: Text

Expandable block quote element.

Will be wrapped into litegram.types.message_entity.MessageEntity with type litegram.enums.message_entity_type.MessageEntityType.EXPANDABLE_BLOCKQUOTE