Add Client Middleware Cookbook

[bdraco]

Adds client middleware cookbook and examples

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.76%. Comparing base (06e3b36) to head (d6e01a7).
Report is 7 commits behind head on master.

✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #10945      +/-   ##
==========================================
- Coverage   98.77%   98.76%   -0.01%     
==========================================
  Files         129      129              
  Lines       39539    39541       +2     
  Branches     2186     2185       -1     
==========================================
  Hits        39054    39054              
- Misses        337      339       +2     
  Partials      148      148              

Flag	Coverage Δ
CI-GHA	98.64% <ø> (-0.01%)	⬇️
OS-Linux	98.35% <ø> (-0.01%)	⬇️
OS-Windows	96.53% <ø> (-0.01%)	⬇️
OS-macOS	97.51% <ø> (+<0.01%)	⬆️
Py-3.10.11	97.40% <ø> (-0.01%)	⬇️
Py-3.10.17	97.93% <ø> (-0.01%)	⬇️
Py-3.11.12	98.02% <ø> (-0.01%)	⬇️
Py-3.11.9	97.48% <ø> (-0.01%)	⬇️
Py-3.12.10	98.41% <ø> (-0.01%)	⬇️
Py-3.13.3	98.41% <ø> (+<0.01%)	⬆️
Py-3.9.13	97.27% <ø> (-0.01%)	⬇️
Py-3.9.22	97.76% <ø> (-0.05%)	⬇️
Py-pypy7.3.16	93.50% <ø> (+8.52%)	⬆️
VM-macos	97.51% <ø> (+<0.01%)	⬆️
VM-ubuntu	98.35% <ø> (-0.01%)	⬇️
VM-windows	96.53% <ø> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[codspeed-hq]

CodSpeed Performance Report

Merging #10945 will not alter performance

_{Comparing client_middleware_cookbook (d6e01a7) with master (5e68276)}

Summary

✅ 59 untouched benchmarks

[Copilot]

Pull Request Overview

This PR adds a new Client Middleware Cookbook with practical examples, integrates it into the main client docs, updates the spelling wordlist, and adds a CHANGES entry.

• Introduce a comprehensive client_middleware_cookbook.rst with multiple middleware patterns.
• Link the new cookbook in docs/client.rst and add “backoff” to the spelling wordlist.
• Add a CHANGES file placeholder entry for this feature.

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
docs/spelling_wordlist.txt	Added “backoff” to the approved spelling list.
docs/client_middleware_cookbook.rst	New cookbook covering Basic Auth, retry, logging, and token refresh middleware.
docs/client.rst	Inserted navigation link to the Client Middleware Cookbook.
CHANGES/10945.feature.rst	Created feature entry (filename and content need alignment).

Comments suppressed due to low confidence (2)

docs/client_middleware_cookbook.rst:305

• ClientRequest does not have a session attribute; request.session will likely be undefined. Consider passing the ClientSession instance into the middleware (e.g., store it on init) or otherwise provide access to the session for token refresh calls.

await self._refresh_access_token(request.session)

CHANGES/10945.feature.rst:1

• The change entry references 9732.feature.rst but the filename is 10945.feature.rst. Update the internal reference to match the correct feature number.

9732.feature.rst

[patchback]

Backport to 3.12: 💚 backport PR created

✅ Backport PR branch: patchback/backports/3.12/18785096b3628f682f950c612d8acb68333629ba/pr-10945

Backported as #10969

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.