valid8r 0.2.6__py3-none-any.whl → 0.2.8__py3-none-any.whl

valid8r/core/parsers.py

@@ -1106,6 +1106,42 @@ def parse_url(
     - Unsupported URL scheme
     - URL requires host
     - Invalid host
+
+    Args:
+        text: The URL string to parse
+        allowed_schemes: Iterable of allowed scheme names (default: ('http', 'https'))
+        require_host: Whether to require a host in the URL (default: True)
+
+    Returns:
+        Maybe[UrlParts]: Success with UrlParts containing parsed components, or Failure with error message
+
+    Examples:
+        >>> from valid8r.core.parsers import parse_url
+        >>> from valid8r.core.maybe import Success
+        >>>
+        >>> # Parse a complete URL
+        >>> result = parse_url('https://user:pass@api.example.com:8080/v1/users?active=true#section')
+        >>> isinstance(result, Success)
+        True
+        >>> url = result.value
+        >>> url.scheme
+        'https'
+        >>> url.host
+        'api.example.com'
+        >>> url.port
+        8080
+        >>> url.path
+        '/v1/users'
+        >>> url.query
+        'active=true'
+        >>> url.fragment
+        'section'
+        >>>
+        >>> # Access credentials
+        >>> url.username
+        'user'
+        >>> url.password
+        'pass'
     """
     if not isinstance(text, str):
         return Maybe.failure('Input must be a string')
@@ -1189,6 +1225,22 @@ def parse_email(text: str) -> Maybe[EmailAddress]:
 
     Returns:
         Maybe[EmailAddress]: Success with EmailAddress or Failure with error message
+
+    Examples:
+        >>> from valid8r.core.parsers import parse_email
+        >>> from valid8r.core.maybe import Success
+        >>>
+        >>> # Parse an email with case normalization
+        >>> result = parse_email('User.Name+tag@Example.COM')
+        >>> isinstance(result, Success)
+        True
+        >>> email = result.value
+        >>> # Local part preserves original case
+        >>> email.local
+        'User.Name+tag'
+        >>> # Domain is normalized to lowercase
+        >>> email.domain
+        'example.com'
     """
     if not isinstance(text, str):
         return Maybe.failure('Input must be a string')

valid8r-0.2.8.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: valid8r
+Version: 0.2.8
+Summary: Clean, flexible input validation for Python applications
+License: MIT
+Keywords: validation,input,cli,maybe-monad
+Author: Mike Lane
+Author-email: mikelane@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: email-validator (>=2.3.0,<3.0.0)
+Requires-Dist: pydantic (>=2.0)
+Requires-Dist: pydantic-core (>=2.27.0,<3.0.0)
+Requires-Dist: uuid-utils (>=0.11.0,<0.12.0)
+Project-URL: Repository, https://github.com/mikelane/valid8r
+Description-Content-Type: text/markdown
+
+# Valid8r
+
+A clean, flexible input validation library for Python applications.
+
+## Features
+
+- **Clean Type Parsing**: Parse strings to various Python types with robust error handling
+- **Flexible Validation**: Chain validators and create custom validation rules
+- **Monadic Error Handling**: Use Maybe monad for clean error propagation
+- **Input Prompting**: Prompt users for input with built-in validation
+- **Structured Results**: Network parsers return rich dataclasses with parsed components
+
+## Available Parsers
+
+### Basic Types
+- **Numbers**: `parse_int`, `parse_float`, `parse_complex`, `parse_decimal`
+- **Text**: `parse_bool` (flexible true/false parsing)
+- **Dates**: `parse_date` (ISO 8601 format)
+- **UUIDs**: `parse_uuid` (with optional version validation)
+
+### Collections
+- **Lists**: `parse_list` (with element parser)
+- **Dictionaries**: `parse_dict` (with key/value parsers)
+- **Sets**: `parse_set` (with element parser)
+
+### Network & Communication
+- **IP Addresses**: `parse_ipv4`, `parse_ipv6`, `parse_ip` (either v4 or v6)
+- **Networks**: `parse_cidr` (IPv4/IPv6 CIDR notation)
+- **Phone Numbers**: `parse_phone` → PhoneNumber (NANP validation)
+- **URLs**: `parse_url` → UrlParts (scheme, host, port, path, query, etc.)
+- **Email**: `parse_email` → EmailAddress (normalized case)
+
+### Advanced
+- **Enums**: `parse_enum` (type-safe enum parsing)
+- **Custom**: `create_parser`, `make_parser`, `validated_parser` (parser factories)
+
+## Installation
+
+```bash
+pip install valid8r
+```
+
+## Quick Start
+
+```python
+from valid8r import (
+    parsers,
+    prompt,
+    validators,
+)
+
+# Simple validation
+age = prompt.ask(
+    "Enter your age: ",
+    parser=parsers.parse_int,
+    validator=validators.minimum(0) & validators.maximum(120)
+)
+
+print(f"Your age is {age}")
+```
+
+### IP parsing helpers
+
+```python
+from valid8r.core.maybe import Success, Failure
+from valid8r.core import parsers
+
+# IPv4 / IPv6 / generic IP
+for text in ["192.168.0.1", "::1", " 10.0.0.1 "]:
+    match parsers.parse_ip(text):
+        case Success(addr):
+            print("Parsed:", addr)
+        case Failure(err):
+            print("Error:", err)
+
+# CIDR (strict by default)
+match parsers.parse_cidr("10.0.0.0/8"):
+    case Success(net):
+        print("Network:", net)  # 10.0.0.0/8
+    case Failure(err):
+        print("Error:", err)
+
+# Non-strict masks host bits
+match parsers.parse_cidr("10.0.0.1/24", strict=False):
+    case Success(net):
+        assert str(net) == "10.0.0.0/24"
+```
+
+### URL and Email helpers
+
+```python
+from valid8r.core.maybe import Success, Failure
+from valid8r.core import parsers
+
+# URL parsing with structured result (UrlParts)
+match parsers.parse_url("https://alice:pw@example.com:8443/x?q=1#top"):
+    case Success(u):
+        print(f"Scheme: {u.scheme}")     # https
+        print(f"Host: {u.host}")         # example.com
+        print(f"Port: {u.port}")         # 8443
+        print(f"Path: {u.path}")         # /x
+        print(f"Query: {u.query}")       # {'q': '1'}
+        print(f"Fragment: {u.fragment}") # top
+    case Failure(err):
+        print("Error:", err)
+
+# Email parsing with normalized case (EmailAddress)
+match parsers.parse_email("First.Last+tag@Example.COM"):
+    case Success(e):
+        print(f"Local: {e.local}")   # First.Last+tag
+        print(f"Domain: {e.domain}") # example.com (normalized)
+    case Failure(err):
+        print("Error:", err)
+```
+
+### Phone Number Parsing
+
+```python
+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"):
+    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
+
+        # Format for display using properties
+        print(f"E.164: {phone.e164}")           # +15551234567
+        print(f"National: {phone.national}")    # (555) 123-4567
+    case Failure(err):
+        print("Error:", err)
+
+# Also accepts various formats
+for number in ["5551234567", "(555) 123-4567", "555-123-4567"]:
+    result = parsers.parse_phone(number)
+    assert result.is_success()
+```
+
+## Testing Support
+
+Valid8r includes comprehensive testing utilities to help you verify your validation logic:
+
+```python
+from valid8r import Maybe, validators, parsers, prompt
+from valid8r.testing import (
+    MockInputContext,
+    assert_maybe_success,
+    assert_maybe_failure,
+)
+
+def validate_age(age: int) -> Maybe[int]:
+    """Validate age is between 0 and 120."""
+    return (validators.minimum(0) & validators.maximum(120))(age)
+
+# Test validation functions with assert helpers
+result = validate_age(42)
+assert assert_maybe_success(result, 42)
+
+result = validate_age(-5)
+assert assert_maybe_failure(result, "at least 0")
+
+# Test prompts with mock input
+with MockInputContext(["yes", "42", "invalid", "25"]):
+    # First prompt
+    result = prompt.ask("Continue? ", parser=parsers.parse_bool)
+    assert result.value_or(False) == True
+
+    # Second prompt
+    age = prompt.ask(
+        "Age? ",
+        parser=parsers.parse_int,
+        validator=validate_age
+    )
+    assert age == 42
+
+    # Third prompt will fail, fourth succeeds
+    age = prompt.ask(
+        "Age again? ",
+        parser=parsers.parse_int,
+        retries=1  # Retry once after failure
+    )
+    assert age == 25
+```
+
+### Testing Utilities Reference
+
+- **`assert_maybe_success(result, expected_value)`**: Assert that a Maybe is Success with the expected value
+- **`assert_maybe_failure(result, error_substring)`**: Assert that a Maybe is Failure containing the error substring
+- **`MockInputContext(inputs)`**: Context manager for mocking user input in tests
+
+For more examples, see the [documentation](https://valid8r.readthedocs.io/).
+
+## Development
+
+This project uses Poetry for dependency management and Tox for testing.
+
+### Setup
+
+```bash
+# Install Poetry
+curl -sSL https://install.python-poetry.org | python3 -
+
+# Install dependencies
+poetry install
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+poetry run tox
+
+# Run BDD tests
+poetry run tox -e bdd
+```
+
+## License
+MIT
+

{valid8r-0.2.6.dist-info → valid8r-0.2.8.dist-info}/RECORD

@@ -2,7 +2,7 @@ valid8r/__init__.py,sha256=Yg46vPVbLZvty-FSXkiJ3IkB6hg20pYcp6nWFidIfkk,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=XlP9u0obe060wOJ29S5czCAQaJLObI4XxMax84R2m4k,43732
+valid8r/core/parsers.py,sha256=ur2wS5_-YHAYaJVwi1SJv6P0TRHp6W799VVqrwV45rg,45319
 valid8r/core/validators.py,sha256=oCrRQ2wIPNkqQXy-hJ7sQ9mJAvxtEtGhoy7WvehWqTc,5756
 valid8r/prompt/__init__.py,sha256=XYB3NEp-tmqT6fGmETVEeXd7Urj0M4ijlwdRAjj-rG8,175
 valid8r/prompt/basic.py,sha256=fLWuN-oiVZyaLdbcW5GHWpoGQ82RG0j-1n7uMYDfOb8,6008
@@ -11,7 +11,7 @@ valid8r/testing/__init__.py,sha256=8mk54zt0Ai2dK0a3GMOTfDPsVQWXaS6uvQJDrkRV9hs,7
 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.2.6.dist-info/METADATA,sha256=nBaDsuI3amt2zftTARhWM55pqCsDRPRhF1sabab1sUA,4015
-valid8r-0.2.6.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-valid8r-0.2.6.dist-info/entry_points.txt,sha256=H_24A4zUgnKIXAIRosJliIcntyqMfmcgKh5_Prl7W18,79
-valid8r-0.2.6.dist-info/RECORD,,
+valid8r-0.2.8.dist-info/METADATA,sha256=W8dh72aZE4kVsq7xPM6yQoJlVhvWdgQS1gDCUbIS_VQ,7148
+valid8r-0.2.8.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+valid8r-0.2.8.dist-info/entry_points.txt,sha256=H_24A4zUgnKIXAIRosJliIcntyqMfmcgKh5_Prl7W18,79
+valid8r-0.2.8.dist-info/RECORD,,

valid8r-0.2.6.dist-info/METADATA

@@ -1,168 +0,0 @@
-Metadata-Version: 2.4
-Name: valid8r
-Version: 0.2.6
-Summary: Clean, flexible input validation for Python applications
-License: MIT
-Keywords: validation,input,cli,maybe-monad
-Author: Mike Lane
-Author-email: mikelane@gmail.com
-Requires-Python: >=3.11,<4.0
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Requires-Dist: email-validator (>=2.3.0,<3.0.0)
-Requires-Dist: pydantic (>=2.0)
-Requires-Dist: pydantic-core (>=2.27.0,<3.0.0)
-Requires-Dist: uuid-utils (>=0.11.0,<0.12.0)
-Project-URL: Repository, https://github.com/mikelane/valid8r
-Description-Content-Type: text/markdown
-
-# Valid8r
-
-A clean, flexible input validation library for Python applications.
-
-## Features
-
-- **Clean Type Parsing**: Parse strings to various Python types with robust error handling
-- **Flexible Validation**: Chain validators and create custom validation rules
-- **Monadic Error Handling**: Use Maybe monad for clean error propagation
-- **Input Prompting**: Prompt users for input with built-in validation
-
-## Installation
-
-```bash
-pip install valid8r
-```
-
-## Quick Start
-
-```python
-from valid8r import (
-    parsers,
-    prompt,
-    validators,
-)
-
-# Simple validation
-age = prompt.ask(
-    "Enter your age: ",
-    parser=parsers.parse_int,
-    validator=validators.minimum(0) & validators.maximum(120)
-)
-
-print(f"Your age is {age}")
-```
-
-### IP parsing helpers
-
-```python
-from valid8r.core.maybe import Success, Failure
-from valid8r.core import parsers
-
-# IPv4 / IPv6 / generic IP
-for text in ["192.168.0.1", "::1", " 10.0.0.1 "]:
-    match parsers.parse_ip(text):
-        case Success(addr):
-            print("Parsed:", addr)
-        case Failure(err):
-            print("Error:", err)
-
-# CIDR (strict by default)
-match parsers.parse_cidr("10.0.0.0/8"):
-    case Success(net):
-        print("Network:", net)  # 10.0.0.0/8
-    case Failure(err):
-        print("Error:", err)
-
-# Non-strict masks host bits
-match parsers.parse_cidr("10.0.0.1/24", strict=False):
-    case Success(net):
-        assert str(net) == "10.0.0.0/24"
-```
-
-### URL and Email helpers
-
-```python
-from valid8r.core.maybe import Success, Failure
-from valid8r.core import parsers
-
-# URL parsing
-match parsers.parse_url("https://alice:pw@example.com:8443/x?q=1#top"):
-    case Success(u):
-        print(u.scheme, u.username, u.password, u.host, u.port)
-    case Failure(err):
-        print("Error:", err)
-
-# Email parsing
-match parsers.parse_email("First.Last+tag@Example.COM"):
-    case Success(e):
-        print(e.local, e.domain)  # First.Last+tag example.com
-    case Failure(err):
-        print("Error:", err)
-```
-
-## Testing Support
-
-Valid8r includes testing utilities to help you verify your validation logic:
-
-```python
-from valid8r import (
-    Maybe,
-    validators,
-    parsers,
-    prompt,
-)
-
-from valid8r.testing import (
-    MockInputContext,
-    assert_maybe_success,
-)
-
-def validate_age(age: int) -> Maybe[int]:
-    return validators.minimum(0) & validators.maximum(120)(age)
-
-# Test prompts with mock input
-with MockInputContext(["yes"]):
-    result = prompt.ask("Continue? ", parser=parsers.parse_bool)
-    assert result.is_success()
-    assert result.value_or(False) == True
-
-# Test validation functions
-result = validate_age(42)
-assert assert_maybe_success(result, 42)
-```
-
-For more information, see the [Testing with Valid8r](docs/user_guide/testing.rst) guide.
-
-## Development
-
-This project uses Poetry for dependency management and Tox for testing.
-
-### Setup
-
-```bash
-# Install Poetry
-curl -sSL https://install.python-poetry.org | python3 -
-
-# Install dependencies
-poetry install
-```
-
-### Running Tests
-
-```bash
-# Run all tests
-poetry run tox
-
-# Run BDD tests
-poetry run tox -e bdd
-```
-
-## License
-MIT
-