Add support for the HTML syntax

Now you can send messages with a subset of HTML in it, as you would
do with Markdown. Automatic detection is also present.

This commit also restructures the underlying code for the syntaxes.

Author: Pietro Albini

botogram/objects/mixins.py

@@ -7,6 +7,7 @@
 """
 
 from .. import utils
+from .. import syntaxes
 
 
 def _require_api(func):
@@ -30,12 +31,6 @@ def send(self, message, preview=True, reply_to=None, syntax=None,
         if hasattr(reply_to, "message_id"):
             reply_to = reply_to.message_id
 
-        # Use the correct syntax
-        if syntax is None:
-            syntax = "markdown" if utils.is_markdown(message) else "plain"
-        elif syntax not in ("plain", "markdown"):
-            raise ValueError("Invalid syntax type: %s")
-
         # Get the correct chat_id
         chat_id = self.username if self.type == "channel" else self.id
 
@@ -46,8 +41,10 @@ def send(self, message, preview=True, reply_to=None, syntax=None,
             args["reply_to_message_id"] = reply_to
         if extra is not None:
             args["reply_markup"] = extra.serialize()
-        if syntax == "markdown":
-            args["parse_mode"] = "Markdown"
+
+        syntax = syntaxes.guess_syntax(message, syntax)
+        if syntax is not None:
+            args["parse_mode"] = syntax
 
         self._api.call("sendMessage", args)
 

botogram/syntaxes.py

@@ -0,0 +1,56 @@
+"""
+    botogram.syntaxes
+    Definition of the different message syntaxes
+
+    Copyright (c) 2016 Pietro Albini <[email protected]>
+    Released under the MIT license
+"""
+
+import re
+
+
+_markdown_re = re.compile(r"("
+                          r"\*(.*)\*|"
+                          r"_(.*)_|"
+                          r"\[(.*)\]\((.*)\)|"
+                          r"`(.*)`|"
+                          r"```(.*)```"
+                          r")")
+
+_html_re = re.compile(r"("
+                      r"<b>(.*)<\/b>|"
+                      r"<strong>(.*)<\/strong>|"
+                      r"<i>(.*)<\/i>|"
+                      r"<em>(.*)<\/em>|"
+                      r"<a\shref=\"(.*)\">(.*)<\/a>|"
+                      r"<code>(.*)<\/code>|"
+                      r"<pre>(.*)<\/pre>"
+                      r")")
+
+
+def is_markdown(message):
+    """Check if a string is actually markdown"""
+    return bool(_markdown_re.match(message))
+
+
+def is_html(message):
+    """Check if a string is actually HTML"""
+    return bool(_html_re.match(message))
+
+
+def guess_syntax(message, provided):
+    """Guess the right syntax for a message"""
+    if provided is None:
+        if is_markdown(message):
+            return "Markdown"
+        elif is_html(message):
+            return "HTML"
+        else:
+            return None
+
+    if provided in ("md", "markdown", "Markdown"):
+        return "Markdown"
+    elif provided in ("html", "HTML"):
+        return "HTML"
+    else:
+        raise ValueError("Invalid syntax: %s" % provided)

botogram/utils.py

@@ -21,9 +21,6 @@
 _command_re = re.compile(r"^\/[a-zA-Z0-9_]+(\@[a-zA-Z0-9_]{5}[a-zA-Z0-9_]*)?$")
 _email_re = re.compile(r"[a-zA-Z0-9_\.\+\-]+\@[a-zA-Z0-9_\.\-]+\.[a-zA-Z]+")
 
-_markdown_re = re.compile(r"(\*(.*)\*|_(.*)_|\[(.*)\]\((.*)\)|`(.*)`|"
-                          r"```(.*)```)")
-
 # This small piece of global state will track if logbook was configured
 _logger_configured = False
 
@@ -133,11 +130,6 @@ def usernames_in(message):
     return results
 
 
-def is_markdown(string):
-    """Check if a string is actually markdown"""
-    return bool(_markdown_re.match(string))
-
-
 def get_language(lang):
     """Get the GNUTranslations instance of a specific language"""
     path = pkg_resources.resource_filename("botogram", "i18n/%s.mo" % lang)

docs/api/bot.rst

@@ -296,11 +296,9 @@ components.
       * :py:class:`botogram.ReplyKeyboardHide`
       * :py:class:`botogram.ForceReply`
 
-      The syntax parameter contains how the message should be processed by
-      Telegram, and it can be either ``plain`` (no syntax) or ``markdown``. If
-      you don't provide it, botogram will try to guess which syntax to use by
-      parsing the message you want to send. This feature is not supported by
-      all the Telegram clients.
+      The *syntax* parameter is for defining how the message text should be
+      processed by Telegram (:ref:`learn more about rich formatting
+      <tricks-messages-syntax>`).
 
       :param int chat: The ID of the chat which should receive the message.
       :param str messgae: The message you want to send.

docs/api/telegram.rst

@@ -68,13 +68,10 @@ Available Classes
       from generating a *preview* for any link included in the message. If the
       message you are sending is in reply to another, set *reply_to* to the ID
       of the other :py:class:`~botogram.Message`. The *syntax* parameter is for
-      defining how the message text should be processed by Telegram. Set it to
-      either ``plain`` (no syntax) or ``markdown`` (see Telegram's current
-      `Markdown support`_). By default botogram will try to guess which syntax
-      to use by parsing the message. This feature is not supported by all app
-      clients. *extra* is an optional object which specifies additional reply
-      interface options on the recipient's end, and can be one of the following
-      types:
+      defining how the message text should be processed by Telegram
+      (:ref:`learn more about rich formatting <tricks-messages-syntax>`).
+      *extra* is an optional object which specifies additional reply interface
+      options on the recipient's end, and can be one of the following types:
 
         * :py:class:`botogram.ReplyKeyboardMarkup`
         * :py:class:`botogram.ReplyKeyboardHide`
@@ -204,13 +201,10 @@ Available Classes
       from generating a *preview* for any link included in the message. If the
       message you are sending is in reply to another, set *reply_to* to the ID
       of the other :py:class:`~botogram.Message`. The *syntax* parameter is for
-      defining how the message text should be processed by Telegram. Set it to
-      either ``plain`` (no syntax) or ``markdown`` (see Telegram's current
-      `Markdown support`_). By default botogram will try to guess which syntax
-      to use by parsing the message. This feature is not supported by all app
-      clients. *extra* is an optional object which specifies additional reply
-      interface options on the recipient's end, and can be one of the following
-      types:
+      defining how the message text should be processed by Telegram
+      (:ref:`learn more about rich formatting <tricks-messages-syntax>`).
+      *extra* is an optional object which specifies additional reply interface
+      options on the recipient's end, and can be one of the following types:
 
         * :py:class:`botogram.ReplyKeyboardMarkup`
         * :py:class:`botogram.ReplyKeyboardHide`
@@ -492,12 +486,10 @@ Available Classes
       Reply with the textual *message* in regards to this message. You may
       optionally stop clients from generating a *preview* for any link included
       in the reply. The *syntax* parameter is for defining how the message text
-      should be processed by Telegram. Set it to either ``plain`` (no syntax) or
-      ``markdown`` (see Telegram's current `Markdown support`_). By default
-      botogram will try to guess which syntax to use by parsing the message.
-      This feature is not supported by all app clients. *extra* is an optional
-      object which specifies additional reply interface options on the
-      recipient's end, and can be one of the following types:
+      should be processed by Telegram (:ref:`learn more about rich formatting
+      <tricks-messages-syntax>`).  *extra* is an optional object which
+      specifies additional reply interface options on the recipient's end, and
+      can be one of the following types:
 
         * :py:class:`botogram.ReplyKeyboardMarkup`
         * :py:class:`botogram.ReplyKeyboardHide`
@@ -1048,4 +1040,3 @@ Available Classes
 .. _Telegram's Bot API: https://core.telegram.org/bots/api
 .. _API methods: https://core.telegram.org/bots/api#available-methods
 .. _API types: https://core.telegram.org/bots/api#available-types
-.. _Markdown support: https://core.telegram.org/bots/api#using-markdown

docs/tricks.rst

@@ -44,3 +44,37 @@ botogram, without being directly provided by the decorator:
 
 * **shared**, which is an instance of the bot's
   :ref:`shared memory <shared-memory>`.
+
+.. _tricks-messages-syntax:
+
+=====================================
+Rich formatting with message syntaxes
+=====================================
+
+Plain text messages can be boring for your users, and also hard to read if
+those messages are full with information. Because of that, Telegram allows bots
+to use rich formatting in their messages. Currently Telegram only supports `a
+subset of`_ Markdown and HTML.
+
+In order to use rich formatting in your messages you don't need to do anything:
+botogram is smart enough to detect when a message uses rich formatting, and the
+used syntax. If for whatever reason that detection fails, you can specify the
+syntax you're using by providing it to the ``syntax`` parameter of the
+:py:meth:`~botogram.Chat.send` method:
+
+.. code-block:: python
+
+   chat.send("*This is Markdown!*", syntax="markdown")
+
+That parameter accepts the following values:
+
+* ``markdown``, or its aliases ``md`` and ``Markdown``
+* ``html``, or its alias ``HTML``
+
+.. note::
+
+   Support for rich formatting depends on your users' Telegram client. If
+   they're using the official ones there are no problems, but that might work
+   on unofficial clients.
+
+.. _a subset of: https://core.telegram.org/bots/api#formatting-options

tests/test_syntaxes.py

@@ -0,0 +1,49 @@
+"""
+    Tests for botogram/syntaxes.py
+
+    Copyright (c) 2016 Pietro Albini <[email protected]>
+    Released under the MIT license
+"""
+
+import pytest
+
+import botogram.syntaxes
+
+
+def test_is_markdown():
+    assert not botogram.syntaxes.is_markdown("not markdown, sorry!")
+    assert not botogram.syntaxes.is_markdown("*a [wonderfully](broken syntax`")
+
+    for delimiter in "*", "_", "`", "```":
+        assert botogram.syntaxes.is_markdown(delimiter+"a"+delimiter)
+
+    assert botogram.syntaxes.is_markdown("[a](b)")
+
+
+def test_is_html():
+    assert not botogram.syntaxes.is_html("not HTML, sorry!")
+    assert not botogram.syntaxes.is_html("<a some </really> <b>roken html</i>")
+
+    for tag in "b", "strong", "i", "em", "pre", "code":
+        assert botogram.syntaxes.is_html("<"+tag+">a</"+tag+">")
+
+    assert not botogram.syntaxes.is_html("<a>a</a>")
+    assert not botogram.syntaxes.is_html("<a test=\"b\">a</a>")
+    assert botogram.syntaxes.is_html("<a href=\"b\">a</a>")
+
+
+def test_guess_syntax():
+    # Provided syntax name
+    for name in ("md", "markdown", "Markdown"):
+        assert botogram.syntaxes.guess_syntax("", name) == "Markdown"
+
+    for name in ("html", "HTML"):
+        assert botogram.syntaxes.guess_syntax("", name) == "HTML"
+
+    with pytest.raises(ValueError):
+        botogram.syntaxes.guess_syntax("", "invalid")
+
+    # Let's guess it
+    assert botogram.syntaxes.guess_syntax("no syntax, sorry!", None) is None
+    assert botogram.syntaxes.guess_syntax("*markdown*", None) == "Markdown"
+    assert botogram.syntaxes.guess_syntax("<b>html</b>", None) == "HTML"

tests/test_utils.py

@@ -63,13 +63,3 @@ def test_usernames_in():
 
     username_url = botogram.utils.usernames_in("http://pwd:[email protected]")
     assert username_url == []
-
-
-def test_is_markdown():
-    assert not botogram.utils.is_markdown("not markdown, sorry!")
-    assert not botogram.utils.is_markdown("*all [wonderfully](broken syntax`")
-    assert botogram.utils.is_markdown("*a*")
-    assert botogram.utils.is_markdown("_a_")
-    assert botogram.utils.is_markdown("[a](b)")
-    assert botogram.utils.is_markdown("`a`")
-    assert botogram.utils.is_markdown("```a```")