Skip to content

Python API

Zarr Codec

cast_value.CastValueRustV1 dataclass

Bases: _CastValueBaseV1

Cast-value codec backed by the cast-value-rs Rust implementation.

Source code in src/cast_value/zarr_compat/v1/rust_codec.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
@dataclass(frozen=True, init=False)
class CastValueRustV1(_CastValueBaseV1):
    """Cast-value codec backed by the cast-value-rs Rust implementation."""

    def _cast_array(
        self,
        arr: np.ndarray,
        *,
        target_dtype: np.dtype,
        scalar_map_entries: Iterable[ScalarMapEntry] | None,
    ) -> np.ndarray:
        from cast_value_rs import (  # noqa: PLC0415  # pylint: disable=import-outside-toplevel
            cast_array as rs_cast_array,
        )

        return rs_cast_array(
            arr=arr,
            target_dtype=_dtype_to_str(target_dtype),  # ty: ignore[invalid-argument-type]
            rounding_mode=self.rounding,
            out_of_range_mode=self.out_of_range,
            scalar_map_entries=_convert_scalar_map(scalar_map_entries),
        )

cast_value.CastValueNumpyV1 dataclass

Bases: _CastValueBaseV1

Cast-value codec backed by the pure-numpy implementation.

Source code in src/cast_value/zarr_compat/v1/numpy_codec.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@dataclass(frozen=True, init=False)
class CastValueNumpyV1(_CastValueBaseV1):
    """Cast-value codec backed by the pure-numpy implementation."""

    def _cast_array(
        self,
        arr: np.ndarray,
        *,
        target_dtype: np.dtype,
        scalar_map_entries: Iterable[ScalarMapEntry] | None,
    ) -> np.ndarray:
        return cast_array(
            arr,
            target_dtype=target_dtype,
            rounding_mode=self.rounding,
            out_of_range_mode=self.out_of_range,
            scalar_map_entries=scalar_map_entries,
        )

cast_value.cast_array 

cast_array(arr: ndarray, *, target_dtype: dtype, rounding_mode: RoundingMode, out_of_range_mode: OutOfRangeMode | None, scalar_map_entries: ScalarMapEntries | None = None) -> ndarray

Cast an array to target_dtype with rounding, out-of-range, and scalar_map handling.

Optimized to minimize allocations and passes over the data. For the simple case (no scalar_map, no rounding needed, no out-of-range), this is essentially just arr.astype(target_dtype).

All casts are performed under np.errstate(over='raise', invalid='raise') so that numpy overflow or invalid-value warnings become hard errors instead of being silently swallowed.

Source code in src/cast_value/impl/_numpy.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def cast_array(
    arr: np.ndarray,
    *,
    target_dtype: np.dtype,
    rounding_mode: RoundingMode,
    out_of_range_mode: OutOfRangeMode | None,
    scalar_map_entries: ScalarMapEntries | None = None,
) -> np.ndarray:
    """Cast an array to target_dtype with rounding, out-of-range, and scalar_map handling.

    Optimized to minimize allocations and passes over the data.
    For the simple case (no scalar_map, no rounding needed, no out-of-range),
    this is essentially just ``arr.astype(target_dtype)``.

    All casts are performed under ``np.errstate(over='raise', invalid='raise')``
    so that numpy overflow or invalid-value warnings become hard errors instead
    of being silently swallowed.
    """
    entries = _normalize_scalar_map(scalar_map_entries)
    with np.errstate(over="raise", invalid="raise"):
        return _cast_array_impl(
            arr,
            target_dtype=target_dtype,
            rounding=rounding_mode,
            out_of_range=out_of_range_mode,
            scalar_map_entries=entries or None,
        )

cast_value.ScalarMapJSON

Bases: TypedDict

JSON representation of the scalar_map codec configuration field.

This type models permitted values for the scalar_map field in the configuration field of the cast_value codec metadata.

See the cast_value spec for details.

Source code in src/cast_value/types.py 
21
22
23
24
25
26
27
28
29
30
31
32
class ScalarMapJSON(TypedDict):
    """
    JSON representation of the scalar_map codec configuration field.

    This type models permitted values for the [`scalar_map`](https://github.com/zarr-developers/zarr-extensions/tree/main/codecs/cast_value#scalar_map) field in the
    [`configuration`](https://github.com/zarr-developers/zarr-extensions/tree/main/codecs/cast_value#configuration) field of the `cast_value` codec metadata.

    See the [`cast_value` spec](https://github.com/zarr-developers/zarr-extensions/tree/main/codecs/cast_value) for details.
    """

    encode: NotRequired[list[tuple[object, object]]]
    decode: NotRequired[list[tuple[object, object]]]

encode instance-attribute 

encode: NotRequired[list[tuple[object, object]]]

decode instance-attribute 

decode: NotRequired[list[tuple[object, object]]]

cast_value.ScalarMapEntry module-attribute 

ScalarMapEntry = tuple[NumericScalar, NumericScalar]

cast_value.ScalarMapEntries module-attribute 

ScalarMapEntries: TypeAlias = Iterable[ScalarMapEntry] | Mapping[NumericScalar, NumericScalar]

cast_value.RoundingMode module-attribute 

RoundingMode = Literal['nearest-even', 'towards-zero', 'towards-positive', 'towards-negative', 'nearest-away']

cast_value.OutOfRangeMode module-attribute 

OutOfRangeMode = Literal['clamp', 'wrap']

cast_value.NumericScalar module-attribute 

NumericScalar: TypeAlias = integer | floating