Firestore API (#79)

* Firestore integration

* Merged with master; Firestore module now using the project ID plumbed in via App

* Correcting a mistyped error message

* Added Firestore

* Fixing some test and lint errors

* Installing enum34 when running below Python 3.4

Author: hiranya911

firebase_admin/credentials.py

@@ -25,6 +25,8 @@
 
 _request = requests.Request()
 _scopes = [
+    'https://www.googleapis.com/auth/cloud-platform',
+    'https://www.googleapis.com/auth/datastore',
     'https://www.googleapis.com/auth/devstorage.read_write',
     'https://www.googleapis.com/auth/firebase',
     'https://www.googleapis.com/auth/identitytoolkit',

firebase_admin/firestore.py

@@ -0,0 +1,78 @@
+# Copyright 2017 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 module.
+
+This module contains utilities for accessing the Google Cloud Firestore databases associated with
+Firebase apps. This requires the google-cloud-firestore Python module.
+"""
+
+try:
+    from google.cloud import firestore # 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.')
+
+import six
+
+from firebase_admin import _utils
+
+
+_FIRESTORE_ATTRIBUTE = '_firestore'
+
+
+def client(app=None):
+    """Returns a client that can be used to interact with Google Cloud Firestore.
+
+    Args:
+      app: An App instance (optional).
+
+    Returns:
+      google.cloud.firestore.Firestore: A Firestore database 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.
+    """
+    fs_client = _utils.get_app_service(app, _FIRESTORE_ATTRIBUTE, _FirestoreClient.from_app)
+    return fs_client.get()
+
+
+class _FirestoreClient(object):
+    """Holds a Google Cloud Firestore client instance."""
+
+    def __init__(self, credentials, project):
+        self._client = firestore.Client(credentials=credentials, project=project)
+
+    def get(self):
+        return self._client
+
+    @classmethod
+    def from_app(cls, app):
+        """Creates a new _FirestoreClient 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 GCLOUD_PROJECT '
+                'environment variable.')
+        elif not isinstance(project, six.string_types):
+            raise ValueError(
+                'Invalid project ID: "{0}". project ID must be a string.'.format(project))
+        return _FirestoreClient(credentials, project)

firebase_admin/storage.py

@@ -15,7 +15,7 @@
 """Firebase Cloud Storage module.
 
 This module contains utilities for accessing Google Cloud Storage buckets associated with
-Firebase apps. This requires installing the google-cloud-storage Python module separately.
+Firebase apps. This requires the google-cloud-storage Python module.
 """
 
 # pylint: disable=import-error,no-name-in-module

integration/test_firestore.py

@@ -0,0 +1,53 @@
+# Copyright 2017 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.
+
+"""Integration tests for firebase_admin.firestore module."""
+import datetime
+import pytest
+
+from google.cloud import exceptions # pylint: disable=import-error,no-name-in-module
+
+from firebase_admin import firestore
+
+
+def test_firestore():
+    client = firestore.client()
+    expected = {
+        'name': u'Mountain View',
+        'country': u'USA',
+        'population': 77846,
+        'capital': False
+    }
+    doc = client.collection('cities').document()
+    doc.set(expected)
+
+    data = doc.get().to_dict()
+    assert data == expected
+
+    doc.delete()
+    with pytest.raises(exceptions.NotFound):
+        doc.get()
+
+def test_server_timestamp():
+    client = firestore.client()
+    expected = {
+        'name': u'Mountain View',
+        'timestamp': firestore.SERVER_TIMESTAMP # pylint: disable=no-member
+    }
+    doc = client.collection('cities').document()
+    doc.set(expected)
+
+    data = doc.get().to_dict()
+    assert isinstance(data['timestamp'], datetime.datetime)
+    doc.delete()

requirements.txt

@@ -4,6 +4,8 @@ pytest-cov >= 2.4.0
 tox >= 2.6.0
 
 google-auth >= 1.1.0
+google-cloud-firestore >= 0.27.0
 google-cloud-storage >= 1.2.0
 requests >= 2.13.0
 six >= 1.6.1
+enum34 >= 1.0.4; python_version < '3.4'

setup.py

@@ -33,11 +33,16 @@
                     'to integrate Firebase into their services and applications.')
 install_requires = [
     'google-auth>=1.1.0',
-    'google-cloud-storage>=1.2.0',
+    'google-cloud-firestore>=0.27.0',
+    'google-cloud-storage>=1.2.0',    
     'requests>=2.13.0',
     'six>=1.6.1'
 ]
 
+extras_require = {
+    ':python_version<"3.4"': ('enum34>=1.0.4',),
+}
+
 version = firebase_admin.__version__
 
 setup(
@@ -49,6 +54,7 @@
     author='Firebase',
     license='Apache License 2.0',
     keywords='firebase cloud development',
+    extras_require=extras_require,
     install_requires=install_requires,
     packages=find_packages(exclude=['tests']),
     classifiers=[

tests/test_firestore.py

@@ -0,0 +1,77 @@
+# Copyright 2017 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."""
+
+import os
+
+import pytest
+
+import firebase_admin
+from firebase_admin import credentials
+from firebase_admin import firestore
+from tests import testutils
+
+
+def teardown_function():
+    testutils.cleanup_apps()
+
+def test_no_project_id():
+    env_var = 'GCLOUD_PROJECT'
+    gcloud_project = os.environ.get(env_var)
+    if gcloud_project:
+        del os.environ[env_var]
+    try:
+        firebase_admin.initialize_app(testutils.MockCredential())
+        with pytest.raises(ValueError):
+            firestore.client()
+    finally:
+        if gcloud_project:
+            os.environ[env_var] = gcloud_project
+
+def test_project_id():
+    cred = credentials.Certificate(testutils.resource_filename('service_account.json'))
+    firebase_admin.initialize_app(cred, {'projectId': 'explicit-project-id'})
+    client = firestore.client()
+    assert client is not None
+    assert client.project == 'explicit-project-id'
+
+def test_project_id_with_explicit_app():
+    cred = credentials.Certificate(testutils.resource_filename('service_account.json'))
+    app = firebase_admin.initialize_app(cred, {'projectId': 'explicit-project-id'})
+    client = firestore.client(app=app)
+    assert client is not None
+    assert client.project == 'explicit-project-id'
+
+def test_service_account():
+    cred = credentials.Certificate(testutils.resource_filename('service_account.json'))
+    firebase_admin.initialize_app(cred)
+    client = firestore.client()
+    assert client is not None
+    assert client.project == 'mock-project-id'
+
+def test_service_account_with_explicit_app():
+    cred = credentials.Certificate(testutils.resource_filename('service_account.json'))
+    app = firebase_admin.initialize_app(cred)
+    client = firestore.client(app=app)
+    assert client is not None
+    assert client.project == 'mock-project-id'
+
+def test_geo_point():
+    geo_point = firestore.GeoPoint(10, 20) # pylint: disable=no-member
+    assert geo_point.latitude == 10
+    assert geo_point.longitude == 20
+
+def test_server_timestamp():
+    assert firestore.SERVER_TIMESTAMP is not None # pylint: disable=no-member

tests/test_storage.py

@@ -43,3 +43,10 @@ def test_valid_name():
     bucket = storage.bucket('foo')
     assert bucket is not None
     assert bucket.name == 'foo'
+
+def test_valid_name_with_explicit_app():
+    # Should not make RPC calls.
+    app = firebase_admin.get_app()
+    bucket = storage.bucket('foo', app=app)
+    assert bucket is not None
+    assert bucket.name == 'foo'