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.