yapx.run

yapx.run

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

Parameters:

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

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
*args	Any	...	()
**kwargs	Any	...	{}

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
command	Optional[Callable[..., Any]]	the root command function	None
subcommands	Union[None, str, CommandOrCallable, CommandSequence, CommandMap]	a list or mapping of subcommand functions	None
**kwargs	Any	passed to the ArgumentParser constructor	{}

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
spec	Dict[str, Any]	...	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	path to file containing spec.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
*args	Any	...	()
test_args	Optional[List[str]]	patch sys.argv with these args	None
disable_pydantic	bool	disable the use of pydantic for additional validation	False
**kwargs	Any	...	{}

Returns:

Type	Description
Any	...

yapx.run_commands_patched