diff --git a/docs/datastore-api.rst b/docs/datastore-api.rst index 157e9d7beba2..93a042eb1651 100644 --- a/docs/datastore-api.rst +++ b/docs/datastore-api.rst @@ -17,14 +17,6 @@ Connections :undoc-members: :show-inheritance: -Credentials ------------ - -.. automodule:: gcloud.datastore.credentials - :members: - :undoc-members: - :show-inheritance: - Datasets -------- diff --git a/gcloud/datastore/__init__.py b/gcloud/datastore/__init__.py index b7ee04221321..45b8f39e3af5 100644 --- a/gcloud/datastore/__init__.py +++ b/gcloud/datastore/__init__.py @@ -2,10 +2,10 @@ You'll typically use these to get started with the API: ->>> import gcloud.datastore ->>> dataset = gcloud.datastore.get_dataset('dataset-id-here', - 'long-email@googleapis.com', - '/path/to/private.key') +>>> from gcloud import datastore +>>> dataset = datastore.get_dataset('dataset-id-here', +... 'long-email@googleapis.com', +... '/path/to/private.key') >>> # Then do other things... >>> query = dataset.query().kind('EntityKind') >>> entity = dataset.entity('EntityKind') @@ -46,8 +46,8 @@ def get_connection(client_email, private_key_path): Use this if you are going to access several datasets with the same set of credentials (unlikely): - >>> import gcloud.datastore - >>> connection = gcloud.datastore.get_connection(email, key_path) + >>> from gcloud import datastore + >>> connection = datastore.get_connection(email, key_path) >>> dataset1 = connection.dataset('dataset1') >>> dataset2 = connection.dataset('dataset2') @@ -74,8 +74,8 @@ def get_dataset(dataset_id, client_email, private_key_path): You'll generally use this as the first call to working with the API: - >>> import gcloud.datastore - >>> dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path) + >>> from gcloud import datastore + >>> dataset = datastore.get_dataset('dataset-id', email, key_path) >>> # Now you can do things with the dataset. >>> dataset.query().kind('TestKind').fetch() [...] diff --git a/gcloud/datastore/connection.py b/gcloud/datastore/connection.py index 983ace032b89..473e31edc94c 100644 --- a/gcloud/datastore/connection.py +++ b/gcloud/datastore/connection.py @@ -195,8 +195,8 @@ def run_query(self, dataset_id, query_pb, namespace=None): Under the hood, the :class:`gcloud.datastore.query.Query` class uses this method to fetch data: - >>> import gcloud.datastore - >>> connection = gcloud.datastore.get_connection(email, key_path) + >>> from gcloud import datastore + >>> connection = datastore.get_connection(email, key_path) >>> dataset = connection.dataset('dataset-id') >>> query = dataset.query().kind('MyKind').filter('property =', 'value') @@ -238,9 +238,9 @@ def lookup(self, dataset_id, key_pbs): and is used under the hood for methods like :func:`gcloud.datastore.dataset.Dataset.get_entity`: - >>> import gcloud.datastore + >>> from gcloud import datastore >>> from gcloud.datastore.key import Key - >>> connection = gcloud.datastore.get_connection(email, key_path) + >>> connection = datastore.get_connection(email, key_path) >>> dataset = connection.dataset('dataset-id') >>> key = Key(dataset=dataset).kind('MyKind').id(1234) diff --git a/gcloud/datastore/query.py b/gcloud/datastore/query.py index 355ab13f81b2..46c34c1e0933 100644 --- a/gcloud/datastore/query.py +++ b/gcloud/datastore/query.py @@ -31,8 +31,8 @@ class Query(object): which generates a query that can be executed without any additional work:: - >>> import gcloud.datastore - >>> dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path) + >>> from gcloud import datastore + >>> dataset = datastore.get_dataset('dataset-id', email, key_path) >>> query = dataset.query('MyKind') :type kind: string @@ -217,8 +217,8 @@ def fetch(self, limit=None): For example:: - >>> import gcloud.datastore - >>> dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path) + >>> from gcloud import datastore + >>> dataset = datastore.get_dataset('dataset-id', email, key_path) >>> query = dataset.query('Person').filter('name =', 'Sally') >>> query.fetch() [, , ...] diff --git a/gcloud/datastore/transaction.py b/gcloud/datastore/transaction.py index 7d8ae471f135..7c73af0a7371 100644 --- a/gcloud/datastore/transaction.py +++ b/gcloud/datastore/transaction.py @@ -15,22 +15,22 @@ class Transaction(object): (either ``insert_auto_id`` or ``upsert``) into the same mutation, and execute those within a transaction:: - import gcloud.datastore - dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path) - with dataset.transaction(bulk_mutation=True) # The default. - entity1.save() - entity2.save() + >>> from gcloud import datastore + >>> dataset = datastore.get_dataset('dataset-id', email, key_path) + >>> with dataset.transaction(bulk_mutation=True) # The default. + ... entity1.save() + ... entity2.save() To rollback a transaction if there is an error:: - import gcloud.datastore - dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path) - with dataset.transaction() as t: - try: - do_some_work() - entity1.save() - except: - t.rollback() + >>> from gcloud import datastore + >>> dataset = datastore.get_dataset('dataset-id', email, key_path) + >>> with dataset.transaction() as t: + ... try: + ... do_some_work() + ... entity1.save() + ... except: + ... t.rollback() If the transaction isn't rolled back, it will commit by default. @@ -42,8 +42,8 @@ class Transaction(object): That means, if you try:: - with dataset.transaction(): - entity = dataset.entity('Thing').save() + >>> with dataset.transaction(): + ... entity = dataset.entity('Thing').save() ``entity`` won't have a complete Key until the transaction is committed. @@ -52,12 +52,11 @@ class Transaction(object): the automatically generated ID will be assigned to the entity:: - with dataset.transaction(): - entity = dataset.entity('Thing') - entity.save() - assert entity.key().is_partial() # There is no ID on this key. - - assert not entity.key().is_partial() # There *is* an ID on this key. + >>> with dataset.transaction(): + ... entity = dataset.entity('Thing') + ... entity.save() + ... assert entity.key().is_partial() # There is no ID on this key. + >>> assert not entity.key().is_partial() # There *is* an ID on this key. .. warning:: If you're using the automatically generated ID functionality, @@ -73,16 +72,16 @@ class Transaction(object): If you don't want to use the context manager you can initialize a transaction manually:: - transaction = dataset.transaction() - transaction.begin() + >>> transaction = dataset.transaction() + >>> transaction.begin() - entity = dataset.entity('Thing') - entity.save() + >>> entity = dataset.entity('Thing') + >>> entity.save() - if error: - transaction.rollback() - else: - transaction.commit() + >>> if error: + ... transaction.rollback() + ... else: + ... transaction.commit() For now, this library will enforce a rule of @@ -95,31 +94,31 @@ class Transaction(object): For example, this is perfectly valid:: - import gcloud.datastore - dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path) - with dataset.transaction(): - dataset.entity('Thing').save() + >>> from gcloud import datastore + >>> dataset = datastore.get_dataset('dataset-id', email, key_path) + >>> with dataset.transaction(): + ... dataset.entity('Thing').save() However, this **wouldn't** be acceptable:: - import gcloud.datastore - dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path) - with dataset.transaction(): - dataset.entity('Thing').save() - with dataset.transaction(): - dataset.entity('Thing').save() + >>> from gcloud import datastore + >>> dataset = datastore.get_dataset('dataset-id', email, key_path) + >>> with dataset.transaction(): + ... dataset.entity('Thing').save() + ... with dataset.transaction(): + ... dataset.entity('Thing').save() Technically, it looks like the Protobuf API supports this type of pattern, however it makes the code particularly messy. If you really need to nest transactions, try:: - import gcloud.datastore - dataset1 = gcloud.datastore.get_dataset('dataset-id', email, key_path) - dataset2 = gcloud.datastore.get_dataset('dataset-id', email, key_path) - with dataset1.transaction(): - dataset1.entity('Thing').save() - with dataset2.transaction(): - dataset2.entity('Thing').save() + >>> from gcloud import datastore + >>> dataset1 = datastore.get_dataset('dataset-id', email, key_path) + >>> dataset2 = datastore.get_dataset('dataset-id', email, key_path) + >>> with dataset1.transaction(): + ... dataset1.entity('Thing').save() + ... with dataset2.transaction(): + ... dataset2.entity('Thing').save() :type dataset: :class:`gcloud.datastore.dataset.Dataset` :param dataset: The dataset to which this :class:`Transaction` belongs.