Skip to content

Commit c20cbf1

Browse files
jgeewaxjgeewax
committed
Merge pull request #49 from jgeewax/transaction-docs-fix
Updated docstrings for consistency in gcloud.datastore.
2 parents b0fa299 + 39ddc2c commit c20cbf1

File tree

5 files changed

+61
-70
lines changed

5 files changed

+61
-70
lines changed

‎docs/datastore-api.rst‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -17,14 +17,6 @@ Connections
1717
:undoc-members:
1818
:show-inheritance:
1919

20-
Credentials
21-
-----------
22-
23-
.. automodule:: gcloud.datastore.credentials
24-
:members:
25-
:undoc-members:
26-
:show-inheritance:
27-
2820
Datasets
2921
--------
3022

‎gcloud/datastore/__init__.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,10 @@
22
33
You'll typically use these to get started with the API:
44
5-
>>> import gcloud.datastore
6-
>>> dataset = gcloud.datastore.get_dataset('dataset-id-here',
7-
'[email protected]',
8-
'/path/to/private.key')
5+
>>> from gcloud import datastore
6+
>>> dataset = datastore.get_dataset('dataset-id-here',
7+
... '[email protected]',
8+
... '/path/to/private.key')
99
>>> # Then do other things...
1010
>>> query = dataset.query().kind('EntityKind')
1111
>>> entity = dataset.entity('EntityKind')
@@ -46,8 +46,8 @@ def get_connection(client_email, private_key_path):
4646
Use this if you are going to access several datasets
4747
with the same set of credentials (unlikely):
4848
49-
>>> import gcloud.datastore
50-
>>> connection = gcloud.datastore.get_connection(email, key_path)
49+
>>> from gcloud import datastore
50+
>>> connection = datastore.get_connection(email, key_path)
5151
>>> dataset1 = connection.dataset('dataset1')
5252
>>> dataset2 = connection.dataset('dataset2')
5353
@@ -74,8 +74,8 @@ def get_dataset(dataset_id, client_email, private_key_path):
7474
7575
You'll generally use this as the first call to working with the API:
7676
77-
>>> import gcloud.datastore
78-
>>> dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path)
77+
>>> from gcloud import datastore
78+
>>> dataset = datastore.get_dataset('dataset-id', email, key_path)
7979
>>> # Now you can do things with the dataset.
8080
>>> dataset.query().kind('TestKind').fetch()
8181
[...]

‎gcloud/datastore/connection.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -195,8 +195,8 @@ def run_query(self, dataset_id, query_pb, namespace=None):
195195
Under the hood, the :class:`gcloud.datastore.query.Query` class
196196
uses this method to fetch data:
197197
198-
>>> import gcloud.datastore
199-
>>> connection = gcloud.datastore.get_connection(email, key_path)
198+
>>> from gcloud import datastore
199+
>>> connection = datastore.get_connection(email, key_path)
200200
>>> dataset = connection.dataset('dataset-id')
201201
>>> query = dataset.query().kind('MyKind').filter('property =', 'value')
202202
@@ -238,9 +238,9 @@ def lookup(self, dataset_id, key_pbs):
238238
and is used under the hood for methods like
239239
:func:`gcloud.datastore.dataset.Dataset.get_entity`:
240240
241-
>>> import gcloud.datastore
241+
>>> from gcloud import datastore
242242
>>> from gcloud.datastore.key import Key
243-
>>> connection = gcloud.datastore.get_connection(email, key_path)
243+
>>> connection = datastore.get_connection(email, key_path)
244244
>>> dataset = connection.dataset('dataset-id')
245245
>>> key = Key(dataset=dataset).kind('MyKind').id(1234)
246246

‎gcloud/datastore/query.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ class Query(object):
3131
which generates a query that can be executed
3232
without any additional work::
3333
34-
>>> import gcloud.datastore
35-
>>> dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path)
34+
>>> from gcloud import datastore
35+
>>> dataset = datastore.get_dataset('dataset-id', email, key_path)
3636
>>> query = dataset.query('MyKind')
3737
3838
:type kind: string
@@ -217,8 +217,8 @@ def fetch(self, limit=None):
217217
218218
For example::
219219
220-
>>> import gcloud.datastore
221-
>>> dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path)
220+
>>> from gcloud import datastore
221+
>>> dataset = datastore.get_dataset('dataset-id', email, key_path)
222222
>>> query = dataset.query('Person').filter('name =', 'Sally')
223223
>>> query.fetch()
224224
[<Entity object>, <Entity object>, ...]

‎gcloud/datastore/transaction.py‎

Lines changed: 45 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -15,22 +15,22 @@ class Transaction(object):
1515
(either ``insert_auto_id`` or ``upsert``)
1616
into the same mutation, and execute those within a transaction::
1717
18-
import gcloud.datastore
19-
dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path)
20-
with dataset.transaction(bulk_mutation=True) # The default.
21-
entity1.save()
22-
entity2.save()
18+
>>> from gcloud import datastore
19+
>>> dataset = datastore.get_dataset('dataset-id', email, key_path)
20+
>>> with dataset.transaction(bulk_mutation=True) # The default.
21+
... entity1.save()
22+
... entity2.save()
2323
2424
To rollback a transaction if there is an error::
2525
26-
import gcloud.datastore
27-
dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path)
28-
with dataset.transaction() as t:
29-
try:
30-
do_some_work()
31-
entity1.save()
32-
except:
33-
t.rollback()
26+
>>> from gcloud import datastore
27+
>>> dataset = datastore.get_dataset('dataset-id', email, key_path)
28+
>>> with dataset.transaction() as t:
29+
... try:
30+
... do_some_work()
31+
... entity1.save()
32+
... except:
33+
... t.rollback()
3434
3535
If the transaction isn't rolled back,
3636
it will commit by default.
@@ -42,8 +42,8 @@ class Transaction(object):
4242
That means,
4343
if you try::
4444
45-
with dataset.transaction():
46-
entity = dataset.entity('Thing').save()
45+
>>> with dataset.transaction():
46+
... entity = dataset.entity('Thing').save()
4747
4848
``entity`` won't have a complete Key
4949
until the transaction is committed.
@@ -52,12 +52,11 @@ class Transaction(object):
5252
the automatically generated ID will be assigned
5353
to the entity::
5454
55-
with dataset.transaction():
56-
entity = dataset.entity('Thing')
57-
entity.save()
58-
assert entity.key().is_partial() # There is no ID on this key.
59-
60-
assert not entity.key().is_partial() # There *is* an ID on this key.
55+
>>> with dataset.transaction():
56+
... entity = dataset.entity('Thing')
57+
... entity.save()
58+
... assert entity.key().is_partial() # There is no ID on this key.
59+
>>> assert not entity.key().is_partial() # There *is* an ID on this key.
6160
6261
.. warning::
6362
If you're using the automatically generated ID functionality,
@@ -73,16 +72,16 @@ class Transaction(object):
7372
If you don't want to use the context manager
7473
you can initialize a transaction manually::
7574
76-
transaction = dataset.transaction()
77-
transaction.begin()
75+
>>> transaction = dataset.transaction()
76+
>>> transaction.begin()
7877
79-
entity = dataset.entity('Thing')
80-
entity.save()
78+
>>> entity = dataset.entity('Thing')
79+
>>> entity.save()
8180
82-
if error:
83-
transaction.rollback()
84-
else:
85-
transaction.commit()
81+
>>> if error:
82+
... transaction.rollback()
83+
... else:
84+
... transaction.commit()
8685
8786
For now,
8887
this library will enforce a rule of
@@ -95,31 +94,31 @@ class Transaction(object):
9594
9695
For example, this is perfectly valid::
9796
98-
import gcloud.datastore
99-
dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path)
100-
with dataset.transaction():
101-
dataset.entity('Thing').save()
97+
>>> from gcloud import datastore
98+
>>> dataset = datastore.get_dataset('dataset-id', email, key_path)
99+
>>> with dataset.transaction():
100+
... dataset.entity('Thing').save()
102101
103102
However, this **wouldn't** be acceptable::
104103
105-
import gcloud.datastore
106-
dataset = gcloud.datastore.get_dataset('dataset-id', email, key_path)
107-
with dataset.transaction():
108-
dataset.entity('Thing').save()
109-
with dataset.transaction():
110-
dataset.entity('Thing').save()
104+
>>> from gcloud import datastore
105+
>>> dataset = datastore.get_dataset('dataset-id', email, key_path)
106+
>>> with dataset.transaction():
107+
... dataset.entity('Thing').save()
108+
... with dataset.transaction():
109+
... dataset.entity('Thing').save()
111110
112111
Technically, it looks like the Protobuf API supports this type of pattern,
113112
however it makes the code particularly messy.
114113
If you really need to nest transactions, try::
115114
116-
import gcloud.datastore
117-
dataset1 = gcloud.datastore.get_dataset('dataset-id', email, key_path)
118-
dataset2 = gcloud.datastore.get_dataset('dataset-id', email, key_path)
119-
with dataset1.transaction():
120-
dataset1.entity('Thing').save()
121-
with dataset2.transaction():
122-
dataset2.entity('Thing').save()
115+
>>> from gcloud import datastore
116+
>>> dataset1 = datastore.get_dataset('dataset-id', email, key_path)
117+
>>> dataset2 = datastore.get_dataset('dataset-id', email, key_path)
118+
>>> with dataset1.transaction():
119+
... dataset1.entity('Thing').save()
120+
... with dataset2.transaction():
121+
... dataset2.entity('Thing').save()
123122
124123
:type dataset: :class:`gcloud.datastore.dataset.Dataset`
125124
:param dataset: The dataset to which this :class:`Transaction` belongs.

0 commit comments

Comments
 (0)