leasepool documentation

leasepool is a local executor orchestration library for async Python applications.

It helps async services safely borrow execution capacity from ThreadPoolExecutor and ProcessPoolExecutor backends using leases, backpressure, expiry, adaptive sizing, batch submission, and clean shutdown.

Python 3.11+ support includes:

• thread backend for blocking I/O and legacy synchronous SDKs.

• process backend for CPU-heavy Python work.

• interpreter backend reserved for Python 3.14+ InterpreterPoolExecutor.

Warning

leasepool is not a distributed task queue. It is not a replacement for Celery, Dramatiq, RQ, Ray, or a message broker. It manages local executor capacity inside one Python process.

User guide

• Installation
  • Install from PyPI
  • Install from source
  • Install documentation dependencies
  • Build documentation locally
  • Python support
• Quickstart
  • Basic thread backend
  • Context-managed leases
  • Manual release
  • CPU work with the process backend
  • Batch many small jobs with WorkGrinder
• Core concepts
  • Executor backend
  • Executor pool
  • Lease
  • Safe executor proxy
  • Backpressure
  • Adaptive sizing
  • WorkGrinder
  • Process log forwarding
• Configuration
  • LeasedExecutorManager
  • Process logging configuration
  • Acquire options
  • WorkGrinder
  • max_pools is per manager
• Thread backend
  • Good uses
  • Example
  • Context manager pattern
  • Avoid
• Process backend
  • Good uses
  • Pickling rules
  • Basic example
  • Keyword arguments
  • Executor kwargs
  • Operational notes
• Process log forwarding
  • Explicit configuration
  • Convenience configuration
  • Configuration fields
  • Composing worker initializers
  • When to enable it
• WorkGrinder
  • How batching works
  • Basic submit
  • enqueue
  • submit_from_thread
  • Shutdown behavior
  • Diagnostics
• Adaptive sizing
  • Example
  • Sizing rule
  • Notify changes
  • Shrinking behavior
  • Failure behavior
• Error handling
  • leasepool exceptions
  • Acquire before start
  • No capacity available
  • Expired leases
  • Full exception example
• FastAPI pattern
• Examples
  • Example map
  • Complete walkthrough
  • FastAPI pattern
• FAQ
  • Is leasepool a task queue?
  • Should I use threads or processes?
  • Can I submit async functions?
  • Is max_pools global?
  • What happens if every pool is leased?
  • What happens after a lease expires?
  • Can I use InterpreterPoolExecutor on Python 3.11?
  • Why do worker-process logs not appear in my app logs?
  • Can I pass executor-specific options?

API reference

• API reference
  • LeasedExecutorManager
  • ExecutorLease
  • WorkGrinder
  • Backends
  • Process logging
  • Exceptions

Project

• Hosting on Read the Docs
• Contributing
• Changelog