From f27b1e1db7c5c4ead0228e5ae14ba2fc510dffae Mon Sep 17 00:00:00 2001 From: Brian Pugh Date: Tue, 3 Dec 2024 20:03:30 -0500 Subject: [PATCH] Add vs-Typer documentation on keyword multiple values. --- docs/source/migration/typer.rst | 4 +- docs/source/vs_typer/README.rst | 1 + .../keyword_multiple_values/README.rst | 59 +++++++++++++++++++ 3 files changed, 62 insertions(+), 2 deletions(-) create mode 100644 docs/source/vs_typer/keyword_multiple_values/README.rst diff --git a/docs/source/migration/typer.rst b/docs/source/migration/typer.rst index 1498308..bb3f303 100644 --- a/docs/source/migration/typer.rst +++ b/docs/source/migration/typer.rst @@ -23,8 +23,8 @@ Much of Cyclopts's syntax is `Typer`_-inspired. Migrating from Typer should be p - :meth:`@app.command() <.App.command>` - In Cyclopts, ``@app.command`` :ref:`always results in a command. ` To define an action when no command is provided, see :meth:`@app.default <.App.default>`. - * - :meth:`@app.add_typer` - - :meth:`@app.command` + * - :meth:`app.add_typer(...)` + - :meth:`app.command(...)` - Sub applications and commands are registered the same way in Cyclopts. * - :meth:`@app.callback()` diff --git a/docs/source/vs_typer/README.rst b/docs/source/vs_typer/README.rst index bf100e2..2c768ff 100644 --- a/docs/source/vs_typer/README.rst +++ b/docs/source/vs_typer/README.rst @@ -29,6 +29,7 @@ This section was written about the current version of Typer: ``v0.9.0``. docstring/README.rst decorator_parentheses/README.rst optional_list/README.rst + keyword_multiple_values/README.rst flag_negation/README.rst help_defaults/README.rst validation/README.rst diff --git a/docs/source/vs_typer/keyword_multiple_values/README.rst b/docs/source/vs_typer/keyword_multiple_values/README.rst new file mode 100644 index 0000000..eccfa93 --- /dev/null +++ b/docs/source/vs_typer/keyword_multiple_values/README.rst @@ -0,0 +1,59 @@ +======================= +Keyword Multiple Values +======================= +In some applications, it is desirable to supply multiple values to a keyword argument. +For example, lets consider an application where we want to specify multiple input files. +We want our application to look like the following: + +.. code-block:: console + + $ my-program output.bin --input input1.bin input2.bin input3.bin + +In Typer, `it is impossible to accomplish this `_. +With Typer, the keyword must be specified before each value: + +.. code-block:: console + + $ my-program output.bin --input input1.bin --input input2.bin --input input3.bin + +By default, Cyclopts behavior mimics Typer, where a single element worth of CLI tokens are consumed. +However, by setting :attr:`.Parameter.consume_multiple` to :obj:`True`, multiple elements worth of CLI tokens will be consumed. +Consider the following example program with a single output path, and multiple input paths. + +.. code-block:: python + + from cyclopts import App, Parameter + from pathlib import Path + from typing import Annotated + + app = App() + + @app.default + def main(output: Path, input: Annotated[list[Path], Parameter(consume_multiple=True)]): + print(f"{input=} {output=}") + + if __name__ == "__main__": + app() + +All of the following invocations are equivalent: + +.. code-block:: console + + $ my-program out.bin input1.bin input2.bin input3.bin + input=[PosixPath('input1.bin'), PosixPath('input2.bin'), PosixPath('input3.bin')] output=PosixPath('out.bin') + + $ my-program out.bin --input input1.bin --input input2.bin --input input3.bin + + $ my-program out.bin --input input1.bin input2.bin input3.bin + + $ my-program --input input1.bin input2.bin input3.bin --output out.bin + + $ my-program --input input1.bin input2.bin input3.bin -- output.bin + +To set this configuration for your entire application, supply it to your root :attr:`.App.default_parameter`: + +.. code-block:: python + + from cyclopts import App, Parameter + + app = App(default_parameter=Parameter(consume_multiple=True))