Repository navigation
Rename Timer to MonotonicTimer - #590
Merged
Merged
Conversation
github-actions
Bot
added
part:docs
llucax
marked this pull request as ready for review
November 5, 2026 14:57
llucax
requested review from
daniel-zullo-frequenz and
shsms
and removed request for
a team
November 5, 2026 14:57
There was a problem hiding this comment.
🟡 Changes recommended
Moving Timer behind __getattr__ without adding it to __all__ breaks existing wildcard imports, causing NameError instead of a deprecation warning.
1 open issue
What changed in this PR
Renames the monotonic-clock receiver to MonotonicTimer, preparing the Timer name for a future wall-clock implementation. The old name remains a deprecated alias intended to preserve compatibility until v2.0.0.
Changes:
- Rename the class and add the deprecated alias without changing timer behavior.
- Update documentation, examples, and existing tests to use
MonotonicTimer. - Add tests for alias identity, deprecation warnings, and warning-free construction.
| File | Description |
|---|---|
tests/test_timer.py |
Migrate timer tests and add deprecation checks. |
tests/test_timer_integration.py |
Use the renamed timer in integration tests. |
tests/test_file_watcher_integration.py |
Update timer usage in file-watcher tests. |
src/frequenz/channels/timer.py |
Rename the class, add the alias, and update API documentation. |
src/frequenz/channels/_select.py |
Update the timer example in the docstring. |
src/frequenz/channels/__init__.py |
Update the receiver overview documentation. |
RELEASE_NOTES.md |
Document migration and planned alias removal. |
README.md |
Update example imports and timer construction. |
docs/user-guide/utilities/timers.md |
Point the user guide to MonotonicTimer. |
Review effort: Balanced
shsms
previously approved these changes
Nov 5, 2026
`Timer` uses the event loop's monotonic clock, which the name doesn't say. Renaming it makes that explicit and frees the name `Timer` for a wall clock timer in a later version. `Timer` stays as a deprecated alias made with `deprecated_aliases()`, so it is the very same class and existing code keeps working, including `isinstance()` checks and type annotations mixing both names. The deprecations guide suggests a separate deprecated subclass for types users construct, which type checkers would report, but then a `MonotonicTimer` created by updated code wouldn't be a `Timer` for code not updated yet, and users would get type errors, not only deprecation notices, while migrating. The warning also says the name will be reused, so users don't think it is gone for good. Every use in the code, docstrings and tests now uses `MonotonicTimer`. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
`Timer` is now a deprecated alias, so point the examples and the timers page at its new name. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
Explain the rename of `Timer` to `MonotonicTimer`, why it happened and how to migrate. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
`Timer` is now only reachable through the module `__getattr__`, and without an `__all__` a star import only picks up names defined in the module, so `from frequenz.channels.timer import *` silently stopped providing `Timer`, failing later with a `NameError` instead of a deprecation warning. List every public name, `Timer` included: a star import looks up each name in `__all__`, which goes through `__getattr__` and warns. Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>
llucax
force-pushed
the
monotonic-timer
branch
from
November 5, 2026 16:37
f9278ba to
4c7dffd
Compare
shsms
approved these changes
Nov 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Timeruses the event loop's monotonic clock; the new name says so and freesTimerfor a wall clock timer (#584).Timerstays as a deprecated alias (deprecated_aliases(), since v1.13.0) until v2.0.0 (#365), and its warning says the name will come back as a wall clock timer.I kept an alias instead of the deprecated subclass the deprecations guide suggests for types users construct: with a subclass, a
MonotonicTimerisn't aTimer, so code migrated piece by piece (an updated library feeding a not-yet-updated app) would get type errors and failingisinstance()checks, not just deprecation warnings.Fixes #582.