datalad.cli.parser

Components to build the parser instance for the CLI

This module must import (and run) really fast for a responsive CLI. It is unconditionally imported by the main() entrypoint.

class datalad.cli.parser.ArgumentParserDisableAbbrev(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

Bases: ArgumentParser

datalad.cli.parser.add_subparser(_intfspec, subparsers, cmd_name, formatter_class, completing=False)

Given an interface spec, add a subparser to subparsers under cmd_name

datalad.cli.parser.fail_with_short_help(parser=None, msg=None, known=None, provided=None, hint=None, exit_code=1, what='command', out=None)

Generic helper to fail with short help possibly hinting on what was intended if known were provided

datalad.cli.parser.parser_add_common_opt(parser, opt, names=None, **kwargs)

datalad.cli.parser.parser_add_common_options(parser, version=None)

Add all options defined in common_args, but excludes ‘help’

datalad.cli.parser.parser_add_version_opt(parser, mod_name, include_name=False, delay=False)

Setup –version option

Parameters:

• parser

• mod_name (str, optional)

• include_name (bool, optional)

• delay (bool, optional) – If set to True, no action is taken immediately, and rather we assign the function which would print the version. Necessary for early pre-parsing of the cmdline

datalad.cli.parser.setup_parser(cmdlineargs, formatter_class=<class 'argparse.RawDescriptionHelpFormatter'>, return_subparsers=False, completing=False, help_ignore_extensions=False)

The holy grail of establishing CLI for DataLad’s Interfaces

Parameters:

• cmdlineargs (sys.argv) – Used to make some shortcuts when construction of a full parser can be avoided.

• formatter_class – Passed to argparse

• return_subparsers (bool, optional) – is used ATM only by BuildManPage in _datalad_build_support

• completing (bool, optional) – Flag to indicate whether the process was invoked by argcomplete

• help_ignore_extensions (bool, optional) – Prevent loading of extension entrypoints when –help is requested. This is enabled when building docs to avoid pollution of generated manpages with extensions commands (that should appear in their own docs, but not in the core datalad package docs)

datalad.cli.parser.setup_parser_for_interface(parser, cls, completing=False)

datalad.cli.parser.setup_parserarg_for_interface(parser, param_name, param, defaults_idx, prefix_chars, defaults, completing=False)

datalad.cli.parser.single_subparser_possible(cmdlineargs, parser, completing)

Performs early analysis of the cmdline

Looks at the first unparsed argument and if a known command, would return only that one.

When a plain command invocation with –version is detected, it will be acted on directly (until sys.exit(0) to avoid wasting time on unnecessary further processing.

Returns:

Returns a status label and a parameter for this status. ‘error’: parsing failed, ‘allknown’: the parser successfully identified all arguments, ‘help’: a help request option was found, ‘unknownopt’: an unknown or incomplete option was found, ‘subcommand’: a potential subcommand name was found. For the latter two modes the second return value is the option or command name. For all other modes the second return value is None.

Return type:

{‘error’, ‘allknown’, ‘help’, ‘unknownopt’, ‘subcommand’}, None or str

datalad.cli.parser.try_suggest_extension_with_command(parser, cmd, completing, known_cmds)

If completing=False, this function will trigger sys.exit()