diff --git a/docs/command.md b/docs/command.md index b323a01..a11300f 100644 --- a/docs/command.md +++ b/docs/command.md @@ -1,9 +1,13 @@ ## Define a command + ```python +"""Simple add program.""" + from typing_extensions import Annotated -from clea import Integer, command +from clea import Integer, command, run + @command def add( @@ -13,35 +17,30 @@ def add( """Add two numbers""" print(f"Total {n1 + n2}") -``` -Invoke the command at runtime using - -```python -from clea import run if __name__ == "__main__": run(cli=add) ``` -> The example is taken from [add.py](https://github.com/angrybayblade/clea/blob/main/examples/add.py) in the examples folder. - -You can check the command definition using +*The example is taken from [add.py](https://github.com/angrybayblade/clea/blob/main/examples/add.py) in the examples folder.* + ```bash $ python add.py --help Usage: add [OPTIONS] N1 N2 - Add two numbers + Add two numbers Options: --help Show help and exit. ``` -Execute the command using +Running the application + ```bash $ python add.py 2 3 @@ -50,32 +49,16 @@ Total 5 ## With custom name + ```python -(...) - @command(name="add-numbers") def add( n1: Annotated[int, Integer()], n2: Annotated[int, Integer()], ) -> None: """Add two numbers""" - print (f"Total: {n1+n2}") - -(...) -``` - -The custom name will show up as the command name -```bash -$ python add.py --help - -Usage: add-numbers [OPTIONS] N1 N2 - - Add two numbers - -Options: - - --help Show help and exit. + print(f"Total {n1 + n2}") ``` ## Next steps diff --git a/docs/context.md b/docs/context.md index 2a86435..0786983 100644 --- a/docs/context.md +++ b/docs/context.md @@ -4,8 +4,14 @@ Whenever a command is executed, a runtime object is created which holds state fo Context object provides a simple key-value data store for storing and retrieving data across the execution. + ```python -from clea import Context, run, group +"""Context example.""" + +from clea.context import Context +from clea.runner import run +from clea.wrappers import group + @group def admin(context: Context) -> None: @@ -34,9 +40,14 @@ if __name__ == "__main__": You can define a custom context for tasks such as loading and storing application config. + ```python -from clea import run, command -from clea import Context as BaseContext +"""Custom context example.""" + +from clea.context import Context as BaseContext +from clea.runner import run +from clea.wrappers import command + class Context(BaseContext): """Custom context object""" diff --git a/docs/group.md b/docs/group.md index 23610b2..f527fc9 100644 --- a/docs/group.md +++ b/docs/group.md @@ -1,12 +1,14 @@ ## Define a group -Define you first command group using - + ```python -from clea import run, group, Integer, Boolean +"""Calculator example.""" + from typing_extensions import Annotated +from clea import Boolean, Integer, group, run + @group def calculator() -> None: @@ -23,64 +25,53 @@ def add( print(f"Answer {n1+n2}") -if __name__ == "__main__": - run(cli=calculator) -``` - -> The example is taken from [calculator.py](https://github.com/angrybayblade/clea/blob/main/examples/calculator.py) in the examples folder. - -You can check the command definition using - -```bash -Usage: calculator [OPTIONS] - - CLI Calculator app. - -Options: - - --help Show help and exit. - -Commands: - - add Add two numbers. -``` - -Execute the command using - -```bash -$ python calculator.py add 2 3 +@calculator.command +def subtract( + n1: Annotated[int, Integer()], + n2: Annotated[int, Integer()], +) -> None: + """Subtract two numbers.""" -Answer 5 -``` + print(f"Answer {n1-n2}") -## With custom name -```python -(...) +@calculator.command +def multiply( + n1: Annotated[int, Integer()], + n2: Annotated[int, Integer()], +) -> None: + """Multiply two numbers.""" -@group(name="calculator-app") -def calculator() -> None: - """CLI Calculator app.""" + print(f"Answer {n1*n2}") @calculator.command -def add( +def devide( n1: Annotated[int, Integer()], n2: Annotated[int, Integer()], + round: Annotated[ # pylint: disable=redefined-builtin + bool, Boolean(help="Round up the answer") + ], ) -> None: - """Add two numbers.""" + """Devide two numbers.""" -(...) -``` + if round: + print(f"Answer {n1//n2}") + else: + print(f"Answer {n1/n2}") -The custom name will show up as the group name +if __name__ == "__main__": + run(cli=calculator) +``` + + ```bash $ python calculator.py --help -Usage: calculator-app [OPTIONS] +Usage: calculator [OPTIONS] - CLI Calculator app. + CLI Calculator app. Options: @@ -89,6 +80,18 @@ Options: Commands: add Add two numbers. + subtract Subtract two numbers. + multiply Multiply two numbers. + devide Devide two numbers. +``` + +Running the application + + +```bash +$ python calculator.py add 2 3 + +Answer 5 ``` ## Next steps diff --git a/docs/index.md b/docs/index.md index 49e8a93..b8d88dc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ ## Introduction -Clea is a light weight application framework for creating CLI applications in python. Clea is uses type annotations to generate the command/group defintions and parse the arguments at the runtime. To start with clea run +Clea is a framework for creating CLI applications in python very quickly. Clea uses type annotations for defining arguments. To start with clea run ## Install @@ -10,12 +10,16 @@ pip3 install clea ## Quickstart -Define you first command using +Define your first application + ```python +"""Simple add program.""" + from typing_extensions import Annotated -from clea import Integer, command +from clea import Integer, command, run + @command def add( @@ -25,35 +29,15 @@ def add( """Add two numbers""" print(f"Total {n1 + n2}") -``` -Invoke the command at runtime using - -```python -from clea import run if __name__ == "__main__": run(cli=add) ``` -> The example is taken from [add.py](https://github.com/angrybayblade/clea/blob/main/examples/add.py) in the examples folder. - -You can check the command definition using - -```bash -$ python add.py --help - -Usage: add [OPTIONS] N1 N2 - - Add two numbers - -Options: - - --help Show help and exit. -``` - Execute the command using + ```bash $ python add.py 2 3 diff --git a/docs/testing.md b/docs/testing.md index 2da64fe..695ca5e 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -2,9 +2,12 @@ To test a clea application you can use the `isolated` flag in the `clea.runner.run` method. For example, to test the `add.py` + ```python +"""Test add.py""" + from examples.add import add as cli -from clea import run +from clea.runner import run def test_missing_arguments() -> None: @@ -22,4 +25,4 @@ def test_add() -> None: result = run(cli=cli, argv=["1", "2"], isolated=True) assert result.exit_code == 0 assert "Total 3" in result.stdout -``` \ No newline at end of file +```