# Saiyaku: Auto-Retry Decorator for Python
Saiyaku, inspired by the Japanese term meaning "disaster" or "calamity," is a Python decorator that allows you to automatically retry a function when a specified exception occurs. It can be useful in scenarios where you want to handle transient errors gracefully by retrying the operation.
---
## Installation
```bash
pip install saiyaku
```
## API
### retry decorator
```python
def retry(exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1, jitter=0, logger=logging_logger):
"""Return a retry decorator.
:param exceptions: an exception or a tuple of exceptions to catch. default: Exception.
:param tries: the maximum number of attempts. default: -1 (infinite).
:param delay: initial delay between attempts. default: 0.
:param max_delay: the maximum value of delay. default: None (no limit).
:param backoff: multiplier applied to delay between attempts. default: 1 (no backoff).
:param jitter: extra seconds added to delay between attempts. default: 0.
fixed if a number, random if a range tuple (min, max)
:param logger: logger.warning(fmt, error, delay) will be called on failed attempts.
default: retry.logging_logger. if None, logging is disabled.
"""
```
Various retrying logic can be achieved by combination of arguments.
#### Examples
```python
from saiyaku import retry
```
```python
@retry()
def make_trouble():
'''Retry until succeed'''
```
```python
@retry(ZeroDivisionError, tries=3, delay=2)
def make_trouble():
'''Retry on ZeroDivisionError, raise error after 3 attempts, sleep 2 seconds between attempts.'''
```
```python
@retry((ValueError, TypeError), delay=1, backoff=2)
def make_trouble():
'''Retry on ValueError or TypeError, sleep 1, 2, 4, 8, ... seconds between attempts.'''
```
```python
@retry((ValueError, TypeError), delay=1, backoff=2, max_delay=4)
def make_trouble():
'''Retry on ValueError or TypeError, sleep 1, 2, 4, 4, ... seconds between attempts.'''
```
```python
@retry(ValueError, delay=1, jitter=1)
def make_trouble():
'''Retry on ValueError, sleep 1, 2, 3, 4, ... seconds between attempts.'''
```
```python
# If you enable logging, you can get warnings like 'ValueError, retrying in
# 1 seconds'
if __name__ == '__main__':
import logging
logging.basicConfig()
make_trouble()
```
### retry_call
```python
def retry_call(f, fargs=None, fkwargs=None, exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1,
jitter=0,
logger=logging_logger):
"""
Calls a function and re-executes it if it failed.
:param f: the function to execute.
:param fargs: the positional arguments of the function to execute.
:param fkwargs: the named arguments of the function to execute.
:param exceptions: an exception or a tuple of exceptions to catch. default: Exception.
:param tries: the maximum number of attempts. default: -1 (infinite).
:param delay: initial delay between attempts. default: 0.
:param max_delay: the maximum value of delay. default: None (no limit).
:param backoff: multiplier applied to delay between attempts. default: 1 (no backoff).
:param jitter: extra seconds added to delay between attempts. default: 0.
fixed if a number, random if a range tuple (min, max)
:param logger: logger.warning(fmt, error, delay) will be called on failed attempts.
default: retry.logging_logger. if None, logging is disabled.
:returns: the result of the f function.
"""
```
This is very similar to the decorator, except that it takes a function and its arguments as parameters. The use case behind it is to be able to dynamically adjust the retry arguments.
```python
import requests
from saiyaku import retry_call
def make_trouble(service, info=None):
if not info:
info = ''
r = requests.get(service + info)
return r.text
def what_is_my_ip(approach=None):
if approach == "optimistic":
tries = 1
elif approach == "conservative":
tries = 3
else:
# skeptical
tries = -1
result = retry_call(make_trouble, fargs=["http://ipinfo.io/"], fkwargs={"info": "ip"}, tries=tries)
print(result)
what_is_my_ip("conservative")
```
---
- This package is created based on [invl/retry](https://github.com/invl/retry) 🔥🚀
Raw data
{
"_id": null,
"home_page": "https://github.com/animemoeus/saiyaku",
"name": "saiyaku",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "saiyaku,retry,decorator,auto-retry,animemoeus",
"author": "Arter Tendean",
"author_email": "arter.tendean.07@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/56/7f/4e0dcbf47966b5e3347d9bbf329169543b6eff12081ae4a29803cf99f409/saiyaku-2023.12.11.tar.gz",
"platform": null,
"description": "# Saiyaku: Auto-Retry Decorator for Python\n\nSaiyaku, inspired by the Japanese term meaning \"disaster\" or \"calamity,\" is a Python decorator that allows you to automatically retry a function when a specified exception occurs. It can be useful in scenarios where you want to handle transient errors gracefully by retrying the operation.\n\n---\n\n## Installation\n\n```bash\npip install saiyaku\n```\n\n## API\n\n### retry decorator\n\n```python\n def retry(exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1, jitter=0, logger=logging_logger):\n \"\"\"Return a retry decorator.\n\n :param exceptions: an exception or a tuple of exceptions to catch. default: Exception.\n :param tries: the maximum number of attempts. default: -1 (infinite).\n :param delay: initial delay between attempts. default: 0.\n :param max_delay: the maximum value of delay. default: None (no limit).\n :param backoff: multiplier applied to delay between attempts. default: 1 (no backoff).\n :param jitter: extra seconds added to delay between attempts. default: 0.\n fixed if a number, random if a range tuple (min, max)\n :param logger: logger.warning(fmt, error, delay) will be called on failed attempts.\n default: retry.logging_logger. if None, logging is disabled.\n \"\"\"\n```\n\nVarious retrying logic can be achieved by combination of arguments.\n\n#### Examples\n\n```python\n from saiyaku import retry\n```\n\n```python\n @retry()\n def make_trouble():\n '''Retry until succeed'''\n```\n\n```python\n @retry(ZeroDivisionError, tries=3, delay=2)\n def make_trouble():\n '''Retry on ZeroDivisionError, raise error after 3 attempts, sleep 2 seconds between attempts.'''\n```\n\n```python\n @retry((ValueError, TypeError), delay=1, backoff=2)\n def make_trouble():\n '''Retry on ValueError or TypeError, sleep 1, 2, 4, 8, ... seconds between attempts.'''\n```\n\n```python\n @retry((ValueError, TypeError), delay=1, backoff=2, max_delay=4)\n def make_trouble():\n '''Retry on ValueError or TypeError, sleep 1, 2, 4, 4, ... seconds between attempts.'''\n```\n\n```python\n @retry(ValueError, delay=1, jitter=1)\n def make_trouble():\n '''Retry on ValueError, sleep 1, 2, 3, 4, ... seconds between attempts.'''\n```\n\n```python\n # If you enable logging, you can get warnings like 'ValueError, retrying in\n # 1 seconds'\n if __name__ == '__main__':\n import logging\n logging.basicConfig()\n make_trouble()\n```\n\n### retry_call\n\n```python\n def retry_call(f, fargs=None, fkwargs=None, exceptions=Exception, tries=-1, delay=0, max_delay=None, backoff=1,\n jitter=0,\n logger=logging_logger):\n \"\"\"\n Calls a function and re-executes it if it failed.\n\n :param f: the function to execute.\n :param fargs: the positional arguments of the function to execute.\n :param fkwargs: the named arguments of the function to execute.\n :param exceptions: an exception or a tuple of exceptions to catch. default: Exception.\n :param tries: the maximum number of attempts. default: -1 (infinite).\n :param delay: initial delay between attempts. default: 0.\n :param max_delay: the maximum value of delay. default: None (no limit).\n :param backoff: multiplier applied to delay between attempts. default: 1 (no backoff).\n :param jitter: extra seconds added to delay between attempts. default: 0.\n fixed if a number, random if a range tuple (min, max)\n :param logger: logger.warning(fmt, error, delay) will be called on failed attempts.\n default: retry.logging_logger. if None, logging is disabled.\n :returns: the result of the f function.\n \"\"\"\n```\n\nThis is very similar to the decorator, except that it takes a function and its arguments as parameters. The use case behind it is to be able to dynamically adjust the retry arguments.\n\n```python\n import requests\n\n from saiyaku import retry_call\n\n\n def make_trouble(service, info=None):\n if not info:\n info = ''\n r = requests.get(service + info)\n return r.text\n\n\n def what_is_my_ip(approach=None):\n if approach == \"optimistic\":\n tries = 1\n elif approach == \"conservative\":\n tries = 3\n else:\n # skeptical\n tries = -1\n result = retry_call(make_trouble, fargs=[\"http://ipinfo.io/\"], fkwargs={\"info\": \"ip\"}, tries=tries)\n print(result)\n\n what_is_my_ip(\"conservative\")\n```\n\n---\n\n- This package is created based on [invl/retry](https://github.com/invl/retry) \ud83d\udd25\ud83d\ude80\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Auto-Retry Decorator for Python",
"version": "2023.12.11",
"project_urls": {
"Documentation": "https://github.com/animemoeus/saiyaku#saiyaku-auto-retry-decorator-for-python",
"Homepage": "https://github.com/animemoeus/saiyaku",
"Repository": "https://github.com/animemoeus/saiyaku"
},
"split_keywords": [
"saiyaku",
"retry",
"decorator",
"auto-retry",
"animemoeus"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "40b04aa898a6a4b6035be94d29e2bb0be83b4d23acee452bd185b42a7aec78ac",
"md5": "5e2ed7b3d8f25ea797ffa02f3baf22e9",
"sha256": "73fe8acfa34270f470df6f48a8bcae31f03bab1f51feee869c8cda4e34b61096"
},
"downloads": -1,
"filename": "saiyaku-2023.12.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5e2ed7b3d8f25ea797ffa02f3baf22e9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 8344,
"upload_time": "2023-12-11T02:00:17",
"upload_time_iso_8601": "2023-12-11T02:00:17.671484Z",
"url": "https://files.pythonhosted.org/packages/40/b0/4aa898a6a4b6035be94d29e2bb0be83b4d23acee452bd185b42a7aec78ac/saiyaku-2023.12.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "567f4e0dcbf47966b5e3347d9bbf329169543b6eff12081ae4a29803cf99f409",
"md5": "bf1162062cce13bafee54924d19872fb",
"sha256": "7d5334ab1e2900d75271f18c156b289210f836b23018ddbc0d1dc4a84f3dccb7"
},
"downloads": -1,
"filename": "saiyaku-2023.12.11.tar.gz",
"has_sig": false,
"md5_digest": "bf1162062cce13bafee54924d19872fb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 7198,
"upload_time": "2023-12-11T02:00:19",
"upload_time_iso_8601": "2023-12-11T02:00:19.620568Z",
"url": "https://files.pythonhosted.org/packages/56/7f/4e0dcbf47966b5e3347d9bbf329169543b6eff12081ae4a29803cf99f409/saiyaku-2023.12.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-11 02:00:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "animemoeus",
"github_project": "saiyaku",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "saiyaku"
}
JSON
