soleil.cli_tools.solex_decorator

Functions

solex([group, _fxn])

Decorator that builds a CLI command similar to the solex script and applies the wrapped callable, if any, to the object resolved from the configuration file.

soleil.cli_tools.solex_decorator.solex(group: ~typing.Callable = <module 'climax' from '/home/docs/checkouts/readthedocs.org/user_builds/soleil/envs/latest/lib/python3.8/site-packages/climax/__init__.py'>, *, _fxn: ~typing.Callable = <class 'soleil.cli_tools.solex_decorator._NotProvided'>, **solconfarg_kwargs) → Callable

Decorator that builds a CLI command similar to the solex script and applies the wrapped callable, if any, to the object resolved from the configuration file.

The returned command exposes a parser attribute of type argparse.ArgumentParser that can be used to add extra CLI arguments that are passed to the wrapped callable. Depending on the specifications of the conf argument of type SolConfArg, these extra arguments might need to be optional argparse arguments (see Number of consumed CLI arguments in the SolConfArg documentation).

Parameters:

group – Pass in a climax group to make the solex call a sub-command.

Example usage

The function can be used as a decorator to define python scripts that execute a function on the object loaded from the configuration file:

from soleil.cli_tools import solex
import climax as clx

@solex()
@clx.argument('--my-opt', default=0, type=int, help='My optional argument.')
def foo(obj, my_opt):
    """ Optional doc string will override the default. """
    ...

if __name__=='__main__':
   foo()

Running the above script with the -h option displays the following help message:

usage: sphinx-build [-h] [--profile [DO_PROFILE]] [--pdb] [--show] [--my-opt MY_OPT] conf [conf ...]

Optional doc string will override the default.

positional arguments:
  conf                  The path of the configuration file to launch and, optionally, any argument overrides

optional arguments:
  -h, --help            show this help message and exit
  --profile [DO_PROFILE]
                        Profile the code and dump the stats to a file. The flag can be followed by a filename ('solex.prof' by default)
  --pdb                 Start an interative debugging session on error
  --show                Display solconf module without resolving and exit
  --my-opt MY_OPT       My optional argument.

Note that the option also supports adding an extra arguments --my-opt that is also passed to the test function foo as argument my_opt.

Note

Soleil CLIs are based on climax and can be combined with any climax construct. Both soleil.argument and soleil.group are aliases to climax.argument and climax.group.

Usage within a command group

The @solex decorator can also be used to define climax sub-commands.

from soleil.cli_tools import solex
import climax as clx

@clx.group()
def my_command_group(): pass

@my_command_group.command()
def bar(): pass

@solex(my_command_group)
@clx.argument('--my_opt', default=0, type=int, help='My optional argument.')
def foo(obj, my_opt):
    """ Optional doc string will override the default. """
    ...

if __name__=='__main__':
   my_command_group()

Running the above script with the -h option displays the following help message:

  usage: ... [-h] {bar,foo} ...

  positional arguments:
    {bar,foo}
      bar
      foo       Optional doc string will override the default.

  optional arguments:
    -h, --help  show this help message and exit