Complete documentation of all prompt classes in pinq.
Interactive text input prompt with support for default values and help messages.
prompt = pinq.TextPrompt(message: str)Parameters:
message(str): The question or prompt text shown to the user
Raises:
- None (construction never fails)
Set a default value for the prompt. If the user presses Enter without typing, this value is returned.
prompt = pinq.TextPrompt("Username: ")
prompt.with_default("admin")Returns: Self for method chaining
Set a help message displayed below the main prompt question.
prompt = pinq.TextPrompt("Email: ")
prompt.with_help_message("Format: user@example.com")Returns: Self for method chaining
Set the page size for autocompletion display.
prompt = pinq.TextPrompt("Name: ")
prompt.with_page_size(5)Returns: Self for method chaining
Display the prompt and block until the user submits an answer.
name = prompt.prompt()Returns: The user's input text
Raises:
RuntimeError- If not a TTY, IO error, or operation canceled
Display the prompt, but allow the user to skip it by pressing ESC.
optional_input = prompt.prompt_skippable()
if optional_input is None:
print("User skipped this prompt")Returns: User's input or None if skipped
Raises:
RuntimeError- If not a TTY or IO error
import pinq
prompt = pinq.TextPrompt("What is your name?")
prompt.with_default("User")
prompt.with_help_message("Press ENTER for default")
name = prompt.prompt()
print(f"Hello, {name}!")Simple yes/no confirmation prompt.
prompt = pinq.ConfirmPrompt(message: str)Parameters:
message(str): The yes/no question shown to the user
Set the default answer: True for yes, False for no.
prompt = pinq.ConfirmPrompt("Continue?")
prompt.with_default(True) # Default to yesReturns: Self for method chaining
Set a help message.
prompt.with_help_message("This action cannot be undone")Returns: Self for method chaining
Display the prompt and wait for yes/no response.
if prompt.prompt():
print("User said yes")
else:
print("User said no")Returns: True for yes, False for no
Raises:
RuntimeError- If not a TTY, IO error, or operation canceled
Display the prompt, allowing ESC to skip.
answer = prompt.prompt_skippable()
if answer is None:
print("User skipped")
elif answer:
print("User said yes")
else:
print("User said no")Returns: True, False, or None if skipped
Raises:
RuntimeError- If not a TTY or IO error
import pinq
if pinq.ConfirmPrompt("Delete file?").with_default(False).prompt():
print("Deleting...")
else:
print("Canceled")Hidden password/secret input prompt.
prompt = pinq.PasswordPrompt(message: str)Parameters:
message(str): The prompt text (usually "Password: ")
Set a help message.
prompt.with_help_message("At least 8 characters")Returns: Self for method chaining
Display the prompt and wait for password input (characters not echoed).
password = prompt.prompt()Returns: The entered password
Raises:
RuntimeError- If not a TTY, IO error, or operation canceled
Display the prompt, allowing ESC to skip.
password = prompt.prompt_skippable()
if password is None:
print("Skipped")Returns: The password or None if skipped
Raises:
RuntimeError- If not a TTY or IO error
import pinq
prompt = pinq.PasswordPrompt("Enter password: ")
password = prompt.prompt()
print(f"Got password of length {len(password)}")Single-choice selection from a list of options.
prompt = pinq.SelectPrompt(message: str, options: List[str])Parameters:
message(str): The selection prompt textoptions(List[str]): Non-empty list of options to choose from
Raises:
RuntimeError- If options list is empty
Set the default selected option by its index.
options = ["Red", "Green", "Blue"]
prompt = pinq.SelectPrompt("Pick a color:", options)
prompt.with_default(1) # Default to "Green"Returns: Self for method chaining
Raises:
RuntimeError- If index is out of range
Set a help message.
prompt.with_help_message("Use arrow keys to navigate")Returns: Self for method chaining
Set how many options are visible at once.
prompt.with_page_size(10) # Show 10 options per pageReturns: Self for method chaining
Display the selection prompt and wait for user choice.
choice = prompt.prompt()Returns: The selected option text
Raises:
RuntimeError- If not a TTY, IO error, or operation canceled
Display the prompt, allowing ESC to skip.
choice = prompt.prompt_skippable()
if choice is None:
print("User skipped")Returns: Selected option or None if skipped
Raises:
RuntimeError- If not a TTY or IO error
import pinq
options = ["Python", "Rust", "Go", "C++"]
prompt = pinq.SelectPrompt("Choose a language:", options)
prompt.with_page_size(4)
language = prompt.prompt()
print(f"You chose: {language}")Multiple-choice selection from a list (select zero or more).
prompt = pinq.MultiSelectPrompt(message: str, options: List[str])Parameters:
message(str): The prompt textoptions(List[str]): Non-empty list of options
Raises:
RuntimeError- If options list is empty
Set which options are selected by default (by index).
prompt = pinq.MultiSelectPrompt("Select tags:", ["rust", "python", "js"])
prompt.with_defaults([0, 2]) # Default select "rust" and "js"Returns: Self for method chaining
Raises:
RuntimeError- If any index is out of range
Set a help message.
prompt.with_help_message("SPACE to select, arrows to navigate")Returns: Self for method chaining
Set how many options are visible at once.
prompt.with_page_size(5)Returns: Self for method chaining
Display the prompt and wait for user selections.
selections = prompt.prompt()Returns: List of selected option texts (may be empty)
Raises:
RuntimeError- If not a TTY, IO error, or operation canceled
Display the prompt, allowing ESC to skip.
selections = prompt.prompt_skippable()
if selections is None:
print("User skipped")Returns: List of selections or None if skipped
Raises:
RuntimeError- If not a TTY or IO error
import pinq
options = ["Apples", "Bananas", "Carrots", "Dates"]
prompt = pinq.MultiSelectPrompt("Select fruits:", options)
fruits = prompt.prompt()
print(f"You chose: {', '.join(fruits)}")Integer input with parsing and validation.
prompt = pinq.IntPrompt(message: str)Parameters:
message(str): The prompt text
Set a default integer value.
prompt = pinq.IntPrompt("Enter count: ")
prompt.with_default(5)Returns: Self for method chaining
Set a help message.
prompt.with_help_message("Must be between 1 and 100")Returns: Self for method chaining
Display and get an integer from the user.
count = prompt.prompt()Returns: The parsed integer
Raises:
RuntimeError- If not a TTY, IO error, operation canceled, or parse error
Display the prompt, allowing ESC to skip.
count = prompt.prompt_skippable()Returns: The integer or None if skipped
Raises:
RuntimeError- If not a TTY, IO error, or parse error
import pinq
prompt = pinq.IntPrompt("How many items?")
count = prompt.prompt()
print(f"Processing {count} items...")Floating-point number input with parsing.
prompt = pinq.FloatPrompt(message: str)Parameters:
message(str): The prompt text
Set a default float value.
prompt = pinq.FloatPrompt("Enter price: ")
prompt.with_default(9.99)Returns: Self for method chaining
Set a help message.
prompt.with_help_message("Use decimal point (e.g., 19.99)")Returns: Self for method chaining
Display and get a float from the user.
price = prompt.prompt()Returns: The parsed float
Raises:
RuntimeError- If not a TTY, IO error, operation canceled, or parse error
Display the prompt, allowing ESC to skip.
price = prompt.prompt_skippable()Returns: The float or None if skipped
Raises:
RuntimeError- If not a TTY, IO error, or parse error
import pinq
prompt = pinq.FloatPrompt("Enter amount: $")
amount = prompt.prompt()
print(f"Total: ${amount:.2f}")Interactive calendar date picker.
prompt = pinq.DateSelectPrompt(message: str)Parameters:
message(str): The prompt text
Note: Requires the date feature (enabled in standard pinq builds)
Set a help message.
prompt.with_help_message("Navigate with arrow keys")Returns: Self for method chaining
Display the interactive calendar and wait for date selection.
date_str = prompt.prompt()Returns: Selected date as string in YYYY-MM-DD format
Raises:
RuntimeError- If not a TTY, IO error, or operation canceled
Display the calendar, allowing ESC to skip.
date_str = prompt.prompt_skippable()
if date_str is None:
print("User skipped date selection")Returns: Date string or None if skipped
Raises:
RuntimeError- If not a TTY or IO error
import pinq
prompt = pinq.DateSelectPrompt("Select a meeting date: ")
date_str = prompt.prompt()
print(f"Meeting on: {date_str}")
# Parse the date for further use
from datetime import datetime
date = datetime.strptime(date_str, "%Y-%m-%d").date()Multi-line text input using an external text editor.
prompt = pinq.EditorPrompt(message: str)Parameters:
message(str): The prompt text
Note: Requires the editor feature (enabled in standard pinq builds)
Set a help message.
prompt.with_help_message("Press e to open editor, ENTER to submit")Returns: Self for method chaining
Display the prompt and open an editor for text input.
text = prompt.prompt()Returns: The text entered in the editor
Raises:
RuntimeError- If not a TTY, IO error, or operation canceled
Display the prompt, allowing ESC to skip.
text = prompt.prompt_skippable()
if text is None:
print("User canceled editor")Returns: Text or None if skipped
Raises:
RuntimeError- If not a TTY or IO error
import pinq
prompt = pinq.EditorPrompt("Write your message: ")
prompt.with_help_message("(opens in your default editor)")
message = prompt.prompt()
print(f"Message length: {len(message)} characters")- Functions Reference - One-liner convenience functions
- Builders Reference - Builder pattern examples
- Overview - Architecture and design