Skip to content

Commit

Permalink
Merge pull request #506 from dhermes/fix-477-part9-docs-fix
Browse files Browse the repository at this point in the history
Updating documentation to reflect bulk datastore API changes.
  • Loading branch information
dhermes committed Jan 8, 2015
2 parents 56daf8c + 8b950cf commit f577b30
Show file tree
Hide file tree
Showing 20 changed files with 273 additions and 239 deletions.
10 changes: 7 additions & 3 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------------------
Expand Down
12 changes: 8 additions & 4 deletions docs/_components/datastore-getting-started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down
22 changes: 8 additions & 14 deletions docs/_components/datastore-quickstart.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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)

----
8 changes: 6 additions & 2 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
19 changes: 10 additions & 9 deletions gcloud/connection.py
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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
Expand Down
32 changes: 16 additions & 16 deletions gcloud/credentials.py
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand Down Expand Up @@ -76,14 +76,14 @@ def get_for_service_account_p12(client_email, private_key_path, scope=None):
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: string or tuple of string
: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(
Expand Down
45 changes: 29 additions & 16 deletions gcloud/datastore/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -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'

Expand All @@ -65,7 +74,7 @@ def set_default_dataset_id(dataset_id=None):
Local environment variable used is:
- GCLOUD_DATASET_ID
:type dataset_id: :class:`str`.
:type dataset_id: string
:param dataset_id: Optional. The dataset ID to use as default.
"""
if dataset_id is None:
Expand All @@ -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.
Expand All @@ -107,12 +120,12 @@ def get_connection():
def _require_dataset_id(dataset_id=None):
"""Infer a dataset ID from the environment, if not passed explicitly.
:type dataset_id: :class:`str`.
:type dataset_id: string
: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: string
: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:
Expand All @@ -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:
Expand Down Expand Up @@ -160,7 +173,7 @@ def get_entities(keys, missing=None, deferred=None,
:type connection: :class:`gcloud.datastore.connection.Connection`
:param connection: Optional. The connection used to connect to datastore.
:type dataset_id: :class:`str`.
:type dataset_id: string
:param dataset_id: Optional. The ID of the dataset.
:rtype: list of :class:`gcloud.datastore.entity.Entity`
Expand Down Expand Up @@ -198,18 +211,18 @@ 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: integer
:param num_ids: The number of IDs to allocate.
:type connection: :class:`gcloud.datastore.connection.Connection`
:param connection: Optional. The connection used to connect to datastore.
:type dataset_id: :class:`str`.
:type dataset_id: string
: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)
Expand Down
Loading

0 comments on commit f577b30

Please sign in to comment.