ddp_utils.console.logger

import ddp_utils.console.logger

Provide the process-wide console logger and action-component factories.

The logger formats level-aware messages and delegates terminal rendering to Console. It also creates independently managed progress bars, spinners, tables, and layout-aware progress workflows. Component settings use sentinel-aware ProgressConfig, SpinnerConfig, and TableConfig objects so an omitted value remains distinguishable from an explicit value. Per-call overrides take precedence over component configuration, which in turn takes precedence over legacy logger defaults.

The module does not own sys.stdout directly and does not implement the rendering components or their styling source.

Examples

Write through the process-global logger:

from ddp_utils.console.logger import get_logger

logger = get_logger()
logger.info("Worker started")

class ddp_utils.console.logger.LogLevelStyle(icon: str = '', color: str | None = None, bg: str | None = None, style: str | None = None)

Bases: object

Style definition for a single global log level.

Variables

Name	Type	Description
icon	str	Symbol rendered before messages.
color	str | None	Optional foreground color.
bg	str | None	Optional background color.
style	str | None	Optional text style.
icon		Symbol rendered before messages.
color		Optional foreground color.
bg		Optional background color.
style		Optional text style.
icon		Symbol rendered before messages.
color		Optional foreground color.
bg		Optional background color.
style		Optional text style.

Examples

Style definition for a single global log level:

style = LogLevelStyle(icon="!", color="yellow", style="bold")

get_color_params() → dict

Return this level’s color, background and style as a keyword-argument dict.

Returns

Type	Description
dict	Mapping accepted by console color helpers.

Examples

Return this level’s color, background and style as a keyword-argument dict:

result = style.get_color_params()

class ddp_utils.console.logger.LogConfig(format_template: str = '{time} {icon} {message}', start_time: float | None = None, level_icons: Dict[str, str] | None = None, level_styles: Dict[str, LogLevelStyle] | None = None, use_real_time: bool = False, time_format: str = '%H:%M:%S', progress_config: ProgressConfig | None = None, spinner_config: SpinnerConfig | None = None, table_config: TableConfig | None = None, default_hide: bool = False, default_timeout: float | None = None, default_terminate_progress: bool = False, default_log_to_file: bool = False, default_exit: bool = False)

Bases: object

Central logger configuration.

Stores:

• global log line format;

• level icons and styles;

• mirrored component configs for progress/spinner/table factories.

ProgressConfig, SpinnerConfig and TableConfig are the component sources of truth.

Examples

Central logger configuration:

config = LogConfig(use_real_time=True)

Initialize logger formatting, level styles, and component defaults.

Parameters

Name	Type	Description
format_template	str	Template for one rendered log line. Supported fields include {time}, {icon}, and {message}.
start_time	Optional[float]	Epoch timestamp used as the relative-time origin. The current time is used when this value is omitted or falsey.
level_icons	Optional[Dict[str, str]]	Level-to-icon overrides merged over DEFAULT_ICONS.
level_styles	Optional[Dict[str, LogLevelStyle]]	Level-to-style overrides merged over DEFAULT_STYLES.
use_real_time	bool	Render wall-clock time with time_format instead of elapsed time when True.
time_format	str	strftime format used for wall-clock timestamps.
progress_config	Optional[ProgressConfig]	Canonical progress-bar configuration. A copy is stored so subsequent caller mutations do not alter this config.
spinner_config	Optional[SpinnerConfig]	Canonical spinner configuration. A copy is stored.
table_config	Optional[TableConfig]	Canonical table configuration. A copy is stored.
default_hide	bool	Global fallback for a log call’s hide option.
default_timeout	Optional[float]	Global fallback timeout for temporary messages.
default_terminate_progress	bool	Terminate active progress before a log record by default.
default_log_to_file	bool	Write records to the configured error file by default.
default_exit	bool	Exit the process after a record by default.

Examples

Configure wall-clock output and safe global defaults:

config = LogConfig(
    format_template="{time} {icon} {message}",
    use_real_time=True,
    default_exit=False,
)

format_message(level: str, message: str) → str

Render a log message with its level’s icon, timestamp and template.

Parameters

Name	Type	Description
level	str	Registered log-level name.
message	str	Text displayed beside a spinner or in a log record.

Returns

Type	Description
str	Formatted line before color styling.

Examples

Render a log message with its level’s icon, timestamp and template:

result = config.format_message(level="info", message=message)

get_style_for_level(level: str) → LogLevelStyle

Return the registered style for a log level, falling back to a plain bullet.

Parameters

Name	Type	Description
level	str	Registered log-level name.

Returns

Type	Description
LogLevelStyle	Registered style or a plain-bullet fallback.

Examples

Return the registered style for a log level, falling back to a plain bullet:

result = config.get_style_for_level(level="info")

add_level_style(name: str, icon: str, color: str | None = None, bg: str | None = None, style: str | None = None) → None

Register or overwrite the icon/color/style used for a log level.

Parameters

Name	Type	Description
name	str	Log-level name.
icon	str	Icon rendered for the level.
color	str | None	Optional foreground color name.
bg	str | None	Optional background color name.
style	str | None	Optional text style name or style collection.

Examples

Register or overwrite the icon/color/style used for a log level:

config.add_level_style(name="audit", icon="A")

get_progress_template() → List[Tuple[str, str, str]]

Return effective progress template.

Priority:

1. explicit ProgressConfig.template

2. explicit ProgressConfig.format_str

3. legacy progress_format (parsed earlier)

Returns

Type	Description
List[Tuple[str, str, str]]	Effective progress template, or None.

Examples

Return effective progress template:

result = config.get_progress_template()

get_progress_config() → ProgressConfig

Return a copy of the current progress-bar configuration.

Returns

Type	Description
ProgressConfig	Independent progress-configuration copy.

Examples

Return a copy of the current progress-bar configuration:

result = config.get_progress_config()

get_spinner_config() → SpinnerConfig

Return a copy of the current spinner configuration.

Returns

Type	Description
SpinnerConfig	Independent spinner-configuration copy.

Examples

Return a copy of the current spinner configuration:

result = config.get_spinner_config()

get_table_config() → TableConfig

Return a copy of the current table configuration.

Returns

Type	Description
TableConfig	Independent table-configuration copy.

Examples

Return a copy of the current table configuration:

result = config.get_table_config()

classmethod show_palette(console=None) → None

Print the available colors, background colors and text styles to the console.

Parameters

Name	Description
console	Optional console used for rendering output.

Examples

Print the available colors, background colors and text styles to the console:

config.show_palette()

show_current_config(console=None) → None

Show the current logger configuration.

Diagnostic policy:

• legacy logger-level fields are shown only as compatibility inputs;

• effective component configs are the real runtime source of truth;

• priority order is printed explicitly so it is obvious why a given field ended up with its final value.

Parameters

Name	Description
console	Optional console used for rendering output.

Examples

Show the current logger configuration:

config.show_current_config()

class ddp_utils.console.logger.LogManager(logger_instance: ConsoleLogger, config: LogConfig)

Bases: object

Level registry and lazy-method builder for ConsoleLogger.

Examples

Level registry and lazy-method builder for ConsoleLogger:

logger = ConsoleLogger()
manager = LogManager(logger, logger.get_config())

Register configured levels and build their callable log methods.

Parameters

Name	Type	Description
logger_instance	ConsoleLogger	Owning logger that receives the final delegated _log call.
config	LogConfig	Source of level styles, icons, and global default options.

Examples

Build a registry for a logger instance:

config = LogConfig()
manager = LogManager(logger_instance=logger, config=config)
manager.info("Ready")

register_level(name: str, icon: str, color: str | None = None, bg: str | None = None, style: str | None = None, default_hide: bool = False, default_timeout: float | None = None, default_terminate_progress: bool = False, default_log_to_file: bool = False, default_exit: bool = False) → None

Register a new custom log level with its icon, colors and default behavior.

Parameters

Name	Type	Description
name	str	Log-level name.
icon	str	Icon rendered for the level.
color	str | None	Optional foreground color name.
bg	str | None	Optional background color name.
style	str | None	Optional text style name or style collection.
default_hide	bool	Value consumed by this operation.
default_timeout	float | None	Value consumed by this operation.
default_terminate_progress	bool	Value consumed by this operation.
default_log_to_file	bool	Value consumed by this operation.
default_exit	bool	Value consumed by this operation.

Raises

Exception	Description
ValueError	If the level name is already registered.

Examples

Register a new custom log level with its icon, colors and default behavior:

manager.register_level(name="audit", icon="A")

set_level_defaults(level: str, hide: bool | None = None, timeout: float | None = None, terminate_progress: bool | None = None, log_to_file: bool | None = None, exit: bool | None = None) → None

Override the default hide/timeout/log_to_file/exit behavior for a registered level.

Parameters

Name	Type	Description
level	str	Registered log-level name.
hide	bool | None	Override whether the record is temporary.
timeout	float | None	Override the temporary-message lifetime in seconds.
terminate_progress	bool | None	Override whether active progress is completed first.
log_to_file	bool | None	Override whether the record is sent to the error file.
exit	bool | None	Override whether error-file handling requests process exit.

Raises

Exception	Description
ValueError	If the level is unknown.

Examples

Override the default hide/timeout/log_to_file/exit behavior for a registered level:

manager.set_level_defaults(level="info")

get_level_defaults(level: str) → dict

Return a copy of the default behavior settings for a log level.

Parameters

Name	Type	Description
level	str	Registered log-level name.

Returns

Type	Description
dict	Copy of the level defaults, or an empty mapping.

Raises

Exception	Description
ValueError	If the level is unknown.

Examples

Return a copy of the default behavior settings for a log level:

result = manager.get_level_defaults(level="info")

unregister_level(name: str) → None

Remove a previously registered custom log level and its style/defaults.

Parameters

Name	Type	Description
name	str	Log-level name.

Examples

Remove a previously registered custom log level and its style/defaults:

manager.unregister_level(name="audit")

get_levels() → List[str]

Return the names of all registered log levels.

Returns

Type	Description
List[str]	Registered level names in insertion order.

Examples

Return the names of all registered log levels:

result = manager.get_levels()

log(level: str, msg: str | Dict[str, Any], hide: bool | None = None, timeout: float | None = None, terminate_progress: bool | None = None, log_to_file: bool | None = None, exit: bool | None = None, **kwargs) → None

Emit a message using a registered level’s effective settings.

Explicit options override the level defaults; None preserves the corresponding configured value. The final message is delegated to the owning logger and may update active progress or write an error log.

Parameters

Name	Type	Description
level	str	Registered log-level name.
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
hide	bool | None	Override whether the record is temporary.
timeout	float | None	Override the temporary-message lifetime in seconds.
terminate_progress	bool | None	Override whether active progress is completed first.
log_to_file	bool | None	Override whether the record is sent to the error file.
exit	bool | None	Override whether error-file handling requests process exit.
kwargs		Additional operation-specific options forwarded unchanged.

Raises

Exception	Description
ValueError	level is not registered with this manager.

Examples

Emit a message while overriding one configured behavior:

manager.log(level="info", msg="Ready")

class ddp_utils.console.logger.ConsoleLogger(debug: bool = False, err_file: str | None = None, print_err_file: bool = False, config: LogConfig | None = None, console: Console | None = None, auto_intercept_stdout: bool = False, intercept_stderr: bool = False, hook_print: bool = False)

Bases: object

Global console logger facade.

Important:

• logger is not a terminal engine;

• Console owns terminal output;

• action components are independent classes created by this logger.

Examples

Global console logger facade:

logger = ConsoleLogger(debug=True)
logger.info("Ready")

Initialize a console logger and its level registry.

Parameters

Name	Type	Description
debug	bool	Enable emission through the debug level immediately.
err_file	Optional[str]	Optional path used for error-file records.
print_err_file	bool	Also render error-file records in the console.
config	Optional[LogConfig]	Logger configuration. A default LogConfig is created when omitted.
console	Optional[Console]	Rendering console. The shared console is used when omitted.
auto_intercept_stdout	bool	Install console stream interception during initialization.
intercept_stderr	bool	Include stderr when automatic interception is enabled.
hook_print	bool	Replace the built-in print when automatic interception is enabled.

Examples

Create an isolated logger without stream interception:

logger = ConsoleLogger(
    debug=True,
    err_file="worker.err",
    auto_intercept_stdout=False,
)

property info: Callable

Return the callable for ordinary informational messages.

Returns

Callable level handler registered as info.

Examples

Report normal runtime progress:

logger.info("Configuration loaded")

property success: Callable

Return the callable for successful-operation messages.

Returns

Callable level handler registered as success.

Examples

Report successful completion:

logger.success("Upload completed")

property warning: Callable

Return the callable for non-blocking warning messages.

Returns

Callable level handler registered as warning.

Examples

Report a recoverable condition:

logger.warning("Retrying request")

property soft_error: Callable

Return the callable for recoverable error messages.

The default soft_error policy neither exits nor terminates active progress and does not write to the error file.

Returns

Callable level handler registered as soft_error.

Examples

Record a failure while allowing work to continue:

logger.soft_error("Optional lookup failed")

property error: Callable

Return the callable for error messages.

The default error policy writes to the configured error file but does not exit the process.

Returns

Callable level handler registered as error.

Examples

Record a failed operation:

logger.error("Response validation failed")

property fatal: Callable

Return the callable for fatal error messages.

The default fatal policy writes to the error file and requests process exit. Per-call options can override that policy.

Returns

Callable level handler registered as fatal.

Examples

Record a fatal condition without exiting during a controlled test:

logger.fatal("Required service unavailable", exit=False)

property debug: Callable

Return the callable for debug messages.

Debug records are emitted only while debug logging is enabled.

Returns

Callable level handler registered as debug.

Examples

Attach diagnostic context:

logger.debug("Cache lookup", key="customer:42")

property service: Callable

Return the callable for temporary service-status messages.

Service records are hidden after 1.5 seconds by default.

Returns

Callable level handler registered as service.

Examples

Display short-lived background status:

logger.service("Refreshing cache")

register_level(name: str, icon: str, color: str | None = None, bg: str | None = None, style: str | None = None, default_hide: bool = False, default_timeout: float | None = None, default_terminate_progress: bool = False, default_log_to_file: bool = False, default_exit: bool = False) → None

Register a new custom log level on the underlying log manager.

Parameters

Name	Type	Description
name	str	Log-level name.
icon	str	Icon rendered for the level.
color	str | None	Optional foreground color name.
bg	str | None	Optional background color name.
style	str | None	Optional text style name or style collection.
default_hide	bool	Value consumed by this operation.
default_timeout	float | None	Value consumed by this operation.
default_terminate_progress	bool	Value consumed by this operation.
default_log_to_file	bool	Value consumed by this operation.
default_exit	bool	Value consumed by this operation.

Examples

Register a new custom log level on the underlying log manager:

logger.register_level(name="audit", icon="A")

unregister_level(name: str) → None

Remove a previously registered custom log level.

Parameters

Name	Type	Description
name	str	Log-level name.

Examples

Remove a previously registered custom log level:

logger.unregister_level(name="audit")

set_level_defaults(level: str, hide: bool | None = None, timeout: float | None = None, terminate_progress: bool | None = None, log_to_file: bool | None = None, exit: bool | None = None) → None

Override the default behavior for a registered log level.

Parameters

Name	Type	Description
level	str	Registered log-level name.
hide	bool | None	Override whether the record is temporary.
timeout	float | None	Override the temporary-message lifetime in seconds.
terminate_progress	bool | None	Override whether active progress is completed first.
log_to_file	bool | None	Override whether the record is sent to the error file.
exit	bool | None	Override whether error-file handling requests process exit.

Examples

Override the default behavior for a registered log level:

logger.set_level_defaults(level="info")

set_global_defaults(hide: bool | None = None, timeout: float | None = None, terminate_progress: bool | None = None, log_to_file: bool | None = None, exit: bool | None = None) → None

Update global logger defaults.

Important: this also updates currently registered level defaults for the same fields.

Parameters

Name	Type	Description
hide	bool | None	Override whether the record is temporary.
timeout	float | None	Override the temporary-message lifetime in seconds.
terminate_progress	bool | None	Override whether active progress is completed first.
log_to_file	bool | None	Override whether the record is sent to the error file.
exit	bool | None	Override whether error-file handling requests process exit.

Examples

Update global logger defaults:

logger.set_global_defaults()

get_level_defaults(level: str) → dict

Return the default behavior settings for a log level.

Parameters

Name	Type	Description
level	str	Registered log-level name.

Returns

Type	Description
dict	Copy of the requested level defaults.

Examples

Return the default behavior settings for a log level:

result = logger.get_level_defaults(level="info")

log(level: str, msg: str | Dict[str, Any], hide: bool | None = None, timeout: float | None = None, terminate_progress: bool | None = None, log_to_file: bool | None = None, exit: bool | None = None, **kwargs) → None

Emit a log message at the given level through the underlying log manager.

Parameters

Name	Type	Description
level	str	Registered log-level name.
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
hide	bool | None	Override whether the record is temporary.
timeout	float | None	Override the temporary-message lifetime in seconds.
terminate_progress	bool | None	Override whether active progress is completed first.
log_to_file	bool | None	Override whether the record is sent to the error file.
exit	bool | None	Override whether error-file handling requests process exit.
kwargs		Additional operation-specific options forwarded unchanged.

Examples

Emit a log message at the given level through the underlying log manager:

logger.log(level="info", msg="Ready")

attach_progress(progress) → None

Attach an active progress bar so log output can coexist with it on screen.

Parameters

Name	Description
progress	Progress object synchronized with the logger and console.

Examples

Attach an active progress bar so log output can coexist with it on screen:

logger.attach_progress(progress=progress)

clear_active_progress() → None

Detach the currently attached progress bar, if any.

Examples

Detach the currently attached progress bar, if any:

logger.clear_active_progress()

create_progress(total: int, description: str = 'Progress', layout: bool | ConsoleLayout = False, layout_title: str | None = None, layout_max_logs: int | None = None, layout_on_finish: str = 'keep', **kwargs)

Create a ProgressBar.

Return contract:

• layout=False -> ProgressBar

• layout=True -> (ProgressBar, LayoutLogger, ConsoleLayout)

• layout=layout_instance -> (ProgressBar, LayoutLogger, layout_instance)

Parameters

Name	Type	Description
total	int	Total number of progress units.
description	str	Human-readable progress label.
layout	bool | ConsoleLayout	Layout policy or an existing ConsoleLayout instance.
layout_title	str | None	Optional title for a newly created layout.
layout_max_logs	int | None	Maximum retained log rows in a new layout.
layout_on_finish	str	Layout completion policy.
kwargs		Additional operation-specific options forwarded unchanged.

Returns

Progress bar, or a progress/logger/layout tuple when layouts are enabled.

Examples

Create a ProgressBar:

progress = logger.create_progress(total=100, description="Import")

create_spinner(message: str = 'Loading.', layout: ConsoleLayout | None = None, type: str | None = None, **kwargs) → BaseSpinner

Create an independent spinner, optionally bound to a layout.

Parameters

Name	Type	Description
message	str	Text displayed beside the spinner.
layout	ConsoleLayout | None	Optional console layout that owns spinner rendering.
type	str | None	Spinner implementation: "simple", "smooth", or "rich". The configured spinner type is used when omitted.
**kwargs		Per-instance spinner options merged over the canonical SpinnerConfig and forwarded to the spinner factory.

Returns

Type	Description
BaseSpinner	Newly created spinner instance. The caller controls its lifecycle.

Raises

Exception	Description
ValueError	The selected spinner type is unknown.

Examples

Run a smooth spinner around blocking work:

spinner = logger.create_spinner("Downloading", type="smooth")
spinner.start()
try:
    download()
finally:
    spinner.stop()

create_table(headers=None, rows=None, layout: ConsoleLayout | None = None, **kwargs) → TableView

Create an independent TableView, optionally bound to a layout.

Parameters

Name	Type	Description
headers		Optional table column headings.
rows		Optional initial table rows.
layout	ConsoleLayout | None	Layout policy or an existing ConsoleLayout instance.
kwargs		Additional operation-specific options forwarded unchanged.

Returns

Type	Description
TableView	New table view bound to the requested layout or console.

Examples

Create an independent TableView, optionally bound to a layout:

table = logger.create_table(headers=["Name"], rows=[["Ada"]])

add_margin(lines: int = 1) → None

Write blank lines to add vertical spacing in the console output.

Parameters

Name	Type	Description
lines	int	Number of blank lines to write.

Examples

Write blank lines to add vertical spacing in the console output:

logger.add_margin()

add_strip(size: int = 10, char: str | None = None, double: bool = False, underline: bool = False, margin: int = 0) → None

Print a horizontal separator line of repeated characters.

Parameters

Name	Type	Description
size	int	Number of separator characters.
char	str | None	Character used to draw the separator.
double	bool	Draw the separator twice when true.
underline	bool	Underline the separator when true.
margin	int	Number of blank lines around the separator.

Examples

Print a horizontal separator line of repeated characters:

logger.add_strip(size=40, char="-")

add_section(title: str, char: str = '-', width: int = 0, margin_before: int = 1, margin_after: int = 0, line_color: str = 'bright_black', title_style: str = 'bold white') → None

Print a titled horizontal separator to mark a new output section.

Parameters

Name	Type	Description
title	str	Section title.
char	str	Character used to draw the separator.
width	int	Requested section width; automatic when zero.
margin_before	int	Blank lines written before the section.
margin_after	int	Blank lines written after the section.
line_color	str	Color applied to the section line.
title_style	str	Style applied to the section title.

Examples

Print a titled horizontal separator to mark a new output section:

logger.add_section(title="Results")

elapsed_time() → str

Return elapsed logger lifetime as MM:SS or HH:MM:SS.

Returns

Type	Description
str	Elapsed duration as MM:SS or HH:MM:SS.

Examples

Return elapsed logger lifetime as MM:SS or HH:MM:SS:

result = logger.elapsed_time()

print_elapsed() → None

Print elapsed logger lifetime through the regular info channel.

Examples

Print elapsed logger lifetime through the regular info channel:

logger.print_elapsed()

stop() → None

Stop logger-related live activity and leave the console in a clean state.

Safe shutdown policy:

• clear temporary/service messages;

• detach logger ownership from the active progress in Console;

• do NOT call complete(), finish(), freeze(), or close() on progress;

• write one trailing newline.

Progress lifecycle is controlled explicitly by the caller code (for example: complete(), finish(), or close() in project/business flow).

Examples

Stop logger-related live activity and leave the console in a clean state:

logger.stop()

show_palette(console=None) → None

Print the available colors, background colors and text styles to the console.

Parameters

Name	Description
console	Optional console used for rendering output.

Examples

Print the available colors, background colors and text styles to the console:

logger.show_palette()

show_current_config(console=None) → None

Print the current logger configuration to the console.

Parameters

Name	Description
console	Optional console used for rendering output.

Examples

Print the current logger configuration to the console:

logger.show_current_config()

install_interception(intercept_stderr: bool = False, hook_print: bool = True) → None

Redirect stdout/stderr (and optionally print()) through this logger’s console.

Parameters

Name	Type	Description
intercept_stderr	bool	Include stderr in stream interception.
hook_print	bool	Route the built-in print through the console.

Examples

Redirect stdout/stderr (and optionally print()) through this logger’s console:

logger.install_interception()

uninstall_interception() → None

Restore the original stdout/stderr/print, undoing install_interception().

Examples

Restore the original stdout/stderr/print, undoing install_interception():

logger.uninstall_interception()

get_console() → Console

Return the underlying Console instance used for output.

Returns

Type	Description
Console	Console used by this logger.

Examples

Return the underlying Console instance used for output:

result = logger.get_console()

get_config() → LogConfig

Return the underlying LogConfig instance.

Returns

Type	Description
LogConfig	Live logger configuration object.

Examples

Return the underlying LogConfig instance:

result = logger.get_config()

cprint(text: str, color: str | None = None, bg: str | None = None, style: str | List[str] | Tuple[str, ...] | None = None, end: str = '\n') → None

Coordinated colored print through the owned Console.

This is the preferred logger-level helper when the caller needs ad-hoc colorized output without registering a separate log level.

Parameters

Name	Type	Description
text	str	Text to render or print.
color	str | None	Optional foreground color name.
bg	str | None	Optional background color name.
style	str | List[str] | Tuple[str, ...] | None	Optional text style name or style collection.
end	str	String appended after printed text.

Examples

Coordinated colored print through the owned Console:

logger.cprint(text="Ready")

ddp_utils.console.logger.get_logger(config: LogConfig | None = None, console: Console | None = None, debug: bool = False, err_file: str | None = None, print_err_file: bool = False, auto_intercept_stdout: bool = False, intercept_stderr: bool = False, hook_print: bool = False) → ConsoleLogger

Return the process-global ConsoleLogger singleton.

The first call creates it. Later calls return the existing instance.

Parameters

Name	Type	Description
config	LogConfig | None	Optional logger configuration used when creating an instance.
console	Console | None	Optional console used for rendering output.
debug	bool	Enable debug-level emission for a newly created logger.
err_file	str | None	Optional path used for error-file records.
print_err_file	bool	Also render error-file records in the console.
auto_intercept_stdout	bool	Install stream interception during logger creation.
intercept_stderr	bool	Include stderr in stream interception.
hook_print	bool	Route the built-in print through the console.

Returns

Type	Description
ConsoleLogger	Process-global logger, created on the first call.

Examples

Return the process-global ConsoleLogger singleton:

logger = get_logger(debug=True)
logger.info("Worker started")

ddp_utils.console.logger.set_logger(logger: ConsoleLogger) → None

Replace the process-global logger singleton.

Parameters

Name	Type	Description
logger	ConsoleLogger	Logger instance installed as the process-global singleton.

Examples

Replace the process-global logger singleton:

set_logger(logger=ConsoleLogger())

ddp_utils.console.logger.reset_logger() → None

Reset the process-global logger singleton.

Examples

Reset the process-global logger singleton:

reset_logger()

ddp_utils.console.logger.info(msg: str | Dict[str, Any], **kwargs) → None

Log a message at the ‘info’ level on the default logger.

Parameters

Name	Type	Description
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
kwargs		Additional operation-specific options forwarded unchanged.

Examples

Log a message at the ‘info’ level on the default logger:

info(msg="Ready")

ddp_utils.console.logger.success(msg: str | Dict[str, Any], **kwargs) → None

Log a message at the ‘success’ level on the default logger.

Parameters

Name	Type	Description
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
kwargs		Additional operation-specific options forwarded unchanged.

Examples

Log a message at the ‘success’ level on the default logger:

success(msg="Ready")

ddp_utils.console.logger.warning(msg: str | Dict[str, Any], **kwargs) → None

Log a message at the ‘warning’ level on the default logger.

Parameters

Name	Type	Description
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
kwargs		Additional operation-specific options forwarded unchanged.

Examples

Log a message at the ‘warning’ level on the default logger:

warning(msg="Ready")

ddp_utils.console.logger.soft_error(msg: str | Dict[str, Any], **kwargs) → None

Log a message at the ‘soft_error’ level on the default logger.

Parameters

Name	Type	Description
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
kwargs		Additional operation-specific options forwarded unchanged.

Examples

Log a message at the ‘soft_error’ level on the default logger:

soft_error(msg="Ready")

ddp_utils.console.logger.error(msg: str | Dict[str, Any], **kwargs) → None

Log a message at the ‘error’ level on the default logger.

Parameters

Name	Type	Description
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
kwargs		Additional operation-specific options forwarded unchanged.

Examples

Log a message at the ‘error’ level on the default logger:

error(msg="Ready")

ddp_utils.console.logger.fatal(msg: str | Dict[str, Any], **kwargs) → None

Log a message at the ‘fatal’ level on the default logger.

Parameters

Name	Type	Description
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
kwargs		Additional operation-specific options forwarded unchanged.

Raises

Exception	Description
SystemExit	The effective fatal policy requests process exit.

Examples

Log a message at the ‘fatal’ level on the default logger:

fatal("Required service unavailable", exit=False)

ddp_utils.console.logger.debug(msg: str | Dict[str, Any], **kwargs) → None

Log a message at the ‘debug’ level on the default logger.

Parameters

Name	Type	Description
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
kwargs		Additional operation-specific options forwarded unchanged.

Examples

Log a message at the ‘debug’ level on the default logger:

get_logger(debug=True)
debug("Cache lookup", key="customer:42")

ddp_utils.console.logger.service(msg: str | Dict[str, Any], **kwargs) → None

Log a message at the ‘service’ level on the default logger.

Parameters

Name	Type	Description
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
kwargs		Additional operation-specific options forwarded unchanged.

Examples

Log a message at the ‘service’ level on the default logger:

service(msg="Ready")

ddp_utils.console.logger.log(level: str, msg: str | Dict[str, Any], **kwargs) → None

Log a message at the given level on the default logger.

Parameters

Name	Type	Description
level	str	Registered log-level name.
msg	str | Dict[str, Any]	Plain text or a structured ttl and body payload.
kwargs		Additional operation-specific options forwarded unchanged.

Examples

Log a message at the given level on the default logger:

log(level="info", msg="Ready")