Commands

seali.command(fn: None | Callable = None, *, help: None | seali.Help = None, version: None | str = None, extra_completions: None | Callable[[str], list[str]] = None)

Wires a function up to the CLI.

Arguments:

• fn: the function to decorate.

  All arguments must be type-annotated. Supported types are None, str, bool, int, float, pathlib.Path, Literals and Unions. Command line inputs are automatically parsed into the specified type.

  All arguments must be either be positional-only (before a /), keyword-only (after a *), or variadic-positional (*args).

  Positional-only arguments may or may have default values.

  Keyword-only arguments...

  • ...with boolean annotations are 'flags'. Flags must have default False.
  • ...with any other annotation are 'options'. These may or may not have a default.

• help: optional, the documentation for the function. Appears when running with -h or --help. Should be a seali.Help object.

• version: optional, the version to report when running with -v or --version.

• extra_completions: optional, a function which will be called with the shell (for example "fish") and which should return any extra completions for this command.

Returns:

A command object that can be called with nothing, or with a list of strings. If called with nothing, defaults to sys.argv[1:].

Command line inputs:

The inputs are scanned left-to-right. If the input begins with a - then it is treated as an option or flag. Otherwise it is treated positionally. (To pass positional arguments that happen to begin with a -, then pass --: all arguments after this are treated positionally, regardless of what they start with.)

Options are set either by --opt=value or via --opt value.

Flags are set by passing them without a value, --flag.

Flags and options may be called with either --kebab-case or --snake_case. The first argument beginning with each letter may be input with just a single-letter abbreviation, e.g. -f instead of --flag.

If there are too many positional inputs, or any unknown flags or options, then...
...if there is a variadic-positional argument, then they will be passed in to this unchanged.
...if there is no variadic-positional argument, then an error will be raised.

Example

@seali.command  # or @seali.command(help=...)
def my_program(pos: str, /, *, someflag: bool = False):
    ...

if __name__ == "__main__":
    my_program()  # same as `my_program(sys.argv)`
                  # or use `my_program(custom_argv)` to customise parsed args