Stockholm

* `Money` objects can be used in Pydantic (`Pydantic>=2.2` supported) models and used with Pydantic's JSON serialization and validation – the same goes for `Number` and `Currency` objects as well. See examples below.

Previously validation of these types required the Pydantic config option `arbitrary_types_allowed` and JSON serialization with `model_dump_json()` resulted in an exception. With these updates there's no need for `arbitrary_types_allowed` and pydantic model's using `Money` fields can use JSON serialization+deserialization natively.
* It's also possible to use the coercible types as Pydantic field type – mainly suited for experimentation and early development. These types will automatically coerce input into `Money`, `Number` or `Currency` objects.
* `stockholm.types.ConvertibleToMoney`
* `stockholm.types.ConvertibleToMoneyWithRequiredCurrency`
* `stockholm.types.ConvertibleToNumber`
* `stockholm.types.ConvertibleToCurrency`
* Dropped support for Python 3.7.

---

Example of using `Money` fields in Pydantic models

python
from pydantic import BaseModel
from stockholm import Money

class Transaction(BaseModel):
reference: str
amount: Money

transaction = Transaction(reference="abc123", amount=Money("100.00", "SEK"))
Transaction(reference='abc123', amount=<stockholm.Money: "100.00 SEK">)

json_data = transaction.model_dump_json()
'{"reference":"abc123","amount":{"value":"100.00 SEK","units":100,"nanos":0,"currency_code":"SEK"}}'

Transaction.model_validate_json(json_data)
Transaction(reference='abc123', amount=<stockholm.Money: "100.00 SEK">)


Example of using coercible fields such as `ConvertibleToMoney` in Pydantic models

python
from pydantic import BaseModel
from stockholm import Money
from stockholm.types import ConvertibleToMoney

class ExampleModel(BaseModel):
amount: ConvertibleToMoney

example = ExampleModel(amount="4711.50 USD")
ExampleModel(amount=<stockholm.Money: "4711.50 USD">)

example.model_dump_json()
'{"amount":{"value":"4711.50 USD","units":4711,"nanos":500000000,"currency_code":"USD"}}'


Note that it's generally recommended to opt for the more strict types (`stockholm.Money`, `stockholm.Number` and `stockholm.Currency`) when possible.

---

* Added so that `Money`, `Number` and `Rate` objects can now be copied using the `copy.copy()` and `copy.deepcopy()` functions.
* Python 3.12 added to test matrix and trove classifiers.
* Fixes some type hints that previously would show as `Unknown` in some LSPs.

---

* Additional support to parse input values from third parties, data models, etc.
* Primarily load protobuf message class from `google.type.money_pb2` before falling back to the included class in `stockholm.protobuf.money_pb2`.
* Added `SLE` and `VED` to `stockholm.currency`.

---

* The `money.asdict()` function can now be called with an optional `keys` argument, which can be used to specify a tuple of keys which shuld be used in the returned dict.
* A `Number` class has been added, which can be used to differentiate between monetary values and values that doesn't hold a currency – `stockholm.Number`. Like `Rate` objects, the `Number` objects cannot be instantiated with a currency or currency code.
* Added additional documentation and examples to the README.

---

The default behaviour for calling `money.asdict()` without arguments has not changed. `money.asdict()` is equivalent to `money.asdict(keys=("value", "units", "nanos", "currency_code"))`.

Values to use in the `keys` tuple for `stockholm.Money` objects are any combination of the following:

| key | description | return type | example |
| :-- | :---------- | :---------- | -------: |
| `value` | amount + currency code | `str` | `"9001.50 USD"`
| `units` | units of the amount | `int` | `9001` |
| `nanos` | number of nano units of the amount | `int` | `500000000` |
| `currency_code` | currency code if available | `str \| None` | `"USD"` |
| `currency` | currency code if available | `str \| None` | `"USD"` |
| `amount` | the monetary amount (excl. currency code) | `str` | `"9001.50"` |

Code examples:

python
from stockholm import Money

Money("4711 USD").asdict(keys=("value", "units", "nanos", "currency_code"))
{'value': '4711.00 USD', 'units': 4711, 'nanos': 0, 'currency_code': 'USD'}

Money("4711 USD").asdict(keys=("amount", "currency"))
{'amount': '4711.00', 'currency': 'USD'}

Money(nanos=10).asdict(keys=("value", "currency", "units", "nanos"))
{'value': '0.00000001', 'currency': None, 'units': 0, 'nanos': 10}


---

* Python 3.11 added to test matrix and trove classifiers to officially claim support.

---

* Adds support for the `protobuf` Python bindings versioned 4.x.x.
* Fixes an issue with the `__hash__` method on `Currency` objects which affected currencies with an `interchangeable_with` value, such as `CNY` (+ `CNH` / `RMB`), `ILS` (+ `NIS`), `TWD` (+ `NTD`). [Thanks th-ad]

---