stonepy 0.2.2__tar.gz → 0.2.4__tar.gz

{stonepy-0.2.2 → stonepy-0.2.4}/CHANGELOG.md

@@ -7,6 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-06-29
+
+### Added
+
+- First-class support for endpoints whose success body is a bare top-level JSON array, via a
+  `ListResponse[Item]` response wrapper. The pipeline validates each element and the wrapper returns
+  a plain `list[Item]`.
+- Live write round-trips (`save` + read-back + delete) for client preferences and watchlists, now
+  that their request models are correct.
+
+### Fixed
+
+- `order.get_orders` and `order.get_order_history` now return `list[EnrichedOrderDTO]` /
+  `list[OrderHistoryDTO]`. The API returns a bare JSON array, but they were typed as single objects,
+  so every call raised a response-parse error (a return-type change)
+  ([#24](https://github.com/aaronmgn/stonepy/issues/24)).
+- `client_preference.save_client_preference` and `watchlist.save_watchlist` now succeed. Their
+  request bodies wrap a single object (`ClientPreference`, `Watchlist`), but the models typed them
+  as lists, so the API rejected every call with HTTP 400
+  ([#24](https://github.com/aaronmgn/stonepy/issues/24)).
+- `watchlist.delete_watchlist` now sends its `ClientAccountId` / `WatchlistId` as query parameters
+  rather than in the body, which the live API requires (a body request 400s)
+  ([#24](https://github.com/aaronmgn/stonepy/issues/24)).
+
+## [0.2.3] - 2026-06-28
+
+### Added
+
+- A live contract-test suite (`tests/live/`) that exercises the generated client against the real
+  CIAPI demo account, run nightly and on demand by a new `live` GitHub Actions workflow. It is
+  skipped unless `STONEX_*` credentials are configured, so the normal test run is unaffected. It
+  caught the two response-parsing fixes below and a set of model mismatches tracked in
+  [#24](https://github.com/aaronmgn/stonepy/issues/24).
+
+### Fixed
+
+- Response models now parse CIAPI's v2 camelCase JSON. The generated models alias fields with the
+  catalog's PascalCase, but the v2 endpoints return camelCase, so with `extra="ignore"` the typed
+  client silently dropped the body to all-`None` (for example `watchlist.get_watchlists` and the
+  `client_preference` lookups returned empty). `ResponseModel` now matches response keys to field
+  aliases case-insensitively, at every nesting level.
+- Datetime fields now parse the ISO 8601 values v2 endpoints return (for example
+  `2026-06-29T21:05:00Z`), in addition to the v1 WCF `/Date(ms)/` format.
+- Correct four response field types the frozen catalog mistypes, verified against the live API, so
+  the affected endpoints parse instead of raising: news story ids are strings (Reuters URNs), a
+  news payload is a list of stories, a market carries a list of spreads, and market state is a
+  single enum. This fixes `news.get_news`, `news.get_news_headlines`,
+  `news.get_market_report_headlines`, `market.get_market_information`, and
+  `market.list_market_information_search`
+  ([#24](https://github.com/aaronmgn/stonepy/issues/24)).
+- `user_account.get_client_and_trading_account()` now returns the populated account data. The
+  endpoint returns the `AccountResult` fields flat at the top level, but the declared response
+  model wrapped them under an `account_result` key, so the typed client always parsed an all-`None`
+  result. The method now returns `AccountResult` directly (a return-type change)
+  ([#24](https://github.com/aaronmgn/stonepy/issues/24)).
+
 ## [0.2.2] - 2026-06-28
 
 ### Fixed
@@ -165,7 +221,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Generated endpoint bindings, DTO models, synchronous and asynchronous clients, retry handling,
   rate-limit handling, and typed resource groups.
 
-[Unreleased]: https://github.com/aaronmgn/stonepy/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/aaronmgn/stonepy/compare/v0.2.4...HEAD
+[0.2.4]: https://github.com/aaronmgn/stonepy/releases/tag/v0.2.4
+[0.2.3]: https://github.com/aaronmgn/stonepy/releases/tag/v0.2.3
 [0.2.2]: https://github.com/aaronmgn/stonepy/releases/tag/v0.2.2
 [0.2.1]: https://github.com/aaronmgn/stonepy/releases/tag/v0.2.1
 [0.2.0]: https://github.com/aaronmgn/stonepy/releases/tag/v0.2.0

{stonepy-0.2.2 → stonepy-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stonepy
-Version: 0.2.2
+Version: 0.2.4
 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

{stonepy-0.2.2 → stonepy-0.2.4}/pyproject.toml

@@ -80,6 +80,9 @@ files = ["src", "tests"]
 [tool.pytest.ini_options]
 addopts = "-q"
 testpaths = ["tests"]
+markers = [
+    "live: exercises endpoints against the real CIAPI demo account (needs STONEX_* creds; skipped otherwise)",
+]
 
 [tool.coverage.run]
 source = ["src/stonepy"]

{stonepy-0.2.2 → stonepy-0.2.4}/src/stonepy/__init__.py

@@ -18,7 +18,7 @@ from stonepy._core.errors import (
 )
 from stonepy.client import AsyncStoneXClient, StoneXClient
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 __all__ = [
     "AsyncStoneXClient",

{stonepy-0.2.2 → stonepy-0.2.4}/src/stonepy/_core/codec.py

@@ -43,9 +43,16 @@ def parse_wcf_date(value: Any) -> datetime | None:
         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))
+        if m:
+            ms = int(m.group(1))
+        else:
+            # CIAPI v2 endpoints return ISO 8601 (e.g. "2026-06-29T21:05:00Z") rather than the
+            # v1 WCF "/Date(ms)/" format; accept both so one codec serves both API versions.
+            try:
+                parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+            except ValueError:
+                raise ValueError(f"not a WCF date: {value!r}") from None
+            return _ensure_timezone_aware(parsed)
     else:
         raise ValueError(f"not a WCF date: {value!r}")
     if ms == WCF_MINVALUE_MS:

{stonepy-0.2.2 → stonepy-0.2.4}/src/stonepy/_core/config.py

@@ -11,7 +11,7 @@ from stonepy._core.logging import safe_repr
 from stonepy._core.status import StatusDecoder, default_status_decoder
 
 _T = TypeVar("_T")
-_FALLBACK_VERSION = "0.2.2"
+_FALLBACK_VERSION = "0.2.4"
 
 
 def _default_user_agent() -> str:

stonepy-0.2.4/src/stonepy/_core/models.py

@@ -0,0 +1,97 @@
+"""Base Pydantic models for requests and responses."""
+
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, RootModel, model_validator
+
+from stonepy._core.codec import StoneXDateTime
+
+__all__ = [
+    "ListResponse",
+    "PassthroughResponseModel",
+    "RequestModel",
+    "ResponseModel",
+    "StoneXDateTime",
+    "StoneXModel",
+]
+
+ItemT = TypeVar("ItemT", bound=BaseModel)
+
+
+class StoneXModel(BaseModel):
+    """Base model for every generated StoneX DTO.
+
+    Enables ``populate_by_name`` so fields can be set with their snake_case Python names or
+    their upstream PascalCase aliases, and ``use_attribute_docstrings`` so each generated
+    field's docstring also becomes its JSON-schema description. ``model_config`` is merged
+    across subclasses, so both behaviors apply to every request and response model.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, use_attribute_docstrings=True)
+
+
+class RequestModel(StoneXModel):
+    """Base model for request bodies. Rejects unknown fields (``extra="forbid"``).
+
+    Forbidding extras surfaces typos and stale fields as validation errors before a request
+    is sent, rather than silently dropping them.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class ResponseModel(StoneXModel):
+    """Base model for response bodies. Ignores unknown fields (``extra="ignore"``).
+
+    Ignoring extras lets the client tolerate new or undocumented fields the API adds without
+    raising, so responses keep parsing across upstream changes.
+
+    Response keys are matched to field aliases case-insensitively: CIAPI's v2 endpoints return
+    camelCase JSON (for example ``clientAccountWatchlists``) while the generated models alias
+    fields with the catalog's PascalCase (``ClientAccountWatchlists``). Without this, an
+    exact-case match would miss every camelCase key and ``extra="ignore"`` would silently drop
+    the data, leaving the parsed model empty. The remap runs at every nesting level because each
+    nested model is itself a ``ResponseModel``.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _match_keys_case_insensitively(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        canonical: dict[str, str] = {}
+        for name, field in cls.model_fields.items():
+            target = field.alias or name
+            canonical.setdefault(name.lower(), target)
+            if field.alias:
+                canonical.setdefault(field.alias.lower(), target)
+        remapped: dict[str, Any] = {}
+        for key, value in data.items():
+            target = canonical.get(key.lower(), key) if isinstance(key, str) else key
+            remapped.setdefault(target, value)
+        return remapped
+
+
+class ListResponse(RootModel[list[ItemT]], Generic[ItemT]):
+    """Response wrapper for endpoints whose success body is a bare top-level JSON array.
+
+    CIAPI's order-query endpoints (for example ``order.get_orders``) return a top-level JSON array
+    rather than an object, which an ordinary ``ResponseModel`` cannot validate. Their
+    ``response_model`` is set to ``ListResponse[Item]``; the pipeline validates each element as
+    ``Item`` and the generated wrapper returns ``root`` (a ``list[Item]``), so callers receive a
+    plain list. Each element is still a ``ResponseModel``, so case-insensitive key matching applies.
+    """
+
+
+class PassthroughResponseModel(StoneXModel):
+    """Response model that retains unknown fields (``extra="allow"``).
+
+    Used for endpoints whose response type is not described in the catalog: every field is
+    preserved on the model instance so callers can still read the raw payload.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")

{stonepy-0.2.2 → stonepy-0.2.4}/src/stonepy/_core/pipeline.py

@@ -11,7 +11,7 @@ from math import isfinite
 from typing import Any, Protocol, TypeVar, cast, runtime_checkable
 
 import httpx
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, RootModel
 from pydantic import ValidationError as PydanticValidationError
 
 from stonepy._core import codec
@@ -417,8 +417,10 @@ class CallContext:
 
     def _parse_success(self, spec: EndpointSpec[ResponseT], resp: httpx.Response) -> ResponseT:
         model = parse_response(spec, resp)
-        if self.config.status_decoder is not None and _should_check_business_status(
-            spec, self.config.status_decoder
+        if (
+            not isinstance(model, RootModel)
+            and self.config.status_decoder is not None
+            and _should_check_business_status(spec, self.config.status_decoder)
         ):
             check_business_status(
                 model,
@@ -443,7 +445,9 @@ def parse_response(spec: EndpointSpec[ResponseT], resp: httpx.Response) -> Respo
         ResponseParseError: If the body is not valid JSON (``phase="decode"``) or does not
             satisfy the response model (``phase="validate"``).
     """
-    raw_body = resp.content or b"{}"
+    model_type = spec.response_model
+    is_list = isinstance(model_type, type) and issubclass(model_type, RootModel)
+    raw_body = resp.content or (b"[]" if is_list else b"{}")
     try:
         payload = codec.loads(raw_body)
     except ValueError as exc:
@@ -455,7 +459,6 @@ def parse_response(spec: EndpointSpec[ResponseT], resp: httpx.Response) -> Respo
             raw_body=raw_body,
             message=str(exc),
         ) from exc
-    model_type = spec.response_model
     try:
         return model_type.model_validate(payload)
     except PydanticValidationError as exc:

{stonepy-0.2.2 → stonepy-0.2.4}/src/stonepy/_endpoints/order.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 from stonepy._core.endpoint import AuthPolicy, EndpointSpec, Param
+from stonepy._core.models import ListResponse
 from stonepy._core.pipeline import CallContext
 from stonepy.models import (
     ApiSimulateTradeOrderResponseDTO,
@@ -333,14 +334,14 @@ async def aget_orders_by_reference(
     )
 
 
-GET_ORDERS_SPEC: EndpointSpec[EnrichedOrderDTO] = EndpointSpec(
+GET_ORDERS_SPEC: EndpointSpec[ListResponse[EnrichedOrderDTO]] = EndpointSpec(
     name="GetOrders v2",
     method="GET",
     path="/v2/orders?clientAccountId={clientAccountId}",
     idempotent=True,
     auth_policy=AuthPolicy.SESSION,
     rate_limit_bucket="order",
-    response_model=EnrichedOrderDTO,
+    response_model=ListResponse[EnrichedOrderDTO],
     params=(
         Param(name="Limit", location="query", python_name="limit"),
         Param(name="clientAccountId", location="query", python_name="client_account_id"),
@@ -350,28 +351,32 @@ GET_ORDERS_SPEC: EndpointSpec[EnrichedOrderDTO] = EndpointSpec(
 
 def get_orders(
     ctx: CallContext, client_account_id: str, *, limit: int | None = None
-) -> EnrichedOrderDTO:
+) -> list[EnrichedOrderDTO]:
     """Query for orders by a specific client account id."""
-    return ctx.invoke(GET_ORDERS_SPEC, query={"Limit": limit, "clientAccountId": client_account_id})
+    return (
+        ctx.invoke(GET_ORDERS_SPEC, query={"Limit": limit, "clientAccountId": client_account_id})
+    ).root
 
 
 async def aget_orders(
     ctx: CallContext, client_account_id: str, *, limit: int | None = None
-) -> EnrichedOrderDTO:
+) -> list[EnrichedOrderDTO]:
     """Query for orders by a specific client account id."""
-    return await ctx.ainvoke(
-        GET_ORDERS_SPEC, query={"Limit": limit, "clientAccountId": client_account_id}
-    )
+    return (
+        await ctx.ainvoke(
+            GET_ORDERS_SPEC, query={"Limit": limit, "clientAccountId": client_account_id}
+        )
+    ).root
 
 
-GET_ORDER_HISTORY_SPEC: EndpointSpec[OrderHistoryDTO] = EndpointSpec(
+GET_ORDER_HISTORY_SPEC: EndpointSpec[ListResponse[OrderHistoryDTO]] = EndpointSpec(
     name="GetOrderHistory v2",
     method="GET",
     path="/v2/orderhistory?clientAccountId={clientAccountId}",
     idempotent=True,
     auth_policy=AuthPolicy.SESSION,
     rate_limit_bucket="order",
-    response_model=OrderHistoryDTO,
+    response_model=ListResponse[OrderHistoryDTO],
     params=(
         Param(name="ClientAccountId", location="query", python_name="client_account_id"),
         Param(name="StartDateTime", location="query", python_name="start_date_time"),
@@ -390,18 +395,20 @@ def get_order_history(
     end_date_time: int | None = None,
     page_size: int | None = None,
     page: int | None = None,
-) -> OrderHistoryDTO:
+) -> list[OrderHistoryDTO]:
     """Queries for an order history."""
-    return ctx.invoke(
-        GET_ORDER_HISTORY_SPEC,
-        query={
-            "ClientAccountId": client_account_id,
-            "StartDateTime": start_date_time,
-            "EndDateTime": end_date_time,
-            "PageSize": page_size,
-            "Page": page,
-        },
-    )
+    return (
+        ctx.invoke(
+            GET_ORDER_HISTORY_SPEC,
+            query={
+                "ClientAccountId": client_account_id,
+                "StartDateTime": start_date_time,
+                "EndDateTime": end_date_time,
+                "PageSize": page_size,
+                "Page": page,
+            },
+        )
+    ).root
 
 
 async def aget_order_history(
@@ -412,18 +419,20 @@ async def aget_order_history(
     end_date_time: int | None = None,
     page_size: int | None = None,
     page: int | None = None,
-) -> OrderHistoryDTO:
+) -> list[OrderHistoryDTO]:
     """Queries for an order history."""
-    return await ctx.ainvoke(
-        GET_ORDER_HISTORY_SPEC,
-        query={
-            "ClientAccountId": client_account_id,
-            "StartDateTime": start_date_time,
-            "EndDateTime": end_date_time,
-            "PageSize": page_size,
-            "Page": page,
-        },
-    )
+    return (
+        await ctx.ainvoke(
+            GET_ORDER_HISTORY_SPEC,
+            query={
+                "ClientAccountId": client_account_id,
+                "StartDateTime": start_date_time,
+                "EndDateTime": end_date_time,
+                "PageSize": page_size,
+                "Page": page,
+            },
+        )
+    ).root
 
 
 GET_ORDER_SPEC: EndpointSpec[GetOrderResponseDTOv2] = EndpointSpec(

{stonepy-0.2.2 → stonepy-0.2.4}/src/stonepy/_endpoints/user_account.py

@@ -7,7 +7,7 @@ from stonepy._core.endpoint import AuthPolicy, EndpointSpec, Param
 from stonepy._core.models import ResponseModel
 from stonepy._core.pipeline import CallContext
 from stonepy.models import (
-    AccountInformationResponseDTOv2,
+    AccountResult,
     ApiAccountInformationSaveRequestDTO,
     ApiAccountInformationSaveResponseDTO,
     ApiGetCommunityActionsResponseDTO,
@@ -43,7 +43,7 @@ async def aget_charting_enabled(ctx: CallContext, id: str) -> ResponseModel:
     return await ctx.ainvoke(GET_CHARTING_ENABLED_SPEC, path_params={"id": id})
 
 
-GET_CLIENT_AND_TRADING_ACCOUNT_SPEC: EndpointSpec[AccountInformationResponseDTOv2] = EndpointSpec(
+GET_CLIENT_AND_TRADING_ACCOUNT_SPEC: EndpointSpec[AccountResult] = EndpointSpec(
     name="GetClientAndTradingAccount v2",
     method="GET",
     path="/v2/UserAccount/ClientAndTradingAccount",
@@ -51,11 +51,11 @@ GET_CLIENT_AND_TRADING_ACCOUNT_SPEC: EndpointSpec[AccountInformationResponseDTOv
     idempotent=True,
     auth_policy=AuthPolicy.SESSION,
     rate_limit_bucket="user_account",
-    response_model=AccountInformationResponseDTOv2,
+    response_model=AccountResult,
 )
 
 
-def get_client_and_trading_account(ctx: CallContext) -> AccountInformationResponseDTOv2:
+def get_client_and_trading_account(ctx: CallContext) -> AccountResult:
     """
     Returns the User's ClientAccountId and a list of their TradingAccounts. There are no
     parameters for this call.
@@ -63,7 +63,7 @@ def get_client_and_trading_account(ctx: CallContext) -> AccountInformationRespon
     return ctx.invoke(GET_CLIENT_AND_TRADING_ACCOUNT_SPEC)
 
 
-async def aget_client_and_trading_account(ctx: CallContext) -> AccountInformationResponseDTOv2:
+async def aget_client_and_trading_account(ctx: CallContext) -> AccountResult:
     """
     Returns the User's ClientAccountId and a list of their TradingAccounts. There are no
     parameters for this call.

{stonepy-0.2.2 → stonepy-0.2.4}/src/stonepy/_endpoints/watchlist.py

@@ -21,8 +21,8 @@ DELETE_WATCHLIST_SPEC: EndpointSpec[DeleteWatchlistResponseDTO] = EndpointSpec(
     rate_limit_bucket="watchlist",
     response_model=DeleteWatchlistResponseDTO,
     params=(
-        Param(name="ClientAccountId", location="body", python_name="client_account_id"),
-        Param(name="WatchlistId", location="body", python_name="watchlist_id"),
+        Param(name="ClientAccountId", location="query", python_name="client_account_id"),
+        Param(name="WatchlistId", location="query", python_name="watchlist_id"),
     ),
 )
 
@@ -33,7 +33,7 @@ def delete_watchlist(
     """Delete watchlist v2."""
     return ctx.invoke(
         DELETE_WATCHLIST_SPEC,
-        body={"ClientAccountId": client_account_id, "WatchlistId": watchlist_id},
+        query={"ClientAccountId": client_account_id, "WatchlistId": watchlist_id},
     )
 
 
@@ -43,7 +43,7 @@ async def adelete_watchlist(
     """Delete watchlist v2."""
     return await ctx.ainvoke(
         DELETE_WATCHLIST_SPEC,
-        body={"ClientAccountId": client_account_id, "WatchlistId": watchlist_id},
+        query={"ClientAccountId": client_account_id, "WatchlistId": watchlist_id},
     )
 
 

{stonepy-0.2.2 → stonepy-0.2.4}/src/stonepy/_generator/emit_contract.py

@@ -15,13 +15,17 @@ from stonepy._generator.catalog import (
     TypeRecord,
     is_enum_record,
     python_name,
-    python_type,
+)
+from stonepy._generator.emit_endpoints import (
+    _PARAM_LOCATION_OVERRIDES,
+    endpoint_spec_name,
+    resolved_path,
+    target_module,
 )
 from stonepy._generator.emit_endpoints import _is_idempotent as _endpoint_is_idempotent
 from stonepy._generator.emit_endpoints import _params as _endpoint_params
-from stonepy._generator.emit_endpoints import endpoint_spec_name, resolved_path, target_module
 from stonepy._generator.emit_models import _cyclic_ref_fields, _lookup_enum_records
-from stonepy._generator.render import BANNER, field_name, format_python
+from stonepy._generator.render import BANNER, field_name, format_python, resolved_field_annotation
 
 __all__ = ["emit_contract_tests"]
 
@@ -418,7 +422,7 @@ def _model_payload(
         if _is_optional_property(prop) or raw_name in optional_here:
             continue
 
-        annotation = python_type(prop, known_names)
+        annotation = resolved_field_annotation(rec.name, prop, known_names)
         sample = _sample_value(
             annotation,
             enum_samples=enum_samples,
@@ -450,7 +454,7 @@ def _construct_payload(
         if name is None or _is_optional_property(prop) or raw_name in optional_here:
             continue
 
-        annotation = python_type(prop, known_names)
+        annotation = resolved_field_annotation(rec.name, prop, known_names)
         payload[name] = _construct_sample_value(
             annotation,
             enum_samples=enum_samples,
@@ -652,8 +656,11 @@ def _request_model_name(rec: EndpointRecord, catalog: Catalog) -> str | None:
 
 
 def _param_fields(rec: EndpointRecord) -> tuple[tuple[str, str, str], ...]:
-    # Reuse the endpoint generator's parameter resolution so the contract expectation always
-    # matches the emitted ``EndpointSpec.params`` (including params synthesized from URI
-    # templates the catalog's parameter list omits).
-    params = _endpoint_params(rec.parameters, None, path=resolved_path(rec))
+    # Reuse the endpoint generator's parameter resolution (including its location overrides) so the
+    # contract expectation always matches the emitted ``EndpointSpec.params`` (including params
+    # synthesized from URI templates the catalog's parameter list omits).
+    location_overrides = _PARAM_LOCATION_OVERRIDES.get((target_module(rec.target), rec.name), {})
+    params = _endpoint_params(
+        rec.parameters, None, path=resolved_path(rec), location_overrides=location_overrides
+    )
     return tuple((param.name, param.location, param.python_name) for param in params)