decimal

Helper methods for working with Python Decimals.

bytes_required(value)

Return the minimum number of bytes needed to serialize a decimal or unscaled value.

Parameters:

Name	Type	Description	Default
value	int | Decimal	a Decimal value or unscaled int value.	required

Returns:

Name	Type	Description
int	int	the minimum number of bytes needed to serialize the value.

Source code in pyiceberg/utils/decimal.py

def bytes_required(value: Union[int, Decimal]) -> int:
    """Return the minimum number of bytes needed to serialize a decimal or unscaled value.

    Args:
        value (int | Decimal): a Decimal value or unscaled int value.

    Returns:
        int: the minimum number of bytes needed to serialize the value.
    """
    if isinstance(value, int):
        return (value.bit_length() + 7) // 8
    elif isinstance(value, Decimal):
        return (decimal_to_unscaled(value).bit_length() + 7) // 8

    raise ValueError(f"Unsupported value: {value}")

bytes_to_decimal(value, scale)

Return a decimal from the bytes.

Parameters:

Name	Type	Description	Default
value	bytes	tbe bytes to be converted into a decimal.	required
scale	int	the scale of the decimal.	required

Returns:

Name	Type	Description
Decimal	Decimal	the scaled decimal.

Source code in pyiceberg/utils/decimal.py

def bytes_to_decimal(value: bytes, scale: int) -> Decimal:
    """Return a decimal from the bytes.

    Args:
        value (bytes): tbe bytes to be converted into a decimal.
        scale (int): the scale of the decimal.

    Returns:
        Decimal: the scaled decimal.
    """
    unscaled_datum = int.from_bytes(value, byteorder="big", signed=True)
    return unscaled_to_decimal(unscaled_datum, scale)

decimal_required_bytes(precision)

Compute the number of bytes required to store a precision.

Parameters:

Name	Type	Description	Default
precision	int	The number of digits to store.	required

Returns:

Type	Description
int	The number of bytes required to store a decimal with a certain precision.

Source code in pyiceberg/utils/decimal.py

def decimal_required_bytes(precision: int) -> int:
    """Compute the number of bytes required to store a precision.

    Args:
        precision: The number of digits to store.

    Returns:
        The number of bytes required to store a decimal with a certain precision.
    """
    if precision <= 0 or precision >= 40:
        raise ValueError(f"Unsupported precision, outside of (0, 40]: {precision}")

    return REQUIRED_LENGTH[precision]

decimal_to_bytes(value, byte_length=None)

Return a byte representation of a decimal.

Parameters:

Name	Type	Description	Default
value	Decimal	a decimal value.	required
byte_length	int	The number of bytes.	None

Returns: bytes: the unscaled value of the Decimal as bytes.

Source code in pyiceberg/utils/decimal.py

def decimal_to_bytes(value: Decimal, byte_length: Optional[int] = None) -> bytes:
    """Return a byte representation of a decimal.

    Args:
        value (Decimal): a decimal value.
        byte_length (int): The number of bytes.
    Returns:
        bytes: the unscaled value of the Decimal as bytes.
    """
    unscaled_value = decimal_to_unscaled(value)
    if byte_length is None:
        byte_length = bytes_required(unscaled_value)
    return unscaled_value.to_bytes(byte_length, byteorder="big", signed=True)

decimal_to_unscaled(value)

Get an unscaled value given a Decimal value.

Parameters:

Name	Type	Description	Default
value	Decimal	A Decimal instance.	required

Returns:

Name	Type	Description
int	int	The unscaled value.

Source code in pyiceberg/utils/decimal.py

def decimal_to_unscaled(value: Decimal) -> int:
    """Get an unscaled value given a Decimal value.

    Args:
        value (Decimal): A Decimal instance.

    Returns:
        int: The unscaled value.
    """
    sign, digits, _ = value.as_tuple()
    return int(Decimal((sign, digits, 0)).to_integral_value())

truncate_decimal(value, width)

Get a truncated Decimal value given a decimal value and a width.

Parameters:

Name	Type	Description	Default
value	Decimal	a decimal value.	required
width	int	A width for the returned Decimal instance.	required

Returns: Decimal: A truncated Decimal instance.

Source code in pyiceberg/utils/decimal.py

def truncate_decimal(value: Decimal, width: int) -> Decimal:
    """Get a truncated Decimal value given a decimal value and a width.

    Args:
        value (Decimal): a decimal value.
        width (int): A width for the returned Decimal instance.
    Returns:
        Decimal: A truncated Decimal instance.
    """
    unscaled_value = decimal_to_unscaled(value)
    applied_value = unscaled_value - (((unscaled_value % width) + width) % width)
    return unscaled_to_decimal(applied_value, abs(int(value.as_tuple().exponent)))

unscaled_to_decimal(unscaled, scale)

Get a scaled Decimal value given an unscaled value and a scale.

Parameters:

Name	Type	Description	Default
unscaled	int	An unscaled value.	required
scale	int	A scale to set for the returned Decimal instance.	required

Returns:

Name	Type	Description
Decimal	Decimal	A scaled Decimal instance.

Source code in pyiceberg/utils/decimal.py

def unscaled_to_decimal(unscaled: int, scale: int) -> Decimal:
    """Get a scaled Decimal value given an unscaled value and a scale.

    Args:
        unscaled (int): An unscaled value.
        scale (int): A scale to set for the returned Decimal instance.

    Returns:
        Decimal: A scaled Decimal instance.
    """
    sign, digits, _ = Decimal(unscaled).as_tuple()
    return Decimal((sign, digits, -scale))