Pydantic Airtable¶

The most intuitive way to integrate Pydantic models with Airtable

✨ Transform Your Airtable Integration¶

Turn your Pydantic models into fully-functional Airtable integrations with just 8 lines of code:

from pydantic_airtable import airtable_model, configure_from_env
from pydantic import BaseModel

configure_from_env()  # Auto-loads from .env

@airtable_model(table_name="Users")
class User(BaseModel):
    name: str                    # Auto-detects as SINGLE_LINE_TEXT
    email: str                   # Auto-detects as EMAIL  
    age: Optional[int] = None    # Auto-detects as NUMBER
    is_active: bool = True       # Auto-detects as CHECKBOX

# That's it! Now you have full CRUD operations
user = User.create(name="Alice", email="alice@example.com", age=28)
users = User.all()
alice = User.find_by(name="Alice")

🌟 Key Features¶

Type Detection

Auto-detects field types from naming patterns. email: str automatically becomes an EMAIL field.
Zero Config

Works with just environment variables. Set your token and base ID, and you're ready to go.
Table Creation

Creates Airtable tables directly from your model definitions with User.create_table().
Intuitive CRUD

Simple, predictable methods: User.create(), User.all(), user.save(), user.delete().
Advanced Filtering

Clean query syntax with User.find_by(is_active=True) and formula support.
Batch Operations

Efficient bulk operations with User.bulk_create([...]) for multiple records.

🚀 Quick Start¶

1. Install the package¶

pip install pydantic-airtable

2. Set up your credentials¶

Create a .env file:

AIRTABLE_ACCESS_TOKEN=pat_your_personal_access_token
AIRTABLE_BASE_ID=app_your_base_id

3. Define your model¶

from pydantic_airtable import airtable_model, configure_from_env
from pydantic import BaseModel
from typing import Optional

configure_from_env()

@airtable_model(table_name="Users")
class User(BaseModel):
    name: str
    email: str
    age: Optional[int] = None

4. Start using it!¶

# Create a table (if it doesn't exist)
User.create_table()

# Create a record
user = User.create(name="Alice", email="alice@example.com", age=28)

# Query records
all_users = User.all()
active_users = User.find_by(is_active=True)

# Update a record
user.age = 29
user.save()

📚 Documentation Sections¶

Section	Description
Getting Started	Installation, setup, and your first model
User Guide	Detailed guides for all features
Advanced	Custom configurations and best practices
Examples	Real-world example applications
API Reference	Complete API documentation

🧠 Field Type Detection¶

The library automatically detects Airtable field types based on your field names:

Python Code	Detected Type	Reason
`email: str`	EMAIL	Field name contains "email"
`phone: str`	PHONE	Field name contains "phone"
`website: str`	URL	Field name contains "website"
`description: str`	LONG_TEXT	Field name suggests long text
`price: float`	CURRENCY	Field name suggests money
`completion_rate: float`	PERCENT	Field name suggests percentage
`is_active: bool`	CHECKBOX	Boolean type
`created_at: datetime`	DATETIME	DateTime type
`Priority: Enum`	SELECT	Enum type
`tags: List[str]`	MULTI_SELECT	List type

💡 Why Pydantic Airtable?¶

Type Safety: Full Pydantic validation with Airtable persistence
Intuitive API: Works exactly like you'd expect
Field Type Defaults: Reduces schema guessing
Production Ready: Error handling, retries, and batch operations
Well Documented: Comprehensive guides and examples

🔗 Links¶

Made with ❤️ for the Python community