riposte

Introducing Riposte

Overview

Riposte is a powerful tool designed to help developers integrate an interactive shell into their applications with ease. By taking care of routine tasks associated with creating Read-Eval-Print Loops (REPLs), Riposte allows developers to concentrate on the core functionalities of their applications. Initially developed to untangle the complex shell logic from the primary codebase in the routersploit project, Riposte has become an invaluable asset for developers seeking a robust solution for building custom interactive shells.

Getting Started

Installing Riposte

Riposte can be easily installed via Python's package manager, pip. It’s compatible with Python version 3.8 and newer. Simply open your terminal and run the following command:

pip install riposte

Example Usage

Here is a brief example showcasing how Riposte can be used to create a simple command-line calculator:

from riposte import Riposte

calculator = Riposte(prompt="calc:~$ ")

MEMORY = []

@calculator.command("add")
def add(x: int, y: int):
    result = f"{x} + {y} = {x + y}"
    MEMORY.append(result)
    calculator.success(result)

@calculator.command("multiply")
def multiply(x: int, y: int):
    result = f"{x} * {y} = {x * y}"
    MEMORY.append(result)
    calculator.success(result)

@calculator.command("memory")
def memory():
    for entry in MEMORY:
        calculator.print(entry)

calculator.run()

With this setup, users can execute commands such as add, multiply, or memory directly from the interactive shell.

Features

Command Registration

Developers can register commands using the @Riposte.command decorator. This feature allows the creation of actionable commands that can perform various tasks. Here is an example:

from riposte import Riposte

repl = Riposte()

@repl.command("hello")
def hello():
    repl.success("Is it me you're looking for?")

repl.run()

Completer

Riposte offers support for command completion using the TAB key. You can enhance your REPL with a completer function associated with specific commands, improving user experience significantly.

@repl.complete("start")
def start_completer(text, line, start_index, end_index):
    # Logic for auto-completion

Guides

Riposte utilizes Python's type hints to interpret command arguments, ensuring that inputs are correctly processed into the expected types. Custom guidelines can also be specified for more complex input parsing scenarios.

@repl.command("guideme")
def guideme(x: int, y: str):
    # Operation logic

Thread Safe Printing

Riposte includes built-in methods for safe printing across threads, such as print, info, error, and more, all providing color-coded outputs corresponding to their message type.

History and Prompt Customization

Riposte saves command history by default, allowing users to review previously executed commands. Additionally, prompts can be customized to your liking or dynamically altered based on set conditions.

Advanced Features

Inline Command Execution

Riposte allows executing multiple commands at once by separating them with semicolons, much like a typical shell environment.

Custom CLI and Input Streams

Customize the CLI arguments for your Riposte applications to fit specific needs, or add unique input streams to control how commands are sent into your REPL. This flexibility allows integrating various input methods, such as files or external messaging systems.

Contribution and Status

Riposte is currently in development and is considered to be in a beta phase. The project might experience breaking changes as it evolves. Contributions are welcome; those interested can check the contributing guidelines and versioning details provided on the project’s repository.

Riposte stands as a testament to the power of simplicity and functionality, offering developers an efficient way to embed sophisticated interactive interfaces within their Python applications.