From 9fbfe4ea1588e5096d15b480b29e112a0994bd62 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Sun, 27 Oct 2024 07:24:06 +0100 Subject: [PATCH] docs: new house style --- docs/api.md | 2 +- docs/instrumentation.md | 2 +- docs/motivation.md | 6 +++--- docs/testing.md | 4 ++-- docs/tutorial.md | 4 ++-- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/api.md b/docs/api.md index 83ede13..e4fdb21 100644 --- a/docs/api.md +++ b/docs/api.md @@ -44,7 +44,7 @@ ``` -## Activation and Deactivation +## Activation and deactivation ```{eval-rst} .. autofunction:: set_active diff --git a/docs/instrumentation.md b/docs/instrumentation.md index bd6412d..ee97c9f 100644 --- a/docs/instrumentation.md +++ b/docs/instrumentation.md @@ -68,7 +68,7 @@ Use `structlog.stdlib.BoundLogger` and explicit async methods like `ainfo()` ins (logging)= -## Standard Library's `logging` +## Standard library's `logging` If standard library's `logging` integration is active, logging happens at warning level and includes the following *extra fields*: diff --git a/docs/motivation.md b/docs/motivation.md index ed5f2b3..7ee34a6 100644 --- a/docs/motivation.md +++ b/docs/motivation.md @@ -1,6 +1,6 @@ # Motivation -## The Need for Retries +## The need for retries Retries are essential for making distributed systems resilient. Transient errors are unavoidable and can happen for the wildest reasons: @@ -15,7 +15,7 @@ And sometimes, one never finds out because a [cosmic ray](https://en.wikipedia.o The bigger the scale, the more likely it is that something will go wrong -- but the chance is never zero. -## The Dangers of Retries +## The dangers of retries However, retries are also very dangerous if done naïvely. Simply repeating an operation until it succeeds can lead to [*cascading failures*](https://en.wikipedia.org/wiki/Cascading_failure) and [*thundering herds*](https://en.wikipedia.org/wiki/Thundering_herd_problem) and ultimately take down your whole system, just because a database had a brief hiccup. @@ -60,7 +60,7 @@ You can [tune all these parameters](stamina.retry) to your liking, but the defau I hope you're now all motivated and ready to jump into our {doc}`tutorial`! -## Supplemental Literature +## Supplemental literature - The [*Exponential Backoff And Jitter*](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) article on the *AWS Architecture Blog* is a good explanation of the basics with pretty graphs. - [*Resiliency in Distributed Systems*](https://blog.pragmaticengineer.com/resiliency-in-distributed-systems/) takes a broader view and explains how to build resilient systems in general. diff --git a/docs/testing.md b/docs/testing.md index 96e2cfe..f5fa678 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -3,7 +3,7 @@ Testing code with retry logic can be tricky, so *stamina* provides dedicated testing helpers that allow you to affect retrying behavior *globally*. -## Turn Off Retries +## Turn off retries The easiest way is to turn off retries using {func}`stamina.set_active`: @@ -19,7 +19,7 @@ def deactivate_retries(): This is a great approach when you're only using our decorator-based API. -## Limiting Retries +## Limiting retries :::{versionadded} 24.3.0 ::: diff --git a/docs/tutorial.md b/docs/tutorial.md index d08339c..3353e98 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -62,7 +62,7 @@ def do_it(code: int) -> httpx.Response: To give you observability of your application's retrying, *stamina* will count the retries using [*prometheus-client*](https://github.com/prometheus/client_python) in the `stamina_retries_total` counter (if installed) and log them out using [*structlog*](https://www.structlog.org/) with a fallback to {mod}`logging`. -## Arbitrary Code Blocks +## Arbitrary code blocks Sometimes you only want to retry a part of a function. @@ -77,7 +77,7 @@ for attempt in stamina.retry_context(on=httpx.HTTPError): ``` -## Retry One Function or Method Call +## Retry one function or method call If you want to retry just one function or method call, *stamina* comes with an even easier way in the shape of {class}`stamina.RetryingCaller` and {class}`stamina.AsyncRetryingCaller`: