zulip-term 0.7.0

近期更改 | 配置 | 快捷键 | 常见问题解答 | 开发 | 教程

关于

Zulip终端是Zulip的官方终端客户端，提供了一种基于文本的用户界面（TUI）。

具体目标包括

• 提供与Zulip网页客户端类似的用户体验，最终支持其所有功能
• 通过键盘实现所有操作（请参阅快捷键）
• 探索适合显示和输入限制的替代用户界面设计
• 支持广泛的平台和终端仿真器
• 充分利用可用的行/列数，从80x24向上扩展（请参阅小型终端说明）

通过我们的教程了解如何使用Zulip终端。

功能状态

我们认为客户端已经提供了一种相当稳定且功能丰富的日常用户体验。

终端客户端目前与Zulip网页客户端存在一些有意的不同之处

• 额外的快捷键以及偶尔的不同快捷键，以更好地支持仅键盘导航；除了方向移动之外，还包括
  • z - 放大/缩小，在流和主题之间，或在所有私人消息和特定对话之间
  • t - 切换左侧面板中流的主题视图（后来被网页客户端用于最近的主题）
  • # - 窄化到提到你的消息（@ 已被使用）
  • f - 窄化到你已标记的消息（关注）
• 当可见对话结束时不会标记额外的消息为已读（请参阅常见问题解答条目）
• 表情符号和反应仅以文本形式呈现，以最大程度地兼容终端/字体
• 脚注链接 - 链接（URL）的脚注 - 使消息可读，同时保留链接列表以供交叉引用
• 在网页客户端中可预览的内容（如图片）也作为脚注存储

当前的开发重点是改进更常使用的日常使用方面 - 以减少用户因特定功能而临时切换到另一个客户端的需要。

我们预计只能长期解决的当前限制包括

• 所有具有额外权限（所有者/管理员）的用户执行的操作
• 访问和更新所有设置
• 使用鼠标/指针完成所有操作
• 国际化UI

有关缺失功能支持的查询，请参阅我们的常见问题解答（FAQ）、我们的公开问题或注册https://chat.zulip.org并参与#zulip-terminal流中的用户和开发者聊天！

支持的平台

• Linux
• OSX
• WSL（在Windows上）

支持的服务器版本

Zulip终端支持的最小服务器版本是2.1.0。它可能仍然可以与早期版本兼容。

支持的Python版本

版本0.6.0是最后一个支持Python 3.5的版本。

后续版本和主开发分支目前在Ubuntu上使用

• CPython 3.6-3.10
• PyPy 3.6-3.9

由于我们的自动化测试不包括UI的交互式测试，因此某些Python版本可能会有问题，尽管通常我们没有发现这种情况。

请注意，我们通常将每个发布版限制在较低的Python版本和较高的Python版本之间，因此如果您的Python版本较新，则某些发布版（或main）可能无法正确安装。在某些情况下，这可能会导致问题#1145中的症状。

安装

我们建议在专用的Python虚拟环境中安装（见下文）或使用自动选项，例如pipx

• 稳定版 - 编号的稳定发布版可在PyPI上作为zulip-term软件包获取

  要安装，请运行以下命令之一：pip3 install zulip-term

• 最新版 - 最新开发版本可以从主git仓库安装

  要安装，请运行以下命令之一：pip3 install git+https://github.com/zulip/zulip-terminal.git@main

我们还提供了一些示例Dockerfile，用于在docker/中构建docker镜像。

在隔离的Python虚拟环境中安装

由于运行需要Python 3.6+，以下命令应在大多数系统上正常工作

1. python3 -m venv zt_venv（在当前目录中创建名为zt_venv的虚拟环境）
2. source zt_venv/bin/activate（激活虚拟环境；这假设您使用的是类似bash的shell）
3. 运行上述安装命令之一

如果您打开不同的终端窗口（或注销/重启计算机），在运行zulip-term之前，您需要再次运行上述列表中的步骤2，因为这将激活该虚拟环境。您可以在Python 3库venv文档中了解更多关于虚拟环境的信息。

保持您的安装更新

稳定发布版可在PyPI和GitHub上获得；为确保您与它们保持更新，我们建议您检查这些网站以获取更新。稳定发布版也在Zulip社区服务器上的#announce流中宣布（https://chat.zulip.org），欢迎您在那里创建账户；预计未来的发布版将在#announce>terminal releases中宣布。

如果您从main git分支运行，请注意这不会自动更新，您必须手动更新。这也适用于其他源或开发安装，包括例如https://aur.archlinux.org/packages/python-zulip-term-git/

首次运行

首次运行zulip-term时，它会查找名为zuliprc的文件，默认情况下在您的家目录中，其中包含登录Zulip服务器的详细信息。

如果找不到此文件，您有两个选择

1. zulip-term将提示您输入服务器、电子邮件和密码，并在该位置为您创建一个zuliprc文件

   注意：如果您使用Google、Github或其他外部身份验证来访问您的Zulip组织，那么您可能没有设置密码，并且目前需要创建一个密码才能使用zulip-terminal。如果您的组织在Zulip云上，您可以通过访问https://zulip.com/accounts/go?next=/accounts/password/reset为您的账户创建新密码。对于自托管服务器，请访问您的<Organization URL>/accounts/password/reset/（例如：https://chat.zulip.org/accounts/password/reset/）为您的账户创建新密码。

2. 每次运行zulip-term时，您都可以使用-c或--config-file选项指定替代zuliprc文件的路径，例如：$ zulip-term -c /path/to/zuliprc

   您的个人zuliprc文件可以从网页应用中的账户设置中的Zulip服务器获取，这赋予您在那里拥有的所有权限。机器人zuliprc文件可以从每个机器人的类似区域下载，并将具有更有限的权限。

注意：如果您的服务器使用自签名证书或不安全的连接，您需要手动添加额外的选项到zuliprc文件 - 请参阅Zulip Python模块的文档。

我们建议您在第一次尝试Zulip终端时，使用-e或--explore选项（在探索模式）运行zulip-term，我们故意不标记消息为已读。尝试跟随我们的教程来熟悉操作。

配置

zuliprc文件包含在[api]部分连接到您的聊天服务器的信息，但还包括在[zterm]部分的zulip-term的可选配置

[api]
email=example@example.com
key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
site=https://realm.zulipchat.com

[zterm]
# Alternative themes are listed in the FAQ
theme=zt_dark
# Autohide defaults to 'no_autohide', but can be set to 'autohide' to hide the left & right panels except when focused.
autohide=autohide
# Footlinks default to 'enabled', but can be set to 'disabled' to hide footlinks.
# disabled won't show any footlinks.
# enabled will show the first 3 per message.
footlinks=disabled
# If you need more flexibility, use maximum-footlinks.
# Maximum footlinks to be shown, defaults to 3, but can be set to any value 0 or greater.
# This option cannot be used with the footlinks option; use one or the other.
maximum-footlinks=3
# Notify defaults to 'disabled', but can be set to 'enabled' to display notifications (see next section).
notify=enabled
# Color depth defaults to 256 colors, but can be set to 1 (for monochrome), 16, or 24bit.
color-depth=256

注意：大多数这些配置设置可以在启动zulip-term时在命令行中指定；zulip-term -h或zulip-term --help将给出完整选项列表。

通知

请注意，目前不支持在WSL上使用通知；请参阅#767。

Linux

以下命令在基于Debian的系统上安装notify-send，类似命令也可以在其他Linux系统上找到。

sudo apt-get install libnotify-bin

OSX

在OS X上不需要额外的包来启用通知。但是，要有一个通知声音，请根据您的shell类型设置以下变量。声音值（此处为Ping）可以是位于/System/Library/Sounds或~/Library/Sounds的任何.aiff文件。

Bash

echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.bash_profile
source ~/.bash_profile

ZSH

echo 'export ZT_NOTIFICATION_SOUND=Ping' >> ~/.zshenv
source ~/.zshenv

复制到剪贴板

Zulip终端允许用户通过Python模块Pyperclip将某些文本复制到剪贴板。该模块使用了可能或可能不随操作系统一起提供的各种系统包。"复制到剪贴板"功能目前仅可用于从流信息弹出窗口复制流电子邮件。

Linux

在Linux上，该模块使用xclip或xsel命令，这些命令应该已经随操作系统一起提供。如果您的系统上没有安装这些命令，则可以使用以下命令安装任何一个：

sudo apt-get install xclip [Recommended]

或

sudo apt-get install xsel

OSX和WSL

不需要额外的包来启用复制到剪贴板。

贡献者指南

Zulip终端是由Zulip社区构建的。

要成为其中的一员并为代码做出贡献，请随时处理任何问题或在其#zulip-terminal上提出您的想法。

有关提交结构和样式，请参阅下面的提交样式部分。

如果您对git（或不是！）不熟悉，您可能受益于Zulip git指南。在贡献时，请注意我们使用的是rebase-oriented workflow。

有一个简单的教程可用于实现typing指示器。遵循它来了解如何为zulip-terminal实现新功能。

当然，您可以在GitHub上浏览源代码和您下载的源代码树，并查看源文件概览以了解文件当前的排列方式。

Urwid

Zulip终端使用urwid在终端中渲染UI组件。urwid是一个很棒的库，您可以通过它仅使用Python就渲染一个不错的终端UI。对于新贡献者来说，Urwid的教程是一个很好的起点。

设置开发环境

有多种选项可供选择；我们正在探索每个选项的优势，并欢迎您就您使用的或认为效果最好的选项提供反馈。

请注意，每种情况下使用的工具通常是相同的，但称呼方式不同。

无论选择哪种选项，您首先需要将 zulip/zulip-terminal 仓库克隆到本地（以下命令将仓库放置在当前目录下）

$ git clone git@github.com:zulip/zulip-terminal.git

以下命令应在仓库目录下运行，可以通过 cd zulip-terminal 实现。

Pipenv

1. 安装 pipenv（请参阅 推荐安装说明；如果您愿意，pipenv 可以安装在虚拟环境中）

$ pip3 install --user pipenv

2. 为 zulip-term 初始化 pipenv 虚拟环境（使用默认的 python 3；例如，使用 --python 3.6 来指定更具体的版本）

$ pipenv --three

3. 安装 zulip-term，包括开发需求

$ pipenv install --dev
$ pipenv run pip3 install -e '.[dev]'

Pip

1. 手动创建并激活一个虚拟环境；任何方法都应有效，例如上述简单安装中使用的方法

   1. python3 -m venv zt_venv（在当前目录下创建名为 zt_venv 的 venv）
   2. source zt_venv/bin/activate（激活 venv；此命令假设使用 bash 类型的 shell）

2. 安装 zulip-term，包括开发需求

$ pip3 install -e '.[dev]'

make/pip

如果您已安装 make，这是最新且最简单的方法

1. make（在当前目录下的 zt_venv 中设置已安装的虚拟环境）
2. source zt_venv/bin/activate（激活 venv；此命令假设使用 bash 类型的 shell）

开发任务

一旦设置了开发环境，您可能会发现以下内容根据您的环境类型很有用

任务	Make & Pip	Pipenv
正常运行	zulip-term	pipenv run zulip-term
以调试模式运行	zulip-term -d	pipenv run zulip-term -d
以分析模式运行	zulip-term --profile	pipenv run zulip-term --profile
运行所有代码检查器	./tools/lint-all	pipenv run ./tools/lint-all
运行所有测试	pytest	pipenv run pytest
构建测试覆盖率报告	pytest --cov-report html:cov_html --cov=./	pipenv run pytest --cov-report html:cov_html --cov=./

如果您使用 pip 与 make 结合，运行 make 将确保开发环境与指定的依赖项保持最新，这对于从 git 获取并重新合并后很有用。

通过代码检查器和自动化测试

当您提交拉取请求（PR）时，CI（GitHub Actions）会运行代码检查器和自动化测试（pytest），我们期望在代码合并之前通过它们。

注意：具有多个提交的可合并 PR 预计在每个提交上都会通过代码检查和测试，而不仅仅是整体通过

在本地运行这些工具可以加快您的开发速度，并避免重复将代码推送到 GitHub 以运行这些检查的需要。

如果您对代码检查器或 pytest 失败的原因感到困惑，请将您的代码推送到分支/PR，我们可以在 PR 或 chat.zulip.org 上讨论问题。

您可以使用上述表中的命令运行所有代码检查器和测试。单个代码检查器也可以通过 tools/ 中的脚本运行。

此外，如果您使用基于 make 的系统

• make lint 和 make test 运行每个任务组中的所有任务
• make check 运行所有检查，这在推送 PR（或更新）之前很有用

纠正某些代码检查器错误可能需要手动干预，例如使用 mypy 进行类型检查。但是，其他代码检查器错误可能可以自动修复，如下所述——这可以节省大量手动调整代码以通过代码检查器的时间！

自动格式化代码

该项目使用 black 和 isort 分别用于代码风格和导入排序。

这些工具可以在本地作为代码检查工具运行，但也可以自动为您格式化代码。

如果您使用的是基于 make 的设置，运行 make fix 将会运行这两个工具（以及其他一些工具）并重新格式化您的代码当前状态——因此，您应该先提交，以防万一，然后如果您对更改满意，可以使用 --amend 修改该提交。

您也可以单独对文件或目录使用这些工具，例如 black zulipterminal 或 isort tests/model/test_model.py

提交风格

我们旨在遵循标准的提交风格，以保持 git log 的一致性和易于阅读。

与代码协作一样，查看 git log 是很有帮助的，我们可以看到我们正在积极使用的风格。

我们关于提交结构和消息的总体风格大致遵循Zulip版本控制指南，所以我们建议您先阅读这个指南。

我们的提交标题与Zulip的一般风格略有不同，每个

• 都以一个或多个小写区域开头，后跟冒号和空格
• 区域是斜杠分隔的没有扩展名的修改文件，或更改的类型
• 以大写字母开始，以句号结束的简洁描述
• 最大整体长度为72（适合github网页界面，无需缩写）

一些示例提交标题

• file3/file1/file2: 改进某个功能的行为。 - 更新文件 file1.txt、file2.py 和 file3.md 的一般提交
• 重构: file1/file2: 提取一些公共函数。 - 不会改变功能行为的纯重构
• bugfix: file1: 避免一些明显的错误。 - 一个理想的小提交来修复错误
• tests: file1: 改进某个功能的测试。 - 仅改进 file1 的测试，很可能在 test_file1.py
• requirements: 将某些依赖从9.2升级到9.3。 - 将依赖从版本9.2升级到版本9.3

通常，对于代码更改，我们要求您在每次提交时更新代码检查和测试，以确保通过（不仅是在每个拉取请求中）。如果您更新了测试，您可以在您的提交文本中添加例如 Tests updated.。

理想情况下，我们更喜欢行为更改伴随着测试改进或添加，并且相应的 Tests added. 或类似的文本是有用的。

为了帮助满足这些规则，您可以使用下一节中描述的 GitLint。 但是，请手动检查您的提交与这些风格规则，因为GitLint无法检查一切——包括语言或语法！

GitLint

如果您计划在拉取请求（PR）中提交git提交，我们强烈建议您通过运行 gitlint install-hook（或在pipenv设置中使用 pipenv run gitlint install-hook）安装 gitlint 提交消息钩子。虽然内容仍然取决于您的写作技巧，但这确保了不同作者之间提交格式的更多一致性。

如果按照上述方式安装了钩子，那么在完成提交文本后，它将由gitlint与我们设置的样式进行检查，如果有任何问题，它会提供建议。如果gitlint发现任何问题，它会询问您是否希望以当前消息提交（“y”为“是”），停止提交过程（“n”为“否”），或编辑提交消息（“e”为“编辑”）。

gitlint还有其他选项可用；例如，可以使用 --commits 选项将其应用于一系列提交，例如 gitlint --commits HEAD~2..HEAD 将其应用于最后几个提交。

与测试（pytest）一起工作的提示

zulip-terminal的测试是用 pytest 编写的。您可以在 /tests 文件夹中阅读测试，以了解如何为新类/函数编写测试。如果您是pytest的新手，阅读其文档绝对是有益的。

我们目前有数千个测试，运行时都会通过pytest进行检查。虽然这取决于您的系统性能，但通常运行时间不会超过一分钟。然而，在调试过程中，您可能仍然希望限制测试范围，以提高周转时间。

• 如果大量测试以非常详细的方式失败，您可能尝试使用-x选项（例如pytest -x）来在第一个失败后停止测试；由于测试和测试固定值的参数化，许多明显的错误/失败可以通过一次修复来解决！（尝试使用pytest --maxfail 3以获得更宽松的版本）
• 为了避免每次运行时都运行所有成功的测试，您可以带上--lf（例如pytest --lf），即--last-failed（可能还有类似的有用选项，如--failed-first和--new-first，与-x配合使用可能效果很好）。
• 从pytest 3.10开始，有--sw（即--stepwise），它以与--lf相同的方式处理已知失败，可以与--stepwise-skip结合使用来控制当前焦点是哪个测试。
• 如果您知道失败的测试名称和/或具体位置，您可以限制测试到特定位置（例如pytest tests/model）或使用所选关键字（例如pytest -k __handle）。

当只有一部分测试正在运行时，使用-v选项（即--verbose）更加实用和有用；它不是显示每个测试结果的点（或F、E、x等），而是显示正在运行的每个测试的名称（含参数）（例如pytest -v -k __handle）。此选项还显示测试的更多详细信息，并且可以多次给出（例如pytest -vv）。

有关pytest选项的更多信息，请参阅pytest -h，或查看完整的pytest文档。

调试技巧

使用print输出

如果运行时启用了调试，zulip-terminal的stdout（标准输出）将重定向到./debug.log。

这意味着，如果您想检查变量的值，或者可能表明到达了代码的某个点，您只需简单地使用print()，例如。

print(f"Just about to do something with {variable}")

当使用调试选项运行时，字符串将被打印到./debug.log。

在类似于bash的终端中，您可以在另一个终端中运行类似tail -f debug.log的命令，以查看print的输出。

使用pudb & telnet进行交互式调试

如果您想在运行时或处于特定状态时调试zulip-terminal，可以在您想调试的代码部分插入

from pudb.remote import set_trace
set_trace()

这将为您启动一个telnet连接。您可以在./debug.log中找到telnet连接的IP地址和端口号。然后在另一个终端中简单地运行

$ telnet 127.0.0.1 6899

其中127.0.0.1是IP地址，6899是您在./debug.log中找到的端口号。

在本地更改后，Zulip Terminal中没有效果！

这很可能意味着您安装了zulip-terminal的正常和开发版本。

要确保您运行的是开发版本

• 如果您使用pipenv，请从克隆/下载的zulip-terminal目录调用pipenv run zulip-term；
• 如果您使用pip（pip3），请确保您已激活正确的虚拟环境（venv）；根据您的shell配置，venv的名称可能会出现在命令提示符中。请注意，在pip3命令中不包含-e也会导致此问题。