Support for *args, positional-only parameters given positionally and function/method groups instantiated as callables

[mauvilsa]

What does this PR do?

Fixes #514

Signatures with *args or positional-only parameters are now supported.

• *args: added as a list argument named like the parameter, e.g. *files: str becomes files of type list[str]. With as_positional=True it becomes a positional that takes zero or more values, which argparse is unable to combine with subcommands, so as_positional=False is required then, e.g. for a class whose methods become subcommands in auto_cli. The AST resolver now follows a *args that is forwarded to other calls. It is replaced by what those calls take positionally, including their own *args, as long as all the calls agree. If the code uses *args itself, or its use can't be resolved, it is added as a list argument. If it is not used, it is left out.
• Positional-only parameters: instantiate, auto_cli and from_config now pass positional-only parameters positionally when calling. When *args has values, the parameters before it are passed positionally too. Before, these calls failed.
• Function and method groups instantiated as callables: add_function_arguments and add_method_arguments have a new instantiate parameter. When the group is instantiated, it is replaced by a functools.partial with the arguments bound. For a method called with an instance, it becomes an operator.methodcaller. Links applied on instantiate can now target these groups' parameters. instantiate=False keeps a group as the parsed namespace. In v4.53.0 the old behavior is kept and deprecated for groups with a nested_key. The deprecation warning shows only with JSONARGPARSE_DEPRECATION_WARNINGS=all. The migration guide explains the change.

This PR also changes add_subcommands to raise an error when the parser already has a positional that accepts a variable number of values, since argparse parses this combination incorrectly, e.g. taking the subcommand name as one of the values.

And it fixes:

• The AST resolver failed for methods whose self is positional-only.
• A typed positional with nargs="*" set in a config file was reset to empty when no values for it were given on the command line.
• A positional-only parameter that has a default was added as a required argument, even though the call can omit it.

Before submitting

• Did you read the contributing guideline?
• If you used a coding agent, did you fully understand and validate all generated code and ensure it follows the contributing guidelines?
• Did you update the documentation? (readme and public docstrings)
• Did you write unit tests such that there is 100% coverage on related code? (required for bug fixes and new features)
• Did you verify that new and existing tests pass locally?
• If this is a bug fix, did you verify that the tests fail without the code fix?
• Did you make sure that all changes preserve backward compatibility?
• Did you update the CHANGELOG including a pull request link? (not for typos, docs, test updates, or minor internal changes/refactors)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (ed8211e) to head (4e41bc2).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##              main      #986    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files           27        27            
  Lines         9170      9309   +139     
==========================================
+ Hits          9170      9309   +139     

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

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the previous compatibility issue is fixed and no new actionable failures remain.

Summary

This PR adds end-to-end support for positional-only and variadic positional parameters and allows function and method argument groups to instantiate as bound callables.

• Records call layouts and reconstructs positional and keyword arguments during instantiation, auto_cli, and from_config.
• Resolves forwarded *args through AST call targets while conservatively retaining unresolved or incompatible signatures.
• Instantiates function groups as functools.partial and instance-method groups as operator.methodcaller.
• Preserves configured values for typed nargs="*" positionals when the command line supplies no replacement.
• Adds migration documentation and comprehensive regression coverage.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    S[Callable signature] --> R[Resolve parameters]
    R --> L[Record CallLayout]
    L --> P[Parse CLI or config values]
    P --> I[Instantiate configuration]
    I --> A[Split positional and keyword arguments]
    A --> C{Group type}
    C -->|Class| O[Construct instance]
    C -->|Function or static/class method| F[functools.partial]
    C -->|Instance method| M[operator.methodcaller]

Loading

_{Reviews (2) · Last reviewed commit: "Address review comments"}

[sonarqubecloud]

Quality Gate passed

Issues
4 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud