Merge pull request googleapis#133 from jgeewax/koss-collection-1

Additional collection methods.

firestore/google/cloud/firestore/client.py

@@ -14,6 +14,9 @@
 
 """Firestore database SDK Client."""
 
+import random
+import string
+
 import grpc
 
 import google.auth
@@ -33,6 +36,9 @@
 ALL_SCOPES = ('https://www.googleapis.com/auth/cloud-platform',
               'https://www.googleapis.com/auth/datastore')
 
+_AUTO_ID_CHARS = (string.ascii_uppercase + string.ascii_lowercase +
+                  string.digits)
+
 
 class Client(_BaseClient, _ClientProjectMixin):
     """Firestore Client.
@@ -63,6 +69,17 @@ def __init__(self, project=None, credentials=None, emulator_host=None):
         self.database_id = None
         self._api = _make_firestore_api(self._connection, emulator_host)
 
+    @staticmethod
+    def auto_id():
+        """Generate a unique client-side identifier.
+
+        Used for the creation of new Documents.
+
+        :rtype: str
+        :returns: A random unique identifier.
+        """
+        return ''.join(random.choice(_AUTO_ID_CHARS) for _ in range(20))
+
     def collection(self, collection_name):
         """Get a reference to a top-level collection.
 

firestore/google/cloud/firestore/collection.py

@@ -42,3 +42,25 @@ def document(self, doc_id):
 
         return document.DocumentRef(self._client,
                                     self._path.child(doc_id))
+
+    def add(self, value):
+        """Create a new document and save it in this colleciton.
+
+        :type value: dict
+        :param value: Dictionary of values to save to the document.
+
+        :rtype: :class:`~google.cloud.firestore.Document`
+        :returns: A ``Document`` that was saved to the database.
+        """
+        return self.new_document().set(value)
+
+    def new_document(self):
+        """Create a reference to a new ``Document`` in this collection.
+
+        New documents are created with uniquely created client-side
+        identifiers.
+
+        :rtype: :class:`~google.cloud.firestore.DocumentRef`
+        :returns: A ``DocumentRef`` to the location of a new document.
+        """
+        return self.document(self._client.auto_id())

firestore/unit_tests/test_client.py

@@ -58,6 +58,13 @@ def test_credentialed_constructor(self):
         client = self._make_one('my-project-id', credentials=creds)
         self.assertIs(client._connection.credentials, creds)
 
+    def test_auto_id(self):
+        client = self._make_one('my-project-id')
+        id1 = client.auto_id()
+        id2 = client.auto_id()
+        self.assertTrue(len(id1) >= 20)
+        self.assertNotEqual(id1, id2)
+
     def test_collection(self):
         from google.cloud.firestore._path import Path
 

firestore/unit_tests/test_collection.py

@@ -35,13 +35,42 @@ def test_constructor(self):
         self.assertIs(col_ref._client, client)
         self.assertEqual(col_ref._path, path)
 
-    def test_doc(self):
-        from google.cloud.firestore.document import DocumentRef
+    def test_document(self):
         from google.cloud.firestore._path import Path
+        from google.cloud.firestore.document import DocumentRef
 
         client = object()
-        path = Path('my-collection')
         doc_path = Path('my-collection', 'my-document')
-        col_ref = self._make_one(client, path)
+        col_ref = self._make_one(client, Path('my-collection'))
         doc_ref = col_ref.document('my-document')
         self.assertEqual(doc_ref, DocumentRef(client, doc_path))
+
+    def test_add(self):
+        import mock
+        from google.cloud.firestore._path import Path
+        from google.cloud.firestore.client import Client
+        from google.cloud.firestore.document import DocumentResult
+        from google.cloud.gapic.firestore.v1alpha1.datastore_api import (
+            DatastoreApi)
+
+        client = Client()
+        client._api = mock.MagicMock(spec=DatastoreApi)
+        col_ref = self._make_one(client, Path('my-collection'))
+        doc = col_ref.add({})
+        self.assertIsInstance(doc, DocumentResult)
+        self.assertTrue(len(doc.id) >= 20)
+
+    def test_new_document(self):
+        import mock
+        from google.cloud.firestore._path import Path
+        from google.cloud.firestore.client import Client
+        from google.cloud.firestore.document import DocumentRef
+        from google.cloud.gapic.firestore.v1alpha1.datastore_api import (
+            DatastoreApi)
+
+        client = Client()
+        client._api = mock.MagicMock(spec=DatastoreApi)
+        col_ref = self._make_one(client, Path('my-collection'))
+        doc_ref = col_ref.new_document()
+        self.assertIsInstance(doc_ref, DocumentRef)
+        self.assertTrue(len(doc_ref.id) >= 20)