meshtrade 1.22.0__py3-none-any.whl → 1.23.1__py3-none-any.whl

meshtrade/type/v1/decimal_operations.py

@@ -0,0 +1,354 @@
+"""Decimal operations utility functions for Mesh API.
+
+This module provides arithmetic, comparison, and utility functions for working
+with protobuf Decimal messages, offering a Pythonic API for decimal arithmetic
+with consistent precision handling.
+"""
+
+from decimal import ROUND_HALF_UP
+
+from .decimal_built_in_conversions import decimal_to_built_in
+from .decimal_pb2 import Decimal
+
+
+def decimal_add(d1: Decimal | None, d2: Decimal | None) -> Decimal:
+    """Add two Decimal values.
+
+    Args:
+        d1: First decimal value (None treated as 0)
+        d2: Second decimal value (None treated as 0)
+
+    Returns:
+        New Decimal containing the sum (d1 + d2)
+
+    None Safety:
+        None inputs are treated as zero
+
+    Example:
+        >>> d1 = Decimal(value="10.5")
+        >>> d2 = Decimal(value="20.3")
+        >>> result = decimal_add(d1, d2)
+        >>> result.value
+        '30.8'
+    """
+    val1 = decimal_to_built_in(d1)
+    val2 = decimal_to_built_in(d2)
+    return Decimal(value=str(val1 + val2))
+
+
+def decimal_sub(d1: Decimal | None, d2: Decimal | None) -> Decimal:
+    """Subtract two Decimal values.
+
+    Args:
+        d1: First decimal value (None treated as 0)
+        d2: Second decimal value (subtrahend, None treated as 0)
+
+    Returns:
+        New Decimal containing the difference (d1 - d2)
+
+    None Safety:
+        None inputs are treated as zero
+
+    Example:
+        >>> d1 = Decimal(value="100.5")
+        >>> d2 = Decimal(value="30.2")
+        >>> result = decimal_sub(d1, d2)
+        >>> result.value
+        '70.3'
+    """
+    val1 = decimal_to_built_in(d1)
+    val2 = decimal_to_built_in(d2)
+    return Decimal(value=str(val1 - val2))
+
+
+def decimal_mul(d1: Decimal | None, d2: Decimal | None) -> Decimal:
+    """Multiply two Decimal values.
+
+    Args:
+        d1: First decimal value (None treated as 0)
+        d2: Second decimal value (None treated as 0)
+
+    Returns:
+        New Decimal containing the product (d1 * d2)
+
+    None Safety:
+        None inputs are treated as zero
+
+    Example:
+        >>> d1 = Decimal(value="10.5")
+        >>> d2 = Decimal(value="2")
+        >>> result = decimal_mul(d1, d2)
+        >>> result.value
+        '21.0'
+    """
+    val1 = decimal_to_built_in(d1)
+    val2 = decimal_to_built_in(d2)
+    return Decimal(value=str(val1 * val2))
+
+
+def decimal_div(d1: Decimal | None, d2: Decimal | None) -> Decimal:
+    """Divide two Decimal values.
+
+    Args:
+        d1: Dividend (None treated as 0)
+        d2: Divisor (must not be zero, None treated as 0)
+
+    Returns:
+        New Decimal containing the quotient (d1 / d2)
+
+    Raises:
+        ZeroDivisionError: If d2 is zero
+
+    None Safety:
+        None inputs are treated as zero (note: None d2 will raise ZeroDivisionError)
+
+    Example:
+        >>> d1 = Decimal(value="100")
+        >>> d2 = Decimal(value="4")
+        >>> result = decimal_div(d1, d2)
+        >>> result.value
+        '25'
+    """
+    val1 = decimal_to_built_in(d1)
+    val2 = decimal_to_built_in(d2)
+
+    if val2 == 0:
+        raise ZeroDivisionError("cannot divide by zero")
+
+    return Decimal(value=str(val1 / val2))
+
+
+def decimal_equal(d1: Decimal | None, d2: Decimal | None) -> bool:
+    """Check if two Decimal values are equal.
+
+    Args:
+        d1: First decimal value (None treated as 0)
+        d2: Second decimal value (None treated as 0)
+
+    Returns:
+        True if d1 == d2, False otherwise
+
+    None Safety:
+        None inputs are treated as zero
+
+    Example:
+        >>> d1 = Decimal(value="10.5")
+        >>> d2 = Decimal(value="10.5")
+        >>> decimal_equal(d1, d2)
+        True
+    """
+    val1 = decimal_to_built_in(d1)
+    val2 = decimal_to_built_in(d2)
+    return val1 == val2
+
+
+def decimal_less_than(d1: Decimal | None, d2: Decimal | None) -> bool:
+    """Check if first Decimal is less than second.
+
+    Args:
+        d1: First decimal value (None treated as 0)
+        d2: Second decimal value (None treated as 0)
+
+    Returns:
+        True if d1 < d2, False otherwise
+
+    None Safety:
+        None inputs are treated as zero
+
+    Example:
+        >>> d1 = Decimal(value="10.5")
+        >>> d2 = Decimal(value="20.3")
+        >>> decimal_less_than(d1, d2)
+        True
+    """
+    val1 = decimal_to_built_in(d1)
+    val2 = decimal_to_built_in(d2)
+    return val1 < val2
+
+
+def decimal_less_than_or_equal(d1: Decimal | None, d2: Decimal | None) -> bool:
+    """Check if first Decimal is less than or equal to second.
+
+    Args:
+        d1: First decimal value (None treated as 0)
+        d2: Second decimal value (None treated as 0)
+
+    Returns:
+        True if d1 <= d2, False otherwise
+
+    None Safety:
+        None inputs are treated as zero
+
+    Example:
+        >>> d1 = Decimal(value="10.5")
+        >>> d2 = Decimal(value="10.5")
+        >>> decimal_less_than_or_equal(d1, d2)
+        True
+    """
+    val1 = decimal_to_built_in(d1)
+    val2 = decimal_to_built_in(d2)
+    return val1 <= val2
+
+
+def decimal_greater_than(d1: Decimal | None, d2: Decimal | None) -> bool:
+    """Check if first Decimal is greater than second.
+
+    Args:
+        d1: First decimal value (None treated as 0)
+        d2: Second decimal value (None treated as 0)
+
+    Returns:
+        True if d1 > d2, False otherwise
+
+    None Safety:
+        None inputs are treated as zero
+
+    Example:
+        >>> d1 = Decimal(value="20.3")
+        >>> d2 = Decimal(value="10.5")
+        >>> decimal_greater_than(d1, d2)
+        True
+    """
+    val1 = decimal_to_built_in(d1)
+    val2 = decimal_to_built_in(d2)
+    return val1 > val2
+
+
+def decimal_greater_than_or_equal(d1: Decimal | None, d2: Decimal | None) -> bool:
+    """Check if first Decimal is greater than or equal to second.
+
+    Args:
+        d1: First decimal value (None treated as 0)
+        d2: Second decimal value (None treated as 0)
+
+    Returns:
+        True if d1 >= d2, False otherwise
+
+    None Safety:
+        None inputs are treated as zero
+
+    Example:
+        >>> d1 = Decimal(value="10.5")
+        >>> d2 = Decimal(value="10.5")
+        >>> decimal_greater_than_or_equal(d1, d2)
+        True
+    """
+    val1 = decimal_to_built_in(d1)
+    val2 = decimal_to_built_in(d2)
+    return val1 >= val2
+
+
+def decimal_is_zero(d: Decimal | None) -> bool:
+    """Check if Decimal value is zero.
+
+    Args:
+        d: Decimal value to check (None treated as 0)
+
+    Returns:
+        True if d == 0, False otherwise
+
+    None Safety:
+        None inputs are treated as zero (returns True)
+
+    Example:
+        >>> d = Decimal(value="0")
+        >>> decimal_is_zero(d)
+        True
+        >>> d2 = Decimal(value="0.001")
+        >>> decimal_is_zero(d2)
+        False
+    """
+    val = decimal_to_built_in(d)
+    return val == 0
+
+
+def decimal_is_negative(d: Decimal | None) -> bool:
+    """Check if Decimal value is negative (< 0).
+
+    Args:
+        d: Decimal value to check (None treated as 0)
+
+    Returns:
+        True if d < 0, False if d >= 0
+
+    None Safety:
+        None inputs are treated as zero (returns False)
+
+    Example:
+        >>> d = Decimal(value="-10.5")
+        >>> decimal_is_negative(d)
+        True
+        >>> d2 = Decimal(value="10.5")
+        >>> decimal_is_negative(d2)
+        False
+    """
+    val = decimal_to_built_in(d)
+    return val < 0
+
+
+def decimal_is_positive(d: Decimal | None) -> bool:
+    """Check if Decimal value is positive (> 0).
+
+    Args:
+        d: Decimal value to check (None treated as 0)
+
+    Returns:
+        True if d > 0, False if d <= 0
+
+    None Safety:
+        None inputs are treated as zero (returns False)
+
+    Example:
+        >>> d = Decimal(value="10.5")
+        >>> decimal_is_positive(d)
+        True
+        >>> d2 = Decimal(value="0")
+        >>> decimal_is_positive(d2)
+        False
+    """
+    val = decimal_to_built_in(d)
+    return val > 0
+
+
+def decimal_round(d: Decimal | None, places: int) -> Decimal:
+    """Round Decimal to specified number of decimal places.
+
+    If places < 0, it rounds the integer part to the nearest 10^(-places).
+
+    Args:
+        d: Decimal value to round (None treated as 0)
+        places: Number of decimal places (can be negative)
+
+    Returns:
+        New Decimal containing the rounded value
+
+    None Safety:
+        None inputs are treated as zero
+
+    Example:
+        >>> d = Decimal(value="5.45")
+        >>> result = decimal_round(d, 1)
+        >>> result.value
+        '5.5'
+        >>> d2 = Decimal(value="545")
+        >>> result2 = decimal_round(d2, -1)
+        >>> result2.value
+        '550'
+    """
+    from decimal import Decimal as PyDecimal
+
+    val = decimal_to_built_in(d)
+
+    if places < 0:
+        # For negative places, use shift-quantize-shift back approach
+        # to properly round the integer part
+        scale = PyDecimal(10) ** (-places)
+        shifted = val / scale
+        rounded_shifted = shifted.quantize(PyDecimal("1"), rounding=ROUND_HALF_UP)
+        rounded_val = rounded_shifted * scale
+    else:
+        # For positive places, quantize directly
+        quantizer = PyDecimal(10) ** -places
+        rounded_val = val.quantize(quantizer, rounding=ROUND_HALF_UP)
+
+    return Decimal(value=str(rounded_val))

meshtrade/type/v1/ledger.py

@@ -10,7 +10,7 @@ class UnsupportedLedgerError(Exception):
     """Exception raised for unsupported Ledger values."""
 
     def __init__(self, ledger: Ledger):
-        self.financial_business_day_convention = ledger
+        self.ledger = ledger
         message = f"Unsupported Ledger: {ledger}"
         super().__init__(message)
 
@@ -23,3 +23,78 @@ def get_ledger_no_decimal_places(ledger: Ledger) -> int:
         return _ledger_decimal_places[ledger]
     else:
         raise UnsupportedLedgerError(ledger)
+
+
+def ledger_to_pretty_string(ledger: Ledger) -> str:
+    """Convert the Ledger enum value to a human-readable network name.
+
+    This method provides user-friendly names for each blockchain network/ledger type.
+
+    Args:
+        ledger: The Ledger enum value
+
+    Returns:
+        A human-readable network name string, or "Unknown" for invalid/unrecognized values
+
+    Example:
+        >>> ledger_to_pretty_string(Ledger.LEDGER_STELLAR)
+        'Stellar'
+        >>> ledger_to_pretty_string(Ledger.LEDGER_ETHEREUM)
+        'Ethereum'
+        >>> ledger_to_pretty_string(Ledger.LEDGER_UNSPECIFIED)
+        'Unspecified'
+    """
+    if ledger == Ledger.LEDGER_STELLAR:
+        return "Stellar"
+    elif ledger == Ledger.LEDGER_ETHEREUM:
+        return "Ethereum"
+    elif ledger == Ledger.LEDGER_BITCOIN:
+        return "Bitcoin"
+    elif ledger == Ledger.LEDGER_LITECOIN:
+        return "Litecoin"
+    elif ledger == Ledger.LEDGER_XRP:
+        return "XRP"
+    elif ledger == Ledger.LEDGER_SA_STOCK_BROKERS:
+        return "SA Stock Brokers"
+    elif ledger == Ledger.LEDGER_NULL:
+        return "Null"
+    elif ledger == Ledger.LEDGER_UNSPECIFIED:
+        return "Unspecified"
+    else:
+        return "Unknown"
+
+
+def ledger_is_valid(ledger: Ledger) -> bool:
+    """Check if ledger value is valid (within enum range).
+
+    Args:
+        ledger: The Ledger enum value to check
+
+    Returns:
+        True if the ledger is a valid enum value, False otherwise
+
+    Example:
+        >>> ledger_is_valid(Ledger.LEDGER_STELLAR)
+        True
+        >>> ledger_is_valid(999)  # Invalid enum value
+        False
+    """
+    return ledger in Ledger.values()
+
+
+def ledger_is_valid_and_defined(ledger: Ledger) -> bool:
+    """Check if ledger is valid and not UNSPECIFIED.
+
+    Args:
+        ledger: The Ledger enum value to check
+
+    Returns:
+        True if the ledger is valid and not LEDGER_UNSPECIFIED, False otherwise
+
+    Example:
+        >>> ledger_is_valid_and_defined(Ledger.LEDGER_STELLAR)
+        True
+        >>> ledger_is_valid_and_defined(Ledger.LEDGER_UNSPECIFIED)
+        False
+    """
+    return ledger_is_valid(ledger) and ledger != Ledger.LEDGER_UNSPECIFIED

meshtrade/type/v1/token.py

@@ -0,0 +1,144 @@
+"""Token utility functions for Mesh API.
+
+This module provides utility functions for working with Token protobuf messages,
+including helper functions for token creation, validation, and formatting.
+"""
+
+from .ledger_pb2 import Ledger
+from .token_pb2 import Token
+
+
+def new_undefined_token() -> Token:
+    """Create a new Token representing an undefined or placeholder token.
+
+    The undefined token has:
+    - Code: "-"
+    - Issuer: "-"
+    - Ledger: LEDGER_UNSPECIFIED
+
+    This is useful as a sentinel value to represent the absence of a valid token
+    or as a placeholder in data structures.
+
+    Returns:
+        A Token configured as undefined
+
+    Example:
+        >>> token = new_undefined_token()
+        >>> token.code
+        '-'
+        >>> token.issuer
+        '-'
+        >>> token_is_undefined(token)
+        True
+    """
+    return Token(
+        code="-",
+        issuer="-",
+        ledger=Ledger.LEDGER_UNSPECIFIED,
+    )
+
+
+def token_is_undefined(token: Token | None) -> bool:
+    """Check whether this token represents an undefined or placeholder token.
+
+    A token is considered undefined if:
+    - The token is None, OR
+    - The token has Code == "-" AND Issuer == "-" AND Ledger == LEDGER_UNSPECIFIED
+
+    Args:
+        token: Token to check (can be None)
+
+    Returns:
+        True if the token is undefined (None or matches undefined pattern), False otherwise
+
+    None Safety:
+        Returns True if token is None
+
+    Example:
+        >>> token = None
+        >>> token_is_undefined(token)
+        True
+        >>> token = new_undefined_token()
+        >>> token_is_undefined(token)
+        True
+        >>> defined = Token(code="USD", issuer="ISSUER", ledger=Ledger.LEDGER_STELLAR)
+        >>> token_is_undefined(defined)
+        False
+    """
+    if token is None:
+        return True
+
+    return token.code == "-" and token.issuer == "-" and token.ledger == Ledger.LEDGER_UNSPECIFIED
+
+
+def token_is_equal_to(token1: Token | None, token2: Token | None) -> bool:
+    """Compare two tokens for equality.
+
+    Two tokens are considered equal if and only if all of the following match:
+    - Code (asset code)
+    - Issuer (asset issuer)
+    - Ledger (blockchain/ledger type)
+
+    Args:
+        token1: First token to compare (can be None)
+        token2: Second token to compare (can be None)
+
+    Returns:
+        True if both tokens are equal (including both being None), False otherwise
+
+    None Safety:
+        Returns True if both are None, False if only one is None
+
+    Example:
+        >>> token1 = Token(code="USD", issuer="ISSUER1", ledger=Ledger.LEDGER_STELLAR)
+        >>> token2 = Token(code="USD", issuer="ISSUER1", ledger=Ledger.LEDGER_STELLAR)
+        >>> token_is_equal_to(token1, token2)
+        True
+        >>> token3 = Token(code="EUR", issuer="ISSUER1", ledger=Ledger.LEDGER_STELLAR)
+        >>> token_is_equal_to(token1, token3)
+        False
+        >>> token_is_equal_to(None, None)
+        True
+    """
+    # Handle None cases
+    if token1 is None and token2 is None:
+        return True
+    if token1 is None or token2 is None:
+        return False
+
+    return token1.code == token2.code and token1.issuer == token2.issuer and token1.ledger == token2.ledger
+
+
+def token_pretty_string(token: Token | None) -> str:
+    """Return a human-readable string representation of the token.
+
+    Format: "CODE by ISSUER on NETWORK"
+
+    Args:
+        token: Token to format (can be None)
+
+    Returns:
+        A formatted string describing the token, or "undefined" if None/undefined
+
+    None Safety:
+        Returns "undefined" if token is None
+
+    Example:
+        >>> token = Token(code="USD", issuer="CIRCLE", ledger=Ledger.LEDGER_STELLAR)
+        >>> token_pretty_string(token)
+        'USD by CIRCLE on Stellar'
+        >>> token_pretty_string(None)
+        'undefined'
+        >>> token_pretty_string(new_undefined_token())
+        'undefined'
+    """
+    if token is None:
+        return "undefined"
+
+    if token_is_undefined(token):
+        return "undefined"
+
+    # Import ledger utility for pretty printing
+    from .ledger import ledger_to_pretty_string
+
+    return f"{token.code} by {token.issuer} on {ledger_to_pretty_string(token.ledger)}"

meshtrade/wallet/account/v1/service_meshpy.py

@@ -9,6 +9,7 @@ the service interface with resource management capabilities, providing authentic
 timeouts, and proper connection handling.
 """
 
+from collections.abc import Iterator
 from datetime import timedelta
 from typing import Optional
 

{meshtrade-1.22.0.dist-info → meshtrade-1.23.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshtrade
-Version: 1.22.0
+Version: 1.23.1
 Summary: Integration SDK for Mesh API Services
 Author-email: Bernard Bussy <bernard@meshtrade.co>
 License: LicenseRef-My-Custom-License