feat: Show summary of used methods on CLI with wakepy -v

[fohrloop]

Previously, running "wakepy -v" would just enable INFO level logging. Now it also prints a summary of used (and unused) methods just before the wakepy logo.

Previously it was possible to see the list of associated wakepy Methods only in case of failure. Now user may see them with the -v flag.

Example:

$ wakepy -v
...
2026-01-15 00:38:14,722 - INFO - Unsupported wakepy Methods on LINUX, "keep.running" Mode: ['caffeinate', 'SetThreadExecutionState']
2026-01-15 00:38:14,727 - INFO - Activated wakepy mode "keep.running" with method: org.gnome.SessionManager

Wakepy Methods (in the order of attempt):

  1. org.freedesktop.PowerManagement
     FAIL: DBusCallError("DBus call of method 'Inhibit' on interface
     'org.freedesktop.PowerManagement.Inhibit' with args ('wakepy', 'wakelock
     active') failed with message: [org.freedesktop.DBus.Error.ServiceUnknown]
     ('The name org.freedesktop.PowerManagement was not provided by any .service
     files',)")

  2. org.gnome.SessionManager
     SUCCESS

  3. caffeinate
     UNSUPPORTED: caffeinate is not supported on LINUX. The supported platforms
     are: MACOS

  4. SetThreadExecutionState
     UNSUPPORTED: SetThreadExecutionState is not supported on LINUX. The
     supported platforms are: WINDOWS
                         _
                        | |
        __      __ __ _ | | __ ___  _ __   _   _
        \ \ /\ / // _` || |/ // _ \| '_ \ | | | |
         \ V  V /| (_| ||   <|  __/| |_) || |_| |
          \_/\_/  \__,_||_|\_\\___|| .__/  \__, |
         v.0.10.2.post2.dev78+ge9cb| |      __/ |
                                   |_|     |___/ 
 ┏━━ Mode: keep.running ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
 ┃                                                      ┃
 ┃  [✔] Programs keep running                           ┃
 ┃  [ ] Display kept on, screenlock disabled            ┃
 ┃                                                      ┃
 ┃   Method: org.gnome.SessionManager                   ┃
 ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 ⠎⡱                                [Press Ctrl+C to exit] 

Closes: #550

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

A substantial refactor of the CLI module replacing monolithic rendering with modular architecture. Introduces a new public main() entry point, CliApp class for command dispatch, DisplayTheme configuration object, and numerous render_* utility functions for decoupled UI presentation.

Changes

Cohort / File(s)	Summary
Core CLI Architecture Refactor src/wakepy/__main__.py	Major structural reorganization: new public main() entry point and CliApp class replace monolithic renderer pattern. Introduces DisplayTheme dataclass, SystemInfo TypedDict, and modular render_* functions (logo, info_box, deprecations, error messages, activation errors, methods output). Adds argument parsing via parse_args(), logging setup via setup_logging(), spinner animation via spinner_frames() and wait_for_interrupt(). Refactors mode/command dispatch and deprecation handling.
Test Suite Updates tests/unit/test_main.py	Updated tests to exercise new public APIs: render_* functions, spinner_frames(), wait_for_interrupt(). Removes tests for internal CLIRenderer and SessionData. Reworked fixtures and assertions to use capsys and direct render utility validation. Adds coverage for new CliApp injection pattern and error message expectations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat: CLI command "wakepy methods" testing all wakepy Methods of a Mode #566: Adds and wires the "wakepy methods" subcommand; directly shares the parse_args(), CLI dispatch, CliApp.run_wakepy_methods(), and render_methods_output() implementation.
• Separate data from presentation logic in __main__.py + fix boolean traps #544: Refactors CLI presentation and data separation through DisplayTheme, CliApp, and rendering changes; shares overlapping architectural modifications to the same module.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.82% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: Show summary of used methods on CLI with wakepy -v' directly describes the main feature being added—displaying a summary of used methods on the CLI when using the -v flag. It aligns with the substantial refactoring of the CLI architecture and new rendering utilities introduced in the changeset.
Description check	✅ Passed	The pull request description follows the required template structure with motivation, implementation details, and issue reference.

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

---

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

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 819494b and cb512c9.

📒 Files selected for processing (2)

• src/wakepy/__main__.py
• tests/unit/test_main.py

🧰 Additional context used

📓 Path-based instructions (2)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Use mypy strict mode with full type annotations
Maintain 100% test coverage
Place top-level functions before subfunctions in file organization
Place imports at the top of the file, not inside functions

Files:

• tests/unit/test_main.py
• src/wakepy/__main__.py

tests/**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

tests/**/*.py: Use pytest with test classes for organizing tests
Prefer using fixtures in tests instead of inline setup

Files:

• tests/unit/test_main.py

🪛 GitHub Actions: Fast Tests 🚀

tests/unit/test_main.py

[error] 12-12: Error during test collection due to ImportError in wakepy.main.

src/wakepy/__main__.py

[error] 24-24: ImportError: cannot import name 'TypedDict' from 'typing' (Python 3.7) - TypedDict is not available in this Python version.

🔇 Additional comments (21)

src/wakepy/__main__.py (11)

60-84: LGTM!

The display layout constants are well-defined, and wait_for_interrupt correctly handles the KeyboardInterrupt for graceful termination.

---

87-115: LGTM!

The DisplayTheme dataclass is well-structured with immutability enforced via frozen=True. The factory method pattern with create() provides a clean API for theme instantiation.

---

117-121: LGTM once the import is fixed.

The SystemInfo TypedDict is well-defined. This will work correctly after resolving the TypedDict import issue flagged earlier.

---

123-137: LGTM!

The main() function cleanly implements dependency injection for testability. The command dispatch logic correctly handles both the default mode and the "methods" subcommand.

---

139-182: LGTM!

The argument parsing is well-structured with good reuse of _add_mode_arguments for both the main command and the "methods" subcommand.

---

185-206: LGTM!

The mode determination logic is clear and handles deprecated flags gracefully. The conflict detection with a helpful error message is appropriate.

---

275-360: LGTM!

The CliApp class is well-structured with clear separation of concerns. The run_wakepy method properly handles the mode lifecycle, verbose output, and graceful termination.

---

363-376: LGTM!

The get_system_info factory and spinner_frames generator are well-implemented. The # pragma: no branch comment correctly handles coverage for the infinite loop.

---

379-410: LGTM!

The rendering functions properly handle string truncation to maintain consistent layout, and the template formatting is clean.

---

413-469: LGTM!

The rendering utilities are well-organized with consistent text wrapping. The activation error message provides helpful diagnostic information for issue reporting.

---

472-533: LGTM!

The render_methods_output function cleanly handles both verbose and non-verbose modes. The _add_mode_arguments helper promotes DRY by reusing argument definitions across parsers.

tests/unit/test_main.py (10)

10-29: Imports are blocked by the upstream TypedDict issue.

The imports from wakepy.__main__ will fail until the TypedDict import compatibility issue is resolved in the source file. Once fixed, these imports are correctly structured.

---

37-76: LGTM!

The fixtures are well-organized using pytest's fixture pattern as per coding guidelines, providing reusable test components for working and broken methods.

---

79-116: LGTM!

The TestGetModeName class provides thorough coverage of mode selection logic with well-organized parametrized tests for different argument combinations.

---

130-154: LGTM!

Good coverage for wait_for_interrupt edge cases including keyboard interrupt handling and empty iterator. The tests correctly use capsys for output verification.

---

157-215: LGTM!

The TestCliAppRunWakepy class provides comprehensive coverage of the main CLI flow, including success, failure, custom theme, and deprecation warning scenarios.

---

217-257: LGTM!

The verbose mode tests properly cover both cases where method information is available and when it's empty, verifying the appropriate output in each scenario.

---

259-363: LGTM!

The TestCliAppRunWakepyMethods class provides thorough testing of the methods subcommand with good coverage of both verbose and non-verbose output formats, plus injection testing via probe_runner.

---

365-404: LGTM!

The TestDisplayTheme and TestShouldUseAsciiOnly classes provide comprehensive coverage of theme creation and ASCII mode detection across different platforms.

---

407-519: LGTM!

The TestRendering class provides excellent coverage of all rendering functions, including edge cases like long name truncation and infinite spinner frame generation.

---

521-578: LGTM!

The TestMain and TestGetLoggingLevel classes properly test the entry point and logging configuration with good use of mocking and parametrization.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}