feat(firestore): Expose Async Firestore Client. (#621)

* feat(firestore): Expose Async Firestore Client.

* fix: Added type hints and defintion wording changes

* fix: removed future annotations until Python 3.6 is depreciated.

* fix: added missed type and clarifying comment for Python 3.6 type hinting.

* fix: lint

Author: jkyle109

firebase_admin/firestore_async.py

@@ -0,0 +1,82 @@
+# Copyright 2022 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Cloud Firestore Async module.
+
+This module contains utilities for asynchronusly accessing the Google Cloud Firestore databases
+associated with Firebase apps. This requires the ``google-cloud-firestore`` Python module.
+"""
+
+from typing import Type
+
+from firebase_admin import (
+    App,
+    _utils,
+)
+from firebase_admin.credentials import Base
+
+try:
+    from google.cloud import firestore # type: ignore # pylint: disable=import-error,no-name-in-module
+    existing = globals().keys()
+    for key, value in firestore.__dict__.items():
+        if not key.startswith('_') and key not in existing:
+            globals()[key] = value
+except ImportError:
+    raise ImportError('Failed to import the Cloud Firestore library for Python. Make sure '
+                      'to install the "google-cloud-firestore" module.')
+
+_FIRESTORE_ASYNC_ATTRIBUTE: str = '_firestore_async'
+
+
+def client(app: App = None) -> firestore.AsyncClient:
+    """Returns an async client that can be used to interact with Google Cloud Firestore.
+
+    Args:
+      app: An App instance (optional).
+
+    Returns:
+      google.cloud.firestore.Firestore_Async: A `Firestore Async Client`_.
+
+    Raises:
+      ValueError: If a project ID is not specified either via options, credentials or
+          environment variables, or if the specified project ID is not a valid string.
+
+    .. _Firestore Async Client: https://googleapis.dev/python/firestore/latest/client.html
+    """
+    fs_client = _utils.get_app_service(
+        app, _FIRESTORE_ASYNC_ATTRIBUTE, _FirestoreAsyncClient.from_app)
+    return fs_client.get()
+
+
+class _FirestoreAsyncClient:
+    """Holds a Google Cloud Firestore Async Client instance."""
+
+    def __init__(self, credentials: Type[Base], project: str) -> None:
+        self._client = firestore.AsyncClient(credentials=credentials, project=project)
+
+    def get(self) -> firestore.AsyncClient:
+        return self._client
+
+    @classmethod
+    def from_app(cls, app: App) -> "_FirestoreAsyncClient":
+        # Replace remove future reference quotes by importing annotations in Python 3.7+ b/238779406
+        """Creates a new _FirestoreAsyncClient for the specified app."""
+        credentials = app.credential.get_credential()
+        project = app.project_id
+        if not project:
+            raise ValueError(
+                'Project ID is required to access Firestore. Either set the projectId option, '
+                'or use service account credentials. Alternatively, set the GOOGLE_CLOUD_PROJECT '
+                'environment variable.')
+        return _FirestoreAsyncClient(credentials, project)

tests/test_firestore_async.py

@@ -0,0 +1,81 @@
+# Copyright 2022 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for firebase_admin.firestore_async."""
+
+import platform
+
+import pytest
+
+import firebase_admin
+from firebase_admin import credentials
+try:
+    from firebase_admin import firestore_async
+except ImportError:
+    pass
+from tests import testutils
+
+
+@pytest.mark.skipif(
+    platform.python_implementation() == 'PyPy',
+    reason='Firestore is not supported on PyPy')
+class TestFirestoreAsync:
+    """Test class Firestore Async APIs."""
+
+    def teardown_method(self, method):
+        del method
+        testutils.cleanup_apps()
+
+    def test_no_project_id(self):
+        def evaluate():
+            firebase_admin.initialize_app(testutils.MockCredential())
+            with pytest.raises(ValueError):
+                firestore_async.client()
+        testutils.run_without_project_id(evaluate)
+
+    def test_project_id(self):
+        cred = credentials.Certificate(testutils.resource_filename('service_account.json'))
+        firebase_admin.initialize_app(cred, {'projectId': 'explicit-project-id'})
+        client = firestore_async.client()
+        assert client is not None
+        assert client.project == 'explicit-project-id'
+
+    def test_project_id_with_explicit_app(self):
+        cred = credentials.Certificate(testutils.resource_filename('service_account.json'))
+        app = firebase_admin.initialize_app(cred, {'projectId': 'explicit-project-id'})
+        client = firestore_async.client(app=app)
+        assert client is not None
+        assert client.project == 'explicit-project-id'
+
+    def test_service_account(self):
+        cred = credentials.Certificate(testutils.resource_filename('service_account.json'))
+        firebase_admin.initialize_app(cred)
+        client = firestore_async.client()
+        assert client is not None
+        assert client.project == 'mock-project-id'
+
+    def test_service_account_with_explicit_app(self):
+        cred = credentials.Certificate(testutils.resource_filename('service_account.json'))
+        app = firebase_admin.initialize_app(cred)
+        client = firestore_async.client(app=app)
+        assert client is not None
+        assert client.project == 'mock-project-id'
+
+    def test_geo_point(self):
+        geo_point = firestore_async.GeoPoint(10, 20) # pylint: disable=no-member
+        assert geo_point.latitude == 10
+        assert geo_point.longitude == 20
+
+    def test_server_timestamp(self):
+        assert firestore_async.SERVER_TIMESTAMP is not None # pylint: disable=no-member