Install & Compatibility
Where this runs
tested against v1.4.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.223s · 23.9MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.197s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pond
✓ from pond import Pond
PooledObjectFactory
✓ from pond import PooledObjectFactory
✗ from pondpond import PooledObjectFactory
The PyPI package is 'pondpond', but the importable module is 'pond'.
This quickstart demonstrates how to set up an object pool using `pond`. It involves defining a `PooledObjectFactory` to manage the lifecycle (creation, destruction, validation, activation, passivation) of your custom objects. An instance of `Pond` is then created with this factory, allowing objects to be borrowed from and recycled back into the pool.
import time
import threading
from pond import Pond, PooledObjectFactory
# Define a factory for the objects to be pooled
class MyObject:
def __init__(self, name):
self.name = name
self.created_at = time.time()
self.is_active = True
def do_work(self):
return f"Object {self.name} working. Active: {self.is_active}"
def cleanup(self):
self.is_active = False
return f"Object {self.name} cleaned up."
class MyObjectFactory(PooledObjectFactory):
def __init__(self, name_prefix):
self.name_prefix = name_prefix
self._counter = 0
self._lock = threading.Lock()
def create(self):
with self._lock:
self._counter += 1
obj = MyObject(f"{self.name_prefix}-{self._counter}")
print(f"Created: {obj.name}")
return obj
def destroy(self, obj):
print(f"Destroyed: {obj.cleanup()}")
def validate(self, obj):
# Example validation: object must be active
return obj.is_active
def activate(self, obj):
# Reset object state if necessary before borrowing
obj.is_active = True
print(f"Activated: {obj.name}")
return obj
def passivate(self, obj):
# Prepare object for recycling (e.g., clear transient data)
obj.is_active = False
print(f"Passivated: {obj.name}")
# Instantiate the Pond with our factory
# max_size: maximum number of objects to keep in the pool
# time_between_eviction_runs: interval in seconds for cleaning up idle objects
factory = MyObjectFactory("worker")
pool = Pond(factory, max_size=5, time_between_eviction_runs=5)
# Borrow objects
obj1 = pool.borrow()
print(obj1.do_work())
obj2 = pool.borrow()
print(obj2.do_work())
# Recycle objects
pool.recycle(obj1)
pool.recycle(obj2)
# Borrow again (should get recycled objects first)
obj3 = pool.borrow()
print(obj3.do_work())
# Simulate some time for eviction to run (if time_between_eviction_runs > -1)
print("Waiting for potential eviction...")
time.sleep(7)
# Close the pool to destroy all remaining objects
pool.close()
print("Pool closed.")
Errors
Common errors & fixes
ImportError: cannot import name 'Pond' from 'pondpond'
The Python package is installed as `pondpond`, but the primary import statement for the library's components, like `Pond` or `PooledObjectFactory`, uses `pond` as the module name.
fixAlways use `from pond import <Symbol>` for importing components of the library, e.g., `from pond import Pond, PooledObjectFactory`.
ModuleNotFoundError: No module named 'madoka'
Starting from `pondpond` version 1.3.0, the `madoka` library became a required runtime dependency for performance improvements, and it must be explicitly installed.
fixInstall the `madoka` dependency using pip: `pip install madoka`.
AttributeError: 'PooledObject' object has no attribute 'my_method'
When you borrow an object from the `Pond`, it returns a `PooledObject` wrapper. To access the actual underlying object and its methods, you must call the `use()` method on the `PooledObject` first.
fixAfter borrowing, access the actual object using `.use()`: `pooled_object = pool.borrow('my_factory_name')
my_actual_object = pooled_object.use()
my_actual_object.my_method()` Upgrade
Version history
1.4.1latest on PyPI · released Mar 1, 2024
Audit
Dependencies
madokarequiredUsed for approximate counting of object pool usage, replacing the 'Count-min sketch' in versions 1.3.0 and above.