corelay.utils

A module containing utility classes and functions for CoRelAy. This includes as an enhanced zip() function, which ensures that the sequences being zipped are of equal length. Furthermore, this module contains functions for getting the representations of runtime objects like functions, methods, classes, and lambda expressions and conditional import functions, which return dummy functions, classes, or modules that raise an error when called or accessed, indicating how to install the missing dependencies for the functionality to work.

Functions

`dummy_from_module_import`	Creates a stub function that raises an error when called.
`dummy_import_module`	Creates a stub class that raises an error when any of its attributes are accessed and returns an instance of it.
`get_fully_qualified_name`	Returns the fully qualified name of the object, which is the module name and the name of the object.
`get_lambda_expression_source_code`	Returns the source code of the specified lambda expression if possible.
`get_object_representation`	Returns a `str` representation of the object, which depends on the type of the object.
`import_or_stub`	Tries to import a module, or types and/or functions from a module.
`zip_equal`	Zips the positional arguments, but only if they are of equal length.

corelay.utils.zip_equal(*args: Iterable[Any]) → Iterator[tuple[Any, ...]][source]

Zips the positional arguments, but only if they are of equal length.

Parameters:: *args (Iterable[Any]) – The iterables that are to be zipped. They must be of equal length.
Raises:: TypeError – The positional arguments have different lengths.
Yields:: tuple[typing.Any, …] – Yields the zipped elements of the positional arguments.
Return type:: Iterator[tuple[Any, …]]

corelay.utils.get_lambda_expression_source_code(lambda_expression: Callable[[...], Any]) → str[source]

Returns the source code of the specified lambda expression if possible. This is done by retrieving the source code of the lambda expression and parsing it into an abstract syntax tree (AST). The AST node that represents the lambda expression is then used to retrieve the source code of the lambda expression.

Note

This function was adapted from the original implementation by Karol Kuczmarski, outline in their blog post Source code of a Python lambda. The code was published as a Gist on GitHub and was published under the Creative Commons Attribution-ShareAlike 4.0 International License. The original code was modified to fit the coding style of this project and to return the representation of the passed object instead of None if the source code cannot be retrieved.

Parameters:: lambda_expression (Callable[..., Any]) – The lambda expression for which the source code is to be returned.
Returns:: Returns the source code of the lambda expression if possible, otherwise the representation of the object is returned.
Return type:: str

corelay.utils.get_object_representation(obj: Any) → str[source]

Returns a str representation of the object, which depends on the type of the object. If the object is a type, module, function or method, then its name is returned, if the object is a lambda expression, then its source code is returned, otherwise the str representation of the object is returned.

Parameters:: obj (Any) – The object for which the str representation is to be returned.
Returns:: Returns a str representation of the object.
Return type:: str

corelay.utils.get_fully_qualified_name(obj: Any) → str[source]

Returns the fully qualified name of the object, which is the module name and the name of the object.

Parameters:: obj (Any) – The object for which the fully qualified name is to be returned. If the object is a type, then the fully-qualified name of the type is returned, otherwise the fully-qualified name of the class of the object is returned.
Returns:: Returns the fully qualified name of the object.
Return type:: str

corelay.utils.dummy_from_module_import(module_name: str) → Callable[[...], Any][source]

Creates a stub function that raises an error when called. This is used to replace an actual import of a type or function from a module, like from module import type or from module import function, of a package that has not been installed. It is useful for optional dependencies of a package, because the retrieved function will raise an exception that tells the user how to install the missing dependencies for the functionality to work. It does not matter if the user meant to import a function or a type, as types are also callable (i.e., if a type is called, then an instance of the type is created and the constructor __init__ of that type is called) and invoking a function is syntactically indistinguishable from instantiating an instance of a type. If the user meant to import a function, then the exception will be raised when the function is called. If the user meant to import a type, then the exception will be raised when the user tries to instantiate an instance of the type.

Parameters:: module_name (str) – The name of the module from which the type or function that is to be replaced was imported.
Returns:: Returns a function that raises an error when called, which instructs the user on how to install the missing dependencies.
Return type:: Callable[…, Any]

corelay.utils.dummy_import_module(module_name: str) → Any[source]

Creates a stub class that raises an error when any of its attributes are accessed and returns an instance of it. This is used to replace an actual import of a module, like import module, of a package that has not been installed. It is useful for optional dependencies of a package, because the retrieved object will raise an exception that tells the user how to install the missing dependencies for the functionality to work. It does not matter that the user meant to import a module and not a class, as accessing a module’s members is syntactically indistinguishable from accessing a class’s attributes. So of the user imported a module, the exception will be raised when the user tries to access any of the module’s members.

Parameters:: module_name (str) – The name of the module that is to be replaced.
Returns:: Returns an instance of a class that raises an error when any of its attributes are accessed, which instructs the user on how to install the missing dependencies.
Return type:: Any

corelay.utils.import_or_stub(module_name: str) → ModuleType[source]

corelay.utils.import_or_stub(module_name: str, type_and_function_names: str) → type[Any] | Callable[[...], Any]

corelay.utils.import_or_stub(module_name: str, type_and_function_names: tuple[str, ...]) → list[type | Callable[[...], Any]]

Tries to import a module, or types and/or functions from a module. If the import fails, the requested module, or types and/or functions are replaced with dummies that will raise an exception when used. This is useful for optional dependencies of a package, because the retrieved module, or types and/or functions will raise an exception that tells the user how to install the missing dependencies for the functionality to work.

Parameters:

module_name (str) – The name of the module that is to be imported or from which the specified types and/or functions are to be imported.
type_and_function_names (str | tuple[str, ...] | None) – The names of the types and/or functions that are to be imported from the module, e.g., ‘function’ or (‘function’, ‘type’). If this argument is not provided, the entire module is imported. If the module, or the types and/or functions cannot be imported, dummies will be returned that will raise an exception when used. Defaults to None.

Raises:

ImportError – If a type or function cannot be imported from a module that is installed, an ImportError is raised. This is done, instead of stubbing the imported type or function, because this always indicates a bug in the code and cannot be fixed by the user installing a missing dependency.

Returns:

Returns the imported module, or types and/or functions that were imported from the module. If the import of the module fails, dummies for the module, or types and/or functions are returned that will raise an exception when used, telling the user how to install the missing dependencies.

Return type:

types.ModuleType | type[Any] | Callable[…, Any] | list[type | Callable[…, Any]]