Keys

Create / interact with Google Cloud Datastore keys.

class google.cloud.datastore.key.Key(*path_args, **kwargs)

Bases: object

An immutable representation of a datastore Key.

To create a basic key directly:

 >>> Key('EntityKind', 1234, project=project)
<Key('EntityKind', 1234), project=...>
>>> Key('EntityKind', 'foo', project=project)
<Key('EntityKind', 'foo'), project=...> 

Though typical usage comes via the key() factory:

 >>> client.key('EntityKind', 1234)
<Key('EntityKind', 1234), project=...>
>>> client.key('EntityKind', 'foo')
<Key('EntityKind', 'foo'), project=...> 

To create a key with a parent:

 >>> client.key('Parent', 'foo', 'Child', 1234)
<Key('Parent', 'foo', 'Child', 1234), project=...>
>>> client.key('Child', 1234, parent=parent_key)
<Key('Parent', 'foo', 'Child', 1234), project=...> 

To create a partial key:

 >>> client.key('Parent', 'foo', 'Child')
<Key('Parent', 'foo', 'Child'), project=...> 

• Parameters

  • path_args( tuple of string and integer ) – May represent a partial (odd length) or full (even length) key path.

  • kwargs– Keyword arguments to be passed in.

Accepted keyword arguments are

• namespace (string): A namespace identifier for the key.

• project (string): The project associated with the key.

• parent ( Key ): The parent of the key.

The project argument is required unless it has been set implicitly.

_ eq_ (other)

Compare two keys for equality.

Incomplete keys never compare equal to any other key.

Completed keys compare equal if they have the same path, project, and namespace.

• Return type

  bool

• Returns

  True if the keys compare equal, else False.

_ hash_ ()

Hash a keys for use in a dictionary lookp.

• Return type

  int

• Returns

  a hash of the key’s state.

_ ne_ (other)

Compare two keys for inequality.

Incomplete keys never compare equal to any other key.

Completed keys compare equal if they have the same path, project, and namespace.

• Return type

  bool

• Returns

  False if the keys compare equal, else True.

completed_key(id_or_name)

Creates new key from existing partial key by adding final ID/name.

• Parameters

  id_or_name( str * or *integer ) – ID or name to be added to the key.

• Return type

  google.cloud.datastore.key.Key

• Returns

  A new Key instance with the same data as the current one and an extra ID or name added.

• Raises

  ValueError if the current key is not partial or if id_or_name is not a string or integer.

property flat_path()

Getter for the key path as a tuple.

• Return type

  tuple of string and integer

• Returns

  The tuple of elements in the path.

classmethod from_legacy_urlsafe(urlsafe)

Convert urlsafe string to Key .

This is intended to work with the “legacy” representation of a datastore “Key” used within Google App Engine (a so-called “Reference”). This assumes that urlsafe was created within an App Engine app via something like ndb.Key(...).urlsafe() .

• Parameters

  urlsafe( bytes * or *unicode ) – The base64 encoded (ASCII) string corresponding to a datastore “Key” / “Reference”.

• Return type

  Key .

• Returns

  The key corresponding to urlsafe .

property id()

ID getter. Based on the last element of path.

• Return type

  int

• Returns

  The (integer) ID of the key.

property id_or_name()

Getter. Based on the last element of path.

• Return type

  int (if id ) or string (if name )

• Returns

  The last element of the key’s path if it is either an id or a name .

property is_partial()

Boolean indicating if the key has an ID (or name).

• Return type

  bool

• Returns

  True if the last element of the key’s path does not have an id or a name .

property kind()

Kind getter. Based on the last element of path.

• Return type

  str

• Returns

  The kind of the current key.

property name()

Name getter. Based on the last element of path.

• Return type

  str

• Returns

  The (string) name of the key.

property namespace()

Namespace getter.

• Return type

  str

• Returns

  The namespace of the current key.

property parent()

The parent of the current key.

• Return type

  google.cloud.datastore.key.Key or NoneType

• Returns

  A new Key instance, whose path consists of all but the last element of current path. If the current key has only one path element, returns None .

property path()

Path getter.

Returns a copy so that the key remains immutable.

• Return type

  list of dict

• Returns

  The (key) path of the current key.

property project()

Project getter.

• Return type

  str

• Returns

  The key’s project.

to_legacy_urlsafe(location_prefix=None)

Convert to a base64 encode urlsafe string for App Engine.

This is intended to work with the “legacy” representation of a datastore “Key” used within Google App Engine (a so-called “Reference”). The returned string can be used as the urlsafe argument to ndb.Key(urlsafe=...) . The base64 encoded values will have padding removed.

NOTE: The string returned by to_legacy_urlsafe is equivalent, but not identical, to the string returned by ndb . The location prefix may need to be specified to obtain identical urlsafe keys.

• Parameters

  location_prefix( str ) – The location prefix of an App Engine project ID. Often this value is ‘s~’, but may also be ‘e~’, or other location prefixes currently unknown.

• Return type

  bytes

• Returns

  A bytestring containing the key encoded as URL-safe base64.

to_protobuf()

Return a protobuf corresponding to the key.

• Return type

  entity_pb2.Key

• Returns

  The protobuf representing the key.