stamina

Name	stamina JSON
Version	24.2.0 JSON
	download
home_page
Summary	Production-grade retries made easy.
upload_time	2024-01-31 06:24:21
maintainer
docs_url	None
author
requires_python	>=3.8
license
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.
Its 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.
- 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.
- Easy _global_ deactivation for testing.

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

- `stamina.RetryingCaller` and `stamina.AsyncRetryingCaller` that allow even easier retries of single callables: `stamina.RetryingCaller(attempts=5).on(ValueError)(do_something, "foo", bar=42)` and `stamina.RetryingCaller(attempts=5)(ValueError, do_something, "foo", bar=42)` will call `do_something("foo", bar=42)` and retry on `ValueError` up to 5 times.

  `stamina.RetryingCaller` and `stamina.AsyncRetryingCaller` take the same arguments as `stamina.retry()`, except for `on` that can be bound separately.

  [#56](https://github.com/hynek/stamina/pull/56)
  [#57](https://github.com/hynek/stamina/pull/57)


---

[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/).

            

Raw data

            {
    "_id": null,
    "home_page": "",
    "name": "stamina",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "",
    "keywords": "reliability,retries,retry",
    "author": "",
    "author_email": "Hynek Schlawack <hs@ox.cx>",
    "download_url": "https://files.pythonhosted.org/packages/49/07/b1af55673b02c3651d2a0a57582513cc1f4a7a5433f551acfb1bff889fc5/stamina-24.2.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.\nIts 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.\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- Easy _global_ deactivation for testing.\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- `stamina.RetryingCaller` and `stamina.AsyncRetryingCaller` that allow even easier retries of single callables: `stamina.RetryingCaller(attempts=5).on(ValueError)(do_something, \"foo\", bar=42)` and `stamina.RetryingCaller(attempts=5)(ValueError, do_something, \"foo\", bar=42)` will call `do_something(\"foo\", bar=42)` and retry on `ValueError` up to 5 times.\n\n  `stamina.RetryingCaller` and `stamina.AsyncRetryingCaller` take the same arguments as `stamina.retry()`, except for `on` that can be bound separately.\n\n  [#56](https://github.com/hynek/stamina/pull/56)\n  [#57](https://github.com/hynek/stamina/pull/57)\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",
    "bugtrack_url": null,
    "license": "",
    "summary": "Production-grade retries made easy.",
    "version": "24.2.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": "c776ece8e6a0ef80306838d43b966f7792ab2319ed973c5b33696c189b6f35ee",
                "md5": "1f90747bc3c7c29f4d6d979606002644",
                "sha256": "4dbd8076d2cb4e228046833e4507af3406cc31b9b6046e8a6729ffde934b2526"
            },
            "downloads": -1,
            "filename": "stamina-24.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "1f90747bc3c7c29f4d6d979606002644",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 14879,
            "upload_time": "2024-01-31T06:24:18",
            "upload_time_iso_8601": "2024-01-31T06:24:18.947551Z",
            "url": "https://files.pythonhosted.org/packages/c7/76/ece8e6a0ef80306838d43b966f7792ab2319ed973c5b33696c189b6f35ee/stamina-24.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4907b1af55673b02c3651d2a0a57582513cc1f4a7a5433f551acfb1bff889fc5",
                "md5": "0f8f79c1e9d27654aaf9df3cdbcd4820",
                "sha256": "8db72126f2342e428b153cbcf837f8a90f89b783aa55e19d4a17193116ee35ee"
            },
            "downloads": -1,
            "filename": "stamina-24.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "0f8f79c1e9d27654aaf9df3cdbcd4820",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 553055,
            "upload_time": "2024-01-31T06:24:21",
            "upload_time_iso_8601": "2024-01-31T06:24:21.371082Z",
            "url": "https://files.pythonhosted.org/packages/49/07/b1af55673b02c3651d2a0a57582513cc1f4a7a5433f551acfb1bff889fc5/stamina-24.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-01-31 06:24:21",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "hynek",
    "github_project": "stamina",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "stamina"
}