Generation of JSON schemas for parsers

[mauvilsa]

What does this PR do?

Adds a new jsonschema completion type, so that a parser can produce a JSON Schema (draft 2020-12) describing the config files it accepts, either programmatically with parser.get_completion_script("jsonschema") or from the command line with --print_completion=jsonschema.

Fixes #618

The schema is derived from the same information as the --help output, and includes:

• Nested structure, i.e. argument groups and subclasses-disabled types as objects, plus which of their keys are required.
• Accepted types, including unions, literals, enums, containers and restrictions such as PositiveInt and Email. For plain argparse actions, which have no type hint, what the action gives, e.g. boolean for store_true, integer for count, the possible values for store_const and an array for append.
• Defaults, excluding required arguments, argparse.SUPPRESS defaults and unset values.
• Descriptions from the docstrings of the classes and functions the arguments come from, or from the help given to add_argument.
• One entry per known subclass of subclass types, each with a fixed class_path and an init_args object for that specific class.
• Subcommands as one object per subcommand plus an optional subcommand key.

Types used in more than one place go once into $defs and are referenced with $ref, which also makes recursive types work.

For subclass types the schema is stricter than the parser: a string is accepted, since it can be a class path or a path to a sub-config file, but an object is only accepted for the known subclasses. An object that accepts any class_path would keep tools from suggesting the known subclasses and from pointing out a class path that has a typo or is not the accepted import path, in which case the init_args would go undescribed. Only when a type has no known subclass is any class_path accepted, without describing its init_args.

To get editor validation and autocompletion, configs can point to a schema with a $schema key. The key is accepted in any config that a parser loads, sub-config files included, and is removed before parsing, so it never reaches the parsed namespace. It is not removed when the parser has an argument with that name, nor from the values of dict types, since there it is data instead of a pointer to a schema.

Other changes:

• --print_completion is now added whenever the setting is enabled, no longer requiring shtab to be installed, and its accepted values are jsonschema plus one shtab-* value per supported shell when shtab is available.
• The parser is only invalidated by get_completion_script for the shtab-* types. Generating a JSON schema does not modify the parser.
• The tab completion section of the documentation is restructured into a "Completion scripts" section covering both completion types, with argcomplete runtime completion documented separately.

This feature is experimental, so the details of the generated schema might change in non-major releases.

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?
• [n/a] 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 (b4a91a2) to head (2443ed6).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##              main      #961    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files           27        28     +1     
  Lines         8784      9162   +378     
==========================================
+ Hits          8784      9162   +378     

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

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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