nt2.casters

module documentation

(source)

Provide any functions for transforming a "stringy" dict/list/value to one with more types.

In practice, this is just cast_stringy_data and any support functions it needs.

Function	`cast_stringy_data`	Take nested `StringyData` and return a copy with matching nodes up-typed.
Function	`_cast_datey`	Cast `date`/`datetime`/`time` strings to `date`/`datetime`/`time` objects.
Function	`_str_to_bool`	Translate a commonly used boolean `str` into a real `bool`.
Function	`_str_to_datey`	Translate an ISO 8601 date/time `str` into a `date`, `datetime`, or marked time `str`.
Function	`_str_to_num`	Translate a number as `str` into a real `int` or `float`.

def cast_stringy_data(data: StringyData, bool_paths: Sequence[str] = (), null_paths: Sequence[str] = (), num_paths: Sequence[str] = (), date_paths: Sequence[str] = (), converter: Converter | None = None) -> TypedData: (source) ¶

Take nested StringyData and return a copy with matching nodes up-typed.

Parameters
data:`StringyData`	A `dict` or `list` composed of `str`, `dict` and `list` items all the way down, or (rarely) a `str`.
bool_paths:`Sequence[str]`	YAMLPath queries indicating nodes to be up-typed to `bool`.
null_paths:`Sequence[str]`	YAMLPath queries indicating nodes to be up-typed to `None`.
num_paths:`Sequence[str]`	YAMLPath queries indicating nodes to be up-typed to `int`/`float`.
date_paths:`Sequence[str]`	YAMLPath queries indicating nodes to be up-typed to `date`/`datetime`/`time`.
converter:`Converter \| None`	A `Converter` used to `unstructure` the result to match specific type support, defaulting to one created with `mk_json_types_converter`.

Returns
`TypedData`	A nested `dict` or `list` containing some "up-typed" (casted) items in addition to `str`s, or (rarely) a single value.

Raises
`ValueError`	Up-typing a `str` failed due to an unexpected format.

def _cast_datey(surgeon: Processor, date_paths: Sequence[str]) -> dict | list: (source) ¶

Cast date/datetime/time strings to date/datetime/time objects.

We can't currently store a time type in the intermediary YAML doc object (surgeon.data), so we mark times as special strs within surgeon.data, then do a second pass to convert them to time objects on the way out.

Parameters
surgeon:`Processor`	A YAMLPath `Processor` with existing `data` to be up-typed.
date_paths:`Sequence[str]`	YAMLPath queries indicating nodes to be up-typed to `date`/`datetime`/`time`.

Returns
`dict \| list`	A nested `dict` or `list` containing some "up-typed" (casted) items in addition to `str`s.

Raises
`ValueError`	Up-typing a `str` failed due to an unexpected format.

def _str_to_bool(informal_bool: str) -> bool: (source) ¶

Translate a commonly used boolean str into a real bool.

Parameters
informal_bool:`str`	A boolean represented as `str`, like `"true"`, `"no"`, `"off"`, etc.

Returns
`bool`	`True` or `False` to match the intent of `informal_bool`.

Raises
`ValueError`	This doesn't look like enough like a `bool` to translate.

def _str_to_datey(informal_datey: str, time_marker: str) -> date | datetime | str: (source) ¶

Translate an ISO 8601 date/time str into a date, datetime, or marked time str.

Parameters
informal_datey:`str`	An ISO 8601 date/time `str`.
time_marker:`str`	An arbitrary prefix (such as a UUID) which will be used to create a "marked time" `str`, rather than an (unyamlable) `time` instance.

Returns
`date \| datetime \| str`	A `date`, `datetime`, or marked time `str` equivalent of `informal_datey`. A marked time `str` is just ISO 8601 prefixed with `time_marker`.

Raises
`ValueError`	This doesn't look like enough like a date/time to translate.

def _str_to_num(informal_num: str) -> int | float: (source) ¶

Translate a number as str into a real int or float.

Parameters
informal_num:`str`	A number represented as `str`, like `"5.5"`, `"1e3"`, or `"0xdecaf"`

Returns
`int \| float`	An `int` or `float` equivalent of `informal_num`.

Raises
`ValueError`	This doesn't look like enough like a number to translate.