Process logging

class ProcessLoggingConfig(enabled=False, level=20, target_logger=None, clear_child_handlers=True)

Bases: object

Configuration for forwarding ProcessPoolExecutor worker logs.

This is intentionally opt-in. Normal leasepool logs are emitted in the parent process through normal Python loggers and do not need this bridge.

Parameters:

• enabled (bool)

• level (int | str)

• target_logger (Logger | None)

• clear_child_handlers (bool)

enabled

Enable child-process log forwarding.

level

Minimum level configured on the child-process root logger.

target_logger

Parent-process logger that receives records from workers. If omitted, LeasedExecutorManager’s logger is used.

clear_child_handlers

Remove inherited/preconfigured child handlers before installing the queue handler. This avoids duplicate child logs after fork and prevents children from writing directly to stderr.

enabled: bool

level: int | str

target_logger: Logger | None

clear_child_handlers: bool

Low-level helpers

These helpers are public in the module primarily for advanced users and tests. Most applications should configure process log forwarding through ProcessLoggingConfig or the LeasedExecutorManager convenience arguments.

class ProcessLoggingConfig(enabled=False, level=20, target_logger=None, clear_child_handlers=True)

Bases: object

Configuration for forwarding ProcessPoolExecutor worker logs.

This is intentionally opt-in. Normal leasepool logs are emitted in the parent process through normal Python loggers and do not need this bridge.

Parameters:

• enabled (bool)

• level (int | str)

• target_logger (Logger | None)

• clear_child_handlers (bool)

enabled

Enable child-process log forwarding.

level

Minimum level configured on the child-process root logger.

target_logger

Parent-process logger that receives records from workers. If omitted, LeasedExecutorManager’s logger is used.

clear_child_handlers

Remove inherited/preconfigured child handlers before installing the queue handler. This avoids duplicate child logs after fork and prevents children from writing directly to stderr.

enabled: bool

level: int | str

target_logger: Logger | None

clear_child_handlers: bool

coerce_log_level(level)

Return a numeric logging level from an int or standard level name.

Return type:

int

Parameters:

level (int | str)

class LoggerForwardingHandler(target_logger)

Bases: Handler

QueueListener target that forwards records into a parent logger.

QueueListener normally writes records directly to concrete handlers. This handler instead re-enters the parent’s logger hierarchy, so the application keeps control over formatters, handlers, filters, propagation, and levels.

Initialize the handler with a target logger.

Parameters:

target_logger (logging.Logger) – The parent logger to which records will be forwarded.

__init__(target_logger)

Initialize the handler with a target logger.

Parameters:

target_logger (logging.Logger) – The parent logger to which records will be forwarded.

emit(record)

Forward a log record to the target logger.

Parameters:

record (logging.LogRecord) – The log record to be forwarded.

Return type:

None

configure_process_worker_logging(log_queue, *, level, clear_existing_handlers)

Install QueueHandler on the worker process root logger.

Parameters:

• log_queue (Any) – The multiprocessing queue to which log records will be sent. If None, logging is not configured.

• level (int | str) – Minimum logging level for the worker process root logger.

• clear_existing_handlers (bool) – Whether to remove existing handlers from the root logger before adding the QueueHandler.

Return type:

None

process_worker_initializer(log_queue, level, clear_existing_handlers, user_initializer, user_initargs)

ProcessPoolExecutor initializer used by leasepool.

It first configures child-process logging, then calls the user’s original initializer, if one was supplied to ProcessPoolExecutor.

Parameters:

• log_queue (Any | None) – The multiprocessing queue to which log records will be sent. If None, logging is not configured.

• level (int | str) – Minimum logging level for the worker process root logger.

• clear_existing_handlers (bool) – Whether to remove existing handlers from the root logger before adding the QueueHandler.

• user_initializer (Callable[..., Any] | None) – The original initializer function supplied by the user to ProcessPoolExecutor, if any.

• user_initargs (tuple[Any, ...]) – The original initializer arguments supplied by the user to ProcessPoolExecutor, if any.

Return type:

None

build_queue_listener(*, log_queue, target_logger)

Create the parent-side listener for child-process log records.

Parameters:

• log_queue (Any) – The multiprocessing queue from which log records will be received.

• target_logger (Logger) – The parent logger to which received log records will be forwarded.

Return type:

QueueListener