valid8r 0.6.2__py3-none-any.whl → 0.7.0__py3-none-any.whl

valid8r/core/maybe.py

@@ -108,6 +108,10 @@ class Success(Maybe[T]):
         """Get a string representation."""
         return f'Success({self.value})'
 
+    def __repr__(self) -> str:
+        """Get a repr representation for debugging and doctests."""
+        return f'Success({self.value!r})'
+
 
 class Failure(Maybe[T]):
     """Represents a failed computation with an error message."""
@@ -160,3 +164,7 @@ class Failure(Maybe[T]):
     def __str__(self) -> str:
         """Get a string representation."""
         return f'Failure({self.error})'
+
+    def __repr__(self) -> str:
+        """Get a repr representation for debugging and doctests."""
+        return f'Failure({self.error!r})'

valid8r/core/parsers.py

@@ -80,7 +80,30 @@ _PHONE_DIGIT_EXTRACTION_PATTERN = re.compile(r'\D')
 
 
 def parse_int(input_value: str, error_message: str | None = None) -> Maybe[int]:
-    """Parse a string to an integer."""
+    """Parse a string to an integer.
+
+    Converts string representations of integers to Python int values.
+    Handles whitespace trimming and accepts whole numbers in float notation (e.g., "42.0").
+
+    Args:
+        input_value: String to parse (leading/trailing whitespace is stripped)
+        error_message: Optional custom error message for parsing failures
+
+    Returns:
+        Maybe[int]: Success(int) if parsing succeeds, Failure(str) with error message otherwise
+
+    Examples:
+        >>> parse_int("42")
+        Success(42)
+        >>> parse_int("  -17  ")
+        Success(-17)
+        >>> parse_int("42.0")
+        Success(42)
+        >>> parse_int("42.5").is_failure()
+        True
+        >>> parse_int("not a number").is_failure()
+        True
+    """
     if not input_value:
         return Maybe.failure('Input must not be empty')
 
@@ -102,7 +125,28 @@ def parse_int(input_value: str, error_message: str | None = None) -> Maybe[int]:
 
 
 def parse_float(input_value: str, error_message: str | None = None) -> Maybe[float]:
-    """Parse a string to a float."""
+    """Parse a string to a floating-point number.
+
+    Converts string representations of numbers to Python float values.
+    Handles whitespace trimming and scientific notation.
+
+    Args:
+        input_value: String to parse (leading/trailing whitespace is stripped)
+        error_message: Optional custom error message for parsing failures
+
+    Returns:
+        Maybe[float]: Success(float) if parsing succeeds, Failure(str) with error message otherwise
+
+    Examples:
+        >>> parse_float("3.14")
+        Success(3.14)
+        >>> parse_float("  -2.5  ")
+        Success(-2.5)
+        >>> parse_float("1e-3")
+        Success(0.001)
+        >>> parse_float("not a number").is_failure()
+        True
+    """
     if not input_value:
         return Maybe.failure('Input must not be empty')
 
@@ -114,7 +158,33 @@ def parse_float(input_value: str, error_message: str | None = None) -> Maybe[flo
 
 
 def parse_bool(input_value: str, error_message: str | None = None) -> Maybe[bool]:
-    """Parse a string to a boolean."""
+    """Parse a string to a boolean value.
+
+    Accepts various common representations of true/false values.
+    Case-insensitive and handles whitespace.
+
+    Recognized true values: 'true', 't', 'yes', 'y', '1'
+    Recognized false values: 'false', 'f', 'no', 'n', '0'
+
+    Args:
+        input_value: String to parse (leading/trailing whitespace is stripped, case-insensitive)
+        error_message: Optional custom error message for parsing failures
+
+    Returns:
+        Maybe[bool]: Success(bool) if parsing succeeds, Failure(str) with error message otherwise
+
+    Examples:
+        >>> parse_bool("true")
+        Success(True)
+        >>> parse_bool("YES")
+        Success(True)
+        >>> parse_bool("n")
+        Success(False)
+        >>> parse_bool("  0  ")
+        Success(False)
+        >>> parse_bool("maybe").is_failure()
+        True
+    """
     if not input_value:
         return Maybe.failure('Input must not be empty')
 
@@ -133,7 +203,27 @@ def parse_bool(input_value: str, error_message: str | None = None) -> Maybe[bool
 
 
 def parse_date(input_value: str, date_format: str | None = None, error_message: str | None = None) -> Maybe[date]:
-    """Parse a string to a date."""
+    """Parse a string to a date object.
+
+    Parses date strings using ISO 8601 format (YYYY-MM-DD) by default,
+    or a custom format if specified.
+
+    Args:
+        input_value: String to parse (leading/trailing whitespace is stripped)
+        date_format: Optional strftime format string (e.g., '%Y-%m-%d', '%m/%d/%Y')
+        error_message: Optional custom error message for parsing failures
+
+    Returns:
+        Maybe[date]: Success(date) if parsing succeeds, Failure(str) with error message otherwise
+
+    Examples:
+        >>> parse_date("2025-01-15")
+        Success(datetime.date(2025, 1, 15))
+        >>> parse_date("01/15/2025", date_format="%m/%d/%Y")
+        Success(datetime.date(2025, 1, 15))
+        >>> parse_date("invalid").is_failure()
+        True
+    """
     if not input_value:
         return Maybe.failure('Input must not be empty')
 
@@ -157,7 +247,30 @@ def parse_date(input_value: str, date_format: str | None = None, error_message:
 
 
 def parse_complex(input_value: str, error_message: str | None = None) -> Maybe[complex]:
-    """Parse a string to a complex number."""
+    """Parse a string to a complex number.
+
+    Accepts various complex number representations including both 'j' and 'i' notation.
+    Handles parentheses and spaces in the input.
+
+    Args:
+        input_value: String to parse (whitespace is stripped, both 'i' and 'j' accepted)
+        error_message: Optional custom error message for parsing failures
+
+    Returns:
+        Maybe[complex]: Success(complex) if parsing succeeds, Failure(str) with error message otherwise
+
+    Examples:
+        >>> parse_complex("3+4j")
+        Success((3+4j))
+        >>> parse_complex("3 + 4i")
+        Success((3+4j))
+        >>> parse_complex("(2-3j)")
+        Success((2-3j))
+        >>> parse_complex("5j")
+        Success(5j)
+        >>> parse_complex("invalid").is_failure()
+        True
+    """
     if not input_value:
         return Maybe.failure('Input must not be empty')
 
@@ -187,7 +300,10 @@ def parse_complex(input_value: str, error_message: str | None = None) -> Maybe[c
 
 
 def parse_decimal(input_value: str, error_message: str | None = None) -> Maybe[Decimal]:
-    """Parse a string to a Decimal.
+    """Parse a string to a Decimal for precise decimal arithmetic.
+
+    Uses Python's Decimal type for arbitrary-precision decimal arithmetic,
+    avoiding floating-point rounding errors. Ideal for financial calculations.
 
     Args:
         input_value: String representation of a decimal number
@@ -196,6 +312,15 @@ def parse_decimal(input_value: str, error_message: str | None = None) -> Maybe[D
     Returns:
         Maybe[Decimal]: Success with Decimal value or Failure with an error message
 
+    Examples:
+        >>> parse_decimal("3.14159")
+        Success(Decimal('3.14159'))
+        >>> parse_decimal("  0.1  ")
+        Success(Decimal('0.1'))
+        >>> parse_decimal("-99.99")
+        Success(Decimal('-99.99'))
+        >>> parse_decimal("not a number").is_failure()
+        True
     """
     if not input_value:
         return Maybe.failure('Input must not be empty')
@@ -229,7 +354,34 @@ def _find_enum_by_name(enum_class: type[E], value: str) -> E | None:
 
 
 def parse_enum(input_value: str, enum_class: type[E], error_message: str | None = None) -> Maybe[object]:
-    """Parse a string to an enum value."""
+    """Parse a string to an enum member.
+
+    Matches input against enum member values and names (case-insensitive for names).
+    Handles whitespace trimming and supports enums with empty string values.
+
+    Args:
+        input_value: String to parse (whitespace is stripped for non-exact matches)
+        enum_class: The Enum class to parse into
+        error_message: Optional custom error message for parsing failures
+
+    Returns:
+        Maybe[object]: Success with enum member if valid, Failure(str) with error message otherwise
+
+    Examples:
+        >>> from enum import Enum
+        >>> class Color(Enum):
+        ...     RED = 'red'
+        ...     GREEN = 'green'
+        ...     BLUE = 'blue'
+        >>> parse_enum("red", Color)
+        Success(<Color.RED: 'red'>)
+        >>> parse_enum("RED", Color)
+        Success(<Color.RED: 'red'>)
+        >>> parse_enum("  green  ", Color)
+        Success(<Color.GREEN: 'green'>)
+        >>> parse_enum("yellow", Color).is_failure()
+        True
+    """
     if not isinstance(enum_class, type) or not issubclass(enum_class, Enum):
         return Maybe.failure(error_message or 'Invalid enum class provided')
 
@@ -269,15 +421,27 @@ def parse_list(
 ) -> Maybe[list[T]]:
     """Parse a string to a list using the specified element parser and separator.
 
+    Splits the input string by the separator and parses each element using the element parser.
+    If no element parser is provided, elements are returned as trimmed strings.
+
     Args:
         input_value: The string to parse
-        element_parser: A function that parses individual elements
-        separator: The string that separates elements
+        element_parser: A function that parses individual elements (default: strips whitespace)
+        separator: The string that separates elements (default: ',')
         error_message: Custom error message for parsing failures
 
     Returns:
-        A Maybe containing the parsed list or an error message
+        Maybe[list[T]]: Success with parsed list or Failure with error message
 
+    Examples:
+        >>> parse_list("a,b,c")
+        Success(['a', 'b', 'c'])
+        >>> parse_list("1, 2, 3", element_parser=parse_int)
+        Success([1, 2, 3])
+        >>> parse_list("apple|banana|cherry", separator="|")
+        Success(['apple', 'banana', 'cherry'])
+        >>> parse_list("1,2,invalid", element_parser=parse_int).is_failure()
+        True
     """
     if not input_value:
         return Maybe.failure('Input must not be empty')
@@ -358,7 +522,32 @@ def parse_dict(  # noqa: PLR0913
     key_value_separator: str = ':',
     error_message: str | None = None,
 ) -> Maybe[dict[K, V]]:
-    """Parse a string to a dictionary using the specified parsers and separators."""
+    """Parse a string to a dictionary using the specified parsers and separators.
+
+    Splits the input string by pair_separator, then splits each pair by key_value_separator.
+    Parses keys and values using the provided parsers (defaults to trimmed strings).
+
+    Args:
+        input_value: The string to parse
+        key_parser: A function that parses keys (default: strips whitespace)
+        value_parser: A function that parses values (default: strips whitespace)
+        pair_separator: The string that separates key-value pairs (default: ',')
+        key_value_separator: The string that separates keys from values (default: ':')
+        error_message: Custom error message for parsing failures
+
+    Returns:
+        Maybe[dict[K, V]]: Success with parsed dictionary or Failure with error message
+
+    Examples:
+        >>> parse_dict("a:1,b:2,c:3")
+        Success({'a': '1', 'b': '2', 'c': '3'})
+        >>> parse_dict("x:10, y:20", value_parser=parse_int)
+        Success({'x': 10, 'y': 20})
+        >>> parse_dict("name=Alice|age=30", pair_separator="|", key_value_separator="=")
+        Success({'name': 'Alice', 'age': '30'})
+        >>> parse_dict("a:1,b:invalid", value_parser=parse_int).is_failure()
+        True
+    """
     if not input_value:
         return Maybe.failure('Input must not be empty')
 
@@ -402,15 +591,33 @@ def parse_set(
 ) -> Maybe[set[T]]:
     """Parse a string to a set using the specified element parser and separator.
 
+    Splits the input string by the separator and parses each element using the element parser.
+    Automatically removes duplicate values. If no element parser is provided, elements are
+    returned as trimmed strings.
+
     Args:
         input_value: The string to parse
-        element_parser: A function that parses individual elements
-        separator: The string that separates elements
+        element_parser: A function that parses individual elements (default: strips whitespace)
+        separator: The string that separates elements (default: ',')
         error_message: Custom error message for parsing failures
 
     Returns:
-        A Maybe containing the parsed set or an error message
+        Maybe[set[T]]: Success with parsed set or Failure with error message
 
+    Examples:
+        >>> result = parse_set("a,b,c")
+        >>> result.is_success()
+        True
+        >>> sorted(result.value_or(set()))
+        ['a', 'b', 'c']
+        >>> result = parse_set("1, 2, 3, 2, 1", element_parser=parse_int)
+        >>> sorted(result.value_or(set()))
+        [1, 2, 3]
+        >>> result = parse_set("red|blue|green|red", separator="|")
+        >>> sorted(result.value_or(set()))
+        ['blue', 'green', 'red']
+        >>> parse_set("1,2,invalid", element_parser=parse_int).is_failure()
+        True
     """
     if separator is None:
         separator = ','
@@ -433,7 +640,10 @@ def parse_int_with_validation(
     max_value: int | None = None,
     error_message: str | None = None,
 ) -> Maybe[int]:
-    """Parse a string to an integer with validation.
+    """Parse a string to an integer with range validation.
+
+    Combines parsing and validation in a single step. First parses the string to an integer,
+    then validates it falls within the specified range.
 
     Args:
         input_value: The string to parse
@@ -442,8 +652,17 @@ def parse_int_with_validation(
         error_message: Custom error message for parsing failures
 
     Returns:
-        A Maybe containing the parsed integer or an error message
+        Maybe[int]: Success with validated integer or Failure with error message
 
+    Examples:
+        >>> parse_int_with_validation("42", min_value=0, max_value=100)
+        Success(42)
+        >>> parse_int_with_validation("5", min_value=10).is_failure()
+        True
+        >>> parse_int_with_validation("150", max_value=100).is_failure()
+        True
+        >>> parse_int_with_validation("50", min_value=0, max_value=100)
+        Success(50)
     """
     result = parse_int(input_value, error_message)
     if result.is_failure():
@@ -469,7 +688,10 @@ def parse_list_with_validation(  # noqa: PLR0913
     max_length: int | None = None,
     error_message: str | None = None,
 ) -> Maybe[list[T]]:
-    """Parse a string to a list with validation.
+    """Parse a string to a list with length validation.
+
+    Combines parsing and validation in a single step. First parses the string to a list,
+    then validates it has an acceptable number of elements.
 
     Args:
         input_value: The string to parse
@@ -480,8 +702,17 @@ def parse_list_with_validation(  # noqa: PLR0913
         error_message: Custom error message for parsing failures
 
     Returns:
-        A Maybe containing the parsed list or an error message
+        Maybe[list[T]]: Success with validated list or Failure with error message
 
+    Examples:
+        >>> parse_list_with_validation("a,b,c", min_length=2, max_length=5)
+        Success(['a', 'b', 'c'])
+        >>> parse_list_with_validation("1,2", element_parser=parse_int, min_length=3).is_failure()
+        True
+        >>> parse_list_with_validation("1,2,3,4,5,6", max_length=5).is_failure()
+        True
+        >>> parse_list_with_validation("10,20,30", element_parser=parse_int, min_length=1)
+        Success([10, 20, 30])
     """
     result = parse_list(input_value, element_parser, separator, error_message)
     if result.is_failure():
@@ -508,7 +739,10 @@ def parse_dict_with_validation(  # noqa: PLR0913
     required_keys: list[str] | None = None,
     error_message: str | None = None,
 ) -> Maybe[dict[K, V]]:
-    """Parse a string to a dictionary with validation.
+    """Parse a string to a dictionary with required keys validation.
+
+    Combines parsing and validation in a single step. First parses the string to a dictionary,
+    then validates that all required keys are present.
 
     Args:
         input_value: The string to parse
@@ -520,8 +754,16 @@ def parse_dict_with_validation(  # noqa: PLR0913
         error_message: Custom error message for parsing failures
 
     Returns:
-        A Maybe containing the parsed dictionary or an error message
+        Maybe[dict[K, V]]: Success with validated dictionary or Failure with error message
 
+    Examples:
+        >>> parse_dict_with_validation("name:Alice,age:30", required_keys=["name", "age"])
+        Success({'name': 'Alice', 'age': '30'})
+        >>> parse_dict_with_validation("name:Bob", required_keys=["name", "age"]).is_failure()
+        True
+        >>> result = parse_dict_with_validation("x:10,y:20", value_parser=parse_int, required_keys=["x"])
+        >>> result.value_or({})
+        {'x': 10, 'y': 20}
     """
     result = parse_dict(input_value, key_parser, value_parser, pair_separator, key_value_separator, error_message)
     if result.is_failure():
@@ -705,13 +947,24 @@ def parse_uuid(text: str, version: int | None = None, strict: bool = True) -> Ma
 def parse_ipv4(text: str) -> Maybe[IPv4Address]:
     """Parse an IPv4 address string.
 
-    Trims surrounding whitespace only. Returns Success with a concrete
-    IPv4Address on success, or Failure with a deterministic error message.
+    Validates and parses IPv4 addresses in dotted-decimal notation.
+    Trims surrounding whitespace.
+
+    Args:
+        text: String containing an IPv4 address (whitespace is stripped)
+
+    Returns:
+        Maybe[IPv4Address]: Success(IPv4Address) if valid, Failure(str) with error message otherwise
 
-    Error messages:
-    - value must be a string
-    - value is empty
-    - not a valid IPv4 address
+    Examples:
+        >>> parse_ipv4("192.168.1.1")
+        Success(IPv4Address('192.168.1.1'))
+        >>> parse_ipv4("  10.0.0.1  ")
+        Success(IPv4Address('10.0.0.1'))
+        >>> parse_ipv4("256.1.1.1").is_failure()
+        True
+        >>> parse_ipv4("not an ip").is_failure()
+        True
     """
     if not isinstance(text, str):
         return Maybe.failure('Input must be a string')
@@ -734,13 +987,24 @@ def parse_ipv4(text: str) -> Maybe[IPv4Address]:
 def parse_ipv6(text: str) -> Maybe[IPv6Address]:
     """Parse an IPv6 address string.
 
-    Trims surrounding whitespace only. Returns Success with a concrete
-    IPv6Address on success, or Failure with a deterministic error message.
+    Validates and parses IPv6 addresses in standard notation.
+    Rejects scope IDs (e.g., %eth0). Trims surrounding whitespace.
+
+    Args:
+        text: String containing an IPv6 address (whitespace is stripped)
+
+    Returns:
+        Maybe[IPv6Address]: Success(IPv6Address) if valid, Failure(str) with error message otherwise
 
-    Error messages:
-    - value must be a string
-    - value is empty
-    - not a valid IPv6 address
+    Examples:
+        >>> parse_ipv6("::1")
+        Success(IPv6Address('::1'))
+        >>> parse_ipv6("2001:0db8:85a3::8a2e:0370:7334")
+        Success(IPv6Address('2001:db8:85a3::8a2e:370:7334'))
+        >>> parse_ipv6("  fe80::1  ")
+        Success(IPv6Address('fe80::1'))
+        >>> parse_ipv6("192.168.1.1").is_failure()
+        True
     """
     if not isinstance(text, str):
         return Maybe.failure('Input must be a string')
@@ -767,12 +1031,27 @@ def parse_ipv6(text: str) -> Maybe[IPv6Address]:
 def parse_ip(text: str) -> Maybe[IPv4Address | IPv6Address]:
     """Parse a string as either an IPv4 or IPv6 address.
 
-    Trims surrounding whitespace only.
+    Automatically detects and parses either IPv4 or IPv6 addresses.
+    Trims surrounding whitespace.
 
-    Error messages:
-    - value must be a string
-    - value is empty
-    - not a valid IP address
+    Args:
+        text: String containing an IP address (IPv4 or IPv6, whitespace is stripped)
+
+    Returns:
+        Maybe[IPv4Address | IPv6Address]: Success with IPv4Address or IPv6Address if valid,
+            Failure(str) with error message otherwise
+
+    Examples:
+        >>> result = parse_ip("192.168.1.1")
+        >>> result.is_success()
+        True
+        >>> result = parse_ip("::1")
+        >>> result.is_success()
+        True
+        >>> parse_ip("  10.0.0.1  ")
+        Success(IPv4Address('10.0.0.1'))
+        >>> parse_ip("not an ip").is_failure()
+        True
     """
     if not isinstance(text, str):
         return Maybe.failure('Input must be a string')
@@ -799,14 +1078,32 @@ def parse_ip(text: str) -> Maybe[IPv4Address | IPv6Address]:
 def parse_cidr(text: str, *, strict: bool = True) -> Maybe[IPv4Network | IPv6Network]:
     """Parse a CIDR network string (IPv4 or IPv6).
 
-    Uses ipaddress.ip_network under the hood. By default ``strict=True``
-    so host bits set will fail. With ``strict=False``, host bits are masked.
+    Validates and parses network addresses in CIDR notation (e.g., 192.168.1.0/24).
+    By default, validates that host bits are not set (strict mode).
+    With strict=False, host bits are masked to the network address.
+
+    Args:
+        text: String containing a CIDR network (whitespace is stripped)
+        strict: If True, reject networks with host bits set; if False, mask them (default: True)
+
+    Returns:
+        Maybe[IPv4Network | IPv6Network]: Success with IPv4Network or IPv6Network if valid,
+            Failure(str) with error message otherwise
 
-    Error messages:
-    - value must be a string
-    - value is empty
-    - has host bits set (when strict and host bits are present)
-    - not a valid network (all other parsing failures)
+    Examples:
+        >>> parse_cidr("192.168.1.0/24")
+        Success(IPv4Network('192.168.1.0/24'))
+        >>> parse_cidr("10.0.0.0/8")
+        Success(IPv4Network('10.0.0.0/8'))
+        >>> parse_cidr("2001:db8::/32")
+        Success(IPv6Network('2001:db8::/32'))
+        >>> # Strict mode rejects host bits
+        >>> parse_cidr("192.168.1.5/24").is_failure()
+        True
+        >>> # Non-strict mode masks host bits
+        >>> result = parse_cidr("192.168.1.5/24", strict=False)
+        >>> str(result.value_or(None))
+        '192.168.1.0/24'
     """
     if not isinstance(text, str):
         return Maybe.failure('Input must be a string')

valid8r/core/validators.py

@@ -7,6 +7,7 @@ that either contains the validated value or an error message.
 
 from __future__ import annotations
 
+import re
 from typing import (
     TYPE_CHECKING,
     Generic,
@@ -102,11 +103,25 @@ def minimum(min_value: N, error_message: str | None = None) -> Validator[N]:
     """Create a validator that ensures a value is at least the minimum.
 
     Args:
-        min_value: The minimum allowed value
+        min_value: The minimum allowed value (inclusive)
         error_message: Optional custom error message
 
     Returns:
-        A validator function
+        Validator[N]: A validator function that accepts values >= min_value
+
+    Examples:
+        >>> from valid8r.core.validators import minimum
+        >>> validator = minimum(0)
+        >>> validator(5)
+        Success(5)
+        >>> validator(0)
+        Success(0)
+        >>> validator(-1).is_failure()
+        True
+        >>> # With custom error message
+        >>> validator = minimum(18, error_message="Must be an adult")
+        >>> validator(17).error_or("")
+        'Must be an adult'
 
     """
 
@@ -122,11 +137,25 @@ def maximum(max_value: N, error_message: str | None = None) -> Validator[N]:
     """Create a validator that ensures a value is at most the maximum.
 
     Args:
-        max_value: The maximum allowed value
+        max_value: The maximum allowed value (inclusive)
         error_message: Optional custom error message
 
     Returns:
-        A validator function
+        Validator[N]: A validator function that accepts values <= max_value
+
+    Examples:
+        >>> from valid8r.core.validators import maximum
+        >>> validator = maximum(100)
+        >>> validator(50)
+        Success(50)
+        >>> validator(100)
+        Success(100)
+        >>> validator(101).is_failure()
+        True
+        >>> # With custom error message
+        >>> validator = maximum(120, error_message="Age too high")
+        >>> validator(150).error_or("")
+        'Age too high'
 
     """
 
@@ -142,12 +171,30 @@ def between(min_value: N, max_value: N, error_message: str | None = None) -> Val
     """Create a validator that ensures a value is between minimum and maximum (inclusive).
 
     Args:
-        min_value: The minimum allowed value
-        max_value: The maximum allowed value
+        min_value: The minimum allowed value (inclusive)
+        max_value: The maximum allowed value (inclusive)
         error_message: Optional custom error message
 
     Returns:
-        A validator function
+        Validator[N]: A validator function that accepts values where min_value <= value <= max_value
+
+    Examples:
+        >>> from valid8r.core.validators import between
+        >>> validator = between(0, 100)
+        >>> validator(50)
+        Success(50)
+        >>> validator(0)
+        Success(0)
+        >>> validator(100)
+        Success(100)
+        >>> validator(-1).is_failure()
+        True
+        >>> validator(101).is_failure()
+        True
+        >>> # With custom error message
+        >>> validator = between(1, 10, error_message="Rating must be 1-10")
+        >>> validator(11).error_or("")
+        'Rating must be 1-10'
 
     """
 
@@ -162,12 +209,30 @@ def between(min_value: N, max_value: N, error_message: str | None = None) -> Val
 def predicate(pred: Callable[[T], bool], error_message: str) -> Validator[T]:
     """Create a validator using a custom predicate function.
 
+    Allows creating custom validators for any validation logic by providing
+    a predicate function that returns True for valid values.
+
     Args:
-        pred: A function that takes a value and returns a boolean
-        error_message: Error message when validation fails
+        pred: A function that takes a value and returns True if valid, False otherwise
+        error_message: Error message to return when validation fails
 
     Returns:
-        A validator function
+        Validator[T]: A validator function that applies the predicate
+
+    Examples:
+        >>> from valid8r.core.validators import predicate
+        >>> # Validate even numbers
+        >>> is_even = predicate(lambda x: x % 2 == 0, "Must be even")
+        >>> is_even(4)
+        Success(4)
+        >>> is_even(3).is_failure()
+        True
+        >>> # Validate string patterns
+        >>> starts_with_a = predicate(lambda s: s.startswith('a'), "Must start with 'a'")
+        >>> starts_with_a("apple")
+        Success('apple')
+        >>> starts_with_a("banana").error_or("")
+        "Must start with 'a'"
 
     """
 
@@ -183,12 +248,30 @@ def length(min_length: int, max_length: int, error_message: str | None = None) -
     """Create a validator that ensures a string's length is within bounds.
 
     Args:
-        min_length: Minimum length of the string
-        max_length: Maximum length of the string
+        min_length: Minimum length of the string (inclusive)
+        max_length: Maximum length of the string (inclusive)
         error_message: Optional custom error message
 
     Returns:
-        A validator function
+        Validator[str]: A validator function that checks string length
+
+    Examples:
+        >>> from valid8r.core.validators import length
+        >>> validator = length(3, 10)
+        >>> validator("hello")
+        Success('hello')
+        >>> validator("abc")
+        Success('abc')
+        >>> validator("abcdefghij")
+        Success('abcdefghij')
+        >>> validator("ab").is_failure()
+        True
+        >>> validator("abcdefghijk").is_failure()
+        True
+        >>> # With custom error message
+        >>> validator = length(8, 20, error_message="Password must be 8-20 characters")
+        >>> validator("short").error_or("")
+        'Password must be 8-20 characters'
 
     """
 
@@ -198,3 +281,285 @@ def length(min_length: int, max_length: int, error_message: str | None = None) -
         return Maybe.failure(error_message or f'String length must be between {min_length} and {max_length}')
 
     return Validator(validator)
+
+
+def matches_regex(pattern: str | re.Pattern[str], error_message: str | None = None) -> Validator[str]:
+    r"""Create a validator that ensures a string matches a regular expression pattern.
+
+    Args:
+        pattern: Regular expression pattern (string or compiled Pattern object)
+        error_message: Optional custom error message
+
+    Returns:
+        Validator[str]: A validator function that checks pattern matching
+
+    Examples:
+        >>> from valid8r.core.validators import matches_regex
+        >>> import re
+        >>> # String pattern
+        >>> validator = matches_regex(r'^\\d{3}-\\d{2}-\\d{4}$')
+        >>> validator('123-45-6789')
+        Success('123-45-6789')
+        >>> validator('invalid').is_failure()
+        True
+        >>> # Compiled regex pattern
+        >>> pattern = re.compile(r'^[A-Z][a-z]+$')
+        >>> validator = matches_regex(pattern)
+        >>> validator('Hello')
+        Success('Hello')
+        >>> validator('hello').is_failure()
+        True
+        >>> # With custom error message
+        >>> validator = matches_regex(r'^\\d{5}$', error_message='Must be a 5-digit ZIP code')
+        >>> validator('1234').error_or('')
+        'Must be a 5-digit ZIP code'
+
+    """
+    compiled_pattern = re.compile(pattern) if isinstance(pattern, str) else pattern
+
+    def validator(value: str) -> Maybe[str]:
+        if compiled_pattern.match(value):
+            return Maybe.success(value)
+        return Maybe.failure(error_message or f'Value must match pattern {compiled_pattern.pattern}')
+
+    return Validator(validator)
+
+
+def in_set(allowed_values: set[T], error_message: str | None = None) -> Validator[T]:
+    """Create a validator that ensures a value is in a set of allowed values.
+
+    Args:
+        allowed_values: Set of allowed values
+        error_message: Optional custom error message
+
+    Returns:
+        Validator[T]: A validator function that checks membership
+
+    Examples:
+        >>> from valid8r.core.validators import in_set
+        >>> # String values
+        >>> validator = in_set({'red', 'green', 'blue'})
+        >>> validator('red')
+        Success('red')
+        >>> validator('yellow').is_failure()
+        True
+        >>> # Numeric values
+        >>> validator = in_set({1, 2, 3, 4, 5})
+        >>> validator(3)
+        Success(3)
+        >>> validator(10).is_failure()
+        True
+        >>> # With custom error message
+        >>> validator = in_set({'small', 'medium', 'large'}, error_message='Size must be S, M, or L')
+        >>> validator('extra-large').error_or('')
+        'Size must be S, M, or L'
+
+    """
+
+    def validator(value: T) -> Maybe[T]:
+        if value in allowed_values:
+            return Maybe.success(value)
+        return Maybe.failure(error_message or f'Value must be one of {allowed_values}')
+
+    return Validator(validator)
+
+
+def non_empty_string(error_message: str | None = None) -> Validator[str]:
+    """Create a validator that ensures a string is not empty.
+
+    Validates that a string contains at least one non-whitespace character.
+    Both empty strings and whitespace-only strings are rejected.
+
+    Args:
+        error_message: Optional custom error message
+
+    Returns:
+        Validator[str]: A validator function that checks for non-empty strings
+
+    Examples:
+        >>> from valid8r.core.validators import non_empty_string
+        >>> validator = non_empty_string()
+        >>> validator('hello')
+        Success('hello')
+        >>> validator('  hello  ')
+        Success('  hello  ')
+        >>> validator('').is_failure()
+        True
+        >>> validator('   ').is_failure()
+        True
+        >>> # With custom error message
+        >>> validator = non_empty_string(error_message='Name is required')
+        >>> validator('').error_or('')
+        'Name is required'
+
+    """
+
+    def validator(value: str) -> Maybe[str]:
+        if value.strip():
+            return Maybe.success(value)
+        return Maybe.failure(error_message or 'String must not be empty')
+
+    return Validator(validator)
+
+
+def unique_items(error_message: str | None = None) -> Validator[list[T]]:
+    """Create a validator that ensures all items in a list are unique.
+
+    Validates that a list contains no duplicate elements by comparing
+    the list length to the set length.
+
+    Args:
+        error_message: Optional custom error message
+
+    Returns:
+        Validator[list[T]]: A validator function that checks for unique items
+
+    Examples:
+        >>> from valid8r.core.validators import unique_items
+        >>> validator = unique_items()
+        >>> validator([1, 2, 3, 4, 5])
+        Success([1, 2, 3, 4, 5])
+        >>> validator([1, 2, 2, 3]).is_failure()
+        True
+        >>> # Works with strings
+        >>> validator(['a', 'b', 'c'])
+        Success(['a', 'b', 'c'])
+        >>> validator(['a', 'b', 'a']).is_failure()
+        True
+        >>> # With custom error message
+        >>> validator = unique_items(error_message='Duplicate items found')
+        >>> validator([1, 1, 2]).error_or('')
+        'Duplicate items found'
+
+    """
+
+    def validator(value: list[T]) -> Maybe[list[T]]:
+        if len(value) == len(set(value)):
+            return Maybe.success(value)
+        return Maybe.failure(error_message or 'All items must be unique')
+
+    return Validator(validator)
+
+
+def subset_of(allowed_set: set[T], error_message: str | None = None) -> Validator[set[T]]:
+    """Create a validator that ensures a set is a subset of allowed values.
+
+    Validates that all elements in the input set are contained within
+    the allowed set. An empty set is always a valid subset.
+
+    Args:
+        allowed_set: The set of allowed values
+        error_message: Optional custom error message
+
+    Returns:
+        Validator[set[T]]: A validator function that checks subset relationship
+
+    Examples:
+        >>> from valid8r.core.validators import subset_of
+        >>> validator = subset_of({1, 2, 3, 4, 5})
+        >>> validator({1, 2, 3})
+        Success({1, 2, 3})
+        >>> validator({1, 2, 3, 4, 5, 6}).is_failure()
+        True
+        >>> # Empty set is valid subset
+        >>> validator(set())
+        Success(set())
+        >>> # With custom error message
+        >>> validator = subset_of({'a', 'b', 'c'}, error_message='Invalid characters')
+        >>> validator({'a', 'd'}).error_or('')
+        'Invalid characters'
+
+    """
+
+    def validator(value: set[T]) -> Maybe[set[T]]:
+        if value.issubset(allowed_set):
+            return Maybe.success(value)
+        return Maybe.failure(error_message or f'Value must be a subset of {allowed_set}')
+
+    return Validator(validator)
+
+
+def superset_of(required_set: set[T], error_message: str | None = None) -> Validator[set[T]]:
+    """Create a validator that ensures a set is a superset of required values.
+
+    Validates that the input set contains all elements from the required set.
+    The input set may contain additional elements beyond those required.
+
+    Args:
+        required_set: The set of required values
+        error_message: Optional custom error message
+
+    Returns:
+        Validator[set[T]]: A validator function that checks superset relationship
+
+    Examples:
+        >>> from valid8r.core.validators import superset_of
+        >>> validator = superset_of({1, 2, 3})
+        >>> validator({1, 2, 3, 4, 5})
+        Success({1, 2, 3, 4, 5})
+        >>> validator({1, 2}).is_failure()
+        True
+        >>> # Exact match is valid
+        >>> validator({1, 2, 3})
+        Success({1, 2, 3})
+        >>> # With custom error message
+        >>> validator = superset_of({'read', 'write'}, error_message='Missing required permissions')
+        >>> validator({'read'}).error_or('')
+        'Missing required permissions'
+
+    """
+
+    def validator(value: set[T]) -> Maybe[set[T]]:
+        if value.issuperset(required_set):
+            return Maybe.success(value)
+        return Maybe.failure(error_message or f'Value must be a superset of {required_set}')
+
+    return Validator(validator)
+
+
+def is_sorted(*, reverse: bool = False, error_message: str | None = None) -> Validator[list[N]]:
+    """Create a validator that ensures a list is sorted.
+
+    Validates that a list is sorted in either ascending or descending order.
+    Uses keyword-only parameters to avoid boolean trap anti-pattern.
+
+    Args:
+        reverse: If True, checks for descending order; otherwise ascending (default)
+        error_message: Optional custom error message
+
+    Returns:
+        Validator[list[N]]: A validator function that checks if list is sorted
+
+    Examples:
+        >>> from valid8r.core.validators import is_sorted
+        >>> # Ascending order (default)
+        >>> validator = is_sorted()
+        >>> validator([1, 2, 3, 4, 5])
+        Success([1, 2, 3, 4, 5])
+        >>> validator([3, 1, 4, 2]).is_failure()
+        True
+        >>> # Descending order
+        >>> validator = is_sorted(reverse=True)
+        >>> validator([5, 4, 3, 2, 1])
+        Success([5, 4, 3, 2, 1])
+        >>> validator([1, 2, 3]).is_failure()
+        True
+        >>> # Works with strings
+        >>> validator = is_sorted()
+        >>> validator(['a', 'b', 'c'])
+        Success(['a', 'b', 'c'])
+        >>> # With custom error message
+        >>> validator = is_sorted(error_message='List must be in order')
+        >>> validator([3, 1, 2]).error_or('')
+        'List must be in order'
+
+    """
+
+    def validator(value: list[N]) -> Maybe[list[N]]:
+        sorted_value = sorted(value, reverse=reverse)
+        if value == sorted_value:
+            return Maybe.success(value)
+        direction = 'descending' if reverse else 'ascending'
+        return Maybe.failure(error_message or f'List must be sorted in {direction} order')
+
+    return Validator(validator)

valid8r/prompt/basic.py

@@ -85,29 +85,68 @@ def ask(  # noqa: PLR0913
     retry: bool | int = False,
     _test_mode: bool = False,
 ) -> Maybe[T]:
-    """Prompt the user for input with validation.
+    """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.
 
     Args:
-        prompt_text: The prompt to display to the user
-        parser: Function to convert string to desired type
-        validator: Function to validate the parsed value
-        error_message: Custom error message for invalid input
-        default: Default value to use if input is empty
-        retry: If True or an integer, retry on invalid input
-        _test_mode: Hidden parameter for testing the final return path
+        prompt_text: The prompt message to display to the user
+        parser: Function to convert string input to desired type (default: returns string as-is)
+        validator: Function to validate the parsed value (default: accepts any value)
+        error_message: Custom error message to display on validation failure
+        default: Default value to use if user provides empty input (displays in prompt)
+        retry: Enable retry on failure - True for unlimited, integer for max attempts, False to disable
+        _test_mode: Internal testing parameter (do not use)
 
     Returns:
-        A Maybe containing the validated input or an error
+        Maybe[T]: Success with validated input, or Failure with error message
 
     Examples:
-        >>> # This would prompt the user and validate their input
         >>> from valid8r.core import parsers, validators
-        >>> age = ask(
+        >>> from valid8r.prompt import ask
+        >>>
+        >>> # Basic integer input with validation
+        >>> result = ask(
         ...     "Enter your age: ",
         ...     parser=parsers.parse_int,
-        ...     validator=validators.minimum(0),
+        ...     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.
 
     """
     # Create a config object from the parameters

{valid8r-0.6.2.dist-info → valid8r-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: valid8r
-Version: 0.6.2
+Version: 0.7.0
 Summary: Clean, flexible input validation for Python applications
 License: MIT
 License-File: LICENSE
@@ -78,6 +78,30 @@ A clean, flexible input validation library for Python applications.
 - **Enums**: `parse_enum` (type-safe enum parsing)
 - **Custom**: `create_parser`, `make_parser`, `validated_parser` (parser factories)
 
+## Available Validators
+
+### Numeric Validators
+- **`minimum(min_value)`** - Ensures value is at least the minimum (inclusive)
+- **`maximum(max_value)`** - Ensures value is at most the maximum (inclusive)
+- **`between(min_value, max_value)`** - Ensures value is within range (inclusive)
+
+### String Validators
+- **`non_empty_string()`** - Rejects empty strings and whitespace-only strings
+- **`matches_regex(pattern)`** - Validates string matches regex pattern (string or compiled)
+- **`length(min_length, max_length)`** - Validates string length within bounds
+
+### Collection Validators
+- **`in_set(allowed_values)`** - Ensures value is in set of allowed values
+- **`unique_items()`** - Ensures all items in a list are unique
+- **`subset_of(allowed_set)`** - Validates set is subset of allowed values
+- **`superset_of(required_set)`** - Validates set is superset of required values
+- **`is_sorted(reverse=False)`** - Ensures list is sorted (ascending or descending)
+
+### Custom Validators
+- **`predicate(func, error_message)`** - Create custom validator from any predicate function
+
+**Note**: All validators support custom error messages and can be combined using `&` (and), `|` (or), and `~` (not) operators.
+
 ## Installation
 
 **Requirements**: Python 3.11 or higher
@@ -168,21 +192,21 @@ from valid8r.core.maybe import Success, Failure
 from valid8r.core import parsers
 
 # Phone number parsing with NANP validation (PhoneNumber)
-match parsers.parse_phone("+1 (555) 123-4567"):
+match parsers.parse_phone("+1 (415) 555-2671"):
     case Success(phone):
         print(f"Country: {phone.country_code}")  # 1
-        print(f"Area: {phone.area_code}")        # 555
-        print(f"Exchange: {phone.exchange}")     # 123
-        print(f"Subscriber: {phone.subscriber}") # 4567
+        print(f"Area: {phone.area_code}")        # 415
+        print(f"Exchange: {phone.exchange}")     # 555
+        print(f"Subscriber: {phone.subscriber}") # 2671
 
         # Format for display using properties
-        print(f"E.164: {phone.e164}")           # +15551234567
-        print(f"National: {phone.national}")    # (555) 123-4567
+        print(f"E.164: {phone.e164}")           # +14155552671
+        print(f"National: {phone.national}")    # (415) 555-2671
     case Failure(err):
         print("Error:", err)
 
 # Also accepts various formats
-for number in ["5551234567", "(555) 123-4567", "555-123-4567"]:
+for number in ["4155552671", "(415) 555-2671", "415-555-2671"]:
     result = parsers.parse_phone(number)
     assert result.is_success()
 ```
@@ -212,24 +236,26 @@ assert assert_maybe_failure(result, "at least 0")
 
 # Test prompts with mock input
 with MockInputContext(["yes", "42", "invalid", "25"]):
-    # First prompt
+    # First prompt - returns Maybe, unwrap with value_or()
     result = prompt.ask("Continue? ", parser=parsers.parse_bool)
     assert result.value_or(False) == True
 
-    # Second prompt
-    age = prompt.ask(
+    # Second prompt - unwrap the Maybe result
+    result = prompt.ask(
         "Age? ",
         parser=parsers.parse_int,
         validator=validate_age
     )
+    age = result.value_or(None)
     assert age == 42
 
-    # Third prompt will fail, fourth succeeds
-    age = prompt.ask(
+    # Third prompt will fail, fourth succeeds - unwrap result
+    result = prompt.ask(
         "Age again? ",
         parser=parsers.parse_int,
-        retries=1  # Retry once after failure
+        retry=1  # Retry once after failure
     )
+    age = result.value_or(None)
     assert age == 25
 ```
 

{valid8r-0.6.2.dist-info → valid8r-0.7.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
 valid8r/__init__.py,sha256=2fzSl6XtKX44sdqzf0GBTn4oEaCvhmyGkdsPDMJjZz8,447
 valid8r/core/__init__.py,sha256=ASOdzqCtpZHbHjjYMZkb78Z-nKxtD26ruTY0bd43ImA,520
 valid8r/core/combinators.py,sha256=KvRiDEqoZgH58cBYPO6SW9pdtkyijk0lS8aGSB5DbO4,2349
-valid8r/core/maybe.py,sha256=xT1xbiLVKohZ2aeaDZoKjT0W6Vk_PPwKbZXpIfsP7hc,4359
-valid8r/core/parsers.py,sha256=U-fszQfRmUzT_PMhmVVlUnTpY7CooeG9rr3Lxv5fIfs,55866
-valid8r/core/validators.py,sha256=oCrRQ2wIPNkqQXy-hJ7sQ9mJAvxtEtGhoy7WvehWqTc,5756
+valid8r/core/maybe.py,sha256=ifz15tDMwRaQLsYvU3pWGBZBxJ2JyyOW-g5YpOw_-3w,4643
+valid8r/core/parsers.py,sha256=WYAgwCIh8HyrXr0AoZeqa0c43-_iVIK_S3wb2lha73c,67456
+valid8r/core/validators.py,sha256=e3B_fi7ch5m0Zczg87r8AhrgEdBTcbz-aygrKCvi0dg,18537
 valid8r/prompt/__init__.py,sha256=XYB3NEp-tmqT6fGmETVEeXd7Urj0M4ijlwdRAjj-rG8,175
-valid8r/prompt/basic.py,sha256=fLWuN-oiVZyaLdbcW5GHWpoGQ82RG0j-1n7uMYDfOb8,6008
+valid8r/prompt/basic.py,sha256=fFARuy5nGTE7xM3dB1jpRC3OPNmp4WwaymFMz7BSgdo,7635
 valid8r/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 valid8r/testing/__init__.py,sha256=8mk54zt0Ai2dK0a3GMOTfDPsVQWXaS6uvQJDrkRV9hs,779
 valid8r/testing/assertions.py,sha256=9KGz1JooCoyikyxMX7VuXB9VYAtj-4H_LPYFGdvS-ps,1820
 valid8r/testing/generators.py,sha256=kAV6NRO9x1gPy0BfGs07ETVxjpTIxOZyV9wH2BA1nHA,8791
 valid8r/testing/mock_input.py,sha256=9GRT7h0PCh9Dea-OcQ5Uls7YqhsTdqMWuX6I6ZlW1aw,2334
-valid8r-0.6.2.dist-info/METADATA,sha256=-uKoFnQMura7JXCYVDu7F4JxR1owUyErOBgc5IJM9f8,9096
-valid8r-0.6.2.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-valid8r-0.6.2.dist-info/entry_points.txt,sha256=H_24A4zUgnKIXAIRosJliIcntyqMfmcgKh5_Prl7W18,79
-valid8r-0.6.2.dist-info/licenses/LICENSE,sha256=JpEmJvRYOTIUt0UjgvpDrd3U94Wnbt_Grr5z-xU2jtk,1066
-valid8r-0.6.2.dist-info/RECORD,,
+valid8r-0.7.0.dist-info/METADATA,sha256=X7tG_qUhsJ3LE0M28nIDMjERAiTOp_xcHnSen9RbXgU,10458
+valid8r-0.7.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+valid8r-0.7.0.dist-info/entry_points.txt,sha256=H_24A4zUgnKIXAIRosJliIcntyqMfmcgKh5_Prl7W18,79
+valid8r-0.7.0.dist-info/licenses/LICENSE,sha256=JpEmJvRYOTIUt0UjgvpDrd3U94Wnbt_Grr5z-xU2jtk,1066
+valid8r-0.7.0.dist-info/RECORD,,