Merge pull request #526 from dhermes/fill-out-datastore-namespace

Moving public classes into datastore package.

Author: dhermes

README.rst

@@ -67,11 +67,8 @@ with the Cloud Datastore using this Client Library.
     from gcloud import datastore
     datastore.set_defaults()
     # Then do other things...
-    from gcloud.datastore.entity import Entity
-    from gcloud.datastore.key import Key
-    from gcloud.datastore.query import Query
-    query = Query(kind='EntityKind')
-    entity = Entity(key=Key('EntityKind'))
+    query = datastore.Query(kind='EntityKind')
+    entity = datastore.Entity(key=datastore.Key('EntityKind'))
 
 Google Cloud Storage
 --------------------

docs/_components/datastore-getting-started.rst

@@ -39,12 +39,9 @@ Open a Python console and...
 
   >>> from gcloud import datastore
   >>> datastore.set_defaults()
-  >>> from gcloud.datastore.query import Query
-  >>> list(Query(kind='Person').fetch())
+  >>> list(datastore.Query(kind='Person').fetch())
   []
-  >>> from gcloud.datastore.entity import Entity
-  >>> from gcloud.datastore.key import Key
-  >>> entity = Entity(key=Key('Person'))
+  >>> entity = datastore.Entity(key=datastore.Key('Person'))
   >>> entity['name'] = 'Your name'
   >>> entity['age'] = 25
   >>> entity.save()

docs/_components/datastore-quickstart.rst

@@ -54,14 +54,12 @@ and initializing the demo settings::
 Once you have initialized,
 you can create entities and save them::
 
-  >>> from gcloud.datastore.entity import Entity
-  >>> from gcloud.datastore.key import Key
-  >>> entity = Entity(key=Key('Person'))
+  >>> from gcloud import datastore
+  >>> entity = datastore.Entity(key=datastore.Key('Person'))
   >>> entity['name'] = 'Your name'
   >>> entity['age'] = 25
   >>> entity.save()
-  >>> from gcloud.datastore.query import Query
-  >>> list(Query(kind='Person').fetch())
+  >>> list(datastore.Query(kind='Person').fetch())
   [<Entity{...} {'name': 'Your name', 'age': 25}>]
 
 ----

docs/index.rst

@@ -31,9 +31,7 @@ Cloud Datastore
   from gcloud import datastore
   datastore.set_defaults()
 
-  from gcloud.datastore.entity import Entity
-  from gcloud.datastore.key import Key
-  entity = Entity(key=Key('Person'))
+  entity = datastore.Entity(key=datastore.Key('Person'))
   entity['name'] = 'Your name'
   entity['age'] = 25
   entity.save()

gcloud/datastore/__init__.py

@@ -17,15 +17,12 @@
 You'll typically use these to get started with the API:
 
 >>> from gcloud import datastore
->>> from gcloud.datastore.entity import Entity
->>> from gcloud.datastore.key import Key
->>> from gcloud.datastore.query import Query
 
 >>> datastore.set_defaults()
 
->>> key = Key('EntityKind', 1234)
->>> entity = Entity(key)
->>> query = Query(kind='EntityKind')
+>>> key = datastore.Key('EntityKind', 1234)
+>>> entity = datastore.Entity(key)
+>>> query = datastore.Query(kind='EntityKind')
 
 The main concepts with this API are:
 
@@ -55,7 +52,12 @@
 from gcloud.datastore import _implicit_environ
 from gcloud.datastore.api import allocate_ids
 from gcloud.datastore.api import get
+from gcloud.datastore.batch import Batch
 from gcloud.datastore.connection import Connection
+from gcloud.datastore.entity import Entity
+from gcloud.datastore.key import Key
+from gcloud.datastore.query import Query
+from gcloud.datastore.transaction import Transaction
 
 
 SCOPE = ('https://www.googleapis.com/auth/datastore',
@@ -121,11 +123,10 @@ def get_connection():
     with the same set of credentials (unlikely):
 
     >>> from gcloud import datastore
-    >>> from gcloud.datastore import Key
 
     >>> connection = datastore.get_connection()
-    >>> key1 = Key('Kind', 1234, dataset_id='dataset1')
-    >>> key2 = Key('Kind', 1234, dataset_id='dataset2')
+    >>> key1 = datastore.Key('Kind', 1234, dataset_id='dataset1')
+    >>> key2 = datastore.Key('Kind', 1234, dataset_id='dataset2')
     >>> entity1 = datastore.get(key1, connection=connection)
     >>> entity2 = datastore.get(key2, connection=connection)
 

gcloud/datastore/connection.py

@@ -169,9 +169,8 @@ def lookup(self, dataset_id, key_pbs,
         under the hood in :func:`gcloud.datastore.get`:
 
         >>> from gcloud import datastore
-        >>> from gcloud.datastore.key import Key
         >>> datastore.set_defaults()
-        >>> key = Key('MyKind', 1234, dataset_id='dataset-id')
+        >>> key = datastore.Key('MyKind', 1234, dataset_id='dataset-id')
         >>> datastore.get(key)
         <Entity object>
 
@@ -261,11 +260,10 @@ def run_query(self, dataset_id, query_pb, namespace=None, eventual=False):
         uses this method to fetch data:
 
         >>> from gcloud import datastore
-        >>> from gcloud.datastore.query import Query
 
         >>> datastore.set_defaults()
 
-        >>> query = Query(kind='MyKind')
+        >>> query = datastore.Query(kind='MyKind')
         >>> query.add_filter('property', '=', 'val')
 
         Using the query's ``fetch_page`` method...

gcloud/datastore/demo/demo.py

@@ -19,25 +19,25 @@
 from gcloud.datastore import demo
 demo.initialize()
 
+# Let's import the package containing our helper classes:
+from gcloud import datastore
+
 # Let's create a new entity of type "Thing" and name it 'Toy':
-from gcloud.datastore.key import Key
-key = Key('Thing')
-from gcloud.datastore.entity import Entity
-toy = Entity(key)
+key = datastore.Key('Thing')
+toy = datastore.Entity(key)
 toy.update({'name': 'Toy'})
 
 # Now let's save it to our datastore:
 toy.save()
 
 # If we look it up by its key, we should find it...
-from gcloud.datastore import get
-print(get([toy.key]))
+print(datastore.get([toy.key]))
 
 # And we should be able to delete it...
 toy.key.delete()
 
 # Since we deleted it, if we do another lookup it shouldn't be there again:
-print(get([toy.key]))
+print(datastore.get([toy.key]))
 
 # Now let's try a more advanced query.
 # First, let's create some entities.
@@ -50,15 +50,14 @@
     (6789, 'Computer', 13)]
 samples = []
 for id, name, age in SAMPLE_DATA:
-    key = Key('Thing', id)
+    key = datastore.Key('Thing', id)
     samples.append(key)
-    entity = Entity(key)
+    entity = datastore.Entity(key)
     entity['name'] = name
     entity['age'] = age
     entity.save()
 # We'll start by look at all Thing entities:
-from gcloud.datastore.query import Query
-query = Query(kind='Thing')
+query = datastore.Query(kind='Thing')
 
 # Let's look at the first two.
 print(list(query.fetch(limit=2)))
@@ -77,17 +76,16 @@
 
 # You can also work inside a transaction.
 # (Check the official docs for explanations of what's happening here.)
-from gcloud.datastore.transaction import Transaction
-with Transaction():
-    print('Creating and savng an entity...')
-    key = Key('Thing', 'foo')
-    thing = Entity(key)
+with datastore.Transaction():
+    print('Creating and saving an entity...')
+    key = datastore.Key('Thing', 'foo')
+    thing = datastore.Entity(key)
     thing['age'] = 10
     thing.save()
 
     print('Creating and saving another entity...')
-    key2 = Key('Thing', 'bar')
-    thing2 = Entity(key2)
+    key2 = datastore.Key('Thing', 'bar')
+    thing2 = datastore.Entity(key2)
     thing2['age'] = 15
     thing2.save()
 
@@ -97,21 +95,21 @@
 print(key.delete(), key2.delete())
 
 # To rollback a transaction, just call .rollback()
-with Transaction() as t:
-    key = Key('Thing', 'another')
-    thing = Entity(key)
+with datastore.Transaction() as t:
+    key = datastore.Key('Thing', 'another')
+    thing = datastore.Entity(key)
     thing.save()
     t.rollback()
 
 # Let's check if the entity was actually created:
-created = get([key])
+created = datastore.get([key])
 print('yes' if created else 'no')
 
 # Remember, a key won't be complete until the transaction is commited.
 # That is, while inside the transaction block, thing.key will be incomplete.
-with Transaction():
-    key = Key('Thing')  # partial
-    thing = Entity(key)
+with datastore.Transaction():
+    key = datastore.Key('Thing')  # partial
+    thing = datastore.Entity(key)
     thing.save()
     print(thing.key)  # This will still be partial
 

regression/clear_datastore.py

@@ -14,12 +14,9 @@
 
 """Script to populate datastore with regression test data."""
 
+from six.moves import input
 
 from gcloud import datastore
-from gcloud.datastore import _implicit_environ
-from gcloud.datastore.query import Query
-from gcloud.datastore.transaction import Transaction
-from six.moves import input
 
 
 datastore._DATASET_ENV_VAR_NAME = 'GCLOUD_TESTS_DATASET_ID'
@@ -39,7 +36,7 @@
 
 def fetch_keys(kind, fetch_max=FETCH_MAX, query=None, cursor=None):
     if query is None:
-        query = Query(kind=kind, projection=['__key__'])
+        query = datastore.Query(kind=kind, projection=['__key__'])
 
     iterator = query.fetch(limit=fetch_max, start_cursor=cursor)
 
@@ -64,7 +61,7 @@ def delete_entities(entities):
 
     dataset_id = dataset_ids.pop()
     key_pbs = [entity.key.to_protobuf() for entity in entities]
-    _implicit_environ.CONNECTION.delete_entities(dataset_id, key_pbs)
+    datastore.get_connection().delete_entities(dataset_id, key_pbs)
 
 
 def remove_kind(kind):
@@ -81,7 +78,7 @@ def remove_kind(kind):
         return
 
     delete_outside_transaction = False
-    with Transaction():
+    with datastore.Transaction():
         # Now that we have all results, we seek to delete.
         print('Deleting keys:')
         print(results)

regression/datastore.py

@@ -17,10 +17,6 @@
 import unittest2
 
 from gcloud import datastore
-from gcloud.datastore.entity import Entity
-from gcloud.datastore.key import Key
-from gcloud.datastore.query import Query
-from gcloud.datastore.transaction import Transaction
 # This assumes the command is being run via tox hence the
 # repository root is the current directory.
 from regression import populate_datastore
@@ -36,7 +32,7 @@ def setUp(self):
         self.case_entities_to_delete = []
 
     def tearDown(self):
-        with Transaction():
+        with datastore.Transaction():
             for entity in self.case_entities_to_delete:
                 entity.key.delete()
 
@@ -45,7 +41,7 @@ class TestDatastoreAllocateIDs(TestDatastore):
 
     def test_allocate_ids(self):
         num_ids = 10
-        allocated_keys = datastore.allocate_ids(Key('Kind'), num_ids)
+        allocated_keys = datastore.allocate_ids(datastore.Key('Kind'), num_ids)
         self.assertEqual(len(allocated_keys), num_ids)
 
         unique_ids = set()
@@ -70,7 +66,7 @@ def _get_post(self, id_or_name=None, post_content=None):
             'rating': 5.0,
         }
         # Create an entity with the given content.
-        entity = Entity(key=Key('Post'))
+        entity = datastore.Entity(key=datastore.Key('Post'))
         entity.update(post_content)
 
         # Update the entity key.
@@ -112,7 +108,7 @@ def test_post_with_generated_id(self):
         self._generic_test_post()
 
     def test_save_multiple(self):
-        with Transaction():
+        with datastore.Transaction():
             entity1 = self._get_post()
             entity1.save()
             # Register entity to be deleted.
@@ -137,23 +133,23 @@ def test_save_multiple(self):
         self.assertEqual(len(matches), 2)
 
     def test_empty_kind(self):
-        query = Query(kind='Post')
+        query = datastore.Query(kind='Post')
         posts = list(query.fetch(limit=2))
         self.assertEqual(posts, [])
 
 
 class TestDatastoreSaveKeys(TestDatastore):
 
     def test_save_key_self_reference(self):
-        key = Key('Person', 'name')
-        entity = Entity(key=key)
+        key = datastore.Key('Person', 'name')
+        entity = datastore.Entity(key=key)
         entity['fullName'] = u'Full name'
         entity['linkedTo'] = key  # Self reference.
 
         entity.save()
         self.case_entities_to_delete.append(entity)
 
-        query = Query(kind='Person')
+        query = datastore.Query(kind='Person')
         query.add_filter('linkedTo', '=', key)
 
         stored_persons = list(query.fetch(limit=2))
@@ -171,10 +167,10 @@ class TestDatastoreQuery(TestDatastore):
     def setUpClass(cls):
         super(TestDatastoreQuery, cls).setUpClass()
         cls.CHARACTERS = populate_datastore.CHARACTERS
-        cls.ANCESTOR_KEY = Key(*populate_datastore.ANCESTOR)
+        cls.ANCESTOR_KEY = datastore.Key(*populate_datastore.ANCESTOR)
 
     def _base_query(self):
-        return Query(kind='Character', ancestor=self.ANCESTOR_KEY)
+        return datastore.Query(kind='Character', ancestor=self.ANCESTOR_KEY)
 
     def test_limit_queries(self):
         limit = 5
@@ -219,7 +215,7 @@ def test_ancestor_query(self):
         self.assertEqual(len(entities), expected_matches)
 
     def test_query___key___filter(self):
-        rickard_key = Key(*populate_datastore.RICKARD)
+        rickard_key = datastore.Key(*populate_datastore.RICKARD)
 
         query = self._base_query()
         query.add_filter('__key__', '=', rickard_key)
@@ -341,10 +337,10 @@ def test_query_group_by(self):
 class TestDatastoreTransaction(TestDatastore):
 
     def test_transaction(self):
-        entity = Entity(key=Key('Company', 'Google'))
+        entity = datastore.Entity(key=datastore.Key('Company', 'Google'))
         entity['url'] = u'www.google.com'
 
-        with Transaction():
+        with datastore.Transaction():
             retrieved_entity = datastore.get(entity.key)
             if retrieved_entity is None:
                 entity.save()