oizom_logger.OizomLogger

class oizom_logger.OizomLogger(logger_name: str, **kwargs: Any)

High-level logger wrapper backed by LoggerConfig.

Provides the public entry point that the rest of the Oizom codebase imports. Accepts the same **kwargs interface as the legacy logger for backward compatibility, but internally translates them into an immutable LoggerConfig and builds a fully configured logging.Logger with both console and rotating-file handlers.

Variables:

• config (LoggerConfig) – The immutable configuration applied to logger.

• logger (logging.Logger) – The underlying logging logger instance retrieved via logging.getLogger().

Example

Standard usage in any Oizom module:

logger = OizomLogger(__name__)
logger.info_with_context("INIT", "Starting sensor setup")

# Or use the raw stdlib logger for ad-hoc logging:
log = logger.get()
log.info("Standard log message")

Construct a configured OizomLogger.

Accepts the legacy keyword-argument surface of the previous oizom_logger module; any unknown keys are silently dropped.

Parameters:

• logger_name – Identifier passed to logging.getLogger(); conventionally the caller’s __name__.

• **kwargs – Any subset of LoggerConfig fields. String log-level names are accepted for console_level and file_level.

Returns:

None.

Raises:

OSError – If the log directory cannot be created or the log file cannot be opened.

Example

>>> log = OizomLogger("demo.test", color=False)
>>> isinstance(log.config, LoggerConfig)
True

Note

Existing handlers on the underlying logger are cleared so re-instantiating with the same name does not duplicate output. See _configure().

_configure() → None

Wire handlers, filters, and formatter onto logger.

Sets the effective logger level to the more verbose of console and file levels, clears any pre-existing handlers/filters to avoid duplication across re-configurations, attaches a ContextFilter, and adds a console handler plus a rotating file handler. Disables propagation to the root logger so messages are not double-emitted.

Parameters:

None.

Returns:

None.

Raises:

OSError – Propagated from _build_file_handler() if the log file cannot be opened.

Example

>>> log = OizomLogger("demo.cfg", color=False)
>>> log._configure()

Note

Invoked automatically from __init__(); external code should rarely need to call this directly.

critical_with_context(context: str, message: str, *args: Any, **kwargs: Any) → None

Emit a CRITICAL record carrying a context token.

Parameters:

• context – Short token inserted into the context column.

• message – %-style format string for the log message.

• *args – Positional substitution arguments for message.

• **kwargs – Forwarded to log_with_context().

Returns:

None.

:raises None directly; underlying logging errors propagate.:

Example

>>> log = OizomLogger(__name__)
>>> log.critical_with_context("BOOT", "watchdog")

Note

Thin wrapper over log_with_context() at level CRITICAL.

debug_with_context(context: str, message: str, *args: Any, **kwargs: Any) → None

Emit a DEBUG record carrying a context token.

Parameters:

• context – Short token inserted into the context column.

• message – %-style format string for the log message.

• *args – Positional substitution arguments for message.

• **kwargs – Forwarded to log_with_context().

Returns:

None.

:raises None directly; underlying logging errors propagate.:

Example

>>> log = OizomLogger(__name__)
>>> log.debug_with_context("READ", "value=%s", 42)

Note

Thin wrapper over log_with_context() at level DEBUG.

error_with_context(context: str, message: str, *args: Any, **kwargs: Any) → None

Emit an ERROR record carrying a context token.

Parameters:

• context – Short token inserted into the context column.

• message – %-style format string for the log message.

• *args – Positional substitution arguments for message.

• **kwargs – Forwarded to log_with_context().

Returns:

None.

:raises None directly; underlying logging errors propagate.:

Example

>>> log = OizomLogger(__name__)
>>> log.error_with_context("NET", "timeout")

Note

Thin wrapper over log_with_context() at level ERROR.

get() → logging.Logger

Return the underlying logging.Logger instance.

Useful when code needs to call standard logging API methods (info, warning, exception and so on) without the context column.

Parameters:

None.

Returns:

The logging.Logger underlying this wrapper.

Raises:

None. –

Example

>>> log = OizomLogger(__name__).get()
>>> log.info("plain log message")

Note

The returned logger has its handlers, filter, and propagation already configured by _configure().

info_with_context(context: str, message: str, *args: Any, **kwargs: Any) → None

Emit an INFO record carrying a context token.

Parameters:

• context – Short token inserted into the context column.

• message – %-style format string for the log message.

• *args – Positional substitution arguments for message.

• **kwargs – Forwarded to log_with_context().

Returns:

None.

:raises None directly; underlying logging errors propagate.:

Example

>>> log = OizomLogger(__name__)
>>> log.info_with_context("INIT", "ready")

Note

Thin wrapper over log_with_context() at level INFO.

install_globally(replace_existing: bool = True) → None

Apply this logger’s configuration to the root logger.

Useful for capturing log output emitted by third-party libraries such as urllib3, paho-mqtt, or picamera. Builds a fresh set of handlers using the same config and attaches them to logging.getLogger() (root).

Parameters:

replace_existing – If True (default), clear any handlers or filters already installed on the root logger before attaching the new ones. Set False to add alongside.

Returns:

None.

Raises:

OSError – Propagated from _build_file_handler() if the log file cannot be opened.

Example

>>> log = OizomLogger(__name__)
>>> log.install_globally()

Note

Call once at process startup, after any third-party library has been imported, to ensure all loggers route through the Oizom pipeline.

log_with_context(level: str, context: str, message: str, *args: Any, **kwargs: Any) → None

Emit a log record with an explicit context token.

Backbone of the *_with_context family of helpers (debug_with_context(), info_with_context(), etc.). Pads/truncates context to LoggerConfig.context_width so the column stays visually aligned across records.

Parameters:

• level – Level name ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"). Case-insensitive.

• context – Short token (e.g. "INIT", "READ") inserted into the context column.

• message – %-style format string for the log message.

• *args – Positional substitution arguments for message.

• **kwargs – Forwarded to logging.Logger.log() (e.g. exc_info, stack_info).

Returns:

None.

:raises None directly; any error inside logging propagates: :raises unchanged.:

Example

>>> log = OizomLogger(__name__)
>>> log.log_with_context("INFO", "INIT", "ready")

Note

Uses stacklevel=3 so file/lineno columns reflect the actual caller, not this wrapper.

warning_with_context(context: str, message: str, *args: Any, **kwargs: Any) → None

Emit a WARNING record carrying a context token.

Parameters:

• context – Short token inserted into the context column.

• message – %-style format string for the log message.

• *args – Positional substitution arguments for message.

• **kwargs – Forwarded to log_with_context().

Returns:

None.

:raises None directly; underlying logging errors propagate.:

Example

>>> log = OizomLogger(__name__)
>>> log.warning_with_context("USB", "device disconnected")

Note

Thin wrapper over log_with_context() at level WARNING.

config

logger