meshtrade 0.0.4__py3-none-any.whl → 0.0.5__py3-none-any.whl

meshtrade/type/v1/__init__.py

@@ -0,0 +1,7 @@
+from .amount import new_amount
+from .decimal_built_in_conversions import built_in_to_decimal, decimal_to_built_in
+from .decimal_pb2 import Decimal
+from .ledger_pb2 import Ledger
+from .ledger import get_ledger_no_decimal_places
+from .token_pb2 import Token
+from .amount_pb2 import Amount

meshtrade/type/v1/amount.py

@@ -0,0 +1,84 @@
+"""
+This module provides a factory function for creating Amount protobuf messages.
+"""
+
+from decimal import ROUND_DOWN, Decimal
+
+from .amount_pb2 import Amount
+from .decimal_built_in_conversions import built_in_to_decimal, decimal_to_built_in
+from .ledger import get_ledger_no_decimal_places
+from .token_pb2 import Token
+
+
+def new_amount(
+    value: Decimal,
+    token: Token,
+    precision_loss_tolerance: Decimal = Decimal("0.00000001")
+) -> Amount:
+    """Creates a new Amount, ensuring the value conforms to system-wide limits.
+
+    This function is the safe constructor for creating Amount protobuf messages.
+    While the underlying conversion from a Python `Decimal` to the protobuf's
+    `string` field is lossless, this function provides critical validation
+    to ensure the value adheres to constraints imposed by other downstream
+    systems (e.g., databases, other microservices with fixed-precision types).
+
+    Its primary operations are:
+
+    1.  **Validation:** It performs a serialization round-trip
+        (Python Decimal -> Protobuf Decimal -> Python Decimal) to simulate
+        how the value is stored and retrieved across the system. It then asserts
+        the value remains unchanged, guaranteeing it doesn't exceed the
+        precision limits of any consuming service.
+
+    2.  **Truncation:** It truncates the validated value to the exact number of
+        decimal places defined for the token's ledger, always rounding down to
+        prevent any inflation of values.
+
+    3.  **Construction:** It constructs and returns the final `Amount` message.
+
+    Args:
+        value: The numerical value of the amount as a Python `Decimal` object.
+        token: The `Token` protobuf message that defines the asset type
+               and its associated ledger.
+        precision_loss_tolerance: The maximum acceptable difference after the
+            validation round-trip. Since the string-based conversion is
+            lossless, any difference indicates a failure to conform to an
+            external system's parsing rules. Defaults to a small tolerance
+            for robustness.
+
+    Returns:
+        An `Amount` protobuf message containing the ledger-compliant, truncated
+        value and the specified token.
+
+    Raises:
+        AssertionError: If the input `value` changes during the validation
+                        round-trip, indicating it exceeds the system's
+                        representational limits and would be corrupted
+                        downstream.
+    """
+
+    # Perform a serialization round-trip to validate the value against
+    # system-wide architectural constraints. This is a lossless operation
+    # in isolation, so any change reveals an incompatibility.
+    value_after_roundtrip = decimal_to_built_in(built_in_to_decimal(value))
+
+    # Confirm the value is perfectly representable within the system's limits.
+    # If the original value had too much precision for a downstream service to
+    # parse, it would change during the round-trip, and this would fail.
+    assert abs(value_after_roundtrip - value) \
+        <= precision_loss_tolerance, \
+            "value exceeds system's precision limits and would be corrupted"
+
+    # Truncate the validated value to the number of decimal places specified by the
+    # token's ledger. ROUND_DOWN ensures the value is never inflated.
+    truncated_value = value_after_roundtrip.quantize(
+        Decimal(10) ** -get_ledger_no_decimal_places(token.ledger),
+        rounding=ROUND_DOWN,
+    )
+
+    # Construct and return the final Amount protobuf message using the sanitized value.
+    return Amount(
+        token=token,
+        value=built_in_to_decimal(truncated_value),
+    )

meshtrade/type/v1/decimal_built_in_conversions.py

@@ -0,0 +1,29 @@
+import decimal
+
+from .decimal_pb2 import Decimal
+
+
+def built_in_to_decimal(decimal_value: decimal.Decimal) -> Decimal:
+    """
+    Converts an instance of the built-in decimal.Decimal type to an instance of the
+    financial Decimal protobuf type.
+
+    :param decimal_value: The decimal.Decimal object to convert.
+    :return: The converted financial Decimal protobuf object.
+    """
+
+    # Contruct and return resultant decimal object
+    return Decimal(
+        value=str(decimal_value),
+    )
+
+
+def decimal_to_built_in(decimal_value: Decimal) -> decimal.Decimal:
+    """
+    Converts an instance of the financial Decimal protobuf type to an instance of the
+    built-in decimal.Decimal type.
+
+    :param decimal_value: The decimal_pb2.Decimal object to convert.
+    :return: The converted decimal.Decimal object.
+    """
+    return decimal.Decimal( decimal_value.value if decimal_value.value != "" else "0"  )

meshtrade/type/v1/ledger.py

@@ -0,0 +1,26 @@
+from typing import Dict
+
+from .ledger_pb2 import Ledger
+
+_ledger_decimal_places: Dict[Ledger, int] = {
+    Ledger.LEDGER_STELLAR: 7,
+    Ledger.LEDGER_SA_STOCK_BROKERS: 2,
+}
+
+class UnsupportedLedgerError(Exception):
+    """Exception raised for unsupported Ledger values."""
+
+    def __init__(self, ledger: Ledger):
+        self.financial_business_day_convention = ledger
+        message = f"Unsupported Ledger: {ledger}"
+        super().__init__(message)
+
+
+def get_ledger_no_decimal_places(ledger: Ledger) -> int:
+    """
+    Returns the number of decimal places supported by the given Ledger
+    """
+    if ledger in _ledger_decimal_places:
+        return _ledger_decimal_places[ledger]
+    else:
+        raise UnsupportedLedgerError(ledger)

{meshtrade-0.0.4.dist-info → meshtrade-0.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshtrade
-Version: 0.0.4
+Version: 0.0.5
 Summary: Integration SDK for Mesh API Services
 Author-email: Bernard Bussy <bernard@meshtrade.co>
 License-Expression: LicenseRef-My-Custom-License
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.8
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: grpcio<2.0,>=1.73.0

{meshtrade-0.0.4.dist-info → meshtrade-0.0.5.dist-info}/RECORD

@@ -79,15 +79,18 @@ meshtrade/trading/spot/v1/service_pb2.pyi,sha256=f0P_1fXtk9qWMRztTmSyq5t9a2zq44I
 meshtrade/trading/spot/v1/spot_pb2.py,sha256=zXtfxzJdH_mfZpadjaIjLpg3rmBUi7sm_9i5-mvuVRc,1534
 meshtrade/trading/spot/v1/spot_pb2.pyi,sha256=DELXsprA9tDCE2Pn1I7J3qIVgYVEI8oJiT6BPIwrR2I,387
 meshtrade/type/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-meshtrade/type/v1/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meshtrade/type/v1/__init__.py,sha256=mN_HvUFZ1uxR6ETeLcxiGYtPluaUSk3Tx5LJMZJ3hrI,286
 meshtrade/type/v1/address_pb2.py,sha256=dRokCvBkbOIE_AxDfCtQnNUoFSNjZ8f9lFW2ii4yqQk,1795
 meshtrade/type/v1/address_pb2.pyi,sha256=A1PdvzCZpd-JKQhTwwQ3gz2Kw9mOkH3S1imSm78_4Uw,1107
+meshtrade/type/v1/amount.py,sha256=iDaAEB0WpuFwU5qE_gY5XWgqD0x0Z131mrAf-S45x1A,3696
 meshtrade/type/v1/amount_pb2.py,sha256=ympMEAxoG95ElDB_l5fk5y0dTLi5gXgwtD25_8ZNobM,1855
 meshtrade/type/v1/amount_pb2.pyi,sha256=uI8D2Ch66e2hvzQCA5SARE8lrGdU_BYby__P_H-QwvY,749
 meshtrade/type/v1/contact_details_pb2.py,sha256=fKhg7lUMJqa6XyA_cVDCin-hDg1garQ3-xYQlnuxPs0,2007
 meshtrade/type/v1/contact_details_pb2.pyi,sha256=Wk9EFWI_rPuuOvPdKsW9Qo0_c8uNg61U-w__YwPQD9E,1292
+meshtrade/type/v1/decimal_built_in_conversions.py,sha256=Cbxjp8kHJ7E74C4DdXup8uMvZofrwNaXTyIY3xa1iLU,913
 meshtrade/type/v1/decimal_pb2.py,sha256=kzcMQ9eaGUWZlv06K6XftteRwX3vvudwrsKqmA_bkcI,1509
 meshtrade/type/v1/decimal_pb2.pyi,sha256=8qhL7jqAhoYJNzTpEiEPKDSRAYSWgvKd8altyVLISFg,386
+meshtrade/type/v1/ledger.py,sha256=psduzLQCIKvEj3rZBHWcsvq1ZjUh3Hb34ycd48TAcy0,743
 meshtrade/type/v1/ledger_pb2.py,sha256=8xJ_7ClfGDwRGImZerIA6D4Zdvdq6jQL0Ebv5XJUgc0,1747
 meshtrade/type/v1/ledger_pb2.pyi,sha256=r3emyUDafn9p3XTzwpnM0gzLiwrmgXYTp8GwZxw8_FM,801
 meshtrade/type/v1/token_pb2.py,sha256=48dMzVixXluV46B1Pqnfp-yLIeL0NYVg3ZzKQlX-ohc,1741
@@ -98,8 +101,8 @@ meshtrade/wallet/account/v1/account_pb2.py,sha256=Jh8Dnju5zktGXfzWY5HGrvq1iO82SN
 meshtrade/wallet/account/v1/account_pb2.pyi,sha256=GN2bT5Ld2B0KyQUmkDQjHfeXEjLSwfuIE2j70jSMIJE,382
 meshtrade/wallet/account/v1/service_pb2.py,sha256=djmoH_Hlld8RlZhtRxDS6Iw2wLwFoHhunExy9EQmbJc,8098
 meshtrade/wallet/account/v1/service_pb2.pyi,sha256=K0d1vjgzzKdGrluF9h2InzFu3-lMy6UQIUqAmb0xDl4,2819
-meshtrade-0.0.4.dist-info/licenses/LICENSE,sha256=7e68NmtCi6H_-e-fbQ82lyTjKKEnLX-Kob8NcYVNaDA,1095
-meshtrade-0.0.4.dist-info/METADATA,sha256=20ufo2BXf7mq1KIMItUifOKcLqCG1fVSPGCMNQOhgOs,6680
-meshtrade-0.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-meshtrade-0.0.4.dist-info/top_level.txt,sha256=L1riO18qkORBnB4bc8vQrHyXdTkgl61nII3cLYQYD_g,10
-meshtrade-0.0.4.dist-info/RECORD,,
+meshtrade-0.0.5.dist-info/licenses/LICENSE,sha256=7e68NmtCi6H_-e-fbQ82lyTjKKEnLX-Kob8NcYVNaDA,1095
+meshtrade-0.0.5.dist-info/METADATA,sha256=5jp3xH1hM1R9-M6kH6yT11bnFsCeO7RzgSDnyLTPwoA,6681
+meshtrade-0.0.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+meshtrade-0.0.5.dist-info/top_level.txt,sha256=L1riO18qkORBnB4bc8vQrHyXdTkgl61nII3cLYQYD_g,10
+meshtrade-0.0.5.dist-info/RECORD,,