kmd

===== kmd

---

An interpreter framework

Overview

kmd allows to build command line driven shells with powerful tab-completion capabilities.

The kmd.Kmd class derives from cmd.Cmd_ and extends it in the following ways:

1. Instead of Python's readline_ module, kmd.Kmd uses the alternative rl_ readline bindings.

2. Setup and tear-down of the readline completer have been moved to preloop and postloop respectively. Subclasses must make sure to call their parents' implementations.

3. Incomplete command names are automatically expanded if they are unique.

4. Command aliases can be defined by extending the aliases dictionary. Alias names apply to all do_, complete_, and help_ attributes.

5. Lines starting with '#' are treated as comments. The new comment method is invoked, receiving the line as argument.

6. It is now possible to configure the shell_escape_chars. The default is '!'.

7. If a history_file is set, kmd.Kmd loads and saves the history in preloop and postloop.

8. The new run method encapsulates the full execution cycle of a Kmd.

.. _cmd.Cmd: https://docs.python.org/3/library/cmd.html .. _readline: https://docs.python.org/3/library/readline.html

Package Contents

kmd.Kmd Implements the mechanics of a command shell, based on cmd.Cmd_.

kmd.completions Implements a set of ready-to-use completions.

kmg.quoting Defines constants and functions for writing completions.

Documentation

For further details please refer to the API Documentation_.

.. _API Documentation: https://kmd.readthedocs.io/en/stable/

Development

kmd development is hosted on GitHub_ where it also has an issue tracker_.

.. _GitHub: https://github.com/stefanholek/kmd .. _issue tracker: https://github.com/stefanholek/kmd/issues

Installation

Installation requires Python 2.7 or higher.

Note: kmd uses the rl_ library which contains a C extension. It is a good idea to review its installation instructions_ and make sure all dependencies are in place.

To install the kmd package, type::

pip install kmd

.. _rl: https://github.com/stefanholek/rl .. _installation instructions: https://github.com/stefanholek/rl#installation

Changelog

2.4 - 2022-11-17

• Upgrade to rl 3.1. [stefan]

• Update filename completion for readline 8.2. [stefan]

• Hide do_EOF from completion and help. [stefan]

• Quote newline characters between double quotes. [stefan]

• Improve documentation and examples. [stefan]

• Replace deprecated python setup.py test in tox.ini. [stefan]

• Remove deprecated test_suite from setup.py. [stefan]

• Remove setuptools from install_requires. [stefan]

• Add a pyproject.toml file. [stefan]

• Include tests in sdist but not in wheel. [stefan]

2.3 - 2019-03-20

• Clear lastcmd when EOF is hit to avoid an infinite loop. See Python issue 13500_. [stefan]

• Drop explicit GPL because the PSF license is GPL-compatible anyway. [stefan]

• Update filename completion with new hooks. [stefan]

• Stop hiding the quoting module in completions and make it available as kmd.quoting. [stefan]

• Stop using rl.completer.reset because it overrides ~/.inputrc. [stefan]

• Stop using 2to3. [stefan]

• Require rl >= 3.0. [stefan]

.. _issue 13500: https://bugs.python.org/issue13500

2.2 - 2012-05-10

• String and filename quoting was not respected when Kmd.run was called with arguments. [stefan]

• Switch to a happier looking Sphinx theme. [stefan]

• Require rl >= 2.2. [stefan]

2.1.2 - 2012-04-14

• Update documentation more. [stefan]

2.1.1 - 2012-03-29

• Update documentation. [stefan]

2.1 - 2011-11-05

• Add Kmd.input method as extension point for subclasses. [stefan]

• Make sure hostname completion survives a missing hosts file. [stefan]

• Require rl >= 2.0.1. [stefan]

2.0 - 2011-10-06

• Add Kmd.aliases dictionary to define command aliases. [stefan]

• Refactor Kmd.do_help for easier customization. [stefan]

• Make sure error messages go to stderr. [stefan]

• Switch to pretty Sphinx-based docs. [stefan]

• Require rl >= 2.0. [stefan]

1.0 - 2011-07-14

• Initial release.