LeasedExecutorManager

class LeasedExecutorManager(*, backend=ExecutorBackend.THREAD, max_pools, min_pools=1, units_per_pool=10, size_provider=None, check_interval=120.0, default_lease_seconds=300.0, lease_grace_seconds=15.0, workers_per_pool=4, name_prefix='leasepool', logger=None, process_logging=None, forward_process_logs=False, process_log_level=20, process_log_target_logger=None, clear_process_log_handlers=True, **executor_kwargs)

Bases: object

Bounded async manager for leased Executor instances.

The manager supports ThreadPoolExecutor and ProcessPoolExecutor on Python 3.11. Python 3.14+ can add InterpreterPoolExecutor through the same backend hook.

Sizing rule:

desired executors =

max(min_pools, ceil(size_provider() / units_per_pool))

desired executors is capped at max_pools.

Parameters:

• backend (ExecutorBackend | str)

• max_pools (int)

• min_pools (int)

• units_per_pool (int)

• size_provider (SizeProvider | None)

• check_interval (float)

• default_lease_seconds (float)

• lease_grace_seconds (float)

• workers_per_pool (int)

• name_prefix (str)

• logger (logging.Logger | None)

• process_logging (ProcessLoggingConfig | None)

• forward_process_logs (bool)

• process_log_level (int | str)

• process_log_target_logger (logging.Logger | None)

• clear_process_log_handlers (bool)

• executor_kwargs (Any)

property backend: ExecutorBackend

async start()

Return type:

None

async stop()

Return type:

None

async acquire(*, lease_seconds=None, owner=None, wait=True, timeout=None)

Acquire an executor lease.

Parameters:

• lease_seconds (float | None, optional) – The duration of the lease in seconds. Defaults to None.

• owner (str | None, optional) – The owner of the lease. Defaults to None.

• wait (bool, optional) – Whether to wait for an available executor. Defaults to True.

• timeout (float | None, optional) – The maximum time to wait for an available executor in seconds. Defaults to None.

Raises:

• LeasePoolNotStartedError – If the lease pool is not started.

• ValueError – If the lease_seconds is not positive.

• LeaseUnavailableError – If no executor is available and wait is False.

• TimeoutError – If the timeout is reached while waiting for an executor.

• LeasePoolNotStartedError – If the lease pool is not started.

• TimeoutError – If the timeout is reached while waiting for an executor.

Returns:

The acquired executor lease.

Return type:

ExecutorLease

async release(lease_id)

Release an executor lease.

Parameters:

lease_id (str) – The ID of the lease to release.

Return type:

None

notify_scale_changed()

Inform the checker that the size signal changed.

Return type:

None

desired_executor_count()

Return type:

int

property available_count: int

property leased_count: int

property total_count: int

stats()

Get statistics about the executor manager.

Returns:

A dictionary containing statistics about the executor manager.

Return type:

dict[str, Any]

Manual summary

Constructor

LeasedExecutorManager(
    *,
    backend="thread",
    max_pools,
    min_pools=1,
    units_per_pool=10,
    size_provider=None,
    check_interval=120.0,
    default_lease_seconds=300.0,
    lease_grace_seconds=15.0,
    workers_per_pool=4,
    name_prefix="leasepool",
    logger=None,
    process_logging=None,
    forward_process_logs=False,
    process_log_level=logging.INFO,
    process_log_target_logger=None,
    clear_process_log_handlers=True,
    **executor_kwargs,
)

Lifecycle

await manager.start()

Start the manager, create the minimum/desired pool count, and start the checker task.

await manager.stop()

Stop the checker task, clear available and leased pools, shut down owned executors, and stop process log forwarding if it is running.

Acquiring and releasing

await manager.acquire(lease_seconds=None, owner=None, wait=True, timeout=None)

Borrow an executor through an ExecutorLease.

await manager.release(lease_id)

Return a lease manually. Most users call await lease.release() or use the lease as an async context manager instead.

Sizing and diagnostics

manager.notify_scale_changed()

Wake the checker after the adaptive size signal changes.

manager.desired_executor_count()

Return the current adaptive target.

manager.stats()

Return a diagnostic snapshot dictionary.

Common properties

manager.backend

Backend enum.

manager.available_count

Number of idle executor pools.

manager.leased_count

Number of currently leased executor pools.

manager.total_count

Available plus leased executor pools.