From 803e3bc14a8cb6ac7356c3f51252dea9a8b87dd5 Mon Sep 17 00:00:00 2001 From: Danny Hermes Date: Thu, 8 Jan 2015 16:54:07 -0800 Subject: [PATCH] Moving public classes into datastore package. Also updating docs to reflect this. --- README.rst | 7 +-- .../_components/datastore-getting-started.rst | 7 +-- docs/_components/datastore-quickstart.rst | 8 ++-- docs/index.rst | 4 +- gcloud/datastore/__init__.py | 19 ++++---- gcloud/datastore/connection.py | 6 +-- gcloud/datastore/demo/demo.py | 48 +++++++++---------- regression/clear_datastore.py | 11 ++--- regression/datastore.py | 30 +++++------- regression/populate_datastore.py | 7 +-- 10 files changed, 62 insertions(+), 85 deletions(-) diff --git a/README.rst b/README.rst index 1d0d6a564369..f481b2d86486 100644 --- a/README.rst +++ b/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 -------------------- diff --git a/docs/_components/datastore-getting-started.rst b/docs/_components/datastore-getting-started.rst index a20aa3a84781..98ae01a152ee 100644 --- a/docs/_components/datastore-getting-started.rst +++ b/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() diff --git a/docs/_components/datastore-quickstart.rst b/docs/_components/datastore-quickstart.rst index 7a14a61d320d..0112d9a8afb0 100644 --- a/docs/_components/datastore-quickstart.rst +++ b/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()) [] ---- diff --git a/docs/index.rst b/docs/index.rst index 0c85bc31093d..4f1e24bbb89f 100644 --- a/docs/index.rst +++ b/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() diff --git a/gcloud/datastore/__init__.py b/gcloud/datastore/__init__.py index 44948b1a6ea6..2425398be7bf 100644 --- a/gcloud/datastore/__init__.py +++ b/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) diff --git a/gcloud/datastore/connection.py b/gcloud/datastore/connection.py index f7478abbc3c2..ec3253a3b281 100644 --- a/gcloud/datastore/connection.py +++ b/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) @@ -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... diff --git a/gcloud/datastore/demo/demo.py b/gcloud/datastore/demo/demo.py index ce653ebfd852..6175a7adcced 100644 --- a/gcloud/datastore/demo/demo.py +++ b/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 diff --git a/regression/clear_datastore.py b/regression/clear_datastore.py index ad79924c29f9..6923ee76bba6 100644 --- a/regression/clear_datastore.py +++ b/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) diff --git a/regression/datastore.py b/regression/datastore.py index 2a1f00b5c373..057cad270e4b 100644 --- a/regression/datastore.py +++ b/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,7 +133,7 @@ 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, []) @@ -145,15 +141,15 @@ def test_empty_kind(self): 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() diff --git a/regression/populate_datastore.py b/regression/populate_datastore.py index d6939e672049..2e61b2ee53cc 100644 --- a/regression/populate_datastore.py +++ b/regression/populate_datastore.py @@ -17,9 +17,6 @@ from six.moves import zip from gcloud import datastore -from gcloud.datastore.entity import Entity -from gcloud.datastore.key import Key -from gcloud.datastore.transaction import Transaction datastore._DATASET_ENV_VAR_NAME = 'GCLOUD_TESTS_DATASET_ID' @@ -85,12 +82,12 @@ def add_characters(): - with Transaction(): + with datastore.Transaction(): for key_path, character in zip(KEY_PATHS, CHARACTERS): if key_path[-1] != character['name']: raise ValueError(('Character and key don\'t agree', key_path, character)) - entity = Entity(key=Key(*key_path)) + entity = datastore.Entity(key=datastore.Key(*key_path)) entity.update(character) entity.save() print('Adding Character %s %s' % (character['name'],