Metadata-Version: 2.1
Name: kmd
Version: 2.4
Summary: An interpreter framework
Home-page: https://github.com/stefanholek/kmd
Author: Stefan H. Holek
Author-email: stefan@epy.co.at
License: PSF-2.0
Project-URL: Documentation, https://kmd.readthedocs.io/en/stable/
Keywords: command line,command shell,shell,interpreter,REPL
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Python Software Foundation License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: Implementation :: CPython
License-File: LICENSE
Requires-Dist: rl (>=3.1)
Provides-Extra: docs
Requires-Dist: sphinx (==5.3.0) ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme (==1.0.0) ; extra == 'docs'

=====
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.
