test: fix latent doctests + competitive suite, declare competitor test deps

[27Bslash6]

Hygiene sweep of three latent issues, none caught by gating CI (it runs targeted tests/unit+tests/critical paths, and --doctest-modules only covers tests/, never src/).

1. Broken src doctests

Failed under pytest --doctest-modules src/:

• backends/base.py — RedisBackend() requires DI/config, so bare construction raised and the follow-up isinstance line NameErrord. Switched to issubclass(RedisBackend, BaseBackend), which demonstrates the runtime-checkable protocol without a live backend.
• reliability/metrics_collection.py — doctest called a non-existent clear_metrics(). Removed it; the "api_calls" in metrics assertion holds regardless of prior state (no need to invent a function for one doctest).

2. Undeclared competitor test deps

tests/competitive/ hard-imports cachetools and aiocache, but neither was declared — the whole comparison suite failed to collect. Declared both in [dependency-groups] dev.

3. Un-rotted 3 competitive tests (test bugs, not product regressions — verified)

Declaring the deps un-hid 3 bit-rotted tests:

• tuple / nested-tuple preservation asserted the obsolete "L1 serializes -> list" behavior. cachekit's L1-only (backend=None) path now stores native object references (no serialization), so tuples are preserved. Updated assertions + docstrings to match (confirmed via direct probe).
• test_cachekit_has_ttl used time_machine, which does not drive L1's time.time() expiry in that path. Switched to a real short sleep; L1 TTL itself is correct (verified with real time).

Verification

• pytest --doctest-modules src/cachekit/backends/base.py src/cachekit/reliability/metrics_collection.py -> 3 passed, 5 skipped
• pytest tests/competitive/ -> 92 passed, 1 skipped (was: collection error)
• ruff check/format clean; make type-check scope is src only (unaffected)

Summary by CodeRabbit

• Tests

  • Updated tuple handling tests to align with L1-only preservation behaviour
  • Enhanced TTL expiry validation using real-time execution

• Chores

  • Added cachetools and aiocache to development dependencies

• Documentation

  • Refined docstring examples and doctest documentation for clarity

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

This PR updates dev dependencies, clarifies documentation examples to match actual behaviour, and refactors competitive tests to assert that cachekit preserves tuple types in L1-only mode and to use real sleep-based timing for TTL validation instead of clock mocking.

Changes

Dependency, Documentation, and Test Updates

Layer / File(s)	Summary
Dev dependency setup pyproject.toml	Added cachetools>=5.3.0 and aiocache>=0.12.0 to development dependencies for enhanced testing support.
Docstring example updates src/cachekit/backends/base.py, src/cachekit/reliability/metrics_collection.py	Updated BaseBackend and get_all_metrics() doctest examples to remove unnecessary setup steps and use cleaner runtime protocol checks that reflect actual usage patterns.
Tuple preservation test updates tests/competitive/test_head_to_head.py	Consolidated module imports, updated test assertions and commentary to verify that tuples are preserved in L1-only caching mode rather than converted to lists, covering both top-level and nested tuple scenarios.
TTL test refactoring tests/competitive/test_head_to_head.py	Replaced time_machine clock patching with real time.sleep() waiting to reliably validate TTL expiry and re-execution behaviour without system clock mocking.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• cachekit-io/cachekit-py#94: Both PRs modify tests/competitive/test_head_to_head.py's TTL test logic but in opposite directions—test: eliminate flaky time.sleep() tests with time-machine #94 introduced time_machine clock-shifting whilst this PR reverts to real time.sleep() for timing control.

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 62.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	❓ Inconclusive	The description covers the three main issues and verification steps, but omits most required template sections like Type of Change, Security Checklist, and Testing checkboxes.	Complete the pull request template by selecting the appropriate Type of Change checkbox and confirming that security and testing checklists have been reviewed.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarises the main changes: fixing latent doctests, resolving competitive suite issues, and declaring missing test dependencies.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/hygiene-doctests-competitive-deps

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!