Add S3 backend core

[shaypal5]

Summary

Closes #41.

Adds a new s3 backend to cachier, allowing function results to be persistently cached in AWS S3 (or any S3-compatible service: MinIO, localstack, etc.).

• New backend: @cachier(backend="s3", s3_bucket="my-bucket") - same decorator API as all other cores
• Flexible client config: pass a pre-built boto3 client (s3_client), a callable factory (s3_client_factory), or let the core auto-create one from s3_region / s3_endpoint_url / s3_config
• Data model: one pickled CacheEntry per cache key, stored at <s3_prefix>/<func_str>/<cache_key>.pkl
• Async: async cached functions are supported via asyncio.to_thread delegation (boto3 is sync-only)
• No import-time warnings: boto3 absence is only signalled when the S3 core is actually instantiated

Files changed

File	Change
src/cachier/cores/s3.py	New _S3Core class implementing the full _BaseCore interface
src/cachier/_types.py	Add S3Client type alias; extend Backend literal with "s3"
src/cachier/core.py	Wire S3 decorator parameters; import and instantiate _S3Core
pyproject.toml	Add s3 pytest marker; add [project.optional-dependencies] extras
tests/s3_tests/	18 tests using moto[s3] (no real AWS account required)
tests/requirements_s3.txt	boto3 + moto[s3] test deps
examples/s3_example.py	Runnable demo

Test plan

• pytest -m s3 - all 18 S3 tests pass (uses moto for offline mocking)
• pytest -m "not (mongo or redis or sql or s3)" - 219 existing tests pass, 0 regressions
• ruff check - no linting errors on changed files
• mypy src/cachier/ - only pre-existing SQL overload error; boto3 stubs handled with # type: ignore[import-untyped]

Open questions (from issue)

The following points from the original issue are left for follow-up if desired:

• Async s3_client_factory (currently sync-only, matching boto3's nature)
• Server-side encryption options in the core API
• Multipart uploads for very large cached values

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 18.22917% with 157 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.57%. Comparing base (85539dc) to head (2827e10).

Files with missing lines	Patch %	Lines
src/cachier/cores/s3.py	16.21%	155 Missing ⚠️
src/cachier/core.py	50.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##            master     #338      +/-   ##
===========================================
- Coverage   100.00%   90.57%   -9.43%     
===========================================
  Files           11       12       +1     
  Lines         1477     1666     +189     
  Branches       185      209      +24     
===========================================
+ Hits          1477     1509      +32     
- Misses           0      156     +156     
- Partials         0        1       +1     

Flag	Coverage Δ
local	58.16% <18.22%> (-5.28%)	⬇️
mongodb	40.93% <18.22%> (-3.21%)	⬇️
postgres	43.93% <18.22%> (-3.46%)	⬇️
redis	47.41% <18.22%> (-3.91%)	⬇️

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

Files with missing lines	Coverage Δ
src/cachier/_types.py	100.00% <100.00%> (ø)
src/cachier/core.py	99.38% <50.00%> (-0.62%)	⬇️
src/cachier/cores/s3.py	16.21% <16.21%> (ø)

---

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 85539dc...2827e10. Read the comment docs.

🚀 New features to boost your workflow:

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