Bulk Operations

The bulk module provides optimized functions for performing operations on multiple Money objects efficiently.

Bulk operations for Money objects.

This module provides functions for performing operations on multiple Money objects at once, which can be more efficient than working with them individually.

moneyx.bulk.bulk_multiply(money_objects, multipliers)

Efficiently multiply multiple Money objects by their corresponding multipliers.

Parameters:

• money_objects (Sequence[Money]) – A sequence of Money objects

• multipliers (Sequence[Union[int, float, Decimal]]) – A sequence of multipliers (must be the same length as money_objects)

Return type:

List[Money]

Returns:

A list of Money objects, each being the result of multiplying the corresponding money_object with its multiplier

Raises:

ValueError – If the sequences have different lengths

Example

>>> from moneyx import Money
>>> from moneyx.bulk import bulk_multiply
>>> prices = [
...     Money("10.00", "USD"),
...     Money("20.00", "USD"),
...     Money("30.00", "USD")
... ]
>>> quantities = [2, 3, 1]
>>> results = bulk_multiply(prices, quantities)
>>> [str(m.amount) for m in results]
['20.00', '60.00', '30.00']

moneyx.bulk.bulk_add(money_objects, currency_code=None)

Efficiently sum multiple Money objects.

All Money objects must have the same currency unless a target currency_code is provided.

Parameters:

• money_objects (Sequence[Money]) – A sequence of Money objects to sum

• currency_code (Optional[str]) – Optional target currency code. If provided, all amounts will be assumed to be in this currency. If not provided, the currency of the first Money object will be used and all objects must have the same currency.

Return type:

Money

Returns:

A single Money object representing the sum

Raises:

ValueError – If the money_objects have different currencies and no currency_code is provided

Example

>>> from moneyx import Money
>>> from moneyx.bulk import bulk_add
>>> expenses = [
...     Money("10.50", "USD"),
...     Money("20.75", "USD"),
...     Money("5.99", "USD"),
... ]
>>> total = bulk_add(expenses)
>>> str(total.amount)
'37.24'

moneyx.bulk.bulk_allocate(money, allocation_data)

Allocate a Money object according to a sequence of ratios.

This function is similar to Money.allocate() but provides a more convenient interface for allocating money according to a sequence of ratios.

Parameters:

• money (Money) – The Money object to allocate

• allocation_data (Sequence[Union[int, float, Decimal]]) – A sequence of values representing allocation ratios/weights

Return type:

List[Money]

Returns:

A list of Money objects, each having a portion of the original amount

Raises:

ValueError – If allocation_data contains negative values or has all zero values

Example

>>> from moneyx import Money
>>> from moneyx.bulk import bulk_allocate
>>> total = Money("100.00", "USD")
>>> shares = [5, 3, 2]  # Allocate in 5:3:2 ratio
>>> results = bulk_allocate(total, shares)
>>> [str(m.amount) for m in results]
['50.00', '30.00', '20.00']

moneyx.bulk.bulk_with_tax(money_objects, tax_rate_percent)

Add tax to multiple Money objects at once.

Parameters:

• money_objects (Sequence[Money]) – A sequence of Money objects

• tax_rate_percent (float) – The tax rate as a percentage (e.g., 10 for 10%)

Return type:

List[Money]

Returns:

A list of Money objects with tax added

Example

>>> from moneyx import Money
>>> from moneyx.bulk import bulk_with_tax
>>> prices = [
...     Money("10.00", "USD"),
...     Money("20.00", "USD"),
...     Money("30.00", "USD")
... ]
>>> with_tax = bulk_with_tax(prices, 10)  # Add 10% tax
>>> [m.amount for m in with_tax]
[Decimal('11.00'), Decimal('22.00'), Decimal('33.00')]