examples.24_money_amount_decimal

  1"""Demonstrates how to parse money amounts like `'€12.34'` or `'USD 12.34'`
  2into a `(currency, Decimal)` tuple using a transformation pipeline.
  3
  4This example shows:
  5  * How to normalize various input formats (`'€12.34'`, `'usd 12.34'`, `'GBP 7.50'`).
  6  * How to convert the string amount into a `Decimal`.
  7  * How to detect invalid or unsupported currency formats gracefully.
  8
  9Run directly:
 10
 11    python examples/24_money_amount_decimal.py
 12
 13Expected output:
 14
 15    good: OK ('EUR', Decimal('12.34'))
 16    good2: OK ('GBP', Decimal('7.50'))
 17    bad : EXCEPTION Value must be one of <enum 'Currency'>, got ('AUD', Decimal('1.23'))
 18"""
 19
 20import sys
 21import pathlib
 22from decimal import Decimal, InvalidOperation
 23from enum import Enum
 24from typing import List
 25
 26# ---------------------------------------------------------------------------
 27# Make repo root importable when running this file directly
 28# ---------------------------------------------------------------------------
 29sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
 30
 31from constrained_values import Response, Status, TypeValidationStrategy
 32from constrained_values.value import TransformationStrategy, ConstrainedValue, PipeLineStrategy
 33
 34
 35class Currency(Enum):
 36    """Supported currencies for this example."""
 37    USD = "USD"
 38    EUR = "EUR"
 39    GBP = "GBP"
 40
 41
 42class Strip(TransformationStrategy[str, str]):
 43    """Trim leading and trailing whitespace from a string."""
 44
 45    def transform(self, value: str) -> Response[str]:
 46        """Strip whitespace from the input string.
 47
 48        Args:
 49            value: The raw input string.
 50
 51        Returns:
 52            Response[str]: Contains:
 53                * `status = Status.OK`
 54                * `details = "strip"`
 55                * `value` — the trimmed string
 56        """
 57        return Response(Status.OK, "strip", value.strip())
 58
 59
 60class NormalizeCurrencyPrefix(TransformationStrategy[str, tuple]):
 61    """Normalize currency prefixes and symbols.
 62
 63    Accepts strings like `'EUR 12.34'`, `'€12.34'`, or `'usd 12.34'`
 64    and converts them into a tuple `(currency_code, amount_string)`.
 65
 66    If the input cannot be parsed, the strategy returns `Status.EXCEPTION`.
 67    """
 68
 69    SYMBOLS = {"€": "EUR", "$": "USD", "£": "GBP"}
 70
 71    def transform(self, value: str) -> Response[tuple]:
 72        """Normalize currency and extract amount substring.
 73
 74        Args:
 75            value: The string containing currency and amount.
 76
 77        Returns:
 78            Response[tuple]: Contains `(currency_code, amount_str)` or
 79            an error response if parsing fails.
 80        """
 81        v = value.strip()
 82        if not v:
 83            return Response(Status.EXCEPTION, "empty", None)
 84        if v[0] in self.SYMBOLS:
 85            cur = self.SYMBOLS[v[0]]
 86            amt = v[1:].strip()
 87            return Response(Status.OK, "symbol", (cur, amt))
 88        parts = v.split(None, 1)
 89        if len(parts) == 2:
 90            cur, amt = parts[0].upper(), parts[1].strip()
 91            return Response(Status.OK, "prefix", (cur, amt))
 92        return Response(Status.EXCEPTION, "format 'CUR 12.34' or '€12.34'", None)
 93
 94
 95class ParseAmount(TransformationStrategy[tuple, tuple]):
 96    """Convert a `(currency, amount_string)` pair into a `(currency, Decimal)` tuple."""
 97
 98    def transform(self, value: tuple) -> Response[tuple]:
 99        """Attempt to parse the amount as a Decimal.
100
101        Args:
102            value: Tuple `(currency_code, amount_str)`.
103
104        Returns:
105            Response[tuple]: Contains:
106                * `status = Status.OK` with `(currency_code, Decimal(amount))`
107                * `status = Status.EXCEPTION` if parsing fails
108        """
109        cur, amt_s = value
110        try:
111            return Response(Status.OK, "decimal", (cur, Decimal(amt_s)))
112        except (InvalidOperation, ValueError) as e:
113            return Response(Status.EXCEPTION, f"bad decimal: {e}", None)
114
115
116from constrained_values import EnumValidationStrategy
117
118class MoneyConfig(ConstrainedValue[tuple]):
119    """A `ConstrainedValue` that parses a money amount into `(currency, Decimal)`.
120
121    The transformation pipeline:
122        1. `TypeValidationStrategy(str)` — ensures the input is a string.
123        2. `Strip()` — trims leading/trailing spaces.
124        3. `NormalizeCurrencyPrefix()` — extracts `(currency, amount_string)`.
125        4. `ParseAmount()` — converts amount to `Decimal`.
126        5. `EnumValidationStrategy(Currency)` — ensures currency is supported.
127    """
128
129    def get_strategies(self) -> List[PipeLineStrategy]:
130        """Return the full transformation pipeline."""
131        return [
132            TypeValidationStrategy(str),
133            Strip(),
134            NormalizeCurrencyPrefix(),
135            ParseAmount(),
136            EnumValidationStrategy(Currency),
137        ]
138
139
140
141def main() -> None:
142    """Run the money parsing demonstration.
143
144    Creates several :class:`MoneyConfig` instances to parse different
145    currency string formats and prints their results.
146
147    Steps:
148        1. `"€12.34"` → OK, parsed as (`'EUR'`, Decimal('12.34')).
149        2. `"gbp 7.50"` → OK, parsed as (`'GBP'`, Decimal('7.50')).
150        3. `"AUD 1.23"` → EXCEPTION, unsupported currency format.
151
152    Prints:
153        * `"good: OK ('EUR', Decimal('12.34'))"`
154        * `"good2: OK ('GBP', Decimal('7.50'))"`
155        * `"bad : EXCEPTION Value must be one of <enum 'Currency'>, got ('AUD', Decimal('1.23'))"`
156    """
157    good = MoneyConfig("€12.34")
158    print("good:", good.status.name, good.value)
159    good2 = MoneyConfig("gbp 7.50")
160    print("good2:", good2.status.name, good2.value)
161    bad = MoneyConfig("AUD 1.23")
162    print("bad :", bad.status.name, bad.details)
163
164
165if __name__ == "__main__":
166    main()