Pypsi - Python Pluggable Shell Interface
========================================
.. image:: https://coveralls.io/repos/ameily/pypsi/badge.svg?branch=master&service=github
:target: https://coveralls.io/github/ameily/pypsi?branch=master
.. image:: https://travis-ci.com/ameily/pypsi.svg?branch=master
:target: https://travis-ci.com/ameily/pypsi
Develop extensible and powerful command line interface shells with minimal code.
Python Pluggable Shell Interface, or pypsi, is a framework for developing
command line based shell interfaces, akin to bash or csh. It is intended to be
a replacement for the builtin Python ``cmd`` module.
Pypsi is targeted towards both large scale and rapid prototype interface
shells. The bootstraping code is very small with very little boilerplate. Pypsi
ships with a great deal of capabilities out of the box, all of which can be used
or ignored. Pypsi is pluggable which allows commands, features, and plugins to be
developed independently in their own source files and/or Python classes. This
results in a very clean source repository. The actual code to setup and run the
shell is extremely small, on the order of ~20-50 lines of code.
Pypsi, at its core, is pluggable. There are many hooks that allow plugin authors
to extend and modify the core behavior of pypsi. Commands are isolated classes
that make distribution, sharing, and modification easy.
Releases
--------
The pypsi source code is hosted at `GitHub <https://github.com/ameily/pypsi>`_
and releases are stored at `PyPI <https://pypi.python.org/pypi/pypsi>`_. The
latest version can also be install via pip:
::
$ pip install pypsi
Documentation can be found on `GitHub Pages <http://ameily.github.io/pypsi>`_.
Features
--------
The following capabilities ship with pypsi and are available out of the box.
- I/O redirection
- Flexible API
- Tab completion
- Multiplatform
- Minimal dependencies
- Colors
- Session tips and message of the day (MOTD)
- Automated help, usage messages, and argument parsing
- Word wrapping
- Term highlighting (grep)
- Tables
- Prompt wizards
- ``cmd`` plugin to migrate existing ``cmd`` commands into pypsi
Demo
----
The ``demo.py`` source file can be run to demonstrate the base commands and
features that ship with pypsi (the ``demo.py`` file can be downloaded from the
git repo at https://github.com/ameily/pypsi/blob/master/demo.py). The commands
displayed below are all optional: pypsi does not require the use of any command
or plugin. The ``demo.py`` file is meant to be a reference to the Pypsi API and
design. Use it as a starting point for your first shell.
Variables
~~~~~~~~~
::
pypsi)> var name = "Paul"
pypsi)> var house = "Atredis"
pypsi)> echo My name is $name, and I belong to House $house
My name is Paul, and I belong to House Atredis
pypsi)> var --list
name Paul
house Atredis
pypsi)> var -d name
pypsi)> echo $name
pypsi)> var name = "Paul $house"
pypsi)> echo $name
Paul Atredis
I/O redirection
~~~~~~~~~~~~~~~
::
pypsi)> echo Hello
Hello
pypsi)> echo Hello > output.txt
pypsi)> echo Goodbye
pypsi)> xargs -I{} "echo line: {}" < output.txt
line: Hello
line: Goodbye
pypsi)> cat output.txt | grep ll
Hello
System commands
~~~~~~~~~~~~~~~
Allows execution of external applications. Command mimics Python's
``os.system()`` function.
::
pypsi)> ls
pypsi: ls: command not found
pypsi)> system ls
include/
src/
README.md
pypsi)> system ls | system grep md
README.md
Fallback command
~~~~~~~~~~~~~~~~
Allows the developer to set which command gets called if one does not exist in
the current shell. This is very useful, for example, if you want to fallback on
any OS installed executables. In this example, the fallback command is
``system``.
::
pypsi)> ls
include/
src/
README.md
Command chaining
~~~~~~~~~~~~~~~~
::
pypsi)> echo Hello && echo --bad-arg && echo goodbye
Hello
echo: unrecgonized arguments: --bad-arg
pypsi)> echo Hello ; echo --bad-arg ; echo goodbye
Hello
echo: unrecgonized arguments: --bad-arg
goodbye
pypsi)> echo --bad-arg || echo first failed
echo: unrecgonized arguments: --bad-arg
first failed
Multiline commands
~~~~~~~~~~~~~~~~~~
::
pypsi)> echo Hello, \
> Dave
Hello, Dave
pypsi)> echo This \
> is \
> pypsi \
> and it rocks
This is pypsi and it rocks
Macros
~~~~~~
Macros are analogous to functions in bash. They provide the ability to create
new commands in the shell.
::
pypsi)> macro hello
> echo Hello, $1
> echo Goodbye from macro $0
> end
pypsi)> hello Adam
Hello, Adam
Goodbye from macro hello
Tab Complete
~~~~~~~~~~~~
Tab completion is easier than ever with PyPsi. Using the included ``command_completer()``
function, arguments and sub-commands are completed automatically when the ``tab``
key is pressed. To get started, add the use of ``command_completer`` to your
custom command's complete function:
.. code-block:: python
def complete(self, shell, args, prefix):
from pypsi.completers import command_completer
return completions = command_completer(self.parser, shell, args, prefix)
Just pass ``command_completer`` the parser you created for the command, along with
the standard arguments to the ``complete`` function, and let PyPsi work it's magic!
::
pypsi)> macro -<tab>
--delete --help --list --show -d -h -l -s
For each argument added to a PyPsi Argument parser, a callback function to get
the possible completions can be specified via the `completer` argument.
The callback function will be called from ``command_completer`` anytime tab is
pressed while the user is currently entering that argument's value. Ex:
.. code-block:: python
# Snippet from macro.py
self.parser.add_argument(
'-s', '--show', help='print macro body',
metavar='NAME', completer=self.complete_macros
)
...
def complete_macros(self, shell, args, prefix):
# returns a list of macro names in the current shell
return list(shell.ctx.macros.keys())
::
pypsi)> macro --show <tab>
hello goodbye
See ``tail.py``, ``help.py``, and ``macro.py`` for examples.
Prompt Wizards
~~~~~~~~~~~~~~
Prompt wizards ask the user a series of questions and request input. Input is
tab completed, validated, and returned. The wizard can be used for easy
configuration of components that require a substantial amount of input.
::
pypsi)> wizard
+-----------------------------------------------------------------------------+
| Entering Example Configuration Wizard |
+-----------------------------------------------------------------------------+
Shows various examples of wizard steps
To exit, enter either Ctrl+C, Ctrl+D, or 'quit'. For help about the current
step, enter 'help' or '?'.
IP Address: <enter>
Error: Value is required
Local IP Address or Host name
IP Address: 192.168.0.10
TCP Port [1337]: <enter>
File path: /var/lo<tab>
local/ lock/ log/
File path: /var/log/<tab>
Xorg.1.log btmp faillog upstart/
Xorg.1.log.old dist-upgrade/ fontconfig.log wtmp
alternatives.log distccd.log fsck/
apt/ dmesg lastlog
bootstrap.log dpkg.log mongodb/
File path: /var/log/dpkg.log
Shell mode [local]: asdf
Error: Invalid choice
Mode of the shell
Shell mode [local]: remote
Config ID Config Value
================================================================================
ip_addr 172.16.11.204
port 1337
path /var/log/dpkg.log
mode remote
License
-------
``pypsi`` is released under the ISC permissive license.
Raw data
{
"_id": null,
"home_page": "https://github.com/ameily/pypsi",
"name": "pypsi",
"maintainer": null,
"docs_url": "https://pythonhosted.org/pypsi/",
"requires_python": null,
"maintainer_email": null,
"keywords": "cli, command line, command line interface, shell, terminal, console, term, command prompt",
"author": "Adam Meily",
"author_email": "meily.adam@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/63/57/b42f34b04e34fe348f17ca1e736d37c58fb6c8b0a1416257e6740433eee8/pypsi-1.4.7.tar.gz",
"platform": null,
"description": "Pypsi - Python Pluggable Shell Interface\r\n========================================\r\n\r\n.. image:: https://coveralls.io/repos/ameily/pypsi/badge.svg?branch=master&service=github\r\n :target: https://coveralls.io/github/ameily/pypsi?branch=master\r\n\r\n.. image:: https://travis-ci.com/ameily/pypsi.svg?branch=master\r\n :target: https://travis-ci.com/ameily/pypsi\r\n\r\nDevelop extensible and powerful command line interface shells with minimal code.\r\n\r\nPython Pluggable Shell Interface, or pypsi, is a framework for developing\r\ncommand line based shell interfaces, akin to bash or csh. It is intended to be\r\na replacement for the builtin Python ``cmd`` module.\r\n\r\nPypsi is targeted towards both large scale and rapid prototype interface\r\nshells. The bootstraping code is very small with very little boilerplate. Pypsi\r\nships with a great deal of capabilities out of the box, all of which can be used\r\nor ignored. Pypsi is pluggable which allows commands, features, and plugins to be\r\ndeveloped independently in their own source files and/or Python classes. This\r\nresults in a very clean source repository. The actual code to setup and run the\r\nshell is extremely small, on the order of ~20-50 lines of code.\r\n\r\nPypsi, at its core, is pluggable. There are many hooks that allow plugin authors\r\nto extend and modify the core behavior of pypsi. Commands are isolated classes\r\nthat make distribution, sharing, and modification easy.\r\n\r\nReleases\r\n--------\r\n\r\nThe pypsi source code is hosted at `GitHub <https://github.com/ameily/pypsi>`_\r\nand releases are stored at `PyPI <https://pypi.python.org/pypi/pypsi>`_. The\r\nlatest version can also be install via pip:\r\n\r\n::\r\n\r\n $ pip install pypsi\r\n\r\nDocumentation can be found on `GitHub Pages <http://ameily.github.io/pypsi>`_.\r\n\r\nFeatures\r\n--------\r\n\r\nThe following capabilities ship with pypsi and are available out of the box.\r\n\r\n- I/O redirection\r\n- Flexible API\r\n- Tab completion\r\n- Multiplatform\r\n- Minimal dependencies\r\n- Colors\r\n- Session tips and message of the day (MOTD)\r\n- Automated help, usage messages, and argument parsing\r\n- Word wrapping\r\n- Term highlighting (grep)\r\n- Tables\r\n- Prompt wizards\r\n- ``cmd`` plugin to migrate existing ``cmd`` commands into pypsi\r\n\r\nDemo\r\n----\r\n\r\nThe ``demo.py`` source file can be run to demonstrate the base commands and\r\nfeatures that ship with pypsi (the ``demo.py`` file can be downloaded from the\r\ngit repo at https://github.com/ameily/pypsi/blob/master/demo.py). The commands\r\ndisplayed below are all optional: pypsi does not require the use of any command\r\nor plugin. The ``demo.py`` file is meant to be a reference to the Pypsi API and\r\ndesign. Use it as a starting point for your first shell.\r\n\r\nVariables\r\n~~~~~~~~~\r\n\r\n::\r\n\r\n pypsi)> var name = \"Paul\"\r\n\r\n pypsi)> var house = \"Atredis\"\r\n\r\n pypsi)> echo My name is $name, and I belong to House $house\r\n\r\n My name is Paul, and I belong to House Atredis\r\n\r\n pypsi)> var --list\r\n\r\n name Paul\r\n house Atredis\r\n\r\n pypsi)> var -d name\r\n\r\n pypsi)> echo $name\r\n\r\n pypsi)> var name = \"Paul $house\"\r\n\r\n pypsi)> echo $name\r\n\r\n Paul Atredis\r\n\r\nI/O redirection\r\n~~~~~~~~~~~~~~~\r\n\r\n::\r\n\r\n pypsi)> echo Hello\r\n\r\n Hello\r\n\r\n pypsi)> echo Hello > output.txt\r\n\r\n pypsi)> echo Goodbye\r\n\r\n pypsi)> xargs -I{} \"echo line: {}\" < output.txt\r\n\r\n line: Hello\r\n line: Goodbye\r\n\r\n pypsi)> cat output.txt | grep ll\r\n\r\n Hello\r\n\r\nSystem commands\r\n~~~~~~~~~~~~~~~\r\n\r\nAllows execution of external applications. Command mimics Python's\r\n``os.system()`` function.\r\n\r\n::\r\n\r\n pypsi)> ls\r\n\r\n pypsi: ls: command not found\r\n\r\n pypsi)> system ls\r\n\r\n include/\r\n src/\r\n README.md\r\n\r\n pypsi)> system ls | system grep md\r\n\r\n README.md\r\n\r\nFallback command\r\n~~~~~~~~~~~~~~~~\r\n\r\nAllows the developer to set which command gets called if one does not exist in\r\nthe current shell. This is very useful, for example, if you want to fallback on\r\nany OS installed executables. In this example, the fallback command is\r\n``system``.\r\n\r\n::\r\n\r\n pypsi)> ls\r\n\r\n include/\r\n src/\r\n README.md\r\n\r\nCommand chaining\r\n~~~~~~~~~~~~~~~~\r\n\r\n::\r\n\r\n pypsi)> echo Hello && echo --bad-arg && echo goodbye\r\n\r\n Hello\r\n echo: unrecgonized arguments: --bad-arg\r\n\r\n pypsi)> echo Hello ; echo --bad-arg ; echo goodbye\r\n\r\n Hello\r\n echo: unrecgonized arguments: --bad-arg\r\n goodbye\r\n\r\n pypsi)> echo --bad-arg || echo first failed\r\n\r\n echo: unrecgonized arguments: --bad-arg\r\n first failed\r\n\r\nMultiline commands\r\n~~~~~~~~~~~~~~~~~~\r\n\r\n::\r\n\r\n pypsi)> echo Hello, \\\r\n > Dave\r\n\r\n Hello, Dave\r\n\r\n pypsi)> echo This \\\r\n > is \\\r\n > pypsi \\\r\n > and it rocks\r\n\r\n This is pypsi and it rocks\r\n\r\nMacros\r\n~~~~~~\r\n\r\nMacros are analogous to functions in bash. They provide the ability to create\r\nnew commands in the shell.\r\n\r\n::\r\n\r\n pypsi)> macro hello\r\n > echo Hello, $1\r\n > echo Goodbye from macro $0\r\n > end\r\n\r\n pypsi)> hello Adam\r\n\r\n Hello, Adam\r\n Goodbye from macro hello\r\n\r\nTab Complete\r\n~~~~~~~~~~~~\r\n\r\nTab completion is easier than ever with PyPsi. Using the included ``command_completer()``\r\nfunction, arguments and sub-commands are completed automatically when the ``tab``\r\nkey is pressed. To get started, add the use of ``command_completer`` to your\r\ncustom command's complete function:\r\n\r\n.. code-block:: python\r\n\r\n def complete(self, shell, args, prefix):\r\n from pypsi.completers import command_completer\r\n return completions = command_completer(self.parser, shell, args, prefix)\r\n\r\nJust pass ``command_completer`` the parser you created for the command, along with\r\nthe standard arguments to the ``complete`` function, and let PyPsi work it's magic!\r\n\r\n::\r\n\r\n pypsi)> macro -<tab>\r\n --delete --help --list --show -d -h -l -s\r\n\r\nFor each argument added to a PyPsi Argument parser, a callback function to get\r\nthe possible completions can be specified via the `completer` argument.\r\nThe callback function will be called from ``command_completer`` anytime tab is\r\npressed while the user is currently entering that argument's value. Ex:\r\n\r\n.. code-block:: python\r\n\r\n # Snippet from macro.py\r\n self.parser.add_argument(\r\n '-s', '--show', help='print macro body',\r\n metavar='NAME', completer=self.complete_macros\r\n )\r\n ...\r\n def complete_macros(self, shell, args, prefix):\r\n # returns a list of macro names in the current shell\r\n return list(shell.ctx.macros.keys())\r\n\r\n::\r\n\r\n pypsi)> macro --show <tab>\r\n hello goodbye\r\n\r\nSee ``tail.py``, ``help.py``, and ``macro.py`` for examples.\r\n\r\n\r\nPrompt Wizards\r\n~~~~~~~~~~~~~~\r\n\r\nPrompt wizards ask the user a series of questions and request input. Input is\r\ntab completed, validated, and returned. The wizard can be used for easy\r\nconfiguration of components that require a substantial amount of input.\r\n\r\n::\r\n\r\n pypsi)> wizard\r\n +-----------------------------------------------------------------------------+\r\n | Entering Example Configuration Wizard |\r\n +-----------------------------------------------------------------------------+\r\n Shows various examples of wizard steps\r\n\r\n To exit, enter either Ctrl+C, Ctrl+D, or 'quit'. For help about the current\r\n step, enter 'help' or '?'.\r\n\r\n IP Address: <enter>\r\n\r\n Error: Value is required\r\n Local IP Address or Host name\r\n\r\n IP Address: 192.168.0.10\r\n\r\n TCP Port [1337]: <enter>\r\n\r\n File path: /var/lo<tab>\r\n\r\n local/ lock/ log/\r\n\r\n File path: /var/log/<tab>\r\n\r\n Xorg.1.log btmp faillog upstart/\r\n Xorg.1.log.old dist-upgrade/ fontconfig.log wtmp\r\n alternatives.log distccd.log fsck/\r\n apt/ dmesg lastlog\r\n bootstrap.log dpkg.log mongodb/\r\n\r\n File path: /var/log/dpkg.log\r\n\r\n Shell mode [local]: asdf\r\n\r\n Error: Invalid choice\r\n\r\n Mode of the shell\r\n\r\n Shell mode [local]: remote\r\n\r\n Config ID Config Value\r\n ================================================================================\r\n ip_addr 172.16.11.204\r\n port 1337\r\n path /var/log/dpkg.log\r\n mode remote\r\n\r\nLicense\r\n-------\r\n\r\n``pypsi`` is released under the ISC permissive license.\r\n",
"bugtrack_url": null,
"license": "ISC",
"summary": "Python Pluggable Shell Interface",
"version": "1.4.7",
"project_urls": {
"Download": "https://pypi.python.org/pypi/pypsi",
"Homepage": "https://github.com/ameily/pypsi"
},
"split_keywords": [
"cli",
" command line",
" command line interface",
" shell",
" terminal",
" console",
" term",
" command prompt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "076d8434a997cc011f418214a89d5655d7515cb819fbe6b88e6bdd79448b84a4",
"md5": "12311259ad56daad945ac87efb16e5a6",
"sha256": "5f30f02eaf1da63d3a2be8fd03064e81ef854cd7d520d730ff589c469aa64a95"
},
"downloads": -1,
"filename": "pypsi-1.4.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "12311259ad56daad945ac87efb16e5a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 89221,
"upload_time": "2025-01-15T20:10:24",
"upload_time_iso_8601": "2025-01-15T20:10:24.131672Z",
"url": "https://files.pythonhosted.org/packages/07/6d/8434a997cc011f418214a89d5655d7515cb819fbe6b88e6bdd79448b84a4/pypsi-1.4.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6357b42f34b04e34fe348f17ca1e736d37c58fb6c8b0a1416257e6740433eee8",
"md5": "615915782a15601bd042e32260815b06",
"sha256": "439c4a0be8587585b8bc29c3be9688602da5b9a694e67d774608d47b468ab4c9"
},
"downloads": -1,
"filename": "pypsi-1.4.7.tar.gz",
"has_sig": false,
"md5_digest": "615915782a15601bd042e32260815b06",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 67903,
"upload_time": "2025-01-15T20:10:26",
"upload_time_iso_8601": "2025-01-15T20:10:26.500548Z",
"url": "https://files.pythonhosted.org/packages/63/57/b42f34b04e34fe348f17ca1e736d37c58fb6c8b0a1416257e6740433eee8/pypsi-1.4.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-15 20:10:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ameily",
"github_project": "pypsi",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "pypsi"
}
JSON
