pydantic-fire 1.0.2

A Python package for defining type-safe, dynamic, and maintainable Firestore schemas using Pydantic

Pydantic Fire

A Python package for defining type-safe, dynamic, and maintainable Firestore schemas using Pydantic.

✨ Features

• Type Safety: Full type hints and Pydantic validation
• Firestore Integration: Seamless Google Cloud Firestore integration
• Sync Support: Full synchronous support for legacy Python applications
• Async Support: Full async/await support for modern Python applications
• Schema Management: Automatic schema validation and management
• Testing Tools: Built-in testing utilities and mock clients
• Documentation: Auto-generated documentation from your schemas
• Security Rules: Automatic Firestore security rules generation
• Performance: Optimized for high-performance applications

🚀 Quick Start

Installation

pip install pydantic-fire

Basic Usage

from pydantic_fire import Document, Collection, Field
from datetime import datetime

class UserDocument(Document):
    name: str = Field(..., description="User's full name")
    email: str = Field(..., description="User's email address")
    created_at: datetime = Field(default_factory=datetime.utcnow)
    is_active: bool = Field(default=True)

# Create a collection
UsersCollection = Collection(UserDocument, "users")

# Use with Firestore
from pydantic_fire import FirestoreGateway

gateway = FirestoreGateway()
user = UserDocument(name="John Doe", email="[e-mail]")

Async Usage

import asyncio
from pydantic_fire import AsyncFirestoreGateway

async def main():
    gateway = AsyncFirestoreGateway()
    user = UserDocument(name="Jane Doe", email="[e-mail]")
    result = await gateway.create_async(UsersCollection, "user456", user)

asyncio.run(main())

📖 Documentation

• Installation Guide
• Quick Start Tutorial
• API Reference
• Examples

🏗️ Architecture

pydantic-fire/
├── core/           # Core schema and validation
├── gateway/        # Firestore gateway implementations
├── sync_operations/  # Synchronous operations
├── async_operations/ # Async operations support
├── utils/          # Utilities and helpers
├── tests/          # Test suite
└── templates/      # Code generation templates

🧪 Development

Setup Development Environment

git clone https://github.com/yourusername/pydantic-fire.git
cd pydantic-fire
pip install -r requirements-dev.txt
pip install -e .

Running Tests

pytest

Code Quality

make lint        # Run linting
make format      # Format code
make type-check  # Type checking

Building Documentation

make docs-serve  # Serve documentation locally

🤝 Contributing

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for your changes
5. Ensure tests pass (pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📊 Requirements

• Python 3.8+
• Google Cloud Firestore
• Pydantic 1.10+ or 2.0+

🔧 Configuration

Environment Variables

export GOOGLE_APPLICATION_CREDENTIALS="path/to/service-account.json"
export FIRESTORE_EMULATOR_HOST="localhost:8080"  # For local development

Configuration File

# config.py
from pydantic_fire import FirestoreGateway

# Configure gateway
gateway = FirestoreGateway(
    project_id="your-project-id",
    database="(default)"
)

📈 Performance

• Lazy Loading: Documents are loaded on-demand
• Batch Operations: Efficient bulk operations
• Caching: Built-in caching for frequently accessed data
• Connection Pooling: Optimized connection management

🔒 Security

• Security Rules: Automatic security rules generation
• Validation: Comprehensive input validation
• Type Safety: Compile-time type checking
• Access Control: Fine-grained access control

🐛 Troubleshooting

Common Issues

1. Import Errors: Ensure all dependencies are installed
2. Authentication: Check Google Cloud credentials
3. Network Issues: Verify Firestore connectivity
4. Type Errors: Check Pydantic model definitions

Getting Help

• GitHub Issues
• Discussions
• Documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Pydantic for data validation
• Google Cloud Firestore for database
• pytest for testing framework

---

Made with ❤️ by the pydantic-fire team