|
| 1 | +# ProxyPatternPool |
| 2 | + |
| 3 | +Generic Proxy and Pool classes for Python. |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | +This module provides two classes: |
| 15 | + |
| 16 | +- `Proxy` implements the |
| 17 | + [proxy pattern](https://en.wikipedia.org/wiki/Proxy_pattern), |
| 18 | + i.e. all calls to methods on the proxy are forwarded to an internally wrapped |
| 19 | + object. This allows to solve the classic chicken-and-egg importation and |
| 20 | + initialization possibly circular-dependency issue with Python modules: |
| 21 | + |
| 22 | + ```python |
| 23 | + # File "database.py" |
| 24 | + db = Proxy() |
| 25 | + |
| 26 | + def init_app(config): |
| 27 | + db.set_obj(initialization from config) |
| 28 | + ``` |
| 29 | + |
| 30 | + ```python |
| 31 | + # File "app.py" |
| 32 | + import database |
| 33 | + from database import db # db is a proxy to nothing |
| 34 | + … |
| 35 | + # delayed initialization |
| 36 | + database.init_app(config) |
| 37 | + |
| 38 | + # db is now a proxy to the initialized object |
| 39 | + ``` |
| 40 | + |
| 41 | + When an internal pool is used, method `_ret_obj` **must** be called to return |
| 42 | + the object to the pool when done with it. |
| 43 | + |
| 44 | +- `Pool` implements a full-featured thread-safe pool of things which can be used |
| 45 | + to store expensive-to-create objects such as database connections, to be |
| 46 | + shared between threads for instance. The above proxy object creates a pool |
| 47 | + automatically depending on its parameters. |
| 48 | + |
| 49 | + This generic pool class can be used independently of the `Proxy` class. |
| 50 | + |
| 51 | + It provides numerous hooks to provide callbacks for creation, deletion, |
| 52 | + stats, tracing, health check… which makes it ideal to manage any kind |
| 53 | + of expensive resources within a process. |
| 54 | + |
| 55 | + ```python |
| 56 | + import ProxyPatternPool as ppp |
| 57 | + |
| 58 | + # start a pool with 2 resources created by "fun" |
| 59 | + pool = ppp.Pool( |
| 60 | + fun = lambda n: f"expensive object {n}", |
| 61 | + min_size=2, max_size=2, timeout=0.5, |
| 62 | + ) |
| 63 | + |
| 64 | + # get resources |
| 65 | + a = pool.get(); b = pool.get() # max_size reached |
| 66 | + try: |
| 67 | + c = pool.get() # will timeout after 0.5 seconds |
| 68 | + assert False |
| 69 | + except ppp.TimeOut: |
| 70 | + pass |
| 71 | + |
| 72 | + pool.ret(a); pool.ret(b); # return resources |
| 73 | + |
| 74 | + pool.shutdown() |
| 75 | + del pool |
| 76 | + ``` |
| 77 | + |
| 78 | +## License |
| 79 | + |
| 80 | +This code is [Public Domain](https://creativecommons.org/publicdomain/zero/1.0/). |
| 81 | + |
| 82 | +All software has bug, this is software, hence… Beware that you may lose your |
| 83 | +hairs or your friends because of it. If you like it, feel free to send a |
| 84 | +postcard to the author. |
| 85 | + |
| 86 | +## Versions |
| 87 | + |
| 88 | +[Sources](https://github.com/zx80/proxy-pattern-pool), |
| 89 | +[documentation](https://zx80.github.io/proxy-pattern-pool/) and |
| 90 | +[issues](https://github.com/zx80/proxy-pattern-pool/issues) |
| 91 | +are hosted on [GitHub](https://github.com). |
| 92 | +Install [package](https://pypi.org/project/ProxyPatternPool/) from |
| 93 | +[PyPI](https://pypi.org/). |
| 94 | +See [version details](VERSIONS.md). |
0 commit comments