Miscellaneous Utilities¶

Utilities shared across the repository.

This module groups small helpers used for exception handling, parsing, timing, interactive exploration, and light registry patterns.

Categories¶

Exception handling: UnavailableException and fatal_unavailable build consistent user-facing errors for missing registry entries.
Registry helpers: MethodCallReplicator and ClassRegister provide small reusable patterns for dispatching calls and registering classes.
Parsing helpers: parse_keyval and fullqual handle CLI-style key/value parsing and qualified-name formatting.
Timing helpers: TimedContext, onetime, localtime, deltatime_point, and deltatime_format support timing and one-shot flags.
Miscellaneous helpers: pairwise, line_maximize, interactive, and get_loaded_dependencies cover assorted convenience tasks.

Example:¶

from tools import UnavailableException, parse_keyval, TimedContext

try:
    raise UnavailableException({"a": 1, "b": 2}, "c", "option")
except UnavailableException as e:
    print(e)

args = parse_keyval(["lr:0.01", "batch:32"])
with TimedContext("my_operation"):
    pass

class tools.misc.ClassRegister(singular: str, optplural: str | None = None)[source]¶

Bases: object

Minimal registry mapping user-visible names to classes.

instantiate(name: str, *args, **kwargs) → object[source]¶

Instantiate the class registered under name.

Parameters:

name (str) – Registered class name.
*args (object) – Positional arguments forwarded to the class constructor.
**kwargs (object) – Keyword arguments forwarded to the class constructor.
Returns
-------
object – Instance of the registered class.
Raises
------
UserException – If name is not registered.

itemize() → list[str][source]¶: Return the registered class names.

register(name: str, cls: type) → None[source]¶

Parameters:

name (str) – Name used to retrieve the class.
cls (type) – Class associated with name.

class tools.misc.MethodCallReplicator(*args: object)[source]¶

Bases: object

Proxy that replicates method calls across multiple instances.

Accessing an attribute returns a callable that invokes the same named attribute on each bound instance, in order, and returns the list of results.

class tools.misc.TimedContext(*args, **kwargs)[source]¶

Bases: Context

Context manager that logs the elapsed runtime of a block.

exception tools.misc.UnavailableException(*args, **kwargs)[source]¶

Bases: UserException

User-facing exception raised when a selected registry entry is missing.

tools.misc.deltatime_format(a: int, b: int) → tuple[int, str][source]¶

Compute and format elapsed time between two captured points.

Parameters:

a (int) – Earlier point returned by deltatime_point().
b (int) – Later point returned by deltatime_point().
Returns
-------
tuple[int – Tuple (seconds, text) containing elapsed seconds and a human-readable duration string.
str] – Tuple (seconds, text) containing elapsed seconds and a human-readable duration string.

tools.misc.deltatime_point() → int[source]¶

Capture an opaque point in monotonic time.

Returns:¶

int: Monotonic timestamp rounded to seconds. The value is intended for use with deltatime_format().

tools.misc.fatal_unavailable(*args, **kwargs) → None[source]¶

Report an unavailable entry as a fatal user-facing error.

Parameters:

*args (str) – Positional arguments forwarded to make_unavailable_exception_text().
**kwargs (str) – Keyword arguments forwarded to make_unavailable_exception_text().

tools.misc.fullqual(obj: object) → str[source]¶

Return a class or instance’s fully qualified name.

Parameters:

obj (object) – Class or instance to describe.
Returns
-------
str – Fully qualified class name. Instances are prefixed with "instance of ".
Example
-------
fullqual(str) (>>>)
'builtins.str'
fullqual(pathlib.Path(".")) (>>>)
pathlib.PosixPath' ('instance of)

tools.misc.get_loaded_dependencies() → list[tuple[str, str | None, int]][source]¶

List currently loaded non-built-in root modules.

Returns:¶

list[tuple[str, str | None, int]]: Tuples of (root_module_name, version, flavor). version is the module’s __version__ attribute when present, otherwise None. flavor is one of IS_STANDARD, IS_SITE, or IS_LOCAL.

Raises:¶

RuntimeError: If Python’s site-packages locations cannot be discovered on the current platform.

tools.misc.interactive(glbs: dict[str, object] | None = None, lcls: dict[str, object] | None = None, prompt: str = '>>> ', cprmpt: str = '... ') → None[source]¶

Run a small interactive Python prompt.

Press Ctrl+D or send an equivalent EOF signal to leave the prompt.

Parameters:

glbs (dict[str, object] | None, optional) – Globals dictionary used when evaluating commands. If None, the caller’s globals are used when available.
lcls (dict[str, object] | None, optional) – Locals dictionary used when evaluating commands. If None, the caller’s locals are used when available, otherwise glbs is used.
prompt (str, optional) – Prompt displayed for a new command.
cprmpt (str, optional) – Prompt displayed while continuing a multi-line command.

tools.misc.line_maximize(scape: Callable[[...], Any], evals: int = 16, start: float = 0.0, delta: float = 1.0, ratio: float = 0.8) → float[source]¶

Best-effort argmax search for a scalar function on non-negative inputs.

The search first expands while values improve, then contracts the step size to refine the best point found within the evaluation budget.

Parameters:

scape (callable) – Function to maximize. It is called with non-negative float values and must return comparable scores.
evals (int, optional) – Maximum number of function evaluations.
start (float, optional) – Initial non-negative point to evaluate.
delta (float, optional) – Initial positive step size.
ratio (float, optional) – Step contraction ratio, expected to be between 0.5 and 1.0 excluded.
Returns
-------
float – Best point found under the evaluation budget.

tools.misc.localtime() → str[source]¶

Return the current local time formatted for logs.

Returns:¶

str: Local time as YYYY/MM/DD HH:MM:SS.

tools.misc.onetime(name: str | None = None) → tuple[Callable[[...], Any], Callable[[...], Any]][source]¶

Create or retrieve a thread-safe one-shot flag.

Parameters:

name (str | None, optional) – Optional global flag name. Reusing the same name returns the same getter/setter pair.
Returns
-------
tuple[callable – (getter, setter) pair. getter returns whether the flag has been set, and setter permanently sets it to True.
callable] – (getter, setter) pair. getter returns whether the flag has been set, and setter permanently sets it to True.

tools.misc.pairwise(data: list | tuple)[source]¶

Yield unordered pairs from an indexable collection.

Parameters:

data (list | tuple) – Indexable collection such as a list or tuple.
Yields
------
tuple – Tuples (data[i], data[j]) for every i < j.
Example
-------
list(pairwise([1 (>>>)
2
3]))
[(1
2)
(1
3)
(2
3)]
list(pairwise("ab")) (>>>)
[('a'
'b')]

tools.misc.parse_keyval(list_keyval: list[str], defaults: dict[str, object] | None = None) → dict[str, object][source]¶

Parse <key>:<value> strings into a typed dictionary.

This helper is used for command-line options such as --gar-args lr:0.01. Keys present in defaults are converted to the type of their default value; other keys are converted by parse_keyval_auto_convert().

Parameters:

list_keyval (list[str]) – Entries formatted as <key>:<value>.
defaults (dict[str, object] | None, optional) – Default key/value mappings. These defaults are also used for type inference and are copied into the returned dictionary when the corresponding key is not explicitly provided.
Returns
-------
dict[str – Parsed key/value pairs with converted values.
object] – Parsed key/value pairs with converted values.
Raises
------
UserException – If an entry is malformed, a key is provided more than once, or conversion to a default value’s type fails.
Example
-------
parse_keyval(["lr (>>>)
{'lr' (0.01, 'batch': 32})
parse_keyval(["debug (>>>)
{'debug' (True, 'workers': 4})