askr 0.1.0__tar.gz

askr-0.1.0/.idea/.gitignore

@@ -0,0 +1,5 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/

askr-0.1.0/.idea/askr.iml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module external.system.id="pyproject.toml" type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/src" />
+      <excludeFolder url="file://$MODULE_DIR$/.venv" />
+    </content>
+    <orderEntry type="jdk" jdkName="~/PycharmProjects/askr/.venv" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PackageRequirementsSettings" />
+  <component name="PyDocumentationSettings" />
+  <component name="ReSTService" />
+  <component name="TestRunnerService" />
+</module>

askr-0.1.0/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

askr-0.1.0/.idea/misc.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectRootManager" version="2" project-jdk-name="~/PycharmProjects/askr/.venv" project-jdk-type="Python SDK" />
+</project>

askr-0.1.0/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/askr.iml" filepath="$PROJECT_DIR$/.idea/askr.iml" />
+    </modules>
+  </component>
+</project>

askr-0.1.0/.idea/workspace.xml

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="AutoImportSettings">
+    <option name="autoReloadType" value="SELECTIVE" />
+  </component>
+  <component name="ChangeListManager">
+    <list default="true" id="183b80c6-482c-4cb9-a416-903c9521f399" name="Changes" comment="" />
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="FileTemplateManagerImpl">
+    <option name="RECENT_TEMPLATES">
+      <list>
+        <option value="Python Script" />
+      </list>
+    </option>
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 3,
+  "fromUser": false
+}]]></component>
+  <component name="ProjectId" id="3JuvSseSHqQZ7r2Z9XoKBriCkN0" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "Python tests.Python tests in test_core.py.executor": "Run",
+    "Python.core.executor": "Run",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "RunOnceActivity.typescript.service.memoryLimit.init": "true",
+    "codeWithMe.voiceChat.enabledByDefault": "false",
+    "last_opened_file_path": "/Users/lev/PycharmProjects/askr",
+    "nodejs_package_manager_path": "npm",
+    "python.packages.toolwindow.project.migrated.to.right.top.v2": "true"
+  }
+}]]></component>
+  <component name="RecentsManager">
+    <key name="CopyFile.RECENT_KEYS">
+      <recent name="$PROJECT_DIR$" />
+      <recent name="$PROJECT_DIR$/src/askr" />
+    </key>
+  </component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-python-sdk-73a66231627c-5bd6d13a2a75-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-262.10968.92" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="183b80c6-482c-4cb9-a416-903c9521f399" name="Changes" comment="" />
+      <created>1790523771170</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1790523771170</updated>
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

askr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prevolut Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

askr-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+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

askr-0.1.0/README.md

@@ -0,0 +1,82 @@
+# 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

askr-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "askr"
+version = "0.1.0"
+description = "Simple, validated input prompts for the terminal"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Prevolut Ltd" }]
+keywords = ["input", "prompt", "cli", "terminal", "validation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]

askr-0.1.0/src/askr/__init__.py

@@ -0,0 +1,24 @@
+"""Simple, validated input prompts for the terminal."""
+
+from .core import (
+    ask_choice,
+    ask_date,
+    ask_float,
+    ask_int,
+    ask_password,
+    ask_path,
+    ask_str,
+    ask_yn,
+)
+
+__all__ = [
+    "ask_choice",
+    "ask_date",
+    "ask_float",
+    "ask_int",
+    "ask_password",
+    "ask_path",
+    "ask_str",
+    "ask_yn",
+]
+__version__ = "0.1.0"

askr-0.1.0/src/askr/core.py

@@ -0,0 +1,361 @@
+"""Simple, validated input prompts for the terminal."""
+
+import math
+import os
+import re
+from collections.abc import Callable, Sequence
+from datetime import date, datetime
+from getpass import getpass
+from pathlib import Path
+from typing import Any, Literal, TypeVar
+
+# Reference date used to show the user an example for each accepted format.
+# Day 27 cannot be a month, so day and month are never confused in the example.
+_EXAMPLE_DATE = date(2026, 9, 27)
+
+_Number = TypeVar("_Number", int, float)
+
+
+def ask_yn(prompt: str, default: bool = True) -> bool:
+    """Ask a yes/no question until a valid answer is given.
+
+    Accepts "y", "yes", "n" and "no" (case-insensitive).
+    Pressing Enter without input returns the default.
+
+    Args:
+        prompt: The question shown to the user.
+        default: The value returned when the user just presses Enter.
+
+    Returns:
+        True for yes, False for no.
+    """
+    hint = "Y/n: " if default else "y/N: "
+    while True:
+        answer = input(f"{prompt} {hint}").strip().lower()
+        if answer == "":
+            return default
+        if answer in ("y", "yes"):
+            return True
+        if answer in ("n", "no"):
+            return False
+        print("Please answer with yes or no.")
+
+
+def ask_int(prompt: str, min_value: int | None = None, max_value: int | None = None) -> int:
+    """Ask for a whole number until a valid one is entered.
+
+    Optionally restricts the input to a range. Both bounds are inclusive.
+
+    Args:
+        prompt: The text shown to the user.
+        min_value: The smallest accepted number, or None for no lower bound.
+        max_value: The largest accepted number, or None for no upper bound.
+
+    Returns:
+        The number entered by the user.
+
+    Raises:
+        ValueError: If min_value is greater than max_value.
+    """
+    return _ask_number(prompt, int, "a whole number", min_value, max_value)
+
+
+def ask_float(prompt: str, min_value: float | None = None, max_value: float | None = None) -> float:
+    """Ask for a number (decimals allowed) until a valid one is entered.
+
+    Optionally restricts the input to a range. Both bounds are inclusive.
+
+    Args:
+        prompt: The text shown to the user.
+        min_value: The smallest accepted number, or None for no lower bound.
+        max_value: The largest accepted number, or None for no upper bound.
+
+    Returns:
+        The number entered by the user.
+
+    Raises:
+        ValueError: If min_value is greater than max_value.
+    """
+    # "nan" and "inf" are valid for float() but never a sensible answer.
+    return _ask_number(prompt, float, "a number", min_value, max_value)
+
+
+def ask_str(prompt: str, min_length: int | None = None, max_length: int | None = None,
+            strip: bool = True) -> str:
+    """Ask for text until it meets the optional length requirements.
+
+    Args:
+        prompt: The text shown to the user.
+        min_length: The minimum number of characters, or None for no limit.
+            Use 1 to disallow empty input.
+        max_length: The maximum number of characters, or None for no limit.
+        strip: Remove leading and trailing whitespace before checking.
+
+    Returns:
+        The text entered by the user.
+
+    Raises:
+        ValueError: If min_length is greater than max_length.
+    """
+    _validate_bounds(min_length, max_length, "min_length", "max_length")
+
+    while True:
+        user_input = input(prompt)
+        if strip:
+            user_input = user_input.strip()
+        if not user_input and min_length:
+            print("Input cannot be empty.")
+            continue
+        if not _check_range(len(user_input), min_length, max_length):
+            print(f"Input must be {_range_hint(min_length, max_length)} characters long.")
+            continue
+        return user_input
+
+
+def ask_choice(prompt: str, options: Sequence[str], default: str | None = None) -> str:
+    """Show a numbered list and ask the user to pick one option.
+
+    The user can answer with the option's number or its name (case-insensitive).
+
+    Args:
+        prompt: The question shown above the list.
+        options: The options to choose from.
+        default: An option returned when the user just presses Enter, or None.
+
+    Returns:
+        The chosen option, exactly as given in options.
+
+    Raises:
+        TypeError: If options is a single string instead of a list.
+        ValueError: If options is empty or default is not one of the options.
+    """
+    # A plain string is a Sequence[str] too, but would list single characters.
+    if isinstance(options, str):
+        raise TypeError("options must be a list of strings, not a single string")
+    if not options:
+        raise ValueError("options must not be empty")
+    if default is not None and default not in options:
+        raise ValueError("default must be one of the options")
+
+    print(prompt)
+    for number, option in enumerate(options, start=1):
+        marker = " (default)" if option == default else ""
+        print(f"  {number}. {option}{marker}")
+
+    lookup = {option.lower(): option for option in options}
+    while True:
+        answer = input("Your choice: ").strip()
+        if answer == "" and default is not None:
+            return default
+        # Names are checked first, so an option called "2" is not mistaken for a number.
+        if answer.lower() in lookup:
+            return lookup[answer.lower()]
+        index = _parse_int(answer)
+        if index is not None and 1 <= index <= len(options):
+            return options[index - 1]
+        print(f"Please enter a number from 1 to {len(options)} or the name of an option.")
+
+
+def ask_password(prompt: str = "Password: ", confirm: bool = False,
+                 min_length: int | None = None,
+                 require_upper: bool = False, require_lower: bool = False,
+                 require_digit: bool = False, require_special: bool = False,
+                 pattern: str | None = None, pattern_hint: str | None = None) -> str:
+    """Ask for a password without showing it on screen.
+
+    All rules the password breaks are reported at once, so the user
+    can fix everything in one go.
+
+    Args:
+        prompt: The text shown to the user.
+        confirm: Ask a second time and require both entries to match.
+        min_length: The minimum number of characters, or None for no limit.
+        require_upper: Require at least one uppercase letter.
+        require_lower: Require at least one lowercase letter.
+        require_digit: Require at least one digit.
+        require_special: Require at least one character that is neither
+            a letter, a digit nor whitespace (e.g. ! ? # _).
+        pattern: A custom regular expression the whole password must match.
+        pattern_hint: The message shown if pattern does not match.
+
+    Returns:
+        The password entered by the user.
+
+    Raises:
+        ValueError: If pattern is not a valid regular expression.
+    """
+    rules: list[tuple[Callable[[str], bool], str]] = []
+    if min_length is not None:
+        rules.append((lambda p: len(p) >= min_length, f"be at least {min_length} characters long"))
+    if require_upper:
+        rules.append((lambda p: any(c.isupper() for c in p), "contain an uppercase letter"))
+    if require_lower:
+        rules.append((lambda p: any(c.islower() for c in p), "contain a lowercase letter"))
+    if require_digit:
+        rules.append((lambda p: any(c.isdigit() for c in p), "contain a digit"))
+    if require_special:
+        rules.append((lambda p: any(not c.isalnum() and not c.isspace() for c in p),
+                      "contain a special character"))
+    if pattern is not None:
+        try:
+            compiled = re.compile(pattern)
+        except re.error as error:
+            raise ValueError(f"pattern is not a valid regular expression: {error}") from None
+        rules.append((lambda p: compiled.fullmatch(p) is not None,
+                      pattern_hint or "match the required format"))
+
+    while True:
+        password = getpass(prompt)
+        broken = [message for check, message in rules if not check(password)]
+        if broken:
+            print("The password must:")
+            for message in broken:
+                print(f"  - {message}")
+            continue
+        if confirm and getpass("Repeat password: ") != password:
+            print("The passwords do not match. Please try again.")
+            continue
+        return password
+
+
+def ask_path(prompt: str, must_exist: bool = True,
+             kind: Literal["any", "file", "dir"] = "any") -> Path:
+    """Ask for a file system path until a valid one is entered.
+
+    Surrounding quotes and a leading "~" are handled, so paths pasted or
+    dragged in from a file manager work as expected.
+
+    Args:
+        prompt: The text shown to the user.
+        must_exist: Require the path to exist.
+        kind: "file" to accept only files, "dir" to accept only folders,
+            "any" to accept both. Only checked if the path exists.
+
+    Returns:
+        The entered path, with "~" expanded.
+
+    Raises:
+        ValueError: If kind is not "any", "file" or "dir".
+    """
+    if kind not in ("any", "file", "dir"):
+        raise ValueError('kind must be "any", "file" or "dir"')
+
+    while True:
+        raw = input(prompt).strip().strip("'\"")
+        if not raw:
+            print("Please enter a path.")
+            continue
+        # Terminals on macOS and Linux escape spaces as "\ " on drag and drop.
+        # On Windows a backslash is the path separator and must stay untouched.
+        if os.name != "nt":
+            raw = raw.replace("\\ ", " ")
+        path = Path(raw).expanduser()
+        if must_exist and not path.exists():
+            print("This path does not exist. Please try again.")
+            continue
+        if path.exists() and kind == "file" and not path.is_file():
+            print("This is not a file. Please enter the path of a file.")
+            continue
+        if path.exists() and kind == "dir" and not path.is_dir():
+            print("This is not a folder. Please enter the path of a folder.")
+            continue
+        return path
+
+
+def ask_date(prompt: str, formats: str | Sequence[str] = "%Y-%m-%d",
+             min_date: date | None = None, max_date: date | None = None) -> date:
+    """Ask for a date until a valid one in one of the accepted formats is entered.
+
+    Args:
+        prompt: The text shown to the user.
+        formats: One strftime format or several, tried in order,
+            e.g. ("%Y-%m-%d", "%d.%m.%Y", "%d/%m/%Y").
+        min_date: The earliest accepted date, or None for no limit.
+        max_date: The latest accepted date, or None for no limit.
+
+    Returns:
+        The entered date.
+
+    Raises:
+        ValueError: If formats is empty or min_date is later than max_date.
+    """
+    if isinstance(formats, str):
+        formats = (formats,)
+    if not formats:
+        raise ValueError("formats must not be empty")
+    _validate_bounds(min_date, max_date, "min_date", "max_date")
+
+    examples = " or ".join(_EXAMPLE_DATE.strftime(fmt) for fmt in formats)
+    while True:
+        value = _parse_date(input(prompt).strip(), formats)
+        if value is None:
+            print(f"Invalid date. Please use a format like {examples}.")
+            continue
+        if not _check_range(value, min_date, max_date):
+            hint = _range_hint(min_date, max_date, at_least="on or after", at_most="on or before")
+            print(f"The date must be {hint}.")
+            continue
+        return value
+
+
+def _ask_number(prompt: str, converter: Callable[[str], _Number], type_name: str,
+                min_value: float | None = None, max_value: float | None = None) -> _Number:
+    """Ask for a number using the given converter until a valid one is entered."""
+    _validate_bounds(min_value, max_value, "min_value", "max_value")
+
+    while True:
+        try:
+            value = converter(input(prompt))
+        except ValueError:
+            print(f"Invalid entry. Please enter {type_name}.")
+            continue
+        if not math.isfinite(value):
+            print(f"Invalid entry. Please enter {type_name}.")
+            continue
+        if not _check_range(value, min_value, max_value):
+            print(f"The number must be {_range_hint(min_value, max_value)}.")
+            continue
+        return value
+
+
+def _parse_int(text: str) -> int | None:
+    """Return text as an int, or None if it is not a whole number."""
+    try:
+        return int(text)
+    except ValueError:
+        return None
+
+
+def _parse_date(text: str, formats: Sequence[str]) -> date | None:
+    """Return the date for the first matching format, or None if none match."""
+    for fmt in formats:
+        try:
+            return datetime.strptime(text, fmt).date()
+        except ValueError:
+            continue
+    return None
+
+
+def _validate_bounds(min_value: Any, max_value: Any, min_name: str, max_name: str) -> None:
+    """Raise ValueError if the lower bound is greater than the upper bound."""
+    if min_value is not None and max_value is not None and min_value > max_value:
+        raise ValueError(f"{min_name} must not be greater than {max_name}")
+
+
+def _check_range(value: Any, min_value: Any, max_value: Any) -> bool:
+    """Return True if value lies within the optional bounds."""
+    return (min_value is None or value >= min_value) and (max_value is None or value <= max_value)
+
+
+def _range_hint(min_value: Any, max_value: Any,
+                at_least: str = "at least", at_most: str = "at most") -> str:
+    """Describe a range in words, e.g. 'at least 3' or 'between 1 and 10'.
+
+    at_least and at_most replace the wording for one-sided ranges,
+    e.g. "on or after" and "on or before" for dates.
+    """
+    if min_value is None:
+        return f"{at_most} {max_value}"
+    if max_value is None:
+        return f"{at_least} {min_value}"
+    return f"between {min_value} and {max_value}"

askr-0.1.0/tests/test_core.py

@@ -0,0 +1,221 @@
+"""Tests for askr. Run with: pytest"""
+
+from collections.abc import Iterable
+from datetime import date
+
+import pytest
+
+import askr
+from askr import core
+
+
+def feed(monkeypatch: pytest.MonkeyPatch, answers: Iterable[str]) -> None:
+    """Replace input() and getpass() with a fixed list of answers."""
+    it = iter(answers)
+    monkeypatch.setattr("builtins.input", lambda prompt="": next(it))
+    monkeypatch.setattr(core, "getpass", lambda prompt="": next(it))
+
+
+# ask_yn
+
+@pytest.mark.parametrize(("answers", "default", "expected"), [
+    (["y"], True, True),
+    (["YES"], False, True),
+    (["n"], True, False),
+    ([" No "], True, False),
+    ([""], True, True),
+    ([""], False, False),
+    (["maybe", "y"], True, True),
+])
+def test_ask_yn(monkeypatch, answers, default, expected):
+    feed(monkeypatch, answers)
+    assert askr.ask_yn("?", default=default) is expected
+
+
+# ask_int / ask_float
+
+def test_ask_int_retries_until_valid(monkeypatch, capsys):
+    feed(monkeypatch, ["abc", "", "1.5", "0", "11", "7"])
+    assert askr.ask_int("n: ", min_value=1, max_value=10) == 7
+    out = capsys.readouterr().out
+    assert "whole number" in out
+    assert "between 1 and 10" in out
+
+
+def test_ask_int_one_sided_bounds(monkeypatch, capsys):
+    feed(monkeypatch, ["-1", "5"])
+    assert askr.ask_int("n: ", min_value=0) == 5
+    assert "at least 0" in capsys.readouterr().out
+
+
+def test_ask_int_returns_int(monkeypatch):
+    feed(monkeypatch, [" 42 "])
+    value = askr.ask_int("n: ")
+    assert value == 42
+    assert isinstance(value, int)
+
+
+def test_ask_float_rejects_nan_and_inf(monkeypatch):
+    feed(monkeypatch, ["nan", "inf", "-inf", "2.5"])
+    assert askr.ask_float("x: ") == 2.5
+
+
+def test_number_bounds_are_checked(monkeypatch):
+    with pytest.raises(ValueError, match="min_value"):
+        askr.ask_int("n: ", min_value=10, max_value=1)
+
+
+# ask_str
+
+def test_ask_str_length(monkeypatch, capsys):
+    feed(monkeypatch, ["   ", "toolong", "ok"])
+    assert askr.ask_str("s: ", min_length=1, max_length=4) == "ok"
+    out = capsys.readouterr().out
+    assert "cannot be empty" in out
+    assert "between 1 and 4" in out
+
+
+def test_ask_str_without_strip(monkeypatch):
+    feed(monkeypatch, ["  hi  "])
+    assert askr.ask_str("s: ", strip=False) == "  hi  "
+
+
+def test_ask_str_allows_empty_by_default(monkeypatch):
+    feed(monkeypatch, [""])
+    assert askr.ask_str("s: ") == ""
+
+
+# ask_choice
+
+OPTIONS = ["Easy", "Medium", "Hard"]
+
+
+@pytest.mark.parametrize(("answers", "expected"), [
+    (["1"], "Easy"),
+    (["hard"], "Hard"),
+    (["0", "4", "x", "²", "2"], "Medium"),
+])
+def test_ask_choice(monkeypatch, answers, expected):
+    feed(monkeypatch, answers)
+    assert askr.ask_choice("?", OPTIONS) == expected
+
+
+def test_ask_choice_default(monkeypatch):
+    feed(monkeypatch, [""])
+    assert askr.ask_choice("?", OPTIONS, default="Medium") == "Medium"
+
+
+def test_ask_choice_prefers_names_over_numbers(monkeypatch):
+    feed(monkeypatch, ["2"])
+    assert askr.ask_choice("?", ["2", "1"]) == "2"
+
+
+def test_ask_choice_invalid_arguments():
+    with pytest.raises(ValueError):
+        askr.ask_choice("?", [])
+    with pytest.raises(ValueError):
+        askr.ask_choice("?", OPTIONS, default="Nightmare")
+    with pytest.raises(TypeError):
+        askr.ask_choice("?", "abc")
+
+
+# ask_password
+
+def test_ask_password_reports_all_broken_rules(monkeypatch, capsys):
+    feed(monkeypatch, ["abc", "Abcdefg1!", "Abcdefg1!"])
+    result = askr.ask_password(confirm=True, min_length=8, require_upper=True,
+                               require_lower=True, require_digit=True,
+                               require_special=True)
+    assert result == "Abcdefg1!"
+    out = capsys.readouterr().out
+    for rule in ("8 characters", "uppercase", "digit", "special"):
+        assert rule in out
+    assert "lowercase" not in out
+
+
+def test_ask_password_confirmation_mismatch(monkeypatch, capsys):
+    feed(monkeypatch, ["secret", "typo", "secret", "secret"])
+    assert askr.ask_password(confirm=True) == "secret"
+    assert "do not match" in capsys.readouterr().out
+
+
+def test_ask_password_umlaut_counts_as_letter(monkeypatch):
+    feed(monkeypatch, ["Äbc"])
+    assert askr.ask_password(require_upper=True) == "Äbc"
+
+
+def test_ask_password_pattern(monkeypatch, capsys):
+    feed(monkeypatch, ["12345", "abcd", "1234"])
+    assert askr.ask_password(pattern=r"\d{4}", pattern_hint="be 4 digits") == "1234"
+    assert "be 4 digits" in capsys.readouterr().out
+
+
+def test_ask_password_invalid_pattern():
+    with pytest.raises(ValueError, match="regular expression"):
+        askr.ask_password(pattern="[")
+
+
+# ask_path
+
+def test_ask_path_kinds(monkeypatch, tmp_path):
+    file = tmp_path / "my file.txt"
+    file.write_text("x")
+    folder = tmp_path / "sub"
+    folder.mkdir()
+
+    feed(monkeypatch, ["", str(tmp_path / "missing"), str(folder), f"'{file}'"])
+    assert askr.ask_path("f: ", kind="file") == file
+
+    feed(monkeypatch, [str(file), str(folder)])
+    assert askr.ask_path("d: ", kind="dir") == folder
+
+
+def test_ask_path_new_file(monkeypatch, tmp_path):
+    target = tmp_path / "new.txt"
+    feed(monkeypatch, [str(target)])
+    assert askr.ask_path("f: ", must_exist=False, kind="file") == target
+
+
+def test_ask_path_expands_home(monkeypatch):
+    feed(monkeypatch, ["~"])
+    assert askr.ask_path("p: ").is_absolute()
+
+
+def test_ask_path_invalid_kind():
+    with pytest.raises(ValueError):
+        askr.ask_path("p: ", kind="folder")  # type: ignore[arg-type]
+
+
+# ask_date
+
+def test_ask_date_formats(monkeypatch, capsys):
+    feed(monkeypatch, ["27/09/2026", "2026-02-30", "27.09.2026"])
+    assert askr.ask_date("d: ", ("%Y-%m-%d", "%d.%m.%Y")) == date(2026, 9, 27)
+    assert "2026-09-27 or 27.09.2026" in capsys.readouterr().out
+
+
+@pytest.mark.parametrize(("kwargs", "message"), [
+    ({"min_date": date(2025, 1, 1)}, "on or after 2025-01-01"),
+    ({"max_date": date(2020, 1, 1)}, "on or before 2020-01-01"),
+    ({"min_date": date(2025, 1, 1), "max_date": date(2025, 12, 31)},
+     "between 2025-01-01 and 2025-12-31"),
+])
+def test_ask_date_range_messages(monkeypatch, capsys, kwargs, message):
+    feed(monkeypatch, ["2024-06-15", "2019-06-15", "2025-06-15"])
+    askr.ask_date("d: ", **kwargs)
+    assert message in capsys.readouterr().out
+
+
+def test_ask_date_invalid_arguments():
+    with pytest.raises(ValueError):
+        askr.ask_date("d: ", formats=())
+    with pytest.raises(ValueError, match="min_date"):
+        askr.ask_date("d: ", min_date=date(2026, 1, 2), max_date=date(2026, 1, 1))
+
+
+# package
+
+def test_public_api():
+    assert sorted(askr.__all__) == sorted(
+        name for name in dir(askr) if name.startswith("ask_")
+    )