valid8r.prompt.basic

Basic input prompting functions with validation support.

This module provides functionality for prompting users for input via the command line with built-in parsing, validation, and retry logic.

Attributes

T

Classes

PromptConfig

Configuration for the ask function.

Functions

ask(prompt_text, *[, parser, validator, ...])

Prompt the user for input with parsing and validation.

Module Contents

valid8r.prompt.basic.T[source]
class valid8r.prompt.basic.PromptConfig[source]

Bases: Generic[T]

Configuration for the ask function.

parser: collections.abc.Callable[[str], valid8r.core.maybe.Maybe[T]] | None = None[source]
validator: collections.abc.Callable[[T], valid8r.core.maybe.Maybe[T]] | None = None[source]
error_message: str | None = None[source]
default: T | None = None[source]
retry: bool | int = False[source]
io_provider: valid8r.prompt.io_provider.IOProvider | None = None[source]
valid8r.prompt.basic.ask(prompt_text, *, parser=None, validator=None, error_message=None, default=None, retry=False, io_provider=None, _test_mode=False)[source]

Prompt the user for input with parsing and validation.

Displays a prompt to the user, parses their input using the provided parser, validates the result, and optionally retries on failure. Returns a Maybe monad containing either the validated input or an error message.

Parameters:

  • prompt_text (str) – The prompt message to display to the user

  • parser (collections.abc.Callable[[str], valid8r.core.maybe.Maybe[T]] | None) – Function to convert string input to desired type (default: returns string as-is)

  • validator (collections.abc.Callable[[T], valid8r.core.maybe.Maybe[T]] | None) – Function to validate the parsed value (default: accepts any value)

  • error_message (str | None) – Custom error message to display on validation failure

  • default (T | None) – Default value to use if user provides empty input (displays in prompt)

  • retry (bool | int) – Enable retry on failure - True for unlimited, integer for max attempts, False to disable

  • io_provider (valid8r.prompt.io_provider.IOProvider | None) – IO provider for handling input/output (default: BuiltinIOProvider)

  • _test_mode (bool) – Internal testing parameter (do not use)

Returns:

Success with validated input, or Failure with error message

Return type:

Maybe[T]

Examples

Basic integer input with validation:

from valid8r.core import parsers, validators
from valid8r.prompt import ask

result = ask(
    "Enter your age: ",
    parser=parsers.parse_int,
    validator=validators.between(0, 120),
    retry=True
)
# User enters "25" -> Success(25)
# User enters "invalid" -> prompts again with error message

Input with default value:

result = ask(
    "Enter port: ",
    parser=parsers.parse_int,
    default=8080
)
# User presses Enter -> Success(8080)
# User enters "3000" -> Success(3000)

Limited retries with custom error:

result = ask(
    "Email: ",
    parser=parsers.parse_email,
    error_message="Invalid email format",
    retry=3
)
# User has 3 attempts to enter valid email

Boolean input with retry:

result = ask(
    "Continue? (yes/no): ",
    parser=parsers.parse_bool,
    retry=True
)
# User enters "yes" -> Success(True)
# User enters "maybe" -> error, retry prompt

Note

The returned Maybe must be unwrapped to access the value. Use pattern matching or .value_or() to extract the result.