add return_stale_on_timeout parameter for stale-while-revalidate caching

[zscgeek]

feat: add return_stale_on_timeout parameter for stale-while-revalidate caching

Adds new return_stale_on_timeout parameter that enables returning stale
cached values when wait_for_calc_timeout expires, instead of triggering
a new calculation. This implements a stale-while-revalidate pattern that
keeps applications responsive while ensuring background cache refresh.

Key changes:

• Add return_stale_on_timeout parameter to all cache backends
• Modify core logic to return stale values on RecalculationNeeded exception
• Fix memory core timeout handling to properly check wait_for_calc_timeout
• Add comprehensive test suite with 7 test cases
• Update documentation and maintain backward compatibility

When enabled, the behavior follows this pattern:

1. Fresh values (≤ stale_after) return immediately
2. Stale values trigger background refresh
3. Caller waits up to wait_for_calc_timeout for refresh to complete
4. If timeout expires, return stale value instead of blocking
5. Background refresh continues for next request

[zscgeek]

bugbot run

[codecov]

Codecov Report

Attention: Patch coverage is 26.08696% with 17 lines in your changes missing coverage. Please review.

Project coverage is 63.39%. Comparing base (2a4d1c9) to head (f1c214a).
Report is 86 commits behind head on master.

Files with missing lines	Patch %	Lines
src/cachier/cores/memory.py	15.38%	10 Missing and 1 partial ⚠️
src/cachier/core.py	14.28%	4 Missing and 2 partials ⚠️

❗ There is a different number of reports uploaded between BASE (2a4d1c9) and HEAD (f1c214a). Click for more details.

HEAD has 30 uploads less than BASE

Flag	BASE (2a4d1c9)	HEAD (f1c214a)
	30	0

Additional details and impacted files

@@             Coverage Diff             @@
##           master     #297       +/-   ##
===========================================
- Coverage   97.84%   63.39%   -34.46%     
===========================================
  Files           8       12        +4     
  Lines         511      948      +437     
  Branches       88      108       +20     
===========================================
+ Hits          500      601      +101     
- Misses         10      329      +319     
- Partials        1       18       +17     

Flag	Coverage Δ
mongodb	48.73% <26.08%> (?)
postgres	48.20% <21.73%> (?)
redis	45.88% <21.73%> (?)

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

Files with missing lines	Coverage Δ
src/cachier/config.py	81.01% <100.00%> (ø)
src/cachier/cores/base.py	96.22% <100.00%> (ø)
src/cachier/cores/mongo.py	97.01% <ø> (ø)
src/cachier/cores/pickle.py	22.94% <100.00%> (ø)
src/cachier/cores/redis.py	65.89% <ø> (ø)
src/cachier/cores/sql.py	94.33% <ø> (ø)
src/cachier/core.py	78.97% <14.28%> (ø)
src/cachier/cores/memory.py	27.77% <15.38%> (ø)

... and 2 files with indirect coverage changes

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9d02182...f1c214a. Read the comment docs.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[shaypal5]

Please rebase over master before continuing to work - a lot of new code was added recently. @zscgeek

[zscgeek]

Please rebase over master before continuing to work - a lot of new code was added recently. @zscgeek

Hi! I will do in the next day or so.