cryptocom-exchange 2.2.0__tar.gz → 2.3.0__tar.gz

{cryptocom_exchange-2.2.0 → cryptocom_exchange-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cryptocom-exchange
-Version: 2.2.0
+Version: 2.3.0
 Summary: Python 3.11+ async library for crypto.com/exchange API using httpx and websockets
 License: MIT
 License-File: LICENSE
@@ -131,7 +131,11 @@ response.
 ### Orders
 
 `Account` caches orders by `client_oid` in `Account.order_cache` (the snippets
-here use `from cryptocom.exchange import exceptions`). Terminal
+here use `from cryptocom.exchange import exceptions`). `get_order` returns
+`None` when the exchange CONFIRMS absence (empty result or code 40401) — a
+ definite answer; unknown outcomes raise `ApiError`. (`OrderNotFoundError`
+lives on for endpoints where absence IS the error reply: cancel, amend.)
+Terminal
 entries (`Order.is_terminal`, `TERMINAL_ORDER_STATUSES`) are final and live
 forever; live entries expire after `orders_ttl` seconds (default 5, `0`
 disables live caching). The cache is only written from observed answers: cancel
@@ -150,14 +154,12 @@ order = await account.wait_for_order(
     timeout=5.0,
 )
 
-# Cancel, then poll to a terminal status. Returns the terminal order, or None
-# when the exchange confirms the order is gone.
-try:
-    order = await account.cancel_order_and_wait(pair, client_id, timeout=5.0)
-except exceptions.CancelNotConfirmedError:
-    await reconcile_later(client_id)  # cancel may still land: reconcile
-else:
-    print("terminal:", order.status if order else "absent")
+# Cancel, then poll to terminal. True = CONFIRMED not live (terminal or
+# absent); False = not confirmed (timed out or still live) - never treat
+# False as cancelled. Indeterminate cancel/lookup failures raise ApiError.
+cancelled = await account.cancel_order_and_wait(pair, client_id, timeout=5.0)
+if not cancelled:
+    await reconcile_later(client_id)  # may still land after the last poll
 ```
 
 A websocket feed can answer lookups directly: `updates` wins over cache and
@@ -171,7 +173,7 @@ order = await account.get_order(client_order_id=client_id, updates={client_id: s
 Two guards worth knowing:
 
 - A `client_oid` created moments ago that reads back empty raises an
-  indeterminate `ApiError`, not `OrderNotFoundError`, for `create_race_guard`
+  indeterminate `ApiError` instead of returning `None`, for `create_race_guard`
   seconds (default 2). Absence right after create is not proof of absence.
 - `wait_for_order` raises `exceptions.WaitNotConfirmedError` (indeterminate) on
   timeout instead of returning `None`. `wait_for_status` is deprecated in its

{cryptocom_exchange-2.2.0 → cryptocom_exchange-2.3.0}/README.md

@@ -105,7 +105,11 @@ response.
 ### Orders
 
 `Account` caches orders by `client_oid` in `Account.order_cache` (the snippets
-here use `from cryptocom.exchange import exceptions`). Terminal
+here use `from cryptocom.exchange import exceptions`). `get_order` returns
+`None` when the exchange CONFIRMS absence (empty result or code 40401) — a
+ definite answer; unknown outcomes raise `ApiError`. (`OrderNotFoundError`
+lives on for endpoints where absence IS the error reply: cancel, amend.)
+Terminal
 entries (`Order.is_terminal`, `TERMINAL_ORDER_STATUSES`) are final and live
 forever; live entries expire after `orders_ttl` seconds (default 5, `0`
 disables live caching). The cache is only written from observed answers: cancel
@@ -124,14 +128,12 @@ order = await account.wait_for_order(
     timeout=5.0,
 )
 
-# Cancel, then poll to a terminal status. Returns the terminal order, or None
-# when the exchange confirms the order is gone.
-try:
-    order = await account.cancel_order_and_wait(pair, client_id, timeout=5.0)
-except exceptions.CancelNotConfirmedError:
-    await reconcile_later(client_id)  # cancel may still land: reconcile
-else:
-    print("terminal:", order.status if order else "absent")
+# Cancel, then poll to terminal. True = CONFIRMED not live (terminal or
+# absent); False = not confirmed (timed out or still live) - never treat
+# False as cancelled. Indeterminate cancel/lookup failures raise ApiError.
+cancelled = await account.cancel_order_and_wait(pair, client_id, timeout=5.0)
+if not cancelled:
+    await reconcile_later(client_id)  # may still land after the last poll
 ```
 
 A websocket feed can answer lookups directly: `updates` wins over cache and
@@ -145,7 +147,7 @@ order = await account.get_order(client_order_id=client_id, updates={client_id: s
 Two guards worth knowing:
 
 - A `client_oid` created moments ago that reads back empty raises an
-  indeterminate `ApiError`, not `OrderNotFoundError`, for `create_race_guard`
+  indeterminate `ApiError` instead of returning `None`, for `create_race_guard`
   seconds (default 2). Absence right after create is not proof of absence.
 - `wait_for_order` raises `exceptions.WaitNotConfirmedError` (indeterminate) on
   timeout instead of returning `None`. `wait_for_status` is deprecated in its

{cryptocom_exchange-2.2.0 → cryptocom_exchange-2.3.0}/pyproject.toml

@@ -7,7 +7,7 @@ packages = [
   {include = "cryptocom", from = "src"},
 ]
 exclude = ["openapi_docs/"]
-version = "2.2.0"
+version = "2.3.0"
 readme = "README.md"
 classifiers = [
   "Operating System :: OS Independent",

{cryptocom_exchange-2.2.0 → cryptocom_exchange-2.3.0}/src/cryptocom/exchange/__init__.py

@@ -1,13 +1,13 @@
 from . import exceptions, instruments, pairs
-from .api import ApiError, ApiProvider, RecordApiProvider
-from .market import Market
 from .account import (
-    Account,
-    OrderKeys,
     MAX_OPEN_ORDERS_PER_ACCOUNT,
     MAX_OPEN_ORDERS_PER_PAIR,
+    Account,
+    OrderKeys,
 )
+from .api import ApiError, ApiProvider, RecordApiProvider
 from .exceptions import ApiAuthError, ApiErrorCode, ExchangeError
+from .market import Market
 from .structs import (
     Candle,
     Deposit,
@@ -29,38 +29,37 @@ from .structs import (
     WithdrawalStatus,
 )
 
-
 __all__ = [
+    "MAX_OPEN_ORDERS_PER_ACCOUNT",
+    "MAX_OPEN_ORDERS_PER_PAIR",
+    "Account",
+    "ApiAuthError",
+    "ApiError",
+    "ApiErrorCode",
+    "ApiProvider",
+    "Candle",
+    "Deposit",
+    "DepositStatus",
+    "ExchangeError",
+    "Instrument",
+    "InstrumentType",
+    "Market",
+    "MarketTrade",
     "Order",
+    "OrderExecFlag",
+    "OrderForceType",
+    "OrderKeys",
     "OrderSide",
     "OrderStatus",
     "OrderType",
-    "OrderForceType",
-    "OrderExecFlag",
-    "OrderKeys",
-    "exceptions",
-    "pairs",
     "Pair",
-    "instruments",
-    "Instrument",
-    "InstrumentType",
-    "Timeframe",
-    "Candle",
-    "MarketTrade",
     "PrivateTrade",
+    "RecordApiProvider",
     "TimeDelta",
-    "Deposit",
+    "Timeframe",
     "Withdrawal",
-    "DepositStatus",
     "WithdrawalStatus",
-    "Market",
-    "Account",
-    "ApiError",
-    "ApiProvider",
-    "RecordApiProvider",
-    "ApiAuthError",
-    "ApiErrorCode",
-    "ExchangeError",
-    "MAX_OPEN_ORDERS_PER_PAIR",
-    "MAX_OPEN_ORDERS_PER_ACCOUNT",
+    "exceptions",
+    "instruments",
+    "pairs",
 ]

{cryptocom_exchange-2.2.0 → cryptocom_exchange-2.3.0}/src/cryptocom/exchange/account.py

@@ -3,12 +3,11 @@ import logging
 import time
 import warnings
 from dataclasses import dataclass
-from uuid import uuid4
 from typing import Any
+from uuid import uuid4
 
 from .api import ApiError, ApiProvider
 from .exceptions import (
-    CancelNotConfirmedError,
     OrderNotActiveError,
     OrderNotFoundError,
     WaitNotConfirmedError,
@@ -459,16 +458,14 @@ class Account:
         deadline = loop.time() + timeout
         last = "unknown"
         while True:
-            try:
-                order = await self.get_order(
-                    order_id=order_id,
-                    client_order_id=client_order_id,
-                    ignore_cache=True,
-                )
-            except OrderNotFoundError:
-                order = None
+            order = await self.get_order(
+                order_id=order_id,
+                client_order_id=client_order_id,
+                ignore_cache=True,
+            )
+            if order is None:
                 last = "absent"
-            if order is not None:
+            else:
                 last = str(order.status)
                 if order.status in statuses:
                     return order
@@ -593,7 +590,7 @@ class Account:
         client_order_id: str | None = None,
         updates: dict[str, Order] | None = None,
         ignore_cache: bool = False,
-    ) -> Order:
+    ) -> Order | None:
         """Get order info by order_id or client_order_id.
 
         Cache-backed for client_order_id lookups. Resolution priority:
@@ -601,16 +598,14 @@ class Account:
         cache > API. Terminal orders are cached forever; live orders for
         ``orders_ttl`` seconds (0 disables caching).
 
-        Args:
-            order_id: Exchange order ID
-            client_order_id: Client order ID (client_oid)
-            updates: Live order snapshot keyed by client_oid (highest priority,
-                populates the cache)
-            ignore_cache: If True, query the exchange directly
+        Returns:
+            The Order, or None if the exchange CONFIRMS the order is absent
+            (empty result / code 40401). None is a definite answer; unknown
+            outcomes raise. Endpoints where "not found" is an error reply
+            (cancel, amend) still raise OrderNotFoundError.
 
         Raises:
             ValueError: If neither order_id nor client_order_id is provided
-            OrderNotFoundError: The order is confirmed absent (deterministic)
             ApiError: Just-created order unreadable, or lookup failed -
                 outcome UNKNOWN, must be reconciled later (indeterminate)
         """
@@ -633,10 +628,15 @@ class Account:
         if client_order_id:
             params["client_oid"] = client_order_id
 
-        data = await self.api.post(
-            "private/get-order-detail",
-            {"params": params},
-        )
+        try:
+            data = await self.api.post(
+                "private/get-order-detail",
+                {"params": params},
+            )
+        except OrderNotFoundError:
+            # Coded 40401 is the same confirmed-absent answer as an empty
+            # result; get_order reports absence as None.
+            data = None
         if not data:
             # Structured success with empty result - normally "not there".
             # Exception: an order created moments ago may not be readable
@@ -654,9 +654,7 @@ class Account:
                         "creation - state unknown, reconcile later",
                         method="private/get-order-detail",
                     )
-            raise OrderNotFoundError(
-                "No order data", code=40401, method="private/get-order-detail"
-            )
+            return None
 
         order = Order.create_from_api(
             self.pairs[data["instrument_name"]],
@@ -729,70 +727,82 @@ class Account:
         client_order_id: str,
         timeout: float = 30.0,
         poll_interval: float = 0.5,
-    ) -> Order | None:
-        """Cancel an order and poll until it reaches a terminal status.
+    ) -> bool:
+        """Cancel an order and confirm it is no longer live.
 
-        Absent and already-terminal orders are treated as confirmed success
-        (nothing to cancel). A cancel rejected as not-active re-queries once:
-        a race with FILLED/CANCELED is a valid terminal outcome, not an error.
-
-        Args:
-            pair: Trading pair
-            client_order_id: Client order ID (client_oid) of the order
-            timeout: Max seconds to wait for a terminal status
-            poll_interval: Seconds between status polls
+        All exchange-side races are resolved here: an already-terminal or
+        confirmed-absent order needs no cancel; a cancel rejected as
+        not-active (316) re-queries once, because racing into
+        FILLED/CANCELED/absent is a confirmed outcome, not an error.
 
         Returns:
-            The order in terminal status, or None if the order is confirmed
-            absent from the exchange.
+            True: CONFIRMED not live - cancel reached terminal status, the
+                order was already terminal, or the exchange confirmed it
+                absent. Safe to treat as cancelled.
+            False: cancellation NOT confirmed - cancel timed out (it may
+                still have landed after the last poll) or the order is
+                confirmed still live. Never read False as "cancelled".
 
         Raises:
-            CancelNotConfirmedError: Terminal status not confirmed in time -
-                the cancel may have landed after the last poll.
-            ApiError: Cancel or lookup failed with an indeterminate error -
-                outcome unknown, the caller must reconcile later.
+            ApiError: Cancel or lookup failed indeterminately - outcome
+                unknown, reconcile later.
         """
-        try:
-            order = await self.get_order(
-                client_order_id=client_order_id, ignore_cache=True
-            )
-        except OrderNotFoundError:
-            return None
-        if order.is_terminal:
-            return order
+        order = await self.get_order(client_order_id=client_order_id, ignore_cache=True)
+        if order is None or order.is_terminal:
+            return True
 
         try:
             await self.cancel_order(pair, client_order_id=client_order_id)
         except OrderNotActiveError:
             # Cancel raced a status change - re-query to learn the outcome.
-            try:
-                order = await self.get_order(
-                    client_order_id=client_order_id, ignore_cache=True
-                )
-            except OrderNotFoundError:
-                return None
-            if order.is_terminal:
-                return order
-            raise
+            order = await self.get_order(
+                client_order_id=client_order_id, ignore_cache=True
+            )
+            return order is None or order.is_terminal
         except OrderNotFoundError:
-            return None
+            return True
 
         loop = asyncio.get_running_loop()
         deadline = loop.time() + timeout
         while loop.time() < deadline:
-            try:
-                order = await self.get_order(
-                    client_order_id=client_order_id, ignore_cache=True
-                )
-            except OrderNotFoundError:
-                return None
-            if order.is_terminal:
-                return order
+            order = await self.get_order(
+                client_order_id=client_order_id, ignore_cache=True
+            )
+            if order is None or order.is_terminal:
+                return True
             await asyncio.sleep(poll_interval)
+        return False
+
+    async def resolve_stuck_order(
+        self,
+        pair: Pair,
+        order: Order,
+        stuck_after: float = 300.0,
+        timeout: float = 30.0,
+        poll_interval: float = 0.5,
+    ) -> bool:
+        """Resolve a possibly-stuck resting order (shadow-order mechanic).
+
+        An order is stuck when it sits in NEW (never activated) for longer
+        than ``stuck_after`` seconds AND cancel-and-wait cannot confirm its
+        removal. Anything else (healthy, terminal, NEW but still fresh, or
+        successfully cancelled) is clear to proceed.
+
+        Returns:
+            True: the order is STUCK (cancel attempted, not confirmed).
+            False: clear to proceed - no cancellation was needed or the
+                stuck order was successfully removed.
 
-        raise CancelNotConfirmedError(
-            f"Order {client_order_id!r} not terminal within {timeout}s "
-            f"(last status: {order.status})"
+        Raises:
+            ApiError: cancel or lookup failed indeterminately - unknown is
+                never reported as stuck or clear; reconcile later.
+        """
+        if order.status != OrderStatus.NEW:
+            return False
+        if time.time() - order.created_at <= stuck_after:
+            return False
+        return not await self.cancel_order_and_wait(
+            pair, order.client_id, timeout, poll_interval
         )
 
     async def update_order(

{cryptocom_exchange-2.2.0 → cryptocom_exchange-2.3.0}/src/cryptocom/exchange/api.py

@@ -193,9 +193,9 @@ class ApiProvider:
 
         self.rate_limiters = {}
 
-        for urls in RATE_LIMITS:
+        for urls, limit in RATE_LIMITS.items():
             for url in urls:
-                self.rate_limiters[url] = aiolimiter.AsyncLimiter(*RATE_LIMITS[urls])
+                self.rate_limiters[url] = aiolimiter.AsyncLimiter(*limit)
 
         # limits for not matched methods
         # Private APIs: 3 requests per 100ms (REST API - authenticated)

{cryptocom_exchange-2.2.0 → cryptocom_exchange-2.3.0}/src/cryptocom/exchange/exceptions.py

@@ -326,14 +326,6 @@ class MaintenanceError(ExchangeError):
     """Exchange under maintenance (code 9010001). Transient."""
 
 
-class CancelNotConfirmedError(ApiError):
-    """Cancel was not confirmed terminal before the timeout.
-
-    Indeterminate (code is None): the cancel may still have landed after
-    the last poll - the caller must reconcile the order later.
-    """
-
-
 class WaitNotConfirmedError(ApiError):
     """An order did not reach a required status before the timeout.
 

{cryptocom_exchange-2.2.0 → cryptocom_exchange-2.3.0}/src/cryptocom/exchange/structs.py

@@ -921,15 +921,15 @@ class Transaction:
 
     @staticmethod
     def _prepare(data):
-        return dict(
-            id=data["id"],
-            instrument=Instrument(data["currency"]),
-            fee=float(data["fee"]),
-            create_time=datetime.fromtimestamp(int(data["create_time"]) / 1000),
-            update_time=datetime.fromtimestamp(int(data["update_time"]) / 1000),
-            amount=float(data["amount"]),
-            address=data["address"],
-        )
+        return {
+            "id": data["id"],
+            "instrument": Instrument(data["currency"]),
+            "fee": float(data["fee"]),
+            "create_time": datetime.fromtimestamp(int(data["create_time"]) / 1000),
+            "update_time": datetime.fromtimestamp(int(data["update_time"]) / 1000),
+            "amount": float(data["amount"]),
+            "address": data["address"],
+        }
 
 
 @dataclass