流利的话语

这个包实现了Discourse API的流畅接口。

这意味着什么？

我们没有将每个端点和方法映射到一个独特的函数，而是提供了一个用于发出任何请求的框架。

这意味着，只需很少的代码，这个包就与 Discourse API 完全兼容，包括未记录的端点、来自插件的端点以及尚未创建的端点。

安装

最简单的安装方法是通过 PyPI

pip install fluent-discourse

用法

设置客户端

通过指定要使用的 base_url、用户名和 api_key 来设置客户端。

from fluent_discourse import Discourse

client = Discourse(base_url="http://localhost:3000", username="test_user", api_key="a0a2d176b3cfbadd36ac2f46ccbd701bf45dfd6f47836e99d570bf7e0ae04af8", raise_for_rate_limit=True)

或者，您可以设置三个环境变量：

export DISCOURSE_URL=http://localhost:3000
export DISCOURSE_USERNAME=test_user
export DISCOURSE_API_KEY=a0a2d176b3cfbadd36ac2f46ccbd701bf45dfd6f47836e99d570bf7e0ae04af8

然后可以使用from_env()类方法来实例化客户端：

from fluent_discourse import Discourse
client = Discourse.from_env(raise_for_rate_limit=False)

在任何一种情况下，该raise_for_rate_limit参数都是可选的（默认为 True）并控制客户端如何响应 RateLimitErrors。如果True，客户将提出RateLimitError；如果是False，它将等待 RateLimit 计数器重置并重试请求的建议时间。

初始化客户端后，您就可以开始发出请求了。让我们先举个例子来看看它是如何工作的。

基本示例

假设我们想要获取最新的帖子，这里是适当的端点。我们需要GET向/posts.json. 以下是您使用我们设置的客户端的方法。

latest = client.posts.json.get()

我希望这能让你了解它是如何工作的。我们不是调用映射到此端点/方法组合的特定函数，而是使用方法链接的形式动态构造请求。最后，我们使用特殊方法get()、put()、post()或delete()来触发对指定端点的请求。

传递 ID 和 Python 保留字

让我们看另一个例子。这次我们想将用户添加到一个组中，这是我们要点击的端点。具体来说，我们想用 将用户添加到组中id=5，所以我们需要向 发送PUT请求/groups/5/members.json。

以下是如何使用此软件包执行此操作：

data = {
	"usernames": "username1,username2"
}
client.groups[5].members.json.put(data)

请注意，我们使用稍微不同的语法（“indexed at”括号）来传递数字。这是因为 python 属性的命名限制。我们还遇到了保留字如forand的问题is。

如果您需要构建一个包含数字或保留字的 URL，有两种方法。

# These throw Syntax errors
## Numbers are not allowed
client.groups.5.members.json.put(data)
## "is" and "for" are reserved words
client.is.this.for.me.get()

# Valid approaches
## Using brackets
client.groups[5].members.json.put(data)
## Using the _() method
client._("is").this._("for").me.get()

如您所见，您可以使用方括号[]或下划线方法_()来处理整数或保留字。

传递数据

、get()、put()和方法均采用单个可选参数 ，post()它是与请求一起传递的数据字典。delete()data

对于put()、post()和delete()方法，数据在请求正文中发送（作为 JSON）。

对于该get()方法，数据作为查询参数添加到 url。

例外

此类中定义了一些自定义异常。

DiscourseError

• 一个包罗万象的父类，用于此包导致的错误。当 Discourse 响应不属于其他更具体类别的错误（例如 500 错误）时引发。

UnauthorizedError

• 当 Discourse 响应 403 错误并指示使用无效凭据来设置客户端时引发。

RateLimitError

• 当 Discourse 响应 429 响应并且客户端配置了raise_for_rate_limit=True.

PageNotFoundError

• 当 Discourse 响应 404 时引发，表明该页面不存在或当前用户无权访问该页面。

您可以直接从包中导入任何这些错误。

from fluent_discourse import DiscourseError

贡献

感谢您有兴趣为这个项目做出贡献！对于错误跟踪和其他问题，请使用 GitHub 上的问题跟踪器。

测试

该软件包力求 100% 的测试覆盖率。测试通过 tox 运行。它们分为单元测试和集成测试。单元测试是自包含的，集成测试将请求发送到服务器。

尽管所有集成测试都针对实时 Discourse 服务器进行了测试，但我们为 CI 测试设置了一个模拟服务器。

设置测试客户端需要三个环境变量：

• DISCOURSE_URL: 话语的基本 url (eg http://localhost:4200)
• DISCOURSE_USERNAME：要交互的用户的用户名，重要的是测试要求该用户具有管理员权限。
• DISCOURSE_API_KEY：配置为与指定用户一起使用的 API 密钥。此键应具有全局范围。

运行所有测试（针对现场话语）：

tox

只运行单元测试：

tox -- -m "not integration"

只运行集成测试（针对现场话语）：

tox -- -m "integration"

要设置模拟服务器并针对它运行测试，请将您的环境DISCOURSE_URL变量设置为http://127.0.0.1:5000并运行：

./run_tests_w_mock_server.sh

100% 的测试覆盖率很重要。如果您进行更改，请确保这些更改也反映在测试中。特别是对于集成测试，在实时话语服务器和模拟服务器上运行它们。请根据需要扩展和调整模拟服务器，以便在实时服务器上准确再现测试结果。

风格起绒

请在提交这些更改之前使用黑色重新格式化任何代码更改。

赶紧跑：

black .

致谢

我从 SendGrid 的 Python API 中窃取了一个流畅的 API 接口（以及一些代码作为起点）的想法。这是解释他们方法的资源。

有一个通用客户端库将这个框架实现为任何 api 的灵活接口。相比之下，这个包是专门为 Discourse 的 API 定制的，包括更好的错误处理。