narrow: Split out narrow_helpers.

This will make more sense as I get deeper into modernizing
how we accept narrows from users via the API and represent
the narrows in event queues.

zerver/lib/events.py

@@ -35,11 +35,8 @@ from zerver.lib.message import (
     remove_message_id_from_unread_mgs,
 )
 from zerver.lib.muted_users import get_user_mutes
-from zerver.lib.narrow import (
-    NarrowTerm,
-    check_narrow_for_events,
-    read_stop_words,
-)
+from zerver.lib.narrow import check_narrow_for_events, read_stop_words
+from zerver.lib.narrow_helpers import NarrowTerm
 from zerver.lib.presence import get_presence_for_user, get_presences_for_realm
 from zerver.lib.push_notifications import push_notifications_enabled
 from zerver.lib.realm_icon import realm_icon_url

zerver/lib/home.py

@@ -15,7 +15,7 @@ from zerver.lib.i18n import (
     get_language_list,
     get_language_translation_data,
 )
-from zerver.lib.narrow import NarrowTerm
+from zerver.lib.narrow_helpers import NarrowTerm
 from zerver.lib.realm_description import get_realm_rendered_description
 from zerver.lib.request import RequestNotes
 from zerver.models import Message, Realm, Stream, UserProfile

zerver/lib/narrow.py

@@ -47,6 +47,7 @@ from sqlalchemy.types import ARRAY, Boolean, Integer, Text
 from zerver.lib.addressee import get_user_profiles, get_user_profiles_by_ids
 from zerver.lib.exceptions import ErrorCode, JsonableError
 from zerver.lib.message import get_first_visible_message_id
+from zerver.lib.narrow_helpers import NarrowTerm
 from zerver.lib.recipient_users import recipient_for_user_profiles
 from zerver.lib.sqlalchemy_utils import get_sqlalchemy_connection
 from zerver.lib.streams import (
@@ -85,25 +86,9 @@ from zerver.models import (
     get_user_including_cross_realm,
 )
 
-
-@dataclass
-class NarrowTerm:
-    # In our current use case we don't yet handle negated narrow terms.
-    operator: str
-    operand: str
-
-
 stop_words_list: Optional[List[str]] = None
 
 
-def narrow_dataclasses_from_tuples(tups: Collection[Sequence[str]]) -> Collection[NarrowTerm]:
-    """
-    This method assumes that the callers are in our event-handling codepath, and
-    therefore as of summer 2023, they do not yet support the "negated" flag.
-    """
-    return [NarrowTerm(operator=tup[0], operand=tup[1]) for tup in tups]
-
-
 def read_stop_words() -> List[str]:
     global stop_words_list
     if stop_words_list is None:

zerver/lib/narrow_helpers.py

@@ -0,0 +1,36 @@
+"""
+This module partly exists to prevent circular dependencies.
+
+It also isolates some fairly yucky code related to the fact
+that we have to support two formats of narrow specifications
+from users:
+
+    legacy:
+        [["stream", "devel"], ["is", mentioned"]
+
+    modern:
+        [
+            {"operator": "stream", "operand": "devel", "negated": "false"},
+            {"operator": "is", "operand": "mentioned", "negated": "false"},
+        ]
+
+    And then on top of that, we want to represent narrow
+    specification internally as dataclasses.
+"""
+from dataclasses import dataclass
+from typing import Collection, Sequence
+
+
+@dataclass
+class NarrowTerm:
+    # In our current use case we don't yet handle negated narrow terms.
+    operator: str
+    operand: str
+
+
+def narrow_dataclasses_from_tuples(tups: Collection[Sequence[str]]) -> Collection[NarrowTerm]:
+    """
+    This method assumes that the callers are in our event-handling codepath, and
+    therefore as of summer 2023, they do not yet support the "negated" flag.
+    """
+    return [NarrowTerm(operator=tup[0], operand=tup[1]) for tup in tups]

zerver/tests/test_message_fetch.py

@@ -30,7 +30,6 @@ from zerver.lib.narrow import (
     LARGER_THAN_MAX_MESSAGE_ID,
     BadNarrowOperatorError,
     NarrowBuilder,
-    NarrowTerm,
     build_narrow_predicate,
     exclude_muting_conditions,
     find_first_unread_anchor,
@@ -38,6 +37,7 @@ from zerver.lib.narrow import (
     ok_to_include_history,
     post_process_limited_query,
 )
+from zerver.lib.narrow_helpers import NarrowTerm
 from zerver.lib.sqlalchemy_utils import get_sqlalchemy_connection
 from zerver.lib.streams import StreamDict, create_streams_if_needed, get_public_streams_queryset
 from zerver.lib.test_classes import ZulipTestCase

zerver/tornado/event_queue.py

@@ -39,7 +39,8 @@ from tornado import autoreload
 from version import API_FEATURE_LEVEL, ZULIP_MERGE_BASE, ZULIP_VERSION
 from zerver.lib.exceptions import JsonableError
 from zerver.lib.message import MessageDict
-from zerver.lib.narrow import build_narrow_predicate, narrow_dataclasses_from_tuples
+from zerver.lib.narrow import build_narrow_predicate
+from zerver.lib.narrow_helpers import narrow_dataclasses_from_tuples
 from zerver.lib.notification_data import UserMessageNotificationsData
 from zerver.lib.queue import queue_json_publish, retry_event
 from zerver.middleware import async_request_timer_restart

zerver/views/events_register.py

@@ -9,7 +9,7 @@ from zerver.context_processors import get_valid_realm_from_request
 from zerver.lib.compatibility import is_pronouns_field_type_supported
 from zerver.lib.events import do_events_register
 from zerver.lib.exceptions import JsonableError, MissingAuthenticationError
-from zerver.lib.narrow import narrow_dataclasses_from_tuples
+from zerver.lib.narrow_helpers import narrow_dataclasses_from_tuples
 from zerver.lib.request import REQ, RequestNotes, has_request_variables
 from zerver.lib.response import json_success
 from zerver.lib.validator import check_bool, check_dict, check_int, check_list, check_string

zerver/views/home.py

@@ -13,7 +13,7 @@ from zerver.decorator import web_public_view, zulip_login_required
 from zerver.forms import ToSForm
 from zerver.lib.compatibility import is_outdated_desktop_app, is_unsupported_browser
 from zerver.lib.home import build_page_params_for_home_page_load, get_user_permission_info
-from zerver.lib.narrow import NarrowTerm
+from zerver.lib.narrow_helpers import NarrowTerm
 from zerver.lib.request import RequestNotes
 from zerver.lib.streams import access_stream_by_name
 from zerver.lib.subdomains import get_subdomain