API Reference¶

This section provides detailed API documentation for ctxlog.

Core API¶

ctxlog - A structured logging library for Python.

This library provides a structured logging system with context-rich logs, multiple output handlers, and support for traditional log levels.

class ctxlog.LogLevel(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]¶

Bases: Enum

Log levels for ctxlog.

DEBUG = 10¶

INFO = 20¶

WARNING = 30¶

ERROR = 40¶

CRITICAL = 50¶

classmethod parse(level)[source]¶

Parse a string or int to a LogLevel.

Parameters:: level (Union[LogLevel, str, int]) – The log level as a string or int.
Return type:: LogLevel
Returns:: The corresponding LogLevel enum value.
Raises:: ValueError – If the level is not a valid log level.

classmethod from_string(level_str)[source]¶

Convert a string to a LogLevel.

Parameters:: level_str (str) – The string representation of the log level.
Return type:: LogLevel
Returns:: The corresponding LogLevel enum value.
Raises:: ValueError – If the string is not a valid log level.

__str__()[source]¶

Return the string representation of the log level.

Return type:: str

class ctxlog.Handler(level=None, serialize=False)[source]¶

Bases: ABC

Base class for log handlers.

Parameters:

level (LogLevel | None)
serialize (bool)

__init__(level=None, serialize=False)[source]¶

Initialize a Handler.

Parameters:

level (Optional[LogLevel]) – Log level for this handler. If None, uses the global level.
serialize (bool) – Whether to serialize logs as JSON.

Return type:

None

abstract emit(log_entry)[source]¶

Emit a log entry.

Parameters:: log_entry (Dict[str, Any]) – The log entry to emit.
Return type:: None

close()[source]¶

Close any resources used by the handler.

Return type:: None

format(log_entry)[source]¶

Format a log entry.

Parameters:: log_entry (Dict[str, Any]) – The log entry to format.
Return type:: str
Returns:: The formatted log entry.

class ctxlog.ConsoleHandler(level=None, serialize=False, color=True, use_stderr=False)[source]¶

Bases: Handler

Handler that outputs logs to the console.

Parameters:

level (LogLevel | None)
serialize (bool)
color (bool)
use_stderr (bool)

__init__(level=None, serialize=False, color=True, use_stderr=False)[source]¶

Initialize a ConsoleHandler.

Parameters:

level (Optional[LogLevel]) – Log level for this handler. If None, uses the global level.
serialize (bool) – Whether to serialize logs as JSON.
color (bool) – Whether to use colored output (only applies if serialize=False).
use_stderr (bool) – Whether to write logs to stderr instead of stdout.

Return type:

None

emit(log_entry)[source]¶

Emit a log entry to the console.

Parameters:: log_entry (Dict[str, Any]) – The log entry to emit.
Return type:: None

class ctxlog.FileHandler(file_path, level=None, serialize=True, rotation=None)[source]¶

Bases: Handler

Handler that outputs logs to a file.

Parameters:

file_path (str)
level (LogLevel | None)
serialize (bool)
rotation (FileRotation | None)

__init__(file_path, level=None, serialize=True, rotation=None)[source]¶

Initialize a FileHandler.

Parameters:

file_path (str) – Path to the log file.
level (Optional[LogLevel]) – Log level for this handler. If None, uses the global level.
serialize (bool) – Whether to serialize logs as JSON.
rotation (Optional[FileRotation]) – Optional FileRotation object for log rotation.

Return type:

None

emit(log_entry)[source]¶

Emit a log entry to the file.

Parameters:: log_entry (Dict[str, Any]) – The log entry to emit.
Return type:: None

close()[source]¶

Close the file handle.

Return type:: None

__del__()[source]¶

Destructor to ensure file is closed when handler is garbage collected.

Return type:: None

class ctxlog.FileRotation(size=None, time=None, keep=5, compression=None)[source]¶

Bases: object

Configuration for log file rotation.

Parameters:

size (str | None)
time (str | None)
keep (int)
compression (Literal['gzip', 'zip'] | None)

__init__(size=None, time=None, keep=5, compression=None)[source]¶

Initialize a FileRotation configuration.

Parameters:

size (Optional[str]) – Size threshold for rotation (e.g., “20MB”). Mutually exclusive with time.
time (Optional[str]) – Time of day for rotation (e.g., “00.00”). Mutually exclusive with size.
keep (int) – Number of rotated files to keep.
compression (Optional[Literal['gzip', 'zip']]) – Compression method for old files (e.g., “gzip”, “zip”).

Raises:

ValueError – If both size and time are specified.

Return type:

None

class ctxlog.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

class ctxlog.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

ctxlog.configure(level=LogLevel.INFO, timefmt='iso', utc=False, handlers=None)[source]¶

Configure the global settings for ctxlog.

This function should be called once, typically at application startup.

Parameters:

level (Union[LogLevel, Literal['debug', 'info', 'warning', 'error', 'critical'], int]) – The global log level. Can be a LogLevel enum value, a string, or an int.
timefmt (str) – Timestamp format for log entries. Use ‘iso’ for ISO8601, or provide a custom strftime format string.
utc (bool) – If True, use UTC for timestamps. Default is False (local time).
handlers (Optional[List[Handler]]) – List of output handlers. If None, a default ConsoleHandler will be used.

Return type:

None

Example

Configure ctxlog at startup:

ctxlog.configure(
    level=ctxlog.LogLevel.INFO,
    timefmt="iso",
    utc=True,
    handlers=[
        ctxlog.ConsoleHandler(serialize=False, color=True, use_stderr=False),
        ctxlog.FileHandler(
            level=ctxlog.LogLevel.DEBUG,
            serialize=True,
            file_path="./app.log",
            rotation=ctxlog.FileRotation(
                size="20MB", # mutually exclusive with time
                time="00.00", # mutually exclusive with size
                keep=12,
                compress_old=True
            ),
        ),
    ]
)

ctxlog.get_logger(name)[source]¶

Get a logger for a module or class.

Parameters:: name (str) – The name of the logger, typically __name__.
Return type:: Logger
Returns:: A Logger instance.

Example

`python logger = ctxlog.get_logger(__name__) `