# Pydantic Fire
[](https://badge.fury.io/py/pydantic-fire)
[](https://pypi.org/project/pydantic-fire/)
[](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**
Raw data
{
"_id": null,
"home_page": null,
"name": "pydantic-fire",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "firestore, google-cloud, pydantic, orm, database, nosql",
"author": null,
"author_email": "ni-rafi <niraficee@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cd/19/36509009d75f0fc09037e49aa052aa332a92526396c80881fdade907357a/pydantic_fire-1.0.2.tar.gz",
"platform": null,
"description": "# Pydantic Fire\r\n\r\n[](https://badge.fury.io/py/pydantic-fire)\r\n[](https://pypi.org/project/pydantic-fire/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\nA Python package for defining type-safe, dynamic, and maintainable Firestore schemas using Pydantic.\r\n\r\n## \u2728 Features\r\n\r\n- **Type Safety**: Full type hints and Pydantic validation\r\n- **Firestore Integration**: Seamless Google Cloud Firestore integration\r\n- **Sync Support**: Full synchronous support for legacy Python applications\r\n- **Async Support**: Full async/await support for modern Python applications\r\n- **Schema Management**: Automatic schema validation and management\r\n- **Testing Tools**: Built-in testing utilities and mock clients\r\n- **Documentation**: Auto-generated documentation from your schemas\r\n- **Security Rules**: Automatic Firestore security rules generation\r\n- **Performance**: Optimized for high-performance applications\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install pydantic-fire\r\n```\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom pydantic_fire import Document, Collection, Field\r\nfrom datetime import datetime\r\n\r\nclass UserDocument(Document):\r\n name: str = Field(..., description=\"User's full name\")\r\n email: str = Field(..., description=\"User's email address\")\r\n created_at: datetime = Field(default_factory=datetime.utcnow)\r\n is_active: bool = Field(default=True)\r\n\r\n# Create a collection\r\nUsersCollection = Collection(UserDocument, \"users\")\r\n\r\n# Use with Firestore\r\nfrom pydantic_fire import FirestoreGateway\r\n\r\ngateway = FirestoreGateway()\r\nuser = UserDocument(name=\"John Doe\", email=\"john@example.com\")\r\n```\r\n\r\n### Async Usage\r\n\r\n```python\r\nimport asyncio\r\nfrom pydantic_fire import AsyncFirestoreGateway\r\n\r\nasync def main():\r\n gateway = AsyncFirestoreGateway()\r\n user = UserDocument(name=\"Jane Doe\", email=\"jane@example.com\")\r\n result = await gateway.create_async(UsersCollection, \"user456\", user)\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n## \ud83d\udcd6 Documentation\r\n\r\n- **[Installation Guide](https://pydantic-fire.readthedocs.io/en/latest/getting-started/installation/)**\r\n- **[Quick Start Tutorial](https://pydantic-fire.readthedocs.io/en/latest/getting-started/quickstart/)**\r\n- **[API Reference](https://pydantic-fire.readthedocs.io/en/latest/api/)**\r\n- **[Examples](https://pydantic-fire.readthedocs.io/en/latest/examples/)**\r\n\r\n## \ud83c\udfd7\ufe0f Architecture\r\n\r\n```\r\npydantic-fire/\r\n\u251c\u2500\u2500 core/ # Core schema and validation\r\n\u251c\u2500\u2500 gateway/ # Firestore gateway implementations\r\n\u251c\u2500\u2500 sync_operations/ # Synchronous operations\r\n\u251c\u2500\u2500 async_operations/ # Async operations support\r\n\u251c\u2500\u2500 utils/ # Utilities and helpers\r\n\u251c\u2500\u2500 tests/ # Test suite\r\n\u2514\u2500\u2500 templates/ # Code generation templates\r\n```\r\n\r\n## \ud83e\uddea Development\r\n\r\n### Setup Development Environment\r\n\r\n```bash\r\ngit clone https://github.com/yourusername/pydantic-fire.git\r\ncd pydantic-fire\r\npip install -r requirements-dev.txt\r\npip install -e .\r\n```\r\n\r\n### Running Tests\r\n\r\n```bash\r\npytest\r\n```\r\n\r\n### Code Quality\r\n\r\n```bash\r\nmake lint # Run linting\r\nmake format # Format code\r\nmake type-check # Type checking\r\n```\r\n\r\n### Building Documentation\r\n\r\n```bash\r\nmake docs-serve # Serve documentation locally\r\n```\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](https://pydantic-fire.readthedocs.io/en/latest/contributing/) for details.\r\n\r\n1. Fork the repository\r\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Make your changes\r\n4. Add tests for your changes\r\n5. Ensure tests pass (`pytest`)\r\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n7. Push to the branch (`git push origin feature/amazing-feature`)\r\n8. Open a Pull Request\r\n\r\n## \ud83d\udcca Requirements\r\n\r\n- Python 3.8+\r\n- Google Cloud Firestore\r\n- Pydantic 1.10+ or 2.0+\r\n\r\n## \ud83d\udd27 Configuration\r\n\r\n### Environment Variables\r\n\r\n```bash\r\nexport GOOGLE_APPLICATION_CREDENTIALS=\"path/to/service-account.json\"\r\nexport FIRESTORE_EMULATOR_HOST=\"localhost:8080\" # For local development\r\n```\r\n\r\n### Configuration File\r\n\r\n```python\r\n# config.py\r\nfrom pydantic_fire import FirestoreGateway\r\n\r\n# Configure gateway\r\ngateway = FirestoreGateway(\r\n project_id=\"your-project-id\",\r\n database=\"(default)\"\r\n)\r\n```\r\n\r\n## \ud83d\udcc8 Performance\r\n\r\n- **Lazy Loading**: Documents are loaded on-demand\r\n- **Batch Operations**: Efficient bulk operations\r\n- **Caching**: Built-in caching for frequently accessed data\r\n- **Connection Pooling**: Optimized connection management\r\n\r\n## \ud83d\udd12 Security\r\n\r\n- **Security Rules**: Automatic security rules generation\r\n- **Validation**: Comprehensive input validation\r\n- **Type Safety**: Compile-time type checking\r\n- **Access Control**: Fine-grained access control\r\n\r\n## \ud83d\udc1b Troubleshooting\r\n\r\n### Common Issues\r\n\r\n1. **Import Errors**: Ensure all dependencies are installed\r\n2. **Authentication**: Check Google Cloud credentials\r\n3. **Network Issues**: Verify Firestore connectivity\r\n4. **Type Errors**: Check Pydantic model definitions\r\n\r\n### Getting Help\r\n\r\n- [GitHub Issues](https://github.com/yourusername/pydantic-fire/issues)\r\n- [Discussions](https://github.com/yourusername/pydantic-fire/discussions)\r\n- [Documentation](https://pydantic-fire.readthedocs.io/)\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- [Pydantic](https://github.com/pydantic/pydantic) for data validation\r\n- [Google Cloud Firestore](https://cloud.google.com/firestore) for database\r\n- [pytest](https://pytest.org/) for testing framework\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f by the pydantic-fire team**\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python package for defining type-safe, dynamic, and maintainable Firestore schemas using Pydantic",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://github.com/ni-rafi/pydantic-fire#readme",
"Homepage": "https://github.com/ni-rafi/pydantic-fire",
"Issues": "https://github.com/ni-rafi/pydantic-fire/issues",
"Repository": "https://github.com/ni-rafi/pydantic-fire"
},
"split_keywords": [
"firestore",
" google-cloud",
" pydantic",
" orm",
" database",
" nosql"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0f69ca568ab70fd2575d1e83293f9c016f7956a7c9e3930240fc8b31f7afdc4d",
"md5": "c6f5b5f1d60f498988af45d965ab32c5",
"sha256": "90a9487ad6f368955e69b833e275e350195a6a1a9f2e01e80d6380bc2919e4fc"
},
"downloads": -1,
"filename": "pydantic_fire-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6f5b5f1d60f498988af45d965ab32c5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 92974,
"upload_time": "2025-07-30T04:50:37",
"upload_time_iso_8601": "2025-07-30T04:50:37.944333Z",
"url": "https://files.pythonhosted.org/packages/0f/69/ca568ab70fd2575d1e83293f9c016f7956a7c9e3930240fc8b31f7afdc4d/pydantic_fire-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cd1936509009d75f0fc09037e49aa052aa332a92526396c80881fdade907357a",
"md5": "a8eb18d35de0d2134ae6abf985db43d7",
"sha256": "f3e67965fd7dd79c7ae4f7759e168ffcaea31728251a9fd2ec0185e9aaafb537"
},
"downloads": -1,
"filename": "pydantic_fire-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a8eb18d35de0d2134ae6abf985db43d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 79939,
"upload_time": "2025-07-30T04:50:39",
"upload_time_iso_8601": "2025-07-30T04:50:39.317875Z",
"url": "https://files.pythonhosted.org/packages/cd/19/36509009d75f0fc09037e49aa052aa332a92526396c80881fdade907357a/pydantic_fire-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 04:50:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ni-rafi",
"github_project": "pydantic-fire#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "google-cloud-firestore",
"specs": [
[
">=",
"2.10.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"1.10.0"
],
[
"<",
"3.0.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
">=",
"2.8.0"
]
]
}
],
"lcname": "pydantic-fire"
}
JSON
