diff --git a/cmd2.png b/cmd2.png index ca540129e..31a6e921f 100644 Binary files a/cmd2.png and b/cmd2.png differ diff --git a/docs/doc_conventions.md b/docs/doc_conventions.md index 85c43e8f3..1bc8dab3c 100644 --- a/docs/doc_conventions.md +++ b/docs/doc_conventions.md @@ -7,9 +7,9 @@ described by [Write The Docs](http://www.writethedocs.org) In addition: -- We have gone to great lengths to retain compatibility with the standard library cmd, the - documentation should make it easy for developers to understand how to move from cmd to cmd2, and - what benefits that will provide +- We have gone to great lengths to retain compatibility with the standard library `cmd`, the + documentation should make it easy for developers to understand how to move from `cmd` to `cmd2`, + and what benefits that will provide - We should provide both descriptive and reference documentation. - API reference documentation should be generated from docstrings in the code - Documentation should include rich hyperlinking to other areas of the documentation, and to the API @@ -18,7 +18,7 @@ In addition: ## Style Checker We strongly encourage all developers to use [Prettier](https://prettier.io/) for formatting all -**Markdown** and YAML files. The easiest way to do this is to integrated it with your IDE and +**Markdown** and YAML files. The easiest way to do this is to integrate it with your IDE and configure your IDE to format on save. You can also install `prettier` either using `npm` or OS package manager such as `brew` or `apt`. @@ -28,7 +28,7 @@ All source files in the documentation must: - have all lower case file names - if the name has multiple words, separate them with an underscore -- end in '.rst' +- end in '.md' ## Indenting @@ -42,7 +42,7 @@ html. ## Titles and Headings -Reference the [Markdown Basic Syntax](https://www.markdownguide.org/basic-syntax/) for synatx basics +Reference the [Markdown Basic Syntax](https://www.markdownguide.org/basic-syntax/) for syntax basics or [The Markdown Guide](https://www.markdownguide.org/) for a more complete reference. ## Inline Code @@ -50,7 +50,7 @@ or [The Markdown Guide](https://www.markdownguide.org/) for a more complete refe Code blocks can be created in two ways: - Indent the block - this will show as a monospace code block, but won't include highighting -- use the triple backticks followed by the code language, e.e. `python` and close with triple +- use the triple backticks followed by the code language, e.g. `python` and close with triple backticks If you want to show non-Python code, like shell commands, then use a different language such as @@ -65,7 +65,7 @@ See the [Links](https://www.markdownguide.org/basic-syntax/) Markdown syntax doc The API documentation is mostly pulled from docstrings in the source code using the MkDocs [mkdocstrings](https://mkdocstrings.github.io/) plugin. -When using `mkdocstinrgs`, it must be preceded by a blank line before and after, i.e.: +When using `mkdocstrings`, it must be preceded by a blank line before and after, i.e.: ```markdown ::: cmd2.history.History diff --git a/docs/examples/alternate_event_loops.md b/docs/examples/alternate_event_loops.md index fb13c450c..dfd12d085 100644 --- a/docs/examples/alternate_event_loops.md +++ b/docs/examples/alternate_event_loops.md @@ -17,8 +17,8 @@ However, there are some limitations to this way of using `cmd2`, mainly that `cm loop of a program. This can be unnecessarily restrictive and can prevent using libraries which depend on controlling their own event loop. -Many Python concurrency libraries involve or require an event loop which they are in control of such -as [asyncio](https://docs.python.org/3/library/asyncio.html), [gevent](http://www.gevent.org/), +Many Python concurrency libraries involve or require an event loop which they are in control of, +such as [asyncio](https://docs.python.org/3/library/asyncio.html), [gevent](http://www.gevent.org/), [Twisted](https://twistedmatrix.com), etc. `cmd2` applications can be executed in a fashion where `cmd2` doesn't own the main loop for the @@ -44,7 +44,8 @@ if __name__ == '__main__': app.postloop() ``` -The `cmd2.Cmd.runcmds_plus_hooks()` method runs multiple commands via `cmd2.Cmd.onecmd_plus_hooks`. +The `cmd2.Cmd.runcmds_plus_hooks()` method runs multiple commands via +`cmd2.Cmd.onecmd_plus_hooks()`. The `cmd2.Cmd.onecmd_plus_hooks()` method will do the following to execute a single command in a normal fashion: diff --git a/docs/examples/getting_started.md b/docs/examples/getting_started.md index 0ab7289eb..559e04a8f 100644 --- a/docs/examples/getting_started.md +++ b/docs/examples/getting_started.md @@ -81,15 +81,15 @@ $ python getting_started.py (Cmd) set ``` -you will see our `maxrepeats` setting show up with it's default value of `3`. +you will see our `maxrepeats` setting show up with its default value of `3`. ## Create A Command Now we will create our first command, called `speak` which will echo back whatever we tell it to say. We are going to use an [argument processor](../features/argument_processing.md) so the `speak` -command can shout and talk piglatin. We will also use some built in methods for +command can shout and talk pig latin. We will also use some built in methods for [generating output](../features/generating_output.md). Add this code to `getting_started.py`, so -that the `speak_parser` attribute and the `do_speak()` method are part of the `CmdLineApp()` class: +that the `speak_parser` attribute and the `do_speak()` method are part of the `FirstApp()` class: ```py speak_parser = cmd2.Cmd2ArgumentParser() @@ -146,13 +146,13 @@ At the end of the method, we use our `maxrepeats` setting as an upper limit to t we will print the output. The last thing you'll notice is that we used the `self.poutput()` method to display our output. -`poutput()` is a method provided by `cmd2`, which I strongly recommend you use anytime you want to +`poutput()` is a method provided by `cmd2`, which I strongly recommend you use any time you want to [generate output](../features/generating_output.md). It provides the following benefits: 1. Allows the user to redirect output to a text file or pipe it to a shell process -1. Gracefully handles `BrokenPipeWarning` exceptions for redirected output +1. Gracefully handles `BrokenPipeError` exceptions for redirected output 1. Makes the output show up in a [transcript](../features/transcripts.md) -1. Honors the setting to [strip embedded ansi sequences](../features/settings.md#allow_style) +1. Honors the setting to [strip embedded ANSI sequences](../features/settings.md#allow_style) (typically used for background and foreground colors) Go run the script again, and try out the `speak` command. Try typing `help speak`, and you will see @@ -215,7 +215,7 @@ Some use cases benefit from the ability to have commands that span more than one you might want the ability for your user to type in a SQL command, which can often span lines and which are terminated with a semicolon. Let's add a [multiline command](../features/multiline_commands.md) to our application. First we'll create a new -command called `orate`. This code shows both the definition of our `speak`command, and the`orate` +command called `orate`. This code shows both the definition of our `speak` command, and the `orate` command: ```py @@ -267,9 +267,9 @@ persist between invocations of your application, you'll need to do a little work Users can access command history using two methods: -- the [readline](https://docs.python.org/3/library/readline.html) library which provides a python +- The [readline](https://docs.python.org/3/library/readline.html) library which provides a Python interface to the [GNU readline library](https://en.wikipedia.org/wiki/GNU_Readline) -- the `history` command which is built-in to `cmd2` +- The `history` command which is built-in to `cmd2` From the prompt in a `cmd2`-based application, you can press `Control-p` to move to the previously entered command, and `Control-n` to move to the next command. You can also search through the @@ -280,10 +280,10 @@ details, including all the available commands, and instructions for customizing The `history` command allows a user to view the command history, and select commands from history by number, range, string search, or regular expression. With the selected commands, users can: -- re-run the commands -- edit the selected commands in a text editor, and run them after the text editor exits -- save the commands to a file -- run the commands, saving both the commands and their output to a file +- Re-run the commands +- Edit the selected commands in a text editor, and run them after the text editor exits +- Save the commands to a file +- Run the commands, saving both the commands and their output to a file Learn more about the `history` command by typing `history -h` at any `cmd2` input prompt, or by exploring [Command History For Users](../features/history.md#for-users). diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md index 33db6723f..9535d5e21 100644 --- a/docs/features/argument_processing.md +++ b/docs/features/argument_processing.md @@ -9,10 +9,10 @@ following for you: 1. Passes the resulting `argparse.Namespace` object to your command function. The `Namespace` includes the `Statement` object that was created when parsing the command line. It can be retrieved by calling `cmd2_statement.get()` on the `Namespace`. -1. Adds the usage message from the argument parser to your command. -1. Checks if the `-h/--help` option is present, and if so, display the help message for the command +1. Adds the usage message from the argument parser to your command's help. +1. Checks if the `-h/--help` option is present, and if so, displays the help message for the command -These features are all provided by the `@with_argparser` decorator which is importable from `cmd2`. +These features are all provided by the `@with_argparser` decorator which is imported from `cmd2`. See the [argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py) @@ -49,7 +49,7 @@ argparser.add_argument('-r', '--repeat', type=int, help='output [n] times') argparser.add_argument('word', nargs='?', help='word to say') @with_argparser(argparser) -def do_speak(self, opts) +def do_speak(self, opts): """Repeats what you tell me to.""" arg = opts.word if opts.piglatin: @@ -91,7 +91,7 @@ the `help tag` command displays: ```text usage: tag [-h] tag content [content ...] -create a html tag +create an HTML tag positional arguments: tag tag @@ -101,13 +101,13 @@ optional arguments: -h, --help show this help message and exit ``` -If you would prefer you can set the `description` while instantiating the `argparse.ArgumentParser` +If you would prefer, you can set the `description` while instantiating the `argparse.ArgumentParser` and leave the docstring on your method empty: ```py from cmd2 import Cmd2ArgumentParser, with_argparser -argparser = Cmd2ArgumentParser(description='create an html tag') +argparser = Cmd2ArgumentParser(description='create an HTML tag') argparser.add_argument('tag', help='tag') argparser.add_argument('content', nargs='+', help='content to surround with tag') @with_argparser(argparser) @@ -121,7 +121,7 @@ Now when the user enters `help tag` they see: ```text usage: tag [-h] tag content [content ...] -create an html tag +create an HTML tag positional arguments: tag tag @@ -136,7 +136,7 @@ To add additional text to the end of the generated help message, use the `epilog ```py from cmd2 import Cmd2ArgumentParser, with_argparser -argparser = Cmd2ArgumentParser(description='create an html tag', +argparser = Cmd2ArgumentParser(description='create an HTML tag', epilog='This command cannot generate tags with no content, like
.') argparser.add_argument('tag', help='tag') argparser.add_argument('content', nargs='+', help='content to surround with tag') @@ -151,7 +151,7 @@ Which yields: ```text usage: tag [-h] tag content [content ...] -create an html tag +create an HTML tag positional arguments: tag tag @@ -195,7 +195,7 @@ class CmdLineApp(cmd2.Cmd): self.poutput(arg) ``` -If you don't want to access the additional attributes on the string passed to you`do_*` method you +If you don't want to access the additional attributes on the string passed to your `do_*` method you can still have `cmd2` apply shell parsing rules to the user input and pass you a list of arguments instead of a string. Apply the `@with_argument_list` decorator to those methods that should receive an argument list instead of a string: @@ -320,7 +320,7 @@ def do_foo(self, args: argparse.Namespace) -> None: ``` However, if you do NOT want the custom decorator runtime behavior to occur even in the case of an -`argparse` error, then that decorator needs to go **before** the `arpgarse` one, e.g.: +`argparse` error, then that decorator needs to go **before** the `argparse` one, e.g.: ```py @my_decorator @@ -338,9 +338,9 @@ example demonstrates both above cases in a concrete fashion. `cmd2` argparse decorators add the following attributes to argparse Namespaces. To avoid naming collisions, do not use any of the names for your argparse arguments. -- `cmd2_statement` - `cmd2.Cmd2AttributeWrapper` object containing `cmd2.Statement` object that was - created when parsing the command line. +- `cmd2_statement` - `cmd2.Cmd2AttributeWrapper` object containing the `cmd2.Statement` object that + was created when parsing the command line. - `cmd2_handler` - `cmd2.Cmd2AttributeWrapper` object containing a subcommand handler function or `None` if one was not set. -- `__subcmd_handler__` - used by cmd2 to identify the handler for a subcommand created with +- `__subcmd_handler__` - used by cmd2 to identify the handler for a subcommand created with the `@cmd2.as_subcommand_to` decorator. diff --git a/docs/features/builtin_commands.md b/docs/features/builtin_commands.md index 33e27aa20..becc4cd31 100644 --- a/docs/features/builtin_commands.md +++ b/docs/features/builtin_commands.md @@ -89,7 +89,7 @@ editor vi Program used by 'edit' feedback_to_output False Include nonessentials in '|' and '>' results max_completion_items 50 Maximum number of CompletionItems to display during tab completion -quiet False Don't print nonessential feedback +quiet False Don't print non-essential feedback scripts_add_to_history True Scripts and pyscripts add commands to history timing False Report execution times ``` diff --git a/docs/features/clipboard.md b/docs/features/clipboard.md index d177b31bf..f3d118565 100644 --- a/docs/features/clipboard.md +++ b/docs/features/clipboard.md @@ -12,9 +12,9 @@ clipboard by ending the command with a greater than symbol: mycommand args > ``` -Think of it as though you are redirecting output to an unnamed, ephemeral place, you know, like the -clipboard. You can also append output to the current contents of the clipboard by ending the command -with two greater than symbols: +Think of it as redirecting the output to an unnamed, ephemeral place: the clipboard. You can also +append output to the current contents of the clipboard by ending the command with two greater than +symbols: ```text mycommand arg1 arg2 >> diff --git a/docs/features/commands.md b/docs/features/commands.md index 06f3877be..ef6cb04b2 100644 --- a/docs/features/commands.md +++ b/docs/features/commands.md @@ -28,9 +28,9 @@ if __name__ == '__main__': sys.exit(c.cmdloop()) ``` -This application subclasses `cmd2.Cmd` but has no code of it's own, so all functionality (and -there's quite a bit) is inherited. Lets create a simple command in this application called `echo` -which outputs any arguments given to it. Add this method to the class: +This application subclasses `cmd2.Cmd` but has no code of its own, so all functionality (and there's +quite a bit) is inherited. Let's create a simple command in this application called `echo` which +outputs any arguments given to it. Add this method to the class: ```py def do_echo(self, line): @@ -55,7 +55,7 @@ A command is passed one argument: a string which contains all the rest of the us in `cmd2` this string is actually a `Statement` object, which is a subclass of `str` to retain backwards compatibility. -`cmd2` has a much more sophsticated parsing engine than what's included in the +`cmd2` has a much more sophisticated parsing engine than what's included in the [cmd](https://docs.python.org/3/library/cmd.html) module. This parsing handles: - quoted arguments @@ -105,7 +105,7 @@ terminator this attribute will tell you which one the user typed. For many simple commands, like the `echo` command above, you can ignore the `Statement` object and -all of it's attributes and just use the passed value as a string. You might choose to use the `argv` +all of its attributes and just use the passed value as a string. You might choose to use the `argv` attribute to do more sophisticated argument processing. Before you go too far down that path, you should check out the [Argument Processing](./argument_processing.md) functionality included with `cmd2`. @@ -149,7 +149,7 @@ def do_bail(self, line): """Exit the application""" self.perror("fatal error, exiting") self.exit_code = 2 - return true + return True if __name__ == '__main__': import sys @@ -174,8 +174,8 @@ Raising `SystemExit(code)` or calling `sys.exit(code)` in a command or hook func You may choose to catch and handle any exceptions which occur in a command method. If the command method raises an exception, `cmd2` will catch it and display it for you. The -[debug setting](./settings.md#debug) controls how the exception is displayed. If `debug` is `false`, -which is the default, `cmd2` will display the exception name and message. If `debug` is `true`, +[debug setting](./settings.md#debug) controls how the exception is displayed. If `debug` is `False`, +which is the default, `cmd2` will display the exception name and message. If `debug` is `True`, `cmd2` will display a traceback, and then display the exception name and message. There are a few exceptions which commands can raise that do not print as described above: @@ -186,7 +186,7 @@ There are a few exceptions which commands can raise that do not print as describ - `KeyboardInterrupt` - raised if running in a text script and `stop` isn't already True to stop the script -All other `BaseExceptions` are not caught by `cmd2` and will be raised +All other `BaseExceptions` are not caught by `cmd2` and will be raised. ## Disabling or Hiding Commands diff --git a/docs/features/completion.md b/docs/features/completion.md index 3d08bf87a..254a9ac53 100644 --- a/docs/features/completion.md +++ b/docs/features/completion.md @@ -85,8 +85,8 @@ instance, `ArgparseCompleter` sets it to False when displaying completion hints. ## Tab Completion Using argparse Decorators {: #argparse-based } -When using one the argparse-based [cmd2.decorators](../api/decorators.md), `cmd2` provides automatic -tab completion of flag names. +When using one of the argparse-based [cmd2.decorators](../api/decorators.md), `cmd2` provides +automatic tab completion of flag names. Tab completion of argument values can be configured by using one of three parameters to `argparse.ArgumentParser.add_argument` @@ -95,25 +95,26 @@ Tab completion of argument values can be configured by using one of three parame - `choices_provider` - `completer` -See the [arg_decorators](https://github.com/python-cmd2/cmd2/blob/main/examples/arg_decorators.py) +See the +[argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py) example for a demonstration of how to use the `choices` parameter. See the [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py) example for a demonstration of how to use the `choices_provider` parameter. See the -[arg_decorators](https://github.com/python-cmd2/cmd2/blob/main/examples/arg_decorators.py) or +[argparse_example](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_example.py) or [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py) example for a demonstration of how to use the `completer` parameter. When tab completing flags or argument values for a `cmd2` command using one of these decorators, `cmd2` keeps track of state so that once a flag has already previously been provided, it won't -attempt to tab complete it again. When no completion results exists, a hint for the current argument +attempt to tab complete it again. When no completion results exist, a hint for the current argument will be displayed to help the user. ## CompletionItem For Providing Extra Context When tab completing things like a unique ID from a database, it can often be beneficial to provide the user with some extra context about the item being completed, such as a description. To -facilitate this, `cmd2` defines the `cmd2.argparse_custom.CompletionItem` class which can be -returned from any of the 3 completion parameters: `choices`, `choices_provider`, and `completer`. +facilitate this, `cmd2` defines the `cmd2.CompletionItem` class which can be returned from any of +the 3 completion parameters: `choices`, `choices_provider`, and `completer`. See the [argparse_completion](https://github.com/python-cmd2/cmd2/blob/main/examples/argparse_completion.py) diff --git a/docs/features/embedded_python_shells.md b/docs/features/embedded_python_shells.md index bfa835af4..bf5bf594c 100644 --- a/docs/features/embedded_python_shells.md +++ b/docs/features/embedded_python_shells.md @@ -17,7 +17,7 @@ The Python shell can run CLI commands from you application using the object name `cmd2` application while maintaining isolation from the full `Cmd` instance. For example, any application command can be run with `app("command ...")`. -You may optionally enable full access to to your application by setting `self.self_in_py` to `True`. +You may optionally enable full access to your application by setting `self.self_in_py` to `True`. Enabling this flag adds `self` to the python session, which is a reference to your `cmd2` application. This can be useful for debugging your application. @@ -32,8 +32,8 @@ All of these parameters are also available to Python scripts which run in your a - supports tab completion of file system paths - has the ability to pass command-line arguments to the scripts invoked -This command provides a more complicated and more powerful scripting capability than that provided -by the simple text file scripts. Python scripts can include conditional control flow logic. See the +This command provides a more complex and powerful scripting capability than that provided by the +simple text file scripts. Python scripts can include conditional control flow logic. See the **python_scripting.py** `cmd2` application and the **script_conditional.py** script in the `examples` source code directory for an example of how to achieve this in your own applications. See [Scripting](./scripting.md) for an explanation of both scripting methods in **cmd2** applications. diff --git a/docs/features/generating_output.md b/docs/features/generating_output.md index beed0c1c0..b423258d0 100644 --- a/docs/features/generating_output.md +++ b/docs/features/generating_output.md @@ -85,7 +85,7 @@ to your output which tell the terminal to change the foreground and background c `cmd2` provides a number of convenience functions and classes for adding color and other styles to text. These are all based on [rich](https://github.com/Textualize/rich) and are documented in the -following sectins: +following sections: - [cmd2.colors][] - [cmd2.rich_utils][] diff --git a/docs/features/help.md b/docs/features/help.md index 816acc11c..437546f07 100644 --- a/docs/features/help.md +++ b/docs/features/help.md @@ -44,7 +44,7 @@ Occasionally there might be an unusual circumstance where providing static help enough and you want to provide dynamic information in the help text for a command. To meet this need, if a `help_foo` method is defined to match the `do_foo` method, then that method will be used to provide the help for command **foo**. This dynamic help is only supported for commands which do -not use an `argparse` decorator because didn't want different output for `help cmd` than for +not use an `argparse` decorator because we didn't want different output for `help cmd` than for `cmd -h`. ## Categorizing Commands @@ -85,7 +85,7 @@ Here's the output from the example `help_categories.py`: There are 2 methods of specifying command categories, using the `@with_category` decorator or with the `categorize()` function. Once a single command category is detected, the help output switches to -a categorized mode of display. All commands with an explicit category defined default to the +a categorized mode of display. All commands without an explicit category defined default to the category `Other`. Using the `@with_category` decorator: @@ -132,7 +132,7 @@ categorize((do_undeploy, ``` The `help` command also has a verbose option (`help -v` or `help --verbose`) that combines the help -categories with per-command Help Messages: +categories with per-command help messages: Documented commands (use 'help -v' for verbose/'help ' for details): diff --git a/docs/features/history.md b/docs/features/history.md index fdc7c9b46..9dfe9f51a 100644 --- a/docs/features/history.md +++ b/docs/features/history.md @@ -54,8 +54,8 @@ that saved input. The examples to follow all assume that you have entered the fo (Cmd) alias create four !echo four Alias 'four' created -In it's simplest form, the `history` command displays previously entered commands. With no -additional arguments, it displays all previously entered commands: +In its simplest form, the `history` command displays previously entered commands. With no additional +arguments, it displays all previously entered commands: (Cmd) history 1 alias create one !echo one @@ -68,7 +68,7 @@ If you give a positive integer as an argument, then it only displays the specifi (Cmd) history 4 4 alias create four !echo four -If you give a negative integer _N_ as an argument, then it display the _Nth_ last command. For +If you give a negative integer _N_ as an argument, then it displays the _Nth_ last command. For example, if you give `-1` it will display the last command you entered. If you give `-2` it will display the next to last command you entered, and so forth: @@ -110,9 +110,9 @@ an argument: > can insert the pseudo-argument '--' which tells parse[args]{#args}() that everything after that is > a positional argument: -There is no zeroth command, so don't ask for it. If you are a python programmer, you've probably +There is no zeroth command, so don't ask for it. If you are a Python programmer, you've probably noticed this looks a lot like the slice syntax for lists and arrays. It is, with the exception that -the first history command is 1, where the first element in a python array is 0. +the first history command is 1, where the first element in a Python array is 0. Besides selecting previous commands by number, you can also search for them. You can use a simple string search: @@ -193,7 +193,7 @@ commands with line numbers to a file, you can do it with output redirection: (Cmd) history 1:4 > history.txt -You might use `-s` or `--script` on it's own if you want to display history commands to the screen +You might use `-s` or `--script` on its own if you want to display history commands to the screen without line numbers, so you can copy them to the clipboard: (Cmd) history -s 1:3 diff --git a/docs/features/hooks.md b/docs/features/hooks.md index 9755f3eef..65cbce4d7 100644 --- a/docs/features/hooks.md +++ b/docs/features/hooks.md @@ -66,7 +66,7 @@ during the command loop: application, after `cmd2.Cmd.preloop` is called - `cmd2.Cmd.prompt` - see [Prompt](./prompt.md) for more information - `cmd2.Cmd.continuation_prompt` - The prompt issued to solicit input for the 2nd and subsequent - lines of a `multiline command [Multiline Commands](./multiline_commands.md) + lines of a [Multiline Command](./multiline_commands.md) - `cmd2.Cmd.echo` - if `True` write the prompt and the command into the output stream In addition, several arguments to `cmd2.Cmd.__init__` also affect the command loop behavior: @@ -154,7 +154,7 @@ is set to `False` by default. The hook method must return a `cmd2.plugin.PostparsingData` object, and it is very convenient to just return the object passed into the hook method. The hook method may modify the attributes of the -object to influence the behavior of the application. If `params.stop` is set to true, a fatal +object to influence the behavior of the application. If `params.stop` is set to `True`, a fatal failure is triggered prior to execution of the command, and the application exits. To modify the user input, you create a new `cmd2.Statement` object and return it in @@ -189,7 +189,7 @@ If a postparsing hook returns a `cmd2.plugin.PostparsingData` object with the Precommand hooks can modify the user input, but cannot request the application terminate. If your hook needs to be able to exit the application, you should implement it as a postparsing hook. -Once output is redirected and the timer started, all the hooks registered with +Once output is redirected and the timer is started, all the hooks registered with `cmd2.Cmd.register_precmd_hook` are called. Here's how to do it: ```py @@ -250,8 +250,8 @@ full backward compatibility with `cmd.Cmd`. If any postcommand hook (registered or `self.postcmd`) returns a `cmd2.plugin.PostcommandData` object with the stop attribute set to `True`, subsequent postcommand hooks will still be called, as will the command finalization hooks, but once those hooks have all been called, the application will -terminate. Likewise, if :`self.postcmd` returns `True`, the command finalization hooks will be -called before the application terminates. +terminate. Likewise, if `self.postcmd` returns `True`, the command finalization hooks will be called +before the application terminates. Any postcommand hook can change the value of the `stop` attribute before returning it, and the modified value will be passed to the next postcommand hook. The value returned by the final @@ -260,7 +260,7 @@ value. If your hook blindly returns `False`, a prior hook's request to exit the be honored. It's best to return the value you were passed unless you have a compelling reason to do otherwise. -To purposefully and silently skip postcommand hooks, commands can raise any of of the following +To purposefully and silently skip postcommand hooks, commands can raise any of the following exceptions. - `cmd2.exceptions.SkipPostcommandHooks` diff --git a/docs/features/misc.md b/docs/features/misc.md index 05999f68a..1bb357c6a 100644 --- a/docs/features/misc.md +++ b/docs/features/misc.md @@ -6,7 +6,8 @@ Turn the timer setting on, and `cmd2` will show the wall time it takes for each ## Exiting -Mention quit, and EOF handling built into `cmd2`. +Like many shell applications, `cmd2` applications can be exited by pressing `Ctrl-D` on an empty +line, or by executing the `quit` command. ## select diff --git a/docs/features/modular_commands.md b/docs/features/modular_commands.md index 1c50e07fe..bc33d7dd0 100644 --- a/docs/features/modular_commands.md +++ b/docs/features/modular_commands.md @@ -4,8 +4,8 @@ Cmd2 also enables developers to modularize their command definitions into `CommandSet` objects. CommandSets represent a logical grouping of commands within an cmd2 application. By default, all -CommandSets will be discovered and loaded automatically when the cmd2.Cmd class is instantiated with -this mixin. This also enables the developer to dynamically add/remove commands from the cmd2 +CommandSets will be discovered and loaded automatically when the `cmd2.Cmd` class is instantiated +with this mixin. This also enables the developer to dynamically add/remove commands from the cmd2 application. This could be useful for loadable plugins that add additional capabilities. Additionally, it allows for object-oriented encapsulation and garbage collection of state that is specific to a CommandSet. @@ -39,8 +39,8 @@ CommandSets group multiple commands together. The plugin will inspect functions with `do_`, help functions with `help_`, and completer functions with `complete_`. A new decorator `with_default_category` is provided to categorize all commands within a CommandSet -in the same command category. Individual commands in a CommandSet may be override the default -category by specifying a specific category with `cmd2.with_category`. +in the same command category. Individual commands in a CommandSet may override the default category +by specifying a specific category with `cmd2.with_category`. CommandSet command methods will always expect the same parameters as when defined in a `cmd2.Cmd` sub-class, except that `self` will now refer to the `CommandSet` instead of the cmd2 instance. The @@ -78,7 +78,7 @@ class ExampleApp(cmd2.Cmd): ### Manual CommandSet Construction -If a CommandSet class requires parameters to be provided to the constructor, you man manually +If a CommandSet class requires parameters to be provided to the constructor, you may manually construct CommandSets and pass in the constructor to Cmd2. ```py @@ -121,10 +121,9 @@ def main(): ### Dynamic Commands You can also dynamically load and unload commands by installing and removing CommandSets at runtime. -For example, if you could support runtime loadable plugins or add/remove commands based on your -state. +For example, you can support runtime loadable plugins or add/remove commands based on your state. -You may need to disable command auto-loading if you need dynamically load commands at runtime. +You may need to disable command auto-loading if you need to dynamically load commands at runtime. ```py import argparse @@ -239,13 +238,13 @@ code around these similar actions rather than organizing your code around simila managed. Subcommand injection allows you to inject subcommands into a base command to present an interface -that is sensible to a user while still organizing your code in whatever structure make more logical +that is sensible to a user while still organizing your code in whatever structure makes more logical sense to the developer. ### Example This example is a variation on the Dynamic Commands example above. A `cut` command is introduced as -a base command and each CommandSet +a base command and each CommandSet adds a subcommand to it. ```py import argparse diff --git a/docs/features/os.md b/docs/features/os.md index 313b988bb..f7a11f8f8 100644 --- a/docs/features/os.md +++ b/docs/features/os.md @@ -6,7 +6,7 @@ See [Output Redirection and Pipes](./redirection.md#output-redirection-and-pipes ## Executing OS commands from within `cmd2` -`cmd2` includes a `shell` command which executes it's arguments in the operating system shell: +`cmd2` includes a `shell` command which executes its arguments in the operating system shell: (Cmd) shell ls -al @@ -82,7 +82,7 @@ the text file using your `cmd2` program (from a Windows command prompt): c:\cmd2> type somecmds.txt | python.exe examples/transcript_example.py omesay ordsway -By default, `cmd2` programs also look for commands pass as arguments from the operating system +By default, `cmd2` programs also look for commands passed as arguments from the operating system shell, and execute those commands before entering the command loop: $ python examples/transcript_example.py help @@ -99,7 +99,7 @@ example, you might have a command inside your `cmd2` program which itself accept maybe even option strings. Say you wanted to run the `speak` command from the operating system shell, but have it say it in pig latin: - $ python example/transcript_example.py speak -p hello there + $ python examples/transcript_example.py speak -p hello there python transcript_example.py speak -p hello there usage: speak [-h] [-p] [-s] [-r REPEAT] words [words ...] speak: error: the following arguments are required: words @@ -112,7 +112,7 @@ Uh-oh, that's not what we wanted. `cmd2` treated `-p`, `hello`, and `there` as c exist in that program, thus the syntax errors. There is an easy way around this, which is demonstrated in `examples/cmd_as_argument.py`. By setting -`allow_cli_args=False` you can so your own argument parsing of the command line: +`allow_cli_args=False` you can do your own argument parsing of the command line: $ python examples/cmd_as_argument.py speak -p hello there ellohay heretay @@ -122,7 +122,7 @@ Check the source code of this example, especially the `main()` function, to see Alternatively you can simply wrap the command plus arguments in quotes (either single or double quotes): - $ python example/transcript_example.py "speak -p hello there" + $ python examples/transcript_example.py "speak -p hello there" ellohay heretay (Cmd) @@ -148,6 +148,6 @@ quits while returning an exit code: Here is another example using `quit`: - $ python example/transcript_example.py "speak -p hello there" quit + $ python examples/transcript_example.py "speak -p hello there" quit ellohay heretay $ diff --git a/docs/features/packaging.md b/docs/features/packaging.md index 0c9262699..a2a67bdf4 100644 --- a/docs/features/packaging.md +++ b/docs/features/packaging.md @@ -8,20 +8,20 @@ ecosystem. ## Publishing to the Python Package Index (PyPI) -The easiest way is to use to follow the tutorial for +The easiest way is to follow the tutorial for [Packaging Python Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/). -This will show you how to package your application as a Python package and uploadi to the Python +This will show you how to package your application as a Python package and upload it to the Python Package Index ([PyPI](https://pypi.org/)). Once published there, users will be able to install it using idiomatic Python packaging tools such as [pip](https://pip.pypa.io/) or [uv](https://github.com/astral-sh/uv). -Small tweaks on this process can allow you to publish to private PyPI mirror such as one hosted on +Small tweaks on this process can allow you to publish to private PyPI mirrors such as one hosted on [AWS CodeArtifact](https://aws.amazon.com/codeartifact/). ## Packaging your application in a container using Docker -Packing your Python application in a [Docker](https://www.docker.com/) container is a great when it -comes to cross-platform portability and convenience since your this container will inlude all +Packing your Python application in a [Docker](https://www.docker.com/) container is great when it +comes to cross-platform portability and convenience since this container will include all dependencies for your application and run them in an isolated environment which won't conflict with operating system dependencies. diff --git a/docs/features/plugins.md b/docs/features/plugins.md index 4c6a60cbf..566f84410 100644 --- a/docs/features/plugins.md +++ b/docs/features/plugins.md @@ -41,11 +41,11 @@ class Example(cmd2_myplugin.MyPlugin, cmd2.Cmd): Note how the plugin must be inherited (or mixed in) before `cmd2.Cmd`. This is required for two reasons: -- The `cmd.Cmd.__init__` method in the python standard library does not call `super().__init__()`. +- The `cmd.Cmd.__init__` method in the Python standard library does not call `super().__init__()`. Because of this oversight, if you don't inherit from `MyPlugin` first, the `MyPlugin.__init__()` method will never be called. - You may want your plugin to be able to override methods from `cmd2.Cmd`. If you mixin the plugin - after `cmd2.Cmd`, the python method resolution order will call [cmd2.Cmd][] methods before it + after `cmd2.Cmd`, the Python method resolution order will call [cmd2.Cmd][] methods before it calls those in your plugin. ## Add commands diff --git a/docs/features/prompt.md b/docs/features/prompt.md index ad385fbcd..76dbc2ade 100644 --- a/docs/features/prompt.md +++ b/docs/features/prompt.md @@ -14,7 +14,7 @@ for the simple use case of statically setting the prompt. When a user types a [Multiline Command](./multiline_commands.md) it may span more than one line of input. The prompt for the first line of input is specified by the `cmd2.Cmd.prompt` instance attribute. The prompt for subsequent lines of input is defined by the `cmd2.Cmd.continuation_prompt` -attribute.See the +attribute. See the [getting_started](https://github.com/python-cmd2/cmd2/blob/main/examples/getting_started.py) example for a demonstration of customizing the continuation prompt. diff --git a/docs/features/redirection.md b/docs/features/redirection.md index 53234c704..e9cf6c982 100644 --- a/docs/features/redirection.md +++ b/docs/features/redirection.md @@ -38,8 +38,8 @@ something like the following: (Cmd) help | grep py | wc > output.txt The above runs the **help** command, pipes its output to **grep** searching for any lines containing -_py_, then pipes the output of grep to the **wc** "word count" command, and finally writes redirects -the output of that to a file called _output.txt_. +_py_, then pipes the output of grep to the **wc** "word count" command, and finally redirects the +output of that to a file called _output.txt_. ## Disabling Redirection diff --git a/docs/features/scripting.md b/docs/features/scripting.md index 53b094880..acad9581b 100644 --- a/docs/features/scripting.md +++ b/docs/features/scripting.md @@ -6,8 +6,8 @@ supports two similar mechanisms: command scripts and python scripts. ## Command Scripts -A command script contains a sequence of commands typed at the the prompt of a `cmd2` based -application. Unlike operating system shell scripts, command scripts can't contain logic or loops. +A command script contains a sequence of commands typed at the prompt of a `cmd2` based application. +Unlike operating system shell scripts, command scripts can't contain logic or loops. ### Creating Command Scripts @@ -18,8 +18,8 @@ Command scripts can be created in several ways: file - saving previously entered commands to a script file using [history -s](./history.md#for-users) -If you create create a text file from scratch, just include one command per line, exactly as you -would type it inside a `cmd2` application. +If you create a text file from scratch, just include one command per line, exactly as you would type +it inside a `cmd2` application. ### Running Command Scripts @@ -110,10 +110,10 @@ for more information. If the cmd2 application follows the [unix_design_philosophy](https://en.wikipedia.org/wiki/Unix_philosophy) a scriptor will have the -most flexibility to piece together workflows using different commands. If the designers' application -is more complete and less likely to be augmented in the future a scripter may opt for simple serial -scripts with little control flow. In either case, choices made by the designer will have effects on -scripters. +most flexibility to piece together workflows using different commands. If the designer\'s +application is more complete and less likely to be augmented in the future a scripter may opt for +simple serial scripts with little control flow. In either case, choices made by the designer will +have effects on scripters. The following diagram illustrates the different boundaries to keep in mind. @@ -137,11 +137,11 @@ flowchart LR !!! note - As a designer it is preferable to design from the inside to out. Your code will be infinitely far easier to unit test than at the higher level. While there are regression testing extensions for cmd2 UnitTesting will always be faster for development. + As a designer it is preferable to design from the inside out. Your code will be infinitely far easier to unit test than at the higher level. While there are regression testing extensions for cmd2, unit testing will always be faster for development. !!! warning - It is bad design or a high level py_script to know about let alone access low level class libraries of an application. Resist this urge at all costs, unless it's necessary. + It is bad design for a high level pyscript to know about let alone access low level class libraries of an application. Resist this urge at all costs, unless it\'s necessary. ### Developing a Basic API @@ -221,8 +221,8 @@ When executing the `speak` command without parameters you see the following erro Usage: speak [-h] [-p] [-s] [-r REPEAT] words [...] Error: the following arguments are required: words -Even though this is a fully qualified CMD2 error the py[script]{#script} must look for this error -and perform error checking.: +Even though this is a fully qualified CMD2 error the pyscript must look for this error and perform +error checking.: ```py app('speak') @@ -256,7 +256,7 @@ if not result: (Cmd) run_pyscript script.py Something went wrong -In python development is good practice to fail and exit quickly after user input.: +In Python development, it is good practice to fail and exit quickly after user input.: ```py import sys @@ -297,8 +297,8 @@ control flow. In the next section we will show how to take advantage of `cmd_res ### Developing an Advanced API Until now the application designer has paid little attention to scripters and their needs. Wouldn't -it be nice if while creating py*scripts one did not have to parse data from `stdout`? We can -accommodate the weary scripter by adding one small line at the end of our `do*\*` commands. +it be nice if while creating pyscripts one did not have to parse data from `stdout`? We can +accommodate the weary scripter by adding one small line at the end of our `do_*` commands. `self.last_result = ` @@ -359,13 +359,13 @@ potentially lead to violation of the When possible, a dataclass is a lightweight solution perfectly suited for data manipulation. Lets dive into an example. -The following fictitional application has two commands: `build` and `status`. We can pretend that -the build action happens somewhere else in the world at an REST API endpoint and has significant -computational cost. The status command for all intents and purposes will only show the current +The following fictional application has two commands: `build` and `status`. We can pretend that the +build action happens somewhere else in the world at an REST API endpoint and has significant +computational cost. The status command for all intents and purposes, will only show the current status of a build task. The application has provided all that is needed for a user to start a build -and then determine it's status. The problem however is that with a long running process the user may +and then determine its status. The problem however is that with a long running process the user may want to wait for it to finish. A designer may be tempted to create a command to start a build and -then poll for status until finished but this scenario is better solved as an extensible script. +then poll for status until finished, but this scenario is better solved as an extensible script. app.py: @@ -419,7 +419,7 @@ class FirstApp(cmd2.Cmd): self._status_cache[args.name] = status self.poutput( - f"Build {args.name.upper()} successfully stared with id : {status.id}" + f"Build {args.name.upper()} successfully started with id : {status.id}" ) self.last_result = status diff --git a/docs/features/settings.md b/docs/features/settings.md index a315231e3..649dd0cbf 100644 --- a/docs/features/settings.md +++ b/docs/features/settings.md @@ -9,7 +9,7 @@ can modify them at runtime using the [set](./builtin_commands.md#set) command. D ## Builtin Settings -`cmd2` has a number of builtin settings. These settings control the behavior of certain application +`cmd2` has a number of built-in settings. These settings control the behavior of certain application features and [Buildin Commands](./builtin_commands.md). Users can use the [set](./builtin_commands.md#set) command to show all settings and to modify the value of any setting. @@ -136,7 +136,7 @@ It's 13 C - are you a penguin? ## Hide Builtin Settings -You may want to prevent a user from modifying a builtin setting. A setting must appear in the +You may want to prevent a user from modifying a built-in setting. A setting must appear in the `cmd2.Cmd.settable` dictionary in order for it to be available to the [set](./builtin_commands.md#set) command. diff --git a/docs/features/shortcuts_aliases_macros.md b/docs/features/shortcuts_aliases_macros.md index b286bc485..47c2586ea 100644 --- a/docs/features/shortcuts_aliases_macros.md +++ b/docs/features/shortcuts_aliases_macros.md @@ -36,7 +36,7 @@ in a similar fashion to aliases in the Bash shell. The syntax to create an alias is: `alias create name command [args]`, e.g. `alias create ls !ls -lF`. -Redirectors and pipes should be quoted in alias definition to prevent the `alias create` command +Redirectors and pipes should be quoted in the alias definition to prevent the `alias create` command from being redirected: alias create save_results print_results ">" out.txt @@ -63,16 +63,16 @@ Note: Aliases cannot have the same name as a command or macro `cmd2` provides a feature that is similar to aliases called macros. The major difference between macros and aliases is that macros can contain argument placeholders. Arguments are expressed when -creating a macro using {#} notation where {1} means the first argument. +creating a macro using `{#}` notation, where `{1}` means the first argument. -The following creates a macro called my[macro]{#macro} that expects two arguments: +The following creates a macro called `my_macro` that expects two arguments: - macro create my[macro]{#macro} make[dinner]{#dinner} -meat {1} -veggie {2} + macro create my_macro make_dinner -meat {1} -veggie {2} When the macro is called, the provided arguments are resolved and the assembled command is run. For example: - my[macro]{#macro} beef broccoli ---> make[dinner]{#dinner} -meat beef -veggie broccoli + my_macro beef broccoli ---> make_dinner -meat beef -veggie broccoli Similar to aliases, pipes and redirectors need to be quoted in the definition of a macro: diff --git a/docs/features/table_creation.md b/docs/features/table_creation.md index cd0a7278d..2509ba45f 100644 --- a/docs/features/table_creation.md +++ b/docs/features/table_creation.md @@ -5,5 +5,5 @@ As of version 3, `cmd2` no longer includes code for table creation. This is because `cmd2` now has a dependency on [rich](https://github.com/Textualize/rich) which has excellent support for this feature. -Please see rich's docummentation on [Tables](https://rich.readthedocs.io/en/latest/tables.html) for +Please see rich's documentation on [Tables](https://rich.readthedocs.io/en/latest/tables.html) for more information. diff --git a/docs/features/transcripts.md b/docs/features/transcripts.md index 1368b13e3..6404c035d 100644 --- a/docs/features/transcripts.md +++ b/docs/features/transcripts.md @@ -7,7 +7,7 @@ responses from commands that produce dynamic or variable output. ## Creating From History -A transcript can automatically generated based upon commands previously executed in the _history_ +A transcript can be automatically generated based upon commands previously executed in the _history_ using `history -t`: ```text @@ -23,7 +23,7 @@ This is by far the easiest way to generate a transcript. !!! warning - Make sure you use the **poutput()** method in your `cmd2` application for generating command output. This method of the `cmd2.Cmd` class ensure that output is properly redirected when redirecting to a file, piping to a shell command, and when generating a transcript. + Make sure you use the **poutput()** method in your `cmd2` application for generating command output. This method of the `cmd2.Cmd` class ensures that output is properly redirected when redirecting to a file, piping to a shell command, and when generating a transcript. ## Creating From A Script File @@ -117,7 +117,7 @@ characters like `.`, `^` and `$`, so you may want to double check the [Python regular expression documentation](https://docs.python.org/3/library/re.html). If your output has slashes in it, you will need to escape those slashes so the stuff between them is -not interpred as a regular expression. In this transcript: +not interpreted as a regular expression. In this transcript: ```text (Cmd) say cd /usr/local/lib/python3.11/site-packages diff --git a/docs/index.md b/docs/index.md index cbbdb7dfb..063af6c60 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ # cmd2 -A python package for building powerful command-line interpreter (CLI) programs. Extends the Python +A Python package for building powerful command-line interpreter (CLI) programs. Extends the Python Standard Library's [cmd](https://docs.python.org/3/library/cmd.html) package. The basic use of `cmd2` is identical to that of [cmd](https://docs.python.org/3/library/cmd.html). @@ -16,7 +16,7 @@ class App(Cmd): 2. Instantiate `App` and start the command loop: -```py title="Instatiating and starting a cmd2 app" linenums="1" hl_lines="5-6" +```py title="Instantiating and starting a cmd2 app" linenums="1" hl_lines="5-6" from cmd2 import Cmd class App(Cmd): # customized attributes and methods here diff --git a/docs/migrating/incompatibilities.md b/docs/migrating/incompatibilities.md index 030959d18..6ed3a0209 100644 --- a/docs/migrating/incompatibilities.md +++ b/docs/migrating/incompatibilities.md @@ -6,11 +6,11 @@ however there are a few incompatibilities. ## Cmd.emptyline() The [Cmd.emptyline()](https://docs.python.org/3/library/cmd.html#cmd.Cmd.emptyline) function is -called when an empty line is entered in response to the prompt. By default, in -[cmd](https://docs.python.org/3/library/cmd.html) if this method is not overridden, it repeats and -executes the last nonempty command entered. However, no end user we have encountered views this as -expected or desirable default behavior. `cmd2` completely ignores empty lines and the base class -`cmd.emptyline()` method never gets called and thus the empty line behavior cannot be overridden. +called when an empty line is entered in response to the prompt. By default, in `cmd` if this method +is not overridden, it repeats and executes the last nonempty command entered. However, no end user +we have encountered views this as expected or desirable default behavior. `cmd2` completely ignores +empty lines and the base class `cmd.emptyline()` method never gets called and thus the empty line +behavior cannot be overridden. ## Cmd.identchars diff --git a/docs/migrating/index.md b/docs/migrating/index.md index 1ea567485..806b47265 100644 --- a/docs/migrating/index.md +++ b/docs/migrating/index.md @@ -9,5 +9,5 @@ If you're thinking of migrating your [cmd](https://docs.python.org/3/library/cmd [cmd](https://docs.python.org/3/library/cmd.html). - [Minimum Required Changes](minimum.md) - the minimum changes required to move from [cmd](https://docs.python.org/3/library/cmd.html) to `cmd2`. Start your migration here. -- [Next Steps](next_steps.md) - Once you've migrated, here a list of things you can do next to add - even more functionality to your app. +- [Next Steps](next_steps.md) - Once you've migrated, here is a list of things you can do next to + add even more functionality to your app. diff --git a/docs/migrating/next_steps.md b/docs/migrating/next_steps.md index 892e05c78..a261bccfd 100644 --- a/docs/migrating/next_steps.md +++ b/docs/migrating/next_steps.md @@ -1,7 +1,7 @@ # Next Steps -Once your current application is using `cmd2`, you can start to expand the functionality by levering -other `cmd2` features. The three ideas here will get you started. Browse the rest of the +Once your current application is using `cmd2`, you can start to expand the functionality by +leveraging other `cmd2` features. The three ideas here will get you started. Browse the rest of the [Features](../features/index.md) to see what else `cmd2` can help you do. ## Argument Parsing @@ -16,7 +16,8 @@ Using this method will: arguments instead of a string of text. 2. Properly handle quoted string input from your users. 3. Create a help message for you based on the `ArgumentParser`. -4. Give you a big headstart adding [Tab Completion](../features/completion.md) to your application. +4. Give you a big head start adding [Tab Completion](../features/completion.md) to your + application. 5. Make it much easier to implement subcommands (i.e. `git` has a bunch of subcommands such as `git pull`, `git diff`, etc). @@ -25,7 +26,7 @@ dig in further. ## Help -If you have lot of commands in your application, `cmd2` can categorize those commands using a one +If you have a lot of commands in your application, `cmd2` can categorize those commands using a one line decorator `@with_category()`. When a user types `help` the available commands will be organized by the category you specified. @@ -39,7 +40,7 @@ what the code actually does. If your program generates output by printing directly to `sys.stdout`, you should consider switching to `cmd2.Cmd.poutput`, `cmd2.Cmd.perror`, and `cmd2.Cmd.pfeedback`. These methods work with several of the built in [Settings](../features/settings.md) to allow the user to view or suppress feedback -(i.e. progress or status output). They also properly handle ansi colored output according to user +(i.e. progress or status output). They also properly handle ANSI colored output according to user preference. Speaking of colored output, you can use any color library you want, or use the included `cmd2.string_utils.stylize` function. These and other related topics are covered in [Generating Output](../features/generating_output.md). diff --git a/docs/migrating/why.md b/docs/migrating/why.md index 060ef0c0e..6d647182e 100644 --- a/docs/migrating/why.md +++ b/docs/migrating/why.md @@ -39,7 +39,7 @@ and capabilities, without you having to do anything: - Users can load script files, which contain a series of commands to be executed. - Users can create [Shortcuts, Aliases, and Macros](../features/shortcuts_aliases_macros.md) to reduce the typing required for repetitive commands. -- Embedded python shell allows a user to execute python code from within your `cmd2` app. How meta. +- Embedded Python shell allows a user to execute Python code from within your `cmd2` app. How meta. - [Clipboard Integration](../features/clipboard.md) allows you to save command output to the operating system clipboard. - A built-in [Timer](../features/misc.md#Timer) can show how long it takes a command to execute diff --git a/docs/overview/alternatives.md b/docs/overview/alternatives.md index c1bbb7876..35b21723a 100644 --- a/docs/overview/alternatives.md +++ b/docs/overview/alternatives.md @@ -16,7 +16,7 @@ However, programming a `textual` application is not as straightforward as using Several Python packages exist for building interactive command-line applications approximately similar in concept to [cmd](https://docs.python.org/3/library/cmd.html) applications. None of them share `cmd2`'s close ties to [cmd](https://docs.python.org/3/library/cmd.html), but they may be -worth investigating nonetheless. Two of the most mature and full featured are: +worth investigating nonetheless. Two of the most mature and full-featured are: - [Python Prompt Toolkit](https://github.com/prompt-toolkit/python-prompt-toolkit) - [Click](https://click.palletsprojects.com) diff --git a/docs/overview/index.md b/docs/overview/index.md index a8cb8ee21..790bf98ea 100644 --- a/docs/overview/index.md +++ b/docs/overview/index.md @@ -6,7 +6,7 @@ Building a new [REPL](https://en.wikipedia.org/wiki/Read–eval–print_loop) or Already built an application that uses [cmd](https://docs.python.org/3/library/cmd.html) from the python standard library and want to add more functionality with very little work? -`cmd2` is a powerful python library for building command line applications. Start here to find out +`cmd2` is a powerful Python library for building command line applications. Start here to find out if this library is a good fit for your needs. - [Installation Instructions](installation.md) - how to install `cmd2` and associated optional @@ -14,5 +14,5 @@ if this library is a good fit for your needs. - [Getting Started Application](../examples/getting_started.md) - a sample application showing many key features of `cmd2` - [Integrate cmd2 Into Your Project](integrating.md) - adding `cmd2` to your project -- [Alternatives](alternatives.md) - other python packages that might meet your needs +- [Alternatives](alternatives.md) - other Python packages that might meet your needs - [Resources](resources.md) - related links and other materials diff --git a/docs/overview/installation.md b/docs/overview/installation.md index e3c12d60d..69f45630a 100644 --- a/docs/overview/installation.md +++ b/docs/overview/installation.md @@ -1,6 +1,6 @@ # Installation Instructions -`cmd2` works on Linux, macOS, and Windows. It requires Python 10 or higher, +`cmd2` works on Linux, macOS, and Windows. It requires Python 3.10 or higher, [pip](https://pypi.org/project/pip), and [setuptools](https://pypi.org/project/setuptools). If you've got all that, then you can just: @@ -18,9 +18,9 @@ $ pip install cmd2 ## Prerequisites -If you have Python 3 >=3.10 installed from [python.org](https://www.python.org), you will already -have [pip](https://pypi.org/project/pip) and [setuptools](https://pypi.org/project/setuptools), but -may need to upgrade to the latest versions: +If you have Python >=3.10 installed from [python.org](https://www.python.org), you will already have +[pip](https://pypi.org/project/pip) and [setuptools](https://pypi.org/project/setuptools), but may +need to upgrade to the latest versions: On Linux or OS X: @@ -93,11 +93,11 @@ identical to GNU Readline. `cmd2` will disable all tab-completion support if an of `readline` is found. When installed using `pip`, `uv`, or similar Python packaging tool on either `macOS` or `Windows`, -`cmd2` will automatically install a compatiable version of readline. +`cmd2` will automatically install a compatible version of readline. -Most `Linux` OSes come with a compatible version of readline. However, if you are using a tool like -`uv` to install Python on your system and configure a virtual environment, `uv` installed versions -of Python come with `libEdit`. +Most Linux operating systems come with a compatible version of readline. However, if you are using a +tool like `uv` to install Python on your system and configure a virtual environment, `uv` installed +versions of Python come with `libedit`. macOS comes with the [libedit](http://thrysoee.dk/editline/) library which is similar, but not identical, to GNU Readline. Tab completion for `cmd2` applications is only tested against GNU diff --git a/docs/overview/integrating.md b/docs/overview/integrating.md index fae95ec6a..b1db57534 100644 --- a/docs/overview/integrating.md +++ b/docs/overview/integrating.md @@ -18,7 +18,7 @@ inadvertently get installed with an incompatible future version of `cmd2`. If you would like to use [Tab Completion](../features/completion.md), then you need a compatible version of [readline](https://tiswww.case.edu/php/chet/readline/rltop.html) installed on your -operating system (OS). `cmd2` forces a sane install of `readline` on both `Windows` and `MacOS`, but +operating system (OS). `cmd2` forces a sane install of `readline` on both `Windows` and `macOS`, but does not do so on `Linux`. If for some reason, you have a Linux OS that has the [Editline Library (libedit)](https://www.thrysoee.dk/editline/) installed instead of `readline`, you will need to manually add a dependency on `gnureadline`. Make sure to include the following diff --git a/docs/plugins/external_test.md b/docs/plugins/external_test.md index 3bb3d39ae..0ebc3490f 100644 --- a/docs/plugins/external_test.md +++ b/docs/plugins/external_test.md @@ -56,7 +56,7 @@ def example_app(): Now write your tests that validate your application using the `cmd2_ext_test.ExternalTestMixin.app_cmd` function to access the cmd2 application's commands. This allows invocation of the application's commands in the same format as a user would type. The results -from calling a command matches what is returned from running an python script with cmd2's +from calling a command matches what is returned from running a Python script with cmd2's [run_pyscript](../features/builtin_commands.md#run_pyscript) command, which provides `stdout`, `stderr`, and the command's result data. diff --git a/docs/testing.md b/docs/testing.md index ab449dbba..7c5875586 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -6,7 +6,7 @@ This covers special considerations when writing unit tests for a cmd2 applicatio ## Testing Commands -The [External Test Plugin](plugins/external_test.md) provides a mixin class with an function that +The [External Test Plugin](plugins/external_test.md) provides a mixin class with a function that allows external calls to application commands. The `cmd2_ext_test.ExternalTestMixin.app_cmd` function captures and returns stdout, stderr, and the command-specific result data. @@ -18,8 +18,8 @@ If you need to mock anything in your cmd2 application, and most specifically in [spec=True](https://docs.python.org/3/library/unittest.mock.html#patch), or whatever equivalent is provided in the mocking library you're using. -In order to automatically load functions as commands cmd2 performs a number of reflection calls to -look up attributes of classes defined in your cmd2 application. Many mocking libraries will +In order to automatically load functions as commands, `cmd2` performs a number of reflection calls +to look up attributes of classes defined in your cmd2 application. Many mocking libraries will automatically create mock objects to match any attribute being requested, regardless of whether they're present in the object being mocked. This behavior can incorrectly instruct cmd2 to treat a function or attribute as something it needs to recognize and process. To prevent this, you should