Implement Global Cache (memcache) (#148)

Makes use of @takashi8 's surprise #130 contribution.

docs/global_cache.rst

@@ -0,0 +1,7 @@
+#######
+Context
+#######
+
+.. automodule:: google.cloud.ndb.global_cache
+    :members:
+    :show-inheritance:

docs/index.rst

@@ -8,6 +8,7 @@
 
    client
    context
+   global_cache
    key
    model
    query

docs/spelling_wordlist.txt

@@ -65,6 +65,7 @@ protobuf
 proxied
 QueryOptions
 reimplemented
+Redis
 RequestHandler
 runtime
 schemas

src/google/cloud/ndb/__init__.py

@@ -52,6 +52,7 @@
     "get_indexes_async",
     "get_multi",
     "get_multi_async",
+    "GlobalCache",
     "in_transaction",
     "Index",
     "IndexProperty",
@@ -135,6 +136,7 @@
 from google.cloud.ndb._datastore_api import STRONG
 from google.cloud.ndb._datastore_query import Cursor
 from google.cloud.ndb._datastore_query import QueryIterator
+from google.cloud.ndb.global_cache import GlobalCache
 from google.cloud.ndb.key import Key
 from google.cloud.ndb.model import BlobKey
 from google.cloud.ndb.model import BlobKeyProperty

src/google/cloud/ndb/_batch.py

@@ -0,0 +1,66 @@
+# Copyright 2018 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
+#
+#     https://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.
+
+"""Support for batching operations."""
+
+from google.cloud.ndb import context as context_module
+from google.cloud.ndb import _eventloop
+
+
+def get_batch(batch_cls, options=None):
+    """Gets a data structure for storing batched calls to Datastore Lookup.
+
+    The batch data structure is stored in the current context. If there is
+    not already a batch started, a new structure is created and an idle
+    callback is added to the current event loop which will eventually perform
+    the batch look up.
+
+    Args:
+        batch_cls (type): Class representing the kind of operation being
+            batched.
+        options (_options.ReadOptions): The options for the request. Calls with
+            different options will be placed in different batches.
+
+    Returns:
+        batch_cls: An instance of the batch class.
+    """
+    context = context_module.get_context()
+    batches = context.batches.get(batch_cls)
+    if batches is None:
+        context.batches[batch_cls] = batches = {}
+
+    if options is not None:
+        options_key = tuple(
+            sorted(
+                (
+                    (key, value)
+                    for key, value in options.items()
+                    if value is not None
+                )
+            )
+        )
+    else:
+        options_key = ()
+
+    batch = batches.get(options_key)
+    if batch is not None:
+        return batch
+
+    def idle():
+        batch = batches.pop(options_key)
+        batch.idle_callback()
+
+    batches[options_key] = batch = batch_cls(options)
+    _eventloop.add_idle(idle)
+    return batch