zulip 0.9.0

依赖关系

Python绑定Zulip API需要以下依赖关系

• Python（版本 >= 3.8）
• requests（版本 >= 0.12.1）

注意：如果您想使用Python 2的Zulip绑定，我们建议安装版本0.6.4。

安装

此包使用setuptools，因此您只需运行

python setup.py install

使用API

目前，唯一完全支持的API操作是发送消息。其他API查询也可以正常工作，但仍在积极开发中，所以请确保我们知道您正在使用它们，这样我们就可以在对其进行任何更改时通知您。

使用这些API绑定的最简单方法是基于本分发中zulip/examples/下的示例工具。

如果您将API密钥放在配置文件~/.zuliprc中，Python API绑定将自动读取它。配置文件的格式如下：

[api]
key=<api key from the web interface>
email=<your email address>
site=<your Zulip server's URI>
insecure=<true or false, true means do not verify the server certificate>
cert_bundle=<path to a file containing CA or server certificates to trust>

省略时，以下设置将使用默认值：

insecure=false
cert_bundle=<the default CA bundle trusted by Python>

或者，您可以在我们的示例中显式使用"--user"，"--api-key"和--site，这在测试时特别有用。如果您正在运行多个共享主目录的机器人，我们建议使用--config来指定特定机器人的zuliprc文件路径。最后，您可以使用环境变量ZULIP_CONFIG，ZULIP_API_KEY，ZULIP_EMAIL，ZULIP_SITE，ZULIP_CERT，ZULIP_CERT_KEY和ZULIP_CERT_BUNDLE来控制所有这些变量的默认值。命令行选项优先于环境变量，然后是配置文件。

其他配置选项的命令行等效项如下：

--insecure
--cert-bundle=<file>

您可以从Zulip设置页面获取您的Zulip API密钥，创建机器人，并管理机器人；当前Zulip中还有一个按钮可以下载您的账户/服务器对的zuliprc文件。

一个典型的简单机器人发送API消息的示例如下：

在文件顶部：

# Make sure the Zulip API distribution's root directory is in sys.path, then:
import zulip
zulip_client = zulip.Client(email="your-bot@example.com", client="MyTestClient/0.1")

当您想要发送消息时：

message = {
  "type": "stream",
  "to": ["support"],
  "subject": "your subject",
  "content": "your content",
}
zulip_client.send_message(message)

如果您正在解析参数，您可能会发现使用Zulip的选项组很有用；有关如何操作的详细信息，请参阅我们的任何API示例。

其他示例：

client.send_message({'type': 'stream', 'content': 'Zulip rules!',
                     'subject': 'feedback', 'to': ['support']})
client.send_message({'type': 'private', 'content': 'Zulip rules!',
                     'to': ['user1@example.com', 'user2@example.com']})

send_message()返回一个包含以下键的dict：msg，result。对于成功的调用，result将是"success"，msg将是空字符串。在出错时，result将是"error"，msg将描述出错的原因。

示例：

API绑定包包含几个示例脚本，展示了如何使用API；它们作为API绑定包的一部分进行安装。

日志记录：

Zulip API附带一个ZulipStream类，可以与日志模块一起使用。

import zulip
import logging
stream = zulip.ZulipStream(type="stream", to=["support"], subject="your subject")
logger = logging.getLogger("your_logger")
logger.addHandler(logging.StreamHandler(stream))
logger.setLevel(logging.DEBUG)
logger.info("This is an INFO test.")
logger.debug("This is a DEBUG test.")
logger.warn("This is a WARN test.")
logger.error("This is a ERROR test.")

发送消息：

您可以使用包含的zulip-send脚本来通过API直接从现有脚本中发送消息。

zulip-send hamlet@example.com cordelia@example.com -m \
    "Conscience doth make cowards of us all."

或者，如果您不想使用您的~/.zuliprc文件：

zulip-send --user shakespeare-bot@example.com \
    --api-key a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5 \
    --site https://zulip.example.com \
    hamlet@example.com cordelia@example.com -m \
    "Conscience doth make cowards of us all."

与不受信任的服务器证书一起工作：

如果您的服务器有一个自签名证书，或者由您不想全局信任的CA签名的证书，则默认情况下，API将因SSL验证错误而失败。

您可以在您的.zuliprc文件中添加insecure=true。

[api]
site=https://zulip.example.com
insecure=true

这禁用了服务器证书的验证，因此连接是加密的但未经验证的。这并不安全，但对于开发环境可能足够好。

您可以在您的.zuliprc文件中显式信任服务器证书，使用cert_bundle=<filename>。

[api]
site=https://zulip.example.com
cert_bundle=/home/bots/certs/zulip.example.com.crt

您还可以显式信任Python默认信任的证书颁发机构（CA）集合之外的不同集合。例如，要信任公司内部CA。

[api]
site=https://zulip.example.com
cert_bundle=/home/bots/certs/example.com.ca-bundle

将服务器证书（或CA证书）保存在其自己的文件中，如果需要，首先将其转换为PEM格式。验证您保存的证书与服务器上的证书是否相同。

cert_bundle选项仅信任与Zulip站点的交互中的服务器/ CA证书，并且相对安全。

请注意，证书包仅仅是将一个或多个证书组合成一个单独的文件。