fxsocket 0.1__tar.gz → 0.2__tar.gz

{fxsocket-0.1 → fxsocket-0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fxsocket
-Version: 0.1
+Version: 0.2
 Summary: Python SDK for the FxSocket API — MT4/MT5 account management, trading, and real-time streaming.
 Project-URL: Homepage, https://fxsocket.com
 Project-URL: Documentation, https://api.fxsocket.com/v1/docs
@@ -138,6 +138,23 @@ with Client(api_key="fxs_live_…") as fx:
         term.order_close(result.order)
 ```
 
+Every order call returns an `OrderResult`. A `200` only means the terminal
+answered — check the body: `success` is true for `retcode` `10009` (done) or
+`10008` (placed), and `outcome` classifies the result as `applied` /
+`no_change` / `partial` / `rejected` (compare against `OrderOutcome`).
+
+`no_change` (retcode `10025`) is a benign, idempotent no-op — the requested
+SL/TP/price already match — so it's safe to treat as applied even though
+`success` is `False`. For idempotent SL/TP management (e.g. re-sending after a
+lost confirmation), send absolute values and gate on `result.is_effective`
+(true for both `applied` and `no_change`):
+
+```python
+res = term.order_modify(ticket, stop_loss=1.0850)
+if res.is_effective:        # applied now, or already in effect
+    ...
+```
+
 Inputs are validated client-side before they're sent. One guard worth knowing:
 in `order_modify`, a literal `stop_loss=0.0` would *remove* your stop-loss, so
 it's rejected — pass `clear_stop_loss=True` to remove one deliberately, while

{fxsocket-0.1 → fxsocket-0.2}/README.md

@@ -111,6 +111,23 @@ with Client(api_key="fxs_live_…") as fx:
         term.order_close(result.order)
 ```
 
+Every order call returns an `OrderResult`. A `200` only means the terminal
+answered — check the body: `success` is true for `retcode` `10009` (done) or
+`10008` (placed), and `outcome` classifies the result as `applied` /
+`no_change` / `partial` / `rejected` (compare against `OrderOutcome`).
+
+`no_change` (retcode `10025`) is a benign, idempotent no-op — the requested
+SL/TP/price already match — so it's safe to treat as applied even though
+`success` is `False`. For idempotent SL/TP management (e.g. re-sending after a
+lost confirmation), send absolute values and gate on `result.is_effective`
+(true for both `applied` and `no_change`):
+
+```python
+res = term.order_modify(ticket, stop_loss=1.0850)
+if res.is_effective:        # applied now, or already in effect
+    ...
+```
+
 Inputs are validated client-side before they're sent. One guard worth knowing:
 in `order_modify`, a literal `stop_loss=0.0` would *remove* your stop-loss, so
 it's rejected — pass `clear_stop_loss=True` to remove one deliberately, while

{fxsocket-0.1 → fxsocket-0.2}/src/fxsocket/__init__.py

@@ -14,6 +14,7 @@ from .enums import (
     HealthStatus,
     OrderKind,
     OrderOperation,
+    OrderOutcome,
     Platform,
     Timeframe,
     TradingStatus,
@@ -113,6 +114,7 @@ __all__ = [
     "Platform",
     "TradingStatus",
     "OrderOperation",
+    "OrderOutcome",
     "OrderKind",
     "DealEntry",
     "HealthStatus",

fxsocket-0.2/src/fxsocket/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2"

{fxsocket-0.1 → fxsocket-0.2}/src/fxsocket/enums.py

@@ -61,6 +61,21 @@ PENDING_OPERATIONS = frozenset(
 )
 
 
+class OrderOutcome(str, Enum):
+    """Semantic classification of a trade result (``OrderResult.outcome``).
+
+    ``success`` only tells you applied-or-not; ``outcome`` additionally
+    separates a benign no-op and a partial fill from a genuine rejection, so
+    clients don't have to hardcode retcode tables. Empty on bridges older than
+    MT5 0.6.1 / MT4 0.5.1.
+    """
+
+    APPLIED = "applied"       #: retcode 10009 (done) / 10008 (placed)
+    NO_CHANGE = "no_change"   #: retcode 10025 — requested state already in effect
+    PARTIAL = "partial"       #: retcode 10010 (done partially)
+    REJECTED = "rejected"     #: anything else — inspect ``retcode`` / ``comment``
+
+
 class OrderKind(str, Enum):
     """Whether an opened row is a live position or a resting pending order."""
 

{fxsocket-0.1 → fxsocket-0.2}/src/fxsocket/models.py

@@ -24,7 +24,7 @@ from datetime import datetime
 from pydantic import BaseModel, ConfigDict
 from pydantic.alias_generators import to_camel
 
-from .enums import Platform, TradingStatus
+from .enums import OrderOutcome, Platform, TradingStatus
 
 
 class _Camel(BaseModel):
@@ -257,12 +257,23 @@ class Candle(_Camel):
 class OrderResult(_Camel):
     """Result of an order send / modify / close.
 
-    ``success`` is true when ``retcode`` is DONE (10009) or PLACED (10010).
+    ``success`` is true when ``retcode`` is DONE (10009) or PLACED (10008).
+
+    ``outcome`` classifies the result further — ``"applied"`` /
+    ``"no_change"`` / ``"partial"`` / ``"rejected"`` (compare against
+    :class:`fxsocket.OrderOutcome`). ``"no_change"`` (retcode 10025) is a
+    benign idempotent no-op — the requested SL/TP/price already match the
+    current values — so it is safe to treat as applied even though ``success``
+    is ``False``. Use :attr:`is_effective` when you only care that the
+    requested state is in effect (the idempotent-retry case). ``outcome`` is
+    empty on bridges older than MT5 0.6.1 / MT4 0.5.1.
+
     ``deal`` is the executed deal ticket (0 for pending placement, and always
     0 on MT4); ``order`` is the resulting position / pending-order ticket.
     """
 
     success: bool
+    outcome: str = ""
     retcode: int
     retcode_description: str
     deal: int
@@ -273,6 +284,20 @@ class OrderResult(_Camel):
     ask: float
     comment: str
 
+    @property
+    def is_no_change(self) -> bool:
+        """True for a benign no-op (retcode 10025 / ``outcome == "no_change"``):
+        the requested SL/TP/price already match the current values."""
+        return self.retcode == 10025 or self.outcome == OrderOutcome.NO_CHANGE
+
+    @property
+    def is_effective(self) -> bool:
+        """True when the requested state is in effect — either ``success``
+        (applied) or a no-op (:attr:`is_no_change`). Use this for idempotent
+        SL/TP management, where re-sending an identical modify returns 10025
+        with ``success=False``."""
+        return self.success or self.is_no_change
+
 
 class MarginCalc(_Camel):
     """Required margin for a hypothetical order (``GET /OrderCalcMargin``)."""

{fxsocket-0.1 → fxsocket-0.2}/tests/test_terminal.py

@@ -299,6 +299,48 @@ def test_order_send_allows_stop_limit_on_mt4() -> None:
     assert sent["stopLimitPrice"] == 1.09
 
 
+@respx.mock
+def test_order_modify_no_change_is_effective() -> None:
+    # An idempotent re-send (SL/TP already match) returns retcode 10025 with
+    # success=False; outcome distinguishes the benign no-op from a rejection,
+    # and is_effective treats it as "requested state is in effect".
+    respx.post(f"{TERM}/OrderModify").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "success": False,
+                "outcome": "no_change",
+                "retcode": 10025,
+                "retcodeDescription": "No changes",
+                "deal": 0,
+                "order": 100,
+                "volume": 0.1,
+                "price": 0.0,
+                "bid": 1.0849,
+                "ask": 1.0851,
+                "comment": "No changes",
+            },
+        ),
+    )
+    with _term() as t:
+        res = t.order_modify(100, stop_loss=1.07)
+    assert res.success is False
+    assert res.outcome == "no_change"
+    assert res.is_no_change is True
+    assert res.is_effective is True
+
+
+def test_order_result_outcome_absent_defaults_empty() -> None:
+    # Bridges older than MT5 0.6.1 / MT4 0.5.1 omit `outcome` — it must default
+    # to "" (backward-compatible), not fail validation.
+    from fxsocket import OrderResult
+
+    res = OrderResult.model_validate(_ORDER_OK)
+    assert res.outcome == ""
+    assert res.success is True
+    assert res.is_effective is True
+
+
 def test_order_send_rejects_nonpositive_volume() -> None:
     from fxsocket import ValidationError
 

fxsocket-0.1/src/fxsocket/_version.py

@@ -1 +0,0 @@
-__version__ = "0.1"