ddp_utils.logger¶

import ddp_utils.logger

Provide a configurable facade over logging for text and JSON data.

The facade adds optional ANSI colors, prefixes, source locations, timestamps, structured dict or list payloads, and convenience methods while retaining the standard logging backend and handlers.

Examples

Write a structured application event without terminal colors:

from ddp_utils.logger import AdvancedLogger

logger = AdvancedLogger(use_colors=False, show_location=False)
logger.info("request completed", {"status": 200})

class ddp_utils.logger.AdvancedLogger(name: str = 'advanced_logger', level: str | int = 'DEBUG', log_to_file: bool = False, filename: str = 'app.log', use_colors: bool = True, show_timestamp: bool = True, show_prefix: bool = True, show_level: bool = True, show_location: bool = False, indent_json: int = 4, prefix: str | None = None, global_flag='DEBUG_ENABLED')¶

Bases: object

Format and dispatch application logs through a standard logger.

The wrapper applies its own severity threshold while the underlying logging.Logger remains at DEBUG. Child facades returned by get_logger() share that logger and its handlers but keep independent prefixes.

Examples

Create component-specific views over one logger:

base = AdvancedLogger(name="service", use_colors=False)
database_log = base.get_logger("db")
database_log.warning("connection retry")

Initialize formatting options and shared logging handlers.

Parameters

Name	Type	Description
name	str	Name passed to `logging.getLogger()`.
level	str \| int	Wrapper threshold as a standard integer or recognized name. Unknown names fall back to `DEBUG`.
log_to_file	bool	Add one UTF-8 file handler when the shared logger does not already have one.
filename	str	Absolute log path or basename under the shared runtime log directory.
use_colors	bool	Add ANSI color sequences to formatted console text.
show_timestamp	bool	Include a local wall-clock timestamp.
show_prefix	bool	Include `prefix` when one is configured.
show_level	bool	Include a padded severity label.
show_location	bool	Include the caller’s filename and line number.
indent_json	int	Indentation used for structured JSON payloads.
prefix	str \| None	Optional component label normalized to uppercase.
global_flag		Global-registry key that enables `DEBUG` messages. `None` disables this additional gate.

Examples

Log INFO and higher to the runtime log directory:

logger = AdvancedLogger(
    name="worker",
    level="INFO",
    log_to_file=True,
    filename="worker.log",
    use_colors=False,
)

debug(*args, force: bool = False, detailed: bool = False, **kwargs) → None¶

Emit a DEBUG record when its global flag and threshold allow it.

Parameters

Name	Type	Description
*args		Message fragments and optional structured payload.
force	bool	Bypass the DEBUG gate and threshold.
detailed	bool	Include the caller location for this record.
**kwargs		Additional structured fields.

Examples

Attach diagnostic state:

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

info(*args, force: bool = False, detailed: bool = False, **kwargs) → None¶

Emit an INFO record when the configured threshold allows it.

Parameters

Name	Type	Description
*args		Message fragments and optional structured payload.
force	bool	Bypass the wrapper threshold.
detailed	bool	Include the caller location for this record.
**kwargs		Additional structured fields.

Examples

Record a completed operation:

logger.info("import completed", rows=120)

warning(*args, force: bool = False, detailed: bool = False, **kwargs) → None¶

Emit a WARNING record when the configured threshold allows it.

Parameters

Name	Type	Description
*args		Message fragments and optional structured payload.
force	bool	Bypass the wrapper threshold.
detailed	bool	Include the caller location for this record.
**kwargs		Additional structured fields.

Examples

Report a recoverable retry:

logger.warning("request will retry", attempt=2)

error(*args, force: bool = False, detailed: bool = False, **kwargs) → None¶

Emit an ERROR record when the configured threshold allows it.

Parameters

Name	Type	Description
*args		Message fragments and optional structured payload.
force	bool	Bypass the wrapper threshold.
detailed	bool	Include the caller location for this record.
**kwargs		Additional structured fields.

Examples

Record an unsuccessful response:

logger.error("request failed", status=503)

critical(*args, force: bool = False, detailed: bool = False, **kwargs) → None¶

Emit a CRITICAL record when the configured threshold allows it.

Parameters

Name	Type	Description
*args		Message fragments and optional structured payload.
force	bool	Bypass the wrapper threshold.
detailed	bool	Include the caller location for this record.
**kwargs		Additional structured fields.

Examples

Report an unrecoverable subsystem failure:

logger.critical("database unavailable")

exception(message: str, *args, **kwargs) → None¶

Log an ERROR record with the active exception traceback.

Parameters

Name	Type	Description
message	str	Record message passed directly to the underlying logger.
*args		Positional formatting arguments accepted by logging.
**kwargs		Additional keyword arguments accepted by logging.

Note

This method bypasses facade formatting, its threshold, and the DEBUG global gate, and always supplies exc_info=True.

Examples

Preserve a caught exception traceback:

try:
    load_configuration()
except OSError:
    logger.exception("configuration load failed")

print(*args, force: bool = False, detailed: bool = False, **kwargs) → None¶

Emit an INFO record as a compatibility alias for info().

Parameters

Name	Type	Description
*args		Message fragments and optional structured payload.
force	bool	Bypass the wrapper threshold.
detailed	bool	Include the caller location for this record.
**kwargs		Additional structured fields.

Examples

Replace a simple built-in print call:

logger.print("worker started")

success(*args, force: bool = False, detailed: bool = False, **kwargs) → None¶

Emit an INFO record decorated as a successful operation.

Parameters

Name	Type	Description
*args		Message fragments. An empty argument list emits nothing.
force	bool	Bypass the wrapper threshold.
detailed	bool	Include the caller location for this record.
**kwargs		Additional structured fields.

Examples

Announce a completed export:

logger.success("export complete", files=4)

highlight(*args, force: bool = False, detailed: bool = False, **kwargs) → None¶

Emit an INFO record decorated as a highlighted message.

Parameters

Name	Type	Description
*args		Message fragments. An empty argument list emits nothing.
force	bool	Bypass the wrapper threshold.
detailed	bool	Include the caller location for this record.
**kwargs		Additional structured fields.

Examples

Draw attention to a selected mode:

logger.highlight("maintenance mode enabled")

get_logger(prefix: str) → AdvancedLogger¶

Return a shallow facade copy with a different component prefix.

Parameters

Name	Type	Description
prefix	str	New label normalized to uppercase, or an empty value to clear the label.

Returns

Type	Description
AdvancedLogger	Independent facade object sharing the underlying logger and handlers with this instance.

Examples

Give two modules stable independent labels:

api_log = logger.get_logger("api")
worker_log = logger.get_logger("worker")