dojosdk 0.1.0__py3-none-any.whl

dojo/__init__.py

@@ -0,0 +1,38 @@
+from dojo.client.sync import Dojo as Dojo
+from dojo.client.async_client import AsyncDojo as AsyncDojo
+
+from dojo._exceptions import (
+    DojoError as DojoError,
+    APIError as APIError,
+    APIConnectionError as APIConnectionError,
+    APITimeoutError as APITimeoutError,
+    APIResponseValidationError as APIResponseValidationError,
+    APIStatusError as APIStatusError,
+    BadRequestError as BadRequestError,
+    AuthenticationError as AuthenticationError,
+    PermissionDeniedError as PermissionDeniedError,
+    NotFoundError as NotFoundError,
+    ConflictError as ConflictError,
+    UnprocessableEntityError as UnprocessableEntityError,
+    RateLimitError as RateLimitError,
+    InternalServerError as InternalServerError,
+)
+
+__all__ = [
+    "Dojo",
+    "AsyncDojo",
+    "DojoError",
+    "APIError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIResponseValidationError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+]

dojo/_compat.py

@@ -0,0 +1,38 @@
+from typing import Any, Type, TypeVar
+
+try:
+    # Pydantic v2
+    from pydantic import BaseModel
+
+    PYDANTIC_V1 = False
+except ImportError:
+    # Pydantic v1 fallback
+    from pydantic import BaseModel  # type: ignore[no-redef]
+
+    PYDANTIC_V1 = True
+
+_T = TypeVar("_T", bound=BaseModel)
+
+
+def model_dump(model: BaseModel, **kwargs: Any) -> dict[str, Any]:
+    """Dump model to a dict, compatible across Pydantic v1 and v2."""
+    if PYDANTIC_V1:
+        return getattr(model, "dict")(**kwargs)  # type: ignore
+    else:
+        return getattr(model, "model_dump")(**kwargs)
+
+
+def model_validate(model_cls: Type[_T], obj: Any) -> _T:
+    """Validate and construct a model from a dict/object, compatible across Pydantic v1 and v2."""
+    if PYDANTIC_V1:
+        return getattr(model_cls, "parse_obj")(obj)  # type: ignore
+    else:
+        return getattr(model_cls, "model_validate")(obj)
+
+
+def model_construct(model_cls: Type[_T], **kwargs: Any) -> _T:
+    """Construct a model without validation, compatible across Pydantic v1 and v2."""
+    if PYDANTIC_V1:
+        return getattr(model_cls, "construct")(**kwargs)  # type: ignore
+    else:
+        return getattr(model_cls, "model_construct")(**kwargs)

dojo/_exceptions.py

@@ -0,0 +1,103 @@
+import httpx
+from typing import Any
+
+
+class DojoError(Exception):
+    """Base exception for all DojoSDK errors."""
+
+    pass
+
+
+class APIError(DojoError):
+    """Base class for errors related to interacting with the Dojo API."""
+
+    pass
+
+
+class APIConnectionError(APIError):
+    """Raised when the SDK fails to connect to the Dojo API service."""
+
+    def __init__(self, message: str = "Connection error.", *, request: httpx.Request | None = None) -> None:
+        super().__init__(message)
+        self.request = request
+
+
+class APITimeoutError(APIConnectionError):
+    """Raised when a request to the Dojo API times out."""
+
+    def __init__(self, message: str = "Request timed out.", *, request: httpx.Request | None = None) -> None:
+        super().__init__(message, request=request)
+
+
+class APIResponseValidationError(APIError):
+    """Raised when the API response does not conform to the expected Pydantic schema."""
+
+    def __init__(self, response: httpx.Response, body: Any, message: str = "API response did not match expected schema.") -> None:
+        super().__init__(message)
+        self.response = response
+        self.status_code = response.status_code
+        self.body = body
+
+
+class APIStatusError(APIError):
+    """Raised when the Dojo API returns a non-2xx status code."""
+
+    def __init__(self, message: str, *, response: httpx.Response, body: Any) -> None:
+        super().__init__(message)
+        self.response = response
+        self.status_code = response.status_code
+        self.body = body
+
+
+class BadRequestError(APIStatusError):
+    """HTTP 400 Bad Request."""
+
+    pass
+
+
+class AuthenticationError(APIStatusError):
+    """HTTP 401 Unauthorized."""
+
+    pass
+
+
+class PermissionDeniedError(APIStatusError):
+    """HTTP 403 Forbidden."""
+
+    pass
+
+
+class NotFoundError(APIStatusError):
+    """HTTP 404 Not Found."""
+
+    pass
+
+
+class ConflictError(APIStatusError):
+    """HTTP 409 Conflict."""
+
+    pass
+
+
+class UnprocessableEntityError(APIStatusError):
+    """HTTP 422 Unprocessable Entity."""
+
+    pass
+
+
+class RateLimitError(APIStatusError):
+    """HTTP 429 Rate Limit Exceeded."""
+
+    pass
+
+
+class InternalServerError(APIStatusError):
+    """HTTP 500+ Internal Server Error."""
+
+    pass
+
+
+class OfflineDataNotAvailableError(DojoError):
+    """Offline data is not available for the requested endpoint or parameters."""
+
+    pass

dojo/client/async_client.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import os
+from typing import Mapping, Union, TYPE_CHECKING
+from functools import cached_property
+import httpx
+
+if TYPE_CHECKING:
+    from dojo.resources.stocks import AsyncStocks
+    from dojo.resources.market_data import AsyncMarketData, AsyncIndices, AsyncInstruments
+    from dojo.resources.macro import AsyncMacro
+    from dojo.resources.benchmark import AsyncBenchmark
+    from dojo.resources.concepts import AsyncConcepts
+    from dojo.resources.news import AsyncNews
+    from dojo.resources.forex import AsyncForex
+    from dojo.resources.user import AsyncUser
+    from dojo.resources.sectors import AsyncSectors
+    from dojo.resources.strategy import AsyncStrategy
+    from dojo.resources.cache import AsyncCache
+
+from dojo.client.base import AsyncAPIClient
+from dojo._exceptions import DojoError
+
+
+class AsyncDojo(AsyncAPIClient):
+    """Asynchronous Dojo API Client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: Union[float, httpx.Timeout] = 300.0,
+        max_retries: int = 1,
+        http_client: httpx.AsyncClient | None = None,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+        return_raw_data: bool = True,
+    ) -> None:
+        """Constructs a new asynchronous Dojo client instance.
+
+        Parameters
+        ----------
+        api_key : str, optional
+            The token used to authenticate requests. If not provided, it is loaded
+            from the DOJO_API_KEY environment variable.
+        base_url : str, optional
+            The base URL of the Dojo API. Defaults to https://api.flowhale.ai.
+        timeout : float or httpx.Timeout, default 300.0
+            Maximum time (in seconds) to wait for an HTTP request before timing out.
+        max_retries : int, default 1
+            Number of times to retry failed requests on connection errors/rate limits.
+        http_client : httpx.AsyncClient, optional
+            A custom httpx AsyncClient instance to use for sending requests.
+        default_headers : dict, optional
+            A dictionary of custom HTTP headers to send with every request.
+        default_query : dict, optional
+            A dictionary of custom query parameters to send with every request.
+        return_raw_data : bool, default True
+            If True, API responses are returned as native Python dictionaries/lists,
+            skipping Pydantic model validation.
+        """
+        from dojo.datasource.config import is_online, HFConfig
+        from dojo.datasource.huggingface import HuggingFaceKlineDataSource
+
+        self._online = is_online()
+
+        api_key = api_key or os.environ.get("DOJO_API_KEY")
+        if self._online and not api_key:
+            raise DojoError("Missing authentication credentials. Please pass an `api_key` or set " "the `DOJO_API_KEY` environment variable.")
+        self.api_key = api_key
+
+        self._data_source = None
+        if not self._online:
+            self._data_source = HuggingFaceKlineDataSource(HFConfig.from_env())
+
+        base_url = base_url or os.environ.get("DOJO_BASE_URL") or "https://api.flowhale.ai"
+
+        if http_client is None:
+            # Default pool limits
+            limits = httpx.Limits(max_connections=100, max_keepalive_connections=20)
+            http_client = httpx.AsyncClient(
+                limits=limits,
+                timeout=timeout,
+                follow_redirects=True,
+            )
+        self._client = http_client
+
+        super().__init__(
+            base_url=base_url,
+            max_retries=max_retries,
+            custom_headers=default_headers,
+            custom_query=default_query,
+            return_raw_data=return_raw_data,
+        )
+
+    @property
+    def auth_headers(self) -> dict[str, str]:
+        """Returns the authorization headers containing the Bearer token."""
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    @property
+    def default_headers(self) -> dict[str, str]:
+        """Returns the default headers containing auth and telemetry details."""
+        headers = super().default_headers
+        headers.update(self.auth_headers)
+        return headers
+
+    def start_background_sync(self, interval_days: int = 1) -> None:
+        """Starts a background daemon thread that refreshes offline datasets periodically.
+
+        Parameters
+        ----------
+        interval_days : int
+            The number of days between each refresh. Defaults to 1.
+        """
+        if self._data_source is not None and hasattr(self._data_source, "start_background_sync"):
+            self._data_source.start_background_sync(interval_days=interval_days)
+
+    def stop_background_sync(self) -> None:
+        """Stops the background dataset refresh thread."""
+        if self._data_source is not None and hasattr(self._data_source, "stop_background_sync"):
+            self._data_source.stop_background_sync()
+
+    async def preload_offline_data(self, paths: list[str] | None = None) -> None:
+        """Preload specific offline data resources into memory to avoid latency on first request."""
+        if self._data_source is not None and hasattr(self._data_source, "preload"):
+            import asyncio
+
+            if paths is None:
+                from dojo.datasource.registry import HF_REGISTRY
+
+                paths = list(HF_REGISTRY.keys())
+            await asyncio.to_thread(self._data_source.preload, paths)
+
+    async def upload_dataset(self, dataset_name: str, local_folder: str, token: str | None = None) -> None:
+        """Uploads a local folder as a dataset to HuggingFace Hub using a background thread."""
+        import asyncio
+        from dojo.datasource.upload import upload_dataset as sync_upload_dataset
+
+        await asyncio.to_thread(sync_upload_dataset, dataset_name, local_folder, token)
+
+    async def download_dataset(self, dataset_name: str, local_folder: str, token: str | None = None) -> None:
+        """Downloads a dataset from HuggingFace Hub to a local folder using a background thread."""
+        import asyncio
+        from dojo.datasource.upload import download_dataset as sync_download_dataset
+
+        await asyncio.to_thread(sync_download_dataset, dataset_name, local_folder, token)
+
+    @cached_property
+    def stocks(self) -> AsyncStocks:
+        """Access the stocks resource namespace for stock quotes, fundamentals, news, and metrics."""
+        from dojo.resources.stocks import AsyncStocks
+
+        return AsyncStocks(self)
+
+    @cached_property
+    def market_data(self) -> AsyncMarketData:
+        """Access the market_data resource namespace for public real-time tickers, order books, and klines."""
+        from dojo.resources.market_data import AsyncMarketData
+
+        return AsyncMarketData(self)
+
+    @cached_property
+    def macro(self) -> AsyncMacro:
+        """Access the macro resource namespace for macroeconomic data, news, and metrics."""
+        from dojo.resources.macro import AsyncMacro
+
+        return AsyncMacro(self)
+
+    @cached_property
+    def benchmark(self) -> AsyncBenchmark:
+        """Access the benchmark resource namespace for index benchmarks and index klines."""
+        from dojo.resources.benchmark import AsyncBenchmark
+
+        return AsyncBenchmark(self)
+
+    @cached_property
+    def concepts(self) -> AsyncConcepts:
+        """Access the concepts resource namespace for concept themes and constituents."""
+        from dojo.resources.concepts import AsyncConcepts
+
+        return AsyncConcepts(self)
+
+    @cached_property
+    def news(self) -> AsyncNews:
+        """Access the news resource namespace for general news, news sentiment scores, and events."""
+        from dojo.resources.news import AsyncNews
+
+        return AsyncNews(self)
+
+    @cached_property
+    def forex(self) -> AsyncForex:
+        """Access the forex resource namespace for forex quotes, klines, and symbol lists."""
+        from dojo.resources.forex import AsyncForex
+
+        return AsyncForex(self)
+
+    @cached_property
+    def user(self) -> AsyncUser:
+        """Access the user resource namespace for user traits management and analytics."""
+        from dojo.resources.user import AsyncUser
+
+        return AsyncUser(self)
+
+    @cached_property
+    def sectors(self) -> AsyncSectors:
+        """Access the sectors resource namespace for sector/industry listings and metrics."""
+        from dojo.resources.sectors import AsyncSectors
+
+        return AsyncSectors(self)
+
+    @cached_property
+    def strategy(self) -> AsyncStrategy:
+        """Access the strategy resource namespace for classic strategy demos and backtest results."""
+        from dojo.resources.strategy import AsyncStrategy
+
+        return AsyncStrategy(self)
+
+    @cached_property
+    def cache(self) -> AsyncCache:
+        """Access the cache resource namespace for resetting/clearing cached data."""
+        from dojo.resources.cache import AsyncCache
+
+        return AsyncCache(self)
+
+    @cached_property
+    def indices(self) -> AsyncIndices:
+        """Access the indices resource namespace for standard index list retrieval."""
+        from dojo.resources.market_data import AsyncIndices
+
+        return AsyncIndices(self)
+
+    @cached_property
+    def instruments(self) -> AsyncInstruments:
+        """Access the instruments resource namespace for exchange tradable instruments listing."""
+        from dojo.resources.market_data import AsyncInstruments
+
+        return AsyncInstruments(self)