Click REPL Plugin

0.3.0 · active · verified Sat Mar 28

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.

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 →