Core Module¶

Logger¶

class ctxlog.logger.Logger(name)[source]¶

Bases: object

Main entry point for ctxlog.

This class provides methods for creating log contexts and emitting logs.

Parameters:: name (str)

__init__(name)[source]¶

Initialize a Logger.

Parameters:: name (str) – The name of the logger, typically the module name.
Return type:: None

new(event=None)[source]¶

Create a new log context without any extra fields.

Return type:: Log
Returns:: A new Log instance.
Parameters:: event (str | None)

ctx(**kwargs)[source]¶

Create a new log context with additional fields. Use .new().ctx() instead if you want to set an event name.

Parameters:: **kwargs (dict[str, Union[str, int, float, bool, None]]) – Additional fields to include in the log context.
Return type:: Log
Returns:: A new Log instance with the provided context.

debug(message)[source]¶

Log a debug message.

Parameters:: message (str) – The log message.
Return type:: None

info(message)[source]¶

Log an info message.

Parameters:: message (str) – The log message.
Return type:: None

warning(message)[source]¶

Log a warning message.

Parameters:: message (str) – The log message.
Return type:: None

error(message)[source]¶

Log an error message.

Parameters:: message (str) – The log message.
Return type:: None

critical(message)[source]¶

Log a critical message.

Parameters:: message (str) – The log message.
Return type:: None

Log¶

class ctxlog.log.LogContext[source]¶

Bases: object

A class to store context fields.

__init__()[source]¶

Initialize an empty LogContext.

Return type:: None

add(**kwargs)[source]¶

Add context fields.

Parameters:: **kwargs (dict[str, Union[str, int, float, bool, None]]) – Context fields to add.
Return type:: None

get_all()[source]¶

Get all context fields.

Return type:: Dict[str, Any]
Returns:: A dictionary of all context fields.

class ctxlog.log.Log(event=None, has_parent=False)[source]¶

Bases: object

A log context with methods for adding structured fields and emitting logs.

Parameters:

event (str | None)
has_parent (bool)

__init__(event=None, has_parent=False)[source]¶

Initialize a Log context.

Parameters:

level – The log level.
event (Optional[str]) – The event name.
has_parent (bool) – Whether this log context has a parent.
**kwargs – Additional context fields.

Return type:

None

ctx(**kwargs)[source]¶

Add context fields to the log.

Parameters:: **kwargs (dict[str, Union[str, int, float, bool, None]]) – Context fields to add. Must be JSON-serializable types.
Return type:: Log
Returns:: Self for method chaining.

exc(exception)[source]¶

Attach exception details to the log.

Parameters:: exception (Exception) – The exception to attach.
Return type:: Log
Returns:: Self for method chaining.

new(event=None, **kwargs)[source]¶

Create a new log context chained to this one.

Parameters:

event (Optional[str]) – The event name for the new log.
**kwargs (Any) – Context fields for the new log.

Return type:

Log

Returns:

A new Log instance chained to this one.

debug(message)[source]¶

Log a debug message.

Parameters:: message (str) – The log message.
Return type:: None

info(message)[source]¶

Log an info message.

Parameters:: message (str) – The log message.
Return type:: None

warning(message)[source]¶

Log a warning message.

Parameters:: message (str) – The log message.
Return type:: None

error(message)[source]¶

Log an error message.

Parameters:: message (str) – The log message.
Return type:: None

critical(message)[source]¶

Log a critical message.

Parameters:: message (str) – The log message.
Return type:: None