Pydantic Plugin: Verify, test and document Literal and Enum types support

[genro]

Context

Add explicit support for Literal and Enum types in the Pydantic plugin:

from typing import Literal
from enum import Enum

class Status(Enum):
    PENDING = "pending"
    ACTIVE = "active"
    CLOSED = "closed"

@sw
def process_action(
    action: Literal["create", "update", "delete"],
    status: Status
):
    ...

# Valid calls
sw("process_action")("create", Status.ACTIVE)
sw("process_action")("update", "pending")  # String coerced to enum

# Invalid - should raise ValidationError
sw("process_action")("invalid", Status.ACTIVE)

Implementation Plan

1. Verify Current Behavior

Pydantic v2 natively supports both Literal and Enum types. The plugin uses create_model() which should handle these automatically.

First step: Write quick tests to verify if it already works:

• Test Literal["a", "b", "c"] with valid and invalid values
• Test Enum with enum values and string coercion
• Document current behavior (pass/fail)

2. Handle Edge Cases

If basic support works, verify and handle:

String-to-Enum coercion:

• Pydantic v2 can coerce strings to Enum values by default
• Test: Status.PENDING and "pending" should both work
• Document this behavior clearly

Literal with mixed types:

• Literal[1, "one", True] - verify type checking
• Ensure error messages are clear when value doesn't match

Enum value vs name:

• Test if Pydantic accepts both Status.PENDING and the string "pending"
• Clarify in docs which forms are accepted

3. Add Comprehensive Tests

Add tests in tests/plugins/test_pydantic.py:

Literal tests:

• Valid literal value → success
• Invalid literal value → ValidationError
• Literal with multiple types
• Empty literal edge case

Enum tests:

• Enum member → success
• String matching enum value → success (coercion)
• Invalid string → ValidationError
• Mixed enum + other parameters

Combined:

• Function with both Literal and Enum parameters
• Verify error messages are helpful

4. Code Changes (if needed)

If tests reveal issues:

• Check if create_model() properly handles these types
• Verify type hint extraction doesn't strip Literal/Enum info
• Add special handling only if necessary

Most likely: no code changes needed, just tests + docs.

5. Documentation

Add to plugin documentation:

• Section on "Restricted Value Types"
• Example with Literal for fixed string choices
• Example with Enum for status/category fields
• Note about string-to-enum coercion behavior
• Best practices: when to use Literal vs Enum

Work Breakdown

• 🔍 Verification: Quick tests to check current behavior (~30 min)
• ✅ Tests: Comprehensive test suite (~100 lines)
• 📝 Documentation: Examples and usage guide
• 🔧 Code: Only if verification reveals issues (likely not needed)

Expected Outcome

Most likely: Already works, just needs tests and documentation to make it official.

Related Issues

• Pydantic Plugin: Implement Annotated with Field constraints support #27 - Annotated with Field (complementary: Annotated[Literal[...], Field(...)])
• Pydantic Plugin: Test, document and configure Union type coercion behavior #26 - Union types (related: Union[Literal["a"], Literal["b"]])
• Supersedes Pydantic Plugin: Add support for Literal and Enum types #15 (original request, closed in favor of this one)

Priority

Medium - Useful for APIs with restricted value sets. Likely low implementation cost (mostly testing).