dlgforge.utils

Public exports for utility helpers.

env_flag(name, default=False)

Env flag.

Parameters:

Name	Type	Description	Default
name	str	str value used by this operation.	required
default	bool	bool value used by this operation.	False

Returns:

Name	Type	Description
bool	bool	Boolean indicator describing the evaluated condition.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - May read environment variables or mutate process-level runtime state.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.env import env_flag
>>> env_flag(...)

env_float(name, default)

Env float.

Parameters:

Name	Type	Description	Default
name	str	str value used by this operation.	required
default	float	float value used by this operation.	required

Returns:

Name	Type	Description
float	float	Value produced by this API.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - May read environment variables or mutate process-level runtime state.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.env import env_float
>>> env_float(...)

env_int(name, default)

Env int.

Parameters:

Name	Type	Description	Default
name	str	str value used by this operation.	required
default	int	int value used by this operation.	required

Returns:

Name	Type	Description
int	int	Value produced by this API.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - May read environment variables or mutate process-level runtime state.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.env import env_int
>>> env_int(...)

load_dotenv_files(project_root)

Load dotenv files.

Parameters:

Name	Type	Description	Default
project_root	Path	Resolved project directory context.	required

Returns:

Name	Type	Description
None	None	No value is returned.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - May read environment variables or mutate process-level runtime state.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.env import load_dotenv_files
>>> load_dotenv_files(...)

extract_json_object(text)

Extract json object.

Parameters:

Name	Type	Description	Default
text	str	Input text.	required

Returns:

Type	Description
Optional[Dict[str, Any]]	Optional[Dict[str, Any]]: Value produced by this API.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - Primarily performs in-memory transformations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.json import extract_json_object
>>> extract_json_object(...)

parse_json_object(text)

Parse json object.

Parameters:

Name	Type	Description	Default
text	str	Input text.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Value produced by this API.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - Primarily performs in-memory transformations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.json import parse_json_object
>>> parse_json_object(...)

strip_code_fences(text)

Strip code fences.

Parameters:

Name	Type	Description	Default
text	str	Input text.	required

Returns:

Name	Type	Description
str	str	Value produced by this API.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - Primarily performs in-memory transformations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.json import strip_code_fences
>>> strip_code_fences(...)

setup_logging(logs_dir, level=logging.INFO)

Setup logging.

Parameters:

Name	Type	Description	Default
logs_dir	Path	Path value used by this operation.	required
level	int	int value used by this operation.	INFO

Returns:

Name	Type	Description
None	None	No value is returned.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - May read environment variables or mutate process-level runtime state.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.logging import setup_logging
>>> setup_logging(...)

deep_merge(base, override)

Deep merge.

Parameters:

Name	Type	Description	Default
base	Dict[str, Any]	Dict[str, Any] value used by this operation.	required
override	Dict[str, Any]	Dict[str, Any] value used by this operation.	required

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Value produced by this API.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - Primarily performs in-memory transformations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.merge import deep_merge
>>> deep_merge(...)

resolve_path(path, project_root, config_dir=None)

Resolve path from configuration.

Parameters:

Name	Type	Description	Default
path	str	Filesystem path used by this operation.	required
project_root	Path	Resolved project directory context.	required
config_dir	Optional[Path]	Resolved project directory context.	None

Returns:

Type	Description
Optional[Path]	Optional[Path]: Resolved value after applying defaults and normalization rules.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - Primarily performs in-memory transformations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.merge import resolve_path
>>> resolve_path(...)

hash_text(text)

Hash text.

Parameters:

Name	Type	Description	Default
text	str	Input text.	required

Returns:

Name	Type	Description
str	str	Value produced by this API.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - Primarily performs in-memory transformations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.text import hash_text
>>> hash_text(...)

render_template(template, values)

Render template.

Parameters:

Name	Type	Description	Default
template	str	Input text.	required
values	Dict[str, Any]	Dict[str, Any] value used by this operation.	required

Returns:

Name	Type	Description
str	str	Value produced by this API.

Raises:

Type	Description
Exception	Propagates unexpected runtime errors from downstream calls.

Side Effects / I/O: - Primarily performs in-memory transformations.

Preconditions / Invariants: - Callers should provide arguments matching annotated types and expected data contracts.

Examples:

>>> from dlgforge.utils.text import render_template
>>> render_template(...)