Skip to content

Commit b4f9ebb

Browse files
tseavertseaver
committed
Merge pull request #413 from tseaver/remove-docstring-poetry
Remove docstring poetry
2 parents 41286a8 + fd43c3d commit b4f9ebb

File tree

11 files changed

+186
-217
lines changed

11 files changed

+186
-217
lines changed

‎docs/_static/css/main.css‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -601,6 +601,14 @@ h2, h3 {
601601
padding: 8px;
602602
}
603603

604+
.admonition {
605+
background-color: #f8f8f8;
606+
}
607+
608+
.admonition pre {
609+
background-color: #eeeeee !important;
610+
}
611+
604612
.docs-header {
605613
position: relative;
606614
padding: 7em 2em 4em;
@@ -662,6 +670,10 @@ h2 .headerlink:hover {
662670
cursor: pointer;
663671
}
664672

673+
.viewcode-link {
674+
float: right;
675+
}
676+
665677
/*
666678
Page Title
667679
*/

‎gcloud/datastore/connection.py‎

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -159,10 +159,9 @@ def lookup(self, dataset_id, key_pbs):
159159
Maps the ``DatastoreService.Lookup`` protobuf RPC.
160160
161161
This method deals only with protobufs
162-
(:class:`gcloud.datastore.datastore_v1_pb2.Key`
163-
and
164-
:class:`gcloud.datastore.datastore_v1_pb2.Entity`)
165-
and is used under the hood for methods like
162+
(:class:`gcloud.datastore.datastore_v1_pb2.Key` and
163+
:class:`gcloud.datastore.datastore_v1_pb2.Entity`) and is used
164+
under the hood for methods like
166165
:func:`gcloud.datastore.dataset.Dataset.get_entity`:
167166
168167
>>> from gcloud import datastore
@@ -224,12 +223,12 @@ def run_query(self, dataset_id, query_pb, namespace=None):
224223
225224
Maps the ``DatastoreService.RunQuery`` protobuf RPC.
226225
227-
Given a Query protobuf,
228-
sends a ``runQuery`` request to the Cloud Datastore API
229-
and returns a list of entity protobufs matching the query.
226+
Given a Query protobuf, sends a ``runQuery`` request to the
227+
Cloud Datastore API and returns a list of entity protobufs
228+
matching the query.
230229
231-
You typically wouldn't use this method directly,
232-
in favor of the :func:`gcloud.datastore.query.Query.fetch` method.
230+
You typically wouldn't use this method directly, in favor of the
231+
:func:`gcloud.datastore.query.Query.fetch` method.
233232
234233
Under the hood, the :class:`gcloud.datastore.query.Query` class
235234
uses this method to fetch data:
@@ -437,9 +436,9 @@ def delete_entities(self, dataset_id, key_pbs):
437436
"""Delete keys from a dataset in the Cloud Datastore.
438437
439438
This method deals only with
440-
:class:`gcloud.datastore.datastore_v1_pb2.Key` protobufs
441-
and not with any of the other abstractions.
442-
For example, it's used under the hood in the
439+
:class:`gcloud.datastore.datastore_v1_pb2.Key` protobufs and not
440+
with any of the other abstractions. For example, it's used
441+
under the hood in the
443442
:func:`gcloud.datastore.entity.Entity.delete` method.
444443
445444
:type dataset_id: string

‎gcloud/datastore/dataset.py‎

Lines changed: 14 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -10,24 +10,20 @@
1010
class Dataset(object):
1111
"""A dataset in the Cloud Datastore.
1212
13-
This class acts as an abstraction of a single dataset
14-
in the Cloud Datastore.
15-
16-
A dataset is analogous to a database
17-
in relational database world,
18-
and corresponds to a single project
19-
using the Cloud Datastore.
20-
21-
Typically, you would only have one of these per connection
22-
however it didn't seem right to collapse the functionality
23-
of a connection and a dataset together into a single class.
24-
25-
Datasets (like :class:`gcloud.datastore.query.Query`)
26-
are immutable.
27-
That is, you cannot change the ID and connection
28-
references.
29-
If you need to modify the connection or ID,
30-
it's recommended to construct a new :class:`Dataset`.
13+
This class acts as an abstraction of a single dataset in the Cloud
14+
Datastore.
15+
16+
A dataset is analogous to a database in relational database world,
17+
and corresponds to a single project using the Cloud Datastore.
18+
19+
Typically, you would only have one of these per connection however
20+
it didn't seem right to collapse the functionality of a connection
21+
and a dataset together into a single class.
22+
23+
Datasets (like :class:`gcloud.datastore.query.Query`) are immutable.
24+
That is, you cannot change the ID and connection references. If you
25+
need to modify the connection or ID, it's recommended to construct a
26+
new :class:`Dataset`.
3127
3228
:type id: string
3329
:param id: The ID of the dataset (your project ID)

‎gcloud/datastore/entity.py‎

Lines changed: 35 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,4 @@
1-
"""Class for representing a single entity in the Cloud Datastore.
2-
3-
Entities are akin to rows in a relational database,
4-
storing the actual instance of data.
5-
6-
Each entity is officially represented with
7-
a :class:`gcloud.datastore.key.Key` class,
8-
however it is possible that you might create
9-
an Entity with only a partial Key
10-
(that is, a Key with a Kind,
11-
and possibly a parent, but without an ID).
12-
13-
Entities in this API act like dictionaries
14-
with extras built in that allow you to
15-
delete or persist the data stored on the entity.
16-
"""
1+
"""Class for representing a single entity in the Cloud Datastore."""
172

183
from gcloud.datastore import datastore_v1_pb2 as datastore_pb
194
from gcloud.datastore.key import Key
@@ -28,42 +13,40 @@ class NoDataset(RuntimeError):
2813

2914

3015
class Entity(dict):
31-
""":type dataset: :class:`gcloud.datastore.dataset.Dataset`
32-
:param dataset: The dataset in which this entity belongs.
16+
"""Entities are akin to rows in a relational database
3317
34-
:type kind: string
35-
:param kind: The kind of entity this is, akin to a table name in a
36-
relational database.
18+
An entity storing the actual instance of data.
19+
20+
Each entity is officially represented with a
21+
:class:`gcloud.datastore.key.Key` class, however it is possible that
22+
you might create an Entity with only a partial Key (that is, a Key
23+
with a Kind, and possibly a parent, but without an ID). In such a
24+
case, the datastore service will automatically assign an ID to the
25+
partial key.
26+
27+
Entities in this API act like dictionaries with extras built in that
28+
allow you to delete or persist the data stored on the entity.
3729
3830
Entities are mutable and act like a subclass of a dictionary.
3931
This means you could take an existing entity and change the key
4032
to duplicate the object.
4133
42-
This can be used on its own, however it is likely easier to use
43-
the shortcut methods provided by :class:`gcloud.datastore.dataset.Dataset`
44-
such as:
45-
46-
- :func:`gcloud.datastore.dataset.Dataset.entity` to create a new entity.
47-
48-
>>> dataset.entity('MyEntityKind')
49-
<Entity[{'kind': 'MyEntityKind'}] {}>
50-
51-
- :func:`gcloud.datastore.dataset.Dataset.get_entity`
52-
to retrieve an existing entity.
34+
Use :func:`gcloud.datastore.dataset.Dataset.get_entity`
35+
to retrieve an existing entity.
5336
5437
>>> dataset.get_entity(key)
5538
<Entity[{'kind': 'EntityKind', id: 1234}] {'property': 'value'}>
5639
57-
You can the set values on the entity
58-
just like you would on any other dictionary.
40+
You can the set values on the entity just like you would on any
41+
other dictionary.
5942
6043
>>> entity['age'] = 20
6144
>>> entity['name'] = 'JJ'
6245
>>> entity
6346
<Entity[{'kind': 'EntityKind', id: 1234}] {'age': 20, 'name': 'JJ'}>
6447
65-
And you can cast an entity to a regular Python dictionary
66-
with the `dict` builtin:
48+
And you can convert an entity to a regular Python dictionary with the
49+
`dict` builtin:
6750
6851
>>> dict(entity)
6952
{'age': 20, 'name': 'JJ'}
@@ -78,6 +61,13 @@ class Entity(dict):
7861
Python3), will be saved using the 'blob_value' field, without
7962
any decoding / encoding step.
8063
64+
:type dataset: :class:`gcloud.datastore.dataset.Dataset`
65+
:param dataset: The dataset in which this entity belongs.
66+
67+
:type kind: string
68+
:param kind: The kind of entity this is, akin to a table name in a
69+
relational database.
70+
8171
:type dataset: :class:`gcloud.datastore.dataset.Dataset`, or None
8272
:param dataset: the Dataset instance associated with this entity.
8373
@@ -101,15 +91,15 @@ def __init__(self, dataset=None, kind=None, exclude_from_indexes=()):
10191
def dataset(self):
10292
"""Get the :class:`.dataset.Dataset` in which this entity belongs.
10393
104-
:rtype: :class:`gcloud.datastore.dataset.Dataset`
105-
:returns: The Dataset containing the entity if there is a key,
106-
else None.
107-
10894
.. note::
10995
This is based on the :class:`gcloud.datastore.key.Key` set on the
11096
entity. That means that if you have no key set, the dataset might
11197
be `None`. It also means that if you change the key on the entity,
11298
this will refer to that key's dataset.
99+
100+
:rtype: :class:`gcloud.datastore.dataset.Dataset`
101+
:returns: The Dataset containing the entity if there is a key,
102+
else None.
113103
"""
114104
return self._dataset
115105

@@ -139,12 +129,10 @@ def kind(self):
139129
"""Get the kind of the current entity.
140130
141131
.. note::
142-
This relies entirely on
143-
the :class:`gcloud.datastore.key.Key`
144-
set on the entity.
145-
That means that we're not storing the kind of the entity at all,
146-
just the properties and a pointer to a Key
147-
which knows its Kind.
132+
This relies entirely on the :class:`gcloud.datastore.key.Key`
133+
set on the entity. That means that we're not storing the kind
134+
of the entity at all, just the properties and a pointer to a
135+
Key which knows its Kind.
148136
"""
149137

150138
if self._key:
@@ -161,8 +149,7 @@ def exclude_from_indexes(self):
161149
def from_key(cls, key, dataset=None):
162150
"""Create entity based on :class:`.datastore.key.Key`.
163151
164-
.. note::
165-
This is a factory method.
152+
.. note:: This is a factory method.
166153
167154
:type key: :class:`gcloud.datastore.key.Key`
168155
:param key: The key for the entity.

‎gcloud/datastore/helpers.py‎

Lines changed: 19 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -78,17 +78,15 @@ def key_from_protobuf(pb):
7878
def _pb_attr_value(val):
7979
"""Given a value, return the protobuf attribute name and proper value.
8080
81-
The Protobuf API uses different attribute names
82-
based on value types rather than inferring the type.
83-
This function simply determines the proper attribute name
84-
based on the type of the value provided
85-
and returns the attribute name
86-
as well as a properly formatted value.
87-
88-
Certain value types need to be coerced into a different type (such as a
89-
`datetime.datetime` into an integer timestamp, or a
90-
`gcloud.datastore.key.Key` into a Protobuf representation.
91-
This function handles that for you.
81+
The Protobuf API uses different attribute names based on value types
82+
rather than inferring the type. This function simply determines the
83+
proper attribute name based on the type of the value provided and
84+
returns the attribute name as well as a properly formatted value.
85+
86+
Certain value types need to be coerced into a different type (such
87+
as a `datetime.datetime` into an integer timestamp, or a
88+
`gcloud.datastore.key.Key` into a Protobuf representation. This
89+
function handles that for you.
9290
9391
.. note::
9492
Values which are "text" ('unicode' in Python2, 'str' in Python3) map
@@ -145,9 +143,9 @@ def _pb_attr_value(val):
145143
def _get_value_from_value_pb(value_pb):
146144
"""Given a protobuf for a Value, get the correct value.
147145
148-
The Cloud Datastore Protobuf API returns a Property Protobuf
149-
which has one value set and the rest blank.
150-
This function retrieves the the one value provided.
146+
The Cloud Datastore Protobuf API returns a Property Protobuf which
147+
has one value set and the rest blank. This function retrieves the
148+
the one value provided.
151149
152150
Some work is done to coerce the return value into a more useful type
153151
(particularly in the case of a timestamp value, or a key value).
@@ -195,9 +193,9 @@ def _get_value_from_value_pb(value_pb):
195193
def _get_value_from_property_pb(property_pb):
196194
"""Given a protobuf for a Property, get the correct value.
197195
198-
The Cloud Datastore Protobuf API returns a Property Protobuf
199-
which has one value set and the rest blank.
200-
This function retrieves the the one value provided.
196+
The Cloud Datastore Protobuf API returns a Property Protobuf which
197+
has one value set and the rest blank. This function retrieves the
198+
the one value provided.
201199
202200
Some work is done to coerce the return value into a more useful type
203201
(particularly in the case of a timestamp value, or a key value).
@@ -213,11 +211,11 @@ def _get_value_from_property_pb(property_pb):
213211
def _set_protobuf_value(value_pb, val):
214212
"""Assign 'val' to the correct subfield of 'value_pb'.
215213
216-
The Protobuf API uses different attribute names
217-
based on value types rather than inferring the type.
214+
The Protobuf API uses different attribute names based on value types
215+
rather than inferring the type.
218216
219-
Some value types (entities, keys, lists) cannot be directly assigned;
220-
this function handles them correctly.
217+
Some value types (entities, keys, lists) cannot be directly
218+
assigned; this function handles them correctly.
221219
222220
:type value_pb: :class:`gcloud.datastore.datastore_v1_pb2.Value`
223221
:param value_pb: The value protobuf to which the value is being assigned.

‎gcloud/datastore/key.py‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,13 +28,12 @@ def __init__(self, path=None, namespace=None, dataset_id=None):
2828
:param dataset: The dataset ID assigned by back-end for the key.
2929
3030
.. note::
31-
3231
The key's ``_dataset_id`` field must be None for keys created
3332
by application code. The
3433
:func:`gcloud.datastore.helpers.key_from_protobuf` factory
35-
will be set the field to an appropriate value for keys returned
36-
from the datastore backend. The application **must** treat any
37-
value set by the back-end as opaque.
34+
will be set the field to an appropriate value for keys
35+
returned from the datastore backend. The application
36+
**must** treat any value set by the back-end as opaque.
3837
"""
3938
self._path = path or [{'kind': ''}]
4039
self._namespace = namespace

0 commit comments

Comments
 (0)