buttons: Add support for PM narrow links in MessageLinkButton.

Currently webapp supports several url types, such as:
        narrow/pm-with/1,2-pm
        narrow/pm-with/1,2-group
        narrow/pm-with/1,2,3-pm
        narrow/pm-with/1,2,3-group
        narrow/pm-with/1-user1
        narrow/pm-with/1-bot-name
(near parameter supported for each)

This commit adds support for narrow using above mentioned url types.

Helper method added: _decode_pm_data().
TypeDict added: DecodedPM(Literal, List)

Tests added and amended.

Author: Ezio-Sarthak

tests/ui_tools/test_buttons.py

@@ -1,6 +1,7 @@
 from typing import Any, Dict
 
 import pytest
+from typing_extensions import Literal
 from urwid import AttrMap, Overlay
 
 from zulipterminal.config.keys import keys_for_command
@@ -406,6 +407,34 @@ def test__decode_stream_data(self, stream_data, expected_response):
 
         assert return_value == expected_response
 
+    @pytest.mark.parametrize('pm_data, expected_response', [
+            ('1,2-pm', dict(recipient_ids=[1, 2], type=Literal['pm'])),
+            ('1,2-group', dict(recipient_ids=[1, 2], type=Literal['pm'])),
+            ('1,2,3-pm', dict(recipient_ids=[1, 2, 3],
+                              type=Literal['group'])),
+            ('1,2,3-group', dict(recipient_ids=[1, 2, 3],
+                                 type=Literal['group'])),
+            ('1-user1', dict(recipient_ids=[1], type=Literal['pm'])),
+            ('1-user2', dict(recipient_ids=[1], type=Literal['pm'])),
+            ('1-bot-name', dict(recipient_ids=[1], type=Literal['pm'])),
+            ('1-bot;name', dict(recipient_ids=[1], type=Literal['pm'])),
+        ],
+        ids=[
+            'pm_with_two_recipients',
+            'group_pm_with_two_recipients',
+            'pm_with_more_than_two_recipients',
+            'group_pm_with_more_than_two_recipients',
+            'pm_exposed_format_1_ordinary',
+            'pm_exposed_format_1_ambigous',
+            'pm_with_bot_exposed_format_1_ordinary',
+            'pm_with_bot_exposed_format_1_ambigous',
+        ]
+    )
+    def test__decode_pm_data(self, pm_data, expected_response):
+        return_value = MessageLinkButton._decode_pm_data(pm_data)
+
+        assert return_value == expected_response
+
     @pytest.mark.parametrize('message_id, expected_return_value', [
         ('1', 1),
         ('foo', None),
@@ -431,6 +460,27 @@ def test__decode_message_id(self, message_id, expected_return_value):
         (SERVER_URL + '/#narrow/stream/1-Stream-1/topic/foo/near/1',
          {'narrow': 'stream:topic:near', 'topic_name': 'foo', 'message_id': 1,
           'stream': {'stream_id': 1, 'stream_name': None}}),
+        (SERVER_URL + '/#narrow/pm-with/1,2-pm',
+         {'narrow': 'pm-with',
+          'pm_with': {'type': Literal['pm'], 'recipient_ids': [1, 2]}}),
+        (SERVER_URL + '/#narrow/pm-with/1,2-group',
+         {'narrow': 'pm-with',
+          'pm_with': {'type': Literal['pm'], 'recipient_ids': [1, 2]}}),
+        (SERVER_URL + '/#narrow/pm-with/1-user1',
+         {'narrow': 'pm-with',
+          'pm_with': {'type': Literal['pm'], 'recipient_ids': [1]}}),
+        (SERVER_URL + '/#narrow/pm-with/1-bot-name',
+         {'narrow': 'pm-with',
+          'pm_with': {'type': Literal['pm'], 'recipient_ids': [1]}}),
+        (SERVER_URL + '/#narrow/pm-with/1,2-pm/near/1',
+         {'narrow': 'pm-with:near', 'message_id': 1,
+          'pm_with': {'type': Literal['pm'], 'recipient_ids': [1, 2]}}),
+        (SERVER_URL + '/#narrow/pm-with/1,2,3-pm',
+         {'narrow': 'pm-with',
+          'pm_with': {'type': Literal['group'], 'recipient_ids': [1, 2, 3]}}),
+        (SERVER_URL + '/#narrow/pm-with/1,2,3-group',
+         {'narrow': 'pm-with',
+          'pm_with': {'type': Literal['group'], 'recipient_ids': [1, 2, 3]}}),
         (SERVER_URL + '/#narrow/foo',
          {}),
         (SERVER_URL + '/#narrow/stream/',
@@ -448,6 +498,13 @@ def test__decode_message_id(self, message_id, expected_return_value):
             'topic_narrow_link',
             'stream_near_narrow_link',
             'topic_near_narrow_link',
+            'pm_with_two_recipients_narrow_link',
+            'group_pm_with_two_recipients_narrow_link',
+            'pm_exposed_format_1_narrow_link',
+            'pm_with_bot_exposed_format_1_narrow_link',
+            'common_pm_near_narrow_link',
+            'pm_with_more_than_two_recipients_narrow_link',
+            'group_pm_with_more_than_two_recipients_narrow_link',
             'invalid_narrow_link_1',
             'invalid_narrow_link_2',
             'invalid_narrow_link_3',
@@ -630,44 +687,83 @@ def test__validate_and_patch_stream_data(self, stream_dict, parsed_link,
             'parsed_link',
             'narrow_to_stream_called',
             'narrow_to_topic_called',
+            'narrow_to_user_called',
         ],
         [
             ({'narrow': 'stream',
               'stream': {'stream_id': 1, 'stream_name': 'Stream 1'}},
              True,
+             False,
              False),
             ({'narrow': 'stream:topic', 'topic_name': 'Foo',
               'stream': {'stream_id': 1, 'stream_name': 'Stream 1'}},
              False,
-             True),
+             True,
+             False),
             ({'narrow': 'stream:near', 'message_id': 1,
               'stream': {'stream_id': 1, 'stream_name': 'Stream 1'}},
              True,
+             False,
              False),
             ({'narrow': 'stream:topic:near', 'topic_name': 'Foo',
               'message_id': 1,
               'stream': {'stream_id': 1, 'stream_name': 'Stream 1'}},
              False,
+             True,
+             False),
+            ({'narrow': 'pm-with',
+              'pm_with': {'type': Literal['pm'], 'recipient_ids': [1, 2]}},
+             False,
+             False,
+             True),
+            ({'narrow': 'pm-with',
+              'pm_with': {'type': Literal['group'],
+                          'recipient_ids': [1, 2, 3]}},
+             False,
+             False,
+             True),
+            ({'narrow': 'pm-with:near', 'message_id': 1,
+              'pm_with': {'type': Literal['pm'], 'recipient_ids': [1, 2]}},
+             False,
+             False,
+             True),
+            ({'narrow': 'pm-with:near', 'message_id': 1,
+              'pm_with': {'type': Literal['group'],
+                          'recipient_ids': [1, 2, 3]}},
+             False,
+             False,
              True),
         ],
         ids=[
             'stream_narrow',
             'topic_narrow',
             'stream_near_narrow',
             'topic_near_narrow',
+            'pm_narrow',
+            'group_pm_narrow',
+            'pm_near_narrow',
+            'group_pm_near_narrow',
         ]
     )
     def test__switch_narrow_to(self, parsed_link, narrow_to_stream_called,
-                               narrow_to_topic_called,
+                               narrow_to_topic_called, narrow_to_user_called,
                                ):
         mocked_button = self.message_link_button()
+        # For PM narrow switch
+        mocked_button.model.user_id_email_dict = {
+            1: '[email protected]',
+            2: '[email protected]',
+            3: '[email protected]',
+        }
 
         mocked_button._switch_narrow_to(parsed_link)
 
         assert (mocked_button.controller.narrow_to_stream.called
                 == narrow_to_stream_called)
         assert (mocked_button.controller.narrow_to_topic.called
                 == narrow_to_topic_called)
+        assert (mocked_button.controller.narrow_to_user.called
+                == narrow_to_user_called)
 
     @pytest.mark.parametrize(['error', 'set_footer_text_called',
                               '_switch_narrow_to_called',

zulipterminal/ui_tools/buttons.py

@@ -1,10 +1,10 @@
 import re
 from functools import partial
-from typing import Any, Callable, Dict, Optional, Tuple, Union, cast
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union, cast
 from urllib.parse import urljoin, urlparse
 
 import urwid
-from typing_extensions import TypedDict
+from typing_extensions import Literal, TypedDict
 
 from zulipterminal.config.keys import is_command_key, primary_key_for_command
 from zulipterminal.config.symbols import (
@@ -306,9 +306,15 @@ class DecodedStream(TypedDict):
     stream_name: Optional[str]
 
 
+class DecodedPM(TypedDict):
+    type: Literal['pm', 'group']
+    recipient_ids: List[int]
+
+
 class ParsedNarrowLink(TypedDict, total=False):
     narrow: str
     stream: DecodedStream
+    pm_with: DecodedPM
     topic_name: str
     message_id: Optional[int]
 
@@ -359,6 +365,22 @@ def _decode_stream_data(encoded_stream_data: str) -> DecodedStream:
             stream_name = hash_util_decode(encoded_stream_data)
             return DecodedStream(stream_id=None, stream_name=stream_name)
 
+    @staticmethod
+    def _decode_pm_data(encoded_pm_data: str) -> DecodedPM:
+        """
+        Returns a dict with PM type and IDs of PM recipients.
+        """
+        # Recipient ids (seperated by `,`) are of prime interest.
+        recipient_ids, *_ = encoded_pm_data.split('-')
+        recipient_ids_list = list(map(int, recipient_ids.split(',')))
+
+        # Currently webapp uses `pm` and `group` suffix interchangeably.
+        # Treat more-than-2 pms to group pms to avoid confusion.
+        pm_type = 'pm' if len(recipient_ids_list) < 3 else 'group'
+
+        return DecodedPM(type=Literal[pm_type],
+                         recipient_ids=recipient_ids_list)
+
     @staticmethod
     def _decode_message_id(message_id: str) -> Optional[int]:
         """
@@ -384,6 +406,12 @@ def _parse_narrow_link(cls, link: str) -> ParsedNarrowLink:
         #    {encoded.20topic.20name}
         # d. narrow/stream/[{stream_id}-]{stream-name}/topic/
         #    {encoded.20topic.20name}/near/{message_id}
+        # e. narrow/pm-with/[{recipient_ids},]-{pm-type}
+        # f. narrow/pm-with/[{recipient_ids},]-{pm-type}/near/{message_id}
+        # g. narrow/pm-with/{user_id}-user{user_id}
+        # h. narrow/pm-with/{user_id}-user{user_id}/near/{message_id}
+        # i. narrow/pm-with/{bot_id}-{bot-name}
+        # j. narrow/pm-with/{bot_id}-{bot-name}/near/{message_id}
         fragments = urlparse(link.rstrip('/')).fragment.split('/')
         len_fragments = len(fragments)
         parsed_link = ParsedNarrowLink()
@@ -414,6 +442,17 @@ def _parse_narrow_link(cls, link: str) -> ParsedNarrowLink:
             parsed_link = dict(narrow='stream:topic:near', stream=stream_data,
                                topic_name=topic_name, message_id=message_id)
 
+        elif (len_fragments == 5 and fragments[1] == 'pm-with'
+                and fragments[3] == 'near'):
+            pm_data = cls._decode_pm_data(fragments[2])
+            message_id = cls._decode_message_id(fragments[4])
+            parsed_link = dict(narrow='pm-with:near', pm_with=pm_data,
+                               message_id=message_id)
+
+        elif len_fragments == 3 and fragments[1] == 'pm-with':
+            pm_data = cls._decode_pm_data(fragments[2])
+            parsed_link = dict(narrow='pm-with', pm_with=pm_data)
+
         return parsed_link
 
     def _validate_and_patch_stream_data(self,
@@ -503,6 +542,22 @@ def _switch_narrow_to(self, parsed_link: ParsedNarrowLink) -> None:
                 topic_name=parsed_link['topic_name'],
                 contextual_message_id=parsed_link['message_id'],
             )
+        elif 'pm-with:near' == narrow:
+            emails = list(
+                self.model.user_id_email_dict.get(user_id)
+                for user_id in parsed_link['pm_with']['recipient_ids']
+            )
+            self.controller.narrow_to_user(
+                recipient_emails=emails,
+                contextual_message_id=parsed_link['message_id'],
+            )
+
+        elif 'pm-with' == narrow:
+            emails = list(
+                self.model.user_id_email_dict.get(user_id)
+                for user_id in parsed_link['pm_with']['recipient_ids']
+            )
+            self.controller.narrow_to_user(recipient_emails=emails)
 
     def handle_narrow_link(self) -> None:
         """