V5 develop hierarchical parsing

[BrianPugh]

Add App.parse_mode ("fallthrough" / "strict") to control how flags are scoped across command levels in meta-app hierarchies. "strict" mode requires meta-app options to appear at the appropriate location; fallthrough (default) preserves existing behavior.

Addresses #627 #630 #730. @isoschiz @cdb39 @oeko2002 I was wondering if you could test out this PR in your applications? This branch is based off of v5-develop, but v5 should be like 99% compatible with any v4 app.

[codecov]

Codecov Report

❌ Patch coverage is 96.69811% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.42%. Comparing base (6f026fd) to head (41b9799).
⚠️ Report is 1 commits behind head on v5-develop.

Files with missing lines	Patch %	Lines
cyclopts/core.py	94.48%	3 Missing and 4 partials ⚠️

Additional details and impacted files

@@              Coverage Diff               @@
##           v5-develop     #776      +/-   ##
==============================================
+ Coverage       90.22%   90.42%   +0.19%     
==============================================
  Files              71       71              
  Lines            8553     8741     +188     
  Branches         1917     1959      +42     
==============================================
+ Hits             7717     7904     +187     
  Misses            467      467              
- Partials          369      370       +1     

Flag	Coverage Δ
unittests	90.36% <96.69%> (+0.20%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds a new App.parse_mode setting to control how options are scoped across meta-app / subcommand boundaries, enabling either strict scoping or fallthrough behavior with improved UX (help/completion/error hints).

Changes:

• Introduces parse_mode on App (inheritance via parent defaults) and implements strict vs fallthrough parsing behavior in meta-app forwarding scenarios.
• Adds token segmentation/partitioning helpers to support hierarchical parsing and token reassembly.
• Expands tests and documentation to cover parse_mode, command indices, and strict help display behavior.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
cyclopts/core.py	Core implementation of parse_mode, command index tracking, scoped parsing, and strict help parameter filtering.
cyclopts/bind.py	Adds helpers (segment_tokens_by_command, partition_tokens) and supports supplying explicit positional_tokens to binding.
cyclopts/argument/_collection.py	Extends ArgumentCollection.copy() to support reset_tokens for safe throwaway parse passes.
cyclopts/exceptions.py	Enhances UnknownOptionError with parent-scope context for strict-mode placement hints.
cyclopts/completion/_base.py	Excludes parent meta flags from subcommand completions in strict mode.
tests/test_parse_mode.py	Comprehensive tests for strict/fallthrough scoping, token reassembly expectations, help display, and edge cases.
tests/test_parse_command_indices.py	Tests internal _parse_commands indices and confirms public parse_commands API remains unchanged.
tests/test_segment_tokens.py	Unit tests for token segmentation helper.
tests/test_app_attribute_inheritance.py	Verifies parse_mode defaulting/inheritance/override behavior on Apps.
docs/source/parse_mode.rst	New user-facing documentation for parse modes, examples, help behavior, and inheritance.
docs/source/index.rst	Adds parse_mode doc page to the documentation TOC.
docs/source/api.rst	Documents App.parse_mode in the API reference.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[octo-yart]

Hello,
Tried this branch on our code base, seems to work fine. I identified two caveats.

First one : when adding a '*argument' to a sub-command, it fails to mask the global 'argument' one (in the meta-app). Not a too serious problem (not so much of a legitimate case).

Second one : when adding another "--version" as a parameter for a sub-command, it fails to mask the global one (the command added automaticaly).

Everything else seems fine (and. thanks, that is a really usefull evolution of cyclopts).

[BrianPugh]

thanks for the feedback @octo-yart! I committed some changes, can you give it another try?