Note:Developers building new applications arestrongly encouraged to use theNDB Client Library, which has several benefitscompared to this client library, such as automatic entity caching via the MemcacheAPI. If you are currently using the older DB Client Library, read theDB to NDB Migration Guide

An instance of the Key class represents a unique key for a Datastore entity.

Key is provided by thegoogle.appengine.ext.db module.

Introduction

Every model instance has an identifyingkey,which includes the instance'sentity kindalong with a uniqueidentifier. The identifier may be either akey name string, assigned explicitly by the application when the instance is created, or an integernumeric ID, assigned automatically by App Engine when the instance is written (put)to the Datastore. The model instance's key()method returns theKey object for the instance. If the instance has not yet been assigned a key,key() raises a NotSavedError.

An application can retrieve a model instance for a given Key using theget() function.

Key instances can be values for Datastore entity properties, includingExpando dynamic properties andListProperty members. TheReferenceProperty model provides features for Key property values such as automatic dereferencing.

Constructor

class Key(encoded=None)

A unique key for a Datastore object.

A key can be converted to a string by passing the Key object tostr(). The string is "urlsafe"—it uses only characters valid for use in URLs. The string representation of the key can be converted back to a Key object by passing it to the Key constructor (theencoded argument).

Note: The string representation of a key looks cryptic, but is not encrypted! It can be converted back to the raw key data, both kind and identifier. If you don't want to expose this data to your users (and allow them to easily guess other entities' keys), then encrypt these strings or use something else.

encoded

Thestr form of a Key instance to convert back into a Key.

Class Methods

The Key class provides the following class method:

Key.from_path(*path,parent=None,namespace=None)

Builds a new Key object from an (optional) ancestor path (in an existing Key object), and one or more new path components. Each pathcomponent consists of a Kind name (kind) and an identifier (id_or_name), which is either a number or a character string.

A path represents the hierarchy of parent-child relationships for an entity. Each entity in the path is represented by the entity's kind, and either its numeric ID or its key name. The full path represents the entity that appears last in the path, with its ancestors (parents) as preceding entities.

For example, the following call creates a Key for an entity of kindAddress with numeric ID9876, under the parent keyUser/Boris:

k = Key.from_path('User', 'Boris', 'Address', 9876)

An alternative way of creating the same Key is as follows:

p1 = Key.from_path('User', 'Boris')k = Key.from_path('Address', 9876, parent=p1)

For more information about paths, see theEntities, Properties, and Keys page.

Arguments

path

A list of one or more ancestor path components, where each component consists of akind and anidentifier:

• kind — The entity kind, represented as a string or a Unicode string.
• identifier — Theid, specified as a string or long. It cannot be the number 0.

namespace=None

The namespace to set for this Key only. If you supply a namespace here, it overrides the current namespace set in thenamespace_manager. IfNone, the API uses the current namespace fromnamespace_manager.get_namespace.

parent=None

Optional parent key. If not supplied, defaults toNone.

Instance Methods

Key instances have the following methods:

app()

Returns the name of the application that stored the data entity.

has_id_or_name()

ReturnsTrue if the entity has either a name or a numeric ID.

id()

Returns the numeric ID of the data entity, as an integer, orNone if the entity does not have a numeric ID.

id_or_name()

Returns the name or numeric ID of the data entity, whichever it has, orNone if the entity has neither a name nor a numeric ID.

kind()

Returns the kind of the data entity, as a string.

name()

Returns the name of the data entity, orNone if the entity does not have a name.

namespace()

Returns the namespace of the data entity. If the entity does not have a current namespace, this method returns the current namespace set in thenamespace_manager.

parent()

Returns the Key of the data entity's parent entity, orNone if the entity has no parent.