Skip to content

Commit 8b72c12

Browse files
authored
docs: added type hints and comments to Datastore samples (#5536)
* docs: added type hints and comments to Datastore samples * linting fix * adding noqa for import order * have mercy * scoped type hints to recommended import * added import statement to each snippet * Added more blocks to inherit import * region tag test * more region tags tests * region tests take 3 * removed cosmetic indent * removed region tag indent * clever idea? * everything indented? * added smoke test * removed smoke test * convert wonky if to _preamble * sample touch ups * Linting and array value access sample * removed extra blank line * More attribute access in Entity construction samples * added assert to make linter happy * added linting suppressor * changed attribute accessor hints to comments * removed attribute access hints deferring to a dedicated block/region
1 parent c03ff8e commit 8b72c12

File tree

2 files changed

+159
-15
lines changed

2 files changed

+159
-15
lines changed

datastore/cloud-client/snippets.py

Lines changed: 128 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,128 @@
1616
import datetime
1717
from pprint import pprint
1818

19-
from google.cloud import datastore
2019
import google.cloud.exceptions
20+
from google.cloud import datastore # noqa: I100
21+
22+
23+
def _preamble():
24+
# [START datastore_incomplete_key]
25+
# [START datastore_named_key]
26+
# [START datastore_key_with_parent]
27+
# [START datastore_key_with_multilevel_parent]
28+
# [START datastore_basic_entity]
29+
# [START datastore_entity_with_parent]
30+
# [START datastore_properties]
31+
# [START datastore_array_value]
32+
# [START datastore_upsert]
33+
# [START datastore_insert]
34+
# [START datastore_update]
35+
# [START datastore_lookup]
36+
# [START datastore_delete]
37+
# [START datastore_batch_upsert]
38+
# [START datastore_batch_lookup]
39+
# [START datastore_batch_delete]
40+
# [START datastore_unindexed_property_query]
41+
# [START datastore_basic_query]
42+
# [START datastore_projection_query]
43+
# [START datastore_ancestor_query]
44+
# [START datastore_run_query]
45+
# [START datastore_limit]
46+
# [START datastore_cursor_paging]
47+
# [START datastore_property_filter]
48+
# [START datastore_composite_filter]
49+
# [START datastore_key_filter]
50+
# [START datastore_ascending_sort]
51+
# [START datastore_descending_sort]
52+
# [START datastore_multi_sort]
53+
# [START datastore_keys_only_query]
54+
# [START datastore_distinct_on_query]
55+
# [START datastore_kindless_query]
56+
# [START datastore_inequality_range]
57+
# [START datastore_inequality_invalid]
58+
# [START datastore_equal_and_inequality_range]
59+
# [START datastore_inequality_sort]
60+
# [START datastore_inequality_sort_invalid_not_same]
61+
# [START datastore_inequality_sort_invalid_not_first]
62+
# [START datastore_array_value_inequality_range]
63+
# [START datastore_array_value_equality]
64+
# [START datastore_exploding_properties]
65+
# [START datastore_transactional_update]
66+
# [START datastore_transactional_retry]
67+
# [START datastore_transactional_get_or_create]
68+
# [START datastore_transactional_single_entity_group_read_only]
69+
# [START datastore_namespace_run_query]
70+
# [START datastore_kind_run_query]
71+
# [START datastore_property_run_query]
72+
# [START datastore_property_by_kind_run_query]
73+
# [START datastore_eventual_consistent_query]
74+
# [START datastore_built_in_index_queries]
75+
# [START datastore_merged_index_query]
76+
# [START datastore_merged_index_tag_queries]
77+
# [START datastore_owner_size_tag_query]
78+
# [START datastore_size_coloration_query]
79+
from google.cloud import datastore
80+
81+
# For help authenticating your client, visit
82+
# https://cloud.google.com/docs/authentication/getting-started
83+
client = datastore.Client()
84+
85+
# [END datastore_incomplete_key]
86+
# [END datastore_named_key]
87+
# [END datastore_key_with_parent]
88+
# [END datastore_key_with_multilevel_parent]
89+
# [END datastore_basic_entity]
90+
# [END datastore_entity_with_parent]
91+
# [END datastore_properties]
92+
# [END datastore_array_value]
93+
# [END datastore_upsert]
94+
# [END datastore_insert]
95+
# [END datastore_update]
96+
# [END datastore_lookup]
97+
# [END datastore_delete]
98+
# [END datastore_batch_upsert]
99+
# [END datastore_batch_lookup]
100+
# [END datastore_batch_delete]
101+
# [END datastore_unindexed_property_query]
102+
# [END datastore_basic_query]
103+
# [END datastore_projection_query]
104+
# [END datastore_ancestor_query]
105+
# [END datastore_run_query]
106+
# [END datastore_limit]
107+
# [END datastore_cursor_paging]
108+
# [END datastore_property_filter]
109+
# [END datastore_composite_filter]
110+
# [END datastore_key_filter]
111+
# [END datastore_ascending_sort]
112+
# [END datastore_descending_sort]
113+
# [END datastore_multi_sort]
114+
# [END datastore_keys_only_query]
115+
# [END datastore_distinct_on_query]
116+
# [END datastore_kindless_query]
117+
# [END datastore_inequality_range]
118+
# [END datastore_inequality_invalid]
119+
# [END datastore_equal_and_inequality_range]
120+
# [END datastore_inequality_sort]
121+
# [END datastore_inequality_sort_invalid_not_same]
122+
# [END datastore_inequality_sort_invalid_not_first]
123+
# [END datastore_array_value_inequality_range]
124+
# [END datastore_array_value_equality]
125+
# [END datastore_exploding_properties]
126+
# [END datastore_transactional_update]
127+
# [END datastore_transactional_retry]
128+
# [END datastore_transactional_get_or_create]
129+
# [END datastore_transactional_single_entity_group_read_only]
130+
# [END datastore_namespace_run_query]
131+
# [END datastore_kind_run_query]
132+
# [END datastore_property_run_query]
133+
# [END datastore_property_by_kind_run_query]
134+
# [END datastore_eventual_consistent_query]
135+
# [END datastore_built_in_index_queries]
136+
# [END datastore_merged_index_query]
137+
# [END datastore_merged_index_tag_queries]
138+
# [END datastore_owner_size_tag_query]
139+
# [END datastore_size_coloration_query]
140+
assert client is not None
21141

22142

23143
def incomplete_key(client):
@@ -91,8 +211,8 @@ def entity_with_parent(client):
91211

92212

93213
def properties(client):
94-
key = client.key("Task")
95214
# [START datastore_properties]
215+
key = client.key("Task")
96216
task = datastore.Entity(key, exclude_from_indexes=["description"])
97217
task.update(
98218
{
@@ -110,8 +230,8 @@ def properties(client):
110230

111231

112232
def array_value(client):
113-
key = client.key("Task")
114233
# [START datastore_array_value]
234+
key = client.key("Task")
115235
task = datastore.Entity(key)
116236
task.update({"tags": ["fun", "programming"], "collaborators": ["alice", "bob"]})
117237
# [END datastore_array_value]
@@ -237,9 +357,8 @@ def batch_lookup(client):
237357
# Create the entities we will lookup.
238358
batch_upsert(client)
239359

240-
keys = [client.key("Task", 1), client.key("Task", 2)]
241-
242360
# [START datastore_batch_lookup]
361+
keys = [client.key("Task", 1), client.key("Task", 2)]
243362
tasks = client.get_multi(keys)
244363
# [END datastore_batch_lookup]
245364

@@ -250,9 +369,8 @@ def batch_delete(client):
250369
# Create the entities we will delete.
251370
batch_upsert(client)
252371

253-
keys = [client.key("Task", 1), client.key("Task", 2)]
254-
255372
# [START datastore_batch_delete]
373+
keys = [client.key("Task", 1), client.key("Task", 2)]
256374
client.delete_multi(keys)
257375
# [END datastore_batch_delete]
258376

@@ -304,6 +422,8 @@ def projection_query(client):
304422
query.projection = ["priority", "percent_complete"]
305423
# [END datastore_projection_query]
306424

425+
# This block intentionally doesn't include the top level import because
426+
# it doesn't use a `datastore.Client` instance
307427
# [START datastore_run_query_projection]
308428
priorities = []
309429
percent_completes = []
@@ -486,9 +606,8 @@ def kindless_query(client):
486606
# Create the entity that we're going to query.
487607
upsert(client)
488608

489-
last_seen_key = client.key("Task", "a")
490-
491609
# [START datastore_kindless_query]
610+
last_seen_key = client.key("Task", "a")
492611
query = client.query()
493612
query.key_filter(last_seen_key, ">")
494613
# [END datastore_kindless_query]

datastore/cloud-client/tasks.py

Lines changed: 31 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,23 @@
1313

1414
import argparse
1515
import datetime
16+
from typing import Union
1617

18+
# [START datastore_add_entity]
1719
# [START datastore_build_service]
20+
# [START datastore_update_entity]
21+
# [START datastore_retrieve_entities]
22+
# [START datastore_delete_entity]
1823
from google.cloud import datastore
1924

25+
# [END datastore_add_entity]
26+
# [END datastore_build_service]
27+
# [END datastore_update_entity]
28+
# [END datastore_retrieve_entities]
29+
# [END datastore_delete_entity]
30+
2031

32+
# [START datastore_build_service]
2133
def create_client(project_id):
2234
return datastore.Client(project_id)
2335

@@ -26,46 +38,56 @@ def create_client(project_id):
2638

2739

2840
# [START datastore_add_entity]
29-
def add_task(client, description):
41+
def add_task(client: datastore.Client, description: str):
42+
# Create an incomplete key for an entity of kind "Task". An incomplete
43+
# key is one where Datastore will automatically generate an Id
3044
key = client.key("Task")
3145

46+
# Create an unsaved Entity object, and tell Datastore not to index the
47+
# `description` field
3248
task = datastore.Entity(key, exclude_from_indexes=["description"])
3349

50+
# Apply new field values and save the Task entity to Datastore
3451
task.update(
3552
{
3653
"created": datetime.datetime.utcnow(),
3754
"description": description,
3855
"done": False,
3956
}
4057
)
41-
4258
client.put(task)
43-
4459
return task.key
4560

4661

4762
# [END datastore_add_entity]
4863

4964

5065
# [START datastore_update_entity]
51-
def mark_done(client, task_id):
66+
def mark_done(client: datastore.Client, task_id: Union[str, int]):
5267
with client.transaction():
68+
# Create a key for an entity of kind "Task", and with the supplied
69+
# `task_id` as its Id
5370
key = client.key("Task", task_id)
71+
# Use that key to load the entity
5472
task = client.get(key)
5573

5674
if not task:
5775
raise ValueError(f"Task {task_id} does not exist.")
5876

77+
# Update a field indicating that the associated
78+
# work has been completed
5979
task["done"] = True
6080

81+
# Persist the change back to Datastore
6182
client.put(task)
6283

6384

6485
# [END datastore_update_entity]
6586

6687

6788
# [START datastore_retrieve_entities]
68-
def list_tasks(client):
89+
def list_tasks(client: datastore.Client):
90+
# Create a query against all of your objects of kind "Task"
6991
query = client.query(kind="Task")
7092
query.order = ["created"]
7193

@@ -76,8 +98,11 @@ def list_tasks(client):
7698

7799

78100
# [START datastore_delete_entity]
79-
def delete_task(client, task_id):
101+
def delete_task(client: datastore.Client, task_id: Union[str, int]):
102+
# Create a key for an entity of kind "Task", and with the supplied
103+
# `task_id` as its Id
80104
key = client.key("Task", task_id)
105+
# Use that key to delete its associated document, if it exists
81106
client.delete(key)
82107

83108

0 commit comments

Comments
 (0)