Google Cloud Storage API [WIP] (#44)

* Delegating token generation to the google.auth.credentials library * Provided a default implementation for get_access_token() * Updated API doc * Experimental GCS integration * Adding GCS dependency * Temp fix for linter false positives * Refactored storage API and added unit tests * Raising a ValueError for non-existing buckets * Custom handling import error * Removing the checks for non-existing buckets * Test case for valid bucket config * Updated setup script. Added GCS dependency.

Author: hiranya911

firebase_admin/credentials.py

@@ -25,6 +25,7 @@
 
 _request = requests.Request()
 _scopes = [
+ 'https://www.googleapis.com/auth/devstorage.read_write',
  'https://www.googleapis.com/auth/firebase',
  'https://www.googleapis.com/auth/userinfo.email'
 ]

firebase_admin/storage.py

@@ -0,0 +1,88 @@
+# 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.
+
+"""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.
+"""
+
+# pylint: disable=import-error,no-name-in-module
+try:
+ from google.cloud import storage
+except ImportError:
+ raise ImportError('Failed to import the Cloud Storage library for Python. Make sure '
+ 'to install the "google-cloud-storage" module.')
+
+import six
+
+from firebase_admin import utils
+
+
+_STORAGE_ATTRIBUTE = '_storage'
+
+def bucket(name=None, app=None):
+ """Returns a handle to a Google Cloud Storage bucket.
+
+ If the name argument is not provided, uses the 'storageBucket' option specified when
+ initializing the App. If that is also not available raises an error. This function
+ does not make any RPC calls.
+
+ Args:
+ name: Name of a cloud storage bucket (optional).
+ app: An App instance (optional).
+
+ Returns:
+ google.cloud.storage.Bucket: A handle to the specified bucket.
+
+ Raises:
+ ValueError: If a bucket name is not specified either via options or method arguments,
+ or if the specified bucket name is not a valid string.
+ """
+ client = utils.get_app_service(app, _STORAGE_ATTRIBUTE, _StorageClient.from_app)
+ return client.bucket(name)
+
+
+class _StorageClient(object):
+ """Holds a Google Cloud Storage client instance."""
+
+ def __init__(self, credentials, project, default_bucket):
+ self._client = storage.Client(credentials=credentials, project=project)
+ self._default_bucket = default_bucket
+
+ @classmethod
+ def from_app(cls, app):
+ credentials = app.credential.get_credential()
+ # Specifying project ID is not required, but providing it when available
+ # significantly speeds up the initialization of the storage client.
+ try:
+ project = app.credential.project_id
+ except AttributeError:
+ project = None
+ default_bucket = app.options.get('storageBucket')
+ return _StorageClient(credentials, project, default_bucket)
+
+ def bucket(self, name=None):
+ """Returns a handle to the specified Cloud Storage Bucket."""
+ bucket_name = name if name is not None else self._default_bucket
+ if bucket_name is None:
+ raise ValueError(
+ 'Storage bucket name not specified. Specify the bucket name via the '
+ '"storageBucket" option when initializing the App, or specify the bucket '
+ 'name explicitly when calling the storage.bucket() function.')
+ elif not bucket_name or not isinstance(bucket_name, six.string_types):
+ raise ValueError(
+ 'Invalid storage bucket name: "{0}". Bucket name must be a non-empty '
+ 'string.'.format(bucket_name))
+ return self._client.bucket(bucket_name)

integration/conftest.py

@@ -42,6 +42,11 @@ def integration_conf(request):
  raise ValueError('Failed to determine project ID from service account certificate.')
  return credentials.Certificate(cert_path), project_id
 
+@pytest.fixture(scope='session')
+def project_id(request):
+ _, project_id = integration_conf(request)
+ return project_id
+
 @pytest.fixture(autouse=True, scope='session')
 def default_app(request):
  """Initializes the default Firebase App instance used for all integration tests.
@@ -51,7 +56,10 @@ def default_app(request):
  test cases having to call it explicitly.
  """
  cred, project_id = integration_conf(request)
- ops = {'databaseURL' : 'https://{0}.firebaseio.com'.format(project_id)}
+ ops = {
+ 'databaseURL' : 'https://{0}.firebaseio.com'.format(project_id),
+ 'storageBucket' : '{0}.appspot.com'.format(project_id)
+ }
  return firebase_admin.initialize_app(cred, ops)
 
 @pytest.fixture(scope='session')

integration/test_storage.py

@@ -0,0 +1,44 @@
+# 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.storage module."""
+import time
+
+from firebase_admin import storage
+
+
+def test_default_bucket(project_id):
+ bucket = storage.bucket()
+ _verify_bucket(bucket, '{0}.appspot.com'.format(project_id))
+
+def test_custom_bucket(project_id):
+ bucket_name = '{0}.appspot.com'.format(project_id)
+ bucket = storage.bucket(bucket_name)
+ _verify_bucket(bucket, bucket_name)
+
+def test_non_existing_bucket():
+ bucket = storage.bucket('non.existing')
+ assert bucket.exists() is False
+
+def _verify_bucket(bucket, expected_name):
+ assert bucket.name == expected_name
+ file_name = 'data_{0}.txt'.format(int(time.time()))
+ blob = bucket.blob(file_name)
+ blob.upload_from_string('Hello World')
+
+ blob = bucket.get_blob(file_name)
+ assert blob.download_as_string() == 'Hello World'
+
+ bucket.delete_blob(file_name)
+ assert not bucket.get_blob(file_name)

requirements.txt

@@ -4,5 +4,6 @@ pytest-cov >= 2.4.0
 tox >= 2.6.0
 
 google-auth >= 1.0.0
+google-cloud-storage >= 1.2.0
 requests >= 2.13.0
 six >= 1.6.1

setup.py

@@ -33,6 +33,7 @@
  'to integrate Firebase into their services and applications.')
 install_requires = [
  'google-auth>=1.0.0',
+ 'google-cloud-storage>=1.2.0',
  'requests>=2.13.0',
  'six>=1.6.1'
 ]

tests/test_app.py

@@ -19,6 +19,7 @@
 
 import firebase_admin
 from firebase_admin import credentials
+from firebase_admin import utils
 from tests import testutils
 
 
@@ -68,6 +69,11 @@ def get(self):
  return None
 
 
+class AppService(object):
+ def __init__(self, app):
+ self._app = app
+
+
 @pytest.fixture(params=[Cert(), RefreshToken(), ExplicitAppDefault(), ImplicitAppDefault()],
  ids=['cert', 'refreshtoken', 'explicit-appdefault', 'implicit-appdefault'])
 def app_credential(request):
@@ -159,3 +165,12 @@ def test_app_delete(self, init_app):
  firebase_admin.get_app(init_app.name)
  with pytest.raises(ValueError):
  firebase_admin.delete_app(init_app)
+
+ def test_app_services(self, init_app):
+ service = utils.get_app_service(init_app, 'test.service', AppService)
+ assert isinstance(service, AppService)
+ service2 = utils.get_app_service(init_app, 'test.service', AppService)
+ assert service is service2
+ firebase_admin.delete_app(init_app)
+ with pytest.raises(ValueError):
+ utils.get_app_service(init_app, 'test.service', AppService)

tests/test_storage.py

@@ -0,0 +1,45 @@
+# 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.storage."""
+
+import pytest
+
+import firebase_admin
+from firebase_admin import credentials
+from firebase_admin import storage
+from tests import testutils
+
+
+def setup_module():
+ cred = credentials.Certificate(testutils.resource_filename('service_account.json'))
+ firebase_admin.initialize_app(cred)
+
+def teardown_module():
+ testutils.cleanup_apps()
+
+def test_invalid_config():
+ with pytest.raises(ValueError):
+ storage.bucket()
+
+@pytest.mark.parametrize('name', [None, '', 0, 1, True, False, list(), tuple(), dict()])
+def test_invalid_name(name):
+ with pytest.raises(ValueError):
+ storage.bucket(name)
+
+def test_valid_name():
+ # Should not make RPC calls.
+ bucket = storage.bucket('foo')
+ assert bucket is not None
+ assert bucket.name == 'foo'