Metadata-Version: 2.4
Name: opnieuw
Version: 3.4.0
Summary: Retries for humans
Author-email: ruud@channable.com
License: BSD 3-Clause License
        
        Copyright (c) 2019, Channable
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        * Redistributions of source code must retain the above copyright notice, this
          list of conditions and the following disclaimer.
        
        * Redistributions in binary form must reproduce the above copyright notice,
          this list of conditions and the following disclaimer in the documentation
          and/or other materials provided with the distribution.
        
        * Neither the name of the copyright holder nor the names of its
          contributors may be used to endorse or promote products derived from
          this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Project-URL: Homepage, https://github.com/channable/opnieuw
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 6 - Mature
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typing-extensions>=4.5.0; python_version < "3.10"
Dynamic: license-file

Opnieuw
=======

Opnieuw is a general-purpose retrying library, written in Python, in
order to simplify the task of adding retry behavior to both synchronous as well
as asynchronous tasks. Opnieuw is easy and straightforward to use.

Opnieuw makes it easy to add robust retries:

 * There is a single retry strategy, exponential backoff with jitter, which
   makes it impossible to forget to add jitter.
 * It has just two parameters, to eliminate the possibility of invalid and
   nonsensical combinations.
 * Parameters are named clearly, to avoid confusing e.g. number of calls
   (including the initial one) with number of retries (excluding the initial
   call).
 * The parameters are intuitive: instead of configuring the base delay for
   exponential backoff, Opnieuw accepts a maximum number of calls to make, and
   maximum time after the first call to still retry.
 * Time units are clear from parameter names to make the decorated code obvious,
   and readable without needing to refer to documentation.

See our [announcement post][post] for a bit more background on why we wrote
Opnieuw.

Example
-------

Suppose we want to parse `https://tech.channable.com/atom.xml` and we want to
add a retry to handle a specific network Exception. We can add Opnieuw to our
network handler as follows:

```python
import requests
from requests.exceptions import ConnectionError, HTTPError

from opnieuw import retry

@retry(
    retry_on_exceptions=(ConnectionError, HTTPError),
    max_calls_total=4,
    retry_window_after_first_call_in_seconds=60,
)
def get_page() -> str:
    response = requests.get('https://tech.channable.com/atom.xml')
    return response.text
```

 * `retry_on_exceptions` specifies which exceptions we want to retry on.

 * `max_calls_total` is the maximum number of times that the decorated function
   gets called, including the initial call.

 * `retry_window_after_first_call_in_seconds` is the maximum number of seconds
   after the first call was initiated, where we would still do a new attempt.

Features
--------

 * Generic decorator API
 * Specify retry exception (i.e. type of exception that we want retry)
 * [Exponential backoff with jitter][exponential-backoff]
 * Pre-shipped list of popular exceptions, which can easily be expanded

Installation
------------

To install Opnieuw, simply:

    $ pip install opnieuw

More examples
--------

The short example above provides a concise demonstration of how Opnieuw could
be used. Let's dig deeper into Opnieuw and add another exception to
`retry_on_exceptions` to do a retry on:

```python
from urllib.error import URLError
import requests
from opnieuw import RetryException, retry

@retry(
    retry_on_exceptions=(ConnectionError, RetryException, URLError),
    max_calls_total=4,
    retry_window_after_first_call_in_seconds=60,
)
def get_page() -> str:
    response = requests.get('https://tech.channable.com/atom.xml')

    if response.status_code != 200:
        raise RetryException

    return response.text
```

We can pass the name of exception we want do retry for or a tuple of exceptions
to the `retry_on_exceptions`. As mentioned earlier Opnieuw was developed to
make it more convenient to add retry behavior to any task.

Let's make it a little bit more generic and define a list of retry exceptions
that should trigger a retry of the function:

```python
STANDARD_HTTP_EXCEPTIONS = (
    ConnectionError,
    ProtocolError,
    RetryException,
    ...
)

@retry(
    retry_on_exceptions=STANDARD_HTTP_EXCEPTIONS,
    max_calls_total=4,
    retry_window_after_first_call_in_seconds=60,
)
def get_page() -> str:
    response = requests.post('https://tech.channable.com/atom.xml')
    return response.text
```

Now our retry is more generic, as exceptions raised which are in
`STANDARD_HTTP_EXCEPTIONS` will be retried.

If you want retry behavior for async tasks, then there is also an async retry
which basically work the same way, but for async tasks.

Here is the example above but in async mode:

```python
from opnieuw import retry_async

STANDARD_HTTP_EXCEPTIONS = (
    ConnectionError,
    EOFError,
    RetryException,
    ...
)

@retry_async(
    retry_on_exceptions=STANDARD_HTTP_EXCEPTIONS,
    max_calls_total=4,
    retry_window_after_first_call_in_seconds=60,
)
async def get_page() -> str:
    response = requests.get('https://tech.channable.com/atom.xml')
    return response.text
```

[post]: https://tech.channable.com/posts/2020-02-05-opnieuw.html
[exponential-backoff]: https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
