App Engine Python SDK  v1.6.9 rev.445
The Python runtime is available as an experimental Preview feature.
Public Member Functions | List of all members
google.appengine.ext.ndb.key.Key Class Reference
Inheritance diagram for google.appengine.ext.ndb.key.Key:

Public Member Functions

def __new__
 
def __repr__
 
def __hash__
 
def __eq__
 
def __ne__
 
def __lt__
 
def __le__
 
def __gt__
 
def __ge__
 
def __getstate__
 
def __setstate__
 
def __getnewargs__
 
def parent
 
def root
 
def namespace
 
def app
 
def id
 
def string_id
 
def integer_id
 
def pairs
 
def flat
 
def kind
 
def reference
 
def serialized
 
def urlsafe
 
def get
 
def get_async
 
def delete
 
def delete_async
 
def from_old_key
 
def to_old_key
 

Detailed Description

An immutable datastore key.

For flexibility and convenience, multiple constructor signatures are
supported.

The primary way to construct a key is using positional arguments:
- Key(kind1, id1, kind2, id2, ...).

This is shorthand for either of the following two longer forms:
- Key(pairs=[(kind1, id1), (kind2, id2), ...])
- Key(flat=[kind1, id1, kind2, id2, ...])

Either of the above constructor forms can additionally pass in another
key using parent=<key>.  The (kind, id) pairs of the parent key are
inserted before the (kind, id) pairs passed explicitly.

You can also construct a Key from a 'url-safe' encoded string:
- Key(urlsafe=<string>)

For esoteric purposes the following constructors exist:
- Key(reference=<reference>) -- passing in a low-level Reference object
- Key(serialized=<string>) -- passing in a serialized low-level Reference
- Key(<dict>) -- for unpickling, the same as Key(**<dict>)

The 'url-safe' string is really a websafe-base64-encoded serialized
Reference, but it's best to think of it as just an opaque unique
string.

Additional constructor keyword arguments:
- app=<string> -- specify the application id
- namespace=<string> -- specify the namespace

If a Reference is passed (using one of reference, serialized or
urlsafe), the args and namespace keywords must match what is already
present in the Reference (after decoding if necessary).  The parent
keyword cannot be combined with a Reference in any form.


Keys are immutable, which means that a Key object cannot be modified
once it has been created.  This is enforced by the implementation as
well as Python allows.

For access to the contents of a key, the following methods and
operations are supported:

- repr(key), str(key) -- return a string representation resembling
  the shortest constructor form, omitting the app and namespace
  unless they differ from the default value.

- key1 == key2, key1 != key2 -- comparison for equality between Keys.

- hash(key) -- a hash value sufficient for storing Keys in a dict.

- key.pairs() -- a tuple of (kind, id) pairs.

- key.flat() -- a tuple of flattened kind and id values, i.e.
  (kind1, id1, kind2, id2, ...).

- key.app() -- the application id.

- key.id() -- the string or integer id in the last (kind, id) pair,
  or None if the key is incomplete.

- key.string_id() -- the string id in the last (kind, id) pair,
  or None if the key has an integer id or is incomplete.

- key.integer_id() -- the integer id in the last (kind, id) pair,
  or None if the key has a string id or is incomplete.

- key.namespace() -- the namespace.

- key.kind() -- a shortcut for key.pairs()[-1][0].

- key.parent() -- a Key constructed from all but the last (kind, id)
  pairs.

- key.urlsafe() -- a websafe-base64-encoded serialized Reference.

- key.serialized() -- a serialized Reference.

- key.reference() -- a Reference object.  The caller promises not to
  mutate it.

Keys also support interaction with the datastore; these methods are
the only ones that engage in any kind of I/O activity.  For Future
objects, see the document for ndb/tasklets.py.

- key.get() -- return the entity for the Key.

- key.get_async() -- return a Future whose eventual result is
  the entity for the Key.

- key.delete() -- delete the entity for the Key.

- key.delete_async() -- asynchronously delete the entity for the Key.

Keys may be pickled.

Subclassing Key is best avoided; it would be hard to get right.

Member Function Documentation

def google.appengine.ext.ndb.key.Key.__eq__ (   self,
  other 
)
Equality comparison operation.
def google.appengine.ext.ndb.key.Key.__ge__ (   self,
  other 
)
Greater than or equal ordering.
def google.appengine.ext.ndb.key.Key.__getnewargs__ (   self)
Private API used for pickling.
def google.appengine.ext.ndb.key.Key.__getstate__ (   self)
Private API used for pickling.
def google.appengine.ext.ndb.key.Key.__gt__ (   self,
  other 
)
Greater than ordering.
def google.appengine.ext.ndb.key.Key.__hash__ (   self)
Hash value, for use in dict lookups.
def google.appengine.ext.ndb.key.Key.__le__ (   self,
  other 
)
Less than or equal ordering.
def google.appengine.ext.ndb.key.Key.__lt__ (   self,
  other 
)
Less than ordering.
def google.appengine.ext.ndb.key.Key.__ne__ (   self,
  other 
)
The opposite of __eq__.
def google.appengine.ext.ndb.key.Key.__new__ (   cls,
  _args,
  kwargs 
)
Constructor.  See the class docstring for arguments.
def google.appengine.ext.ndb.key.Key.__repr__ (   self)
String representation, used by str() and repr().

We produce a short string that conveys all relevant information,
suppressing app and namespace when they are equal to the default.
def google.appengine.ext.ndb.key.Key.__setstate__ (   self,
  state 
)
Private API used for pickling.
def google.appengine.ext.ndb.key.Key.app (   self)
Return the application id.
def google.appengine.ext.ndb.key.Key.delete (   self,
  ctx_options 
)
Synchronously delete the entity for this Key.

This is a no-op if no such entity exists.
def google.appengine.ext.ndb.key.Key.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).
def google.appengine.ext.ndb.key.Key.flat (   self)
Return a tuple of alternating kind and id values.
def google.appengine.ext.ndb.key.Key.get (   self,
  ctx_options 
)
Synchronously get the entity for this Key.

Return None if there is no such entity.
def google.appengine.ext.ndb.key.Key.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.
def google.appengine.ext.ndb.key.Key.id (   self)
Return the string or integer id in the last (kind, id) pair, if any.

Returns:
  A string or integer id, or None if the key is incomplete.
def google.appengine.ext.ndb.key.Key.integer_id (   self)
Return the integer id in the last (kind, id) pair, if any.

Returns:
  An integer id, or None if the key has a string id or is incomplete.
def google.appengine.ext.ndb.key.Key.kind (   self)
Return the kind of the entity referenced.

This is the kind from the last (kind, id) pair.
def google.appengine.ext.ndb.key.Key.namespace (   self)
Return the namespace.
def google.appengine.ext.ndb.key.Key.pairs (   self)
Return a tuple of (kind, id) pairs.
def google.appengine.ext.ndb.key.Key.parent (   self)
Return a Key constructed from all but the last (kind, id) pairs.

If there is only one (kind, id) pair, return None.
def google.appengine.ext.ndb.key.Key.reference (   self)
Return the Reference object for this Key.

This is a entity_pb.Reference instance -- a protocol buffer class
used by the lower-level API to the datastore.

NOTE: The caller should not mutate the return value.
def google.appengine.ext.ndb.key.Key.root (   self)
Return the root key.  This is either self or the highest parent.
def google.appengine.ext.ndb.key.Key.serialized (   self)
Return a serialized Reference object for this Key.
def google.appengine.ext.ndb.key.Key.string_id (   self)
Return the string id in the last (kind, id) pair, if any.

Returns:
  A string id, or None if the key has an integer id or is incomplete.
def google.appengine.ext.ndb.key.Key.urlsafe (   self)
Return a url-safe string encoding this Key's Reference.

This string is compatible with other APIs and languages and with
the strings used to represent Keys in GQL and in the App Engine
Admin Console.

The documentation for this class was generated from the following file: