Debug Utilities

Injection

class BBInjectionUtils

Bases: object

Utilities to inject custom functionality into functions.

static inject(mod_identity, target_object, target_name, log_errors=True)

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

Example of cls usage:

# cls usage
@BBInjectionUtils.inject(ModIdentity(), SimSpawner, SimSpawner.spawn_sim.__name__)
def do_something_on_spawn_sim(original, cls, *args, **kwargs):
    return original(*args, **kwargs)
Example of self usage:

# Self usage
@BBInjectionUtils.inject(ModIdentity(), SimInfo, 'load_sim_info')
def do_something_on_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 decorated with ‘flexmethod’

  • 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.

  • Functions decorated with ‘classproperty’

  • Functions decorated with ‘staticproperty’

  • Functions decorated with ‘flexproperty’

Parameters:

  • mod_identity (BBModIdentity) – The identity of the Mod that is injecting custom code.

  • target_object (Any) – The class that contains the target function.

  • target_name (str) – The name of the function being injected to.

  • log_errors (bool, optional) – If set to True, any errors thrown by the wrapped function will be handled by your mod. If set to False, any errors thrown by the wrapped function will not be caught. Default is True.

Returns:

A wrapped function.

Return type:

Callable