zodic 0.1.0

A TypeScript Zod-inspired validation library for Python with excellent type safety and developer experience

zodic

A TypeScript Zod-inspired validation library for Python with excellent type safety and developer experience.

Features

• Type-safe validation with excellent IDE support and autocompletion
• Intuitive chainable API for building complex schemas
• Lightning-fast performance - 2M+ operations/second
• Comprehensive error reporting with detailed nested paths
• Zero dependencies - lightweight and fast imports
• Extensible architecture for custom validators
• Framework agnostic - works with FastAPI, Django, Flask, etc.

Installation

pip install zodic

Requires Python 3.9+

Quick Start

import zodic as z

# Basic validation
name_schema = z.string().min(1).max(100)
name = name_schema.parse("Alice")  # Returns "Alice"

# Object validation  
user_schema = z.object({
    "name": z.string().min(1),
    "age": z.number().int().min(0).max(120),
    "email": z.string().optional(),
    "is_active": z.boolean().default(True)
})

# Parse and validate data
user_data = {
    "name": "Alice Johnson", 
    "age": 30,
    "email": "[e-mail]"
}

user = user_schema.parse(user_data)
# Returns: {"name": "Alice Johnson", "age": 30, "email": "[e-mail]", "is_active": True}

Documentation

Basic Types

import zodic as z

# Primitives
z.string()     # str
z.number()     # int | float
z.boolean()    # bool  
z.none()       # None

# String validation
z.string().min(5)              # Minimum length
z.string().max(100)            # Maximum length  
z.string().length(10)          # Exact length

# Number validation
z.number().int()               # Must be integer
z.number().positive()          # > 0
z.number().min(0).max(100)     # Range validation

# Collections
z.array(z.string())            # List[str]
z.object({"name": z.string()}) # Dict with typed fields

Advanced Features

# Optional and nullable
z.string().optional()          # str | None (can be missing)
z.string().nullable()          # str | None (can be null)
z.string().default("hello")    # Default value if missing

# Transformations
z.string().transform(str.upper)           # Transform after validation
z.number().transform(lambda x: x * 2)     # Custom transformations

# Custom validation
z.string().refine(
    lambda x: x.startswith("prefix_"),
    "Must start with 'prefix_'"
)

# Union types  
z.union([z.string(), z.number()])         # str | int | float

Error Handling

# Parse (throws ZodError on failure)
try:
    result = z.string().parse(123)
except z.ZodError as e:
    print(e)  # "Validation error at root: Expected string, received int"

# Safe parse (returns result object)
result = z.string().safe_parse(123)
if result["success"]:
    print(result["data"])     # Parsed value
else:
    print(result["error"])    # ZodError object

Real-World Example

# API request validation
api_schema = z.object({
    "user": z.object({
        "name": z.string().min(1).max(100),
        "email": z.string().refine(lambda x: "@" in x, "Invalid email"),
        "age": z.number().int().min(13).max(120)
    }),
    "preferences": z.object({
        "theme": z.union([z.literal("light"), z.literal("dark")]).default("light"),
        "notifications": z.boolean().default(True)
    }).optional(),
    "tags": z.array(z.string()).max(10).default([])
})

# Validate incoming request
try:
    validated_data = api_schema.parse(request_data)
    # Process validated data...
except z.ZodError as e:
    return {"error": str(e)}, 400

Why Zodic?

vs Pydantic

• Lighter weight - Zero dependencies, 10x faster imports
• Better API - More intuitive, chainable methods inspired by Zod
• Better errors - Detailed path reporting for nested validation

vs marshmallow

• Type safety - Full integration with Python type hints
• Performance - Significantly faster validation
• Modern API - Designed for Python 3.8+ with latest features

vs cerberus

• Developer experience - Better error messages and IDE support
• Composability - Easy to build complex schemas from simple parts
• Type system - First-class type safety and inference

Performance

Zodic is designed for speed:

String validation:  2,000,000+ ops/sec
Number validation:  1,600,000+ ops/sec  
Object validation:    297,000+ ops/sec

Development

# Clone and install
git clone https://github.com/Seyamalam/zodic.git
cd zodic
pip install -e ".[dev]"

# Run tests
pytest

# Run type checking  
mypy zodic

# Format code
black zodic tests
isort zodic tests

Contributing

We welcome contributions! Please see our Contributing Guide for details.

• Bug reports: GitHub Issues
• Feature requests: GitHub Issues
• Pull requests: GitHub PRs

License

MIT License - see LICENSE file for details.

Acknowledgments

Inspired by Zod - the amazing TypeScript validation library that set the standard for developer experience in schema validation.

Roadmap

• v0.1: Core validation with basic types (CURRENT)
• v0.2: Enhanced string/number validators (email, URL, regex, etc.)
• v0.3: Advanced features (recursive schemas, conditional validation)
• v0.4: Framework integrations (FastAPI, Django, Flask)
• v1.0: Production ready with full Zod feature parity

---

Star us on GitHub if Zodic helps you build better Python applications!