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 |
required |
package
|
str | None
|
Required when qualname starts with |
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 →
Truewhen blank (whitespace-only) - sequences and mappings →
Truewhenlen == 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: |
()
|
default
|
Any
|
Value returned when any attribute in any path is missing.
Defaults to |
None
|
Returns:
| Type | Description |
|---|---|
Callable[[Any], Any]
|
A callable |
Callable[[Any], Any]
|
list of values when multiple paths are given), or default on |
Callable[[Any], Any]
|
exc: |
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. |
required |
strict
|
bool
|
When |
True
|
Returns:
| Type | Description |
|---|---|
bool | None
|
|
bool | None
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If value does not match any recognised token and
|
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 |
str
|
actual are identical. |
Base64
¶
Base64 utilities accepting str or bytes input.