新しいPython API

開発
1

Discourse API を利用するための新しい Python パッケージ fluent-discourse を共有できることを嬉しく思います。

Discourse API を Python 経由で利用するためのパッケージは すでにいくつか存在します。それなのに、なぜ新たに開発したのでしょうか？

既存の Discourse パッケージは、API の各エンドポイントに対して固有の Python 関数を作成するという、似たようなアプローチを取っている傾向があります。

このアプローチにはいくつかの欠点があります：

  1. API と完全な機能同等性を実現することが非常に困難です。Discourse の API はドキュメントが十分でないことが多く、エンドポイントをリバースエンジニアリングする必要がある場合もよくあります。さらに、コア機能の一部ではない API エンドポイントを公開する多数のプラグインも存在します。これにより、ライブラリ利用者は、必要なエンドポイントをライブラリに追加するためにプルリクエストを送るのか、それとも追加のエンドポイントに対して独自ソリューションを構築するのかという難しい選択を迫られます。
  2. 別の API を学ぶ必要があります。Discourse API のメソッドやエンドポイントを学ぶだけでなく、Python での対応する関数呼び出しが何かを特定する必要があります。
  3. テストすべきコードが膨大になるため、100% のテストカバレッジを達成するのが難しくなります。その結果、生成されるソフトウェアの品質に対する信頼性が低下します。

これとは対照的に、私はメソッドチェーンを使用してリクエストを構築する「フレンド（fluent）」インターフェースを採用しました。例を見てみましょう。
ID が 5 のカテゴリ ‘foo’ の最新トピックを取得するには、以下のエンドポイントを使用します：
GET /c/foo/5.json。
このライブラリを使ってそのリクエストを行うには、単に以下のように呼び出します：
client.c.foo[5].json.get()

ご覧の通り、API エンドポイントと Python での対応する呼び出しの間には、意味的な同等性があります。

このアプローチには以下のような利点があります：

  1. ドキュメント化されていないエンドポイント、プラグイン由来のエンドポイント、そして今後定義される可能性のあるエンドポイント（将来性）を含む、Discourse API との完全な機能同等性を最初から備えています。
  2. Discourse API だけを学べば十分です。どの API 呼び出しもこのように簡単に翻訳できるため、対応する関数を探す必要がありません。
  3. ライブラリ全体で約 150 行のコードしかありません。これにより、100% のテストカバレッジを達成することが極めて容易になります。

ライブの Discourse サーバーに対するいくつかの統合テストにより、100% のテストカバレッジを達成しています。

もしこれが魅力的に聞こえるなら、ぜひこのパッケージを試してみてください！

「いいね！」 21
3

興味深いアプローチですね…

PHP で同様のことを行うにはマジックメソッドに依存する必要があり、IDE の自動補完などの利点を失うことになります。しかし、その代償は価値があるかもしれません。

このアプローチの利点は、単に URL を引数として渡す client.get(url) と比べて何でしょうか？

4

それは良い指摘ですね。この場合、IDE の自動補完はあまり役立ちません。もしそれが重要な要件であれば、別のライブラリを使用する価値があるかもしれません。

各メソッドチェーンが新しいクライアントを返すため、考えられる利点の一つは、特定のメソッドチェーンを変数に格納し、後続の呼び出しで再利用できることです。例えば、新規投稿を作成したいデータリストがあるとします。

post_data = [
  {
    "raw": "Hello World!",
    "topic_id": 123,
    ...
  },
  {
    "raw": "Tester",
    "topic_id": 501,
    ...
  },
  ...
]

「新規投稿」のメソッドチェーンを格納し、リスト内の各投稿の作成に再利用できます。

new_post_endpoint = client.posts.json

for post in post_data:
  new_post_endpoint.post(data=post)

クライアントを再利用できるこの機能が役立つ他のシナリオも想像できるでしょう。それ以外には、ご提案のように単に URL を渡すのと比べて大きな利点はありません。このアプローチの根拠について説明している Universal Client ライブラリについてお読みいただくことをお勧めします。

また、このアプローチの PHP 固有の実装については、SendGrid の PHP API をご覧ください。私は SendGrid の Python API について読んだ際に、このライブラリの構築に触発されました。

「いいね！」 3