stonepy 0.1.0__tar.gz

stonepy-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/

stonepy-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-06-18
+
+- Initial StoneX CIAPI v2 client release.
+- Includes generated endpoint bindings, DTO models, sync and async clients, retry handling,
+  rate-limit handling, and typed resource groups.

stonepy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Morgan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stonepy-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: stonepy
+Version: 0.1.0
+Summary: Python client for the StoneX (CIAPI) v2 trading API
+Project-URL: Homepage, https://github.com/aaronmgn/stonepy
+Project-URL: Repository, https://github.com/aaronmgn/stonepy
+Project-URL: Issues, https://github.com/aaronmgn/stonepy/issues
+Author-email: Aaron Morgan <aaron@dvops.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ciapi,cityindex,stonex,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: simplejson<4.0,>=3.19
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Requires-Dist: types-simplejson; extra == 'dev'
+Requires-Dist: unasync>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# stonepy
+
+Python client for the StoneX (CIAPI) v2 trading API.
+
+## Installation
+
+```bash
+pip install stonepy
+```
+
+Requires Python >= 3.11.
+
+## Quickstart
+
+```python
+from stonepy import ClientConfig, StoneXClient
+from stonepy.models import ApiLogOnRequestDTO
+
+config = ClientConfig(base_url="https://ciapi.cityindex.com/TradingAPI")
+
+with StoneXClient(config) as client:
+    session = client.session.log_on(
+        ApiLogOnRequestDTO(
+            UserName="username",
+            Password="password",
+            AppKey="app-key",
+            AppVersion="stonepy",
+            AppComments="",
+        )
+    )
+    print(session.status_code)
+```
+
+Environment-based configuration is also available:
+
+```python
+from stonepy import ClientConfig, StoneXClient
+
+config = ClientConfig.from_env()
+
+with StoneXClient(config) as client:
+    print(client.session)
+```
+
+`ClientConfig.from_env()` reads `STONEX_BASE_URL`, `STONEX_APP_KEY`, `STONEX_USERNAME`,
+and `STONEX_PASSWORD`. `STONEX_BASE_URL` is required unless `base_url=` is passed.
+
+## Authentication and Sessions
+
+Calling `client.session.log_on(...)` establishes the authenticated session token that the
+client attaches to every subsequent request. The token is held by the client for the life of
+its context manager.
+
+If you supply `app_key`, `username`, and `password` on `ClientConfig` (directly or via
+`ClientConfig.from_env()`), the client also refreshes the session automatically: it
+re-authenticates in the background before the token expires, controlled by
+`ClientConfig.proactive_refresh_seconds` (default `1080.0`, i.e. 18 minutes), and transparently
+re-logs-on if a request is rejected with an expired-session error. Without those credentials you
+must call `log_on` yourself and manage re-authentication.
+
+```python
+config = ClientConfig(
+    base_url="https://ciapi.cityindex.com/TradingAPI",
+    app_key="app-key",
+    username="username",
+    password="password",
+)  # credentials present -> automatic proactive session refresh
+```
+
+## Async Usage
+
+```python
+from stonepy import AsyncStoneXClient, ClientConfig
+from stonepy.models import ApiLogOnRequestDTO
+
+config = ClientConfig(base_url="https://ciapi.cityindex.com/TradingAPI")
+
+async with AsyncStoneXClient(config) as client:
+    session = await client.session.log_on(
+        ApiLogOnRequestDTO(
+            UserName="username",
+            Password="password",
+            AppKey="app-key",
+            AppVersion="stonepy",
+            AppComments="",
+        )
+    )
+    print(session.status_code)
+```
+
+Use `aclose()` for async clients when not using `async with`; use `close()` for sync clients.
+
+## Error Handling
+
+All library exceptions inherit from `StoneXError`.
+
+```python
+from stonepy import RateLimitError, StoneXAPIError, StoneXError, StoneXClient
+
+try:
+    with StoneXClient(config) as client:
+        client.order.list_active_orders(request_dto)
+except RateLimitError as exc:
+    print(exc.retry_after)
+except StoneXAPIError as exc:
+    print(exc.http_status, exc.error_code, exc.error_message)
+except StoneXError as exc:
+    print(exc)
+```
+
+Important subclasses include `AuthenticationError`, `RateLimitError`,
+`OrderRejectedError`, `ResponseParseError`, `StoneXAPIError`, and `TransportError`.
+
+## Pagination
+
+Paginated API methods return the page DTO documented by StoneX. For example,
+`client.market.list_market_search_paginated(...)` accepts `page`, `page_size`, and
+`order_by` keyword arguments and returns `ListMarketSearchPaginatedResponseDTO`:
+
+```python
+page = client.market.list_market_search_paginated(
+    "gold",
+    search_by_market_code=False,
+    search_by_market_name=True,
+    spread_product_type=True,
+    cfd_product_type=True,
+    binary_product_type=False,
+    ascending_order=True,
+    include_options=False,
+    client_account_id=12345,
+    page=0,
+    page_size=100,
+)
+print(page.total_number_of_results)
+```
+
+## API Reference
+
+See `docs/API_REFERENCE.md` for the public package surface and links to the upstream StoneX
+CIAPI v2 documentation.
+
+## Development
+
+```bash
+uv venv
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```

stonepy-0.1.0/README.md

@@ -0,0 +1,151 @@
+# stonepy
+
+Python client for the StoneX (CIAPI) v2 trading API.
+
+## Installation
+
+```bash
+pip install stonepy
+```
+
+Requires Python >= 3.11.
+
+## Quickstart
+
+```python
+from stonepy import ClientConfig, StoneXClient
+from stonepy.models import ApiLogOnRequestDTO
+
+config = ClientConfig(base_url="https://ciapi.cityindex.com/TradingAPI")
+
+with StoneXClient(config) as client:
+    session = client.session.log_on(
+        ApiLogOnRequestDTO(
+            UserName="username",
+            Password="password",
+            AppKey="app-key",
+            AppVersion="stonepy",
+            AppComments="",
+        )
+    )
+    print(session.status_code)
+```
+
+Environment-based configuration is also available:
+
+```python
+from stonepy import ClientConfig, StoneXClient
+
+config = ClientConfig.from_env()
+
+with StoneXClient(config) as client:
+    print(client.session)
+```
+
+`ClientConfig.from_env()` reads `STONEX_BASE_URL`, `STONEX_APP_KEY`, `STONEX_USERNAME`,
+and `STONEX_PASSWORD`. `STONEX_BASE_URL` is required unless `base_url=` is passed.
+
+## Authentication and Sessions
+
+Calling `client.session.log_on(...)` establishes the authenticated session token that the
+client attaches to every subsequent request. The token is held by the client for the life of
+its context manager.
+
+If you supply `app_key`, `username`, and `password` on `ClientConfig` (directly or via
+`ClientConfig.from_env()`), the client also refreshes the session automatically: it
+re-authenticates in the background before the token expires, controlled by
+`ClientConfig.proactive_refresh_seconds` (default `1080.0`, i.e. 18 minutes), and transparently
+re-logs-on if a request is rejected with an expired-session error. Without those credentials you
+must call `log_on` yourself and manage re-authentication.
+
+```python
+config = ClientConfig(
+    base_url="https://ciapi.cityindex.com/TradingAPI",
+    app_key="app-key",
+    username="username",
+    password="password",
+)  # credentials present -> automatic proactive session refresh
+```
+
+## Async Usage
+
+```python
+from stonepy import AsyncStoneXClient, ClientConfig
+from stonepy.models import ApiLogOnRequestDTO
+
+config = ClientConfig(base_url="https://ciapi.cityindex.com/TradingAPI")
+
+async with AsyncStoneXClient(config) as client:
+    session = await client.session.log_on(
+        ApiLogOnRequestDTO(
+            UserName="username",
+            Password="password",
+            AppKey="app-key",
+            AppVersion="stonepy",
+            AppComments="",
+        )
+    )
+    print(session.status_code)
+```
+
+Use `aclose()` for async clients when not using `async with`; use `close()` for sync clients.
+
+## Error Handling
+
+All library exceptions inherit from `StoneXError`.
+
+```python
+from stonepy import RateLimitError, StoneXAPIError, StoneXError, StoneXClient
+
+try:
+    with StoneXClient(config) as client:
+        client.order.list_active_orders(request_dto)
+except RateLimitError as exc:
+    print(exc.retry_after)
+except StoneXAPIError as exc:
+    print(exc.http_status, exc.error_code, exc.error_message)
+except StoneXError as exc:
+    print(exc)
+```
+
+Important subclasses include `AuthenticationError`, `RateLimitError`,
+`OrderRejectedError`, `ResponseParseError`, `StoneXAPIError`, and `TransportError`.
+
+## Pagination
+
+Paginated API methods return the page DTO documented by StoneX. For example,
+`client.market.list_market_search_paginated(...)` accepts `page`, `page_size`, and
+`order_by` keyword arguments and returns `ListMarketSearchPaginatedResponseDTO`:
+
+```python
+page = client.market.list_market_search_paginated(
+    "gold",
+    search_by_market_code=False,
+    search_by_market_name=True,
+    spread_product_type=True,
+    cfd_product_type=True,
+    binary_product_type=False,
+    ascending_order=True,
+    include_options=False,
+    client_account_id=12345,
+    page=0,
+    page_size=100,
+)
+print(page.total_number_of_results)
+```
+
+## API Reference
+
+See `docs/API_REFERENCE.md` for the public package surface and links to the upstream StoneX
+CIAPI v2 documentation.
+
+## Development
+
+```bash
+uv venv
+uv sync --extra dev
+uv run pytest -q
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+```

stonepy-0.1.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "stonepy"
+dynamic = ["version"]
+description = "Python client for the StoneX (CIAPI) v2 trading API"
+requires-python = ">=3.11"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Aaron Morgan", email = "aaron@dvops.io" }]
+keywords = ["stonex", "ciapi", "trading", "cityindex"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1.0", "pydantic>=2.7,<3.0", "simplejson>=3.19,<4.0"]
+
+[project.urls]
+Homepage = "https://github.com/aaronmgn/stonepy"
+Repository = "https://github.com/aaronmgn/stonepy"
+Issues = "https://github.com/aaronmgn/stonepy/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "respx>=0.21",
+    "mypy>=1.10",
+    "ruff>=0.5",
+    "unasync>=0.6",
+    "pre-commit>=3.7",
+    "types-simplejson",
+    "twine>=5",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/stonepy/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stonepy"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/stonepy/py.typed" = "stonepy/py.typed"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/stonepy", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src", "tests"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["src/stonepy"]
+omit = [
+    "src/stonepy/models/*",
+    "src/stonepy/resources/*/_sync/*",
+    "src/stonepy/resources/*/__init__.py",
+]

stonepy-0.1.0/src/stonepy/__init__.py

@@ -0,0 +1,27 @@
+from stonepy._core.config import ClientConfig
+from stonepy._core.errors import (
+    AuthenticationError,
+    OrderRejectedError,
+    RateLimitError,
+    ResponseParseError,
+    StoneXAPIError,
+    StoneXError,
+    TransportError,
+)
+from stonepy.client import AsyncStoneXClient, StoneXClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncStoneXClient",
+    "AuthenticationError",
+    "ClientConfig",
+    "OrderRejectedError",
+    "RateLimitError",
+    "ResponseParseError",
+    "StoneXAPIError",
+    "StoneXClient",
+    "StoneXError",
+    "TransportError",
+    "__version__",
+]

stonepy-0.1.0/src/stonepy/_core/__init__.py

@@ -0,0 +1 @@
+

stonepy-0.1.0/src/stonepy/_core/clock.py

@@ -0,0 +1,49 @@
+"""Clock abstraction so timing logic is testable with a fake clock."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Protocol, runtime_checkable
+
+
+class Clock(Protocol):
+    def now(self) -> float: ...
+    def sleep(self, seconds: float) -> None: ...
+
+
+@runtime_checkable
+class AsyncClock(Clock, Protocol):
+    async def asleep(self, seconds: float) -> None: ...
+
+
+class SystemClock:
+    def now(self) -> float:
+        return time.monotonic()
+
+    def sleep(self, seconds: float) -> None:
+        if seconds > 0:
+            time.sleep(seconds)
+
+    async def asleep(self, seconds: float) -> None:
+        if seconds > 0:
+            await asyncio.sleep(seconds)
+
+
+class FakeClock:
+    def __init__(self) -> None:
+        self._t = 0.0
+
+    def now(self) -> float:
+        return self._t
+
+    def sleep(self, seconds: float) -> None:
+        self._t += max(0.0, seconds)
+
+    async def asleep(self, seconds: float) -> None:
+        self.sleep(seconds)
+
+    def advance(self, seconds: float) -> None:
+        if seconds < 0:
+            raise ValueError("seconds must be non-negative")
+        self._t += seconds

stonepy-0.1.0/src/stonepy/_core/codec.py

@@ -0,0 +1,96 @@
+"""Decimal-safe JSON and WCF (`/Date(ms)/`) date handling."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import UTC, datetime, timedelta
+from decimal import Decimal
+from typing import Annotated, Any, NoReturn, TypeAlias
+
+import simplejson
+from pydantic import BeforeValidator, PlainSerializer
+
+WCF_MINVALUE_MS = -62135596800000
+_WCF_RE = re.compile(r"\\?/Date\((-?\d+)(?:[+-]\d{4})?\)\\?/")
+_UTC_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+_MS_PER_DAY = 86_400_000
+_MS_PER_SECOND = 1_000
+
+
+def _ensure_timezone_aware(value: datetime) -> datetime:
+    if value.utcoffset() is None:
+        raise ValueError("datetime must be timezone-aware")
+    return value
+
+
+def parse_wcf_date(value: Any) -> datetime | None:
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return _ensure_timezone_aware(value)
+    if isinstance(value, bool):
+        raise ValueError(f"not a WCF date: {value!r}")
+    if isinstance(value, int):
+        ms = value
+    elif isinstance(value, str):
+        m = _WCF_RE.fullmatch(value)
+        if not m:
+            raise ValueError(f"not a WCF date: {value!r}")
+        ms = int(m.group(1))
+    else:
+        raise ValueError(f"not a WCF date: {value!r}")
+    if ms == WCF_MINVALUE_MS:
+        return None
+    try:
+        return _UTC_EPOCH + timedelta(milliseconds=ms)
+    except OverflowError as exc:
+        raise ValueError(f"WCF date out of range: {value!r}") from exc
+
+
+def format_wcf_date(value: datetime | None) -> str | None:
+    if value is None:
+        return None
+    aware_value = _ensure_timezone_aware(value)
+    delta = aware_value.astimezone(UTC) - _UTC_EPOCH
+    ms = (
+        delta.days * _MS_PER_DAY
+        + delta.seconds * _MS_PER_SECOND
+        + delta.microseconds // _MS_PER_SECOND
+    )
+    return f"/Date({ms})/"
+
+
+StoneXDateTime: TypeAlias = Annotated[
+    datetime | None,
+    BeforeValidator(parse_wcf_date),
+    PlainSerializer(format_wcf_date, when_used="always"),
+]
+
+
+def _reject_nonfinite_decimals(value: Any) -> None:
+    if isinstance(value, Decimal):
+        if not value.is_finite():
+            raise ValueError("non-finite Decimal values are not valid JSON")
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            _reject_nonfinite_decimals(key)
+            _reject_nonfinite_decimals(item)
+    elif isinstance(value, (list, tuple)):
+        for item in value:
+            _reject_nonfinite_decimals(item)
+
+
+def _reject_json_constant(value: str) -> NoReturn:
+    raise ValueError(f"non-finite JSON constant is not allowed: {value}")
+
+
+def dumps(obj: Any) -> str:
+    _reject_nonfinite_decimals(obj)
+    return simplejson.dumps(obj, use_decimal=True, allow_nan=False, separators=(",", ":"))
+
+
+def loads(text: str | bytes) -> Any:
+    if isinstance(text, bytes):
+        text = text.decode("utf-8")
+    return json.loads(text, parse_float=Decimal, parse_constant=_reject_json_constant)