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.

Project links

• GitHub repository

• PyPI package

Free-threaded Python / no-GIL support

leasepool is a pure Python package and does not ship native extension modules. It is intended to work on CPython free-threaded builds.

Current support level: Stable.

The package declares:

Programming Language :: Python :: Free Threading :: 3 - Stable

User-submitted functions are still responsible for their own thread-safety when executed concurrently.

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
  • Free-threaded Python
• 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
  • Event-loop ownership
• Configuration
  • LeasedExecutorManager
  • Validation notes
  • Process logging configuration
  • Acquire options
  • WorkGrinder
  • Loop ownership
  • 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
  • Broken process pools
  • 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
  • Event-loop ownership
  • 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
  • Broken executors
  • 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?
  • What happens if I release a lease while submitted work is still running?
  • Does lease expiry kill already-running work?
  • Can I call WorkGrinder from another event loop?

API reference

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

Project

• Hosting on Read the Docs
• Contributing
• Changelog