pico-pydantic 0.2.1

Declarative, AOP-based Pydantic validation for pico-ioc managed components. Validates method arguments against BaseModel type hints before execution.

📦 pico-pydantic

Pico-Pydantic

Pico-Pydantic integrates Pico-IoC with Pydantic, enabling declarative, aspect-oriented validation of method arguments within your service layer.

It uses Pico-IoC's MethodInterceptor system to perform validation based on Pydantic BaseModel type hints before your method's business logic runs. This is the ideal tool for ensuring arguments passed between IoC-managed services are structurally correct.

🐍 Requires Python 3.11+ 🧩 Works with Pydantic 2.0+ 🔄 Supports async and sync methods 🧪 Enables unit testing of validation separate from business logic

---

🎯 Why pico-pydantic

While web frameworks handle validation at the HTTP boundary, business services often need to guarantee input integrity internally, especially when components are called from CLI tools, workers, or other services.

Pico-Pydantic provides:

• Declarative @validate boundaries for service methods.
• Aspect-Oriented Programming (AOP) for argument validation.
• Clear error handling with ValidationFailedError.
• Centralized validation logic, decoupled from the core service code.

Concern	Pico-IoC Default	pico-pydantic
Argument checking	Manual if/raise	Declarative @validate
Schema definition	None	Pydantic BaseModel type hints
Handling errors	Raw ValidationError	Wrapped ValidationFailedError

---

🧱 Core Features

• Method validation via @validate decorator.
• ValidationInterceptor for AOP execution.
• Seamless compatibility with BaseModel type annotations.
• Correct handling of positional, keyword, and default arguments.
• Zero coupling to web frameworks.

---

📦 Installation

pip install pico-pydantic

Also install pico-ioc and pydantic:

pip install pico-ioc pydantic

---

🚀 Quick Example

1. Define the Data Model and Service:

from pydantic import BaseModel, Field
from pico_ioc import component
from pico_pydantic import validate

class ItemData(BaseModel):
    name: str = Field(min_length=3)
    price: float = Field(gt=0)

@component
class InventoryService:
    @validate
    async def add_item(self, data: ItemData) -> dict:
        # Validation happens BEFORE this line
        print(f"Adding item: {data.name}")
        return data.model_dump()

2. Full Example: Initialization, Success, and Failure Handling

import asyncio
from pico_ioc import DictSource, configuration, init
from pico_pydantic import ValidationFailedError

# Define the base configuration (optional)
config = configuration(DictSource({}))

# 'components' is used here as the module containing InventoryService.
container = init(
    modules=["components"],
    config=config,
)

async def main():
    service = container.get(InventoryService)

    # --- Success: Validation Passes ---
    print("--- Testing Success ---")
    result = await service.add_item({"name": "Hammer", "price": 10.50})
    print(f"Result: {result}")
    
    # --- Failure: ValidationFailedError is thrown by the Interceptor ---
    print("\n--- Testing Failure ---")
    try:
        # Fails: 'price' is negative, violating Field(gt=0)
        await service.add_item({"name": "A", "price": -5})
    except ValidationFailedError as e:
        print(f"Validation failed for method '{e.method_name}'.")
        print(e.pydantic_error) # Shows the detailed Pydantic error
    
    await container.cleanup_all_async()
    container.shutdown()

if __name__ == "__main__":
    asyncio.run(main())

---

⚙️ How It Works

• The ValidationInterceptor is globally registered with Pico-IoC.
• When a method decorated with @validate is called:
• The interceptor captures the call arguments.
• It inspects the method signature for arguments with the BaseModel type hint.
• It calls BaseModel.model_validate(value) on the argument value.
• If validation fails, it wraps the error in ValidationFailedError and stops execution.
• If successful, call_next is executed, and the original method runs.

No manual checks inside the service method. Logic stays clean.

---

💡 Architecture Overview

                 ┌─────────────────────────────┐
                 │         Your App            │
                 │ (Service Layer)             │
                 └──────────────┬──────────────┘
                                │
                        @validate called
                                │
                 ┌──────────────▼───────────────┐
                 │          Pico-IoC            │
                 └──────────────┬───────────────┘
                                │
                    ValidationInterceptor (AOP)
                                │
                 ┌──────────────▼───────────────┐
                 │         pico-pydantic        │
                 │  Inspect & model_validate()  │
                 └──────────────┬───────────────┘
                                │
                             Pydantic 2.0+

---

🤖 Claude Code Skills

This project includes pre-designed skills for Claude Code, enabling AI-assisted development with pico-pydantic patterns.

Skill	Command	Description
Pico Validate	/pico-validate	Adds Pydantic validation to pico-ioc components
Pico Test Generator	/pico-tests	Generates tests for pico-framework components

See Skills documentation for full details and installation instructions.

---

📝 License

MIT