msticpy.common.utility.types module

Utility classes and functions.

class msticpy.common.utility.types.ImportPlaceholder(name: str, required_pkgs: list[str])

Bases: object

Placeholder class for optional imports.

Initialize class with imported item name and reqd. packages.

class msticpy.common.utility.types.ParseableEnum

Bases: object

Mix-in class for parseable Enum sub-classes.

parse(value: str) → Enum | None

Return enumeration matching (case-insensitive) string value.

class msticpy.common.utility.types.SingletonArgsClass(wrapped_cls: type[Any])

Bases: SingletonClass

SingletonArgs decorator class.

Notes

Using this decorator on a class enforces the following behavior:

  • First instantiation of class will work as normal

  • Subsequent attempts with the same set/values of kwargs will just return the original class

  • Instantiation of the class with a different set of kwargs will instantiate a new class.

  • The class method current() will always return the last instance of the class.

Instantiate the class wrapper.

current() → object

Return the current instance of the wrapped class.

class msticpy.common.utility.types.SingletonClass(wrapped_cls: type[Any])

Bases: object

Singleton decorator class.

Notes

Using this decorator on a class enforces the following behavior:

  • First instantiation of class will work as normal

  • Subsequent attempts with the same set/values of kwargs will just return the original class

  • The class method current() will always return the last instance of the class.

Instantiate the class wrapper.

current() → object

Return the current instance of the wrapped class.

msticpy.common.utility.types.arg_to_list(arg: str | list[str], delims: str = ',; ') → list[str]

Convert an optional list/str/str with delims into a list.

Parameters:

  • arg (Union[str, list[str]]) – A string, delimited string or list

  • delims (str, optional) – The default delimiters to use, by default “,; “

Returns:

List of string components

Return type:

list[str]

Raises:

TypeError – If arg is not a string or list

msticpy.common.utility.types.check_kwarg(arg_name: str, legal_args: list[str]) → None

Check argument names against a list.

Parameters:

  • arg_name (str) – Argument to check

  • legal_args (list[str]) – List of possible arguments.

Raises:

NameError – If the argument is not legal. If the arg_name is a close match to one or more, legal_args these are returned in the exception.

msticpy.common.utility.types.check_kwargs(supplied_args: dict[str, Any], legal_args: list[str]) → None

Check all kwargs names against a list.

Parameters:

  • supplied_args (dict[str, Any]) – Arguments to check

  • legal_args (list[str]) – List of possible arguments.

Raises:

NameError – If any of the arguments are not legal. If the an arg is a close match to one or more legal_args, these are returned in the exception.

msticpy.common.utility.types.checked_kwargs(legal_args: Iterable[str])

Decorate function to check kwargs names against legal arg names.

Parameters:

legal_args (Iterable[str]) – Iterable of possible arguments.

Raises:

NameError – If any of the arguments are not legal. If the an arg is a close match to one or more legal_args, these are returned in the exception.

Notes

The checking is done against the union of legal_args and any named arguments of the wrapped function.

msticpy.common.utility.types.collapse_dicts(*dicts: dict) → dict

Merge multiple dictionaries - later dicts have higher precedence.

msticpy.common.utility.types.enum_parse(enum_cls: type[EnumT], value: str) → EnumT | None

Try to parse a string value to an Enum member.

Parameters:

  • enum_cls (EnumType) – The Enum type to check against

  • value (str) – The enum value to parse

Returns:

The enumeration value matching value or None

Return type:

Optional[EnumType]

Raises:

TypeError – If something other than an Enum subclass is passed.

msticpy.common.utility.types.export(obj: type[T]) → type[T]
msticpy.common.utility.types.export(obj: Callable) → Callable

Decorate function or class to export to __all__.

msticpy.common.utility.types.singleton(cls: type) → Callable

Class decorator for singleton classes.