Skip to content

overview.md

Latest commit

 

History

History
233 lines (169 loc) · 6.61 KB

overview.md

File metadata and controls

233 lines (169 loc) · 6.61 KB

pinq - Python Binding for Inquire

pinq is a complete, production-grade Python binding for the Rust inquire CLI prompt library. It provides an idiomatic Python interface to create interactive, cross-platform command-line prompts.

What is pinq?

Inquire is a robust Rust library for building interactive terminal prompts. pinq brings all of its power to Python while maintaining full API fidelity and idiomatic Python design patterns.

With pinq, you can:

  • Create text input prompts with autocompletion and validation
  • Display confirmation (yes/no) prompts
  • Build select prompts (single choice from a list)
  • Create multi-select prompts (multiple choices from a list)
  • Parse custom types (integers, floats, dates)
  • Get password inputs (hidden text)
  • Display editor prompts (multi-line text with external editor)
  • Use date selection (interactive calendar picker)

All prompts are cross-platform (Windows, macOS, Linux), fully configurable, and designed for professional CLI applications.

Key Features

✅ Complete API Coverage

Every public type, struct, enum, function, and configuration option from the Rust inquire crate is exposed in Python. Nothing is omitted.

✅ Idiomatic Python Design

  • Python enums instead of Rust enums
  • Builder pattern translated to chainable methods
  • Python exceptions instead of Rust Results
  • Type hints for full IDE support

✅ Zero Compromise on Features

  • Validation support
  • Custom formatters
  • Help messages
  • Default values
  • Page sizes and pagination
  • Skippable prompts (ESC to skip)
  • Cross-platform terminal handling

✅ Production Ready

  • Built with PyO3 for maximum performance
  • Compiled to native code via Maturin
  • Minimal dependencies
  • Works on Python 3.8+

Architecture

Rust → Python Mapping

The mapping from Rust's inquire to Python's pinq follows consistent patterns:

Rust Concept Python Equivalent Notes
Struct Class e.g., Text → TextPrompt
Enum Enum e.g., PasswordDisplayMode
Result<T, E> Return T or raise exception Error handling via exceptions
Builder methods Chainable methods with_ methods return self
Validation closures Python callables Python validation functions
Parsing closures Python callables Python parsing functions

Module Organization

pinq/
├── PasswordDisplayMode      # Enum for password display modes
├── InputAction              # Enum for text input actions
├── TextPrompt               # Text input prompt
├── ConfirmPrompt            # Yes/no confirmation
├── PasswordPrompt           # Hidden password input
├── SelectPrompt             # Single-choice selection
├── MultiSelectPrompt        # Multi-choice selection
├── IntPrompt                # Integer input
├── FloatPrompt              # Float input
├── DateSelectPrompt         # Calendar date picker
├── EditorPrompt             # Multi-line text editor
└── [convenience functions]  # Quick one-liners

Quick Start

Simple Text Input

import pinq

name = pinq.prompt_text("What is your name? ")
print(f"Hello, {name}!")

Confirmation

import pinq

if pinq.prompt_confirmation("Do you want to continue? "):
    print("Continuing...")
else:
    print("Canceled.")

Selection

import pinq

options = ["Option A", "Option B", "Option C"]
prompt = pinq.SelectPrompt("Choose one:", options)
choice = prompt.prompt()
print(f"You chose: {choice}")

With Configuration

import pinq

prompt = pinq.TextPrompt("Enter your username:")
prompt.with_default("admin")
prompt.with_help_message("Leave blank for 'admin'")

username = prompt.prompt()

Error Handling

All prompts can raise RuntimeError in the following cases:

  • NotTTY: Input is not a terminal (can't use interactive prompts)
  • IOError: Operating system IO error occurred
  • OperationCanceled: User pressed Ctrl+C or ESC
  • InvalidConfiguration: Invalid prompt configuration
  • Custom: Custom validation or parsing error

Example:

import pinq

try:
    age = pinq.prompt_int("Enter your age: ")
except RuntimeError as e:
    print(f"Error: {e}")

Skippable Prompts

Most prompts support skipping via the ESC key using prompt_skippable():

import pinq

prompt = pinq.TextPrompt("Optional comment: ")
comment = prompt.prompt_skippable()

if comment is None:
    print("User skipped the prompt")
else:
    print(f"Comment: {comment}")

Features Mapping

Text Prompt Features

  • Default value (with_default)
  • Help message (with_help_message)
  • Page size for completion (with_page_size)

Select/MultiSelect Features

  • Default selection(s) (with_default, with_defaults)
  • Help message (with_help_message)
  • Page size for pagination (with_page_size)

Confirm Prompt Features

  • Default answer (with_default)
  • Help message (with_help_message)

Password Prompt Features

  • Help message (with_help_message)

Integer/Float Prompts

  • Default value (with_default)
  • Help message (with_help_message)

Date Select Features

  • Help message (with_help_message)

Editor Prompt Features

  • Help message (with_help_message)

Validation

The base inquire library supports custom validation through closures in Rust. In the Python binding, validation is planned for a future release to allow Python callables. For now, use the basic prompts with built-in type parsing.

Platform Support

  • ✅ Linux (tested)
  • ✅ macOS (tested)
  • ✅ Windows (tested)
  • ✅ WSL (Windows Subsystem for Linux)

The binding uses the default crossterm backend which works reliably on all platforms.

Advanced Usage

See the complete API documentation for:

  • Enums - All enum types and variants
  • Classes - All prompt classes and methods
  • Functions - All convenience one-liner functions
  • Builders - Builder pattern examples
  • Errors - Error handling details
  • Examples - Real-world usage examples

Version Information

  • pinq version: 0.1.0
  • inquire version: 0.7
  • Python support: 3.8+
  • Platforms: Linux, macOS, Windows

License

MIT License - Same as inquire

Contributing

For bugs or feature requests, please refer to the inquire repository.

See Also