aress-sdk 0.1.0__py3-none-any.whl

aress_sdk/__init__.py

@@ -0,0 +1,278 @@
+"""Aress SDK — official Python client for the Aress Data API.
+
+Fetch instruments, bonds, currencies and (preview) funds from the Iranian
+capital market over the Aress Data HTTP API.
+
+Quickstart::
+
+    from aress_sdk import AressClient
+
+    with AressClient("<your api key>") as client:
+        for currency in client.currencies.list():
+            print(currency.symbol, currency.farsi_name)
+
+See :class:`AressClient` / :class:`AsyncAressClient` for the full surface.
+"""
+
+from ._version import __version__
+from .client import AressClient, AsyncAressClient
+from .config import (
+    API_KEY_HEADER,
+    DEFAULT_BACKOFF_FACTOR,
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    ClientConfig,
+)
+from .exceptions import (
+    AressAPIStatusError,
+    AressConnectionError,
+    AressError,
+    AressTimeoutError,
+    AressTransportError,
+    AuthenticationError,
+    BadRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    UnprocessableEntityError,
+)
+
+# Domain models — re-exported for convenient typing/imports.
+from .bonds import Bond, BondDailyTradeHistory
+from .currencies import Currency, CurrencyDailyHistory
+from .funds import (
+    CategoryAnnualPeriodAnalysis,
+    CategoryIssueRedeemSeriesItem,
+    CategoryIssueRedeemAnalysisItem,
+    CategoryMonthlyPeriodAnalysis,
+    CategoryPeriodAnalysis,
+    SubFund,
+    FundManager,
+    FundAnalysis,
+    FundNavAndReturnHistoryItem,
+    IndexReturnHistoryItem,
+    FundAnnualPeriodAnalysis,
+    FundAssetAllocation,
+    FundCategory,
+    FundFinancialRegime,
+    FundIssueRedeemSeriesItem,
+    FundMonthlyPeriodAnalysis,
+    FundNavHistoryItem,
+    FundPeriodAnalysis,
+    FundRecentAdjustedNavHistoryItem,
+    FundSummaryAnalysis,
+    FundType,
+    SubFundWithSummaryAnalysis,
+    SubFundFlowsSummary,
+    AumFlowPoint,
+    SubFundDailySeriesPoint,
+    FundMonthlyReturn,
+    RollingPeriodAnalysis,
+    RollingPeriodAnalysisVsBenchmark,
+    RollingPeriodDecomposition,
+    RollingPeriodWindowDecomposition,
+    RollingPeriodWindowAnalysis,
+    RollingPeriodWindowAnalysisVsBenchmark,
+    RollingWindow,
+    TotalIndexAnnualPeriodAnalysis,
+    TotalIndexMonthlyPeriodAnalysis,
+)
+from .instruments import (
+    DailyClientTypeHistory,
+    DailyIndexHistory,
+    DailyTradeHistory,
+    Index,
+    IndexReturnHistoryPoint,
+    Instrument,
+    OptionMarketLive,
+    OptionMarketLiveEntry,
+    OptionMarketLiveLeg,
+    PriceAdjustment,
+    RealtimeClientType,
+    RealtimeIndex,
+    RealtimeInstrument,
+    RealtimeMarket,
+    RealtimeOrderBook,
+    RealtimeOrderBookRow,
+    Sector,
+    ShareChange,
+    SubSector,
+    UnderlyingOptionMarketLive,
+)
+from .ime import (
+    ImeCdcContract,
+    ImeCdcDailyTradeHistory,
+    ImeOptionContract,
+    ImeCdcLive,
+    ImeClientType,
+    ImeListedInstrumentLive,
+    ImeMarketLive,
+    ImeOptionChainLive,
+    ImeOptionExpirationLive,
+    ImeOptionLegLive,
+    ImeOptionStrikeLive,
+    ImeOrderBookRow,
+    ImeUnderlyingOptionChainLive,
+)
+from .market import (
+    MarketListWindow,
+    RealtimeStockFlow,
+    RealtimeStockFlows,
+    SectorTradeValue,
+    SectorTradeValues,
+    StockPriceChange,
+    StockPriceChanges,
+)
+from .tradingview import (
+    TradingViewBar,
+    TradingViewConfig,
+    TradingViewExchange,
+    TradingViewHistory,
+    TradingViewSearchResult,
+    TradingViewSymbolInfo,
+    TradingViewSymbolType,
+)
+from .reports import (
+    AppliedFilter,
+    ReportBatchResultItem,
+    ReportCalculationResultType,
+    ReportCategory,
+    ReportFilter,
+    ReportFilterOption,
+    ReportMetadata,
+    ReportRequest,
+    ReportResult,
+)
+
+__all__ = [
+    "__version__",
+    # clients
+    "AressClient",
+    "AsyncAressClient",
+    # config
+    "ClientConfig",
+    "API_KEY_HEADER",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_BACKOFF_FACTOR",
+    # exceptions
+    "AressError",
+    "AressTransportError",
+    "AressConnectionError",
+    "AressTimeoutError",
+    "AressAPIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "ServerError",
+    # instruments
+    "Sector",
+    "SubSector",
+    "Instrument",
+    "PriceAdjustment",
+    "ShareChange",
+    "DailyTradeHistory",
+    "DailyClientTypeHistory",
+    "Index",
+    "DailyIndexHistory",
+    "IndexReturnHistoryPoint",
+    # realtime
+    "RealtimeOrderBookRow",
+    "RealtimeOrderBook",
+    "RealtimeClientType",
+    "RealtimeInstrument",
+    "RealtimeIndex",
+    "RealtimeMarket",
+    "OptionMarketLiveLeg",
+    "OptionMarketLiveEntry",
+    "UnderlyingOptionMarketLive",
+    "OptionMarketLive",
+    # IME
+    "ImeCdcContract",
+    "ImeOptionContract",
+    "ImeCdcDailyTradeHistory",
+    "ImeOrderBookRow",
+    "ImeClientType",
+    "ImeCdcLive",
+    "ImeListedInstrumentLive",
+    "ImeMarketLive",
+    "ImeOptionLegLive",
+    "ImeOptionStrikeLive",
+    "ImeOptionExpirationLive",
+    "ImeUnderlyingOptionChainLive",
+    "ImeOptionChainLive",
+    # tradingview
+    "TradingViewExchange",
+    "TradingViewSymbolType",
+    "TradingViewConfig",
+    "TradingViewSearchResult",
+    "TradingViewSymbolInfo",
+    "TradingViewBar",
+    "TradingViewHistory",
+    # market lists
+    "MarketListWindow",
+    "StockPriceChange",
+    "StockPriceChanges",
+    "SectorTradeValue",
+    "SectorTradeValues",
+    "RealtimeStockFlow",
+    "RealtimeStockFlows",
+    # bonds
+    "Bond",
+    "BondDailyTradeHistory",
+    # currencies
+    "Currency",
+    "CurrencyDailyHistory",
+    # funds
+    "SubFund",
+    "FundType",
+    "FundCategory",
+    "FundFinancialRegime",
+    "RollingWindow",
+    "FundNavHistoryItem",
+    "FundAnalysis",
+    "FundNavAndReturnHistoryItem",
+    "IndexReturnHistoryItem",
+    "FundSummaryAnalysis",
+    "FundAssetAllocation",
+    "SubFundWithSummaryAnalysis",
+    "FundManager",
+    "SubFundFlowsSummary",
+    "AumFlowPoint",
+    "SubFundDailySeriesPoint",
+    "FundMonthlyReturn",
+    "FundRecentAdjustedNavHistoryItem",
+    "RollingPeriodWindowAnalysis",
+    "RollingPeriodAnalysis",
+    "RollingPeriodWindowAnalysisVsBenchmark",
+    "RollingPeriodAnalysisVsBenchmark",
+    "RollingPeriodDecomposition",
+    "RollingPeriodWindowDecomposition",
+    "FundIssueRedeemSeriesItem",
+    "CategoryIssueRedeemSeriesItem",
+    "CategoryIssueRedeemAnalysisItem",
+    "FundPeriodAnalysis",
+    "FundMonthlyPeriodAnalysis",
+    "FundAnnualPeriodAnalysis",
+    "CategoryPeriodAnalysis",
+    "CategoryMonthlyPeriodAnalysis",
+    "CategoryAnnualPeriodAnalysis",
+    "TotalIndexMonthlyPeriodAnalysis",
+    "TotalIndexAnnualPeriodAnalysis",
+    # reports
+    "ReportMetadata",
+    "ReportCategory",
+    "ReportFilter",
+    "ReportFilterOption",
+    "ReportRequest",
+    "ReportResult",
+    "AppliedFilter",
+    "ReportBatchResultItem",
+    "ReportCalculationResultType",
+]

aress_sdk/_resource.py

@@ -0,0 +1,40 @@
+"""Base classes for resource clients.
+
+Resources are thin: they build the request path/params, delegate the HTTP call
+to a transport, and validate the JSON response into pydantic models. The model
+parsing is shared here so the sync and async resources stay symmetric.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List, Type, TypeVar
+
+from pydantic import TypeAdapter
+
+from ._transport import AsyncTransport, SyncTransport
+from ._types import AressModel
+
+M = TypeVar("M", bound=AressModel)
+
+
+def parse_one(model: Type[M], data: Any) -> M:
+    return model.model_validate(data)
+
+
+def parse_list(model: Type[M], data: Any) -> List[M]:
+    adapter: TypeAdapter = TypeAdapter(List[model])  # type: ignore[valid-type]
+    return adapter.validate_python(data)
+
+
+class SyncResource:
+    """Base for synchronous resource clients."""
+
+    def __init__(self, transport: SyncTransport) -> None:
+        self._t = transport
+
+
+class AsyncResource:
+    """Base for asynchronous resource clients."""
+
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._t = transport

aress_sdk/_transport.py

@@ -0,0 +1,271 @@
+"""HTTP transport: thin wrappers over ``httpx`` clients.
+
+Two transports share one retry/error-mapping policy:
+
+* :class:`SyncTransport`  — wraps :class:`httpx.Client`.
+* :class:`AsyncTransport` — wraps :class:`httpx.AsyncClient`.
+
+Resources call ``transport.get(path, params=...)`` and get back parsed JSON
+(``dict``/``list``); non-2xx responses are turned into
+:class:`~aress_sdk.exceptions.AressAPIStatusError` subclasses, and transport
+failures into :class:`~aress_sdk.exceptions.AressTransportError` subclasses.
+Retries (with exponential backoff) cover connection errors, timeouts, 5xx and
+429.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from .config import ClientConfig
+from .exceptions import (
+    AressConnectionError,
+    AressTimeoutError,
+    AressTransportError,
+    error_from_response,
+)
+
+# Status codes worth retrying (the request is read-only, so this is always safe).
+_RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+
+def _clean_params(params: Optional[Mapping[str, Any]]) -> Optional[dict]:
+    """Drop ``None`` values so optional filters become "not sent"."""
+    if not params:
+        return None
+    return {key: value for key, value in params.items() if value is not None}
+
+
+def _should_retry_status(status_code: int) -> bool:
+    return status_code in _RETRYABLE_STATUS
+
+
+def _backoff_seconds(config: ClientConfig, attempt: int) -> float:
+    """Exponential backoff: factor * 2**attempt (attempt is 0-based)."""
+    return config.backoff_factor * (2 ** attempt)
+
+
+def _wrap_transport_error(exc: httpx.HTTPError) -> AressTransportError:
+    request = getattr(exc, "request", None)
+    if isinstance(exc, httpx.TimeoutException):
+        return AressTimeoutError(f"Request timed out: {exc}", request=request)
+    if isinstance(exc, httpx.ConnectError):
+        return AressConnectionError(f"Failed to connect to the API: {exc}", request=request)
+    return AressConnectionError(f"Transport error: {exc}", request=request)
+
+
+class _BaseTransport:
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+
+    @property
+    def base_url(self) -> str:
+        return self._config.normalized_base_url()
+
+    @property
+    def config(self) -> ClientConfig:
+        """The client configuration, so resources can read per-endpoint budgets."""
+        return self._config
+
+
+class SyncTransport(_BaseTransport):
+    """Synchronous transport backed by :class:`httpx.Client`."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        *,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        super().__init__(config)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(
+            base_url=config.normalized_base_url(),
+            timeout=config.timeout,
+            headers=config.default_headers(),
+        )
+
+    def get(self, path: str, *, params: Optional[Mapping[str, Any]] = None) -> Any:
+        clean = _clean_params(params)
+        last_exc: Optional[AressTransportError] = None
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._client.get(
+                    path, params=clean, headers=self._config.auth_headers()
+                )
+            except httpx.HTTPError as exc:
+                last_exc = _wrap_transport_error(exc)
+                if attempt < self._config.max_retries:
+                    time.sleep(_backoff_seconds(self._config, attempt))
+                    continue
+                raise last_exc
+
+            if response.is_success:
+                return _decode(response)
+
+            if _should_retry_status(response.status_code) and attempt < self._config.max_retries:
+                time.sleep(_backoff_seconds(self._config, attempt))
+                continue
+
+            raise error_from_response(response)
+
+        # Unreachable, but keeps type checkers happy.
+        assert last_exc is not None
+        raise last_exc
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        """POST a JSON body and return the parsed JSON response.
+
+        Same retry/error policy as :meth:`get`. The reports calculation
+        endpoints are read-only despite using POST (the body carries filter
+        selections), so retrying transient failures is safe.
+
+        ``timeout`` overrides the client-level timeout for this request only,
+        and applies **per attempt** — slow endpoints (report calculations) pass
+        their own budget rather than inflating it for the whole client.
+        """
+        last_exc: Optional[AressTransportError] = None
+        request_timeout = self._config.timeout if timeout is None else timeout
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = self._client.post(
+                    path,
+                    json=json,
+                    timeout=request_timeout,
+                    headers=self._config.auth_headers(),
+                )
+            except httpx.HTTPError as exc:
+                last_exc = _wrap_transport_error(exc)
+                if attempt < self._config.max_retries:
+                    time.sleep(_backoff_seconds(self._config, attempt))
+                    continue
+                raise last_exc
+
+            if response.is_success:
+                return _decode(response)
+
+            if _should_retry_status(response.status_code) and attempt < self._config.max_retries:
+                time.sleep(_backoff_seconds(self._config, attempt))
+                continue
+
+            raise error_from_response(response)
+
+        assert last_exc is not None
+        raise last_exc
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+
+class AsyncTransport(_BaseTransport):
+    """Asynchronous transport backed by :class:`httpx.AsyncClient`."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        *,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        super().__init__(config)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            base_url=config.normalized_base_url(),
+            timeout=config.timeout,
+            headers=config.default_headers(),
+        )
+
+    async def get(self, path: str, *, params: Optional[Mapping[str, Any]] = None) -> Any:
+        import asyncio
+
+        clean = _clean_params(params)
+        last_exc: Optional[AressTransportError] = None
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._client.get(
+                    path, params=clean, headers=self._config.auth_headers()
+                )
+            except httpx.HTTPError as exc:
+                last_exc = _wrap_transport_error(exc)
+                if attempt < self._config.max_retries:
+                    await asyncio.sleep(_backoff_seconds(self._config, attempt))
+                    continue
+                raise last_exc
+
+            if response.is_success:
+                return _decode(response)
+
+            if _should_retry_status(response.status_code) and attempt < self._config.max_retries:
+                await asyncio.sleep(_backoff_seconds(self._config, attempt))
+                continue
+
+            raise error_from_response(response)
+
+        assert last_exc is not None
+        raise last_exc
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: Optional[Any] = None,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        """Async counterpart of :meth:`SyncTransport.post`; ``timeout``
+        overrides the client-level timeout for this request only, per attempt."""
+        import asyncio
+
+        last_exc: Optional[AressTransportError] = None
+        request_timeout = self._config.timeout if timeout is None else timeout
+
+        for attempt in range(self._config.max_retries + 1):
+            try:
+                response = await self._client.post(
+                    path,
+                    json=json,
+                    timeout=request_timeout,
+                    headers=self._config.auth_headers(),
+                )
+            except httpx.HTTPError as exc:
+                last_exc = _wrap_transport_error(exc)
+                if attempt < self._config.max_retries:
+                    await asyncio.sleep(_backoff_seconds(self._config, attempt))
+                    continue
+                raise last_exc
+
+            if response.is_success:
+                return _decode(response)
+
+            if _should_retry_status(response.status_code) and attempt < self._config.max_retries:
+                await asyncio.sleep(_backoff_seconds(self._config, attempt))
+                continue
+
+            raise error_from_response(response)
+
+        assert last_exc is not None
+        raise last_exc
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+
+def _decode(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError as exc:
+        raise AressConnectionError(
+            f"Expected JSON from {response.request.url} but got non-JSON body"
+        ) from exc

aress_sdk/_types.py

@@ -0,0 +1,71 @@
+"""Shared field types and the base response model.
+
+The API serializes Jalali (Persian) dates as ISO ``YYYY-MM-DD`` strings (e.g.
+``"1403-01-15"``). On the SDK side we parse them back into
+:class:`jdatetime.date` so callers get real date objects with calendar
+arithmetic, and serialize them back to the same ISO string.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import jdatetime
+from pydantic import BaseModel, ConfigDict, GetCoreSchemaHandler
+from pydantic.json_schema import GetJsonSchemaHandler, JsonSchemaValue
+from pydantic_core import core_schema
+
+
+class _JalaliDatePydanticAnnotation:
+    """Pydantic v2 support for :class:`jdatetime.date`.
+
+    Accepts a ``jdatetime.date`` or an ISO ``YYYY-MM-DD`` Jalali string and
+    serializes to the ISO string form.
+    """
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, _source_type: Any, _handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        def validate(value: Any) -> jdatetime.date:
+            if isinstance(value, jdatetime.date):
+                return value
+            if isinstance(value, str):
+                try:
+                    year, month, day = (int(part) for part in value.split("-"))
+                    return jdatetime.date(year, month, day)
+                except (ValueError, TypeError) as exc:
+                    raise ValueError(f"Invalid Jalali date: {value!r}") from exc
+            raise ValueError(f"Invalid Jalali date: {value!r}")
+
+        return core_schema.no_info_plain_validator_function(
+            validate,
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                lambda value: value.isoformat(),
+                return_schema=core_schema.str_schema(),
+            ),
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, _schema: core_schema.CoreSchema, _handler: GetJsonSchemaHandler
+    ) -> JsonSchemaValue:
+        return {"type": "string", "format": "date", "example": "1403-01-15"}
+
+
+#: A Jalali calendar date (``jdatetime.date``) usable as a pydantic field type.
+JalaliDate = Annotated[jdatetime.date, _JalaliDatePydanticAnnotation]
+
+
+class AressModel(BaseModel):
+    """Base class for all response models returned by the SDK.
+
+    Configured to ignore unknown fields, so the SDK keeps working when the API
+    adds new fields to a response.
+    """
+
+    model_config = ConfigDict(
+        extra="ignore",
+        frozen=False,
+        populate_by_name=True,
+    )

aress_sdk/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the SDK version."""
+
+__version__ = "0.1.0"

aress_sdk/bonds/__init__.py

@@ -0,0 +1,11 @@
+"""Bonds domain: bonds and their daily trade history."""
+
+from .models import Bond, BondDailyTradeHistory
+from .resource import AsyncBondsResource, BondsResource
+
+__all__ = [
+    "Bond",
+    "BondDailyTradeHistory",
+    "BondsResource",
+    "AsyncBondsResource",
+]