Firestore Pydantic ODM
======================
**Firestore Pydantic ODM** es una librería para interactuar con Google
Cloud Firestore de forma sencilla y eficiente. Utiliza
`Pydantic <https://pydantic-docs.helpmanual.io/>`__ para la validación y
serialización de datos y ofrece soporte para operaciones asíncronas,
batch writes, transacciones, paginación, proyecciones y más.
Esta librería está diseñada para facilitar el desarrollo de aplicaciones
que requieren almacenar y consultar datos en Firestore, ofreciendo una
interfaz Pythonic y desacoplada que permite cambiar fácilmente el
cliente (por ejemplo, para usar emuladores o mocks en testing).
Características
---------------
- **CRUD Asíncrono:** Soporte completo para crear, leer, actualizar y
eliminar documentos de Firestore usando ``async/await``.
- **Validación con Pydantic:** Define tus modelos de datos con
validación automática, asegurando la integridad de la información.
- **Consultas Avanzadas:** Realiza búsquedas con filtros, proyecciones
(seleccionar solo ciertos campos) y ordenación.
- **Batch Operations y Transacciones:** Agrupa múltiples operaciones de
escritura y ejecuta transacciones de forma atómica para mayor
eficiencia y coherencia.
- **Soporte para Emulador y Testing:** Configura de forma sencilla el
uso del emulador de Firestore o integra mocks para pruebas unitarias.
- **Fácil Integración:** Se integra sin problemas en cualquier proyecto
Python.
Instalación
-----------
Desde el Código Fuente
~~~~~~~~~~~~~~~~~~~~~~
1. Clona el repositorio:
.. code:: bash
git clone https://github.com/santosdevco/firestore-pydantic-odm
cd firestore_pydantic_odm
2. Instala las dependencias y el paquete en modo editable:
.. code:: bash
pip install -e .
Dependencias
~~~~~~~~~~~~
Revisa el archivo `requirements.txt <requirements.txt>`__ para conocer
las dependencias necesarias, entre las que se incluyen: - ``pydantic`` -
``google-cloud-firestore>=2.0.0`` - ``pytest`` y ``pytest-asyncio``
(para testing)
Estructura del Proyecto
-----------------------
La organización recomendada es la siguiente:
::
firestore_pydantic_odm/
__init__.py # Exposición de la API pública
firestore_model.py # Lógica principal del ODM
firestore_fields.py # Descriptores y manejo de filtros
enums.py # Enumeraciones (e.g., BatchOperation)
firestore_client.py # Inicialización y gestión del cliente Firestore
tests/
conftest.py # Fixtures para pruebas
tests.py # Pruebas unitarias
Dockerfile # Configuración Docker
docker-compose.yaml # Configuración Docker Compose
requirements.txt # Dependencias del proyecto
pytest.ini # Configuración global de Pytest
setup.py # Script de instalación del paquete
..
**Nota:** El archivo ``__init__.py`` es fundamental para que Python
reconozca el directorio ``firestore_pydantic_odm`` como un paquete.
En él se exportan las clases y funciones principales de la librería.
Uso Básico
----------
Definir un Modelo
~~~~~~~~~~~~~~~~~
Crea tus modelos extendiendo la clase base ``BaseFirestoreModel``:
.. code:: python
from firestore_pydantic_odm import BaseFirestoreModel
class User(BaseFirestoreModel):
class Settings:
name = "users" # Nombre de la colección en Firestore
name: str
email: str
Inicializar el Cliente de Firestore
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Antes de utilizar los modelos, inicializa la conexión:
.. code:: python
from firestore_pydantic_odm import FirestoreDB, BaseFirestoreModel
# Inicializa el cliente, pudiendo especificar el host del emulador si es necesario
db = FirestoreDB(project_id="tu-proyecto", emulator_host="localhost:8080")
# Inyecta el cliente en la clase base para que todos los modelos lo utilicen
BaseFirestoreModel.initialize_db(db)
Operaciones CRUD
~~~~~~~~~~~~~~~~
Crear y Guardar un Documento
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
user = User(name="Alice", email="alice@example.com")
await user.save()
Actualizar un Documento
^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
user.email = "nueva_alice@example.com"
await user.update()
Eliminar un Documento
^^^^^^^^^^^^^^^^^^^^^
.. code:: python
await user.delete()
Obtener un Documento por ID
^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
user = await User.get("id_del_documento")
Consultas
~~~~~~~~~
Buscar Documentos
^^^^^^^^^^^^^^^^^
Realiza búsquedas utilizando filtros:
.. code:: python
async for user in User.find(filters=[User.name == "Alice"]):
print(user)
Buscar un Único Documento
^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: python
user = await User.find_one(filters=[User.email == "alice@example.com"])
Usar Proyecciones
^^^^^^^^^^^^^^^^^
Si solo necesitas ciertos campos, puedes usar un modelo de proyección:
.. code:: python
from pydantic import BaseModel
class UserProjection(BaseModel):
name: str
async for user in User.find(filters=[User.name == "Alice"], projection=UserProjection):
print(user)
Batch Operations y Transacciones
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Operaciones en Batch
^^^^^^^^^^^^^^^^^^^^
.. code:: python
from firestore_pydantic_odm import BatchOperation
ops = [
(BatchOperation.CREATE, User(name="Bob", email="bob@example.com")),
(BatchOperation.UPDATE, user),
(BatchOperation.DELETE, another_user)
]
await User.batch_write(ops)
Testing
-------
| El proyecto incluye pruebas unitarias con
`pytest <https://docs.pytest.org/>`__ y
`pytest-asyncio <https://github.com/pytest-dev/pytest-asyncio>`__.
| Para ejecutar los tests, simplemente corre:
.. code:: bash
pytest
El archivo ``pytest.ini`` y ``conftest.py`` (ubicado en la raíz o en el
directorio ``tests/``) proporcionan la configuración y las fixtures
necesarias.
Contribuir
----------
¡Contribuciones son bienvenidas! Si deseas aportar mejoras:
1. Haz un fork del repositorio.
2. Crea una rama para tu feature o corrección.
3. Realiza tus cambios y asegúrate de que todos los tests pasen.
4. Envía un Pull Request describiendo tus mejoras.
Licencia
--------
Distribuido bajo la Licencia MIT. Consulta el archivo
`LICENSE <LICENSE>`__ para más detalles.
Raw data
{
"_id": null,
"home_page": "https://github.com/santosdevco/firestore-pydantic-odm",
"name": "firestore-pydantic-odm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "firestore pydantic odm asynchronous",
"author": "Santos Dev Co",
"author_email": "projects@santosdevco.com",
"download_url": "https://files.pythonhosted.org/packages/11/59/d8cc6f937732938778b1a03cd665a4e3d23112847796febf389fce6e896c/firestore_pydantic_odm-0.1.6.tar.gz",
"platform": null,
"description": "Firestore Pydantic ODM\n======================\n\n**Firestore Pydantic ODM** es una librer\u00eda para interactuar con Google\nCloud Firestore de forma sencilla y eficiente. Utiliza\n`Pydantic <https://pydantic-docs.helpmanual.io/>`__ para la validaci\u00f3n y\nserializaci\u00f3n de datos y ofrece soporte para operaciones as\u00edncronas,\nbatch writes, transacciones, paginaci\u00f3n, proyecciones y m\u00e1s.\n\nEsta librer\u00eda est\u00e1 dise\u00f1ada para facilitar el desarrollo de aplicaciones\nque requieren almacenar y consultar datos en Firestore, ofreciendo una\ninterfaz Pythonic y desacoplada que permite cambiar f\u00e1cilmente el\ncliente (por ejemplo, para usar emuladores o mocks en testing).\n\nCaracter\u00edsticas\n---------------\n\n- **CRUD As\u00edncrono:** Soporte completo para crear, leer, actualizar y\n eliminar documentos de Firestore usando ``async/await``.\n- **Validaci\u00f3n con Pydantic:** Define tus modelos de datos con\n validaci\u00f3n autom\u00e1tica, asegurando la integridad de la informaci\u00f3n.\n- **Consultas Avanzadas:** Realiza b\u00fasquedas con filtros, proyecciones\n (seleccionar solo ciertos campos) y ordenaci\u00f3n.\n- **Batch Operations y Transacciones:** Agrupa m\u00faltiples operaciones de\n escritura y ejecuta transacciones de forma at\u00f3mica para mayor\n eficiencia y coherencia.\n- **Soporte para Emulador y Testing:** Configura de forma sencilla el\n uso del emulador de Firestore o integra mocks para pruebas unitarias.\n- **F\u00e1cil Integraci\u00f3n:** Se integra sin problemas en cualquier proyecto\n Python.\n\nInstalaci\u00f3n\n-----------\n\nDesde el C\u00f3digo Fuente\n~~~~~~~~~~~~~~~~~~~~~~\n\n1. Clona el repositorio:\n\n .. code:: bash\n\n git clone https://github.com/santosdevco/firestore-pydantic-odm\n cd firestore_pydantic_odm\n\n2. Instala las dependencias y el paquete en modo editable:\n\n .. code:: bash\n\n pip install -e .\n\nDependencias\n~~~~~~~~~~~~\n\nRevisa el archivo `requirements.txt <requirements.txt>`__ para conocer\nlas dependencias necesarias, entre las que se incluyen: - ``pydantic`` -\n``google-cloud-firestore>=2.0.0`` - ``pytest`` y ``pytest-asyncio``\n(para testing)\n\nEstructura del Proyecto\n-----------------------\n\nLa organizaci\u00f3n recomendada es la siguiente:\n\n::\n\n firestore_pydantic_odm/\n __init__.py # Exposici\u00f3n de la API p\u00fablica\n firestore_model.py # L\u00f3gica principal del ODM\n firestore_fields.py # Descriptores y manejo de filtros\n enums.py # Enumeraciones (e.g., BatchOperation)\n firestore_client.py # Inicializaci\u00f3n y gesti\u00f3n del cliente Firestore\n tests/\n conftest.py # Fixtures para pruebas\n tests.py # Pruebas unitarias\n Dockerfile # Configuraci\u00f3n Docker\n docker-compose.yaml # Configuraci\u00f3n Docker Compose\n requirements.txt # Dependencias del proyecto\n pytest.ini # Configuraci\u00f3n global de Pytest\n setup.py # Script de instalaci\u00f3n del paquete\n\n..\n\n **Nota:** El archivo ``__init__.py`` es fundamental para que Python\n reconozca el directorio ``firestore_pydantic_odm`` como un paquete.\n En \u00e9l se exportan las clases y funciones principales de la librer\u00eda.\n\nUso B\u00e1sico\n----------\n\nDefinir un Modelo\n~~~~~~~~~~~~~~~~~\n\nCrea tus modelos extendiendo la clase base ``BaseFirestoreModel``:\n\n.. code:: python\n\n from firestore_pydantic_odm import BaseFirestoreModel\n\n class User(BaseFirestoreModel):\n class Settings:\n name = \"users\" # Nombre de la colecci\u00f3n en Firestore\n\n name: str\n email: str\n\nInicializar el Cliente de Firestore\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nAntes de utilizar los modelos, inicializa la conexi\u00f3n:\n\n.. code:: python\n\n from firestore_pydantic_odm import FirestoreDB, BaseFirestoreModel\n\n # Inicializa el cliente, pudiendo especificar el host del emulador si es necesario\n db = FirestoreDB(project_id=\"tu-proyecto\", emulator_host=\"localhost:8080\")\n\n # Inyecta el cliente en la clase base para que todos los modelos lo utilicen\n BaseFirestoreModel.initialize_db(db)\n\nOperaciones CRUD\n~~~~~~~~~~~~~~~~\n\nCrear y Guardar un Documento\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n user = User(name=\"Alice\", email=\"alice@example.com\")\n await user.save()\n\nActualizar un Documento\n^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n user.email = \"nueva_alice@example.com\"\n await user.update()\n\nEliminar un Documento\n^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n await user.delete()\n\nObtener un Documento por ID\n^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n user = await User.get(\"id_del_documento\")\n\nConsultas\n~~~~~~~~~\n\nBuscar Documentos\n^^^^^^^^^^^^^^^^^\n\nRealiza b\u00fasquedas utilizando filtros:\n\n.. code:: python\n\n async for user in User.find(filters=[User.name == \"Alice\"]):\n print(user)\n\nBuscar un \u00danico Documento\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n user = await User.find_one(filters=[User.email == \"alice@example.com\"])\n\nUsar Proyecciones\n^^^^^^^^^^^^^^^^^\n\nSi solo necesitas ciertos campos, puedes usar un modelo de proyecci\u00f3n:\n\n.. code:: python\n\n from pydantic import BaseModel\n\n class UserProjection(BaseModel):\n name: str\n\n async for user in User.find(filters=[User.name == \"Alice\"], projection=UserProjection):\n print(user)\n\nBatch Operations y Transacciones\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nOperaciones en Batch\n^^^^^^^^^^^^^^^^^^^^\n\n.. code:: python\n\n from firestore_pydantic_odm import BatchOperation\n\n ops = [\n (BatchOperation.CREATE, User(name=\"Bob\", email=\"bob@example.com\")),\n (BatchOperation.UPDATE, user),\n (BatchOperation.DELETE, another_user)\n ]\n\n await User.batch_write(ops)\n\nTesting\n-------\n\n| El proyecto incluye pruebas unitarias con\n `pytest <https://docs.pytest.org/>`__ y\n `pytest-asyncio <https://github.com/pytest-dev/pytest-asyncio>`__.\n| Para ejecutar los tests, simplemente corre:\n\n.. code:: bash\n\n pytest\n\nEl archivo ``pytest.ini`` y ``conftest.py`` (ubicado en la ra\u00edz o en el\ndirectorio ``tests/``) proporcionan la configuraci\u00f3n y las fixtures\nnecesarias.\n\nContribuir\n----------\n\n\u00a1Contribuciones son bienvenidas! Si deseas aportar mejoras:\n\n1. Haz un fork del repositorio.\n2. Crea una rama para tu feature o correcci\u00f3n.\n3. Realiza tus cambios y aseg\u00farate de que todos los tests pasen.\n4. Env\u00eda un Pull Request describiendo tus mejoras.\n\nLicencia\n--------\n\nDistribuido bajo la Licencia MIT. Consulta el archivo\n`LICENSE <LICENSE>`__ para m\u00e1s detalles.\n",
"bugtrack_url": null,
"license": null,
"summary": "ODM para Firestore utilizando Pydantic y operaciones as\u00edncronas",
"version": "0.1.6",
"project_urls": {
"Bug Tracker": "https://github.com/santosdevco/firestore_pydantic_odm/issues",
"Documentation": "https://github.com/santosdevco/firestore_pydantic_odm#readme",
"Homepage": "https://github.com/santosdevco/firestore-pydantic-odm",
"Source Code": "https://github.com/santosdevco/firestore_pydantic_odm"
},
"split_keywords": [
"firestore",
"pydantic",
"odm",
"asynchronous"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "91f87332698caf5b3ba9f979644a7cd113829410cdd39d3f31beff5b5ecefc6b",
"md5": "1ab20bda46ad339bb60dc99364cd7b9c",
"sha256": "9c4c315e02d2268bab3fc1e1665fd36a1088428a70e6e2e4dd67eb8c57cb080b"
},
"downloads": -1,
"filename": "firestore_pydantic_odm-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1ab20bda46ad339bb60dc99364cd7b9c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 10070,
"upload_time": "2025-02-22T17:06:13",
"upload_time_iso_8601": "2025-02-22T17:06:13.000179Z",
"url": "https://files.pythonhosted.org/packages/91/f8/7332698caf5b3ba9f979644a7cd113829410cdd39d3f31beff5b5ecefc6b/firestore_pydantic_odm-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1159d8cc6f937732938778b1a03cd665a4e3d23112847796febf389fce6e896c",
"md5": "351a78ae4d2b20b89c5ddcbf80bf505e",
"sha256": "7bc33959732bf5a09e35fb74d6df8030bab95dbedb9cc8bf8a9a4734158209fc"
},
"downloads": -1,
"filename": "firestore_pydantic_odm-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "351a78ae4d2b20b89c5ddcbf80bf505e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 11367,
"upload_time": "2025-02-22T17:06:14",
"upload_time_iso_8601": "2025-02-22T17:06:14.915226Z",
"url": "https://files.pythonhosted.org/packages/11/59/d8cc6f937732938778b1a03cd665a4e3d23112847796febf389fce6e896c/firestore_pydantic_odm-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-22 17:06:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "santosdevco",
"github_project": "firestore-pydantic-odm",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "fastapi",
"specs": [
[
"==",
"0.70.0"
]
]
},
{
"name": "fastapi-socketio",
"specs": [
[
"==",
"0.0.9"
]
]
},
{
"name": "uvicorn",
"specs": [
[
"==",
"0.15.0"
]
]
},
{
"name": "gunicorn",
"specs": []
},
{
"name": "google-cloud-aiplatform",
"specs": [
[
">=",
"1.38"
]
]
},
{
"name": "google-cloud-firestore",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest_asyncio",
"specs": []
}
],
"lcname": "firestore-pydantic-odm"
}
JSON
