Metadata-Version: 2.4
Name: pydantic-fire
Version: 1.0.1
Summary: A Python package for defining type-safe, dynamic, and maintainable Firestore schemas using Pydantic
Author-email: ni-rafi <niraficee@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ni-rafi/pydantic-fire
Project-URL: Documentation, https://pydantic-fire.readthedocs.io/
Project-URL: Repository, https://github.com/ni-rafi/pydantic-fire.git
Project-URL: Issues, https://github.com/ni-rafi/pydantic-fire/issues
Keywords: firestore,google-cloud,pydantic,orm,database,nosql
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.4.0; extra == "docs"
Requires-Dist: mkdocs-material>=8.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.19.0; extra == "docs"
Provides-Extra: testing
Requires-Dist: pytest>=7.0.0; extra == "testing"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "testing"
Requires-Dist: pytest-cov>=4.0.0; extra == "testing"
Dynamic: license-file

# 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**
