Click REPL Plugin

0.3.0 · active · verified Thu Apr 09

click-repl is a Python library that provides a REPL (Read-Eval-Print Loop) plugin for Click-based command-line applications. It allows users to execute multiple commands in a single interactive session, maintaining a shared context. The current version is 0.3.0, released in June 2023, and it generally follows the release cadence of its upstream dependency, Click.

Common errors

```
ModuleNotFoundError: No module named 'click._bashcomplete'
```
cause This error occurs because older versions of `click-repl` (prior to 0.2.0) depended on an internal `click._bashcomplete` module, which was removed in Click version 8.0.0.

fix Upgrade `click-repl` to version 0.2.0 or newer using `pip install --upgrade click-repl`. Alternatively, downgrade Click to a version below 8.0.0 using `pip install "click<8.0.0"`.
```
AttributeError: 'Command' object has no attribute 'commands'
```
cause The `repl` function (or `register_repl`) expects a `click.Group` object or the context of a `Group` to provide available commands, but it received a `click.Command` object instead.

fix Ensure that `register_repl()` or `repl()` is called with a `click.Group` instance (e.g., `register_repl(cli)` where `cli` is a `click.Group`) or the context of a group, not a simple `click.Command`.
```
Unhandled UsageError exception when unsupported command is provided
```
cause When an unknown command is entered in the `click-repl` session, the underlying `click.UsageError` is not always caught and handled gracefully, leading to a traceback.

fix Upgrade `click-repl` to the latest version to ensure bug fixes related to exception handling are applied. For example: `pip install --upgrade click-repl`.
```
ModuleNotFoundError: No module named 'click'
```
cause The `click` library, which `click-repl` depends on, is not installed in the current Python environment.

fix Install the `click` package using pip: `pip install click`.

Warnings

breaking `click-repl` 0.3.0 dropped support for Python 2.x. Applications running on Python 2 must use an older version (e.g., 0.2.x).
Fix: Upgrade to Python 3.6+ or pin `click-repl` to a version compatible with Python 2.x (e.g., `click-repl<0.3.0`).
breaking In `click-repl` 0.3.0, the internal implementation for the `prompt()` function was changed to use `prompt_toolkit.PromptSession()` instead of `prompt_toolkit.prompt()`. While this fixed an unbound memory usage growth, it might subtly affect highly customized REPL environments that were directly interacting with the internal prompt mechanism.
Fix: Review custom REPL implementations, especially if directly manipulating `prompt_toolkit` internals, to ensure compatibility with `PromptSession`.
gotcha Older versions of `click-repl` (specifically prior to 0.2.0) were incompatible with Click 8.0.0 due to changes in Click's internal API. Attempting to use `click-repl` 0.1.x with Click 8+ will result in import errors or runtime failures.
Fix: Ensure `click-repl` is version 0.2.0 or higher when using Click 8.x or newer. The current version (0.3.0) is compatible.
gotcha When using `click-repl`, the parent context (`ctx.obj`) is reused between subcommands. This is a feature for performance but can be a footgun if you expect a fresh context for each REPL command, potentially leading to stale data or unexpected side effects if not handled carefully.
Fix: Be mindful of state stored in `ctx.obj` within the REPL. Explicitly clear or reset relevant data if a fresh state is required for subsequent commands.

Install

pip install click-repl Install stable version

Imports

register_repl
```
from click_repl import register_repl
```
repl
```
from click_repl import repl
```
Used for advanced REPL customization, instead of `register_repl`.

Quickstart

This quickstart demonstrates how to integrate `click-repl` into a basic Click application. It defines a Click group `cli` with two commands, `hello` and `greet`. The `register_repl(cli)` function adds a 'repl' subcommand to the CLI, enabling an interactive session where `hello` and `greet` can be executed. To run, save as `my_app.py` and execute `python my_app.py repl` in your terminal, then type `hello` or `greet yourname`.

import click
from click_repl import register_repl

@click.group()
def cli():
    """A simple CLI with a REPL."""
    pass

@cli.command()
def hello():
    click.echo("Hello from the REPL!")

@cli.command()
@click.argument('name')
def greet(name):
    click.echo(f"Nice to meet you, {name}!")

if __name__ == '__main__':
    register_repl(cli)
    cli()

view raw JSON →