Mount Telegram and Naver as sub-resources on Datamaxi / AsyncDatamaxi (#186)

* feat: mount telegram/naver as sub-resources on Datamaxi

Telegram/Naver accept shared api= and reuse the client's one Session;
standalone Telegram(api_key=)/Naver(api_key=) still build own transport.

Refs #184

* feat: mount telegram/naver on AsyncDatamaxi

AsyncTelegram/AsyncNaver accept shared api= for mounting; standalone
still supported.

Refs #184

* test: mounted telegram/naver reuse shared session (sync+async)

Refs #184

* docs: show mounted maxi.telegram/maxi.naver form

Refs #184

* chore: drop comment on telegram/naver mount

* chore: drop section-header comment in telegram/naver tests

* docs: drop standalone telegram/naver table rows + mount notes

* docs: drop async telegram/naver mount note

Author: martinkersner

README.md

@@ -100,13 +100,16 @@ the others.
 <details markdown="1"><summary>Sync</summary>
 
 ```python
-from datamaxi import Datamaxi, Telegram, Naver
+from datamaxi import Datamaxi
 
-# Clients read DATAMAXI_API_KEY from the environment automatically.
-# Alternatively, pass api_key="your_api_key" explicitly to each client.
+# The client reads DATAMAXI_API_KEY from the environment automatically.
+# Alternatively, pass api_key="your_api_key" explicitly.
 maxi = Datamaxi()
-telegram = Telegram()
-naver = Naver()
+
+# Telegram and Naver are mounted as `maxi.telegram` / `maxi.naver`
+# (standalone `Telegram` / `Naver` clients remain available too).
+channels, _ = maxi.telegram.channels()
+trend = maxi.naver.trend(symbol="BTC")
 
 # Fetch CEX candle data (returns pandas DataFrame)
 df = maxi.cex.candle(
@@ -188,14 +191,14 @@ The package ships these clients, all configured the same way (see
 
 | Client            | Import                                        | Purpose                                                    |
 | ----------------- | --------------------------------------------- | ---------------------------------------------------------- |
-| `Datamaxi`        | `from datamaxi import Datamaxi`               | Synchronous client for all crypto REST data.               |
-| `Telegram`        | `from datamaxi import Telegram`               | Telegram channel messages and metadata.                    |
-| `Naver`           | `from datamaxi import Naver`                  | Naver search-trend data (South Korea).                     |
+| `Datamaxi`        | `from datamaxi import Datamaxi`               | Synchronous client for all REST data, incl. `maxi.telegram` / `maxi.naver`. |
 | `AsyncDatamaxi`   | `from datamaxi.aio import AsyncDatamaxi`      | Async twin of `Datamaxi` (needs the `[async]` extra).      |
 | `AsyncDatamaxiWS` | `from datamaxi.aio.ws import AsyncDatamaxiWS` | Async WebSocket streaming (needs the `[ws]` extra).        |
 
-`AsyncTelegram` and `AsyncNaver` are the async twins of `Telegram` / `Naver`,
-also imported from `datamaxi.aio`.
+Telegram and Naver are mounted on `Datamaxi` / `AsyncDatamaxi` (`maxi.telegram`,
+`maxi.naver`) so they reuse the client's shared session. The standalone
+`Telegram` / `Naver` (and their async twins `AsyncTelegram` / `AsyncNaver`,
+imported from `datamaxi.aio`) remain available for independent use.
 
 ## REST API Reference
 
@@ -495,12 +498,8 @@ Off-exchange signals: Telegram channels and Naver search trends.
 Fetch Telegram channel messages and metadata.
 
 ```python
-# Initialize Telegram client
-from datamaxi import Telegram
-telegram = Telegram(api_key=api_key)
-
 # Fetch channels
-data, next_request = telegram.channels(
+data, next_request = maxi.telegram.channels(
     page=1,                  # Optional: page number
     limit=1000,              # Optional: items per page
     category=None,           # Optional: filter by category
@@ -509,7 +508,7 @@ data, next_request = telegram.channels(
 )
 
 # Fetch messages
-data, next_request = telegram.messages(
+data, next_request = maxi.telegram.messages(
     channel_name=None,       # Optional: filter by channel
     page=1,                  # Optional: page number
     limit=1000,              # Optional: items per page
@@ -524,15 +523,11 @@ data, next_request = telegram.messages(
 Fetch Naver search trend data (South Korea).
 
 ```python
-# Initialize Naver client
-from datamaxi import Naver
-naver = Naver(api_key=api_key)
-
 # Get supported symbols
-symbols = naver.symbols()
+symbols = maxi.naver.symbols()
 
 # Fetch trend data
-data = naver.trend(
+data = maxi.naver.trend(
     symbol="BTC",            # Required: symbol to search
     pandas=True              # Optional: return DataFrame or list
 )
@@ -756,8 +751,7 @@ asyncio.run(main())
 Use `AsyncDatamaxi` as an async context manager (shown above) or call
 `await client.aclose()` yourself. Paginated endpoints return an async
 `next_request` — `await` it too
-(`data, next_request = await client.cex.announcement(...)`). Telegram and Naver
-have standalone `AsyncTelegram` / `AsyncNaver` clients.
+(`data, next_request = await client.cex.announcement(...)`).
 
 Every endpoint in the [REST API Reference](#rest-api-reference) works the same
 under the async client — see the [docs](https://datamaxi.readthedocs.io/) where

datamaxi/aio/__init__.py

@@ -16,7 +16,9 @@
 
 Mirrors the full sync surface (``cex.*``, ``funding_rate``, ``forex``,
 ``premium``, ``liquidation``, ``open_interest``, ``margin_borrow``,
-``index_price``, plus standalone ``AsyncTelegram`` / ``AsyncNaver``). Reuses
+``index_price``, ``telegram``, ``naver``). The standalone
+``AsyncTelegram`` / ``AsyncNaver`` classes stay exported for back-compat.
+Reuses
 the sync client's endpoint resolution and error handling (``datamaxi._dispatch``)
 and the shared DataFrame / ResponseMeta helpers, so the two clients can't drift
 on request building or error semantics.
@@ -68,6 +70,8 @@ def __init__(self, api_key=None, **kwargs: Any):
         self.open_interest = AsyncOpenInterest(api)
         self.margin_borrow = AsyncMarginBorrow(api)
         self.index_price = AsyncIndexPrice(api)
+        self.telegram = AsyncTelegram(api=api)
+        self.naver = AsyncNaver(api=api)
 
     async def aclose(self):
         await self._api.aclose()

datamaxi/aio/naver.py

@@ -20,10 +20,12 @@
 class AsyncNaver(AsyncResource):
     """Client to fetch Naver trend data from DataMaxi+ API (async)."""
 
-    def __init__(self, api_key=None, **kwargs: Any):
-        if "base_url" not in kwargs:
-            kwargs["base_url"] = BASE_URL
-        super().__init__(AsyncAPI(api_key, **kwargs))
+    def __init__(self, api_key=None, api=None, **kwargs: Any):
+        if api is None:
+            if "base_url" not in kwargs:
+                kwargs["base_url"] = BASE_URL
+            api = AsyncAPI(api_key, **kwargs)
+        super().__init__(api)
 
     async def aclose(self):
         await self._api.aclose()

datamaxi/aio/telegram.py

@@ -17,10 +17,12 @@
 class AsyncTelegram(AsyncResource):
     """Client to fetch Telegram data from DataMaxi+ API (async)."""
 
-    def __init__(self, api_key=None, **kwargs: Any):
-        if "base_url" not in kwargs:
-            kwargs["base_url"] = BASE_URL
-        super().__init__(AsyncAPI(api_key, **kwargs))
+    def __init__(self, api_key=None, api=None, **kwargs: Any):
+        if api is None:
+            if "base_url" not in kwargs:
+                kwargs["base_url"] = BASE_URL
+            api = AsyncAPI(api_key, **kwargs)
+        super().__init__(api)
 
     async def aclose(self):
         await self._api.aclose()

datamaxi/naver/__init__.py

@@ -13,16 +13,19 @@
 class Naver(Resource):
     """Client to fetch Naver trend data from DataMaxi+ API."""
 
-    def __init__(self, api_key=None, **kwargs: Any):
+    def __init__(self, api_key=None, api=None, **kwargs: Any):
         """Initialize the object.
 
         Args:
             api_key (str): The DataMaxi+ API key
+            api (API): Shared transport to reuse when mounted on
+                ``Datamaxi`` (``maxi.naver``); when omitted this builds its
+                own ``API`` for standalone use.
             **kwargs: Keyword arguments used by `datamaxi.api.API`.
         """
-        if "base_url" not in kwargs:
+        if api is None and "base_url" not in kwargs:
             kwargs["base_url"] = BASE_URL
-        super().__init__(api_key, **kwargs)
+        super().__init__(api_key, api=api, **kwargs)
 
     def symbols(self) -> List[str]:
         """Get Naver trend supported token symbols

datamaxi/resources/__init__.py

@@ -28,6 +28,8 @@
 from datamaxi.resources.cex_symbol import (  # used in documentation # noqa:F401
     CexSymbol,
 )
+from datamaxi.telegram import Telegram
+from datamaxi.naver import Naver
 
 
 class Datamaxi:
@@ -67,6 +69,8 @@ def __init__(self, api_key=None, **kwargs: Any):
         self.open_interest = OpenInterest(api=api)
         self.margin_borrow = MarginBorrow(api=api)
         self.index_price = IndexPrice(api=api)
+        self.telegram = Telegram(api=api)
+        self.naver = Naver(api=api)
 
     def close(self):
         self._api.close()

datamaxi/telegram/__init__.py

@@ -10,16 +10,19 @@
 class Telegram(Resource):
     """Client to fetch Telegram data from DataMaxi+ API."""
 
-    def __init__(self, api_key=None, **kwargs: Any):
+    def __init__(self, api_key=None, api=None, **kwargs: Any):
         """Initialize the object.
 
         Args:
             api_key (str): The DataMaxi+ API key
+            api (API): Shared transport to reuse when mounted on
+                ``Datamaxi`` (``maxi.telegram``); when omitted this builds
+                its own ``API`` for standalone use.
             **kwargs: Keyword arguments used by `datamaxi.api.API`.
         """
-        if "base_url" not in kwargs:
+        if api is None and "base_url" not in kwargs:
             kwargs["base_url"] = BASE_URL
-        super().__init__(api_key, **kwargs)
+        super().__init__(api_key, api=api, **kwargs)
 
     def channels(
         self,

tests/test_async_resources.py

@@ -171,6 +171,30 @@ async def run():
     assert _run(run()) == _CHANNELS
 
 
+def test_async_telegram_naver_mounted_reuse_shared_session():
+    c = _dm()
+    assert isinstance(c.telegram, AsyncTelegram)
+    assert isinstance(c.naver, AsyncNaver)
+    # Same shared AsyncAPI/transport as every other sub-resource.
+    assert c.telegram._api is c._api
+    assert c.naver._api is c._api
+    assert c.telegram._api is c.cex._api
+
+
+def test_async_mounted_telegram_and_naver_work():
+    async def run():
+        async with _dm() as c:
+            channels, _ = await c.telegram.channels()
+            messages, _ = await c.telegram.messages(channel_name="alpha")
+            trend = await c.naver.trend("BTC", pandas=False)
+            return channels, messages, trend
+
+    channels, messages, trend = _run(run())
+    assert channels == _CHANNELS
+    assert messages == _MESSAGES
+    assert trend == _TREND
+
+
 def test_async_funding_history_and_latest():
     async def run():
         async with _dm() as c:

tests/test_naver.py

@@ -6,7 +6,7 @@
 import pytest
 from urllib.parse import urlparse, parse_qs
 
-from datamaxi.naver import Naver
+from datamaxi import Datamaxi, Naver
 from datamaxi.error import ClientError, ServerError
 from tests.util import mock_http_response
 
@@ -68,3 +68,19 @@ def test_naver_trend_client_error():
 def test_naver_trend_server_error():
     with pytest.raises(ServerError):
         _client().trend("BTC")
+
+
+def test_naver_mounted_reuses_shared_session():
+    maxi = Datamaxi(api_key="key", base_url=BASE_URL)
+    assert isinstance(maxi.naver, Naver)
+    # Same shared API/transport as every other sub-resource.
+    assert maxi.naver._api is maxi._api
+    assert maxi.naver._api is maxi.cex._api
+
+
+@mock_http_response(responses.GET, "/api/v1/naver-trend", _TREND)
+def test_naver_mounted_trend_works():
+    maxi = Datamaxi(api_key="key", base_url=BASE_URL)
+    df = maxi.naver.trend("BTC")
+    assert isinstance(df, pd.DataFrame)
+    assert len(df) == 2

tests/test_telegram.py

@@ -5,7 +5,7 @@
 import pytest
 from urllib.parse import urlparse, parse_qs
 
-from datamaxi.telegram import Telegram
+from datamaxi import Datamaxi, Telegram
 from datamaxi.error import ClientError, ServerError
 from tests.util import mock_http_response
 
@@ -101,3 +101,27 @@ def test_channels_client_error():
 def test_messages_server_error():
     with pytest.raises(ServerError):
         _client().messages(channel_name="alpha")
+
+
+def test_telegram_mounted_reuses_shared_session():
+    maxi = Datamaxi(api_key="key", base_url=BASE_URL)
+    assert isinstance(maxi.telegram, Telegram)
+    # Same shared API/transport as every other sub-resource.
+    assert maxi.telegram._api is maxi._api
+    assert maxi.telegram._api is maxi.cex._api
+
+
+@mock_http_response(responses.GET, "/api/v1/telegram/channels", _CHANNELS)
+def test_telegram_mounted_channels_work():
+    maxi = Datamaxi(api_key="key", base_url=BASE_URL)
+    res, next_request = maxi.telegram.channels()
+    assert res == _CHANNELS
+    assert callable(next_request)
+
+
+@mock_http_response(responses.GET, "/api/v1/telegram/messages", _MESSAGES)
+def test_telegram_mounted_messages_work():
+    maxi = Datamaxi(api_key="key", base_url=BASE_URL)
+    res, next_request = maxi.telegram.messages(channel_name="alpha")
+    assert res == _MESSAGES
+    assert callable(next_request)