Inpromptu
A library for inferring interactive prompts from object instances.
What Inpromptu Is
Inpromptu is a near-direct replacement for Python's built-in cmd.py utility.
Rather than rewrite an extra class with special do_
methods, Inpromptu will infer a prompt from the class directly.
Inpromptu takes an object instance's callables and exposes them in a read-evaluate-print-loop that supports tab-completion.
Born from a need to quickly interact with real-world devices and a frustration from the manual overhead of cmd.py, Inpromptu automatically generates an interactive prompt session by taking advantage of Python's type hinting and introspection capabilities. Features include
- seamless automatic tab completion using a method's function signature
- supports:
bool
,int
,float
,str
, anything that inherits fromEnum
- supports:
- automatic help generation using a method's docstring
Inpromptu also provides a prompt_toolkit-compatible completer so you can build more complicated prompts while getting all of inpromptu's introspection elements for free.
What Inpromptu Isn't
Inpromptu creates an interactive prompt. Inpromptu is not:
- a command line interface generator. See argparse, python-fire, or click for that.
- a api-replacement for cmd.py. There are some differences, mainly the lack of
do_
methods. Have a go at the examples.
Requirements
- Python 3.6 or later
- all methods that will support completion must have all parameters type-hinted
Installation
You can install this latest stable version of this package from PyPI with
pip install inpromptu
Or you can clone this repository and, from within this directory, install inpromptu in editable mode with
pip install -e .
Example Time
Start with a class in file such as test_drive.py.
class TestDrive:
def __init__(self):
"""initialization!"""
self.vehicle_speed = 0
honk(self):
"""beep the horn."""
print("Beep!")
speed(self):
"""return the vehicle speed."""
return self.vehicle_speed
Create a prompt with Inpromptu.
from inpromptu import Inpromptu
my_test_drive = TestDrive()
my_prompt = Inpromptu(my_test_drive)
my_prompt.cmdloop()
Run it!
python3 test_drive.py
This should produce a prompt:
>>>
Press tab twice to show all your callable attributes.
honk speed
>>>
Great! Now let's demo argument completion.
First, add a function with type-hinted annotations for all input arguments (except self or cls).
add_fuel(self, gallons: float = 0, top_off: bool = False):
"""Add fuel in gallons.""
pass
Run it!
python3 test_drive.py
Start typing at the prompt
>>> add_f
Press tab to complete any function.
>>> add_fuel
Put a space between the command and press tab twice.
gallons=<float> top_off=<False>
>>> add_fuel
Magic! At this point you can finish entering the command in many ways.
>>> add_fuel gallons=10 top_off=False
OR
>>> add_fuel 10 False
OR
>>> add_fuel 10 top_off=False
In other words, arguments can be filled out by name or by position or by a combination of position first, then by name--just like how *args and **kwds behave on normal python functions.
So what are you waiting for? Why not take it for a test drive? From the example directory, run:
python3 test_drive.py
FAQs
Why not just use the python shell?
You could! Inpromptu is intented to be a bit more minimalistic and user-friendly. Inpromptu can be used as a minimalistic UI on its own.
Is there any way I can tease out the core elements to build my own interface?
Yes. In fact, core elements of Inpromptu can be hooked directly into Python Prompt Toolkit to provide the same kind of object-based completions with richer prompt features. See the examples folder for some inspiration.
What's not implemented?
- functions that use
*args
and**kwds
as input - The @overload operator.
- functions wrapped in decorators: like
@cache
,@cached_property
from functools- Note: some cases may work already.
- Recording a series of commands.
What's Going to be Implemented Next?
*args
and**kwds
- Explicit handling of functions wrapped in decorators.
- Overloading completions for specified functions
About the Author
Inpromptu was written by someone who used cmd.py one-too-many times. There had to be a better solution. And Inpromptu is one of many.