Skip to main content

Converter HTML to Telegram Entities

Project description

Sulguk - HTML to telegram entities converter

PyPI version downloads license

Need to deliver formatted content to your bot clients? Having a hangover after trying to fit HTML into telegram? Beautifulsoup is too complicated and not helping with messages?

Try sulguk (술국, a hangover soup) - delivered since 1800s.

Problem

Telegram supports parse_mode="html", but:

  • Telegram processes spaces and new lines incorrectly. So we cannot format HTML source for more readability.
  • Amount of supported tags is very low
  • It does not ignore additional attributes in supported tags.

Let's imagine we have HTML like this:

<b>This is a demo of <a href="https://github.com/tishka17/sulguk">Sulguk</a></b>

  <u>Underlined</u>
  <i>Italic</i>
  <b>Bold</b>

This is how it is rendered in browser (expected behavior):

But this is how it is rendered in Telegram with parse_mode="html":

To solve this we can convert HTML to telegram entities with sulguk. So that's how it looks now:

Example

  1. Create your nice HTML:
<ol start="10">
    <li>some item</li>
    <li>other item</li>
</ol>
<p>Some <b>text</b> in a paragraph</p>
  1. Convert it into text and entities
result = transform_html(raw_html)
  1. Send it to telegram.

Depending on your library you may need to convert entities from dict into proper type

await bot.send_message(
    chat_id=CHAT_ID,
    text=result.text,
    entities=result.entities,
)

Example for aiogram users

  1. Add SulgukMiddleware to your bot
from sulguk import AiogramSulgukMiddleware

bot.session.middleware(AiogramSulgukMiddleware())
  1. Create your nice HTML:
<ol start="10">
    <li>some item</li>
    <li>other item</li>
</ol>
<p>Some <b>text</b> in a paragraph</p>
  1. Send it using sulguk as a parse_mode:
from sulguk import SULGUK_PARSE_MODE

await bot.send_message(
    chat_id=CHAT_ID,
    text=raw_html,
    parse_mode=SULGUK_PARSE_MODE,
)

Supported tags:

For all supported tags unknown attributes are ignored as well as unknown classes. Unsupported tags are raising an error.

Standard telegram tags (with some changes):

  • <a> - a hyperlink with href attribute
  • <b>, <strong> - a bold text
  • <i>, <em> - an italic text
  • <s>, <strike>, <del> - a strikethrough text
  • <u>, <ins> - an underlined text
  • <span> - an inline element with optional attribute class="tg-spoiler" to make a spoiler
  • <tg-spoiler> - a telegram spoiler
  • <pre> with optional class="language-<name>" - a preformatted block with code. <name> will be sent as a language attribute in telegram.
  • <code> - an inline preformatted element.

Note: In standard Telegram HTML you can set a preformatted text language nesting <code class="language-<name>"> in <pre> tag. This works when it is an only child. But any additional symbol outside of <code> breaks it. The same behavior is supported in sulguk. Otherwise, you can set the language on <pre> tag itself.

Additional tags:

  • <br/> - new line
  • <hr/> - horizontal line
  • <wbr/> - word break opportunity
  • <ul> - unordered list
  • <ol> - ordered list with optional attributes
    • reversed - to reverse numbers order
    • type (1/a/A/i/I) - to set numbering style
    • start - to set starting number
  • <li> - list item, with optional value attribute to change number. Nested lists have indentation
  • <div> - a block (not inline) element
  • <p> - a paragraph, emphasized with empty lines
  • <q> - a quoted text
  • <blockquote> - a block quote. Like a paragraph with indentation
  • <h1>-<h6> - text headers, styled using available telegram options
  • <noscirpt> - contents is shown as not scripting is supported
  • <cite>, <var> - italic
  • <progress>, <meter> are rendered using emoji (🟩🟩🟩🟨⬜️⬜️)
  • <kbd>, <samp> - preformatted text
  • <img> - as a link with picture emoji before. alt text is used if provided.

Tags which are treated as block elements (like <div>):

<footer>, <header>, <main>, <nav>, <section>

Tags which are treated as inline elements (like <span>):

<html>, <body>, <output>, <data>, <time>

Tags which contents is ignored:

<head>, <link>, <meta>, <script>, <style>, <template>, <title>

Command line utility for channel management

  1. Install with addons
pip install 'sulguk[cli]'
  1. Set environment variable BOT_TOKEN
export BOT_TOKEN="your telegram token"
  1. Send HTML file as a message to your channel. Additional files will be sent as comments to the first one. You can provide a channel name or a public link
sulguk send @chat_id file.html
  1. If you want to, edit using the link from shell or from your tg client. Edition of comments is supported as well.
sulguk edit 'https://t.me/channel/1?comment=42' file.html

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sulguk-0.8.0.tar.gz (26.5 kB view details)

Uploaded Source

Built Distribution

sulguk-0.8.0-py3-none-any.whl (28.7 kB view details)

Uploaded Python 3

File details

Details for the file sulguk-0.8.0.tar.gz.

File metadata

  • Download URL: sulguk-0.8.0.tar.gz
  • Upload date:
  • Size: 26.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.12

File hashes

Hashes for sulguk-0.8.0.tar.gz
Algorithm Hash digest
SHA256 1329aab0fe1ca6407b5c0cc819001e4182d4f9f7376f53be4b8dda2ec6cbc1b4
MD5 4ab64b8374d50cfbd26c45a52cb9608c
BLAKE2b-256 4643d92a7728b89447379b08d30a2853d3e6e6b09571320f2f3a8edbe14538b1

See more details on using hashes here.

File details

Details for the file sulguk-0.8.0-py3-none-any.whl.

File metadata

  • Download URL: sulguk-0.8.0-py3-none-any.whl
  • Upload date:
  • Size: 28.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.10.12

File hashes

Hashes for sulguk-0.8.0-py3-none-any.whl
Algorithm Hash digest
SHA256 92e391063c8f913cd7d33f23cc8870a4342b2e37a2683c68d91f53a5fef48e2e
MD5 764e6ad3fd511cfb2635615a64b3c6e5
BLAKE2b-256 1a85ffeb494780b7f0a03af9d38aa3225bea1ba5ceaaeb3dd30d31163b5b6cce

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page