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
- 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 ifid_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 likendb.Key(...).urlsafe()
.
-
property
id
# ID getter. Based on the last element of path.
- Return type
- 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 (ifname
)- Returns
The last element of the key’s path if it is either an
id
or aname
.
-
property
is_partial
# Boolean indicating if the key has an ID (or name).
- Return type
- Returns
True
if the last element of the key’s path does not have anid
or aname
.
-
property
kind
# Kind getter. Based on the last element of path.
- Return type
- Returns
The kind of the current key.
-
property
name
# Name getter. Based on the last element of path.
- Return type
- Returns
The (string) name of the key.
-
property
parent
# The parent of the current key.
- Return type
google.cloud.datastore.key.Key
orNoneType
- 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, returnsNone
.
-
property
path
# Path getter.
Returns a copy so that the key remains immutable.
-
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 tondb.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 byndb
. The location prefix may need to be specified to obtain identical urlsafe keys.