Types

The rite.conversion.types submodule provides helpers to convert between core Python types in a predictable, safe way.

Type Conversion Utilities

Basic Python type conversions.

This submodule provides utilities for converting between Python's built-in types: int, float, str, bool, bytes, list, dict, set, tuple.

Examples

from rite.conversion.types import ( ... types_to_int, ... types_to_bool, ... types_to_list ... ) types_to_int("42") 42 types_to_bool("yes") True types_to_list((1, 2, 3)) [1, 2, 3]

Modules

types_to_bool

Boolean Conversion

Convert values to boolean representation.

Examples

from rite.conversion.types import types_to_bool types_to_bool("yes") True types_to_bool("no") False types_to_bool(1) True

Functions

types_to_bool(x: Any, default: bool | None = None) -> bool | None

Convert a value to a boolean.

Parameters:

Name	Type	Description	Default
x	Any	Value to convert (string, number, bool, or None).	required
default	bool | None	Default value if conversion fails.	None

Returns:

Type	Description
bool | None	Boolean representation or default/None if conversion fails.

Examples:

>>> types_to_bool("yes")
True
>>> types_to_bool("no")
False
>>> types_to_bool(1)
True
>>> types_to_bool(0)
False
>>> types_to_bool(None)

>>> types_to_bool(None, False)
False
>>> types_to_bool("invalid")

>>> types_to_bool("invalid", True)
True

types_to_bytes

Bytes Conversion Module

Convert various types to bytes representation.

Examples

from rite.conversion.types import types_to_bytes types_to_bytes("hello") b'hello' types_to_bytes(42) b'42'

Functions

types_to_bytes(content: Any, *, encoding: str = 'utf-8', errors: str = 'strict', strings_only: bool = False) -> bytes | bytearray | Any

Convert content to a byte representation.

Parameters:

Name	Type	Description	Default
content	Any	Content to convert to bytes.	required
encoding	str	Character encoding to use.	'utf-8'
errors	str	Error handling scheme.	'strict'
strings_only	bool	If True, leave protected types unconverted.	False

Returns:

Type	Description
bytes | bytearray | Any	Byte representation or original if protected.

Examples:

>>> types_to_bytes("hello")
b'hello'
>>> types_to_bytes(42, strings_only=True)
42
>>> types_to_bytes(42, strings_only=False)
b'42'
>>> types_to_bytes(b"bytes")
b'bytes'

Notes

Behavior: - bytes/bytearray: returned as-is - memoryview: converted to bytes - objects with bytes: bytes(obj) - os.PathLike: os.fspath(obj) encoded - str: encoded with encoding/errors - everything else: str(obj).encode()

If strings_only=True, protected types (None, numbers) are returned unmodified.

types_to_dict

Dictionary Conversion

Convert sequences and mappings to dictionary representation.

Examples

from rite.conversion.types import types_to_dict types_to_dict([("a", 1), ("b", 2)]) {'a': 1, 'b': 2} types_to_dict({"x": 10})

Functions

types_to_dict(x: Any, key_attr: str | None = None) -> dict[Any, Any]

Convert a value to a dictionary.

Parameters:

Name	Type	Description	Default
x	Any	Value to convert (mapping, sequence of pairs, or list).	required
key_attr	str | None	Attribute name to use as key for object sequences.	None

Returns:

Type	Description
dict[Any, Any]	Dictionary representation of the value.

Raises:

Type	Description
ValueError	If conversion is not possible.

Examples:

>>> types_to_dict([("a", 1), ("b", 2)])
{'a': 1, 'b': 2}
>>> types_to_dict({"x": 10, "y": 20})
{'x': 10, 'y': 20}
>>> types_to_dict([("x", 1)])
{'x': 1}

Notes

Objects with key_attr will use obj.key_attr as dictionary key.

types_to_float

Float Conversion

Convert values to floating-point representation.

Examples

from rite.conversion.types import types_to_float types_to_float("3.14") 3.14 types_to_float(42) 42.0 types_to_float("invalid")

Functions

types_to_float(x: Any, default: float | None = None) -> float | None

Convert a value to a float.

Parameters:

Name	Type	Description	Default
x	Any	Value to convert (string, number, bool, or None).	required
default	float | None	Default value if conversion fails.	None

Returns:

Type	Description
float | None	Float representation or default/None if conversion fails.

Examples:

>>> types_to_float("3.14")
3.14
>>> types_to_float(42)
42.0
>>> types_to_float("1.5e3")
1500.0
>>> types_to_float("invalid")

>>> types_to_float("invalid", 0.0)
0.0
>>> types_to_float(True)
1.0

types_to_int

Integer Conversion

Convert values to integer representation.

Examples

from rite.conversion.types import types_to_int types_to_int("42") 42 types_to_int(3.14) 3 types_to_int("invalid")

Functions

types_to_int(x: Any, default: int | None = None) -> int | None

Convert a value to an integer.

Parameters:

Name	Type	Description	Default
x	Any	Value to convert (string, number, bool, or None).	required
default	int | None	Default value if conversion fails.	None

Returns:

Type	Description
int | None	Integer representation or default/None if conversion fails.

Examples:

>>> types_to_int("42")
42
>>> types_to_int(3.14)
3
>>> types_to_int("invalid")

>>> types_to_int("invalid", 0)
0
>>> types_to_int(True)
1

types_to_list

List Conversion

Convert values to list representation.

Examples

from rite.conversion.types import types_to_list types_to_list((1, 2, 3)) [1, 2, 3] types_to_list("hello") ['h', 'e', 'l', 'l', 'o'] types_to_list(42) [42]

Functions

types_to_list(x: Any, split_strings: bool = False) -> list[Any]

Convert a value to a list.

Parameters:

Name	Type	Description	Default
x	Any	Value to convert to list.	required
split_strings	bool	If True, strings become list of chars.	False

Returns:

Type	Description
list[Any]	List representation of the value.

Examples:

>>> types_to_list((1, 2, 3))
[1, 2, 3]
>>> types_to_list({1, 2, 3})
[1, 2, 3]
>>> types_to_list("hello", split_strings=True)
['h', 'e', 'l', 'l', 'o']
>>> types_to_list("hello", split_strings=False)
['hello']
>>> types_to_list(42)
[42]
>>> types_to_list(None)
[None]

types_to_number

Number Conversion

Parse numbers from strings including those with units or suffixes.

Examples

from rite.conversion.types import types_to_number types_to_number("45.5 %") 45.5 types_to_number("20 m") 20.0

Functions

types_to_number(x: Any, default: float | None = None) -> float | None

Parse a number from strings like '20 m', '45.5 %', '100/ha'.

Parameters:

Name	Type	Description	Default
x	Any	Value to convert (number, string, or None).	required
default	float | None	Default value if parsing fails.	None

Returns:

Type	Description
float | None	Float representation or default/None if parsing fails.

Examples:

>>> types_to_number("45.5 %")
45.5
>>> types_to_number(100)
100.0
>>> types_to_number("1.5e3")
1500.0
>>> types_to_number("invalid")

>>> types_to_number("invalid", 0.0)
0.0
>>> types_to_number("20 meters")
20.0

types_to_percentage

Percentage Conversion

Convert values to percentage (0-100 range).

Examples

from rite.conversion.types import types_to_percentage types_to_percentage(0.35) 35.0 types_to_percentage("35%") 35.0

Functions

types_to_percentage(x: Any, default: float | None = None, clamp: bool = True) -> float | None

Convert value to percentage (0-100).

Accepts 35, "35", "35%", 0.35 (interpreted as 35% if 0<=x<=1).

Parameters:

Name	Type	Description	Default
x	Any	Value to convert (number, string, or None).	required
default	float | None	Default value if conversion fails.	None
clamp	bool	If True, clamp result to 0-100 range.	True

Returns:

Type	Description
float | None	Percentage value (0.0-100.0) or default if conversion fails.

Examples:

>>> types_to_percentage(0.35)
35.0
>>> types_to_percentage("35%")
35.0
>>> types_to_percentage(150)
100.0
>>> types_to_percentage(150, clamp=False)
150.0
>>> types_to_percentage("invalid")

>>> types_to_percentage("invalid", 0.0)
0.0

types_to_set

Set Conversion

Convert iterables to set representation.

Examples

from rite.conversion.types import types_to_set types_to_set([1, 2, 2, 3]) {1, 2, 3} types_to_set("hello")

Functions

types_to_set(x: Any) -> set[Any]

Convert a value to a set.

Parameters:

Name	Type	Description	Default
x	Any	Value to convert to set (iterable or single value).	required

Returns:

Type	Description
set[Any]	Set representation of the value.

Examples:

>>> types_to_set([1, 2, 2, 3])
{1, 2, 3}
>>> types_to_set((1, 2, 3))
{1, 2, 3}
>>> types_to_set("hello")
{'h', 'e', 'l', 'o'}
>>> types_to_set(42)
{42}

Notes

Strings are treated as iterables of characters. Single values are wrapped in a set.

types_to_str

String Conversion

Convert values to string representation.

Examples

from rite.conversion.types import types_to_str types_to_str(42) '42' types_to_str([1, 2, 3]) '[1, 2, 3]' types_to_str(None) ''

Functions

types_to_str(x: Any, none_as_empty: bool = True, encoding: str = 'utf-8') -> str

Convert a value to a string.

Parameters:

Name	Type	Description	Default
x	Any	Value to convert to string.	required
none_as_empty	bool	If True, None converts to empty string.	True
encoding	str	Encoding to use for bytes objects.	'utf-8'

Returns:

Type	Description
str	String representation of the value.

Examples:

>>> types_to_str(42)
'42'
>>> types_to_str(None)
''
>>> types_to_str(None, none_as_empty=False)
'None'
>>> types_to_str(b'hello')
'hello'
>>> types_to_str([1, 2, 3])
'[1, 2, 3]'

types_to_tuple

Tuple Conversion

Convert iterables to tuple representation.

Examples

from rite.conversion.types import types_to_tuple types_to_tuple([1, 2, 3]) (1, 2, 3) types_to_tuple("hello") ('h', 'e', 'l', 'l', 'o')

Functions

types_to_tuple(x: Any) -> tuple[Any, ...]

Convert a value to a tuple.

Parameters:

Name	Type	Description	Default
x	Any	Value to convert to tuple (iterable or single value).	required

Returns:

Type	Description
tuple[Any, ...]	Tuple representation of the value.

Examples:

>>> types_to_tuple([1, 2, 3])
(1, 2, 3)
>>> types_to_tuple({1, 2, 3})
(1, 2, 3)
>>> types_to_tuple("hello")
('h', 'e', 'l', 'l', 'o')
>>> types_to_tuple(42)
(42,)

options: show_root_heading: true show_source: false heading_level: 2