Class Key (2.9.0)
Stay organized with collections
Save and categorize content based on your preferences.
Key(*path_args, **kwargs)An immutable representation of a datastore Key.
.. testsetup:: key-ctor
from google.cloud import datastore
project = 'my-special-pony' client = datastore.Client(project=project) Key = datastore.Key
parent_key = client.key('Parent', 'foo')
To create a basic key directly:
.. doctest:: key-ctor
Key('EntityKind', 1234, project=project) <Key('EntityKind', 1234), project=...> Key('EntityKind', 'foo', project=project) <Key('EntityKind', 'foo'), project=...>
Though typical usage comes via the xref_key factory:
.. doctest:: key-ctor
client.key('EntityKind', 1234) <Key('EntityKind', 1234), project=...> client.key('EntityKind', 'foo') <Key('EntityKind', 'foo'), project=...>
To create a key with a parent:
.. doctest:: key-ctor
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:
.. doctest:: key-ctor
client.key('Parent', 'foo', 'Child') <Key('Parent', 'foo', 'Child'), project=...>
Parameter |
|
|---|---|
| Name | Description |
path_args |
tuple of string and integer
May represent a partial (odd length) or full (even length) key path. |
Properties
flat_path
Getter for the key path as a tuple.
| Returns | |
|---|---|
| Type | Description |
tuple of string and integer |
The tuple of elements in the path. |
id
ID getter. Based on the last element of path.
| Returns | |
|---|---|
| Type | Description |
int |
The (integer) ID of the key. |
id_or_name
Getter. Based on the last element of path.
| Returns | |
|---|---|
| Type | Description |
int (if |
The last element of the key's path if it is either an id or a name. |
is_partial
Boolean indicating if the key has an ID (or name).
| Returns | |
|---|---|
| Type | Description |
bool |
True if the last element of the key's path does not have an id or a name. |
kind
Kind getter. Based on the last element of path.
| Returns | |
|---|---|
| Type | Description |
str |
The kind of the current key. |
name
Name getter. Based on the last element of path.
| Returns | |
|---|---|
| Type | Description |
str |
The (string) name of the key. |
namespace
Namespace getter.
| Returns | |
|---|---|
| Type | Description |
str |
The namespace of the current key. |
parent
The parent of the current key.
| Returns | |
|---|---|
| Type | Description |
Key or |
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. |
path
Path getter.
Returns a copy so that the key remains immutable.
| Returns | |
|---|---|
| Type | Description |
|
The (key) path of the current key. |
project
Project getter.
| Returns | |
|---|---|
| Type | Description |
str |
The key's project. |
Methods
__eq__
__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.
| Returns | |
|---|---|
| Type | Description |
bool |
True if the keys compare equal, else False. |
__hash__
__hash__()Hash a keys for use in a dictionary lookp.
| Returns | |
|---|---|
| Type | Description |
int |
a hash of the key's state. |
__ne__
__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.
| Returns | |
|---|---|
| Type | Description |
bool |
False if the keys compare equal, else True. |
completed_key
completed_key(id_or_name)Creates new key from existing partial key by adding final ID/name.
| Parameter | |
|---|---|
| Name | Description |
id_or_name |
str or integer
ID or name to be added to the key. |
| Exceptions | |
|---|---|
| Type | Description |
`ValueError |
if the current key is not partial or if id_or_name is not a string or integer. |
| Returns | |
|---|---|
| Type | Description |
Key |
A new Key instance with the same data as the current one and an extra ID or name added. |
from_legacy_urlsafe
from_legacy_urlsafe(urlsafe)Convert urlsafe string to xref_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().
| Parameter | |
|---|---|
| Name | Description |
urlsafe |
bytes or unicode
The base64 encoded (ASCII) string corresponding to a datastore "Key" / "Reference". |
| Returns | |
|---|---|
| Type | Description |
Key. |
The key corresponding to urlsafe. |
to_legacy_urlsafe
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.
| Parameter | |
|---|---|
| Name | Description |
location_prefix |
str
The location prefix of an App Engine project ID. Often this value is 's |
| Returns | |
|---|---|
| Type | Description |
bytes |
A bytestring containing the key encoded as URL-safe base64. |
to_protobuf
to_protobuf()Return a protobuf corresponding to the key.
| Returns | |
|---|---|
| Type | Description |
|
The protobuf representing the key. |