Handlers

This module provides output handlers for ctxlog.

class ctxlog.handlers.FileRotation(size=None, time=None, keep=5, compression=None)

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)

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.handlers.Handler(level=None, serialize=False)

Bases: ABC

Base class for log handlers.

Parameters:

• level (LogLevel | None)

• serialize (bool)

__init__(level=None, serialize=False)

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)

Emit a log entry.

Parameters:

log_entry (Dict[str, Any]) – The log entry to emit.

Return type:

None

close()

Close any resources used by the handler.

Return type:

None

format(log_entry)

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.handlers.ConsoleHandler(level=None, serialize=False, color=True, use_stderr=False)

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)

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)

Emit a log entry to the console.

Parameters:

log_entry (Dict[str, Any]) – The log entry to emit.

Return type:

None

class ctxlog.handlers.FileHandler(file_path, level=None, serialize=True, rotation=None)

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)

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)

Emit a log entry to the file.

Parameters:

log_entry (Dict[str, Any]) – The log entry to emit.

Return type:

None

close()

Close the file handle.

Return type:

None

__del__()

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

Return type:

None

Handler Base Class

class ctxlog.handlers.Handler(level=None, serialize=False)

Bases: ABC

Base class for log handlers.

Parameters:

• level (LogLevel | None)

• serialize (bool)

__init__(level=None, serialize=False)

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)

Emit a log entry.

Parameters:

log_entry (Dict[str, Any]) – The log entry to emit.

Return type:

None

close()

Close any resources used by the handler.

Return type:

None

format(log_entry)

Format a log entry.

Parameters:

log_entry (Dict[str, Any]) – The log entry to format.

Return type:

str

Returns:

The formatted log entry.

Console Handler

class ctxlog.handlers.ConsoleHandler(level=None, serialize=False, color=True, use_stderr=False)

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)

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)

Emit a log entry to the console.

Parameters:

log_entry (Dict[str, Any]) – The log entry to emit.

Return type:

None

File Handler

class ctxlog.handlers.FileHandler(file_path, level=None, serialize=True, rotation=None)

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)

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)

Emit a log entry to the file.

Parameters:

log_entry (Dict[str, Any]) – The log entry to emit.

Return type:

None

close()

Close the file handle.

Return type:

None

__del__()

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

Return type:

None

File Rotation

class ctxlog.handlers.FileRotation(size=None, time=None, keep=5, compression=None)

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)

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