Updating documentation to reflect bulk datastore API changes.

Fixes #477.

Author: dhermes

README.rst

@@ -65,10 +65,14 @@ with the Cloud Datastore using this Client Library.
 .. code:: python
 
     from gcloud import datastore
-    dataset = datastore.get_dataset('dataset-id-here')
+    datastore.set_default_connection()
+    datastore.set_default_dataset_id()
     # Then do other things...
-    query = dataset.query().kind('EntityKind')
-    entity = dataset.entity('EntityKind')
+    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'))
 
 Google Cloud Storage
 --------------------

docs/_components/datastore-getting-started.rst

@@ -38,14 +38,18 @@ Add some data to your dataset
 Open a Python console and...
 
   >>> from gcloud import datastore
-  >>> dataset = datastore.get_dataset('<your-dataset-id>')
-  >>> dataset.query().fetch()
+  >>> datastore.set_default_connection()
+  >>> datastore.set_default_dataset_id('<your-dataset-id>')
+  >>> from gcloud.datastore.query import Query
+  >>> list(Query(kind='Person').fetch())
   []
-  >>> entity = dataset.entity('Person')
+  >>> from gcloud.datastore.entity import Entity
+  >>> from gcloud.datastore.key import Key
+  >>> entity = Entity(key=Key('Person'))
   >>> entity['name'] = 'Your name'
   >>> entity['age'] = 25
   >>> entity.save()
-  >>> dataset.query('Person').fetch()
+  >>> list(Query(kind='Person').fetch())
   [<Entity{...} {'name': 'Your name', 'age': 25}>]
 
 And that's it!

docs/_components/datastore-quickstart.rst

@@ -46,28 +46,22 @@ You can interact with a demo dataset
 in a Python interactive shell.
 
 Start by importing the demo module
-and instantiating the demo dataset::
+and initializing the demo settings::
 
   >>> from gcloud.datastore import demo
-  >>> dataset = demo.get_dataset()
+  >>> demo.initialize()
 
-Once you have the dataset,
+Once you have initialized,
 you can create entities and save them::
 
-  >>> dataset.query('MyExampleKind').fetch()
-  [<Entity{...}, ]
-  >>> entity = dataset.entity('Person')
+  >>> from gcloud.datastore.entity import Entity
+  >>> from gcloud.datastore.key import Key
+  >>> entity = Entity(key=Key('Person'))
   >>> entity['name'] = 'Your name'
   >>> entity['age'] = 25
   >>> entity.save()
-  >>> dataset.query('Person').fetch()
+  >>> from gcloud.datastore.query import Query
+  >>> list(Query(kind='Person').fetch())
   [<Entity{...} {'name': 'Your name', 'age': 25}>]
 
-.. note::
-  The ``get_dataset`` method is just a shortcut for::
-
-  >>> from gcloud import datastore
-  >>> from gcloud.datastore import demo
-  >>> dataset = datastore.get_dataset(demo.DATASET_ID)
-
 ----

docs/index.rst

@@ -28,8 +28,12 @@ Cloud Datastore
 .. code-block:: python
 
   from gcloud import datastore
-  dataset = datastore.get_dataset('<dataset-id>')
-  entity = dataset.entity('Person')
+  datastore.set_default_connection()
+  datastore.set_default_dataset_id('<dataset-id>')
+
+  from gcloud.datastore.entity import Entity
+  from gcloud.datastore.key import Key
+  entity = Entity(key=Key('Person'))
   entity['name'] = 'Your name'
   entity['age'] = 25
   entity.save()

gcloud/connection.py

@@ -22,11 +22,8 @@
 class Connection(object):
     """A generic connection to Google Cloud Platform.
 
-    Subclasses should understand
-    only the basic types
-    in method arguments,
-    however they should be capable
-    of returning advanced types.
+    Subclasses should understand only the basic types in method arguments,
+    however they should be capable of returning advanced types.
     """
 
     API_BASE_URL = 'https://www.googleapis.com'
@@ -39,17 +36,21 @@ class Connection(object):
     """The user agent for gcloud-python requests."""
 
     def __init__(self, credentials=None):
-        """
-        :type credentials: :class:`oauth2client.client.OAuth2Credentials`
+        """Constructor for Connection.
+
+        :type credentials: :class:`oauth2client.client.OAuth2Credentials` or
+                           :class:`NoneType`
         :param credentials: The OAuth2 Credentials to use for this connection.
         """
         self._http = None
         self._credentials = credentials
 
     @property
     def credentials(self):
-        """
-        :rtype: :class:`oauth2client.client.OAuth2Credentials`, or None
+        """Getter for current credentials.
+
+        :rtype: :class:`oauth2client.client.OAuth2Credentials` or
+                :class:`NoneType`
         :returns: The credentials object associated with this connection.
         """
         return self._credentials

gcloud/credentials.py

@@ -22,32 +22,32 @@ def get_credentials():
 
     .. note::
       You should not need to use this function directly. Instead, use the
-      helper methods provided in
-      :func:`gcloud.datastore.__init__.get_connection` and
-      :func:`gcloud.datastore.__init__.get_dataset` which use this method
-      under the hood.
+      helper method :func:`gcloud.datastore.__init__.get_connection`
+      which uses this method under the hood.
 
     Checks environment in order of precedence:
     - Google App Engine (production and testing)
     - Environment variable GOOGLE_APPLICATION_CREDENTIALS pointing to
       a file with stored credentials information.
-    - Stored "well known" file associated with `gcloud` command line tool.
+    - Stored "well known" file associated with ``gcloud`` command line tool.
     - Google Compute Engine production environment.
 
     The file referred to in GOOGLE_APPLICATION_CREDENTIALS is expected to
     contain information about credentials that are ready to use. This means
     either service account information or user account information with
-    a ready-to-use refresh token:
-        {                                       {
-            'type': 'authorized_user',              'type': 'service_account',
-            'client_id': '...',                     'client_id': '...',
-            'client_secret': '...',       OR        'client_email': '...',
-            'refresh_token': '...,                  'private_key_id': '...',
-        }                                           'private_key': '...',
-                                                }
+    a ready-to-use refresh token::
+
+      {                                       {
+          'type': 'authorized_user',              'type': 'service_account',
+          'client_id': '...',                     'client_id': '...',
+          'client_secret': '...',       OR        'client_email': '...',
+          'refresh_token': '...,                  'private_key_id': '...',
+      }                                           'private_key': '...',
+                                              }
+
     The second of these is simply a JSON key downloaded from the Google APIs
     console. The first is a close cousin of the "client secrets" JSON file
-    used by `oauth2client.clientsecrets` but differs in formatting.
+    used by ``oauth2client.clientsecrets`` but differs in formatting.
 
     :rtype: :class:`oauth2client.client.GoogleCredentials`,
             :class:`oauth2client.appengine.AppAssertionCredentials`,
@@ -68,22 +68,22 @@ def get_for_service_account_p12(client_email, private_key_path, scope=None):
       known explicitly and detecting the environment implicitly would be
       superfluous.
 
-    :type client_email: string
+    :type client_email: :class:`str`
     :param client_email: The e-mail attached to the service account.
 
-    :type private_key_path: string
+    :type private_key_path: :class:`str`
     :param private_key_path: The path to a private key file (this file was
                              given to you when you created the service
                              account). This file must be in P12 format.
 
-    :type scope: string or tuple of strings
+    :type scope: :class:`str` or :class:`tuple` of :class:`str`
     :param scope: The scope against which to authenticate. (Different services
                   require different scopes, check the documentation for which
                   scope is required for the different levels of access to any
                   particular API.)
 
     :rtype: :class:`oauth2client.client.SignedJwtAssertionCredentials`
-    :returns: A new SignedJwtAssertionCredentials instance with the
+    :returns: A new ``SignedJwtAssertionCredentials`` instance with the
               needed service account settings.
     """
     return client.SignedJwtAssertionCredentials(

gcloud/datastore/__init__.py

@@ -16,12 +16,17 @@
 
 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_default_connection()
+>>> datastore.set_default_dataset_id()
+>>>
 >>> key = Key('EntityKind', 1234)
 >>> entity = Entity(key)
->>> query = Query('your-dataset-id', kind='EntityKind')
+>>> query = Query(kind='EntityKind')
 
 The main concepts with this API are:
 
@@ -39,6 +44,10 @@
 
 - :class:`gcloud.datastore.query.Query`
   which represents a lookup or search over the rows in the datastore.
+
+- :class:`gcloud.datastore.transaction.Transaction`
+  which represents an all-or-none transaction and enables consistency
+  when race conditions may occur.
 """
 
 import os
@@ -49,9 +58,9 @@
 from gcloud.datastore import helpers
 
 
-SCOPE = ('https://www.googleapis.com/auth/datastore ',
+SCOPE = ('https://www.googleapis.com/auth/datastore',
          'https://www.googleapis.com/auth/userinfo.email')
-"""The scope required for authenticating as a Cloud Datastore consumer."""
+"""The scopes required for authenticating as a Cloud Datastore consumer."""
 
 _DATASET_ENV_VAR_NAME = 'GCLOUD_DATASET_ID'
 
@@ -92,9 +101,13 @@ def get_connection():
     with the same set of credentials (unlikely):
 
     >>> from gcloud import datastore
+    >>> from gcloud.datastore import Key
+    >>>
     >>> connection = datastore.get_connection()
-    >>> dataset1 = connection.dataset('dataset1')
-    >>> dataset2 = connection.dataset('dataset2')
+    >>> key1 = Key('Kind', 1234, dataset_id='dataset1')
+    >>> key2 = Key('Kind', 1234, dataset_id='dataset2')
+    >>> entity1 = key1.get(connection=connection)
+    >>> entity2 = key2.get(connection=connection)
 
     :rtype: :class:`gcloud.datastore.connection.Connection`
     :returns: A connection defined with the proper credentials.
@@ -110,9 +123,9 @@ def _require_dataset_id(dataset_id=None):
     :type dataset_id: :class:`str`.
     :param dataset_id: Optional.
 
-    :rtype: :class:`gcloud.datastore.dataset.Dataset`
-    :returns: A dataset based on the current environment.
-    :raises: :class:`EnvironmentError` if ``dataset_id`` is None,
+    :rtype: :class:`str`
+    :returns: A dataset ID based on the current environment.
+    :raises: :class:`EnvironmentError` if ``dataset_id`` is ``None``,
              and cannot be inferred from the environment.
     """
     if dataset_id is None:
@@ -130,7 +143,7 @@ def _require_connection(connection=None):
 
     :rtype: :class:`gcloud.datastore.connection.Connection`
     :returns: A connection based on the current environment.
-    :raises: :class:`EnvironmentError` if ``connection`` is None, and
+    :raises: :class:`EnvironmentError` if ``connection`` is ``None``, and
              cannot be inferred from the environment.
     """
     if connection is None:
@@ -198,7 +211,7 @@ def allocate_ids(incomplete_key, num_ids, connection=None, dataset_id=None):
     :type incomplete_key: A :class:`gcloud.datastore.key.Key`
     :param incomplete_key: Partial key to use as base for allocated IDs.
 
-    :type num_ids: A :class:`int`.
+    :type num_ids: :class:`int`.
     :param num_ids: The number of IDs to allocate.
 
     :type connection: :class:`gcloud.datastore.connection.Connection`
@@ -208,8 +221,8 @@ def allocate_ids(incomplete_key, num_ids, connection=None, dataset_id=None):
     :param dataset_id: Optional. The ID of the dataset.
 
     :rtype: list of :class:`gcloud.datastore.key.Key`
-    :returns: The (complete) keys allocated with `incomplete_key` as root.
-    :raises: `ValueError` if `incomplete_key` is not a partial key.
+    :returns: The (complete) keys allocated with ``incomplete_key`` as root.
+    :raises: :class:`ValueError` if ``incomplete_key`` is not a partial key.
     """
     connection = _require_connection(connection)
     dataset_id = _require_dataset_id(dataset_id)