Skip to content

Reflection

rn_forge.commons.lang.reflection

Reflection helpers for fully-qualified names, error messages, and argument inspection.

Provides: ReflectUtils: Static utilities for inspecting callables, resolving fully-qualified names, formatting error messages, and reading variable values from stack frames.

Typical usage::

from rn_forge.commons.lang.reflection import ReflectUtils

fqn = ReflectUtils.get_fully_qualified_name(MyClass)
# "mypackage.module.MyClass"

ReflectUtils

Reflection helpers for human-readable names and arguments.

Example::

from rn_forge.commons.lang.reflection import ReflectUtils

fqn = ReflectUtils.get_fully_qualified_name(ValueError("oops"))
# "builtins.ValueError"

get_error_message(error) staticmethod

Return a formatted error string of the form "<FQN> -> <str(error)>".

Parameters:

Name Type Description Default
error Exception

The exception instance to format.

required

Returns:

Type Description
str

A string combining the fully-qualified class name and the exception

str

message, separated by ->.

Example::

ReflectUtils.get_error_message(ValueError("bad input"))
# "builtins.ValueError -> bad input"

get_fully_qualified_name(target) staticmethod

Return the fully-qualified module.qualname for a type, function, instance, or frame.

For a :class:types.FrameType the result is <module>.<co_qualname>. For all other objects the containing module and __qualname__ of the type (or the object itself, if it is a class or function) are joined with a ".".

Parameters:

Name Type Description Default
target Any

A class, function, object instance, or :class:types.FrameType.

required

Returns:

Type Description
str

A dotted string of the form "module.QualifiedName".

Example::

ReflectUtils.get_fully_qualified_name(int)
# "builtins.int"

inspect_method_arguments(method, method_args, method_kwargs, exclude=None, include=None) staticmethod

Return ["param=value", ...] for the arguments bound to method.

self and cls are excluded by default unless listed in include. Intended for audit logging and debug output — do not use to drive program logic.

Parameters:

Name Type Description Default
method Callable[..., Any]

The callable whose signature is used for binding.

required
method_args tuple[Any, ...]

Positional arguments to bind.

required
method_kwargs dict[str, Any]

Keyword arguments to bind.

required
exclude list[str] | None

Additional parameter names to suppress from output.

None
include list[str] | None

When provided, only these parameter names are included, overriding the default self/cls exclusion.

None

Returns:

Type Description
list[str]

A list of "name=value" strings for each included bound argument.

Example::

def greet(self, name: str, greeting: str = "Hello") -> str: ...

ReflectUtils.inspect_method_arguments(
    greet, (obj, "World"), {}, exclude=["greeting"]
)
# ["name='World'"]

inspect_variables(var_names, source_frame=None) staticmethod

Return ["name=value", ...] for comma-separated var_names resolved in a frame.

Dot-notation is supported for attribute access (e.g. "obj.attr"). When a dotted path ends in a callable attribute, it is called with no arguments and the return value is used.

Parameters:

Name Type Description Default
var_names str

Comma-separated variable names, optionally with dot-notation for attribute traversal (e.g. "req.method").

required
source_frame FrameType | None

The stack frame whose locals are searched. Defaults to the immediate caller's frame when None.

None

Returns:

Type Description
list[str]

A list of "name=value" strings. Returns an empty list when no

list[str]

frame can be resolved.

Example::

x = 42
ReflectUtils.inspect_variables("x")
# ["x=42"]

ReflectUtils.inspect_variables("request.method, user.email")