Injection

Injection Utils

class CommonInjectionUtils

Bases: object

Utilities to inject custom functionality into functions.

static inject_and_print_arguments(mod_identity, target_object, target_function_name, log, log_stack_trace=False, handle_exceptions=True)

A decorator used to inject code into a function and print any arguments or keyword arguments passed to it.

Note

See documentation of inject_safely_into() for more details about the arguments and keyword arguments.

Example of cls usage:  

# cls usage
@CommonInjectionUtils.inject_and_print_arguments(ModInfo.get_identity(), SimSpawner, SimSpawner.spawn_sim._name__)

Example of self usage:  

# Self usage
@CommonInjectionUtils.inject_safely_into(ModInfo.get_identity(), SimInfo, SimInfo.load_sim_info.__name__)
def do_custom_load_sim_info(original, self, *args, **kwargs):
    return original(self, *args, **kwargs)

Note

Injection WILL work on

• Functions decorated with ‘property’
• Functions decorated with ‘classmethod’
• Functions decorated with ‘staticmethod’
• Functions with ‘cls’ or ‘self’ as the first argument.

Note

Injection WILL NOT work on

• Global functions, i.e. Functions not contained within a class.
• Global variables, i.e. Variables not contained within a class or function.

Parameters:

• mod_identity (CommonModIdentity) – The identity of the Mod that is injecting custom code.
• target_object (Any) – The class that contains the target function.
• target_function_name (str) – The name of the function being injected to.
• log (CommonLog) – The log being printed to when the injected function is invoked. The arguments and keyword arguments sent to the function will be printed.
• log_stack_trace (bool, optional) – If True, the stack trace will be logged in addition to the arguments and keyword arguments. If False, the stack trace will not be logged. Default is False.
• handle_exceptions (bool, optional) – If set to True, any exceptions thrown by the wrapped function will be handled. If set to False, any exceptions thrown by the wrapped function will not be caught. Default is True.

Returns:

A wrapped function.

Return type:

Callable

static inject_into(target_object, target_function_name)

Warning

This function is DEPRECATED. Use inject_safely_into() instead.

static inject_safely_into(mod_identity, target_object, target_function_name, handle_exceptions=True)

A decorator used to inject code into a function. It will run the original function should any problems occur. If handle_exceptions is True, it will catch and log exceptions.

Example of cls usage:  

# cls usage
@CommonInjectionUtils.inject_safely_into(ModInfo.get_identity(), SimSpawner, SimSpawner.spawn_sim._name__)
def do_custom_spawn_sim(original, cls, *args, **kwargs):
    return original(*args, **kwargs)

Example of self usage:  

# Self usage
@CommonInjectionUtils.inject_safely_into(ModInfo.get_identity(), SimInfo, SimInfo.load_sim_info.__name__)
def do_custom_load_sim_info(original, self, *args, **kwargs):
    return original(self, *args, **kwargs)

Note

Injection WILL work on

• Functions decorated with ‘property’
• Functions decorated with ‘classmethod’
• Functions decorated with ‘staticmethod’
• Functions with ‘cls’ or ‘self’ as the first argument.

Note

Injection WILL NOT work on

• Global functions, i.e. Functions not contained within a class.
• Global variables, i.e. Variables not contained within a class or function.

Parameters:

• mod_identity (CommonModIdentity) – The identity of the Mod that is injecting custom code.
• target_object (Any) – The class that contains the target function.
• target_function_name (str) – The name of the function being injected to.
• handle_exceptions (bool, optional) – If set to True, any exceptions thrown by the wrapped function will be handled. If set to False, any exceptions thrown by the wrapped function will not be caught. Default is True.

Returns:

A wrapped function.

Return type:

Callable

static inject_safely_into_function(mod_identity, target_object, target_function_name, callback, replace_return=False, handle_exceptions=True)

A decorator used to inject code into a function. It will run the original function should any problems occur. If handle_exceptions is True, it will catch and log exceptions.

Example of cls usage:  

# cls usage
@CommonInjectionUtils.inject_safely_into(ModInfo.get_identity(), SimSpawner, SimSpawner.spawn_sim._name__)
def do_custom_spawn_sim(original, cls, *args, **kwargs):
    return original(*args, **kwargs)

Example of self usage:  

# Self usage
@CommonInjectionUtils.inject_safely_into(ModInfo.get_identity(), SimInfo, SimInfo.load_sim_info.__name__)
def do_custom_load_sim_info(original, self, *args, **kwargs):
    return original(self, *args, **kwargs)

Note

Injection WILL work on

• Functions decorated with ‘property’
• Functions decorated with ‘classmethod’
• Functions decorated with ‘staticmethod’
• Functions with ‘cls’ or ‘self’ as the first argument.

Note

Injection WILL NOT work on

• Global functions, i.e. Functions not contained within a class.
• Global variables, i.e. Variables not contained within a class or function.

Parameters:

• mod_identity (CommonModIdentity) – The identity of the Mod that is injecting custom code.
• target_object (Any) – The class that contains the target function.
• target_function_name (str) – The name of the function being injected to.
• callback (Callable[.., Any]) – When the injected function is invoked, this callback will be invoked.
• replace_return (bool, optional) – If True, the returned result of the callback argument will replace the returned result of the original function. If False, the callback will be invoked, but the result of invoking the original function will be returned. Default is False.
• handle_exceptions (bool, optional) – If set to True, any exceptions thrown by the wrapped function will be handled. If set to False, any exceptions thrown by the wrapped function will not be caught. Default is True.

Returns:

A wrapped function.

Return type:

Callable