Keys#

Create / interact with Google Cloud Datastore keys.

class google.cloud.datastore.key.Key(*path_args, **kwargs)[source]#

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.

completed_key(id_or_name)[source]#

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)[source]#

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)[source]#

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()[source]#

Return a protobuf corresponding to the key.

Return type

entity_pb2.Key

Returns

The protobuf representing the key.