Skip to content

User Guide

Welcome to the Duckdantic user guide! This guide covers all features in detail.

Guide Contents

Basic Usage

Learn the fundamentals of defining traits, checking satisfaction, and working with different object types.

Duck API

Master the ergonomic Duck API for seamless integration with Pydantic and natural isinstance usage.

Traits

Deep dive into trait specifications, field types, and trait composition.

Type Policies

Understand and customize type checking behavior with flexible policies.

Providers (Coming Soon)

Learn how Duckdantic normalizes fields from different object types.

Advanced Topics (Coming Soon)

Explore advanced features like custom matchers, performance optimization, and integration patterns.

Quick Navigation

- :material-play-circle: **New to Duckdantic?** *** Start with [Basic Usage](basic-usage.md) to learn the fundamentals - :material-duck: **Using Pydantic?** *** Jump to the [Duck API](duck-api.md) for the best experience - :material-cog: **Need Customization?** *** Check out [Type Policies](policies.md) for fine-tuning validation - :material-rocket: **Performance Critical?** *** Advanced optimization strategies coming soon

Common Tasks

Define a Simple Trait

from duckdantic import TraitSpec, FieldSpec

UserTrait = TraitSpec(
    name="User",
    fields=(
        FieldSpec("id", int, required=True),
        FieldSpec("name", str, required=True),
        FieldSpec("email", str, required=False),
    )
)

Check Object Satisfaction

from duckdantic import satisfies

user_data = {"id": 1, "name": "Alice"}
if satisfies(user_data, UserTrait):
    print("Valid user!")

Use Duck Types

from pydantic import BaseModel
from duckdantic import Duck

class User(BaseModel):
    id: int
    name: str

UserDuck = Duck(User)

# Natural isinstance usage
data = {"id": 2, "name": "Bob"}
assert isinstance(data, UserDuck)

Compose Traits

from duckdantic import union, intersect

# Accept either User or Guest
FlexibleTrait = union(UserTrait, GuestTrait)

# Require both User and Admin fields
AdminUserTrait = intersect(UserTrait, AdminTrait)

Best Practices

  1. Start Simple: Begin with basic traits and add complexity as needed
  2. Reuse Traits: Define traits once and reuse them across your application
  3. Use Duck API: When working with Pydantic, prefer the Duck API
  4. Cache Benefits: Let the built-in cache optimize performance
  5. Clear Names: Give traits descriptive names for better debugging

Getting Help