Instruction:
Can you generate a brief explanation for the following Python 3 code
def _get_async(self, **q_options):
    res = yield self.fetch_async(1, **q_options)
    if not res:
      raise tasklets.Return(None)
    raise tasklets.Return(res[0])

Response: Internal version of get_async.


Instruction:
Write a Python 3 function for
counting the number of query results up to a limit.

Response:
def count_async(self, limit=None, **q_options):
    """Count the number of query results, up to a limit.

    This is the asynchronous version of Query.count().
    """
    qry = self._fix_namespace()
    return qry._count_async(limit=limit, **q_options)


Instruction:
Implement a function in Python 3 to
fetch a page of results. This is the asynchronous version of Query. fetch_page.

Response:
def fetch_page_async(self, page_size, **q_options):
    """Fetch a page of results.

    This is the asynchronous version of Query.fetch_page().
    """
    qry = self._fix_namespace()
    return qry._fetch_page_async(page_size, **q_options)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _fetch_page_async(self, page_size, **q_options):
    q_options.setdefault('batch_size', page_size)
    q_options.setdefault('produce_cursors', True)
    it = self.iter(limit=page_size + 1, **q_options)
    results = []
    while (yield it.has_next_async()):
      results.append(it.next())
      if len(results) >= page_size:
        break
    try:
      cursor = it.cursor_after()
    except datastore_errors.BadArgumentError:
      cursor = None
    raise tasklets.Return(results, cursor, it.probably_has_next())

Response: Internal version of fetch_page_async.


Instruction:
Make a summary of the following Python 3 code
def analyze(self):
    class MockBindings(dict):

      def __contains__(self, key):
        self[key] = None
        return True
    bindings = MockBindings()
    used = {}
    ancestor = self.ancestor
    if isinstance(ancestor, ParameterizedThing):
      ancestor = ancestor.resolve(bindings, used)
    filters = self.filters
    if filters is not None:
      filters = filters.resolve(bindings, used)
    return sorted(used)

Response: Return a list giving the parameters required by a query.


Instruction:
Can you write a function in Python 3 where it
binds parameter values. Returns a new Query object.

Response:
def _bind(self, args, kwds):
    """Bind parameter values.  Returns a new Query object."""
    bindings = dict(kwds)
    for i, arg in enumerate(args):
      bindings[i + 1] = arg
    used = {}
    ancestor = self.ancestor
    if isinstance(ancestor, ParameterizedThing):
      ancestor = ancestor.resolve(bindings, used)
    filters = self.filters
    if filters is not None:
      filters = filters.resolve(bindings, used)
    unused = []
    for i in xrange(1, 1 + len(args)):
      if i not in used:
        unused.append(i)
    if unused:
      raise datastore_errors.BadArgumentError(
          'Positional arguments %s were given but not used.' %
          ', '.join(str(i) for i in unused))
    return self.__class__(kind=self.kind, ancestor=ancestor,
                          filters=filters, orders=self.orders,
                          app=self.app, namespace=self.namespace,
                          default_options=self.default_options,
                          projection=self.projection, group_by=self.group_by)


Instruction:
Create a Python 3 function for
returning the cursor before the current item.

Response:
def cursor_before(self):
    """Return the cursor before the current item.

    You must pass a QueryOptions object with produce_cursors=True
    for this to work.

    If there is no cursor or no current item, raise BadArgumentError.
    Before next() has returned there is no cursor.  Once the loop is
    exhausted, this returns the cursor after the last item.
    """
    if self._exhausted:
      return self.cursor_after()
    if isinstance(self._cursor_before, BaseException):
      raise self._cursor_before
    return self._cursor_before


Instruction:
Create a Python 3 function to
return the cursor after the current item.

Response:
def cursor_after(self):
    """Return the cursor after the current item.

    You must pass a QueryOptions object with produce_cursors=True
    for this to work.

    If there is no cursor or no current item, raise BadArgumentError.
    Before next() has returned there is no cursor.    Once the loop is
    exhausted, this returns the cursor after the last item.
    """
    if isinstance(self._cursor_after, BaseException):
      raise self._cursor_after
    return self._cursor_after


Instruction:
Can you generate a brief explanation for the following Python 3 code
def has_next_async(self):
    if self._fut is None:
      self._fut = self._iter.getq()
    flag = True
    try:
      yield self._fut
    except EOFError:
      flag = False
    raise tasklets.Return(flag)

Response: Return a Future whose result will say whether a next item is available.


Instruction:
Make a summary of the following Python 3 code
def next(self):
    if self._fut is None:
      self._fut = self._iter.getq()
    try:
      try:
        # The future result is set by this class's _extended_callback
        # method.
        # pylint: disable=unpacking-non-sequence
        (ent,
         self._cursor_before,
         self._cursor_after,
         self._more_results) = self._fut.get_result()
        return ent
      except EOFError:
        self._exhausted = True
        raise StopIteration
    finally:
      self._fut = None

Response: Iterator protocol for get next item or raise StopIteration.


Instruction:
Implement a function in Python 3 to
run this query and put entities into the given queue.

Response:
def run_to_queue(self, queue, conn, options=None):
    """Run this query, putting entities into the given queue."""
    if options is None:
      # Default options.
      offset = None
      limit = None
      keys_only = None
    else:
      # Capture options we need to simulate.
      offset = options.offset
      limit = options.limit
      keys_only = options.keys_only

      # Cursors are supported for certain orders only.
      if (options.start_cursor or options.end_cursor or
          options.produce_cursors):
        names = set()
        if self.__orders is not None:
          names = self.__orders._get_prop_names()
        if '__key__' not in names:
          raise datastore_errors.BadArgumentError(
              '_MultiQuery with cursors requires __key__ order')

    # Decide if we need to modify the options passed to subqueries.
    # NOTE: It would seem we can sometimes let Cloud Datastore handle
    # the offset natively, but this would thwart the duplicate key
    # detection, so we always have to emulate the offset here.
    # We can set the limit we pass along to offset + limit though,
    # since that is the maximum number of results from a single
    # subquery we will ever have to consider.
    modifiers = {}
    if offset:
      modifiers['offset'] = None
      if limit is not None:
        modifiers['limit'] = min(_MAX_LIMIT, offset + limit)
    if keys_only and self.__orders is not None:
      modifiers['keys_only'] = None
    if modifiers:
      options = QueryOptions(config=options, **modifiers)

    if offset is None:
      offset = 0

    if limit is None:
      limit = _MAX_LIMIT

    if self.__orders is None:
      # Run the subqueries sequentially; there is no order to keep.
      keys_seen = set()
      for subq in self.__subqueries:
        if limit <= 0:
          break
        subit = tasklets.SerialQueueFuture('_MultiQuery.run_to_queue[ser]')
        subq.run_to_queue(subit, conn, options=options)
        while limit > 0:
          try:
            batch, index, result = yield subit.getq()
          except EOFError:
            break
          if keys_only:
            key = result
          else:
            key = result._key
          if key not in keys_seen:
            keys_seen.add(key)
            if offset > 0:
              offset -= 1
            else:
              limit -= 1
              queue.putq((None, None, result))
      queue.complete()
      return

    # This with-statement causes the adapter to set _orig_pb on all
    # entities it converts from protobuf.
    # TODO: Does this interact properly with the cache?
    with conn.adapter:
      # Start running all the sub-queries.
      todo = []  # List of (subit, dsquery) tuples.
      for subq in self.__subqueries:
        dsquery = subq._get_query(conn)
        subit = tasklets.SerialQueueFuture('_MultiQuery.run_to_queue[par]')
        subq.run_to_queue(subit, conn, options=options, dsquery=dsquery)
        todo.append((subit, dsquery))

      # Create a list of (first-entity, subquery-iterator) tuples.
      state = []  # List of _SubQueryIteratorState instances.
      for subit, dsquery in todo:
        try:
          thing = yield subit.getq()
        except EOFError:
          continue
        else:
          state.append(_SubQueryIteratorState(thing, subit, dsquery,
                                              self.__orders))

      # Now turn it into a sorted heap.  The heapq module claims that
      # calling heapify() is more efficient than calling heappush() for
      # each item.
      heapq.heapify(state)

      # Repeatedly yield the lowest entity from the state vector,
      # filtering duplicates.  This is essentially a multi-way merge
      # sort.  One would think it should be possible to filter
      # duplicates simply by dropping other entities already in the
      # state vector that are equal to the lowest entity, but because of
      # the weird sorting of repeated properties, we have to explicitly
      # keep a set of all keys, so we can remove later occurrences.
      # Note that entities will still be sorted correctly, within the
      # constraints given by the sort order.
      keys_seen = set()
      while state and limit > 0:
        item = heapq.heappop(state)
        batch = item.batch
        index = item.index
        entity = item.entity
        key = entity._key
        if key not in keys_seen:
          keys_seen.add(key)
          if offset > 0:
            offset -= 1
          else:
            limit -= 1
            if keys_only:
              queue.putq((batch, index, key))
            else:
              queue.putq((batch, index, entity))
        subit = item.iterator
        try:
          batch, index, entity = yield subit.getq()
        except EOFError:
          pass
        else:
          item.batch = batch
          item.index = index
          item.entity = entity
          heapq.heappush(state, item)
      queue.complete()


Instruction:
Implement a function in Python 3 to
wrap for memcache. get.

Response:
def memcache_get(self, key, for_cas=False, namespace=None, use_cache=False,
                   deadline=None):
    """An auto-batching wrapper for memcache.get() or .get_multi().

    Args:
      key: Key to set.  This must be a string; no prefix is applied.
      for_cas: If True, request and store CAS ids on the Context.
      namespace: Optional namespace.
      deadline: Optional deadline for the RPC.

    Returns:
      A Future (!) whose return value is the value retrieved from
      memcache, or None.
    """
    if not isinstance(key, basestring):
      raise TypeError('key must be a string; received %r' % key)
    if not isinstance(for_cas, bool):
      raise TypeError('for_cas must be a bool; received %r' % for_cas)
    if namespace is None:
      namespace = namespace_manager.get_namespace()
    options = (for_cas, namespace, deadline)
    batcher = self.memcache_get_batcher
    if use_cache:
      return batcher.add_once(key, options)
    else:
      return batcher.add(key, options)


Instruction:
Make a summary of the following Python 3 code
def positional(max_pos_args):
  __ndb_debug__ = 'SKIP'

  def positional_decorator(wrapped):
    if not DEBUG:
      return wrapped
    __ndb_debug__ = 'SKIP'

    @wrapping(wrapped)
    def positional_wrapper(*args, **kwds):
      __ndb_debug__ = 'SKIP'
      if len(args) > max_pos_args:
        plural_s = ''
        if max_pos_args != 1:
          plural_s = 's'
        raise TypeError(
            '%s() takes at most %d positional argument%s (%d given)' %
            (wrapped.__name__, max_pos_args, plural_s, len(args)))
      return wrapped(*args, **kwds)
    return positional_wrapper
  return positional_decorator

Response: A decorator to declare that only the first N arguments may be positional.


Instruction:
Can you tell what is the following Python 3 function doing
def decorator(wrapped_decorator):
  def helper(_func=None, **options):
    def outer_wrapper(func):
      @wrapping(func)
      def inner_wrapper(*args, **kwds):
        return wrapped_decorator(func, args, kwds, **options)
      return inner_wrapper

    if _func is None:
      # Form (2), with options.
      return outer_wrapper

    # Form (1), vanilla.
    if options:
      # Don't allow @decorator(foo, op1=5).
      raise TypeError('positional arguments not supported')
    return outer_wrapper(_func)
  helper.wrapped_decorator = wrapped_decorator
  return helper

Response: A decorator that returns a function that accepts keyword arguments in its declaration.


Instruction:
Here you have a function in Python 3, explain what it does
def fibonacci(n):
  if n <= 1:
    raise ndb.Return(n)
  a, b = yield fibonacci(n - 1), fibonacci(n - 2)
  raise ndb.Return(a + b)

Response: A recursive Fibonacci to exercise task switching.


Instruction:
Can you tell what is the following Python 3 function doing
def memoizing_fibonacci(n):
  if n <= 1:
    raise ndb.Return(n)
  key = ndb.Key(FibonacciMemo, str(n))
  memo = yield key.get_async(ndb_should_cache=False)
  if memo is not None:
    assert memo.arg == n
    logging.info('memo hit: %d -> %d', n, memo.value)
    raise ndb.Return(memo.value)
  logging.info('memo fail: %d', n)
  a = yield memoizing_fibonacci(n - 1)
  b = yield memoizing_fibonacci(n - 2)
  ans = a + b
  memo = FibonacciMemo(key=key, arg=n, value=ans)
  logging.info('memo write: %d -> %d', n, memo.value)
  yield memo.put_async(ndb_should_cache=False)
  raise ndb.Return(ans)

Response: A memoizing recursive Fibonacci to exercise RPCs.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def run_queue(self, options, todo):
    utils.logging_debug('AutoBatcher(%s): %d items',
                        self._todo_tasklet.__name__, len(todo))
    batch_fut = self._todo_tasklet(todo, options)
    self._running.append(batch_fut)
    # Add a callback when we're done.
    batch_fut.add_callback(self._finished_callback, batch_fut, todo)

Response: Actually run the _todo_tasklet.


Instruction:
Write a Python 3 function that can
add an arg and returns a future.

Response:
def add(self, arg, options=None):
    """Adds an arg and gets back a future.

    Args:
      arg: one argument for _todo_tasklet.
      options: rpc options.

    Return:
      An instance of future, representing the result of running
        _todo_tasklet without batching.
    """
    fut = tasklets.Future('%s.add(%s, %s)' % (self, arg, options))
    todo = self._queues.get(options)
    if todo is None:
      utils.logging_debug('AutoBatcher(%s): creating new queue for %r',
                          self._todo_tasklet.__name__, options)
      if not self._queues:
        eventloop.add_idle(self._on_idle)
      todo = self._queues[options] = []
    todo.append((fut, arg))
    if len(todo) >= self._limit:
      del self._queues[options]
      self.run_queue(options, todo)
    return fut


Instruction:
Can you generate the documentation for the following Python 3 function
def _finished_callback(self, batch_fut, todo):
    self._running.remove(batch_fut)
    err = batch_fut.get_exception()
    if err is not None:
      tb = batch_fut.get_traceback()
      for (fut, _) in todo:
        if not fut.done():
          fut.set_exception(err, tb)

Response: Called by the tasklet when the batch future has finished.


Instruction:
Can you generate the documentation for the following Python 3 function
def get_namespaces(start=None, end=None):
  q = Namespace.query()
  if start is not None:
    q = q.filter(Namespace.key >= Namespace.key_for_namespace(start))
  if end is not None:
    q = q.filter(Namespace.key < Namespace.key_for_namespace(end))
  return [x.namespace_name for x in q]

Response: Return all namespaces in the specified range.


Instruction:
Can you write a function in Python 3 where it
returns all kinds in the specified range for the current namespace.

Response:
def get_kinds(start=None, end=None):
  """Return all kinds in the specified range, for the current namespace.

  Args:
    start: only return kinds >= start if start is not None.
    end: only return kinds < end if end is not None.

  Returns:
    A list of kind names between the (optional) start and end values.
  """
  q = Kind.query()
  if start is not None and start != '':
    q = q.filter(Kind.key >= Kind.key_for_kind(start))
  if end is not None:
    if end == '':
      return []
    q = q.filter(Kind.key < Kind.key_for_kind(end))

  return [x.kind_name for x in q]


Instruction:
Can you generate the documentation for the following Python 3 function
def get_properties_of_kind(kind, start=None, end=None):
  q = Property.query(ancestor=Property.key_for_kind(kind))
  if start is not None and start != '':
    q = q.filter(Property.key >= Property.key_for_property(kind, start))
  if end is not None:
    if end == '':
      return []
    q = q.filter(Property.key < Property.key_for_property(kind, end))

  return [Property.key_to_property(k) for k in q.iter(keys_only=True)]

Response: Return all properties of the specified kind in the specified range.


Instruction:
Create a Python 3 function for
returning all representations of properties of the specified kind in the specified range.

Response:
def get_representations_of_kind(kind, start=None, end=None):
  """Return all representations of properties of kind in the specified range.

  NOTE: This function does not return unindexed properties.

  Args:
    kind: name of kind whose properties you want.
    start: only return properties >= start if start is not None.
    end: only return properties < end if end is not None.

  Returns:
    A dictionary mapping property names to its list of representations.
  """
  q = Property.query(ancestor=Property.key_for_kind(kind))
  if start is not None and start != '':
    q = q.filter(Property.key >= Property.key_for_property(kind, start))
  if end is not None:
    if end == '':
      return {}
    q = q.filter(Property.key < Property.key_for_property(kind, end))

  result = {}
  for property in q:
    result[property.property_name] = property.property_representation

  return result


Instruction:
Write a Python 3 script for
returning the version of the entity group containing key.

Response:
def get_entity_group_version(key):
  """Return the version of the entity group containing key.

  Args:
    key: a key for an entity group whose __entity_group__ key you want.

  Returns:
    The version of the entity group containing key. This version is
    guaranteed to increase on every change to the entity group. The version
    may increase even in the absence of user-visible changes to the entity
    group. May return None if the entity group was never written to.

    On non-HR datatores, this function returns None.
  """

  eg = EntityGroup.key_for_entity_group(key).get()
  if eg:
    return eg.version
  else:
    return None


Instruction:
How would you code a function in Python 3 to
return the Key for a namespace.

Response:
def key_for_namespace(cls, namespace):
    """Return the Key for a namespace.

    Args:
      namespace: A string giving the namespace whose key is requested.

    Returns:
      The Key for the namespace.
    """
    if namespace:
      return model.Key(cls.KIND_NAME, namespace)
    else:
      return model.Key(cls.KIND_NAME, cls.EMPTY_NAMESPACE_ID)


Instruction:
Write a Python 3 script for
returning the key for the given property of the given kind.

Response:
def key_for_property(cls, kind, property):
    """Return the __property__ key for property of kind.

    Args:
      kind: kind whose key is requested.
      property: property whose key is requested.

    Returns:
      The key for property of kind.
    """
    return model.Key(Kind.KIND_NAME, kind, Property.KIND_NAME, property)


Instruction:
Create a Python 3 function for
returning the kind name of a given key.

Response:
def key_to_kind(cls, key):
    """Return the kind specified by a given __property__ key.

    Args:
      key: key whose kind name is requested.

    Returns:
      The kind specified by key.
    """
    if key.kind() == Kind.KIND_NAME:
      return key.id()
    else:
      return key.parent().id()


Instruction:
Can you tell what is the following Python 3 function doing
def key_for_entity_group(cls, key):
    return model.Key(cls.KIND_NAME, cls.ID, parent=key.root())

Response: Return the key for the entity group containing key.


Instruction:
Can you tell what is the following Python 3 function doing
def process_request(self, unused_request):
    # Compare to the first half of toplevel() in context.py.
    tasklets._state.clear_all_pending()
    # Create and install a new context.
    ctx = tasklets.make_default_context()
    tasklets.set_context(ctx)

Response: Called by Django before deciding which view to execute.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _make_ctx_options(ctx_options, config_cls=ContextOptions):
  if not ctx_options:
    return None
  for key in list(ctx_options):
    translation = _OPTION_TRANSLATIONS.get(key)
    if translation:
      if translation in ctx_options:
        raise ValueError('Cannot specify %s and %s at the same time' %
                         (key, translation))
      ctx_options[translation] = ctx_options.pop(key)
  return config_cls(**ctx_options)

Response: Helper function to construct a ContextOptions object from keyword arguments.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def set_cache_policy(self, func):
    if func is None:
      func = self.default_cache_policy
    elif isinstance(func, bool):
      func = lambda unused_key, flag=func: flag
    self._cache_policy = func

Response: Sets the context cache policy function.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _use_cache(self, key, options=None):
    flag = ContextOptions.use_cache(options)
    if flag is None:
      flag = self._cache_policy(key)
    if flag is None:
      flag = ContextOptions.use_cache(self._conn.config)
    if flag is None:
      flag = True
    return flag

Response: Return whether to use the context cache for this key.


Instruction:
How would you implement a function in Python 3 that
sets the memcache policy function.

Response:
def set_memcache_policy(self, func):
    """Set the memcache policy function.

    Args:
      func: A function that accepts a Key instance as argument and returns
        a bool indicating if it should be cached.  May be None.
    """
    if func is None:
      func = self.default_memcache_policy
    elif isinstance(func, bool):
      func = lambda unused_key, flag=func: flag
    self._memcache_policy = func


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _use_memcache(self, key, options=None):
    flag = ContextOptions.use_memcache(options)
    if flag is None:
      flag = self._memcache_policy(key)
    if flag is None:
      flag = ContextOptions.use_memcache(self._conn.config)
    if flag is None:
      flag = True
    return flag

Response: Return whether to use memcache for this key.


Instruction:
Make a summary of the following Python 3 code
def default_datastore_policy(key):
    flag = None
    if key is not None:
      modelclass = model.Model._kind_map.get(key.kind())
      if modelclass is not None:
        policy = getattr(modelclass, '_use_datastore', None)
        if policy is not None:
          if isinstance(policy, bool):
            flag = policy
          else:
            flag = policy(key)
    return flag

Response:
Default datastore policy.

    This defers to _use_datastore on the Model class.

    Args:
      key: Key instance.

    Returns:
      A bool or None.


Instruction:
Here you have a function in Python 3, explain what it does
def set_datastore_policy(self, func):
    if func is None:
      func = self.default_datastore_policy
    elif isinstance(func, bool):
      func = lambda unused_key, flag=func: flag
    self._datastore_policy = func

Response: Set the context datastore policy function.


Instruction:
Write a Python 3 script for
returning whether to use the datastore for this key.

Response:
def _use_datastore(self, key, options=None):
    """Return whether to use the datastore for this key.

    Args:
      key: Key instance.
      options: ContextOptions instance, or None.

    Returns:
      True if the datastore should be used, False otherwise.
    """
    flag = ContextOptions.use_datastore(options)
    if flag is None:
      flag = self._datastore_policy(key)
    if flag is None:
      flag = ContextOptions.use_datastore(self._conn.config)
    if flag is None:
      flag = True
    return flag


Instruction:
How would you explain what the following Python 3 function does
def default_memcache_timeout_policy(key):
    timeout = None
    if key is not None and isinstance(key, model.Key):
      modelclass = model.Model._kind_map.get(key.kind())
      if modelclass is not None:
        policy = getattr(modelclass, '_memcache_timeout', None)
        if policy is not None:
          if isinstance(policy, (int, long)):
            timeout = policy
          else:
            timeout = policy(key)
    return timeout

Response: Default memcache timeout policy.


Instruction:
Create a Python 3 function to
set the policy function for memcache timeout expiration.

Response:
def set_memcache_timeout_policy(self, func):
    """Set the policy function for memcache timeout (expiration).

    Args:
      func: A function that accepts a key instance as argument and returns
        an integer indicating the desired memcache timeout.  May be None.

    If the function returns 0 it implies the default timeout.
    """
    if func is None:
      func = self.default_memcache_timeout_policy
    elif isinstance(func, (int, long)):
      func = lambda unused_key, flag=func: flag
    self._memcache_timeout_policy = func


Instruction:
Write a Python 3 script for
returning the memcache timeout for this key.

Response:
def _get_memcache_timeout(self, key, options=None):
    """Return the memcache timeout (expiration) for this key."""
    timeout = ContextOptions.memcache_timeout(options)
    if timeout is None:
      timeout = self._memcache_timeout_policy(key)
    if timeout is None:
      timeout = ContextOptions.memcache_timeout(self._conn.config)
    if timeout is None:
      timeout = 0
    return timeout


Instruction:
Implement a Python 3 function for
returning a cached Model instance given the entity key if available.

Response:
def _load_from_cache_if_available(self, key):
    """Returns a cached Model instance given the entity key if available.

    Args:
      key: Key instance.

    Returns:
      A Model instance if the key exists in the cache.
    """
    if key in self._cache:
      entity = self._cache[key]  # May be None, meaning "doesn't exist".
      if entity is None or entity._key == key:
        # If entity's key didn't change later, it is ok.
        # See issue 13.  http://goo.gl/jxjOP
        raise tasklets.Return(entity)


Instruction:
Can you write a function in Python 3 where it
gets a Model instance given the entity key.

Response:
def get(self, key, **ctx_options):
    """Return a Model instance given the entity key.

    It will use the context cache if the cache policy for the given
    key is enabled.

    Args:
      key: Key instance.
      **ctx_options: Context options.

    Returns:
      A Model instance if the key exists in the datastore; None otherwise.
    """
    options = _make_ctx_options(ctx_options)
    use_cache = self._use_cache(key, options)
    if use_cache:
      self._load_from_cache_if_available(key)

    use_datastore = self._use_datastore(key, options)
    if (use_datastore and
        isinstance(self._conn, datastore_rpc.TransactionalConnection)):
      use_memcache = False
    else:
      use_memcache = self._use_memcache(key, options)
    ns = key.namespace()
    memcache_deadline = None  # Avoid worries about uninitialized variable.

    if use_memcache:
      mkey = self._memcache_prefix + key.urlsafe()
      memcache_deadline = self._get_memcache_deadline(options)
      mvalue = yield self.memcache_get(mkey, for_cas=use_datastore,
                                       namespace=ns, use_cache=True,
                                       deadline=memcache_deadline)
      # A value may have appeared while yielding.
      if use_cache:
        self._load_from_cache_if_available(key)
      if mvalue not in (_LOCKED, None):
        cls = model.Model._lookup_model(key.kind(),
                                        self._conn.adapter.default_model)
        pb = entity_pb.EntityProto()

        try:
          pb.MergePartialFromString(mvalue)
        except ProtocolBuffer.ProtocolBufferDecodeError:
          logging.warning('Corrupt memcache entry found '
                          'with key %s and namespace %s' % (mkey, ns))
          mvalue = None
        else:
          entity = cls._from_pb(pb)
          # Store the key on the entity since it wasn't written to memcache.
          entity._key = key
          if use_cache:
            # Update in-memory cache.
            self._cache[key] = entity
          raise tasklets.Return(entity)

      if mvalue is None and use_datastore:
        yield self.memcache_set(mkey, _LOCKED, time=_LOCK_TIME, namespace=ns,
                                use_cache=True, deadline=memcache_deadline)
        yield self.memcache_gets(mkey, namespace=ns, use_cache=True,
                                 deadline=memcache_deadline)

    if not use_datastore:
      # NOTE: Do not cache this miss.  In some scenarios this would
      # prevent an app from working properly.
      raise tasklets.Return(None)

    if use_cache:
      entity = yield self._get_batcher.add_once(key, options)
    else:
      entity = yield self._get_batcher.add(key, options)

    if entity is not None:
      if use_memcache and mvalue != _LOCKED:
        # Don't serialize the key since it's already the memcache key.
        pbs = entity._to_pb(set_key=False).SerializePartialToString()
        # Don't attempt to write to memcache if too big.  Note that we
        # use LBYL ("look before you leap") because a multi-value
        # memcache operation would fail for all entities rather than
        # for just the one that's too big.  (Also, the AutoBatcher
        # class doesn't pass back exceptions very well.)
        if len(pbs) <= memcache.MAX_VALUE_SIZE:
          timeout = self._get_memcache_timeout(key, options)
          # Don't use fire-and-forget -- for users who forget
          # @ndb.toplevel, it's too painful to diagnose why their simple
          # code using a single synchronous call doesn't seem to use
          # memcache.  See issue 105.  http://goo.gl/JQZxp
          yield self.memcache_cas(mkey, pbs, time=timeout, namespace=ns,
                                  deadline=memcache_deadline)

    if use_cache:
      # Cache hit or miss.  NOTE: In this case it is okay to cache a
      # miss; the datastore is the ultimate authority.
      self._cache[key] = entity

    raise tasklets.Return(entity)


Instruction:
How would you explain what the following Python 3 function does
def call_on_commit(self, callback):
    if not self.in_transaction():
      callback()
    else:
      self._on_commit_queue.append(callback)

Response: Call a callback upon successful commit of a transaction.


Instruction:
How would you code a function in Python 3 to
return a Future for a nickname from an account.

Response:
def get_nickname(userid):
  """Return a Future for a nickname from an account."""
  account = yield get_account(userid)
  if not account:
    nickname = 'Unregistered'
  else:
    nickname = account.nickname or account.email
  raise ndb.Return(nickname)


Instruction:
Implement a function in Python 3 to
mark a task as done.

Response:
def mark_done(task_id):
  """Marks a task as done.

  Args:
    task_id: The integer id of the task to update.

  Raises:
    ValueError: if the requested task doesn't exist.
  """
  task = Task.get_by_id(task_id)
  if task is None:
    raise ValueError('Task with id %d does not exist' % task_id)
  task.done = True
  task.put()


Instruction:
Can you generate a brief explanation for the following Python 3 code
def format_tasks(tasks):
  return ['%d : %s (%s)' % (task.key.id(),
                            task.description,
                            ('done' if task.done
                             else 'created %s' % task.created))
          for task in tasks]

Response: Converts a list of tasks to a list of string representations.


Instruction:
Write a Python 3 function for
accepting a string command and performs an action.

Response:
def handle_command(command):
  """Accepts a string command and performs an action.

  Args:
    command: the command to run as a string.
  """
  try:
    cmds = command.split(None, 1)
    cmd = cmds[0]
    if cmd == 'new':
      add_task(get_arg(cmds))
    elif cmd == 'done':
      mark_done(int(get_arg(cmds)))
    elif cmd == 'list':
      for task in format_tasks(list_tasks()):
        print task
    elif cmd == 'delete':
      delete_task(int(get_arg(cmds)))
    else:
      print_usage()
  except Exception, e:  # pylint: disable=broad-except
    print e
    print_usage()


Instruction:
Can you generate a brief explanation for the following Python 3 code
def delete_async(blob_key, **options):
  if not isinstance(blob_key, (basestring, BlobKey)):
    raise TypeError('Expected blob key, got %r' % (blob_key,))
  rpc = blobstore.create_rpc(**options)
  yield blobstore.delete_async(blob_key, rpc=rpc)

Response: Async version of delete.


Instruction:
Implement a function in Python 3 to
create upload URL for POST form.

Response:
def create_upload_url(success_path,
                      max_bytes_per_blob=None,
                      max_bytes_total=None,
                      **options):
  """Create upload URL for POST form.

  Args:
    success_path: Path within application to call when POST is successful
      and upload is complete.
    max_bytes_per_blob: The maximum size in bytes that any one blob in the
      upload can be or None for no maximum size.
    max_bytes_total: The maximum size in bytes that the aggregate sizes of all
      of the blobs in the upload can be or None for no maximum size.
    **options: Options for create_rpc().

  Returns:
    The upload URL.

  Raises:
    TypeError: If max_bytes_per_blob or max_bytes_total are not integral types.
    ValueError: If max_bytes_per_blob or max_bytes_total are not
      positive values.
  """
  fut = create_upload_url_async(success_path,
                                max_bytes_per_blob=max_bytes_per_blob,
                                max_bytes_total=max_bytes_total,
                                **options)
  return fut.get_result()


Instruction:
Can you tell what is the following Python 3 function doing
def parse_blob_info(field_storage):
  if field_storage is None:
    return None

  field_name = field_storage.name

  def get_value(dct, name):
    value = dct.get(name, None)
    if value is None:
      raise BlobInfoParseError(
          'Field %s has no %s.' % (field_name, name))
    return value

  filename = get_value(field_storage.disposition_options, 'filename')
  blob_key_str = get_value(field_storage.type_options, 'blob-key')
  blob_key = BlobKey(blob_key_str)

  upload_content = email.message_from_file(field_storage.file)
  content_type = get_value(upload_content, 'content-type')
  size = get_value(upload_content, 'content-length')
  creation_string = get_value(upload_content, UPLOAD_INFO_CREATION_HEADER)
  md5_hash_encoded = get_value(upload_content, 'content-md5')
  md5_hash = base64.urlsafe_b64decode(md5_hash_encoded)

  try:
    size = int(size)
  except (TypeError, ValueError):
    raise BlobInfoParseError(
        '%s is not a valid value for %s size.' % (size, field_name))

  try:
    creation = blobstore._parse_creation(creation_string, field_name)
  except blobstore._CreationFormatError, err:
    raise BlobInfoParseError(str(err))

  return BlobInfo(id=blob_key_str,
                  content_type=content_type,
                  creation=creation,
                  filename=filename,
                  size=size,
                  md5_hash=md5_hash,
                 )

Response: Parse a BlobInfo record from a file upload field_storage.


Instruction:
Create a Python 3 function for
fetching data for a blob.

Response:
def fetch_data(blob, start_index, end_index, **options):
  """Fetch data for blob.

  Fetches a fragment of a blob up to MAX_BLOB_FETCH_SIZE in length.  Attempting
  to fetch a fragment that extends beyond the boundaries of the blob will return
  the amount of data from start_index until the end of the blob, which will be
  a smaller size than requested.  Requesting a fragment which is entirely
  outside the boundaries of the blob will return empty string.  Attempting
  to fetch a negative index will raise an exception.

  Args:
    blob: BlobInfo, BlobKey, str or unicode representation of BlobKey of
      blob to fetch data from.
    start_index: Start index of blob data to fetch.  May not be negative.
    end_index: End index (inclusive) of blob data to fetch.  Must be
      >= start_index.
    **options: Options for create_rpc().

  Returns:
    str containing partial data of blob.  If the indexes are legal but outside
    the boundaries of the blob, will return empty string.

  Raises:
    TypeError if start_index or end_index are not indexes.  Also when blob
      is not a string, BlobKey or BlobInfo.
    DataIndexOutOfRangeError when start_index < 0 or end_index < start_index.
    BlobFetchSizeTooLargeError when request blob fragment is larger than
      MAX_BLOB_FETCH_SIZE.
    BlobNotFoundError when blob does not exist.
  """
  fut = fetch_data_async(blob, start_index, end_index, **options)
  return fut.get_result()


Instruction:
Can you create a Python 3 function that
retrieves a BlobInfo entity by blob key.

Response:
def get(cls, blob_key, **ctx_options):
    """Retrieve a BlobInfo by key.

    Args:
      blob_key: A blob key.  This may be a str, unicode or BlobKey instance.
      **ctx_options: Context options for Model().get_by_id().

    Returns:
      A BlobInfo entity associated with the provided key,  If there was
      no such entity, returns None.
    """
    fut = cls.get_async(blob_key, **ctx_options)
    return fut.get_result()


Instruction:
Here you have a function in Python 3, explain what it does
def get_async(cls, blob_key, **ctx_options):
    if not isinstance(blob_key, (BlobKey, basestring)):
      raise TypeError('Expected blob key, got %r' % (blob_key,))
    if 'parent' in ctx_options:
      raise TypeError('Parent is not supported')
    return cls.get_by_id_async(str(blob_key), **ctx_options)

Response: Async version of get ().


Instruction:
Given the following Python 3 function, write the documentation
def get_multi_async(cls, blob_keys, **ctx_options):
    for blob_key in blob_keys:
      if not isinstance(blob_key, (BlobKey, basestring)):
        raise TypeError('Expected blob key, got %r' % (blob_key,))
    if 'parent' in ctx_options:
      raise TypeError('Parent is not supported')
    blob_key_strs = map(str, blob_keys)
    keys = [model.Key(BLOB_INFO_KIND, id) for id in blob_key_strs]
    return model.get_multi_async(keys, **ctx_options)

Response: Async version of get_multi.


Instruction:
Here you have a function in Python 3, explain what it does
def delete(self, **options):
    fut = delete_async(self.key(), **options)
    fut.get_result()

Response: Permanently delete this blob from Blobstore.


Instruction:
Write a Python 3 function that can
fill the internal buffer with the given size.

Response:
def __fill_buffer(self, size=0):
    """Fills the internal buffer.

    Args:
      size: Number of bytes to read. Will be clamped to
        [self.__buffer_size, MAX_BLOB_FETCH_SIZE].
    """
    read_size = min(max(size, self.__buffer_size), MAX_BLOB_FETCH_SIZE)

    self.__buffer = fetch_data(self.__blob_key, self.__position,
                               self.__position + read_size - 1)
    self.__buffer_position = 0
    self.__eof = len(self.__buffer) < read_size


Instruction:
Create a Python 3 function to
return the BlobInfo for this file.

Response:
def blob_info(self):
    """Returns the BlobInfo for this file."""
    if not self.__blob_info:
      self.__blob_info = BlobInfo.get(self.__blob_key)
    return self.__blob_info


Instruction:
Can you create a Python 3 function that
creates a new Connection object with the right adapter.

Response:
def make_connection(config=None, default_model=None,
                    _api_version=datastore_rpc._DATASTORE_V3,
                    _id_resolver=None):
  """Create a new Connection object with the right adapter.

  Optionally you can pass in a datastore_rpc.Configuration object.
  """
  return datastore_rpc.Connection(
      adapter=ModelAdapter(default_model, id_resolver=_id_resolver),
      config=config,
      _api_version=_api_version)


Instruction:
Given the following Python 3 function, write the documentation
def _unpack_user(v):
  uv = v.uservalue()
  email = unicode(uv.email().decode('utf-8'))
  auth_domain = unicode(uv.auth_domain().decode('utf-8'))
  obfuscated_gaiaid = uv.obfuscated_gaiaid().decode('utf-8')
  obfuscated_gaiaid = unicode(obfuscated_gaiaid)

  federated_identity = None
  if uv.has_federated_identity():
    federated_identity = unicode(
        uv.federated_identity().decode('utf-8'))

  value = users.User(email=email,
                     _auth_domain=auth_domain,
                     _user_id=obfuscated_gaiaid,
                     federated_identity=federated_identity)
  return value

Response: Internal helper to unpack a User value from a protocol buffer.


Instruction:
Here you have a function in Python 3, explain what it does
def _date_to_datetime(value):
  if not isinstance(value, datetime.date):
    raise TypeError('Cannot convert to datetime expected date value; '
                    'received %s' % value)
  return datetime.datetime(value.year, value.month, value.day)

Response: Convert a date object to a datetime object for Cloud Datastore storage.


Instruction:
Explain what the following Python 3 code does
def _time_to_datetime(value):
  if not isinstance(value, datetime.time):
    raise TypeError('Cannot convert to datetime expected time value; '
                    'received %s' % value)
  return datetime.datetime(1970, 1, 1,
                           value.hour, value.minute, value.second,
                           value.microsecond)

Response: Convert a time to a datetime for Cloud Datastore storage.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def transactional_tasklet(func, args, kwds, **options):
  from . import tasklets
  func = tasklets.tasklet(func)
  return transactional_async.wrapped_decorator(func, args, kwds, **options)

Response: A decorator that will be used to wrap a function in a tasklet.


Instruction:
Can you create a Python 3 function that
updates all descendants to a specified value.

Response:
def _set(self, value):
    """Updates all descendants to a specified value."""
    if self.__is_parent_node():
      for child in self.__sub_counters.itervalues():
        child._set(value)
    else:
      self.__counter = value


Instruction:
Explain what the following Python 3 code does
def _comparison(self, op, value):
    # NOTE: This is also used by query.gql().
    if not self._indexed:
      raise datastore_errors.BadFilterError(
          'Cannot query for unindexed property %s' % self._name)
    from .query import FilterNode  # Import late to avoid circular imports.
    if value is not None:
      value = self._do_validate(value)
      value = self._call_to_base_type(value)
      value = self._datastore_type(value)
    return FilterNode(self._name, op, value)

Response: Internal helper for comparison operators.


Instruction:
Can you write a function in Python 3 where it
calls all validations on the value.

Response:
def _do_validate(self, value):
    """Call all validations on the value.

    This calls the most derived _validate() method(s), then the custom
    validator function, and then checks the choices.  It returns the
    value, possibly modified in an idempotent way, or raises an
    exception.

    Note that this does not call all composable _validate() methods.
    It only calls _validate() methods up to but not including the
    first _to_base_type() method, when the MRO is traversed looking
    for _validate() and _to_base_type() methods.  (IOW if a class
    defines both _validate() and _to_base_type(), its _validate()
    is called and then the search is aborted.)

    Note that for a repeated Property this function should be called
    for each item in the list, not for the list as a whole.
    """
    if isinstance(value, _BaseValue):
      return value
    value = self._call_shallow_validation(value)
    if self._validator is not None:
      newvalue = self._validator(self, value)
      if newvalue is not None:
        value = newvalue
    if self._choices is not None:
      if value not in self._choices:
        raise datastore_errors.BadValueError(
            'Value %r for property %s is not an allowed choice' %
            (value, self._name))
    return value


Instruction:
Make a summary of the following Python 3 code
def _fix_up(self, cls, code_name):
    self._code_name = code_name
    if self._name is None:
      self._name = code_name

Response: Internal helper to tell the property its name and set the code_name.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _set_value(self, entity, value):
    if entity._projection:
      raise ReadonlyPropertyError(
          'You cannot set property values of a projection entity')
    if self._repeated:
      if not isinstance(value, (list, tuple, set, frozenset)):
        raise datastore_errors.BadValueError('Expected list or tuple, got %r' %
                                             (value,))
      value = [self._do_validate(v) for v in value]
    else:
      if value is not None:
        value = self._do_validate(value)
    self._store_value(entity, value)

Response: Internal helper to set a value in an entity for a Property.


Instruction:
Create a Python 3 function for
liking _get_base_value but always returns a list.

Response:
def _get_base_value_unwrapped_as_list(self, entity):
    """Like _get_base_value(), but always returns a list.

    Returns:
      A new list of unwrapped base values.  For an unrepeated
      property, if the value is missing or None, returns [None]; for a
      repeated property, if the original value is missing or None or
      empty, returns [].
    """
    wrapped = self._get_base_value(entity)
    if self._repeated:
      if wrapped is None:
        return []
      assert isinstance(wrapped, list)
      return [w.b_val for w in wrapped]
    else:
      if wrapped is None:
        return [None]
      assert isinstance(wrapped, _BaseValue)
      return [wrapped.b_val]


Instruction:
Can you write a function in Python 3 where it
calls _from_base_type() if necessary.

Response:
def _opt_call_from_base_type(self, value):
    """Call _from_base_type() if necessary.

    If the value is a _BaseValue instance, unwrap it and call all
    _from_base_type() methods.  Otherwise, return the value
    unchanged.
    """
    if isinstance(value, _BaseValue):
      value = self._call_from_base_type(value.b_val)
    return value


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _opt_call_to_base_type(self, value):
    if not isinstance(value, _BaseValue):
      value = _BaseValue(self._call_to_base_type(value))
    return value

Response: Optimize the value to be a _BaseValue instance if necessary.


Instruction:
Given the following Python 3 function, write the documentation
def _call_from_base_type(self, value):
    methods = self._find_methods('_from_base_type', reverse=True)
    call = self._apply_list(methods)
    return call(value)

Response: Call all _from_base_type() methods on the value.


Instruction:
Explain what the following Python 3 code does
def _call_to_base_type(self, value):
    methods = self._find_methods('_validate', '_to_base_type')
    call = self._apply_list(methods)
    return call(value)

Response: Call all _validate and _to_base_type methods on the value.


Instruction:
Implement a Python 3 function for
calling the _validate methods that can be called with the given value.

Response:
def _call_shallow_validation(self, value):
    """Call the initial set of _validate() methods.

    This is similar to _call_to_base_type() except it only calls
    those _validate() methods that can be called without needing to
    call _to_base_type().

    An example: suppose the class hierarchy is A -> B -> C ->
    Property, and suppose A defines _validate() only, but B and C
    define _validate() and _to_base_type().  The full list of
    methods called by _call_to_base_type() is::

      A._validate()
      B._validate()
      B._to_base_type()
      C._validate()
      C._to_base_type()

    This method will call A._validate() and B._validate() but not the
    others.
    """
    methods = []
    for method in self._find_methods('_validate', '_to_base_type'):
      if method.__name__ != '_validate':
        break
      methods.append(method)
    call = self._apply_list(methods)
    return call(value)


Instruction:
Given the following Python 3 function, write the documentation
def _find_methods(cls, *names, **kwds):
    reverse = kwds.pop('reverse', False)
    assert not kwds, repr(kwds)
    cache = cls.__dict__.get('_find_methods_cache')
    if cache:
      hit = cache.get(names)
      if hit is not None:
        return hit
    else:
      cls._find_methods_cache = cache = {}
    methods = []
    for c in cls.__mro__:
      for name in names:
        method = c.__dict__.get(name)
        if method is not None:
          methods.append(method)
    if reverse:
      methods.reverse()
    cache[names] = methods
    return methods

Response: Compute a list of composable methods.


Instruction:
Can you generate the documentation for the following Python 3 function
def _apply_list(self, methods):
    def call(value):
      for method in methods:
        newvalue = method(self, value)
        if newvalue is not None:
          value = newvalue
      return value
    return call

Response: Returns a single callable that applies a list of methods to a value.


Instruction:
Given the following Python 3 function, write the documentation
def _apply_to_values(self, entity, function):
    value = self._retrieve_value(entity, self._default)
    if self._repeated:
      if value is None:
        value = []
        self._store_value(entity, value)
      else:
        value[:] = map(function, value)
    else:
      if value is not None:
        newvalue = function(value)
        if newvalue is not None and newvalue is not value:
          self._store_value(entity, newvalue)
          value = newvalue
    return value

Response: Applies a function to the property value and returns the value or list of values.


Instruction:
Explain what the following Python 3 code does
def _get_value(self, entity):
    if entity._projection:
      if self._name not in entity._projection:
        raise UnprojectedPropertyError(
            'Property %s is not in the projection' % (self._name,))
    return self._get_user_value(entity)

Response: Internal helper to get the value for this Property from an entity.


Instruction:
Given the following Python 3 function, write the documentation
def _serialize(self, entity, pb, prefix='', parent_repeated=False,
                 projection=None):
    """Internal helper to serialize this property to a protocol buffer.

    Subclasses may override this method.

    Args:
      entity: The entity, a Model (subclass) instance.
      pb: The protocol buffer, an EntityProto instance.
      prefix: Optional name prefix used for StructuredProperty
        (if present, must end in '.').
      parent_repeated: True if the parent (or an earlier ancestor)
        is a repeated Property.
      projection: A list or tuple of strings representing the projection for
        the model instance, or None if the instance is not a projection.
    """
    values = self._get_base_value_unwrapped_as_list(entity)
    name = prefix + self._name
    if projection and name not in projection:
      return

    if self._indexed:
      create_prop = lambda: pb.add_property()
    else:
      create_prop = lambda: pb.add_raw_property()

    if self._repeated and not values and self._write_empty_list:
      # We want to write the empty list
      p = create_prop()
      p.set_name(name)
      p.set_multiple(False)
      p.set_meaning(entity_pb.Property.EMPTY_LIST)
      p.mutable_value()
    else:
      # We write a list, or a single property
      for val in values:
        p = create_prop()
        p.set_name(name)
        p.set_multiple(self._repeated or parent_repeated)
        v = p.mutable_value()
        if val is not None:
          self._db_set_value(v, p, val)
          if projection:
            # Projected properties have the INDEX_VALUE meaning and only contain
            # the original property's name and value.
            new_p = entity_pb.Property()
            new_p.set_name(p.name())
            new_p.set_meaning(entity_pb.Property.INDEX_VALUE)
            new_p.set_multiple(False)
            new_p.mutable_value().CopyFrom(v)
            p.CopyFrom(new_p)

Response: Internal helper to serialize this property to a protocol buffer.


Instruction:
Explain what the following Python 3 code does
def _deserialize(self, entity, p, unused_depth=1):
    if p.meaning() == entity_pb.Property.EMPTY_LIST:
      self._store_value(entity, [])
      return

    val = self._db_get_value(p.value(), p)
    if val is not None:
      val = _BaseValue(val)

    # TODO: replace the remainder of the function with the following commented
    # out code once its feasible to make breaking changes such as not calling
    # _store_value().

    # if self._repeated:
    #   entity._values.setdefault(self._name, []).append(val)
    # else:
    #   entity._values[self._name] = val

    if self._repeated:
      if self._has_value(entity):
        value = self._retrieve_value(entity)
        assert isinstance(value, list), repr(value)
        value.append(val)
      else:
        # We promote single values to lists if we are a list property
        value = [val]
    else:
      value = val
    self._store_value(entity, value)

Response: Internal helper to deserialize this property from a protocol buffer.


Instruction:
Make a summary of the following Python 3 code
def _check_property(self, rest=None, require_indexed=True):
    if require_indexed and not self._indexed:
      raise InvalidPropertyError('Property is unindexed %s' % self._name)
    if rest:
      raise InvalidPropertyError('Referencing subproperty %s.%s '
                                 'but %s is not a structured property' %
                                 (self._name, rest, self._name))

Response: Internal helper to check this property for specific requirements.


Instruction:
Can you tell what is the following Python 3 function doing
def _set_value(self, entity, value):
    if value is not None:
      value = _validate_key(value, entity=entity)
      value = entity._validate_key(value)
    entity._entity_key = value

Response: Setter for key attribute.


Instruction:
How would you code a function in Python 3 to
override _get_value to not raise UnprojectedPropertyError.

Response:
def _get_value(self, entity):
    """Override _get_value() to *not* raise UnprojectedPropertyError."""
    value = self._get_user_value(entity)
    if value is None and entity._projection:
      # Invoke super _get_value() to raise the proper exception.
      return super(StructuredProperty, self)._get_value(entity)
    return value


Instruction:
Can you generate the documentation for the following Python 3 function
def _check_property(self, rest=None, require_indexed=True):
    if not rest:
      raise InvalidPropertyError(
          'Structured property %s requires a subproperty' % self._name)
    self._modelclass._check_properties([rest], require_indexed=require_indexed)

Response: Override for Property. _check_property.


Instruction:
Make a summary of the following Python 3 code
def _check_initialized(self):
    baddies = self._find_uninitialized()
    if baddies:
      raise datastore_errors.BadValueError(
          'Entity has uninitialized properties: %s' % ', '.join(baddies))

Response: Internal helper to check for uninitialized properties. Raises a BadValueError if it finds any.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _reset_kind_map(cls):
    # Preserve "system" kinds, like __namespace__
    keep = {}
    for name, value in cls._kind_map.iteritems():
      if name.startswith('__') and name.endswith('__'):
        keep[name] = value
    cls._kind_map.clear()
    cls._kind_map.update(keep)

Response: Clear the kind map. Useful for testing.


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _lookup_model(cls, kind, default_model=None):
    modelclass = cls._kind_map.get(kind, default_model)
    if modelclass is None:
      raise KindError(
          "No model class found for kind '%s'. Did you forget to import it?" %
          kind)
    return modelclass

Response: Lookup the model class for the given kind.


Instruction:
Write a Python 3 script to
compare two entities of the same class excluding keys.

Response:
def _equivalent(self, other):
    """Compare two entities of the same class, excluding keys."""
    if other.__class__ is not self.__class__:  # TODO: What about subclasses?
      raise NotImplementedError('Cannot compare different model classes. '
                                '%s is not %s' % (self.__class__.__name__,
                                                  other.__class_.__name__))
    if set(self._projection) != set(other._projection):
      return False
    # It's all about determining inequality early.
    if len(self._properties) != len(other._properties):
      return False  # Can only happen for Expandos.
    my_prop_names = set(self._properties.iterkeys())
    their_prop_names = set(other._properties.iterkeys())
    if my_prop_names != their_prop_names:
      return False  # Again, only possible for Expandos.
    if self._projection:
      my_prop_names = set(self._projection)
    for name in my_prop_names:
      if '.' in name:
        name, _ = name.split('.', 1)
      my_value = self._properties[name]._get_value(self)
      their_value = other._properties[name]._get_value(other)
      if my_value != their_value:
        return False
    return True


Instruction:
Here you have a function in Python 3, explain what it does
def _to_pb(self, pb=None, allow_partial=False, set_key=True):
    if not allow_partial:
      self._check_initialized()
    if pb is None:
      pb = entity_pb.EntityProto()

    if set_key:
      # TODO: Move the key stuff into ModelAdapter.entity_to_pb()?
      self._key_to_pb(pb)

    for unused_name, prop in sorted(self._properties.iteritems()):
      prop._serialize(self, pb, projection=self._projection)

    return pb

Response: Internal helper to turn an entity into an EntityProto protobuf.


Instruction:
Explain what the following Python 3 code does
def _from_pb(cls, pb, set_key=True, ent=None, key=None):
    if not isinstance(pb, entity_pb.EntityProto):
      raise TypeError('pb must be a EntityProto; received %r' % pb)
    if ent is None:
      ent = cls()

    # A key passed in overrides a key in the pb.
    if key is None and pb.key().path().element_size():
      key = Key(reference=pb.key())
    # If set_key is not set, skip a trivial incomplete key.
    if key is not None and (set_key or key.id() or key.parent()):
      ent._key = key

    # NOTE(darke): Keep a map from (indexed, property name) to the property.
    # This allows us to skip the (relatively) expensive call to
    # _get_property_for for repeated fields.
    _property_map = {}
    projection = []
    for indexed, plist in ((True, pb.property_list()),
                           (False, pb.raw_property_list())):
      for p in plist:
        if p.meaning() == entity_pb.Property.INDEX_VALUE:
          projection.append(p.name())
        property_map_key = (p.name(), indexed)
        if property_map_key not in _property_map:
          _property_map[property_map_key] = ent._get_property_for(p, indexed)
        _property_map[property_map_key]._deserialize(ent, p)

    ent._set_projection(projection)
    return ent

Response: Internal helper to create an entity from an EntityProto protobuf.


Instruction:
Given the following Python 3 function, write the documentation
def _get_property_for(self, p, indexed=True, depth=0):
    parts = p.name().split('.')
    if len(parts) <= depth:
      # Apparently there's an unstructured value here.
      # Assume it is a None written for a missing value.
      # (It could also be that a schema change turned an unstructured
      # value into a structured one.  In that case, too, it seems
      # better to return None than to return an unstructured value,
      # since the latter doesn't match the current schema.)
      return None
    next = parts[depth]
    prop = self._properties.get(next)
    if prop is None:
      prop = self._fake_property(p, next, indexed)
    return prop

Response: Internal helper to get the Property for a protobuf - level property.


Instruction:
Can you tell what is the following Python 3 function doing
def _clone_properties(self):
    cls = self.__class__
    if self._properties is cls._properties:
      self._properties = dict(cls._properties)

Response: Internal helper to clone self. _properties.


Instruction:
Can you tell what is the following Python 3 function doing
def _fake_property(self, p, next, indexed=True):
    self._clone_properties()
    if p.name() != next and not p.name().endswith('.' + next):
      prop = StructuredProperty(Expando, next)
      prop._store_value(self, _BaseValue(Expando()))
    else:
      compressed = p.meaning_uri() == _MEANING_URI_COMPRESSED
      prop = GenericProperty(next,
                             repeated=p.multiple(),
                             indexed=indexed,
                             compressed=compressed)
    prop._code_name = next
    self._properties[prop._name] = prop
    return prop

Response: Internal helper to create a fake Property.


Instruction:
Write a Python 3 script to
return a dict containing the entity s property values.

Response:
def _to_dict(self, include=None, exclude=None):
    """Return a dict containing the entity's property values.

    Args:
      include: Optional set of property names to include, default all.
      exclude: Optional set of property names to skip, default none.
        A name contained in both include and exclude is excluded.
    """
    if (include is not None and
        not isinstance(include, (list, tuple, set, frozenset))):
      raise TypeError('include should be a list, tuple or set')
    if (exclude is not None and
        not isinstance(exclude, (list, tuple, set, frozenset))):
      raise TypeError('exclude should be a list, tuple or set')
    values = {}
    for prop in self._properties.itervalues():
      name = prop._code_name
      if include is not None and name not in include:
        continue
      if exclude is not None and name in exclude:
        continue
      try:
        values[name] = prop._get_for_dict(self)
      except UnprojectedPropertyError:
        pass  # Ignore unprojected properties rather than failing.
    return values


Instruction:
Create a Python 3 function for
fixing up the properties of a given class by calling their _fix_up method.

Response:
def _fix_up_properties(cls):
    """Fix up the properties by calling their _fix_up() method.

    Note: This is called by MetaModel, but may also be called manually
    after dynamically updating a model class.
    """
    # Verify that _get_kind() returns an 8-bit string.
    kind = cls._get_kind()
    if not isinstance(kind, basestring):
      raise KindError('Class %s defines a _get_kind() method that returns '
                      'a non-string (%r)' % (cls.__name__, kind))
    if not isinstance(kind, str):
      try:
        kind = kind.encode('ascii')  # ASCII contents is okay.
      except UnicodeEncodeError:
        raise KindError('Class %s defines a _get_kind() method that returns '
                        'a Unicode string (%r); please encode using utf-8' %
                        (cls.__name__, kind))
    cls._properties = {}  # Map of {name: Property}
    if cls.__module__ == __name__:  # Skip the classes in *this* file.
      return
    for name in set(dir(cls)):
      attr = getattr(cls, name, None)
      if isinstance(attr, ModelAttribute) and not isinstance(attr, ModelKey):
        if name.startswith('_'):
          raise TypeError('ModelAttribute %s cannot begin with an underscore '
                          'character. _ prefixed attributes are reserved for '
                          'temporary Model instance values.' % name)
        attr._fix_up(cls, name)
        if isinstance(attr, Property):
          if (attr._repeated or
              (isinstance(attr, StructuredProperty) and
               attr._modelclass._has_repeated)):
            cls._has_repeated = True
          cls._properties[attr._name] = attr
    cls._update_kind_map()


Instruction:
Write a Python 3 script to
create a Query object for this class.

Response:
def _query(cls, *args, **kwds):
    """Create a Query object for this class.

    Args:
      distinct: Optional bool, short hand for group_by = projection.
      *args: Used to apply an initial filter
      **kwds: are passed to the Query() constructor.

    Returns:
      A Query object.
    """
    # Validating distinct.
    if 'distinct' in kwds:
      if 'group_by' in kwds:
        raise TypeError(
            'cannot use distinct= and group_by= at the same time')
      projection = kwds.get('projection')
      if not projection:
        raise TypeError(
            'cannot use distinct= without projection=')
      if kwds.pop('distinct'):
        kwds['group_by'] = projection

    # TODO: Disallow non-empty args and filter=.
    from .query import Query  # Import late to avoid circular imports.
    qry = Query(kind=cls._get_kind(), **kwds)
    qry = qry.filter(*cls._default_filters())
    qry = qry.filter(*args)
    return qry


Instruction:
Implement a Python 3 function for
running a GQL query.

Response:
def _gql(cls, query_string, *args, **kwds):
    """Run a GQL query."""
    from .query import gql  # Import late to avoid circular imports.
    return gql('SELECT * FROM %s %s' % (cls._class_name(), query_string),
               *args, **kwds)


Instruction:
Can you implement a function in Python 3 that
writes this entity to Cloud Datastore.

Response:
def _put_async(self, **ctx_options):
    """Write this entity to Cloud Datastore.

    This is the asynchronous version of Model._put().
    """
    if self._projection:
      raise datastore_errors.BadRequestError('Cannot put a partial entity')
    from . import tasklets
    ctx = tasklets.get_context()
    self._prepare_for_put()
    if self._key is None:
      self._key = Key(self._get_kind(), None)
    self._pre_put_hook()
    fut = ctx.put(self, **ctx_options)
    post_hook = self._post_put_hook
    if not self._is_default_hook(Model._default_post_put_hook, post_hook):
      fut.add_immediate_callback(post_hook, fut)
    return fut


Instruction:
How would you explain what the following Python 3 function does
def _allocate_ids(cls, size=None, max=None, parent=None, **ctx_options):
    return cls._allocate_ids_async(size=size, max=max, parent=parent,
                                   **ctx_options).get_result()

Response: Allocates a range of key IDs for this model class.


Instruction:
Create a Python 3 function for
allocating a range of key IDs for this model class.

Response:
def _allocate_ids_async(cls, size=None, max=None, parent=None,
                          **ctx_options):
    """Allocates a range of key IDs for this model class.

    This is the asynchronous version of Model._allocate_ids().
    """
    from . import tasklets
    ctx = tasklets.get_context()
    cls._pre_allocate_ids_hook(size, max, parent)
    key = Key(cls._get_kind(), None, parent=parent)
    fut = ctx.allocate_ids(key, size=size, max=max, **ctx_options)
    post_hook = cls._post_allocate_ids_hook
    if not cls._is_default_hook(Model._default_post_allocate_ids_hook,
                                post_hook):
      fut.add_immediate_callback(post_hook, size, max, parent, fut)
    return fut


Instruction:
Explain what the following Python 3 code does
def _get_by_id(cls, id, parent=None, **ctx_options):
    return cls._get_by_id_async(id, parent=parent, **ctx_options).get_result()

Response: Returns an instance of Model class by ID.


Instruction:
Write a Python 3 function that can
return an instance of Model class by ID.

Response:
def _get_by_id_async(cls, id, parent=None, app=None, namespace=None,
                       **ctx_options):
    """Returns an instance of Model class by ID (and app, namespace).

    This is the asynchronous version of Model._get_by_id().
    """
    key = Key(cls._get_kind(), id, parent=parent, app=app, namespace=namespace)
    return key.get_async(**ctx_options)


Instruction:
Can you generate a brief explanation for the following Python 3 code
def _is_default_hook(default_hook, hook):
    if not hasattr(default_hook, '__call__'):
      raise TypeError('Default hooks for ndb.model.Model must be callable')
    if not hasattr(hook, '__call__'):
      raise TypeError('Hooks must be callable')
    return default_hook.im_func is hook.im_func

Response: Checks whether a specific hook is in its default state.


Instruction:
Create a Python 3 function for
constructing a Reference from a list of pairs.

Response:
def _ConstructReference(cls, pairs=None, flat=None,
                        reference=None, serialized=None, urlsafe=None,
                        app=None, namespace=None, parent=None):
  """Construct a Reference; the signature is the same as for Key."""
  if cls is not Key:
    raise TypeError('Cannot construct Key reference on non-Key class; '
                    'received %r' % cls)
  if (bool(pairs) + bool(flat) + bool(reference) + bool(serialized) +
      bool(urlsafe)) != 1:
    raise TypeError('Cannot construct Key reference from incompatible keyword '
                    'arguments.')
  if flat or pairs:
    if flat:
      if len(flat) % 2:
        raise TypeError('_ConstructReference() must have an even number of '
                        'positional arguments.')
      pairs = [(flat[i], flat[i + 1]) for i in xrange(0, len(flat), 2)]
    elif parent is not None:
      pairs = list(pairs)
    if not pairs:
      raise TypeError('Key references must consist of at least one pair.')
    if parent is not None:
      if not isinstance(parent, Key):
        raise datastore_errors.BadValueError(
            'Expected Key instance, got %r' % parent)
      pairs[:0] = parent.pairs()
      if app:
        if app != parent.app():
          raise ValueError('Cannot specify a different app %r '
                           'than the parent app %r' %
                           (app, parent.app()))
      else:
        app = parent.app()
      if namespace is not None:
        if namespace != parent.namespace():
          raise ValueError('Cannot specify a different namespace %r '
                           'than the parent namespace %r' %
                           (namespace, parent.namespace()))
      else:
        namespace = parent.namespace()
    reference = _ReferenceFromPairs(pairs, app=app, namespace=namespace)
  else:
    if parent is not None:
      raise TypeError('Key reference cannot be constructed when the parent '
                      'argument is combined with either reference, serialized '
                      'or urlsafe arguments.')
    if urlsafe:
      serialized = _DecodeUrlSafe(urlsafe)
    if serialized:
      reference = _ReferenceFromSerialized(serialized)
    if not reference.path().element_size():
      raise RuntimeError('Key reference has no path or elements (%r, %r, %r).'
                         % (urlsafe, serialized, str(reference)))
    # TODO: ensure that each element has a type and either an id or a name
    if not serialized:
      reference = _ReferenceFromReference(reference)
    # You needn't specify app= or namespace= together with reference=,
    # serialized= or urlsafe=, but if you do, their values must match
    # what is already in the reference.
    if app is not None:
      ref_app = reference.app()
      if app != ref_app:
        raise RuntimeError('Key reference constructed uses a different app %r '
                           'than the one specified %r' %
                           (ref_app, app))
    if namespace is not None:
      ref_namespace = reference.name_space()
      if namespace != ref_namespace:
        raise RuntimeError('Key reference constructed uses a different '
                           'namespace %r than the one specified %r' %
                           (ref_namespace, namespace))
  return reference


Instruction:
Can you tell what is the following Python 3 function doing
def _ReferenceFromPairs(pairs, reference=None, app=None, namespace=None):
  if reference is None:
    reference = entity_pb.Reference()
  path = reference.mutable_path()
  last = False
  for kind, idorname in pairs:
    if last:
      raise datastore_errors.BadArgumentError(
          'Incomplete Key entry must be last')
    t = type(kind)
    if t is str:
      pass
    elif t is unicode:
      kind = kind.encode('utf8')
    else:
      if issubclass(t, type):
        # Late import to avoid cycles.
        from .model import Model
        modelclass = kind
        if not issubclass(modelclass, Model):
          raise TypeError('Key kind must be either a string or subclass of '
                          'Model; received %r' % modelclass)
        kind = modelclass._get_kind()
        t = type(kind)
      if t is str:
        pass
      elif t is unicode:
        kind = kind.encode('utf8')
      elif issubclass(t, str):
        pass
      elif issubclass(t, unicode):
        kind = kind.encode('utf8')
      else:
        raise TypeError('Key kind must be either a string or subclass of Model;'
                        ' received %r' % kind)
    # pylint: disable=superfluous-parens
    if not (1 <= len(kind) <= _MAX_KEYPART_BYTES):
      raise ValueError('Key kind string must be a non-empty string up to %i'
                       'bytes; received %s' %
                       (_MAX_KEYPART_BYTES, kind))
    elem = path.add_element()
    elem.set_type(kind)
    t = type(idorname)
    if t is int or t is long:
      # pylint: disable=superfluous-parens
      if not (1 <= idorname < _MAX_LONG):
        raise ValueError('Key id number is too long; received %i' % idorname)
      elem.set_id(idorname)
    elif t is str:
      # pylint: disable=superfluous-parens
      if not (1 <= len(idorname) <= _MAX_KEYPART_BYTES):
        raise ValueError('Key name strings must be non-empty strings up to %i '
                         'bytes; received %s' %
                         (_MAX_KEYPART_BYTES, idorname))
      elem.set_name(idorname)
    elif t is unicode:
      idorname = idorname.encode('utf8')
      # pylint: disable=superfluous-parens
      if not (1 <= len(idorname) <= _MAX_KEYPART_BYTES):
        raise ValueError('Key name unicode strings must be non-empty strings up'
                         ' to %i bytes; received %s' %
                         (_MAX_KEYPART_BYTES, idorname))
      elem.set_name(idorname)
    elif idorname is None:
      last = True
    elif issubclass(t, (int, long)):
      # pylint: disable=superfluous-parens
      if not (1 <= idorname < _MAX_LONG):
        raise ValueError('Key id number is too long; received %i' % idorname)
      elem.set_id(idorname)
    elif issubclass(t, basestring):
      if issubclass(t, unicode):
        idorname = idorname.encode('utf8')
      # pylint: disable=superfluous-parens
      if not (1 <= len(idorname) <= _MAX_KEYPART_BYTES):
        raise ValueError('Key name strings must be non-empty strings up to %i '
                         'bytes; received %s' % (_MAX_KEYPART_BYTES, idorname))
      elem.set_name(idorname)
    else:
      raise TypeError('id must be either a numeric id or a string name; '
                      'received %r' % idorname)
  # An empty app id means to use the default app id.
  if not app:
    app = _DefaultAppId()
  # Always set the app id, since it is mandatory.
  reference.set_app(app)
  # An empty namespace overrides the default namespace.
  if namespace is None:
    namespace = _DefaultNamespace()
  # Only set the namespace if it is not empty.
  if namespace:
    reference.set_name_space(namespace)
  return reference

Response: Construct a Reference from a list of pairs.


Instruction:
Given the following Python 3 function, write the documentation
def _ReferenceFromSerialized(serialized):
  if not isinstance(serialized, basestring):
    raise TypeError('serialized must be a string; received %r' % serialized)
  elif isinstance(serialized, unicode):
    serialized = serialized.encode('utf8')
  return entity_pb.Reference(serialized)

Response: Construct a Reference from a serialized Reference.


Instruction:
Write a Python 3 function for
decoding a url - safe base64 - encoded string.

Response:
def _DecodeUrlSafe(urlsafe):
  """Decode a url-safe base64-encoded string.

  This returns the decoded string.
  """
  if not isinstance(urlsafe, basestring):
    raise TypeError('urlsafe must be a string; received %r' % urlsafe)
  if isinstance(urlsafe, unicode):
    urlsafe = urlsafe.encode('utf8')
  mod = len(urlsafe) % 4
  if mod:
    urlsafe += '=' * (4 - mod)
  # This is 3-4x faster than urlsafe_b64decode()
  return base64.b64decode(urlsafe.replace('-', '+').replace('_', '/'))


Instruction:
Make a summary of the following Python 3 code
def _parse_from_ref(cls, pairs=None, flat=None,
                      reference=None, serialized=None, urlsafe=None,
                      app=None, namespace=None, parent=None):
    """Construct a Reference; the signature is the same as for Key."""
    if cls is not Key:
      raise TypeError('Cannot construct Key reference on non-Key class; '
                      'received %r' % cls)
    if (bool(pairs) + bool(flat) + bool(reference) + bool(serialized) +
        bool(urlsafe) + bool(parent)) != 1:
      raise TypeError('Cannot construct Key reference from incompatible '
                      'keyword arguments.')
    if urlsafe:
      serialized = _DecodeUrlSafe(urlsafe)
    if serialized:
      reference = _ReferenceFromSerialized(serialized)
    if reference:
      reference = _ReferenceFromReference(reference)
    pairs = []
    elem = None
    path = reference.path()
    for elem in path.element_list():
      kind = elem.type()
      if elem.has_id():
        id_or_name = elem.id()
      else:
        id_or_name = elem.name()
      if not id_or_name:
        id_or_name = None
      tup = (kind, id_or_name)
      pairs.append(tup)
    if elem is None:
      raise RuntimeError('Key reference has no path or elements (%r, %r, %r).'
                         % (urlsafe, serialized, str(reference)))
    # TODO: ensure that each element has a type and either an id or a name
    # You needn't specify app= or namespace= together with reference=,
    # serialized= or urlsafe=, but if you do, their values must match
    # what is already in the reference.
    ref_app = reference.app()
    if app is not None:
      if app != ref_app:
        raise RuntimeError('Key reference constructed uses a different app %r '
                           'than the one specified %r' %
                           (ref_app, app))
    ref_namespace = reference.name_space()
    if namespace is not None:
      if namespace != ref_namespace:
        raise RuntimeError('Key reference constructed uses a different '
                           'namespace %r than the one specified %r' %
                           (ref_namespace, namespace))
    return (reference, tuple(pairs), ref_app, ref_namespace)

Response: Construct a Key reference from a reference.


Instruction:
How would you explain what the following Python 3 function does
def parent(self):
    pairs = self.__pairs
    if len(pairs) <= 1:
      return None
    return Key(pairs=pairs[:-1], app=self.__app, namespace=self.__namespace)

Response: Return a Key constructed from all but the last pair.


Instruction:
How would you explain what the following Python 3 function does
def string_id(self):
    id = self.id()
    if not isinstance(id, basestring):
      id = None
    return id

Response: Return the string id in the last pair of kind and id.


Instruction:
Given the following Python 3 function, write the documentation
def integer_id(self):
    id = self.id()
    if not isinstance(id, (int, long)):
      id = None
    return id

Response: Return the integer id in the last kind id pair.


Instruction:
Write a Python 3 script to
return a tuple of alternating kind and id values.

Response:
def flat(self):
    """Return a tuple of alternating kind and id values."""
    flat = []
    for kind, id in self.__pairs:
      flat.append(kind)
      flat.append(id)
    return tuple(flat)


Instruction:
Explain what the following Python 3 code does
def reference(self):
    if self.__reference is None:
      self.__reference = _ConstructReference(self.__class__,
                                             pairs=self.__pairs,
                                             app=self.__app,
                                             namespace=self.__namespace)
    return self.__reference

Response: Return the Reference object for this Key.


Instruction:
Given the following Python 3 function, write the documentation
def urlsafe(self):
    # This is 3-4x faster than urlsafe_b64decode()
    urlsafe = base64.b64encode(self.reference().Encode())
    return urlsafe.rstrip('=').replace('+', '-').replace('/', '_')

Response: Return a url - safe string encoding this Key s Reference.


Instruction:
Create a Python 3 function to
return a Future whose result is the entity for this Key.

Response:
def get_async(self, **ctx_options):
    """Return a Future whose result is the entity for this Key.

    If no such entity exists, a Future is still returned, and the
    Future's eventual return result be None.
    """
    from . import model, tasklets
    ctx = tasklets.get_context()
    cls = model.Model._kind_map.get(self.kind())
    if cls:
      cls._pre_get_hook(self)
    fut = ctx.get(self, **ctx_options)
    if cls:
      post_hook = cls._post_get_hook
      if not cls._is_default_hook(model.Model._default_post_get_hook,
                                  post_hook):
        fut.add_immediate_callback(post_hook, self, fut)
    return fut


Instruction:
Write a Python 3 function that can
schedule deletion of the entity for this Key.

Response:
def delete_async(self, **ctx_options):
    """Schedule deletion of the entity for this Key.

    This returns a Future, whose result becomes available once the
    deletion is complete.  If no such entity exists, a Future is still
    returned.  In all cases the Future's result is None (i.e. there is
    no way to tell whether the entity existed or not).
    """
    from . import tasklets, model
    ctx = tasklets.get_context()
    cls = model.Model._kind_map.get(self.kind())
    if cls:
      cls._pre_delete_hook(self)
    fut = ctx.delete(self, **ctx_options)
    if cls:
      post_hook = cls._post_delete_hook
      if not cls._is_default_hook(model.Model._default_post_delete_hook,
                                  post_hook):
        fut.add_immediate_callback(post_hook, self, fut)
    return fut


Instruction:
How would you explain what the following Python 3 function does
def add_flow_exception(exc):
  global _flow_exceptions
  if not isinstance(exc, type) or not issubclass(exc, Exception):
    raise TypeError('Expected an Exception subclass, got %r' % (exc,))
  as_set = set(_flow_exceptions)
  as_set.add(exc)
  _flow_exceptions = tuple(as_set)

Response: Add an exception that should not be logged.


Instruction:
How would you explain what the following Python 3 function does
def _init_flow_exceptions():
  global _flow_exceptions
  _flow_exceptions = ()
  add_flow_exception(datastore_errors.Rollback)
  try:
    from webob import exc
  except ImportError:
    pass
  else:
    add_flow_exception(exc.HTTPException)

Response: Internal helper to initialize _flow_exceptions.


Instruction:
Explain what the following Python 3 code does
def synctasklet(func):
  taskletfunc = tasklet(func)  # wrap at declaration time.

  @utils.wrapping(func)
  def synctasklet_wrapper(*args, **kwds):
    # pylint: disable=invalid-name
    __ndb_debug__ = utils.func_info(func)
    return taskletfunc(*args, **kwds).get_result()
  return synctasklet_wrapper

Response: Decorator to run a function as a tasklet when called.


Instruction:
Implement a function in Python 3 to
create a new context that can connect to a Remote Cloud Datastore instance.

Response:
def _make_cloud_datastore_context(app_id, external_app_ids=()):
  """Creates a new context to connect to a remote Cloud Datastore instance.

  This should only be used outside of Google App Engine.

  Args:
    app_id: The application id to connect to. This differs from the project
      id as it may have an additional prefix, e.g. "s~" or "e~".
    external_app_ids: A list of apps that may be referenced by data in your
      application. For example, if you are connected to s~my-app and store keys
      for s~my-other-app, you should include s~my-other-app in the external_apps
      list.
  Returns:
    An ndb.Context that can connect to a Remote Cloud Datastore. You can use
    this context by passing it to ndb.set_context.
  """
  from . import model  # Late import to deal with circular imports.
  # Late import since it might not exist.
  if not datastore_pbs._CLOUD_DATASTORE_ENABLED:
    raise datastore_errors.BadArgumentError(
        datastore_pbs.MISSING_CLOUD_DATASTORE_MESSAGE)
  import googledatastore
  try:
    from google.appengine.datastore import cloud_datastore_v1_remote_stub
  except ImportError:
    from google3.apphosting.datastore import cloud_datastore_v1_remote_stub

  current_app_id = os.environ.get('APPLICATION_ID', None)
  if current_app_id and current_app_id != app_id:
    # TODO(pcostello): We should support this so users can connect to different
    # applications.
    raise ValueError('Cannot create a Cloud Datastore context that connects '
                     'to an application (%s) that differs from the application '
                     'already connected to (%s).' % (app_id, current_app_id))
  os.environ['APPLICATION_ID'] = app_id

  id_resolver = datastore_pbs.IdResolver((app_id,) + tuple(external_app_ids))
  project_id = id_resolver.resolve_project_id(app_id)
  endpoint = googledatastore.helper.get_project_endpoint_from_env(project_id)
  datastore = googledatastore.Datastore(
      project_endpoint=endpoint,
      credentials=googledatastore.helper.get_credentials_from_env())

  conn = model.make_connection(_api_version=datastore_rpc._CLOUD_DATASTORE_V1,
                               _id_resolver=id_resolver)

  # If necessary, install the stubs
  try:
    stub = cloud_datastore_v1_remote_stub.CloudDatastoreV1RemoteStub(datastore)
    apiproxy_stub_map.apiproxy.RegisterStub(datastore_rpc._CLOUD_DATASTORE_V1,
                                            stub)
  except:
    pass  # The stub is already installed.
  # TODO(pcostello): Ensure the current stub is connected to the right project.

  # Install a memcache and taskqueue stub which throws on everything.
  try:
    apiproxy_stub_map.apiproxy.RegisterStub('memcache', _ThrowingStub())
  except:
    pass  # The stub is already installed.
  try:
    apiproxy_stub_map.apiproxy.RegisterStub('taskqueue', _ThrowingStub())
  except:
    pass  # The stub is already installed.

  return make_context(conn=conn)


Instruction:
Can you generate the documentation for the following Python 3 function
def _analyze_indexed_fields(indexed_fields):
  result = {}
  for field_name in indexed_fields:
    if not isinstance(field_name, basestring):
      raise TypeError('Field names must be strings; got %r' % (field_name,))
    if '.' not in field_name:
      if field_name in result:
        raise ValueError('Duplicate field name %s' % field_name)
      result[field_name] = None
    else:
      head, tail = field_name.split('.', 1)
      if head not in result:
        result[head] = [tail]
      elif result[head] is None:
        raise ValueError('Field name %s conflicts with ancestor %s' %
                         (field_name, head))
      else:
        result[head].append(tail)
  return result

Response: Internal helper to check a list of indexed fields.


Instruction:
Can you generate the documentation for the following Python 3 function
def _make_model_class(message_type, indexed_fields, **props):
  analyzed = _analyze_indexed_fields(indexed_fields)
  for field_name, sub_fields in analyzed.iteritems():
    if field_name in props:
      raise ValueError('field name %s is reserved' % field_name)
    try:
      field = message_type.field_by_name(field_name)
    except KeyError:
      raise ValueError('Message type %s has no field named %s' %
                       (message_type.__name__, field_name))
    if isinstance(field, messages.MessageField):
      if not sub_fields:
        raise ValueError(
            'MessageField %s cannot be indexed, only sub-fields' % field_name)
      sub_model_class = _make_model_class(field.type, sub_fields)
      prop = model.StructuredProperty(sub_model_class, field_name,
                                      repeated=field.repeated)
    else:
      if sub_fields is not None:
        raise ValueError(
            'Unstructured field %s cannot have indexed sub-fields' % field_name)
      if isinstance(field, messages.EnumField):
        prop = EnumProperty(field.type, field_name, repeated=field.repeated)
      elif isinstance(field, messages.BytesField):
        prop = model.BlobProperty(field_name,
                                  repeated=field.repeated, indexed=True)
      else:
        # IntegerField, FloatField, BooleanField, StringField.
        prop = model.GenericProperty(field_name, repeated=field.repeated)
    props[field_name] = prop
  return model.MetaModel('_%s__Model' % message_type.__name__,
                         (model.Model,), props)

Response: Construct a Model subclass corresponding to a Message subclass.


Instruction:
Here you have a function in Python 3, explain what it does
def _projected_entity_to_message(ent, message_type):
  msg = message_type()
  analyzed = _analyze_indexed_fields(ent._projection)
  for name, sublist in analyzed.iteritems():
    prop = ent._properties[name]
    val = prop._get_value(ent)
    assert isinstance(prop, model.StructuredProperty) == bool(sublist)
    if sublist:
      field = message_type.field_by_name(name)
      assert isinstance(field, messages.MessageField)
      assert prop._repeated == field.repeated
      if prop._repeated:
        assert isinstance(val, list)
        val = [_projected_entity_to_message(v, field.type) for v in val]
      else:
        assert isinstance(val, prop._modelclass)
        val = _projected_entity_to_message(val, field.type)
    setattr(msg, name, val)
  return msg

Response: Recursive helper for _from_base_type() to convert an entity to a message.


Instruction:
Explain what the following Python 3 code does
def _validate(self, value):
    if not isinstance(value, self._enum_type):
      raise TypeError('Expected a %s instance, got %r instead' %
                      (self._enum_type.__name__, value))

Response: Validate an Enum value.


Instruction:
Implement a Python 3 function for
validating an Enum value.

Response:
def _validate(self, msg):
    """Validate an Enum value.

    Raises:
      TypeError if the value is not an instance of self._message_type.
    """
    if not isinstance(msg, self._message_type):
      raise TypeError('Expected a %s instance for %s property',
                      self._message_type.__name__,
                      self._code_name or self._name)


Instruction:
Can you generate the documentation for the following Python 3 function
def _to_base_type(self, msg):
    ent = _message_to_entity(msg, self._modelclass)
    ent.blob_ = self._protocol_impl.encode_message(msg)
    return ent

Response: Convert a Message value to a Model instance.


Instruction:
Implement a function in Python 3 to
convert a Model instance to a Message value.

Response:
def _from_base_type(self, ent):
    """Convert a Model instance (entity) to a Message value."""
    if ent._projection:
      # Projection query result.  Reconstitute the message from the fields.
      return _projected_entity_to_message(ent, self._message_type)

    blob = ent.blob_
    if blob is not None:
      protocol = self._protocol_impl
    else:
      # Perhaps it was written using a different protocol.
      protocol = None
      for name in _protocols_registry.names:
        key = '__%s__' % name
        if key in ent._values:
          blob = ent._values[key]
          if isinstance(blob, model._BaseValue):
            blob = blob.b_val
          protocol = _protocols_registry.lookup_by_name(name)
          break
    if blob is None or protocol is None:
      return None  # This will reveal the underlying dummy model.
    msg = protocol.decode_message(self._message_type, blob)
    return msg


Instruction:
Given the following Python 3 function, write the documentation
def _get_value(self, entity):
    value = super(_ClassKeyProperty, self)._get_value(entity)
    if not value:
      value = entity._class_key()
      self._store_value(entity, value)
    return value

Response: Compute and store a default value if necessary.


Instruction:
Can you implement a function in Python 3 that
overrides ; called by Model. _fix_up_properties.

Response:
def _update_kind_map(cls):
    """Override; called by Model._fix_up_properties().

    Update the kind map as well as the class map, except for PolyModel
    itself (its class key is empty).  Note that the kind map will
    contain entries for all classes in a PolyModel hierarchy; they all
    have the same kind, but different class names.  PolyModel class
    names, like regular Model class names, must be globally unique.
    """
    cls._kind_map[cls._class_name()] = cls
    class_key = cls._class_key()
    if class_key:
      cls._class_map[tuple(class_key)] = cls


Instruction:
Here you have a function in Python 3, explain what it does
def _from_pb(cls, pb, set_key=True, ent=None, key=None):
    prop_name = cls.class_._name
    class_name = []
    for plist in [pb.property_list(), pb.raw_property_list()]:
      for p in plist:
        if p.name() == prop_name:
          class_name.append(p.value().stringvalue())
    cls = cls._class_map.get(tuple(class_name), cls)
    return super(PolyModel, cls)._from_pb(pb, set_key, ent, key)

Response: Override. _from_pb Use the class map to give the correct subclass of cls.


Instruction:
Write a Python 3 script to
override Make sure that the kind returned is the root class of the the polymorphic hierarchy.

Response:
def _get_kind(cls):
    """Override.

    Make sure that the kind returned is the root class of the
    polymorphic hierarchy.
    """
    bases = cls._get_hierarchy()
    if not bases:
      # We have to jump through some hoops to call the superclass'
      # _get_kind() method.  First, this is called by the metaclass
      # before the PolyModel name is defined, so it can't use
      # super(PolyModel, cls)._get_kind().  Second, we can't just call
      # Model._get_kind() because that always returns 'Model'.  Hence
      # the 'im_func' hack.
      return model.Model._get_kind.im_func(cls)
    else:
      return bases[0]._class_name()


Instruction:
Can you implement a function in Python 3 that
returns all potential kernels in a base_dirs

Response:
def find_env_paths_in_basedirs(base_dirs):
    """Returns all potential envs in a basedir"""
    # get potential env path in the base_dirs
    env_path = []
    for base_dir in base_dirs:
        env_path.extend(glob.glob(os.path.join(
            os.path.expanduser(base_dir), '*', '')))
    # self.log.info("Found the following kernels from config: %s", ", ".join(venvs))

    return env_path


Instruction:
Create a Python 3 function for
converting a list of paths to environments to env_data.

Response:
def convert_to_env_data(mgr, env_paths, validator_func, activate_func,
                        name_template, display_name_template, name_prefix):
    """Converts a list of paths to environments to env_data.

    env_data is a structure {name -> (ressourcedir, kernel spec)}
    """
    env_data = {}
    for venv_dir in env_paths:
        venv_name = os.path.split(os.path.abspath(venv_dir))[1]
        kernel_name = name_template.format(name_prefix + venv_name)
        kernel_name = kernel_name.lower()
        if kernel_name in env_data:
            mgr.log.debug(
                "Found duplicate env kernel: %s, which would again point to %s. Using the first!",
                kernel_name, venv_dir)
            continue
        argv, language, resource_dir = validator_func(venv_dir)
        if not argv:
            # probably does not contain the kernel type (e.g. not R or python or does not contain
            # the kernel code itself)
            continue
        display_name = display_name_template.format(kernel_name)
        kspec_dict = {"argv": argv, "language": language,
                      "display_name": display_name,
                      "resource_dir": resource_dir
                      }

        # the default vars are needed to save the vars in the function context
        def loader(env_dir=venv_dir, activate_func=activate_func, mgr=mgr):
            mgr.log.debug("Loading env data for %s" % env_dir)
            res = activate_func(mgr, env_dir)
            # mgr.log.info("PATH: %s" % res['PATH'])
            return res

        kspec = EnvironmentLoadingKernelSpec(loader, **kspec_dict)
        env_data.update({kernel_name: (resource_dir, kspec)})
    return env_data