# Pydantic Fire

[![PyPI version](https://badge.fury.io/py/pydantic-fire.svg)](https://badge.fury.io/py/pydantic-fire)
[![Python versions](https://img.shields.io/pypi/pyversions/pydantic-fire.svg)](https://pypi.org/project/pydantic-fire/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install pydantic-fire
```

### Basic Usage

```python
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="john@example.com")
```

### Async Usage

```python
import asyncio
from pydantic_fire import AsyncFirestoreGateway

async def main():
    gateway = AsyncFirestoreGateway()
    user = UserDocument(name="Jane Doe", email="jane@example.com")
    result = await gateway.create_async(UsersCollection, "user456", user)

asyncio.run(main())
```

## 📖 Documentation

- **[Installation Guide](https://pydantic-fire.readthedocs.io/en/latest/getting-started/installation/)**
- **[Quick Start Tutorial](https://pydantic-fire.readthedocs.io/en/latest/getting-started/quickstart/)**
- **[API Reference](https://pydantic-fire.readthedocs.io/en/latest/api/)**
- **[Examples](https://pydantic-fire.readthedocs.io/en/latest/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

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

### Running Tests

```bash
pytest
```

### Code Quality

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

### Building Documentation

```bash
make docs-serve  # Serve documentation locally
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](https://pydantic-fire.readthedocs.io/en/latest/contributing/) 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

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

### Configuration File

```python
# 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](https://github.com/yourusername/pydantic-fire/issues)
- [Discussions](https://github.com/yourusername/pydantic-fire/discussions)
- [Documentation](https://pydantic-fire.readthedocs.io/)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Pydantic](https://github.com/pydantic/pydantic) for data validation
- [Google Cloud Firestore](https://cloud.google.com/firestore) for database
- [pytest](https://pytest.org/) for testing framework

---

**Made with ❤️ by the pydantic-fire team**
