feat(firestore): async samples (GoogleCloudPlatform#4461)

rafilong · leahecole · crwilcox · web-flow · commit 0903921a4c6e · 2020-08-19T14:42:08.000-07:00
* feat(firestore): create async samples directory

* feat(firestore): update requirements to point to wip git branch

* feat(firestore): copy sync snippets to async client directory

* feat(firestore): create async snippets

* feat(firestore): copy sync distributed_counters sample to async client directory

* feat(firestore): create async distributed_counters sample

* feat(firestore): add _async suffix

Co-authored-by: Leah E. Cole &lt;6719667+leahecole@users.noreply.github.com&gt;
Co-authored-by: Christopher Wilcox &lt;crwilcox@google.com&gt;
diff --git a/firestore/cloud-async-client/distributed_counters.py b/firestore/cloud-async-client/distributed_counters.py
@@ -0,0 +1,81 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# [START fs_counter_classes_async]
+import random
+
+from google.cloud import firestore
+
+
+class Shard(object):
+    """
+    A shard is a distributed counter. Each shard can support being incremented
+    once per second. Multiple shards are needed within a Counter to allow
+    more frequent incrementing.
+    """
+
+    def __init__(self):
+        self._count = 0
+
+    def to_dict(self):
+        return {"count": self._count}
+
+
+class Counter(object):
+    """
+    A counter stores a collection of shards which are
+    summed to return a total count. This allows for more
+    frequent incrementing than a single document.
+    """
+
+    def __init__(self, num_shards):
+        self._num_shards = num_shards
+
+    # [END fs_counter_classes_async]
+
+    # [START fs_create_counter_async]
+    async def init_counter(self, doc_ref):
+        """
+        Create a given number of shards as
+        subcollection of specified document.
+        """
+        col_ref = doc_ref.collection("shards")
+
+        # Initialize each shard with count=0
+        for num in range(self._num_shards):
+            shard = Shard()
+            await col_ref.document(str(num)).set(shard.to_dict())
+
+    # [END fs_create_counter_async]
+
+    # [START fs_increment_counter_async]
+    async def increment_counter(self, doc_ref):
+        """Increment a randomly picked shard."""
+        doc_id = random.randint(0, self._num_shards - 1)
+
+        shard_ref = doc_ref.collection("shards").document(str(doc_id))
+        return await shard_ref.update({"count": firestore.Increment(1)})
+
+    # [END fs_increment_counter_async]
+
+    # [START fs_get_count_async]
+    async def get_count(self, doc_ref):
+        """Return a total count across all shards."""
+        total = 0
+        shards = doc_ref.collection("shards").list_documents()
+        async for shard in shards:
+            total += (await shard.get()).to_dict().get("count", 0)
+        return total
+
+    # [END fs_get_count_async]
diff --git a/firestore/cloud-async-client/distributed_counters_test.py b/firestore/cloud-async-client/distributed_counters_test.py
@@ -0,0 +1,62 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from google.cloud import firestore
+import pytest
+
+import distributed_counters
+
+pytestmark = pytest.mark.asyncio
+
+shards_list = []
+doc_ref = None
+
+
+@pytest.fixture
+def fs_client():
+    yield firestore.AsyncClient()
+
+    # clean up
+    for shard in shards_list:
+        shard.delete()
+
+    if doc_ref:
+        doc_ref.delete()
+
+
+async def test_distributed_counters(fs_client):
+    col = fs_client.collection("dc_samples")
+    doc_ref = col.document("distributed_counter")
+    counter = distributed_counters.Counter(2)
+    await counter.init_counter(doc_ref)
+
+    shards = doc_ref.collection("shards").list_documents()
+    shards_list = [shard async for shard in shards]
+    assert len(shards_list) == 2
+
+    await counter.increment_counter(doc_ref)
+    await counter.increment_counter(doc_ref)
+    assert await counter.get_count(doc_ref) == 2
+
+
+async def test_distributed_counters_cleanup(fs_client):
+    col = fs_client.collection("dc_samples")
+    doc_ref = col.document("distributed_counter")
+
+    shards = doc_ref.collection("shards").list_documents()
+    shards_list = [shard async for shard in shards]
+    for shard in shards_list:
+        await shard.delete()
+
+    await doc_ref.delete()
diff --git a/firestore/cloud-async-client/snippets.py b/firestore/cloud-async-client/snippets.py
@@ -95,7 +95,7 @@ def __init__(self, name, state, country, capital=False, population=0, regions=[]
 
     @staticmethod
     def from_dict(source):
-        # [START_EXCLUDE_async]
+        # [START_EXCLUDE]
         city = City(source["name"], source["state"], source["country"])
 
         if "capital" in source:
@@ -108,10 +108,10 @@ def from_dict(source):
             city.regions = source["regions"]
 
         return city
-        # [END_EXCLUDE_async]
+        # [END_EXCLUDE]
 
     def to_dict(self):
-        # [START_EXCLUDE_async]
+        # [START_EXCLUDE]
         dest = {"name": self.name, "state": self.state, "country": self.country}
 
         if self.capital:
@@ -124,7 +124,7 @@ def to_dict(self):
             dest["regions"] = self.regions
 
         return dest
-        # [END_EXCLUDE_async]
+        # [END_EXCLUDE]
 
     def __repr__(self):
         return f"City(\
