boxes/server_url/docs: Update to use new webapp quoting style.

This commit adds the same new quoting style as used in the webapp, ie.
indicating the quoted author and location.

The URL generation part of the code now has its own module named
server_url.py, along with the tests for this module added as
test_server_url.py. This will allow to track changes in the server and
make constructing and deconstructing server URL's easier. This module
can also be later integrated into the API package.

Details of server_url.py are added to docs/developer-file-overview.md

Tests added and amended.

Fixes #514.

Author: zee-bit

docs/developer-file-overview.md

@@ -7,6 +7,7 @@ Zulip Terminal uses [Zulip's API](https://zulip.com/api/) to store and retrieve
 | zulipterminal/         | core.py             | Defines the `Controller`, which sets up the `model`, `view`, and coordinates the application           |
 |                        | helper.py           | Helper functions used in multiple places                                                               |
 |                        | model.py            | Defines the `Model`, fetching and storing data retrieved from the Zulip server                         |
+|                        | server_url.py       | Constructs and encodes server_url of messages.                                                         |
 |                        | ui.py               | Defines the `View`, and controls where each component is displayed                                     |
 |                        | unicode_emojis.py   | Stores valid unicode emoji data                                                                        |
 |                        | urwid_types.py      | Preliminary urwid types to improve type analysis                                                       |

tests/server_url/test_server_url.py

@@ -0,0 +1,71 @@
+import pytest
+
+from zulipterminal.server_url import encode_stream, near_message_url
+
+
+@pytest.mark.parametrize('stream_id, stream_name, expected_encoded_string', [
+    (10, 'zulip terminal', '10-zulip-terminal'),
+    (12, '<strong>xss</strong>', '12-.3Cstrong.3Exss.3C.2Fstrong.3E'),
+    (17, '#test-here #T1 #T2 #T3', '17-.23test-here-.23T1-.23T2-.23T3'),
+    (27, ':party_parrot:', '27-.3Aparty_parrot.3A'),
+    (44, '(ZT) % zulip ?/; &', '44-.28ZT.29-.25-zulip-.3F.2F.3B-.26'),
+    (273, 'abc + de = abcde', '273-abc-.2B-de-.3D-abcde'),
+    (374, '/ in a stream name ?', '374-.2F-in-a-stream-name-.3F'),
+])
+def test_encode_stream(stream_id, stream_name, expected_encoded_string):
+    encoded_string = encode_stream(
+        stream_id=stream_id, stream_name=stream_name
+    )
+
+    assert encoded_string == expected_encoded_string
+
+
+@pytest.mark.parametrize(['server_url', 'msg', 'expected_message_url'], [
+    (
+        'https://chat.zulip.org',
+        {
+            'id': 17252,
+            'type': 'stream',
+            'stream_id': 23,
+            'display_recipient': 'zulip terminal',
+            'subject': '#test-here #T1 #T2 #T3',
+        },
+        ('https://chat.zulip.org/#narrow/stream/23-zulip-terminal'
+         '/topic/.23test-here.20.23T1.20.23T2.20.23T3/near/17252'),
+    ),
+    (
+        'https://foo-bar.co.in',
+        {
+            'id': 5412,
+            'type': 'stream',
+            'stream_id': 425,
+            'display_recipient': '/ in a stream name ?',
+            'subject': 'abc + de = abcde'
+        },
+        ('https://foo-bar.co.in/#narrow/stream/425-.2F-in-a-stream-name-.3F'
+         '/topic/abc.20.2B.20de.20.3D.20abcde/near/5412'),
+    ),
+    (
+        'https://foo.bar.com',
+        {
+            'id': 24284,
+            'type': 'private',
+            'display_recipient': [
+                {
+                    'id': 12,
+                },
+                {
+                    'id': 144,
+                },
+                {
+                    'id': 249,
+                }
+            ]
+        },
+        'https://foo.bar.com/#narrow/pm-with/12,144,249-pm/near/24284',
+    ),
+])
+def test_near_message_url(server_url, msg, expected_message_url):
+    message_url = near_message_url(server_url=server_url, message=msg)
+
+    assert message_url == expected_message_url

zulipterminal/server_url.py

@@ -0,0 +1,87 @@
+import urllib.parse
+
+from zulipterminal.helper import Message
+
+
+def hash_util_encode(string: str) -> str:
+    """
+    Hide URI-encoding by replacing '%' with '.'
+    urllib.quote is equivalent to encodeURIComponent in JavaScript.
+    Referred from zerver/lib/url_encoding.py
+    """
+    # `safe` has a default value of "/", but we want those encoded, too.
+    return urllib.parse.quote(
+        string, safe=b"").replace(".", "%2E").replace("%", ".")
+
+
+def encode_stream(stream_id: int, stream_name: str) -> str:
+    """
+    Encodes stream_name with stream_id and replacing any occurence
+    of whitespace to '-'. This is the format of message representation
+    in webapp. Referred from zerver/lib/url_encoding.py.
+    """
+    stream_name = stream_name.replace(' ', '-')
+    return str(stream_id) + '-' + hash_util_encode(stream_name)
+
+
+def near_stream_message_url(server_url: str, message: Message) -> str:
+    """
+    Returns the complete encoded URL of a message from #narrow/stream.
+    Referred from zerver/lib/url_encoding.py.
+    """
+    message_id = str(message['id'])
+    stream_id = message['stream_id']
+    stream_name = message['display_recipient']
+    topic_name = message['subject']
+    encoded_stream = encode_stream(stream_id, stream_name)
+    encoded_topic = hash_util_encode(topic_name)
+
+    parts = [
+        server_url,
+        '#narrow',
+        'stream',
+        encoded_stream,
+        'topic',
+        encoded_topic,
+        'near',
+        message_id,
+    ]
+    full_url = '/'.join(parts)
+    return full_url
+
+
+def near_pm_message_url(server_url: str, message: Message) -> str:
+    """
+    Returns the complete encoded URL of a message from #narrow/pm-with.
+    Referred from zerver/lib/url_encoding.py.
+    """
+    message_id = str(message['id'])
+    str_user_ids = [
+        str(recipient['id'])
+        for recipient in message['display_recipient']
+    ]
+
+    pm_str = ','.join(str_user_ids) + '-pm'
+    parts = [
+        server_url,
+        '#narrow',
+        'pm-with',
+        pm_str,
+        'near',
+        message_id,
+    ]
+    full_url = '/'.join(parts)
+    return full_url
+
+
+def near_message_url(server_url: str, message: Message) -> str:
+    """
+    Returns the correct encoded URL of a message, if
+    it is present in stream/pm-with accordingly.
+    Referred from zerver/lib/url_encoding.py.
+    """
+    if message['type'] == 'stream':
+        url = near_stream_message_url(server_url, message)
+    else:
+        url = near_pm_message_url(server_url, message)
+    return url

zulipterminal/ui_tools/boxes.py

@@ -26,6 +26,7 @@
     Message, format_string, get_unused_fence, match_emoji, match_group,
     match_stream, match_topics, match_user,
 )
+from zulipterminal.server_url import near_message_url
 from zulipterminal.ui_tools.buttons import EditModeButton
 from zulipterminal.ui_tools.tables import render_table
 from zulipterminal.urwid_types import urwid_Size
@@ -1233,7 +1234,20 @@ def keypress(self, size: urwid_Size, key: str) -> Optional[str]:
                 self.message['id'])['raw_content']
             fence = get_unused_fence(message_raw_content)
 
-            quote = '{0}quote\n{1}\n{0}\n'.format(fence, message_raw_content)
+            absolute_url = near_message_url(
+                self.model.server_url[:-1], self.message)
+
+            # Compose box should look something like this:
+            #   @_**Zeeshan|514** [said](link to message):
+            #   ```quote
+            #   message_content
+            #   ```
+            quote = '@_**{0}|{1}** [said]({2}):\n{3}quote\n{4}\n{3}\n'.format(
+                        self.message['sender_full_name'],
+                        self.message['sender_id'],
+                        absolute_url,
+                        fence,
+                        message_raw_content)
 
             self.model.controller.view.write_box.msg_write_box.set_edit_text(
                 quote)