incenp.click-shell

A shell extension for Click


License
BSD-3-Clause
Install
pip install incenp.click-shell==2.1.0

Documentation

Incenp.Click-Shell - A shell extension for Click

Incenp.Click-Shell is an extension to click that easily turns your Click-powered Python command-line application into a shell utility. It is built on top of the built in Python cmd module, with modifications to make it work with Click.

Features

  • Adds a "shell" mode with command completion to any Click app.
  • Just a one line change for most click apps.

Usage

Simply replace @click.group with @incenp.click_shell.shell on the root level command:

import click
from incenp.click_shell import shell

# @click.group()  # no longer
@shell(prompt='my-app> ', intro='Starting my app...')
def my_app():
    pass

@my_app.command()
def testcommand():
    click.echo("testcommand is running")

# more commands

if __name__ == '__main__':
    my_app()

When run, you should expect an output like so:

$ python my_app.py
Starting my app...
my-app> testcommand
testcommand is running
my-app>

Using the Incenp.Click-Shell decorator alters the functionality of your program only when the program is called without a subcommand argument. Otherwise, your app will function identically to how it did before.

History

Incenp.Click-Shell is a fork of Clark Perkins’ click-shell, motivated by the lack of recent development in the original project and in particular the lack of support for recent versions of Click, which introduced changes that completely broke the original click-shell.

Incenp.Click-Shell is used in exactly the same way as the original click-shell, the only difference being that the module to import is named incenp.click_shell instead of click_shell.

Importantly, in this fork Python 2 support has been completely removed. If support for Python 2 is important for you, then you may keep using the original click-shell module instead; it won’t work with Click 8, but if you’re using Python 2 you’re stuck with older versions of Click anyway, since Click 8 also dropped support for Python 2.

Copying

Incenp.Click-Shell is distributed under a 3-clause BSD license. The full license is included in the LICENSE file of the source distribution.

Homepage and repository

The project is located at https://github.com/gouttegd/click-shell with the manual at https://incenp.org/dvlpt/click-shell/index.html.