valid8r 0.2.0__tar.gz

valid8r-0.2.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: valid8r
+Version: 0.2.0
+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
+

valid8r-0.2.0/README.md

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

valid8r-0.2.0/pyproject.toml

@@ -0,0 +1,190 @@
+[tool.poetry]
+name = "valid8r"
+version = "0.2.0"
+description = "Clean, flexible input validation for Python applications"
+authors = ["Mike Lane <mikelane@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+repository = "https://github.com/mikelane/valid8r"
+keywords = ["validation", "input", "cli", "maybe-monad"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+packages = [{include = "valid8r"}]
+include = [{ path = "valid8r/py.typed", format = "wheel" }]
+
+[tool.poetry.dependencies]
+python = ">=3.11,<4.0"
+email-validator = "^2.3.0"
+pydantic = ">=2.0"
+pydantic-core = "^2.27.0"
+# No external dependencies for core functionality
+uuid-utils = "^0.11.0"
+
+[tool.poetry.group.dev.dependencies]
+fastapi = "^0.119.0"
+httpx = "^0.28.1"
+livereload = "^2.7.1"
+mypy = "^1.17.1"
+pre-commit = "^4.3.0"
+uvicorn = "^0.37.0"
+
+[tool.poetry.group.lint.dependencies]
+isort = "^6.0.1"
+ruff = "^0.12.8"
+
+[tool.poetry.group.docs.dependencies]
+myst-parser = "^4.0.1"
+sphinx = "^8.2.3"
+sphinx-autoapi = "^3.6.0"
+sphinx-autodoc-typehints = "^3.2.0"
+sphinx-copybutton = "^0.5.2"
+sphinx-rtd-theme = "^3.0.2"
+
+
+[tool.poetry.group.test.dependencies]
+behave = "^1.3.0"
+coverage = "^7.10.2"
+pytest = "^8.4.1"
+pytest-cov = "^6.2.1"
+pytest-mock = "^3.14.1"
+pytest-sugar = "^1.0.0"
+tox = "^4.28.4"
+
+[tool.poetry.scripts]
+docs-build = "scripts.docs:build"
+docs-serve = "scripts.docs:serve"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["it_*.py", "test_*.py"]
+python_functions = ["it_*"]
+python_classes = ["Describe[A-Z]*"]
+addopts = ["-s", "-ra", "-q", "-vv"]
+
+
+[tool.isort]
+line_length = 120
+profile = "black"
+multi_line_output = 3
+force_grid_wrap = 2
+include_trailing_comma = true
+use_parentheses = true
+ensure_newline_before_comments = true
+
+known_first_party = ["valid8r"]
+
+[tool.ruff]
+line-length = 120
+
+src = ["valid8r", "tests"]
+
+include = ["*.py"]
+
+exclude = [".git", ".venv", "__pycache__", "build", "dist"]
+
+target-version = "py311"
+
+respect-gitignore = true
+
+[tool.ruff.format]
+quote-style = "single"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812", # Ignore missing trailing commas (conflicts with ruff format)
+    "D203", # Don't require 1 blank line before class docstring
+    "D213", # Don't require multiline docstring to start at the second line
+    "EM101", # Allow raw strings as error messages
+    "ISC001", # Ignore implicitly concatenated strings (conflicts with ruff format)
+    "PLR0911", # I don't agree that there could be too many return statements.
+    "T201", # This module needs to print, so don't prevent it
+    "TRY003", # Don't be so strict about the length of exception messages or whatever this is
+]
+
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.lint.per-file-ignores]
+"test_*.py" = [
+    "D100", # Don't require module docstrings
+    "D101", # Don't require class docstrings
+    "D102", # Don't require method docstrings
+    "FBT001", # Allow tests to use boolean arguments
+    "PLR2004", # Don't prevent magic values in tests
+    "S101", # Don't prevent asserts
+]
+"tests/*" = [
+    "D100", # Don't require module docstrings in tests
+    "D101", # Don't require class docstrings in tests
+    "D102", # Don't require method docstrings in tests
+    "D103", # Don't require function docstrings in tests
+    "D104", # Don't require init docstrings in tests
+    "PGH003", # Allow tests to casually ignore mypy complaints about incorrect types
+    "PLC0415", # Allow imports inside test functions
+    "PLR0913", # Allow tests to have as many arguments as we want
+]
+"tests/bdd/steps/*" = [
+    "S101", # Allow asserts in behave tests
+]
+"tests/_utils/check_coverage.py" = ["T201"] # allow print function in the scripts
+"scripts/*" = ["T201"] # allow print function in the scripts
+"smoke_test.py" = ["S101"] # allow asserts in smoke test
+"conftest.py" = ["D100"] # Don't require module docstrings in conftest
+"__init__.py" = ["F401"] # allow unused imports in __init__.py
+"valid8r/core/parsers.py" = [
+    "C901", # Allow complex functions in parsers
+    "D413", # Allow missing blank line after last docstring section
+    "FBT001", # Allow boolean positional arguments
+    "FBT002", # Allow boolean default arguments
+    "PLR2004", # Allow magic values for network constants
+]
+
+[tool.ruff.lint.isort]
+required-imports = ["from __future__ import annotations"]
+known-first-party = ["valid8r"]
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "single"
+multiline-quotes = "double"
+docstring-quotes = "double"
+
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+
+[[tool.mypy.overrides]]
+module = [
+  "pytest",
+  "pytest.*",
+  "pytest_mock",
+  "pytest_mock.*",
+  "behave",
+  "behave.*",
+  "sphinx",
+  "sphinx.*",
+]
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = [
+  "tests.*",
+  "docs.*",
+]
+ignore_errors = true

valid8r-0.2.0/valid8r/__init__.py

@@ -0,0 +1,27 @@
+# valid8r/__init__.py
+"""Valid8r: A clean, flexible input validation library for Python."""
+
+from __future__ import annotations
+
+__version__ = '0.1.0'
+
+# Public API re-exports for concise imports
+# Modules
+from . import prompt
+from .core import (
+    combinators,
+    parsers,
+    validators,
+)
+from .core.maybe import Maybe
+
+# Types
+
+__all__ = [
+    'Maybe',
+    '__version__',
+    'combinators',
+    'parsers',
+    'prompt',
+    'validators',
+]

valid8r-0.2.0/valid8r/core/__init__.py

@@ -0,0 +1,28 @@
+# valid8r/core/__init__.py
+"""Core validation components."""
+
+from __future__ import annotations
+
+from valid8r.core.parsers import (
+    EmailAddress,
+    UrlParts,
+    parse_cidr,
+    parse_email,
+    parse_ip,
+    parse_ipv4,
+    parse_ipv6,
+    parse_url,
+)
+
+__all__ = [
+    'EmailAddress',
+    'UrlParts',
+    'parse_cidr',
+    'parse_email',
+    'parse_ip',
+    # existing exports may be defined elsewhere; explicitly expose IP helpers
+    'parse_ipv4',
+    'parse_ipv6',
+    # URL/Email helpers
+    'parse_url',
+]

valid8r-0.2.0/valid8r/core/combinators.py

@@ -0,0 +1,89 @@
+"""Combinators for creating complex validation rules.
+
+This module provides functions to combine validators using logical operations like AND, OR, and NOT.
+These combinators allow for creation of complex validation chains.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    TypeVar,
+)
+
+from valid8r.core.maybe import (
+    Maybe,
+    Success,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar('T')
+
+
+def and_then(first: Callable[[T], Maybe[T]], second: Callable[[T], Maybe[T]]) -> Callable[[T], Maybe[T]]:
+    """Combine two validators with logical AND (both must succeed).
+
+    Args:
+        first: The first validator function
+        second: The second validator function
+
+    Returns:
+        A new validator function that passes only if both validators pass
+
+    """
+
+    def combined_validator(value: T) -> Maybe[T]:
+        result = first(value)
+        match result:
+            case Success(value):
+                return second(value)
+            case _:
+                return result
+
+    return combined_validator
+
+
+def or_else(first: Callable[[T], Maybe[T]], second: Callable[[T], Maybe[T]]) -> Callable[[T], Maybe[T]]:
+    """Combine two validators with logical OR (either can succeed).
+
+    Args:
+        first: The first validator function
+        second: The second validator function
+
+    Returns:
+        A new validator function that passes if either validator passes
+
+    """
+
+    def combined_validator(value: T) -> Maybe[T]:
+        result = first(value)
+        match result:
+            case Success(value):
+                return result
+            case _:
+                return second(value)
+
+    return combined_validator
+
+
+def not_validator(validator: Callable[[T], Maybe[T]], error_message: str) -> Callable[[T], Maybe[T]]:
+    """Negate a validator (success becomes failure and vice versa).
+
+    Args:
+        validator: The validator function to negate
+        error_message: Error message for when the negated validator fails
+
+    Returns:
+        A new validator function that passes if the original validator fails
+
+    """
+
+    def negated_validator(value: T) -> Maybe[T]:
+        result = validator(value)
+        if result.is_failure():
+            return Maybe.success(value)
+        return Maybe.failure(error_message)
+
+    return negated_validator