Add docs

docs/examples.rst

@@ -130,3 +130,19 @@ KuCoin
 ~~~~~~
 
 .. literalinclude:: ../example/datastore/kucoin.py
+
+Helpers
+-------
+
+GMO Coin
+~~~~~~~~
+
+:class:`.helpers.GMOCoinHelper` を利用したサンプルコードです。
+
+:meth:`.helpers.GMOCoinHelper.manage_ws_token` を利用することで、`Private WebSocket のアクセストークン <https://api.coin.z.com/docs/#ws-auth-post>`_ を管理します。
+デフォルトでは 5 分ごとにアクセストークンを延長します。 延長が失敗した場合は、アクセストークンを作成します。
+このメソッドは無限ループとなっているので、 :meth:`asyncio.create_task` でタスクスケジュールしてください。
+
+以下は適当なチャンネルを購読して、アクセストークンの管理タスクスケジュールするサンプルコードです。
+
+.. literalinclude:: ../example/helpers/gmocoin.py

docs/exchanges.rst

@@ -58,7 +58,7 @@ Authentication
 
     https://api.coin.z.com/docs/#authentication-private-ws
 
-    ただし :class:`.GMOCoinDataStore` に「アクセストークン」を管理する機能があります。
+    ただし :class:`.GMOCoinDataStore` 及び :class:`.helpers.GMOCoinHelper` に「アクセストークン」を管理する機能があります。
 
     :meth:`.GMOCoinDataStore.initialize` は「アクセストークンを取得」の POST リクエストに対応しています。
     これにより「アクセストークン」が属性 :attr:`.GMOCoinDataStore.token` に格納されます。

docs/reference.rst

@@ -79,3 +79,12 @@ Store changes
 
    pybotters.StoreChange
    pybotters.StoreStream
+
+
+Helpers
+-------
+
+.. autosummary::
+   :toctree: generated
+
+   pybotters.helpers.GMOCoinHelper

example/helpers/gmocoin.py

@@ -0,0 +1,48 @@
+import asyncio
+import os
+
+try:
+    from rich import print
+except ImportError:
+    pass
+
+import pybotters
+from pybotters.helpers import GMOCoinHelper
+
+
+async def main():
+    apis = {
+        "gmocoin": [
+            os.getenv("GMOCOIN_API_KEY", ""),
+            os.getenv("GMOCOIN_API_SECRET", ""),
+        ],
+    }
+
+    async with pybotters.Client(apis=apis) as client:
+        store = pybotters.GMOCoinDataStore()
+        gmohelper = GMOCoinHelper(client)
+
+        token = await gmohelper.create_access_token()
+
+        ws = client.ws_connect(
+            f"wss://api.coin.z.com/ws/private/v1/{token}",
+            send_json={
+                "command": "subscribe",
+                "channel": "positionSummaryEvents",
+                "option": "PERIODIC",
+            },
+            hdlr_json=store.onmessage,
+        )
+
+        # Create a task to manage WebSocket URL and access token.
+        asyncio.create_task(
+            gmohelper.manage_ws_token(ws, token),
+        )
+
+        with store.position_summary.watch() as stream:
+            async for change in stream:
+                print(change.data)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pybotters/helpers/gmocoin.py

@@ -13,12 +13,25 @@ def __init__(
         self,
         client: Client,
     ) -> None:
+        """Post-maintenance reconnection helper for GMO Coin.
+
+        Args:
+            client (Client): pybotters.Client
+        """
         self._client = client
         self._url = removeprefix(
             "https://api.coin.z.com/private/v1/ws-auth", self._client._base_url
         )
 
     async def create_access_token(self) -> str:
+        """Helper for ``POST /private/v1/ws-auth``.
+
+        Raises:
+            GMOCoinResponseError: Response error.
+
+        Returns:
+            str: Created access token.
+        """
         r = await self._client.fetch(
             "POST",
             self._url,
@@ -31,6 +44,14 @@ async def create_access_token(self) -> str:
             raise GMOCoinResponseError(r.text)
 
     async def extend_access_token(self, token: str) -> None:
+        """Helper for ``PUT /private/v1/ws-auth``.
+
+        Args:
+            token (str): Access token to extend
+
+        Raises:
+            GMOCoinResponseError: Response error.
+        """
         r = await self._client.fetch(
             "PUT",
             self._url,
@@ -46,8 +67,18 @@ async def manage_ws_token(
         self,
         ws: WebSocketApp,
         token: str,
-        delay: float = 1800.0,  # 30 minutes
+        delay: float = 300.0,  # 5 minutes
     ) -> NoReturn:
+        """Manage the access token for the WebSocket connection.
+
+        This method is a coroutine for an infinite loop.
+        It should be executed by :meth:`asyncio.create_task`.
+
+        Args:
+            ws (WebSocketApp): WebSocketApp instance.
+            token (str): Access token.
+            delay (float, optional): Sleep time. Defaults to 300.0 (5 minutes).
+        """
         while True:
             try:
                 await self.extend_access_token(token)