summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorkotfu <kotfu@kotfu.net>2020-02-05 20:56:29 -0700
committerkotfu <kotfu@kotfu.net>2020-02-05 20:56:29 -0700
commit7476c27e95b6a9c1ee1c93893d678012c019cf7c (patch)
tree469fb2f21d78de458f80f276bda0d6f8a73fe554
parent58500cb0b86e8046b49aac5d554a6fa9630c0cd3 (diff)
downloadcmd2-git-7476c27e95b6a9c1ee1c93893d678012c019cf7c.tar.gz
Documentation updates
-rw-r--r--CHANGELOG.md20
-rw-r--r--docs/api/utility_classes.rst4
-rw-r--r--docs/conf.py3
-rw-r--r--docs/features/settings.rst25
-rwxr-xr-xexamples/environment.py10
5 files changed, 38 insertions, 24 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5117f1ed..77ba6b00 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,4 +1,4 @@
-## 0.9.26 (TBD, 2020)
+## 1.0.0-rc1 (TBD, 2020)
* Enhancements
* Changed the default help text to make `help -v` more discoverable
* Added `add_settable()` and `remove_settable()` convenience methods to update `self.settable` dictionary
@@ -10,9 +10,11 @@
* `prompt`
* `self.settable` changed to `self.settables`
* It is now a Dict[str, Settable] instead of Dict[str, str]
+ * setting onchange callbacks have a new method signature and must be added to the
+ Settable instance in order to be called
* **set** command now supports tab-completion of values
* Removed `cast()` utility function
-
+
## 0.9.25 (January 26, 2020)
* Enhancements
* Reduced what gets put in package downloadable from PyPI (removed irrelevant CI config files and such)
@@ -74,7 +76,7 @@
* Fix bug where cmd2 ran 'stty sane' command when stdin was not a terminal
* Enhancements
* Send all startup script paths to run_script. Previously we didn't do this if the file was empty, but that
- showed no record of the run_script command in history.
+ showed no record of the run_script command in history.
* Made it easier for developers to override `edit` command by having `do_history` no longer call `do_edit`. This
also removes the need to exclude `edit` command from history list.
* It is no longer necessary to set the `prog` attribute of an argparser with subcommands. cmd2 now automatically
@@ -143,7 +145,7 @@
* Enhancements
* Greatly simplified using argparse-based tab completion. The new interface is a complete overhaul that breaks
the previous way of specifying completion and choices functions. See header of [argparse_custom.py](https://github.com/python-cmd2/cmd2/blob/master/cmd2/argparse_custom.py)
- for more information.
+ for more information.
* Enabled tab completion on multiline commands
* **Renamed Commands Notice**
* The following commands were renamed in the last release and have been removed in this release
@@ -153,7 +155,7 @@
* We apologize for any inconvenience, but the new names are more self-descriptive
* Lots of end users were confused particularly about what exactly `load` should be loading
* Breaking Changes
- * Restored `cmd2.Cmd.statement_parser` to be a public attribute (no underscore)
+ * Restored `cmd2.Cmd.statement_parser` to be a public attribute (no underscore)
* Since it can be useful for creating [post-parsing hooks](https://cmd2.readthedocs.io/en/latest/features/hooks.html#postparsing-hooks)
* Completely overhauled the interface for adding tab completion to argparse arguments. See enhancements for more details.
* `ACArgumentParser` is now called `Cmd2ArgumentParser`
@@ -193,7 +195,7 @@
* `perror` - print a message to sys.stderr
* `pexcept` - print Exception message to sys.stderr. If debug is true, print exception traceback if one exists
* Signature of `poutput` and `perror` significantly changed
- * Removed color parameters `color`, `err_color`, and `war_color` from `poutput` and `perror`
+ * Removed color parameters `color`, `err_color`, and `war_color` from `poutput` and `perror`
* See the docstrings of these methods or the [cmd2 docs](https://cmd2.readthedocs.io/en/latest/features/generating_output.html) for more info on applying styles to output messages
* `end` argument is now keyword-only and cannot be specified positionally
* `traceback_war` no longer exists as an argument since it isn't needed now that `perror` and `pexcept` exist
@@ -203,7 +205,7 @@
* `COLORS_NEVER` --> `ANSI_NEVER`
* `COLORS_TERMINAL` --> `ANSI_TERMINAL`
* **Renamed Commands Notice**
- * The following commands have been renamed. The old names will be supported until the next release.
+ * The following commands have been renamed. The old names will be supported until the next release.
* `load` --> `run_script`
* `_relative_load` --> `_relative_run_script`
* `pyscript` --> `run_pyscript`
@@ -222,7 +224,7 @@
* Fixed issue where `_cmdloop()` suppressed exceptions by returning from within its `finally` code
* Fixed UnsupportedOperation on fileno error when a shell command was one of the commands run while generating
a transcript
- * Fixed bug where history was displaying expanded multiline commands when -x was not specified
+ * Fixed bug where history was displaying expanded multiline commands when -x was not specified
* Enhancements
* **Added capability to chain pipe commands and redirect their output (e.g. !ls -l | grep user | wc -l > out.txt)**
* `pyscript` limits a command's stdout capture to the same period that redirection does.
@@ -243,7 +245,7 @@
* Text scripts now run immediately instead of adding their commands to `cmdqueue`. This allows easy capture of
the entire script's output.
* Added member to `CommandResult` called `stop` which is the return value of `onecmd_plus_hooks` after it runs
- the given command line.
+ the given command line.
* Breaking changes
* Replaced `unquote_redirection_tokens()` with `unquote_specific_tokens()`. This was to support the fix
that allows terminators in alias and macro values.
diff --git a/docs/api/utility_classes.rst b/docs/api/utility_classes.rst
index 7ed0c584..2ee92ced 100644
--- a/docs/api/utility_classes.rst
+++ b/docs/api/utility_classes.rst
@@ -1,6 +1,10 @@
Utility Classes
===============
+.. autoclass:: cmd2.utils.Settable
+
+ .. automethod:: __init__
+
.. autoclass:: cmd2.utils.StdSim
.. autoclass:: cmd2.utils.ByteBuf
diff --git a/docs/conf.py b/docs/conf.py
index 7a8da9d1..16e8ecb7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -25,9 +25,6 @@ from pkg_resources import get_distribution
# Import for custom theme from Read the Docs
import sphinx_rtd_theme
-sys.path.insert(0, os.path.abspath('..'))
-
-
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
index 23c7686d..40b9bc35 100644
--- a/docs/features/settings.rst
+++ b/docs/features/settings.rst
@@ -3,8 +3,8 @@ Settings
Settings provide a mechanism for a user to control the behavior of a ``cmd2``
based application. A setting is stored in an instance attribute on your
-subclass of :class:`cmd2.cmd2.Cmd` and must also appear in the
-:attr:`cmd2.cmd2.Cmd.settable` dictionary. Developers may set default values
+subclass of :class:`.cmd2.Cmd` and must also appear in the
+:attr:`~.cmd2.Cmd.settable` dictionary. Developers may set default values
for these settings and users can modify them at runtime using the
:ref:`features/builtin_commands:set` command. Developers can
:ref:`features/settings:Create New Settings` and can also
@@ -116,15 +116,21 @@ Create New Settings
-------------------
Your application can define user-settable parameters which your code can
-reference. First create a class attribute with the default value. Then update
-the ``settable`` dictionary with your setting name and a short description
-before you initialize the superclass. Here's an example, from
+reference. In your initialization code:
+
+1. Create an instance attribute with a default value.
+2. Create a :class:`.Settable` object which describes your setting.
+3. Pass the :class:`.Settable` object to
+ :meth:`cmd2.cmd2.Cmd.add_settable`.
+
+Here's an example, from
``examples/environment.py``:
.. literalinclude:: ../../examples/environment.py
-If you want to be notified when a setting changes (as we do above), then define
-a method ``_onchange_{setting}()``. This method will be called after the user
+If you want to be notified when a setting changes (as we do above), then be
+sure to supply a method to the ``onchange_cb`` parameter of the
+`.cmd2.utils.Settable`. This method will be called after the user
changes a setting, and will receive both the old value and the new value.
.. code-block:: text
@@ -153,13 +159,14 @@ Hide Builtin Settings
---------------------
You may want to prevent a user from modifying a builtin setting. A setting
-must appear in the :attr:`cmd2.cmd2.Cmd.settable` dictionary in order for it
+must appear in the :attr:`~.cmd2.Cmd.settable` dictionary in order for it
to be available to the :ref:`features/builtin_commands:set` command.
Let's say that you never want end users of your program to be able to enable
full debug tracebacks to print out if an error occurs. You might want to hide
the :ref:`features/settings:debug` setting. To do so, remove it from the
-:attr:`cmd2.cmd2.Cmd.settable` dictionary after you initialize your object::
+:attr:`~.cmd2.Cmd.settable` dictionary after you initialize your object.
+The :meth:`~.cmd2.Cmd.remove_settable` convenience method makes this easy::
class MyApp(cmd2.Cmd):
diff --git a/examples/environment.py b/examples/environment.py
index fb90838c..a24734f1 100755
--- a/examples/environment.py
+++ b/examples/environment.py
@@ -8,12 +8,16 @@ import cmd2
class EnvironmentApp(cmd2.Cmd):
""" Example cmd2 application. """
- degrees_c = 22
- sunny = False
def __init__(self):
super().__init__()
- self.add_settable(cmd2.Settable('degrees_c', int, 'Temperature in Celsius'))
+ self.degrees_c = 22
+ self.sunny = False
+ self.add_settable(cmd2.Settable('degrees_c',
+ int,
+ 'Temperature in Celsius',
+ onchange_cb=self._onchange_degrees_c
+ ))
self.add_settable(cmd2.Settable('sunny', bool, 'Is it sunny outside?'))
def do_sunbathe(self, arg):