From ea89e95857a4fb9e2400ec0835b5d856511c3f93 Mon Sep 17 00:00:00 2001
From: "neiljp (Neil Pilgrim)" <github@kepier.clara.net>
Date: Fri, 19 Nov 2021 21:54:53 -0800
Subject: [PATCH] api: Add Literal types for various important message flags.

With some copy-editing by tabbott.
---
 zulip/setup.py          |  1 +
 zulip/zulip/__init__.py | 35 ++++++++++++++++++++++++++++++++++-
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/zulip/setup.py b/zulip/setup.py
index cd0806c..3ae35e4 100755
--- a/zulip/setup.py
+++ b/zulip/setup.py
@@ -71,6 +71,7 @@ setuptools_info = dict(
         "matrix_client",
         "distro",
         "click",
+        "typing_extensions>=3.7",
     ],
 )
 
diff --git a/zulip/zulip/__init__.py b/zulip/zulip/__init__.py
index 0b6ac52..4f78683 100644
--- a/zulip/zulip/__init__.py
+++ b/zulip/zulip/__init__.py
@@ -28,6 +28,7 @@ from typing import (
 
 import distro
 import requests
+from typing_extensions import Literal
 
 __version__ = "0.8.1"
 
@@ -44,6 +45,38 @@ requests_json_is_function = callable(requests.Response.json)
 
 API_VERSTRING = "v1/"
 
+# An optional parameter to `move_topic` and `update_message` actions
+# See eg. https://zulip.com/api/update-message#parameter-propagate_mode
+EditPropagateMode = Literal["change_one", "change_all", "change_later"]
+
+# Generally a `reaction_type` is present whenever an emoji is specified:
+# - Optional parameters to actions: `add_reaction`, `remove_reaction`
+# - Events: "user_status", "reaction", "message", "update_message"
+# - Inside each reaction in the `reactions` field of returned message objects.
+EmojiType = Literal["realm_emoji", "unicode_emoji", "zulip_extra_emoji"]
+
+# Message flags which may be directly modified by the current user:
+# - Updated by `update_message_flags` (and for the `read` flag, also
+#   the `mark_all_as_read`, `mark_stream_as_read`, and
+#   `mark_topic_as_read` actions.
+# - User is notified of changes via `update_message_flags` events.
+# See subset of https://zulip.com/api/update-message-flags#available-flags
+ModifiableMessageFlag = Literal["read", "starred", "collapsed"]
+
+# All possible message flags.
+# - Generally present in `flags` object of returned message objects.
+# - User is notified of changes via "update_message_flags" and `update_message`
+#   events. The latter is important for clients to learn when a message is
+#   edited to mention the current user or contain an alert word.
+# See https://zulip.com/api/update-message-flags#available-flags
+MessageFlag = Literal[
+    ModifiableMessageFlag,
+    "mentioned",
+    "wildcard_mentioned",
+    "has_alert_word",
+    "historical",
+]
+
 
 class CountingBackoff:
     def __init__(
@@ -1638,7 +1671,7 @@ class Client:
         topic: str,
         new_topic: Optional[str] = None,
         message_id: Optional[int] = None,
-        propagate_mode: str = "change_all",
+        propagate_mode: EditPropagateMode = "change_all",
         notify_old_topic: bool = True,
         notify_new_topic: bool = True,
     ) -> Dict[str, Any]: