launch.utilities.type_utils module

Module that implements type coercion and checking utilities.

launch.utilities.type_utils.AllowedTypesTuple = (<class 'int'>, <class 'float'>, <class 'bool'>, <class 'str'>, typing.List[int], typing.List[float], typing.List[bool], typing.List[str]): Allowed scalar types.

launch.utilities.type_utils.AllowedTypesType

Allowed scalar values.

launch.utilities.type_utils.AllowedValueType

Substitution to a scalar type or a scalar type.

launch.utilities.type_utils.ListTypesType

Allowed types.

alias of Type[List[int] | List[float] | List[bool] | List[str]]

launch.utilities.type_utils.ListValueType

Allowed uniform sequence values.

alias of List[int] | List[float] | List[bool] | List[str]

launch.utilities.type_utils.NormalizedScalarType

Normalized version of SomeSequenceType.

alias of List[Substitution] | int | float | bool | str

launch.utilities.type_utils.NormalizedSequenceType

Normalized version of SomeValueType.

launch.utilities.type_utils.NormalizedValueType

String embedded substitution version of SomeScalarType

launch.utilities.type_utils.ScalarTypesTuple = (<class 'int'>, <class 'float'>, <class 'bool'>, <class 'str'>): Tuple of valid list types.

launch.utilities.type_utils.ScalarTypesType

Allowed uniform list types.

alias of Type[int | float | bool | str]

launch.utilities.type_utils.ScalarValueType

Allowed uniform list values.

alias of int | float | bool | str

launch.utilities.type_utils.SequenceValueType

Allowed values.

alias of Sequence[int] | Sequence[float] | Sequence[bool] | Sequence[str]

launch.utilities.type_utils.SomeScalarType

Substitution that can be performed to a uniform list.

launch.utilities.type_utils.SomeSequenceType

Union of SomeScalarType and SomeSequenceType.

launch.utilities.type_utils.SomeValueType

Normalized version of SomeScalarType.

launch.utilities.type_utils.StrSomeScalarType

String embedded substitution version of SomeSequenceType

launch.utilities.type_utils.StrSomeSequenceType

String embedded substitution version of SomeValueType

alias of Sequence[int | str] | Sequence[float | str] | Sequence[bool | str] | Sequence[str]

Coerce a list of strings to a list of scalars.

Parameters:

value – list of strings to be coerced.
data_type – value will be coerced to data_type.
can_be_str – if True, strings will be kept in case coercion fails. launch.frontend makes use of this for string embedded substitutions.

Raise:

ValueError if the coercion failed.

Raise:

TypeError if value is not a list of str.

Returns:

value coerced to data_type.

Coerce value type to data_type.

Parameters:

value – string to be coerced.
data_type – value will be coerced to data_type.
can_be_str – if True, the result will be kept as an string if it cannot be coerced. In the case of lists, it will also accept strings as items. launch.frontend makes use of this for string embedded substitutions.

Raise:

ValueError if the coercion failed or data_type is invalid.

Raise:

TypeError if value is not a str.

Returns:

value coerced to data_type.

Extract type information from type object.

Parameters:: data_type – It can be: - a scalar type i.e. str, int, float, bool; - a uniform list i.e List[str], List[int], List[float], List[bool];
Returns:: a tuple (type_obj, is_list). is_list is True for the supported list types, if not is False. type_obj is the object representing that type in Python. In the case of a list, it’s the type of the items. e.g.: data_type = List[int] -> (int, True) data_type = bool -> (bool, False)

Try to convert value to the type specified in data_type.

Parameters:

value – string or list of strings to be coerced.
data_type – value will be coerced to data_type.
can_be_str – if True, strings will be kept in case coercion fails. In the case of lists, it will also accepts strings as items. launch.frontend makes use of this for string embedded substitutions.

Raise:

ValueError if the coercion failed.

Raise:

TypeError if value is a list and data_type is not a typing.List[x] object.

Raise:

TypeError if value is neither a str of a list of str.

Returns:

value coerced to data_type.

Check if value is instance of data_type.

Parameters:

value – variable to check.
data_type – type that value should be an instance of. When None the function behaves like is_instance_of_valid_type().
can_be_str – if True, strings will also be accepted. launch.frontend makes use of this for string embedded substitutions.

Raise:

ValueError if data_type is invalid.

Returns:

True if value is an instance of data_type, else False.

launch.utilities.type_utils.is_instance_of_valid_type(value: Any, *, can_be_str: bool = False) → bool[source]

Return True if value is an instance of an allowed type.

See AllowedTypesTuple definition for further reference.

Parameters:

value – variable to be checked.
can_be_str – when True, non-uniform lists mixed with strings are allowed.

Returns:

True when value is an instance of a valid type, False if not.

launch.utilities.type_utils.is_normalized_substitution(x)[source]

Return True if x is a normalized substitution.

A normalized substitution is a list with launch.Substitution instances as items.

launch.utilities.type_utils.is_substitution(x)[source]

Return True if x is some substitution.

This can be: - A launch.Substitution instance. - A list of mixed launch.Substitution and str instances, with at least one instance of the former.

launch.utilities.type_utils.is_typing_list(data_type: Any) → bool[source]

Return True if data_type is typing.List or a subscription of it.

Examples

assert is_typing_list(typing.List)
assert is_typing_list(typing.List[int])
assert not is_typing_list(int)

Return True if data_type is an instance of a valid scalar type.

See ScalarTypesTuple for further reference.

Normalize a mix of substitution and values.

This function becomes handy when you need a substitution whose result will be coerced to a specific type.

Example:

class MyAction(Action):
    def __init__(self, my_int: Union[int, SomeSubstitutionsType]):
        self.__my_int_normalized = normalize_typed_substitution(some_int, int)
        ...

    def execute(self, context):
        my_int = perform_typed_substitution(context, self.__my_int_normalized, int)
        ...

List of substitutions coerced a list to strings can be confused with a single substitution that is coerced to a list of strings. e.g.: [‘asd’, TextSubstitution(text=’bsd’)] To avoid confusions, the passed value will always be interpreted as a single substitution if possible, like in the above example (which will resolved to ‘asdbsd’). To make it a list of substitutions: [‘asd’, [TextSubstitution(text=’bsd’)]]

param value:: value to be normalized.
param data_type:: value can be either an instance of data_type or a substitution. In the case of lists, value can be either a substitution or a list. In the later case, its items should match the type specified by data_type or be a substitution. If None, it should be possible to perform the resulting normalized value to a valid type. See is_substitution().
return:: the normalized value.
raise:: TypeError if the normalized value cannot later be resolved to an instance of data_type, or to a valid type when data_type is `None.
raise:: ValueError if data_type is not valid. See AllowedTypesTuple.

Perform a normalized typed substitution.

This function becomes handy when you need a substitution whose result will be coerced to a specific type.

See normalize_typed_substitution for an example.

Parameters:

context – A launch.LaunchContext instance. It will be used to perform the substitutions in value, if there are any.
value – normalized typed substitution to be performed.
data_type – The return value will satisfy is_instance_of(output) == True. If after trying to coerce the performed substitution that isn’t achieved, ValueError is raised. See is_instance_of().

Returns:

the result of performing all the substitutions in value and coercing the result.

Raise:

TypeError if the normalized value cannot later be resolved to an instance of data_type, or to a valid type when data_type is `None.

Raise:

ValueError if data_type is not valid. See AllowedTypesTuple.

Raise:

ValueError if after coercing the substitutions the end result is not of the expected type.