fabricatio_core.utils

A collection of utility functions for the fabricatio package.

Functions

override_kwargs(→ Dict[str, Any])	Override the values in kwargs with the provided overrides.
fallback_kwargs(→ Dict[str, Any])	Fallback the values in kwargs with the provided fallbacks.
ok(→ T)	Check if a value is None and raise a ValueError with the provided message if it is.
cfg(→ None)	Configure the package based on the provided manifest and features.
build_install_msg(→ str)	Builds an installation message for missing modules with pip and uv commands.
get_source_pkgname(→ str)	Get the top-level package name from a module at the given call stack depth.
first_available(…)	Return the first available item in the iterable that's not None.
wrap_in_block(→ str)	Wraps a string in a block with a title.

Module Contents

fabricatio_core.utils.override_kwargs(kwargs: Mapping[str, Any], **overrides) → Dict[str, Any]

Override the values in kwargs with the provided overrides.

fabricatio_core.utils.fallback_kwargs(kwargs: Mapping[str, Any], **fallbacks) → Dict[str, Any]

Fallback the values in kwargs with the provided fallbacks.

fabricatio_core.utils.ok[T](val: T | None, msg: str = 'Value is None') → T

Check if a value is None and raise a ValueError with the provided message if it is.

Parameters:

• val – The value to check.

• msg – The message to include in the ValueError if val is None.

Returns:

The value if it is not None.

Return type:

T

fabricatio_core.utils.cfg(feats: Sequence[str], pkg_name: str | None = None) → None

Configure the package based on the provided manifest and features.

If any module in manifest is missing, raises ModuleNotFoundError with ready-to-run installation commands for both pip and uv.

Automatically converts ‘_’ to ‘-’ in package name to match PyPI naming convention.

Example

Missing dependencies. Please install with:

pip install my-novel-pkg[workflow,debug] uv add “my-novel-pkg[workflow,debug]”

Parameters:

• feats – Extra feature names required (e.g., [“workflow”, “debug”]).

• pkg_name – Optional package name, defaults to detected source package name

Raises:

ModuleNotFoundError – If any module is not found.

fabricatio_core.utils.build_install_msg(feats: Iterable[str], pkg: str | None = None) → str

Builds an installation message for missing modules with pip and uv commands.

Parameters:

• feats – Iterable of feature names required

• pkg – Optional package name, defaults to detected source package name

Returns:

Formatted error message with installation instructions for both pip and uv

Return type:

str

fabricatio_core.utils.get_source_pkgname(depth: int = 2) → str

Get the top-level package name from a module at the given call stack depth.

Attempts to automatically detect the package name by inspecting the caller’s module information at the specified depth. Converts underscores to hyphens to match PyPI naming convention. Returns ‘unknown’ if package name cannot be determined.

Parameters:

depth (int) – The number of frames to go back in the call stack. Depth 1 means the immediate caller, 2 is the caller’s caller, etc. Must be >= 1.

Returns:

The detected top-level package name or ‘unknown’ as fallback.

Return type:

str

fabricatio_core.utils.first_available[T](iterable: Iterable[T | None]) → T

fabricatio_core.utils.first_available(iterable: Iterable[T | None], *, raise_exception: Literal[True, False] = False) → T | None

fabricatio_core.utils.first_available(iterable: Iterable[T | None], msg: str = 'No available item found in the iterable.', *, raise_exception: Literal[True, False] = True) → T

Return the first available item in the iterable that’s not None.

This function searches through the provided iterable and returns the first item that is not None. If all items are None or the iterable is empty, it raises a ValueError.

Parameters:

• iterable – The iterable collection to search through.

• msg – The message to include in the ValueError if no non-None item is found.

• raise_exception – If True, raises a ValueError if no non-None item is found.

Returns:

The first non-None item found in the iterable. If no non-None item is found, it raises a ValueError.

Return type:

T

Raises:

ValueError – If no non-None item is found in the iterable.

Examples

>>> first_available([None, None, "value", "another"])
'value'
>>> first_available([1, 2, 3])
1
>>> assert (first_available([None, None]))
ValueError: No available item found in the iterable.

fabricatio_core.utils.wrap_in_block(string: str, title: str, style: str = '-') → str

Wraps a string in a block with a title.

Parameters:

• string – The string to wrap.

• title – The title of the block.

• style – The style of the block.

Returns:

The wrapped string.

Return type:

str