Add --warp-config KEY=VALUE CLI option to examples

[c0d1f1ed]

Description

Add a repeatable --warp-config KEY=VALUE CLI option to the shared example
argument parser so that warp.config attributes can be overridden from the
command line without editing source code.

Closes #2205

Checklist

• New or existing tests cover these changes
• The documentation is up to date with these changes
• CHANGELOG.md has been updated (if user-facing change)

Test plan

uv run --extra dev -m unittest newton.tests.test_warp_config_cli -v

11 unit tests covering integer, string, boolean, None, and empty-string
values, repeated overrides, unknown keys, and malformed entries.

Manual smoke test:

uv run -m newton.examples basic_pendulum --warp-config mode=release
uv run -m newton.examples basic_pendulum --warp-config optimization_level=2 \
    --warp-config verbose=True

New feature / API change

# Override a single warp.config attribute
uv run -m newton.examples basic_pendulum --warp-config optimization_level=2

# Override multiple attributes
uv run -m newton.examples basic_pendulum \
    --warp-config optimization_level=2 \
    --warp-config cpu_compiler_flags=""

Summary by CodeRabbit

• New Features

  • Added a repeatable CLI option (--warp-config KEY=VALUE) to override runtime configuration keys with basic type coercion.

• Tests

  • Added tests covering type parsing (numbers, booleans, None, bare words), repeated overrides, empty values, and error cases for malformed or unknown entries.

• Documentation

  • Changelog updated to document the new CLI override option.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a repeatable --warp-config KEY=VALUE CLI option to the examples parser, validates keys against warp.config, parses values with ast.literal_eval (falling back to raw strings), applies overrides early in init(), and adds unit tests for success and error cases.

Changes

Cohort / File(s)	Summary
Changelog CHANGELOG.md	Documented the new --warp-config KEY=VALUE repeatable CLI option under Unreleased → Added.
CLI & Runtime newton/examples/__init__.py	Added repeatable --warp-config arg in create_parser() (action=append) and new helper _apply_warp_config(parser, args) to validate keys, parse values with ast.literal_eval (fallback to string), and set attributes on warp.config; invoked early in init() before Warp initialization calls.
Tests newton/tests/test_warp_config_cli.py	New test module covering no-op, int/bool/None/string coercion, empty-value handling, repeated-override precedence, parser wiring, and error cases for unknown keys and missing =; includes a unittest entrypoint.

Sequence Diagram(s)

sequenceDiagram
    participant CLI as User (CLI)
    participant Parser as create_parser()/argparse
    participant Apply as _apply_warp_config
    participant Config as warp.config
    participant Init as init()

    CLI->>Parser: invoke example with --warp-config KEY=VALUE...
    Parser->>Parser: parse args (collect warp_config list)
    Parser-->>Apply: init() calls _apply_warp_config(parser, args)
    Apply->>Apply: for each entry: ensure "KEY=VALUE", validate key exists
    Apply->>Apply: parse VALUE via ast.literal_eval (fallback to string)
    Apply->>Config: setattr(warp.config, KEY, parsed_value)
    Apply-->>Init: return after applying overrides
    Init->>Config: proceed with Warp initialization (e.g., device selection)
    Init-->>CLI: example runs using applied config overrides

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• camevor

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly describes the main change: adding a repeatable --warp-config CLI option to examples for overriding warp.config attributes.
Linked Issues check	✅ Passed	The PR implementation fully satisfies all coding requirements from issue #2205: repeatable CLI option [#2205], key validation [#2205], ast.literal_eval parsing with string fallback [#2205], and early application before kernel compilation [#2205].
Out of Scope Changes check	✅ Passed	All changes are directly within scope: CHANGELOG documentation, CLI argument addition, config application logic, and comprehensive unit tests validating the --warp-config feature implementation.
Docstring Coverage	✅ Passed	Docstring coverage is 88.89% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{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!

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@newton/examples/__init__.py`:
- Around line 544-545: The current validation in _apply_warp_config allows
private or dunder keys because it only uses hasattr(wp.config, key); update the
validation to first reject any key that starts with '_' (e.g., if
key.startswith('_') then call parser.error with a message like "invalid
--warp-config key '{key}': private keys are not allowed") before checking
hasattr, and ensure parser.error is used for both private-key and unknown-key
cases; also add the provided test_private_key_rejected unit test to assert
SystemExit and that the stderr contains the private-key rejection message.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: a64dcbea-57a7-4057-86cd-834dd42a5c2f

📥 Commits

Reviewing files that changed from the base of the PR and between ad728e6 and 62bef1b.

📒 Files selected for processing (3)

• CHANGELOG.md
• newton/examples/__init__.py
• newton/tests/test_warp_config_cli.py

✅ Files skipped from review due to trivial changes (1)

• CHANGELOG.md

🚧 Files skipped from review as they are similar to previous changes (1)

• newton/tests/test_warp_config_cli.py

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@newton/examples/__init__.py`:
- Around line 535-539: The code assumes args has a warp_config attribute and
will raise AttributeError when a custom parser calls init(parser) without it;
update the check around args.warp_config to be defensive (e.g., use
getattr(args, 'warp_config', None) or hasattr(args, 'warp_config') and confirm
it's truthy/iterable) before the early return and before iterating over it so
the loop over args.warp_config only runs when the attribute exists and is
non-empty.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

Run ID: bffca2cb-91e7-429c-87d0-ed36cde31e99

📥 Commits

Reviewing files that changed from the base of the PR and between 62bef1b and a438316.

📒 Files selected for processing (3)

• CHANGELOG.md
• newton/examples/__init__.py
• newton/tests/test_warp_config_cli.py

✅ Files skipped from review due to trivial changes (1)

• CHANGELOG.md

🚧 Files skipped from review as they are similar to previous changes (1)

• newton/tests/test_warp_config_cli.py

[eric-heiden]

LGTM!