Metadata-Version: 2.5
Name: askr
Version: 0.1.0
Summary: Simple, validated input prompts for the terminal
Author: Prevolut Ltd
License-Expression: MIT
License-File: LICENSE
Keywords: cli,input,prompt,terminal,validation
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# askr

Simple, validated input prompts for the terminal.

Every function keeps asking until the answer is valid, so you never have to write
another `while True` / `try` / `except ValueError` loop around `input()` again.

## Installation

```bash
pip install askr
```

Requires Python 3.10 or newer. No dependencies.

## Usage

```python
from datetime import date
from askr import ask_choice, ask_date, ask_float, ask_int, ask_password, ask_path, ask_str, ask_yn

age = ask_int("Your age: ", min_value=0, max_value=120)
price = ask_float("Price: ", min_value=0)
name = ask_str("Your name: ", min_length=1, max_length=40)

if ask_yn("Continue?"):             # Enter = yes
    ...
if ask_yn("Delete everything?", default=False):   # Enter = no
    ...

mode = ask_choice("Difficulty?", ["Easy", "Medium", "Hard"], default="Medium")

password = ask_password(confirm=True, min_length=8, require_upper=True,
                        require_digit=True, require_special=True)
pin = ask_password("PIN: ", pattern=r"\d{4}", pattern_hint="be exactly 4 digits")

file = ask_path("File to open: ", kind="file")
birthday = ask_date("Birthday: ", ("%Y-%m-%d", "%d.%m.%Y"), max_date=date.today())
```

What the user sees:

```
Your age: abc
Invalid entry. Please enter a whole number.
Your age: 200
The number must be between 0 and 120.

Difficulty?
  1. Easy
  2. Medium (default)
  3. Hard
Your choice: hard

Password:
The password must:
  - contain an uppercase letter
  - contain a special character
```

## Functions

| Function | Returns | Validates |
|---|---|---|
| `ask_int` | `int` | whole number, optional `min_value` / `max_value` |
| `ask_float` | `float` | finite number, optional `min_value` / `max_value` |
| `ask_str` | `str` | optional `min_length` / `max_length`, strips whitespace by default |
| `ask_yn` | `bool` | y / yes / n / no, Enter returns `default` |
| `ask_choice` | `str` | option number or name (case-insensitive), optional `default` |
| `ask_password` | `str` | hidden input, optional confirmation, length, character classes, regex |
| `ask_path` | `Path` | must exist (optional), file or folder only (optional) |
| `ask_date` | `date` | one or more formats, optional `min_date` / `max_date` |

Invalid arguments from the programmer (for example `min_value` greater than `max_value`)
raise a `ValueError` immediately instead of asking the user forever.

`Ctrl+C` and `Ctrl+D` are not caught, so your program can handle them the way it wants
(`KeyboardInterrupt` and `EOFError`).

## License

MIT
