summaryrefslogtreecommitdiff
path: root/cmd2/py_bridge.py
diff options
context:
space:
mode:
authorkotfu <kotfu@kotfu.net>2020-02-22 20:15:14 -0700
committerkotfu <kotfu@kotfu.net>2020-02-22 20:15:14 -0700
commitacf269f07f9437a54d8b02491ed1db3da05f374f (patch)
tree76b6aaf38ed4f110a6f598d1271f6d2bfa3f7971 /cmd2/py_bridge.py
parent44bf30ae5634046c1e428d1e2438d0f1a4cdcd43 (diff)
downloadcmd2-git-acf269f07f9437a54d8b02491ed1db3da05f374f.tar.gz
Add py_bridge API documentation
Diffstat (limited to 'cmd2/py_bridge.py')
-rw-r--r--cmd2/py_bridge.py42
1 files changed, 24 insertions, 18 deletions
diff --git a/cmd2/py_bridge.py b/cmd2/py_bridge.py
index b7346d22..6624d7ad 100644
--- a/cmd2/py_bridge.py
+++ b/cmd2/py_bridge.py
@@ -1,7 +1,7 @@
# coding=utf-8
"""
-Bridges calls made inside of a Python environment to the Cmd2 host app while maintaining a reasonable
-degree of isolation between the two
+Bridges calls made inside of a Python environment to the Cmd2 host app
+while maintaining a reasonable degree of isolation between the two.
"""
import sys
@@ -14,32 +14,38 @@ from .utils import namedtuple_with_defaults, StdSim
class CommandResult(namedtuple_with_defaults('CommandResult', ['stdout', 'stderr', 'stop', 'data'])):
"""Encapsulates the results from a cmd2 app command
- Named tuple attributes
- ----------------------
- stdout: str - output captured from stdout while this command is executing
- stderr: str - output captured from stderr while this command is executing. None if no error captured.
- stop: bool - return value of onecmd_plus_hooks after it runs the given command line.
- data - possible data populated by the command.
+ :stdout: str - output captured from stdout while this command is executing
+ :stderr: str - output captured from stderr while this command is executing
+ None if no error captured.
+ :stop: bool - return value of onecmd_plus_hooks after it runs the given
+ command line.
+ :data: possible data populated by the command.
- Any combination of these fields can be used when developing a scripting API for a given command.
- By default stdout, stderr, and stop will be captured for you. If there is additional command specific data,
- then write that to cmd2's last_result member. That becomes the data member of this tuple.
+ Any combination of these fields can be used when developing a scripting API
+ for a given command. By default stdout, stderr, and stop will be captured
+ for you. If there is additional command specific data, then write that to
+ cmd2's last_result member. That becomes the data member of this tuple.
- In some cases, the data member may contain everything needed for a command and storing stdout
- and stderr might just be a duplication of data that wastes memory. In that case, the StdSim can
- be told not to store output with its pause_storage member. While this member is True, any output
- sent to StdSim won't be saved in its buffer.
+ In some cases, the data member may contain everything needed for a command
+ and storing stdout and stderr might just be a duplication of data that
+ wastes memory. In that case, the StdSim can be told not to store output
+ with its pause_storage member. While this member is True, any output sent
+ to StdSim won't be saved in its buffer.
+
+ The code would look like this::
- The code would look like this:
if isinstance(self.stdout, StdSim):
self.stdout.pause_storage = True
if isinstance(sys.stderr, StdSim):
sys.stderr.pause_storage = True
- See StdSim class in utils.py for more information
+ See :class:`~cmd2.utils.StdSim` for more information.
+
+ .. note::
- NOTE: Named tuples are immutable. So the contents are there for access, not for modification.
+ Named tuples are immutable. The contents are there for access,
+ not for modification.
"""
def __bool__(self) -> bool:
"""Returns True if the command succeeded, otherwise False"""