feat: export enum constants + Literal type hints (#4)

datamaxi/__init__.py

@@ -1,3 +1,45 @@
 from datamaxi.datamaxi import Datamaxi  # noqa: F401
 from datamaxi.telegram import Telegram  # noqa: F401
 from datamaxi.naver import Naver  # noqa: F401
+from datamaxi.lib.constants import (  # noqa: F401
+    SPOT,
+    FUTURES,
+    USD,
+    ASC,
+    DESC,
+    INTERVAL_1M,
+    INTERVAL_5M,
+    INTERVAL_15M,
+    INTERVAL_30M,
+    INTERVAL_1H,
+    INTERVAL_4H,
+    INTERVAL_12H,
+    INTERVAL_1D,
+    SUPPORTED_INTERVALS,
+    Market,
+    Interval,
+    SortOrder,
+)
+
+__all__ = [
+    "Datamaxi",
+    "Telegram",
+    "Naver",
+    "SPOT",
+    "FUTURES",
+    "USD",
+    "ASC",
+    "DESC",
+    "INTERVAL_1M",
+    "INTERVAL_5M",
+    "INTERVAL_15M",
+    "INTERVAL_30M",
+    "INTERVAL_1H",
+    "INTERVAL_4H",
+    "INTERVAL_12H",
+    "INTERVAL_1D",
+    "SUPPORTED_INTERVALS",
+    "Market",
+    "Interval",
+    "SortOrder",
+]

datamaxi/datamaxi/cex_announcement.py

@@ -1,6 +1,6 @@
 from typing import Any, Dict, Optional, Tuple, Callable
 from datamaxi.api import API
-from datamaxi.lib.constants import ASC, DESC
+from datamaxi.lib.constants import ASC, DESC, SortOrder
 
 
 class CexAnnouncement(API):
@@ -19,7 +19,7 @@ def __call__(
         self,
         page: int = 1,
         limit: int = 1000,
-        sort: str = DESC,
+        sort: SortOrder = DESC,
         key: Optional[str] = None,
         exchange: Optional[str] = None,
         category: Optional[str] = None,

datamaxi/datamaxi/cex_candle.py

@@ -1,10 +1,10 @@
-from typing import Any, List, Dict, Union
+from typing import Any, List, Dict, Union, Optional
 import pandas as pd
 from datamaxi.api import API
 from datamaxi.lib.utils import check_required_parameter
 from datamaxi.lib.utils import check_required_parameters
 from datamaxi.datamaxi.utils import convert_data_to_data_frame
-from datamaxi.lib.constants import SPOT, FUTURES, INTERVAL_1D, USD
+from datamaxi.lib.constants import SPOT, FUTURES, INTERVAL_1D, USD, Market, Interval
 
 
 class CexCandle(API):
@@ -25,10 +25,10 @@ def __init__(self, api_key=None, **kwargs: Any):
     def __call__(
         self,
         exchange: str,
-        market: str,
+        market: Market,
         symbol: str,
         currency: str = USD,
-        interval: str = INTERVAL_1D,
+        interval: Interval = INTERVAL_1D,
         from_unix: str = None,
         to_unix: str = None,
         pandas: bool = True,
@@ -82,7 +82,7 @@ def __call__(
         else:
             return res
 
-    def exchanges(self, market: str) -> List[str]:
+    def exchanges(self, market: Market) -> List[str]:
         """Fetch supported exchanges for candle data.
 
         `GET /api/v1/cex/candle/exchanges`
@@ -102,7 +102,9 @@ def exchanges(self, market: str) -> List[str]:
 
         return self.request_endpoint("cex_candle_exchanges", market=market)
 
-    def symbols(self, exchange: str = None, market: str = None) -> List[Dict]:
+    def symbols(
+        self, exchange: str = None, market: Optional[Market] = None
+    ) -> List[Dict]:
         """Fetch supported symbols for candle data.
 
         `GET /api/v1/cex/candle/symbols`

datamaxi/datamaxi/cex_ticker.py

@@ -2,7 +2,7 @@
 import pandas as pd
 from datamaxi.api import API
 from datamaxi.lib.utils import check_required_parameters
-from datamaxi.lib.constants import SPOT, FUTURES
+from datamaxi.lib.constants import SPOT, FUTURES, Market
 
 
 class CexTicker(API):
@@ -21,7 +21,7 @@ def get(
         self,
         exchange: str,
         symbol: str,
-        market: str,
+        market: Market,
         currency: str = None,
         conversion_base: str = None,
         include_source: bool = False,
@@ -77,7 +77,7 @@ def get(
 
     def exchanges(
         self,
-        market: str,
+        market: Market,
     ) -> List[str]:
         """Fetch supported exchanges for ticker data.
 
@@ -105,7 +105,7 @@ def exchanges(
     def symbols(
         self,
         exchange: str,
-        market: str,
+        market: Market,
     ) -> List[str]:
         """Fetch supported symbols for ticker data.
 

datamaxi/datamaxi/funding_rate.py

@@ -4,7 +4,7 @@
 from datamaxi.lib.utils import check_required_parameter
 from datamaxi.lib.utils import check_required_parameters
 from datamaxi.datamaxi.utils import convert_data_to_data_frame
-from datamaxi.lib.constants import ASC, DESC
+from datamaxi.lib.constants import ASC, DESC, SortOrder
 
 
 class FundingRate(API):
@@ -27,7 +27,7 @@ def history(
         limit: int = 1000,
         fromDateTime: str = None,
         toDateTime: str = None,
-        sort: str = DESC,
+        sort: SortOrder = DESC,
         pandas: bool = True,
     ) -> Union[Tuple[Dict, Callable], Tuple[pd.DataFrame, Callable]]:
         """Fetch historical funding rate data

datamaxi/datamaxi/index_price.py

@@ -1,6 +1,7 @@
 from typing import Any, Dict, Optional
 from datamaxi.api import API
 from datamaxi.lib.utils import check_required_parameter
+from datamaxi.lib.constants import Interval
 
 
 class IndexPrice(API):
@@ -23,7 +24,7 @@ def __call__(
         asset: str,
         from_: Optional[str] = None,
         to: Optional[str] = None,
-        interval: str = "5m",
+        interval: Interval = "5m",
     ) -> Dict[str, Any]:
         """Fetch historical index price data for a single asset.
 

datamaxi/datamaxi/liquidation.py

@@ -1,5 +1,6 @@
 from typing import Any, Dict, Optional
 from datamaxi.api import API
+from datamaxi.lib.constants import Interval
 
 
 class Liquidation(API):
@@ -130,7 +131,7 @@ def symbol_history(
         symbol: str,
         quote: str = "USDT",
         exchange: Optional[str] = None,
-        interval: str = "5m",
+        interval: Interval = "5m",
         window: str = "24h",
     ) -> Dict[str, Any]:
         """Bucketed long / short liquidation USD time series + price line.

datamaxi/datamaxi/open_interest.py

@@ -1,5 +1,6 @@
 from typing import Any, Dict, Optional
 from datamaxi.api import API
+from datamaxi.lib.constants import Interval, SortOrder
 
 
 class OpenInterest(API):
@@ -40,7 +41,7 @@ def overview(
         page: int = 1,
         limit: int = 20,
         key: str = "binance",
-        sort: str = "desc",
+        sort: SortOrder = "desc",
         query: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Paginated token × exchange OI matrix.
@@ -84,7 +85,7 @@ def summary(self, topN: int = 10) -> Dict[str, Any]:
     def history_aggregated(
         self,
         token_id: str,
-        interval: str = "1h",
+        interval: Interval = "1h",
         from_: Optional[int] = None,
         to: Optional[int] = None,
     ) -> Dict[str, Any]:

datamaxi/datamaxi/premium.py

@@ -1,6 +1,7 @@
-from typing import Any, List, Union
+from typing import Any, List, Union, Optional
 import pandas as pd
 from datamaxi.api import API
+from datamaxi.lib.constants import Market, SortOrder
 
 
 class Premium(API):
@@ -25,16 +26,16 @@ def __call__(  # noqa: C901
         asset: str = None,
         source_quote: str = None,
         target_quote: str = None,
-        sort: str = None,
+        sort: Optional[SortOrder] = None,
         key: str = None,
         page: int = 1,
         limit: int = 100,
         currency: str = None,
         conversion_base: str = None,
         min_sv: str = None,
         min_tv: str = None,
-        source_market: str = None,
-        target_market: str = None,
+        source_market: Optional[Market] = None,
+        target_market: Optional[Market] = None,
         only_transferable: bool = False,
         network: str = None,
         premium_type: str = None,

datamaxi/lib/constants.py

@@ -1,4 +1,4 @@
-from typing import Final
+from typing import Final, Literal
 
 BASE_URL: Final = "https://api.datamaxiplus.com"
 SPOT: Final = "spot"
@@ -27,3 +27,10 @@
 
 ASC: Final = "asc"
 DESC: Final = "desc"
+
+# Type aliases for the enumerable string parameters used across the client
+# surface. These are hint-only (Literal is not enforced at runtime), so
+# passing a bare string still works — they exist to give IDE/mypy checking.
+Market = Literal["spot", "futures"]
+Interval = Literal["1m", "5m", "15m", "30m", "1h", "4h", "12h", "1d"]
+SortOrder = Literal["asc", "desc"]

datamaxi/telegram/__init__.py

@@ -1,6 +1,6 @@
 from typing import Any, Dict, Optional, Tuple, Callable
 from datamaxi.api import API
-from datamaxi.lib.constants import BASE_URL
+from datamaxi.lib.constants import BASE_URL, SortOrder
 
 
 class Telegram(API):
@@ -23,7 +23,7 @@ def channels(
         limit: int = 1000,
         category: Optional[str] = None,
         key: Optional[str] = None,
-        sort: str = "desc",
+        sort: SortOrder = "desc",
     ) -> Tuple[Dict[str, Any], Callable]:
         """Get Telegram supported channels
 
@@ -77,7 +77,7 @@ def messages(
         page: int = 1,
         limit: int = 1000,
         key: Optional[str] = None,
-        sort: str = "desc",
+        sort: SortOrder = "desc",
         category: Optional[str] = None,
         search_query: Optional[str] = None,
     ) -> Tuple[Dict[str, Any], Callable]: