Valid8r

Tutorials

  • Build a CLI in 10 Minutes
    • Step 1: Setup (1 minute)
    • Step 2: Basic Structure (2 minutes)
    • Step 3: Add Input Validation (2 minutes)
    • Step 4: Interactive Prompts (2 minutes)
    • Step 5: Email Notifications (2 minutes)
    • Step 6: Write a Test (1 minute)
    • What We Learned
    • Key Concepts
      • The Maybe Pattern
      • Chaining Validators
      • Interactive Prompts
    • Next Steps
    • Complete Code

User Guide

  • Getting Started
    • Installation
    • Basic Concepts
    • Your First Validation
    • Using Success and Failure Types
    • Chaining Validators
    • Prompting for User Input
    • Next Steps
  • Understanding the Maybe Monad
    • Basic Concepts
    • Creating Maybe Instances
    • Checking Maybe Status
    • Extracting Values and Errors
    • Accessing Structured Error Details
    • Pattern Matching with Match Statement
    • Advanced Pattern Matching
    • Chaining Operations with bind
    • Transforming Values with map
    • Why Use the Maybe Monad?
    • Advanced Usage
  • Parsers
    • Basic Usage
    • Available Parsers
    • Security Considerations
      • Parser Input Limits
      • Integer Parser
      • Float Parser
      • Boolean Parser
      • Date Parser
      • DateTime Parser (Timezone-Aware)
      • Timedelta Parser (Duration)
      • Complex Number Parser
      • Decimal Parser
      • Enum Parser
      • UUID Parser
    • Collection Type Parsing
    • IP Address and CIDR Parsers
    • URL Parser with Structured Results
    • Email Parser with Structured Results
    • Phone Number Parser (North American)
    • Creating Custom Parsers
      • Using the create_parser Function
      • Using the make_parser Decorator
    • Validated Parsers
    • Error Handling
    • Common Parser Features
    • Combining Parsers with Validators
    • Parser Function Errors vs Validation Logic
    • Parsing with Validation
    • Parser Limitations and Edge Cases
      • Integer Parser
      • Float Parser
      • Boolean Parser
      • Date Parser
      • Complex Parser
      • Enum Parser
  • Type-Based Parsers
    • Overview
    • Basic Usage
      • Simple Types
      • Optional Types
    • Collection Types
      • Lists
      • Dictionaries
      • Sets
    • Union Types
    • Literal Types
    • Enum Types
    • Annotated Types with Validators
    • Advanced Usage
      • Nested Complex Types
      • Reusable Type Aliases
    • Security Considerations
      • DoS Protection
      • Input Validation Best Practices
    • Limitations
      • Unsupported Types
      • Error Messages
    • See Also
  • Validators
    • Basic Usage
    • Built-in Validators
      • Minimum Validator
      • Maximum Validator
      • Between Validator
      • Length Validator
      • Predicate Validator
      • Matches Regex Validator
      • In Set Validator
      • Non-Empty String Validator
      • Unique Items Validator
      • Subset Of Validator
      • Superset Of Validator
      • Is Sorted Validator
    • Combining Validators
    • Error Messages in Combined Validators
    • Custom Validators
    • Use with Parsers
    • Processing Validation Results
    • Validator Limitations and Edge Cases
  • Schema Validation
    • Overview
    • Basic Usage
    • Field Definition
    • Error Accumulation
    • Field Path Tracking
    • Nested Schemas
    • Required vs Optional Fields
    • Strict Mode
    • Combining Parsers and Validators
    • Validation Error Structure
    • Type Preservation
    • Use Cases
      • API Request Validation
      • Configuration Validation
      • Form Data Validation
    • Best Practices
    • See Also
  • Async Validation
    • Overview
    • When to Use Async Validation
    • Quick Start
      • Basic Async Validator
    • Schema Async Validation
      • Method Signature
      • Basic Usage
      • Multiple Async Validators
      • Execution Order
    • Timeout Support
      • Setting Timeouts
      • Handling Timeouts
      • Timeout Best Practices
    • Error Handling
      • Error Structure
      • Example Output
      • Handling Exceptions in Validators
    • Common Patterns
      • Database Uniqueness Check
      • External API Validation
      • Geolocation Validation
    • Mixing Sync and Async Validators
      • Example
      • Performance Considerations
    • Performance Optimization
      • Concurrent Field Validation
      • Caching Results
      • Rate Limiting with RateLimitedValidator
      • Batch Validation with parallel_validate
      • Timeout Handling with TimeoutValidator
      • TTL-Based Caching with CachedValidator
      • Retry Logic with Exponential Backoff
        • RetryingValidator Parameters
        • Retry Behavior
        • Example: Tracking Retry Metrics
        • Best Practices for Retry Logic
    • Testing Async Validators
      • Unit Testing
      • Mocking Async Dependencies
      • Integration Testing
    • Migration from Sync to Async
      • Step 1: Keep Sync Validators
      • Step 2: Add Async Validators
      • Step 3: Gradually Replace
      • Backward Compatibility
    • See Also
  • Error Handling
    • Why Structured Errors?
    • ValidationError Dataclass
    • ErrorCode Constants
    • Creating Failure with ValidationError
    • Accessing Structured Error Information
    • Programmatic Error Handling
    • Converting Errors to JSON
    • Pattern Matching with Structured Errors
    • Multi-Field Validation with Paths
    • Backward Compatibility
    • Migration Guide
    • Best Practices
    • Next Steps
  • User Input Prompting
    • Basic Usage
    • The ask Function
    • Default Values
    • Error Handling and Retries
    • Custom Error Messages
    • Processing User Input
    • Common Patterns
      • Password Input
      • Confirmation Prompts
      • Menu Selection
    • Interactive Applications
    • Best Practices
    • Limitations
  • Advanced Usage
    • Complex Validation Chains
    • Custom Validator Factories
    • Creating a Domain-Specific Validation Library
    • Working with External Data
    • Integration with Web Frameworks
    • Advanced Monadic Patterns
    • Asynchronous Validation
    • Testing Your Validators
    • Performance Considerations
    • Production Security Patterns
  • Library Comparison Guide
    • Quick Reference: When to Choose Each Library
    • Feature Comparison Matrix
    • Detailed Comparisons
      • valid8r vs Pydantic
      • valid8r vs marshmallow
      • valid8r vs cerberus
    • Performance Benchmarks
      • Summary
      • When Performance Matters
    • Migration Guides
      • From Pydantic to valid8r
      • From marshmallow to valid8r
      • From cerberus to valid8r
    • Hybrid Approaches
      • Using valid8r with Pydantic (Recommended)
      • Using valid8r Parsers in Pydantic Models
    • Frequently Asked Questions
      • Why another validation library?
      • Is valid8r faster than Pydantic?
      • Can I use valid8r with FastAPI?
      • What makes valid8r different?
      • Should I migrate from Pydantic?
      • Does valid8r support async validation?
      • Can I create custom parsers?
      • Is valid8r production-ready?
      • What’s the learning curve?
    • Summary: Choosing the Right Library
    • Additional Resources

Guides

  • Choosing a Validation Approach
    • Decision Flowchart
      • Quick Decision Tree
    • Parser Chaining
      • When to Use
      • Example
      • Characteristics
    • Schema Validation
      • When to Use
      • Example
      • Characteristics
    • from_type() (Type-Based Parsing)
      • When to Use
      • Example
      • Characteristics
    • Comparison Table
    • When to Use Each Approach
      • Use Parser Chaining When:
      • Use Schema Validation When:
      • Use from_type() When:
    • Migration Guide
      • From Parser Chaining to Schema
      • From Schema to from_type()
      • From from_type() to Parser Chaining
    • Frequently Asked Questions
      • Which approach is fastest?
      • Can I combine approaches?
      • How do I validate nested objects?
      • What if I need custom error messages?
      • Should I use Schema or Pydantic for APIs?
    • Summary
  • Async Validators Guide
    • Overview
    • Key Features
    • Installation
    • Database Validators (MVP)
      • unique_in_db - Uniqueness Validation
      • exists_in_db - Foreign Key Validation
    • Usage Patterns
      • Concurrent Validation
      • Integration with Async Frameworks
      • Error Handling
    • Database Compatibility
    • Performance Considerations
    • Validator Composition
      • all_of - Parallel AND Composition
      • any_of - Parallel OR Composition
      • sequence - Sequential Composition
      • Mixed Composition
      • Performance Comparison
    • Validator Wrappers
      • TimeoutValidator
      • CachedValidator
      • Batch Validation with max_concurrency
    • Future Features
    • Examples
    • Troubleshooting
      • “Database error: connection refused”
      • “Query takes too long”
      • “AttributeError: ‘Connection’ object has no attribute ‘execute’”
    • Related Documentation
    • Support
  • FastAPI Async Validation Guide
    • Table of Contents
    • Prerequisites
    • Installation
    • Quick Start
    • Request Body Validation
      • Basic Request Body Validation
      • Invalid Requests Are Rejected Automatically
      • Clients Receive Clear Error Messages
      • Valid Requests Proceed to Handler
    • Query Parameter Validation
      • Basic Query Parameter Validation
      • Missing Parameters Are Handled Gracefully
      • Invalid Parameter Values Are Rejected
      • Error Messages Explain What Went Wrong
    • Request Header Validation
      • Basic Header Validation
      • Authentication Token Verification
      • Custom Header Format Validation
      • Unauthorized Requests Are Rejected Appropriately
    • Error Handling
      • Returning Appropriate HTTP Status Codes
      • Structured Error Responses
      • Clients Receive Actionable Feedback
    • Performance Considerations
      • When Is Async Validation Beneficial?
      • Synchronous vs Async Validation Performance
      • Performance Comparison
      • Best Practices for Performance
      • Making Informed Architecture Decisions
    • Complete Example
    • Next Steps

Examples

  • Basic Examples
    • Basic Parsing
    • Basic Validation
    • Combining Parsing and Validation
    • User Input with Validation
    • Form Validation
    • Configuration Validation
    • Data Structure Validation
    • IP Address parsing
  • Chaining Validators
    • Basic Validator Chaining
    • Using Logical OR with the | Operator
    • Negating Validators with the ~ Operator
    • Complex Validation Chains
    • Validation Priority and Short-Circuit Behavior
    • Validator Composition for Form Validation
    • Validator Factory Functions
    • Real-world Example: Data Pipeline Validation
  • Custom Validators
    • Creating a Simple Custom Validator
    • Creating a Validator Factory Function
    • String Validation Examples
    • Date and Time Validators
    • Collection Validators
    • Custom Domain-Specific Validators
    • Creating Stateful Validators
  • Interactive Prompts
    • Basic User Input
    • Using Default Values
    • Controlling Retry Behavior
    • Custom Error Messages
    • Building a Menu System
    • Custom Input Masking
    • Multi-stage Input Flow
    • Command-line Arguments with Fallback to Prompts
    • Interactive Data Entry Form
  • FastAPI + Pydantic Integration
    • Installation
    • Overview
    • Example 1: Pattern Matching with Field Validators
    • Example 2: Advanced Pattern Matching
    • Example 3: Batch Validation with Pattern Matching
    • Example 4: Multi-Field Pattern Matching
    • Example 5: Chained Validation with Pattern Matching
    • Example 6: Custom Validation with Rich Error Context
    • Example 7: Production-Ready FastAPI Integration
      • Installation for Production Example
    • Running the Example
    • Example Requests
    • Key Takeaways
    • Why Pattern Matching?
  • Environment Variables Integration
    • Overview
    • Installation
    • Why Use Valid8r for Environment Configuration?
    • 12-Factor App Principles
    • Basic Usage
      • Define a Configuration Schema
      • Load and Validate Configuration
    • Schema-Based vs Dataclass Approach
      • Schema-Based (Recommended)
      • Dataclass-Based (Alternative)
    • Nested Configuration
    • Best Practices
      • Naming Conventions
      • Prefixes for Multi-Service Applications
      • Defaults and Required Fields
      • Validation with Chained Parsers
    • Example: FastAPI Application
    • Example: Docker Deployment
      • Docker and Docker Compose Integration
      • Kubernetes ConfigMap and Secrets
    • Example: .env File Support
    • Common Patterns and Use Cases
      • Pattern: Configuration Validation on Startup
      • Pattern: Environment-Specific Defaults
      • Pattern: Feature Flags
      • Pattern: Complex List Parsing
    • Troubleshooting
      • Common Error Messages
      • Debugging Configuration
      • Testing Configuration Loading
    • See Also
    • Related Examples

Security

  • Security Overview
    • Quick Links
    • Security Boundaries
    • Defense in Depth Strategy
    • Parser Input Limits
    • Example: Secure Validation Pattern
    • DoS Protection
    • Recent Security Fixes
      • v0.9.1 - Phone Parser DoS Protection (November 2025)
    • Production Deployment
    • Reporting Security Issues
    • Additional Resources
  • Production Deployment Security Guide
    • Table of Contents
    • Defense in Depth Strategy
    • Framework-Specific Guides
      • Flask
        • Basic Setup
        • Input Validation Pattern
        • Rate Limiting
        • Error Logging
      • Django
        • Settings Configuration
        • View-Based Validation
        • Form Validation
      • FastAPI
        • Application Configuration
        • Pydantic Integration
        • Manual Validation Pattern
    • Rate Limiting
      • Redis-Based Rate Limiting (Production)
      • Per-User Rate Limiting
    • Monitoring and Logging
      • Structured Logging
      • Metrics Collection
    • Security Testing
      • Integration Tests
      • Load Testing
    • Best Practices Checklist
    • Additional Resources
  • Secure Parser Development Guidelines
    • Table of Contents
    • Overview
    • DoS Prevention
      • Principle: Early Length Guards
      • Maximum Input Lengths
      • Performance Threshold
    • ReDoS Prevention
      • Overview of ReDoS Attacks
      • Automated ReDoS Detection
      • Vulnerable Pattern Examples
      • Safe Regex Patterns in valid8r
      • CI/CD Integration
      • Testing for ReDoS
    • Input Validation Order
    • Testing Requirements
      • Correctness Tests
      • Security Tests
      • Coverage Requirements
    • Error Messages
      • User-Facing Messages
      • Docstring Documentation
    • Common Patterns
      • Pattern 1: External Library Validation
      • Pattern 2: Regex Operations
      • Pattern 3: Multi-Stage Parsing
    • References
      • Security Standards
      • Project References
      • Testing
    • Checklist for New Parsers
    • Maintenance
  • Security Policy
    • Supported Versions
    • Reporting a Vulnerability
      • 1. Do Not Open a Public Issue
      • 2. Report Privately
      • Email Template
      • 3. What to Expect
    • Security Update Process
    • Security Best Practices
      • Input Validation
      • Dependencies
      • Framework Configuration
    • Recent Security Fixes
      • v0.9.1 - Phone Parser DoS Protection (November 2025)
    • Scope
    • Security Resources
    • Contact

API Reference

  • API Reference
    • valid8r
      • Submodules
        • valid8r.async_validators
        • valid8r.core
        • valid8r.integrations
        • valid8r.prompt
        • valid8r.testing
      • Attributes
      • Classes
      • Functions
      • Package Contents
        • __version__
        • ErrorCode
        • ValidationError
        • Failure
        • Maybe
        • Success
        • EmailAddress
        • PhoneNumber
        • UrlParts
        • Field
        • Schema
        • from_type()

Development

  • Contributing to Valid8r
    • Setting Up Your Development Environment
    • Development Workflow
    • Code Style Guidelines
    • Testing Guidelines
    • Documentation Guidelines
    • Security Guidelines
    • Pull Request Process
    • Versioning Guidelines
    • Code of Conduct
    • Questions and Support
  • Testing Valid8r
    • Testing Framework
    • Directory Structure
    • Running Tests
    • Continuous Integration
    • Writing Unit Tests
    • Mocking
    • Writing BDD Tests
      • Feature Files
      • Step Implementations
    • Test Coverage
    • Debugging Tests
    • Testing Edge Cases
    • Creating Test Fixtures
    • Best Practices
  • Changelog
    • [Unreleased]
      • Added
    • [0.1.0] - 2025-02-26
      • Added
Valid8r
  • Overview: module code

All modules for which code is available

  • valid8r
    • valid8r.async_validators
    • valid8r.core.combinators
    • valid8r.core.errors
    • valid8r.core.maybe
    • valid8r.core.parsers
    • valid8r.core.schema
    • valid8r.core.type_adapters
    • valid8r.core.validators
    • valid8r.integrations.argparse
    • valid8r.integrations.click
    • valid8r.integrations.env
    • valid8r.integrations.pydantic
    • valid8r.integrations.typer
    • valid8r.prompt.basic
    • valid8r.prompt.io_provider
    • valid8r.testing.assertions
    • valid8r.testing.generators
    • valid8r.testing.mock_input

© Copyright 2026, Valid8r Contributors.

Built with Sphinx using a theme provided by Read the Docs.