Skip to content

docs: fix facts in docs and the missing-client error message - #97

Merged
lesnik512 merged 1 commit into
mainfrom
docs/fix-facts
Oct 3, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/fix-facts

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Summary

Several statements in the docs and README did not match the code, and one error message gave advice the broker cannot follow.

Changes

  • docs/introduction/installation.md: "Python 3.13+" changed to 3.11+, matching requires-python = ">=3.11,<4" in pyproject.toml.
  • Worst-case idle latency was documented as max_polling_interval × 1.5. subscriber/schedule.py:50 computes min(base * 2**n * jitter, max_idle), so jitter is applied before the cap and the worst case is max_polling_interval. Fixed in how-it-works.md and subscriber.md; the jitter mentions in README.md and the subscriber.md table now say it is applied before the cap.
  • docs/usage/basic.md: timeline_key / payloads_key are prefixes; TimerStore._keys (store.py:95-97) builds {key}:{topic}.
  • how-it-works.md pointed to the broker docstring for the Cluster restriction, but that docstring does not mention it. The check is broker.py:142, which raises TypeError; the docs now say so.
  • subscriber.md: removed "NoCast-typed"; the example uses StreamMessage[TimerMessage].
  • publisher.md: removed an unused StreamMessage import.
  • router.md: async def handle_invoice(...): ... was not valid Python; it now byte-compiles.
  • configs.py:28: "Connection not available. Connect the broker first." The client only comes from the constructor (broker.py:150, ConnectionState(client)); connect() cannot supply one. New message: "TimersBroker has no Redis client; pass one to TimersBroker(client)." The existing test now asserts the message; it failed before the change.
  • Plainer wording in basic.md for timer ID overwrites and cancel_all side effects.

All Python blocks in README.md and docs/ byte-compile, ruff reports no unused imports in them, and the three testing.md examples pass under pytest.

Checklist

  • Lint and format pass (ruff)
  • Type check passes (ty)
  • Tests pass and new behavior is covered
  • Build succeeds (uv build) if packaging or build config changed
  • Repo metadata stays consistent across the three surfaces (GitHub description, pyproject description, profile blurb) if this touches packaging

- Python requirement is 3.11+, matching requires-python.
- Idle backoff jitter is applied before the cap, so worst-case idle
  latency is max_polling_interval, not 1.5x.
- timeline_key and payloads_key are per-topic key prefixes.
- Redis Cluster: the constructor raises TypeError.
- Drop "NoCast-typed" and an unused import from examples.
- Make the router prefix example valid Python.
- Missing-client error now says to pass a client to TimersBroker.
- Plainer wording on timer ID overwrite and cancel_all side effects.
@lesnik512
lesnik512 merged commit 055521d into main Oct 3, 2026
13 checks passed
@lesnik512
lesnik512 deleted the docs/fix-facts branch October 3, 2026 10:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant