zulipcli 0.3__tar.gz → 0.4__tar.gz

{zulipcli-0.3 → zulipcli-0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zulipcli
-Version: 0.3
+Version: 0.4
 Summary: Command-line interface for Zulip
 License-Expression: MIT
 License-File: LICENSE

{zulipcli-0.3 → zulipcli-0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "zulipcli"
-version = "0.3"
+version = "0.4"
 description = "Command-line interface for Zulip"
 authors = [
   {name = "Daniel Bosk", email = "daniel@bosk.se"}

{zulipcli-0.3 → zulipcli-0.4}/src/zulipcli/cli.nw

@@ -32,6 +32,7 @@ option names, and argument values.
 <<[[cli.py]]>>=
 """Command-line interface for Zulip."""
 
+import configparser
 from datetime import datetime, timezone
 from pathlib import Path
 import re
@@ -42,6 +43,7 @@ from typing import Annotated, Optional
 from rich.console import Console
 from rich.markdown import Markdown
 import typer
+import zulip
 
 import zulipcli
 
@@ -56,16 +58,29 @@ def main():
 
 \section{Argument parsing}
 
-The top-level Typer application accepts a \texttt{-{}-zuliprc} option to
-override the default configuration file path.
-The callback stores that override in the root context, so each
+The module still exposes a standalone [[app]] whose callback accepts
+\texttt{-{}-zuliprc} to override the default configuration file path.
+That callback stores the resolved path in the root context, so each
 subcommand can ask one helper for a configured client.
 Typing the option as a [[Path]] also gives us filesystem completion for
 free.
 
+We also expose [[build_embedded_app()]] for host applications that want
+to mount the same command tree under their own subcommand name.
+The embedded form declares no root options, so the host can choose the
+mount name with [[add_typer()]] and populate [[ctx.obj["zuliprc"]]] in
+its own callback.
+The standalone form keeps Typer's completion-installation flags, while
+the embedded form disables them by default so the host owns that
+surface.
+
+<<constants>>=
+APP_HELP = "Command-line interface for Zulip"
+@
+
 <<functions>>=
 app = typer.Typer(
-    help="Command-line interface for Zulip",
+    help=APP_HELP,
     add_completion=True,
     no_args_is_help=True,
 )
@@ -84,24 +99,83 @@ def configure_app(
     ] = None,
 ):
     """Configure shared CLI options."""
-    ctx.obj = {
-        "zuliprc": None if zuliprc is None else str(zuliprc),
-    }
+    ctx.ensure_object(dict)
+    if zuliprc is not None:
+        ctx.obj["zuliprc"] = str(zuliprc)
+    else:
+        ctx.obj.setdefault("zuliprc", None)
+@
+
+<<functions>>=
+def _get_root_zuliprc(ctx: typer.Context):
+    """Return the zuliprc override stored in the root context."""
+    root_ctx = ctx.find_root()
+    obj = getattr(root_ctx, "obj", None) or {}
+    if "zuliprc" in obj:
+        return obj["zuliprc"]
+    params = getattr(root_ctx, "params", None) or {}
+    return params.get("zuliprc")
 @
 
+Client construction can fail before any API call if the configured
+[[zuliprc]] path is missing or malformed.
+Those failures are still ordinary command-line errors, so we report them
+through the same [[Error: ...]] path instead of showing a traceback.
+
 <<functions>>=
 def _get_client_from_context(ctx):
     """Create a Zulip client from the current Typer context."""
-    root_ctx = ctx.find_root()
-    obj = root_ctx.obj or {}
-    return zulipcli.get_client(obj.get("zuliprc"))
+    try:
+        return zulipcli.get_client(_get_root_zuliprc(ctx))
+    except (configparser.Error, zulip.ZulipError) as error:
+        _exit_with_error(str(error))
 @
 
+The standalone and embedded applications share the same command
+handlers.
+We therefore build the embedded Typer application as a fresh object,
+normalise its context in a minimal callback, and register the shared
+handlers onto it.
+That keeps the standalone and embedded command surfaces aligned without
+forcing either form to own the other's root options.
+
+<<functions>>=
+def build_embedded_app(
+    *,
+    help: Optional[str] = None,
+    add_completion: bool = False,
+    no_args_is_help: bool = True,
+) -> typer.Typer:
+    """Return a Typer app suitable for mounting in another Typer app.
+
+    Example:
+        parent = typer.Typer()
+        parent.add_typer(build_embedded_app(), name="zulip")
+
+    The host callback should store the resolved zuliprc path in
+    ``ctx.obj["zuliprc"]`` before the embedded commands run.
+    """
+    embedded_app = typer.Typer(
+        help=APP_HELP if help is None else help,
+        add_completion=add_completion,
+        no_args_is_help=no_args_is_help,
+    )
 
-\section{Reporting Zulip API errors}
+    @embedded_app.callback()
+    def configure_embedded_app(ctx: typer.Context):
+        """Prepare shared CLI state for embedded use."""
+        ctx.ensure_object(dict)
+        ctx.obj.setdefault("zuliprc", None)
 
-The ordinary commands should all report Zulip API failures in the same
-way: print the server's message on stderr and exit with status [[1]].
+    _register_commands(embedded_app)
+    return embedded_app
+@
+
+
+\section{Reporting Zulip errors}
+
+The ordinary commands should all report user-facing Zulip failures in
+the same way: print the message on stderr and exit with status [[1]].
 Factoring that policy into two helpers keeps each command focused on its
 own data handling instead of repeating the same error-checking branch.
 
@@ -135,17 +209,17 @@ If the client cannot be created or a Zulip API request fails, we simply
 return no candidates.
 
 Typer also gives completion callbacks the parsed command context.
-That is enough for this CLI: the root context carries the top-level
-[[--zuliprc]] override, and the active command context already contains
-the selected stream for [[read TOPIC]] and [[send --topic TOPIC]].
+That is enough for this CLI: the root context carries the resolved
+[[zuliprc]] path, whether it came from the standalone [[--zuliprc]]
+option or a host application's callback, and the active command context
+already contains the selected stream for [[read TOPIC]] and
+[[send --topic TOPIC]].
 
 <<functions>>=
 def _get_completion_client(ctx: typer.Context):
     """Create a Zulip client for shell completion lookups."""
-    root_ctx = ctx.find_root()
-    zuliprc = (root_ctx.params or {}).get("zuliprc")
     try:
-        return zulipcli.get_client(zuliprc)
+        return zulipcli.get_client(_get_root_zuliprc(ctx))
     except Exception:
         return None
 @
@@ -249,9 +323,9 @@ def complete_user_emails(ctx: typer.Context, incomplete: str):
     return completions
 @
 
-Let's verify that the Typer application still shows help when invoked
-without a subcommand and that the shared [[--zuliprc]] option reaches
-both commands and completion callbacks.
+Let's verify both CLI entry styles: the standalone application still
+accepts [[--zuliprc]], while the embedded factory exposes the same
+subcommands without claiming that root option for itself.
 
 <<test [[cli.py]]>>=
 """Tests for zulipcli.cli."""
@@ -261,6 +335,7 @@ import io
 from types import SimpleNamespace
 
 import pytest
+import typer
 from click.shell_completion import _resolve_context, _resolve_incomplete
 from typer.main import get_command
 from typer.testing import CliRunner
@@ -315,6 +390,121 @@ def test_cli_passes_zuliprc_to_commands(monkeypatch):
     assert seen["zuliprc"] == "/tmp/custom.zuliprc"
 @
 
+<<test functions>>=
+def test_cli_reports_missing_zuliprc_without_traceback(monkeypatch):
+    def get_client(zuliprc=None):
+        raise cli.zulip.ConfigNotFoundError(
+            "api_key or email not specified and file "
+            "/tmp/missing.zuliprc does not exist"
+        )
+
+    monkeypatch.setattr(cli.zulipcli, "get_client", get_client)
+
+    result = runner.invoke(
+        app,
+        ["--zuliprc", "/tmp/missing.zuliprc", "users"],
+    )
+
+    assert result.exit_code == 1
+    assert result.output == (
+        "Error: api_key or email not specified and file "
+        "/tmp/missing.zuliprc does not exist\n"
+    )
+@
+
+<<test functions>>=
+def test_embedded_app_mounts_under_custom_name(monkeypatch):
+    client = MagicMock()
+    client.get_streams.return_value = {
+        "result": "success",
+        "streams": [],
+    }
+    monkeypatch.setattr(
+        cli.zulipcli,
+        "get_client",
+        lambda zuliprc=None: client,
+    )
+
+    parent = typer.Typer()
+    parent.add_typer(cli.build_embedded_app(), name="zulip")
+
+    result = runner.invoke(parent, ["zulip", "streams"])
+
+    assert result.exit_code == 0
+    client.get_streams.assert_called_once_with()
+@
+
+<<test functions>>=
+def test_embedded_app_has_no_zuliprc_option():
+    command = get_command(cli.build_embedded_app())
+
+    assert "--zuliprc" not in {
+        option
+        for param in command.params
+        for option in getattr(param, "opts", [])
+    }
+@
+
+<<test functions>>=
+def test_embedded_app_reads_zuliprc_from_parent_ctx_obj(monkeypatch):
+    client = MagicMock()
+    client.get_streams.return_value = {
+        "result": "success",
+        "streams": [],
+    }
+    seen = {}
+
+    def get_client(zuliprc=None):
+        seen["zuliprc"] = zuliprc
+        return client
+
+    monkeypatch.setattr(cli.zulipcli, "get_client", get_client)
+
+    parent = typer.Typer()
+
+    @parent.callback()
+    def configure_parent(ctx: typer.Context):
+        ctx.ensure_object(dict)
+        ctx.obj["zuliprc"] = "/tmp/fake.zuliprc"
+
+    parent.add_typer(cli.build_embedded_app(), name="zulip")
+
+    result = runner.invoke(parent, ["zulip", "streams"])
+
+    assert result.exit_code == 0
+    assert seen["zuliprc"] == "/tmp/fake.zuliprc"
+@
+
+<<test functions>>=
+def test_standalone_app_still_has_zuliprc_option():
+    command = get_command(app)
+
+    assert "--zuliprc" in {
+        option
+        for param in command.params
+        for option in getattr(param, "opts", [])
+    }
+@
+
+<<test functions>>=
+def test_standalone_callback_preserves_existing_ctx_obj():
+    class DummyContext:
+        def __init__(self):
+            self.obj = {"course": "DD1337"}
+
+        def ensure_object(self, object_type):
+            if self.obj is None:
+                self.obj = object_type()
+            return self.obj
+
+    ctx = DummyContext()
+
+    cli.configure_app(ctx)
+
+    assert ctx.obj["course"] == "DD1337"
+    assert ctx.obj["zuliprc"] is None
+@
+
 <<test functions>>=
 def test_stream_completion_uses_zuliprc_override(monkeypatch):
     client = MagicMock()
@@ -331,7 +521,8 @@ def test_stream_completion_uses_zuliprc_override(monkeypatch):
     monkeypatch.setattr(cli.zulipcli, "get_client", get_client)
     assert complete_stream_names(
         SimpleNamespace(find_root=lambda: SimpleNamespace(
-            params={"zuliprc": "/tmp/custom.zuliprc"},
+            obj={"zuliprc": "/tmp/custom.zuliprc"},
+            params={},
         )),
         "g",
     ) == ["general"]
@@ -372,8 +563,7 @@ By default we exclude bots and deactivated users, since the common use
 case is finding a human colleague's email address.
 
 <<functions>>=
-@app.command("users")
-def users(
+def _users_handler(
     ctx: typer.Context,
     pattern: Annotated[
         Optional[str],
@@ -563,8 +753,7 @@ Reading from stdin is useful for piping output from other commands
 directly into a Zulip message, which is a common scripting pattern.
 
 <<functions>>=
-@app.command("send")
-def send(
+def _send_handler(
     ctx: typer.Context,
     stream: Annotated[
         Optional[str],
@@ -794,8 +983,7 @@ on a server with many streams where the web interface's sidebar
 becomes unwieldy.
 
 <<functions>>=
-@app.command("streams")
-def streams(
+def _streams_handler(
     ctx: typer.Context,
     pattern: Annotated[
         Optional[str],
@@ -879,8 +1067,7 @@ identifier, so we first resolve the human-readable stream name via
 [[get_stream_id()]].
 
 <<functions>>=
-@app.command("topics")
-def topics(
+def _topics_handler(
     ctx: typer.Context,
     stream: Annotated[
         str,
@@ -999,13 +1186,21 @@ immediately after the most recent batch we just printed.
 That yields oldest-to-newest output without collecting the whole history
 in memory first.
 
+Unread filtering is still just another Zulip narrow term, so the command
+can expose it as a boolean option without changing the pagination logic.
+
+Marking messages as read needs more care. We should only acknowledge
+messages that actually reached stdout, so we collect the IDs of messages
+whose printing succeeded and update their flags only after the whole read
+finishes. That way an encoding failure or broken pipe cannot silently
+mark unseen messages as read.
+
 <<constants>>=
 HISTORY_BATCH_SIZE = 1000
 @
 
 <<functions>>=
-@app.command("read")
-def read(
+def _read_handler(
     ctx: typer.Context,
     stream: Annotated[
         str,
@@ -1021,14 +1216,54 @@ def read(
             autocompletion=complete_topic_names,
         ),
     ] = None,
+    unread: Annotated[
+        bool,
+        typer.Option(
+            "--unread",
+            "-U",
+            help="only show unread messages",
+        ),
+    ] = False,
+    mark_as_read: Annotated[
+        bool,
+        typer.Option(
+            "--mark-as-read/--no-mark-as-read",
+            help="mark printed messages as read",
+        ),
+    ] = False,
 ):
     """Read messages from a stream or topic."""
     read_command(
         _get_client_from_context(ctx),
-        SimpleNamespace(stream=stream, topic=topic),
+        SimpleNamespace(
+            stream=stream,
+            topic=topic,
+            unread=unread,
+            mark_as_read=mark_as_read,
+        ),
     )
 @
 
+The standalone and embedded applications must expose the same five
+subcommands.
+We therefore register the handlers through one helper that binds the
+shared command implementations to whichever [[typer.Typer]] instance we
+are constructing.
+
+<<functions>>=
+def _register_commands(target: typer.Typer) -> None:
+    """Register Zulip subcommands on ``target``."""
+    target.command("users")(_users_handler)
+    target.command("send")(_send_handler)
+    target.command("streams")(_streams_handler)
+    target.command("topics")(_topics_handler)
+    target.command("read")(_read_handler)
+@
+
+<<functions>>=
+_register_commands(app)
+@
+
 The output needs to stay readable for both a whole stream and a single
 topic.
 We therefore print a UTC timestamp, sender, and topic on the first
@@ -1077,6 +1312,8 @@ def _print_read_message(message):
 The request stays constant across pages except for the anchor.
 Each successful batch is printed immediately, and then the anchor moves
 to one past the last message ID we have already seen.
+If the caller asked to mark messages as read, we defer that update until
+after every page has been printed successfully.
 
 <<functions>>=
 def read_command(client, args):
@@ -1093,7 +1330,12 @@ def read_command(client, args):
         request["narrow"].append(
             {"operator": "topic", "operand": args.topic}
         )
+    if args.unread:
+        request["narrow"].append(
+            {"operator": "is", "operand": "unread"}
+        )
 
+    printed_message_ids = [] if args.mark_as_read else None
     found_newest = False
     while not found_newest:
         result = _require_success(client.get_messages(request))
@@ -1102,7 +1344,75 @@ def read_command(client, args):
         if result["messages"]:
             for message in result["messages"]:
                 _print_read_message(message)
+                if printed_message_ids is not None:
+                    printed_message_ids.append(message["id"])
             request["anchor"] = result["messages"][-1]["id"] + 1
+
+    if printed_message_ids:
+        _require_success(client.update_message_flags({
+            "messages": printed_message_ids,
+            "op": "add",
+            "flag": "read",
+        }))
+@
+
+Let's verify that the CLI forwards the new filtering and acknowledgement
+flags to [[read_command()]].
+
+<<test functions>>=
+def test_read_cli_passes_unread_and_mark_as_read_flags(monkeypatch):
+    seen = {}
+
+    def fake_read_command(client, args):
+        seen["client"] = client
+        seen["args"] = args
+
+    monkeypatch.setattr(cli, "read_command", fake_read_command)
+    monkeypatch.setattr(
+        cli,
+        "_get_client_from_context",
+        lambda ctx: "client",
+    )
+
+    result = runner.invoke(
+        app,
+        ["read", "general", "-U", "--mark-as-read"],
+    )
+
+    assert result.exit_code == 0
+    assert seen["client"] == "client"
+    assert seen["args"].stream == "general"
+    assert seen["args"].topic is None
+    assert seen["args"].unread is True
+    assert seen["args"].mark_as_read is True
+@
+
+We should also verify the default parser behaviour: without either flag,
+[[read]] should include all messages and leave them unread.
+
+<<test functions>>=
+def test_read_cli_defaults_to_all_messages_without_marking(monkeypatch):
+    seen = {}
+
+    def fake_read_command(client, args):
+        seen["client"] = client
+        seen["args"] = args
+
+    monkeypatch.setattr(cli, "read_command", fake_read_command)
+    monkeypatch.setattr(
+        cli,
+        "_get_client_from_context",
+        lambda ctx: "client",
+    )
+
+    result = runner.invoke(app, ["read", "general"])
+
+    assert result.exit_code == 0
+    assert seen["client"] == "client"
+    assert seen["args"].stream == "general"
+    assert seen["args"].topic is None
+    assert seen["args"].unread is False
+    assert seen["args"].mark_as_read is False
 @
 
 Let's build a small helper for synthetic history payloads.
@@ -1145,7 +1455,12 @@ def test_read_stream_uses_stream_name(capsys, monkeypatch):
 
     client = MagicMock()
     client.get_messages.side_effect = get_messages
-    args = SimpleNamespace(stream="general", topic=None)
+    args = SimpleNamespace(
+        stream="general",
+        topic=None,
+        unread=False,
+        mark_as_read=False,
+    )
     monkeypatch.setattr(cli, "_stdout_is_tty", lambda: False)
     read_command(client, args)
 
@@ -1164,6 +1479,7 @@ def test_read_stream_uses_stream_name(capsys, monkeypatch):
         "1970-01-01T00:00:00Z\tAlice Admin\tAnnouncements\n"
         "Hello stream\n\n"
     )
+    client.update_message_flags.assert_not_called()
 @
 
 We should also verify that interactive terminals render Markdown through
@@ -1198,7 +1514,12 @@ def test_read_renders_markdown_on_tty(capsys, monkeypatch):
 
     client = MagicMock()
     client.get_messages.return_value = response
-    args = SimpleNamespace(stream="general", topic=None)
+    args = SimpleNamespace(
+        stream="general",
+        topic=None,
+        unread=False,
+        mark_as_read=False,
+    )
     monkeypatch.setattr(cli, "_stdout_is_tty", lambda: True)
     monkeypatch.setattr(cli, "Console", FakeConsole)
     monkeypatch.setattr(cli, "Markdown", FakeMarkdown)
@@ -1211,6 +1532,157 @@ def test_read_renders_markdown_on_tty(capsys, monkeypatch):
     )
 @
 
+We should also verify that unread reads add Zulip's [[is:unread]]
+narrow and only mark messages after they have all been printed.
+
+<<test functions>>=
+def test_read_unread_narrows_and_marks_after_printing(monkeypatch):
+    response = {
+        "result": "success",
+        "found_newest": True,
+        "messages": [
+            _make_stream_message(
+                1,
+                0,
+                "Alice Admin",
+                "Announcements",
+                "First message",
+            ),
+            _make_stream_message(
+                2,
+                60,
+                "Bob Builder",
+                "Announcements",
+                "Second message",
+            ),
+        ],
+    }
+    requests = []
+    events = []
+
+    def get_messages(request):
+        requests.append(copy.deepcopy(request))
+        return response
+
+    def print_message(message):
+        events.append(("print", message["id"]))
+
+    def update_message_flags(request):
+        events.append(("mark", copy.deepcopy(request)))
+        return {"result": "success"}
+
+    client = MagicMock()
+    client.get_messages.side_effect = get_messages
+    client.update_message_flags.side_effect = update_message_flags
+    args = SimpleNamespace(
+        stream="general",
+        topic=None,
+        unread=True,
+        mark_as_read=True,
+    )
+    monkeypatch.setattr(cli, "_print_read_message", print_message)
+
+    read_command(client, args)
+
+    assert requests == [{
+        "anchor": 0,
+        "num_before": 0,
+        "num_after": HISTORY_BATCH_SIZE,
+        "narrow": [
+            {"operator": "stream", "operand": "general"},
+            {"operator": "is", "operand": "unread"},
+        ],
+        "client_gravatar": False,
+        "apply_markdown": False,
+    }]
+    assert events == [
+        ("print", 1),
+        ("print", 2),
+        ("mark", {
+            "messages": [1, 2],
+            "op": "add",
+            "flag": "read",
+        }),
+    ]
+@
+
+Empty history should not trigger a flag update even when the user asks
+for one.
+
+<<test functions>>=
+def test_read_mark_as_read_skips_empty_history():
+    client = MagicMock()
+    client.get_messages.return_value = {
+        "result": "success",
+        "found_newest": True,
+        "messages": [],
+    }
+    args = SimpleNamespace(
+        stream="general",
+        topic=None,
+        unread=False,
+        mark_as_read=True,
+    )
+
+    read_command(client, args)
+
+    client.update_message_flags.assert_not_called()
+@
+
+If printing fails midway, we should not mark even the earlier messages as
+read. The user has only seen a partial transcript.
+
+<<test functions>>=
+def test_read_does_not_mark_messages_when_printing_fails(monkeypatch):
+    client = MagicMock()
+    client.get_messages.return_value = {
+        "result": "success",
+        "found_newest": True,
+        "messages": [
+            _make_stream_message(
+                1,
+                0,
+                "Alice Admin",
+                "Announcements",
+                "First message",
+            ),
+            _make_stream_message(
+                2,
+                60,
+                "Bob Builder",
+                "Announcements",
+                "Second message",
+            ),
+        ],
+    }
+    args = SimpleNamespace(
+        stream="general",
+        topic=None,
+        unread=False,
+        mark_as_read=True,
+    )
+    seen = []
+
+    def print_message(message):
+        seen.append(message["id"])
+        if message["id"] == 2:
+            raise UnicodeEncodeError(
+                "ascii",
+                "å",
+                0,
+                1,
+                "ordinal not in range(128)",
+            )
+
+    monkeypatch.setattr(cli, "_print_read_message", print_message)
+
+    with pytest.raises(UnicodeEncodeError):
+        read_command(client, args)
+
+    assert seen == [1, 2]
+    client.update_message_flags.assert_not_called()
+@
+
 We can also verify that topic reads keep both names in the narrow and
 advance the anchor when the history spans more than one API page.
 
@@ -1255,6 +1727,8 @@ def test_read_topic_pages_through_history(capsys, monkeypatch):
     args = SimpleNamespace(
         stream="general",
         topic="release planning",
+        unread=False,
+        mark_as_read=False,
     )
     monkeypatch.setattr(cli, "_stdout_is_tty", lambda: False)
     read_command(client, args)
@@ -1291,7 +1765,12 @@ def test_read_reports_history_errors(capsys):
         "result": "error",
         "msg": "Invalid narrow operator",
     }
-    args = SimpleNamespace(stream="general", topic=None)
+    args = SimpleNamespace(
+        stream="general",
+        topic=None,
+        unread=False,
+        mark_as_read=False,
+    )
 
     with pytest.raises(SystemExit) as excinfo:
         read_command(client, args)