Metadata-Version: 2.1
Name: argshell
Version: 1.6.1
Summary: Integrates the argparse and cmd modules.
Project-URL: Homepage, https://github.com/matt-manes/argshell
Project-URL: Documentation, https://github.com/matt-manes/argshell/tree/main/docs
Project-URL: Source code, https://github.com/matt-manes/argshell/tree/main/src/argshell
Author-email: Matt Manes <mattmanes@pm.me>
License-File: LICENSE.txt
Keywords: argparse,cmd,commandline,shell,terminal
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: colorama
Requires-Dist: pathier
Requires-Dist: printbuddies
Requires-Dist: rich
Requires-Dist: rich-argparse
Description-Content-Type: text/markdown

# argshell

Integrates the argparse and cmd modules to create custom shells with argparse functionality. 

## Installation

Install with:

<pre>
pip install argshell
</pre>



## Usage

Custom shells are created by subclassing the ArgShell class and adding functions of the form `do_*()`, just like the cmd.Cmd class.  
The `ArgShell` class contains a `rich.console.Console` object that can be used to print renderables.  
![](assets/myshell.svg)

In terminal:
![](assets/echo.svg)

---

Rather than being limited to input strings, you can use `argparse` style parsers for shell commands.  
Create a function that instantiates an `ArgShellParser` instance, adds arguments, and then returns the `ArgShellParser` object.  
Then you can can decorate `do_*` functions using `with_parser()` to pass a `Namespace` object instead of a string.
![](assets/myshell_with_parser.svg)

In terminal:
![](assets/add_help.svg)
![](assets/add.svg)

---

The `with_parser` function also accepts an optional list of functions that accept and return an `argshell.Namespace` object.  
These functions will be executed in order after the parser function parses the arguments.
![](assets/post_parser.svg)

In terminal:
![](assets/invert_add.svg)
![](assets/invert_double_add.svg)

--- 

When using your shell, entering `help command` will, in addition to the command's doc string,
print the help message of the parser that decorates it, if it is decorated.  
![](assets/help_list.svg)
![](assets/help.svg)

---

The `capture` command can be used to save an svg of another command's output by prepending to a command.  
(NOTE: This only works for output printed with `ArgShell`'s `console` member mentioned earlier.)
The following would create a file called `add.svg` in your current directory:
![](assets/capture.svg)
The saved svg:
![](assets/add.svg)

---

There's also a "hidden" command for generating documentation called `shell_docs`.
![](assets/help_shell_docs.svg)

Executing that command for `MyShell`:
![](assets/shell_docs.svg)