yapx.run

yapx.run

Use given functions to construct an ArgumentParser, parse the args, invoke the appropriate command and return any result.

PARAMETER	DESCRIPTION
command	the root command function TYPE: Optional[Callable[..., Any]] DEFAULT: None
subcommands	a list or mapping of subcommand functions TYPE: Union[None, str, CommandOrCallable, CommandSequence, CommandMap] DEFAULT: None
args	arguments to parse (default=sys.argv[1:]) TYPE: Optional[List[str]] DEFAULT: None
default_args	arguments to parse when no arguments are given. TYPE: Optional[List[str]] DEFAULT: None
**kwargs	passed to the ArgumentParser constructor TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Any	...

Examples:

>>> import yapx
...
>>> def print_nums(*args: int):
...     print('Args: ', *args)
...     return args
...
>>> def find_evens(_context: yapx.Context):
...     return [x for x in _context.relay_value if x % 2 == 0]
...
>>> def find_odds(_context: yapx.Context):
...     return [x for x in _context.relay_value if x % 2 != 0]
...
>>> cli_args = ['find-odds', '1', '2', '3', '4', '5']
>>> yapx.run(print_nums, [find_evens, find_odds], args=cli_args)
Args:  1 2 3 4 5
[1, 3, 5]

yapx.run_commands

Use given functions to construct an ArgumentParser, parse the args, invoke the appropriate command and return any result.

yapx.run_commands(...) is equivalent to yapx.run(None, ...), to be used when there is no root command.

PARAMETER	DESCRIPTION
*args	... TYPE: Any DEFAULT: ()
**kwargs	... TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Any	...

Examples:

>>> import yapx
...
>>> def find_evens(*args: int):
...     return [x for x in args if x % 2 == 0]
...
>>> def find_odds(*args: int):
...     return [x for x in args if x % 2 != 0]
...
>>> cli_args = ['find-odds', '1', '2', '3', '4', '5']
>>> yapx.run_commands([find_evens, find_odds], args=cli_args)
[1, 3, 5]

yapx.build_parser

Use given functions to construct an ArgumentParser.

PARAMETER	DESCRIPTION
command	the root command function TYPE: Optional[Callable[..., Any]] DEFAULT: None
subcommands	a list or mapping of subcommand functions TYPE: Union[None, str, CommandOrCallable, CommandSequence, CommandMap] DEFAULT: None
**kwargs	passed to the ArgumentParser constructor TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
ArgumentParser	...

Examples:

>>> import yapx
...
>>> def print_nums(*args: int):
...     print('Args: ', *args)
...     return args
...
>>> def find_evens(_context: yapx.Context):
...     return [x for x in _context.relay_value if x % 2 == 0]
...
>>> def find_odds(_context: yapx.Context):
...     return [x for x in _context.relay_value if x % 2 != 0]
...
>>> cli_args = ['find-odds', '1', '2', '3', '4', '5']
>>> parser = yapx.build_parser(print_nums, [find_evens, find_odds])
...
>>> import argparse
>>> isinstance(parser, argparse.ArgumentParser)
True

yapx.build_parser_from_spec

Use given spec to construct an ArgumentParser.

PARAMETER	DESCRIPTION
spec	... TYPE: Dict[str, Any]

RETURNS	DESCRIPTION
ArgumentParser	...

Examples:

>>> import yapx
...
>>> parser_spec: Dict[str, Any] = {
...     "expected_prog": {
...         "description": "expected_description",
...         "arguments": {
...             "value": {
...                 "type": "int",
...                 "default": 69
...             },
...             "flag": {"action": "store_true"}
...         },
...         "subparsers": {
...             "expected_subcmd": {
...                 "description": "expected_description"
...             }
...         },
...     },
... }

>>> parser: yapx.ArgumentParser = yapx.build_parser_from_spec(parser_spec)

yapx.build_parser_from_file

Use given file to construct an ArgumentParser.

Supports files in json or yaml format.

PARAMETER	DESCRIPTION
path	path to file containing spec. TYPE: Union[str, Path]

RETURNS	DESCRIPTION
ArgumentParser	...

Examples:

Full spec for parsers and arguments:

.parser_ref:
  description: "..."
  add_help: true
  arguments: {}
  subparsers: {}

.argument_ref:
  flags: []
  pos: false
  required: false
  default: null
  nargs: 1
  type: str
  choices: []
  help: ""
  metavar: ""
  action: ""
  group: ""
  exclusive: false
  const: null

Example spec in YAML:

'test-cli':
  description: "halp"
  add_help: true
  arguments:
    value:
      type: int
      default: 69
  subparsers:
    'test-subcmd':
      arguments: {}
      subparsers: {}

Testing

yapx.run_patched

For use in tests.

Same as yapx.run, with the ability to patch args and disable pydantic.

PARAMETER	DESCRIPTION
*args	... TYPE: Any DEFAULT: ()
test_args	patch sys.argv with these args TYPE: Optional[List[str]] DEFAULT: None
disable_pydantic	disable the use of pydantic for additional validation TYPE: bool DEFAULT: False
**kwargs	... TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Any	...

yapx.run_commands_patched