PyValidX

Custom field validation for Python with Pydantic

PyValidX is a powerful and flexible validation library built on top of Pydantic that provides a rich set of validators for common use cases while allowing you to create custom validation logic with ease.

✨ Features

• 🎯 Easy to Use: Simple validation with clear, readable syntax
• 🔧 Flexible: Support for custom validators and conditional validation
• 📝 Type Safe: Built on Pydantic with full type annotation support
• 🌍 Comprehensive: Wide range of built-in validators for strings, numbers, dates, and more
• 🚀 Performance: Efficient validation with minimal overhead
• 📖 Well Documented: Comprehensive documentation with examples

🚀 Quick Example

from pyvalidx import ValidatedModel, field_validated
from pyvalidx.core import is_required
from pyvalidx.string import is_email, is_strong_password
from pyvalidx.numeric import min_value

class User(ValidatedModel):
    name: str = field_validated(is_required())
    email: str = field_validated(is_required(), is_email())
    password: str = field_validated(is_required(), is_strong_password())
    age: int = field_validated(is_required(), min_value(18))

# This will validate automatically
try:
    user = User(
        name="John Doe",
        email="john@example.com", 
        password="SecurePass123!",
        age=25
    )
    print("User created successfully!")
except ValidationException as e:
    print(f"Validation failed: {e.to_dict()}")

📦 Installation

Install PyValidX using pip:

pip install pyvalidx

Or with poetry:

poetry add pyvalidx

🔌 FastAPI Integration

PyValidX works seamlessly with FastAPI for robust API validation:

from fastapi import FastAPI
from fastapi.responses import JSONResponse
from pyvalidx import ValidatedModel, ValidationException, field_validated
from pyvalidx.core import is_required
from pyvalidx.string import is_email, is_strong_password

app = FastAPI()

# Configure global exception handler
@app.exception_handler(ValidationException)
async def validation_exception_handler(request, exc: ValidationException):
    return JSONResponse(
        status_code=400,
        content={"error": "Validation failed", "details": exc.to_dict()}
    )

# Define your DTO
class CreateUserDto(ValidatedModel):
    username: str = field_validated(is_required())
    email: str = field_validated(is_required(), is_email())
    password: str = field_validated(is_required(), is_strong_password())

# Use it in your endpoint
@app.post("/users")
async def create_user(payload: CreateUserDto):
    # Validation happens automatically!
    return {"message": "User created", "username": payload.username}

Error Response Example:

{
  "error": "Validation failed",
  "details": {
    "email": ["Invalid email format"],
    "password": ["Password must be strong"]
  }
}

🎯 Core Concepts

Validators

Validators are functions that check if a value meets certain criteria. They return True if valid, False otherwise.

ValidatedModel

A Pydantic model that automatically runs custom validators on initialization and provides error handling.

field_validated

A field decorator that attaches validators to model fields.

ValidationException

A custom exception that provides structured error information when validation fails.

📚 Available Validators

Core Validators

• is_required() - Ensures field is not None, empty string, or empty list
• min_length() - Minimum string/list length
• max_length() - Maximum string/list length
• same_as() - Field must match another field
• required_if() - Conditional requirement based on another field

String Validators

• is_email() - Valid email format
• is_strong_password() - Strong password requirements
• matches_regex() - Custom regex pattern matching
• no_whitespace() - No spaces allowed
• is_phone() - Colombian phone number format

Numeric Validators

• is_positive() - Positive numbers only
• is_integer() - Integer type validation
• is_float() - Float type validation
• min_value() - Minimum numeric value
• max_value() - Maximum numeric value

Date Validators

• is_date() - Valid date format
• is_future_date() - Date must be in the future
• is_past_date() - Date must be in the past
• is_today() - Date must be today

Type Validators

• is_dict() - Dictionary type validation
• is_list() - List type validation
• is_boolean() - Boolean type validation
• is_in() - Value must be in specified choices

🔗 Quick Links

• Getting Started - Install and set up PyValidX
• Validators - Explore all available validators
• API Reference - Complete API documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Harrison Alonso Arroyave Gaviria

• GitHub: @harrison-gaviria
• Email: harrisonarroyaveg@gmail.com