Metadata-Version: 2.4
Name: django-orm-firebase
Version: 0.0.2
Summary: Django ORM-like interface for Firebase
Project-URL: Homepage, https://github.com/sheikhjebran/django_firebase_orm
Project-URL: Repository, https://github.com/sheikhjebran/django_firebase_orm
Project-URL: Bug Tracker, https://github.com/sheikhjebran/django_firebase_orm/issues
Author-email: Jebran Sheikh <sheikhjebran@gmail.com>
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: django>=4.2
Requires-Dist: firebase-admin>=7.0.0
Description-Content-Type: text/markdown

# django_firebase_orm

A Firestore-backed, Django-project-friendly model layer.

This repository provides a small ORM-like wrapper around Firebase Admin and
Cloud Firestore. It is useful inside a Django project, but it is not a drop-in
replacement for `django.db.models`.

## Features
- Define simple model classes like Django ORM
- Save, retrieve, update, delete, and query Firestore documents
- Manager and QuerySet wrappers for common query patterns

## Current Scope
- Model definition and basic persistence
- `save`, `update`, `delete`, `get`, `all`, and simple equality filters
- Bulk queryset and manager `update`/`delete` helpers
- Service-account based Firebase initialization
- Django settings-based Firebase initialization

## Current Limitations
- No Django model inheritance or migrations
- No field validation, relations, or model managers integrated with Django
- Query support is limited to simple Firestore `where(... == ...)` filtering
- Collection names map to the lowercase model class name

## Recommended Next Steps
1. Add explicit field types and validation.
2. Add relation support or document Firestore subcollection patterns.
3. Add project-level Firebase options and more init variants if needed.
4. Decide whether this project should stay an ORM-like wrapper or become a full Django app integration.

## Installation
```bash
pip install firebase-admin Django
```

If you want Django settings-based initialization or the `AppConfig` startup
hook, Django must be installed.

## Usage
```python
from django_firebase_orm import Model, Manager, initialize_firebase

initialize_firebase('path/to/serviceAccountKey.json')

class User(Model):
    name = ''
    age = 0

user = User(name='Alice', age=30)
user.save()

user = User.get('some_id')
users = User.all()

manager = Manager(User)
alice_users = manager.filter(name='Alice')
```

## Django Settings Configuration
If you already have Django configured, you can initialize Firebase from settings.

```python
# settings.py
FIREBASE_CREDENTIAL_PATH = BASE_DIR / 'serviceAccountKey.json'
FIREBASE_OPTIONS = {
    'projectId': 'your-project-id',
}
```

Then call:

```python
initialize_firebase()
```

### Supported Settings
- `FIREBASE_CREDENTIAL_PATH`: path to a Firebase service account JSON file.
- `FIREBASE_OPTIONS`: optional dictionary passed to `firebase_admin.initialize_app()`.
- `FIREBASE_AUTO_INIT`: set to `True` to enable automatic startup initialization from `AppConfig.ready()`.

## Django AppConfig
If you want Firebase to initialize automatically when Django starts, register
the app config in `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    'django_firebase_orm.apps.DjangoFirebaseOrmConfig',
]
```

Set `FIREBASE_AUTO_INIT = True` in your settings to enable the startup hook.

The app config calls `initialize_firebase()` from `ready()` only when that flag
is enabled, and it uses the same `FIREBASE_CREDENTIAL_PATH` and
`FIREBASE_OPTIONS` settings described above.

## Development
```bash
python -m unittest discover -s tests
```

## Project Structure
- `django_firebase_orm/` - package source
- `tests/` - unit tests
- `setup.py` - package metadata

## License
MIT
