Remove docstring poetry

docs/_static/css/main.css

@@ -601,6 +601,14 @@ h2, h3 {
   padding: 8px;
 }
 
+.admonition {
+  background-color: #f8f8f8;
+}
+
+.admonition pre {
+  background-color: #eeeeee !important;
+}
+
 .docs-header {
     position: relative;
     padding: 7em 2em 4em;
@@ -662,6 +670,10 @@ h2 .headerlink:hover {
   cursor: pointer;
 }
 
+.viewcode-link {
+  float: right;
+}
+
 /*
  Page Title
 */

gcloud/datastore/connection.py

@@ -159,10 +159,9 @@ def lookup(self, dataset_id, key_pbs):
         Maps the ``DatastoreService.Lookup`` protobuf RPC.
 
         This method deals only with protobufs
-        (:class:`gcloud.datastore.datastore_v1_pb2.Key`
-        and
-        :class:`gcloud.datastore.datastore_v1_pb2.Entity`)
-        and is used under the hood for methods like
+        (:class:`gcloud.datastore.datastore_v1_pb2.Key` and
+        :class:`gcloud.datastore.datastore_v1_pb2.Entity`) and is used
+        under the hood for methods like
         :func:`gcloud.datastore.dataset.Dataset.get_entity`:
 
         >>> from gcloud import datastore
@@ -224,12 +223,12 @@ def run_query(self, dataset_id, query_pb, namespace=None):
 
         Maps the ``DatastoreService.RunQuery`` protobuf RPC.
 
-        Given a Query protobuf,
-        sends a ``runQuery`` request to the Cloud Datastore API
-        and returns a list of entity protobufs matching the query.
+        Given a Query protobuf, sends a ``runQuery`` request to the
+        Cloud Datastore API and returns a list of entity protobufs
+        matching the query.
 
-        You typically wouldn't use this method directly,
-        in favor of the :func:`gcloud.datastore.query.Query.fetch` method.
+        You typically wouldn't use this method directly, in favor of the
+        :func:`gcloud.datastore.query.Query.fetch` method.
 
         Under the hood, the :class:`gcloud.datastore.query.Query` class
         uses this method to fetch data:
@@ -437,9 +436,9 @@ def delete_entities(self, dataset_id, key_pbs):
         """Delete keys from a dataset in the Cloud Datastore.
 
         This method deals only with
-        :class:`gcloud.datastore.datastore_v1_pb2.Key` protobufs
-        and not with any of the other abstractions.
-        For example, it's used under the hood in the
+        :class:`gcloud.datastore.datastore_v1_pb2.Key` protobufs and not
+        with any of the other abstractions.  For example, it's used
+        under the hood in the
         :func:`gcloud.datastore.entity.Entity.delete` method.
 
         :type dataset_id: string

gcloud/datastore/dataset.py

@@ -10,24 +10,20 @@
 class Dataset(object):
     """A dataset in the Cloud Datastore.
 
-    This class acts as an abstraction of a single dataset
-    in the Cloud Datastore.
-
-    A dataset is analogous to a database
-    in relational database world,
-    and corresponds to a single project
-    using the Cloud Datastore.
-
-    Typically, you would only have one of these per connection
-    however it didn't seem right to collapse the functionality
-    of a connection and a dataset together into a single class.
-
-    Datasets (like :class:`gcloud.datastore.query.Query`)
-    are immutable.
-    That is, you cannot change the ID and connection
-    references.
-    If you need to modify the connection or ID,
-    it's recommended to construct a new :class:`Dataset`.
+    This class acts as an abstraction of a single dataset in the Cloud
+    Datastore.
+
+    A dataset is analogous to a database in relational database world,
+    and corresponds to a single project using the Cloud Datastore.
+
+    Typically, you would only have one of these per connection however
+    it didn't seem right to collapse the functionality of a connection
+    and a dataset together into a single class.
+
+    Datasets (like :class:`gcloud.datastore.query.Query`) are immutable.
+    That is, you cannot change the ID and connection references.  If you
+    need to modify the connection or ID, it's recommended to construct a
+    new :class:`Dataset`.
 
     :type id: string
     :param id: The ID of the dataset (your project ID)

gcloud/datastore/entity.py

@@ -1,19 +1,4 @@
-"""Class for representing a single entity in the Cloud Datastore.
-
-Entities are akin to rows in a relational database,
-storing the actual instance of data.
-
-Each entity is officially represented with
-a :class:`gcloud.datastore.key.Key` class,
-however it is possible that you might create
-an Entity with only a partial Key
-(that is, a Key with a Kind,
-and possibly a parent, but without an ID).
-
-Entities in this API act like dictionaries
-with extras built in that allow you to
-delete or persist the data stored on the entity.
-"""
+"""Class for representing a single entity in the Cloud Datastore."""
 
 from gcloud.datastore import datastore_v1_pb2 as datastore_pb
 from gcloud.datastore.key import Key
@@ -28,42 +13,40 @@ class NoDataset(RuntimeError):
 
 
 class Entity(dict):
-    """:type dataset: :class:`gcloud.datastore.dataset.Dataset`
-    :param dataset: The dataset in which this entity belongs.
+    """Entities are akin to rows in a relational database
 
-    :type kind: string
-    :param kind: The kind of entity this is, akin to a table name in a
-                 relational database.
+    An entity storing the actual instance of data.
+
+    Each entity is officially represented with a
+    :class:`gcloud.datastore.key.Key` class, however it is possible that
+    you might create an Entity with only a partial Key (that is, a Key
+    with a Kind, and possibly a parent, but without an ID).  In such a
+    case, the datastore service will automatically assign an ID to the
+    partial key.
+
+    Entities in this API act like dictionaries with extras built in that
+    allow you to delete or persist the data stored on the entity.
 
     Entities are mutable and act like a subclass of a dictionary.
     This means you could take an existing entity and change the key
     to duplicate the object.
 
-    This can be used on its own, however it is likely easier to use
-    the shortcut methods provided by :class:`gcloud.datastore.dataset.Dataset`
-    such as:
-
-    - :func:`gcloud.datastore.dataset.Dataset.entity` to create a new entity.
-
-      >>> dataset.entity('MyEntityKind')
-      <Entity[{'kind': 'MyEntityKind'}] {}>
-
-    - :func:`gcloud.datastore.dataset.Dataset.get_entity`
-      to retrieve an existing entity.
+    Use :func:`gcloud.datastore.dataset.Dataset.get_entity`
+    to retrieve an existing entity.
 
       >>> dataset.get_entity(key)
       <Entity[{'kind': 'EntityKind', id: 1234}] {'property': 'value'}>
 
-    You can the set values on the entity
-    just like you would on any other dictionary.
+    You can the set values on the entity just like you would on any
+    other dictionary.
 
     >>> entity['age'] = 20
     >>> entity['name'] = 'JJ'
     >>> entity
     <Entity[{'kind': 'EntityKind', id: 1234}] {'age': 20, 'name': 'JJ'}>
 
-    And you can cast an entity to a regular Python dictionary
-    with the `dict` builtin:
+    And you can convert an entity to a regular Python dictionary with the
+    `dict` builtin:
 
     >>> dict(entity)
     {'age': 20, 'name': 'JJ'}
@@ -78,6 +61,13 @@ class Entity(dict):
        Python3), will be saved using the 'blob_value' field, without
        any decoding / encoding step.
 
+    :type dataset: :class:`gcloud.datastore.dataset.Dataset`
+    :param dataset: The dataset in which this entity belongs.
+
+    :type kind: string
+    :param kind: The kind of entity this is, akin to a table name in a
+                 relational database.
+
     :type dataset: :class:`gcloud.datastore.dataset.Dataset`, or None
     :param dataset: the Dataset instance associated with this entity.
 
@@ -101,15 +91,15 @@ def __init__(self, dataset=None, kind=None, exclude_from_indexes=()):
     def dataset(self):
         """Get the :class:`.dataset.Dataset` in which this entity belongs.
 
-        :rtype: :class:`gcloud.datastore.dataset.Dataset`
-        :returns: The Dataset containing the entity if there is a key,
-                  else None.
-
         .. note::
           This is based on the :class:`gcloud.datastore.key.Key` set on the
           entity. That means that if you have no key set, the dataset might
           be `None`. It also means that if you change the key on the entity,
           this will refer to that key's dataset.
+
+        :rtype: :class:`gcloud.datastore.dataset.Dataset`
+        :returns: The Dataset containing the entity if there is a key,
+                  else None.
         """
         return self._dataset
 
@@ -139,12 +129,10 @@ def kind(self):
         """Get the kind of the current entity.
 
         .. note::
-          This relies entirely on
-          the :class:`gcloud.datastore.key.Key`
-          set on the entity.
-          That means that we're not storing the kind of the entity at all,
-          just the properties and a pointer to a Key
-          which knows its Kind.
+          This relies entirely on the :class:`gcloud.datastore.key.Key`
+          set on the entity.  That means that we're not storing the kind
+          of the entity at all, just the properties and a pointer to a
+          Key which knows its Kind.
         """
 
         if self._key:
@@ -161,8 +149,7 @@ def exclude_from_indexes(self):
     def from_key(cls, key, dataset=None):
         """Create entity based on :class:`.datastore.key.Key`.
 
-        .. note::
-          This is a factory method.
+        .. note:: This is a factory method.
 
         :type key: :class:`gcloud.datastore.key.Key`
         :param key: The key for the entity.

gcloud/datastore/helpers.py

@@ -78,17 +78,15 @@ def key_from_protobuf(pb):
 def _pb_attr_value(val):
     """Given a value, return the protobuf attribute name and proper value.
 
-    The Protobuf API uses different attribute names
-    based on value types rather than inferring the type.
-    This function simply determines the proper attribute name
-    based on the type of the value provided
-    and returns the attribute name
-    as well as a properly formatted value.
-
-    Certain value types need to be coerced into a different type (such as a
-    `datetime.datetime` into an integer timestamp, or a
-    `gcloud.datastore.key.Key` into a Protobuf representation.
-    This function handles that for you.
+    The Protobuf API uses different attribute names based on value types
+    rather than inferring the type.  This function simply determines the
+    proper attribute name based on the type of the value provided and
+    returns the attribute name as well as a properly formatted value.
+
+    Certain value types need to be coerced into a different type (such
+    as a `datetime.datetime` into an integer timestamp, or a
+    `gcloud.datastore.key.Key` into a Protobuf representation.  This
+    function handles that for you.
 
     .. note::
        Values which are "text" ('unicode' in Python2, 'str' in Python3) map
@@ -145,9 +143,9 @@ def _pb_attr_value(val):
 def _get_value_from_value_pb(value_pb):
     """Given a protobuf for a Value, get the correct value.
 
-    The Cloud Datastore Protobuf API returns a Property Protobuf
-    which has one value set and the rest blank.
-    This function retrieves the the one value provided.
+    The Cloud Datastore Protobuf API returns a Property Protobuf which
+    has one value set and the rest blank.  This function retrieves the
+    the one value provided.
 
     Some work is done to coerce the return value into a more useful type
     (particularly in the case of a timestamp value, or a key value).
@@ -195,9 +193,9 @@ def _get_value_from_value_pb(value_pb):
 def _get_value_from_property_pb(property_pb):
     """Given a protobuf for a Property, get the correct value.
 
-    The Cloud Datastore Protobuf API returns a Property Protobuf
-    which has one value set and the rest blank.
-    This function retrieves the the one value provided.
+    The Cloud Datastore Protobuf API returns a Property Protobuf which
+    has one value set and the rest blank.  This function retrieves the
+    the one value provided.
 
     Some work is done to coerce the return value into a more useful type
     (particularly in the case of a timestamp value, or a key value).
@@ -213,11 +211,11 @@ def _get_value_from_property_pb(property_pb):
 def _set_protobuf_value(value_pb, val):
     """Assign 'val' to the correct subfield of 'value_pb'.
 
-    The Protobuf API uses different attribute names
-    based on value types rather than inferring the type.
+    The Protobuf API uses different attribute names based on value types
+    rather than inferring the type.
 
-    Some value types (entities, keys, lists) cannot be directly assigned;
-    this function handles them correctly.
+    Some value types (entities, keys, lists) cannot be directly
+    assigned; this function handles them correctly.
 
     :type value_pb: :class:`gcloud.datastore.datastore_v1_pb2.Value`
     :param value_pb: The value protobuf to which the value is being assigned.

gcloud/datastore/key.py

@@ -28,13 +28,12 @@ def __init__(self, path=None, namespace=None, dataset_id=None):
         :param dataset: The dataset ID assigned by back-end for the key.
 
         .. note::
-
            The key's ``_dataset_id`` field must be None for keys created
            by application code.  The
            :func:`gcloud.datastore.helpers.key_from_protobuf` factory
-           will be set the field to an appropriate value for keys returned
-           from the datastore backend.  The application **must** treat any
-           value set by the back-end as opaque.
+           will be set the field to an appropriate value for keys
+           returned from the datastore backend.  The application
+           **must** treat any value set by the back-end as opaque.
         """
         self._path = path or [{'kind': ''}]
         self._namespace = namespace