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

@@ -2,6 +2,7 @@
 
 import pytest
 from pytest import param as case
+from typing_extensions import Literal
 from urwid import AttrMap, Overlay
 
 from zulipterminal.config.keys import keys_for_command
@@ -364,6 +365,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, 2)
+
+        assert return_value == expected_response
+
     @pytest.mark.parametrize(
         "message_id, expected_return_value",
         [
@@ -415,6 +444,56 @@ def test__decode_message_id(self, message_id, expected_return_value):
                     "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/", {}),
             (SERVER_URL + "/#narrow/stream/1-Stream-1/topic/", {}),
@@ -427,6 +506,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",
@@ -435,7 +521,7 @@ def test__decode_message_id(self, message_id, expected_return_value):
         ],
     )
     def test__parse_narrow_link(self, link, expected_parsed_link):
-        return_value = MessageLinkButton._parse_narrow_link(link)
+        return_value = MessageLinkButton._parse_narrow_link(link, 1)
 
         assert return_value == expected_parsed_link
 
@@ -667,7 +753,12 @@ def test__validate_and_patch_stream_data(
         assert error == expected_error
 
     @pytest.mark.parametrize(
-        "parsed_link, narrow_to_stream_called, narrow_to_topic_called",
+        [
+            "parsed_link",
+            "narrow_to_stream_called",
+            "narrow_to_topic_called",
+            "narrow_to_user_called",
+        ],
         [
             (
                 {
@@ -676,6 +767,7 @@ def test__validate_and_patch_stream_data(
                 },
                 True,
                 False,
+                False,
             ),
             (
                 {
@@ -685,6 +777,7 @@ def test__validate_and_patch_stream_data(
                 },
                 False,
                 True,
+                False,
             ),
             (
                 {
@@ -694,6 +787,7 @@ def test__validate_and_patch_stream_data(
                 },
                 True,
                 False,
+                False,
             ),
             (
                 {
@@ -704,29 +798,80 @@ def test__validate_and_patch_stream_data(
                 },
                 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_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, report_error_called, _switch_narrow_to_called, exit_popup_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.api_types import EditPropagateMode
 from zulipterminal.config.keys import is_command_key, primary_key_for_command
@@ -322,9 +322,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]
 
@@ -375,6 +381,27 @@ 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, user_id: int) -> 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(",")))
+
+        no_of_recipients = len(recipient_ids_list)
+        # Bump no. of recipients tp include current user_id if not already
+        # present
+        if user_id not in recipient_ids_list:
+            no_of_recipients += 1
+
+        # Currently webapp uses `pm` and `group` suffix interchangeably.
+        # Treat more-than-2 pms to group pms to avoid confusion.
+        pm_type = "pm" if no_of_recipients < 3 else "group"
+
+        return DecodedPM(type=Literal[pm_type], recipient_ids=recipient_ids_list)
+
     @staticmethod
     def _decode_message_id(message_id: str) -> Optional[int]:
         """
@@ -386,7 +413,7 @@ def _decode_message_id(message_id: str) -> Optional[int]:
             return None
 
     @classmethod
-    def _parse_narrow_link(cls, link: str) -> ParsedNarrowLink:
+    def _parse_narrow_link(cls, link: str, user_id: int) -> ParsedNarrowLink:
         """
         Returns either a dict with narrow parameters for supported links or an
         empty dict.
@@ -400,6 +427,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()
@@ -440,6 +473,19 @@ def _parse_narrow_link(cls, link: str) -> ParsedNarrowLink:
                 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], user_id)
+            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], user_id)
+            parsed_link = dict(narrow="pm-with", pm_with=pm_data)
+
         return parsed_link
 
     def _validate_and_patch_stream_data(self, parsed_link: ParsedNarrowLink) -> str:
@@ -528,13 +574,29 @@ 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:
         """
         Narrows to the respective narrow if the narrow link is valid or updates
         the footer with an appropriate validation error message.
         """
-        parsed_link = self._parse_narrow_link(self.link)
+        parsed_link = self._parse_narrow_link(self.link, self.model.user_id)
         error = self._validate_narrow_link(parsed_link)
 
         if error: