| Name | stamina JSON |
| Version |
24.3.0
JSON |
| download |
| home_page | None |
| Summary | Production-grade retries made easy. |
| upload_time | 2024-08-27 14:54:16 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
reliability
retries
retry
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# *stamina*: Production-grade Retries Made Easy
Transient failures are common in distributed systems.
To make your systems resilient, you need to **retry** failed operations.
But bad retries can make things *much worse*.
*stamina* is an opinionated wrapper around the great-but-unopinionated [Tenacity](https://tenacity.readthedocs.io/) package.
Our goal is to be as **ergonomic** as possible, while doing the **right thing by default**, and minimizing the potential for **misuse**.
It is the result of years of copy-pasting the same configuration over and over again:
- Retry only on certain exceptions – or even a subset of them by introspecting them first using a predicate.
- Exponential **backoff** with **jitter** between retries.
- Limit the number of retries **and** total time.
- Automatic **async** support – including [Trio](https://trio.readthedocs.io/).
- Preserve **type hints** of the decorated callable.
- Flexible **instrumentation** with [Prometheus](https://github.com/prometheus/client_python), [*structlog*](https://www.structlog.org/), and standard library's `logging` support out-of-the-box.
- Dedicated support for **testing** that allows to _globally_ deactivate retries, or to limit the number of retries and to remove backoffs.
For example:
```python
import httpx
import stamina
@stamina.retry(on=httpx.HTTPError, attempts=3)
def do_it(code: int) -> httpx.Response:
resp = httpx.get(f"https://httpbin.org/status/{code}")
resp.raise_for_status()
return resp
```
<!-- end docs index -->
**Async** callables work use the same API and it's possible to retry **arbitrary blocks**, too.
Check out our [tutorial](https://stamina.hynek.me/en/latest/tutorial.html) for more examples!
## Release Information
### Added
- The *on* argument in all retry functions now can be a callable that takes an exception and returns a bool which decides whether or not a retry should be scheduled.
[#70](https://github.com/hynek/stamina/pull/70)
- `stamina.Attempt` now has a `next_wait` attribute that contains the time the *next* backoff will wait, if the *current* attempt fails (sans jitter).
[#72](https://github.com/hynek/stamina/pull/72)
- It is now possible to switch *stamina* into a testing mode using `stamina.set_testing()`.
It disables backoffs and caps the number of retries.
[#73](https://github.com/hynek/stamina/pull/73)
---
[Full Changelog →](https://github.com/hynek/stamina/blob/main/CHANGELOG.md)
## Credits
*stamina* is written by [Hynek Schlawack](https://hynek.me/) and distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
The development is kindly supported by my employer [Variomedia AG](https://www.variomedia.de/) and all my amazing [GitHub Sponsors](https://github.com/sponsors/hynek).
This project would not be possible without the years of incredible work that went into [Tenacity](https://tenacity.readthedocs.io/).
## *stamina* for Enterprise
Available as part of the [Tidelift Subscription](https://tidelift.com/?utm_source=lifter&utm_medium=referral&utm_campaign=hynek).
The maintainers of *stamina* and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open-source packages you use to build your applications.
Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
Raw data
{
"_id": null,
"home_page": null,
"name": "stamina",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "reliability, retries, retry",
"author": null,
"author_email": "Hynek Schlawack <hs@ox.cx>",
"download_url": "https://files.pythonhosted.org/packages/c8/35/afe1f3467e840f414cfea90993c5a94490a6360eb3653236c3a7de099cf6/stamina-24.3.0.tar.gz",
"platform": null,
"description": "# *stamina*: Production-grade Retries Made Easy\n\nTransient failures are common in distributed systems.\nTo make your systems resilient, you need to **retry** failed operations.\nBut bad retries can make things *much worse*.\n\n*stamina* is an opinionated wrapper around the great-but-unopinionated [Tenacity](https://tenacity.readthedocs.io/) package.\nOur goal is to be as **ergonomic** as possible, while doing the **right thing by default**, and minimizing the potential for **misuse**.\nIt is the result of years of copy-pasting the same configuration over and over again:\n\n- Retry only on certain exceptions \u2013 or even a subset of them by introspecting them first using a predicate.\n- Exponential **backoff** with **jitter** between retries.\n- Limit the number of retries **and** total time.\n- Automatic **async** support \u2013 including [Trio](https://trio.readthedocs.io/).\n- Preserve **type hints** of the decorated callable.\n- Flexible **instrumentation** with [Prometheus](https://github.com/prometheus/client_python), [*structlog*](https://www.structlog.org/), and standard library's `logging` support out-of-the-box.\n- Dedicated support for **testing** that allows to _globally_ deactivate retries, or to limit the number of retries and to remove backoffs.\n\nFor example:\n\n```python\nimport httpx\n\nimport stamina\n\n\n@stamina.retry(on=httpx.HTTPError, attempts=3)\ndef do_it(code: int) -> httpx.Response:\n resp = httpx.get(f\"https://httpbin.org/status/{code}\")\n resp.raise_for_status()\n\n return resp\n```\n\n<!-- end docs index -->\n\n**Async** callables work use the same API and it's possible to retry **arbitrary blocks**, too.\nCheck out our [tutorial](https://stamina.hynek.me/en/latest/tutorial.html) for more examples!\n\n\n\n## Release Information\n\n### Added\n\n- The *on* argument in all retry functions now can be a callable that takes an exception and returns a bool which decides whether or not a retry should be scheduled.\n [#70](https://github.com/hynek/stamina/pull/70)\n\n- `stamina.Attempt` now has a `next_wait` attribute that contains the time the *next* backoff will wait, if the *current* attempt fails (sans jitter).\n [#72](https://github.com/hynek/stamina/pull/72)\n\n- It is now possible to switch *stamina* into a testing mode using `stamina.set_testing()`.\n It disables backoffs and caps the number of retries.\n [#73](https://github.com/hynek/stamina/pull/73)\n\n\n---\n\n[Full Changelog \u2192](https://github.com/hynek/stamina/blob/main/CHANGELOG.md)\n\n\n## Credits\n\n*stamina* is written by [Hynek Schlawack](https://hynek.me/) and distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n\nThe development is kindly supported by my employer [Variomedia AG](https://www.variomedia.de/) and all my amazing [GitHub Sponsors](https://github.com/sponsors/hynek).\n\nThis project would not be possible without the years of incredible work that went into [Tenacity](https://tenacity.readthedocs.io/).\n\n\n## *stamina* for Enterprise\n\nAvailable as part of the [Tidelift Subscription](https://tidelift.com/?utm_source=lifter&utm_medium=referral&utm_campaign=hynek).\n\nThe maintainers of *stamina* and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open-source packages you use to build your applications.\nSave time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.\n",
"bugtrack_url": null,
"license": null,
"summary": "Production-grade retries made easy.",
"version": "24.3.0",
"project_urls": {
"Changelog": "https://github.com/hynek/stamina/blob/main/CHANGELOG.md",
"Documentation": "https://stamina.hynek.me/",
"Funding": "https://github.com/sponsors/hynek",
"Mastodon": "https://mastodon.social/@hynek",
"Source": "https://github.com/hynek/stamina",
"Twitter": "https://twitter.com/hynek"
},
"split_keywords": [
"reliability",
" retries",
" retry"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d81818b0b93812cc0a69a0b17c591dca1a3779aeab7f0ff094dee51f4a6bcd3",
"md5": "b4674caf08fdb8e876a804c58e1db8c0",
"sha256": "28caf1a5db514256d86e32b60621630552fa9a60dace4e6fb5c78ba15f26236e"
},
"downloads": -1,
"filename": "stamina-24.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b4674caf08fdb8e876a804c58e1db8c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16445,
"upload_time": "2024-08-27T14:54:14",
"upload_time_iso_8601": "2024-08-27T14:54:14.448258Z",
"url": "https://files.pythonhosted.org/packages/7d/81/818b0b93812cc0a69a0b17c591dca1a3779aeab7f0ff094dee51f4a6bcd3/stamina-24.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c835afe1f3467e840f414cfea90993c5a94490a6360eb3653236c3a7de099cf6",
"md5": "cfa8ea681c10b9ebd7831804e7684441",
"sha256": "1d763c98962ca11f1729c357422926a750a138e803e7beb9f9d6c99d33d9997d"
},
"downloads": -1,
"filename": "stamina-24.3.0.tar.gz",
"has_sig": false,
"md5_digest": "cfa8ea681c10b9ebd7831804e7684441",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 558536,
"upload_time": "2024-08-27T14:54:16",
"upload_time_iso_8601": "2024-08-27T14:54:16.996652Z",
"url": "https://files.pythonhosted.org/packages/c8/35/afe1f3467e840f414cfea90993c5a94490a6360eb3653236c3a7de099cf6/stamina-24.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-27 14:54:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hynek",
"github_project": "stamina",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "stamina"
}
