Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Automatic update of documentation. #51

Merged
merged 1 commit into from Feb 24, 2014
Merged

Automatic update of documentation. #51

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
16 changes: 8 additions & 8 deletions _modules/gcloud/datastore/__init__.html
View file
Open in desktop
Expand Up @@ -85,10 +85,10 @@ <h1>Source code for gcloud.datastore.__init__</h1><div class="highlight"><pre>

<span class="sd">You&#39;ll typically use these to get started with the API:</span>

<span class="sd">&gt;&gt;&gt; import gcloud.datastore</span>
<span class="sd">&gt;&gt;&gt; dataset = gcloud.datastore.get_dataset(&#39;dataset-id-here&#39;,</span>
<span class="sd"> &#39;long-email@googleapis.com&#39;,</span>
<span class="sd"> &#39;/path/to/private.key&#39;)</span>
<span class="sd">&gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd">&gt;&gt;&gt; dataset = datastore.get_dataset(&#39;dataset-id-here&#39;,</span>
<span class="sd">... &#39;long-email@googleapis.com&#39;,</span>
<span class="sd">... &#39;/path/to/private.key&#39;)</span>
<span class="sd">&gt;&gt;&gt; # Then do other things...</span>
<span class="sd">&gt;&gt;&gt; query = dataset.query().kind(&#39;EntityKind&#39;)</span>
<span class="sd">&gt;&gt;&gt; entity = dataset.entity(&#39;EntityKind&#39;)</span>
Expand Down Expand Up @@ -129,8 +129,8 @@ <h1>Source code for gcloud.datastore.__init__</h1><div class="highlight"><pre>
<span class="sd"> Use this if you are going to access several datasets</span>
<span class="sd"> with the same set of credentials (unlikely):</span>

<span class="sd"> &gt;&gt;&gt; import gcloud.datastore</span>
<span class="sd"> &gt;&gt;&gt; connection = gcloud.datastore.get_connection(email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; connection = datastore.get_connection(email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; dataset1 = connection.dataset(&#39;dataset1&#39;)</span>
<span class="sd"> &gt;&gt;&gt; dataset2 = connection.dataset(&#39;dataset2&#39;)</span>

Expand All @@ -157,8 +157,8 @@ <h1>Source code for gcloud.datastore.__init__</h1><div class="highlight"><pre>

<span class="sd"> You&#39;ll generally use this as the first call to working with the API:</span>

<span class="sd"> &gt;&gt;&gt; import gcloud.datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = gcloud.datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; # Now you can do things with the dataset.</span>
<span class="sd"> &gt;&gt;&gt; dataset.query().kind(&#39;TestKind&#39;).fetch()</span>
<span class="sd"> [...]</span>
Expand Down
8 changes: 4 additions & 4 deletions _modules/gcloud/datastore/connection.html
View file
Open in desktop
Expand Up @@ -278,8 +278,8 @@ <h1>Source code for gcloud.datastore.connection</h1><div class="highlight"><pre>
<span class="sd"> Under the hood, the :class:`gcloud.datastore.query.Query` class</span>
<span class="sd"> uses this method to fetch data:</span>

<span class="sd"> &gt;&gt;&gt; import gcloud.datastore</span>
<span class="sd"> &gt;&gt;&gt; connection = gcloud.datastore.get_connection(email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; connection = datastore.get_connection(email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; dataset = connection.dataset(&#39;dataset-id&#39;)</span>
<span class="sd"> &gt;&gt;&gt; query = dataset.query().kind(&#39;MyKind&#39;).filter(&#39;property =&#39;, &#39;value&#39;)</span>

Expand Down Expand Up @@ -321,9 +321,9 @@ <h1>Source code for gcloud.datastore.connection</h1><div class="highlight"><pre>
<span class="sd"> and is used under the hood for methods like</span>
<span class="sd"> :func:`gcloud.datastore.dataset.Dataset.get_entity`:</span>

<span class="sd"> &gt;&gt;&gt; import gcloud.datastore</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; from gcloud.datastore.key import Key</span>
<span class="sd"> &gt;&gt;&gt; connection = gcloud.datastore.get_connection(email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; connection = datastore.get_connection(email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; dataset = connection.dataset(&#39;dataset-id&#39;)</span>
<span class="sd"> &gt;&gt;&gt; key = Key(dataset=dataset).kind(&#39;MyKind&#39;).id(1234)</span>

Expand Down
8 changes: 4 additions & 4 deletions _modules/gcloud/datastore/query.html
View file
Open in desktop
Expand Up @@ -114,8 +114,8 @@ <h1>Source code for gcloud.datastore.query</h1><div class="highlight"><pre>
<span class="sd"> which generates a query that can be executed</span>
<span class="sd"> without any additional work::</span>

<span class="sd"> &gt;&gt;&gt; import gcloud.datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = gcloud.datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; query = dataset.query(&#39;MyKind&#39;)</span>

<span class="sd"> :type kind: string</span>
Expand Down Expand Up @@ -300,8 +300,8 @@ <h1>Source code for gcloud.datastore.query</h1><div class="highlight"><pre>

<span class="sd"> For example::</span>

<span class="sd"> &gt;&gt;&gt; import gcloud.datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = gcloud.datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; query = dataset.query(&#39;Person&#39;).filter(&#39;name =&#39;, &#39;Sally&#39;)</span>
<span class="sd"> &gt;&gt;&gt; query.fetch()</span>
<span class="sd"> [&lt;Entity object&gt;, &lt;Entity object&gt;, ...]</span>
Expand Down
91 changes: 45 additions & 46 deletions _modules/gcloud/datastore/transaction.html
View file
Open in desktop
Expand Up @@ -98,22 +98,22 @@ <h1>Source code for gcloud.datastore.transaction</h1><div class="highlight"><pre
<span class="sd"> (either ``insert_auto_id`` or ``upsert``)</span>
<span class="sd"> into the same mutation, and execute those within a transaction::</span>

<span class="sd"> import gcloud.datastore</span>
<span class="sd"> dataset = gcloud.datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> with dataset.transaction(bulk_mutation=True) # The default.</span>
<span class="sd"> entity1.save()</span>
<span class="sd"> entity2.save()</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; with dataset.transaction(bulk_mutation=True) # The default.</span>
<span class="sd"> ... entity1.save()</span>
<span class="sd"> ... entity2.save()</span>

<span class="sd"> To rollback a transaction if there is an error::</span>

<span class="sd"> import gcloud.datastore</span>
<span class="sd"> dataset = gcloud.datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> with dataset.transaction() as t:</span>
<span class="sd"> try:</span>
<span class="sd"> do_some_work()</span>
<span class="sd"> entity1.save()</span>
<span class="sd"> except:</span>
<span class="sd"> t.rollback()</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; with dataset.transaction() as t:</span>
<span class="sd"> ... try:</span>
<span class="sd"> ... do_some_work()</span>
<span class="sd"> ... entity1.save()</span>
<span class="sd"> ... except:</span>
<span class="sd"> ... t.rollback()</span>

<span class="sd"> If the transaction isn&#39;t rolled back,</span>
<span class="sd"> it will commit by default.</span>
Expand All @@ -125,8 +125,8 @@ <h1>Source code for gcloud.datastore.transaction</h1><div class="highlight"><pre
<span class="sd"> That means,</span>
<span class="sd"> if you try::</span>

<span class="sd"> with dataset.transaction():</span>
<span class="sd"> entity = dataset.entity(&#39;Thing&#39;).save()</span>
<span class="sd"> &gt;&gt;&gt; with dataset.transaction():</span>
<span class="sd"> ... entity = dataset.entity(&#39;Thing&#39;).save()</span>

<span class="sd"> ``entity`` won&#39;t have a complete Key</span>
<span class="sd"> until the transaction is committed.</span>
Expand All @@ -135,12 +135,11 @@ <h1>Source code for gcloud.datastore.transaction</h1><div class="highlight"><pre
<span class="sd"> the automatically generated ID will be assigned</span>
<span class="sd"> to the entity::</span>

<span class="sd"> with dataset.transaction():</span>
<span class="sd"> entity = dataset.entity(&#39;Thing&#39;)</span>
<span class="sd"> entity.save()</span>
<span class="sd"> assert entity.key().is_partial() # There is no ID on this key.</span>

<span class="sd"> assert not entity.key().is_partial() # There *is* an ID on this key.</span>
<span class="sd"> &gt;&gt;&gt; with dataset.transaction():</span>
<span class="sd"> ... entity = dataset.entity(&#39;Thing&#39;)</span>
<span class="sd"> ... entity.save()</span>
<span class="sd"> ... assert entity.key().is_partial() # There is no ID on this key.</span>
<span class="sd"> &gt;&gt;&gt; assert not entity.key().is_partial() # There *is* an ID on this key.</span>

<span class="sd"> .. warning::</span>
<span class="sd"> If you&#39;re using the automatically generated ID functionality,</span>
Expand All @@ -156,16 +155,16 @@ <h1>Source code for gcloud.datastore.transaction</h1><div class="highlight"><pre
<span class="sd"> If you don&#39;t want to use the context manager</span>
<span class="sd"> you can initialize a transaction manually::</span>

<span class="sd"> transaction = dataset.transaction()</span>
<span class="sd"> transaction.begin()</span>
<span class="sd"> &gt;&gt;&gt; transaction = dataset.transaction()</span>
<span class="sd"> &gt;&gt;&gt; transaction.begin()</span>

<span class="sd"> entity = dataset.entity(&#39;Thing&#39;)</span>
<span class="sd"> entity.save()</span>
<span class="sd"> &gt;&gt;&gt; entity = dataset.entity(&#39;Thing&#39;)</span>
<span class="sd"> &gt;&gt;&gt; entity.save()</span>

<span class="sd"> if error:</span>
<span class="sd"> transaction.rollback()</span>
<span class="sd"> else:</span>
<span class="sd"> transaction.commit()</span>
<span class="sd"> &gt;&gt;&gt; if error:</span>
<span class="sd"> ... transaction.rollback()</span>
<span class="sd"> ... else:</span>
<span class="sd"> ... transaction.commit()</span>

<span class="sd"> For now,</span>
<span class="sd"> this library will enforce a rule of</span>
Expand All @@ -178,31 +177,31 @@ <h1>Source code for gcloud.datastore.transaction</h1><div class="highlight"><pre

<span class="sd"> For example, this is perfectly valid::</span>

<span class="sd"> import gcloud.datastore</span>
<span class="sd"> dataset = gcloud.datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> with dataset.transaction():</span>
<span class="sd"> dataset.entity(&#39;Thing&#39;).save()</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; with dataset.transaction():</span>
<span class="sd"> ... dataset.entity(&#39;Thing&#39;).save()</span>

<span class="sd"> However, this **wouldn&#39;t** be acceptable::</span>

<span class="sd"> import gcloud.datastore</span>
<span class="sd"> dataset = gcloud.datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> with dataset.transaction():</span>
<span class="sd"> dataset.entity(&#39;Thing&#39;).save()</span>
<span class="sd"> with dataset.transaction():</span>
<span class="sd"> dataset.entity(&#39;Thing&#39;).save()</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset = datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; with dataset.transaction():</span>
<span class="sd"> ... dataset.entity(&#39;Thing&#39;).save()</span>
<span class="sd"> ... with dataset.transaction():</span>
<span class="sd"> ... dataset.entity(&#39;Thing&#39;).save()</span>

<span class="sd"> Technically, it looks like the Protobuf API supports this type of pattern,</span>
<span class="sd"> however it makes the code particularly messy.</span>
<span class="sd"> If you really need to nest transactions, try::</span>

<span class="sd"> import gcloud.datastore</span>
<span class="sd"> dataset1 = gcloud.datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> dataset2 = gcloud.datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> with dataset1.transaction():</span>
<span class="sd"> dataset1.entity(&#39;Thing&#39;).save()</span>
<span class="sd"> with dataset2.transaction():</span>
<span class="sd"> dataset2.entity(&#39;Thing&#39;).save()</span>
<span class="sd"> &gt;&gt;&gt; from gcloud import datastore</span>
<span class="sd"> &gt;&gt;&gt; dataset1 = datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; dataset2 = datastore.get_dataset(&#39;dataset-id&#39;, email, key_path)</span>
<span class="sd"> &gt;&gt;&gt; with dataset1.transaction():</span>
<span class="sd"> ... dataset1.entity(&#39;Thing&#39;).save()</span>
<span class="sd"> ... with dataset2.transaction():</span>
<span class="sd"> ... dataset2.entity(&#39;Thing&#39;).save()</span>

<span class="sd"> :type dataset: :class:`gcloud.datastore.dataset.Dataset`</span>
<span class="sd"> :param dataset: The dataset to which this :class:`Transaction` belongs.</span>
Expand Down
1 change: 0 additions & 1 deletion _modules/index.html
View file
Open in desktop
Expand Up @@ -84,7 +84,6 @@ <h1>All modules for which code is available</h1>
<li><a href="gcloud/credentials.html">gcloud.credentials</a></li>
<li><a href="gcloud/datastore/__init__.html">gcloud.datastore.__init__</a></li>
<li><a href="gcloud/datastore/connection.html">gcloud.datastore.connection</a></li>
<li><a href="gcloud/datastore/credentials.html">gcloud.datastore.credentials</a></li>
<li><a href="gcloud/datastore/dataset.html">gcloud.datastore.dataset</a></li>
<li><a href="gcloud/datastore/entity.html">gcloud.datastore.entity</a></li>
<li><a href="gcloud/datastore/helpers.html">gcloud.datastore.helpers</a></li>
Expand Down
8 changes: 0 additions & 8 deletions _sources/datastore-api.txt
View file
Open in desktop
Expand Up @@ -17,14 +17,6 @@ Connections
:undoc-members:
:show-inheritance:

Credentials
-----------

.. automodule:: gcloud.datastore.credentials
:members:
:undoc-members:
:show-inheritance:

Datasets
--------

Expand Down