Skip to content

Utils

rn_forge.commons.lang.utils

Value, dynamic-import, diff, and base64 helpers.

AppUtils

General-purpose value and import utilities.

get_or_default(value, default=None) staticmethod

Return value if it is not empty, otherwise default.

Uses :meth:is_empty to test emptiness.

import_string(qualname, package=None) staticmethod

Import and return an object by its fully-qualified dotted name.

Accepts pkg.mod:attr and pkg.mod.attr forms. A leading . performs a relative import and requires package.

Parameters:

Name Type Description Default
qualname str

Dotted (or pkg.mod:attr) path to the target, e.g. "os.path.join" or ".submodule.MyClass" for relative imports.

required
package str | None

Required when qualname starts with "." (relative import). Defaults to None.

None

Returns:

Type Description
Any

The imported object (function, class, constant, etc.).

Raises:

Type Description
ImportError

If qualname is malformed, the module cannot be imported, or the attribute does not exist on the module.

Example::

join = AppUtils.import_string("os.path.join")
join("/tmp", "file.txt")  # "/tmp/file.txt"

is_empty(value) staticmethod

Return True when value is considered empty.

Rules:

  • None → True
  • numbers and booleans → always False
  • strings → True when blank (whitespace-only)
  • sequences and mappings → True when len == 0
  • other objects → bool(value) inverted

join_string(separator, *values) staticmethod

Join values into a string using separator.

If a single non-string sequence is passed it is transparently unpacked, so both AppUtils.join_string(",", 1, 2, 3) and AppUtils.join_string(",", [1, 2, 3]) produce the same output.

Returns an empty string when no values are supplied.

null_safe_attrgetter(*paths, default=None) staticmethod

Return a callable that safely retrieves one or more attributes.

Wraps :func:operator.attrgetter, returning default instead of raising :exc:AttributeError when any attribute in the path is absent.

Parameters:

Name Type Description Default
*paths str

Attribute paths forwarded to :func:operator.attrgetter, e.g. "user.profile.email".

()
default Any

Value returned when any attribute in any path is missing. Defaults to None.

None

Returns:

Type Description
Callable[[Any], Any]

A callable getter(obj) that returns the attribute value (or a

Callable[[Any], Any]

list of values when multiple paths are given), or default on

Callable[[Any], Any]

exc:AttributeError.

Example::

get_email = AppUtils.null_safe_attrgetter("profile.email")
get_email(user)  # "alice@example.com" or None

parse_bool(value, *, strict=True) staticmethod

Convert a value to bool using common truthy/falsy string tokens.

Recognises (case-insensitive):

  • Truthy: "true", "yes", "y", "on", "1", "enabled"
  • Falsy: "false", "no", "n", "off", "0", "disabled", "none"

Parameters:

Name Type Description Default
value Any

The value to convert. bool instances are returned unchanged without any string conversion.

required
strict bool

When True (default), raise :exc:ValueError for unrecognised strings. When False, return None instead.

True

Returns:

Type Description
bool | None

True, False, or None (only possible when

bool | None

strict=False).

Raises:

Type Description
ValueError

If value does not match any recognised token and strict=True.

Example::

AppUtils.parse_bool("yes")      # True
AppUtils.parse_bool("DISABLED") # False
AppUtils.parse_bool("maybe", strict=False)  # None

unified_diff(expected, actual, *, expected_name='expected', actual_name='actual') staticmethod

Return a unified diff between expected and actual, or "" if equal.

The empty-string-for-equal-inputs contract is deliberate: callers use it to decide "did anything change" without a separate equality check.

Parameters:

Name Type Description Default
expected str

The baseline text.

required
actual str

The text being compared against expected.

required
expected_name str

Label for expected in the diff header.

'expected'
actual_name str

Label for actual in the diff header.

'actual'

Returns:

Type Description
str

A conventional unified diff string, or "" when expected and

str

actual are identical.

Base64

Base64 utilities accepting str or bytes input.

decode(value) staticmethod

Return the raw bytes decoded from the base64 value.

decode_to_string(value, encoding='utf-8') staticmethod

Decode the base64 value and return it as a string.

encode(value) staticmethod

Return the base64-encoded string for value.