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. |
Inheritance
builtins.object > KeyProperties
flat_path
Getter for the key path as a tuple.
| Type | Description |
| tuple of string and integer | The tuple of elements in the path. |
id
ID getter. Based on the last element of path.
| Type | Description |
|---|---|
| int | The (integer) ID of the key. |
id_or_name
Getter. Based on the last element of path.
| Type | Description |
| int (if ``id``) or string (if ``name``) | 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).
| 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.
| Type | Description |
| str | The kind of the current key. |
name
Name getter. Based on the last element of path.
| Type | Description |
| str | The (string) name of the key. |
namespace
Namespace getter.
| Type | Description |
| str | The namespace of the current key. |
parent
The parent of the current key.
| Type | Description |
| Key or `NoneType` | 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.
| Type | Description |
| `list` of `dict` | The (key) path of the current key. |
project
Project getter.
| 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.
| Type | Description |
| bool | True if the keys compare equal, else False. |
__hash__
__hash__
()
Hash a keys for use in a dictionary lookp.
| 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.
| 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.
| Name | Description |
| id_or_name | str or integer
ID or name to be added to the key. |
| Type | Description |
| `ValueError | if the current key is not partial or if ``id_or_name`` is not a string or integer. |
| 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()
.
| Name | Description |
| urlsafe | bytes or unicode
The base64 encoded (ASCII) string corresponding to a datastore "Key" / "Reference". |
| 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.
.. 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.
| Name | Description |
| location_prefix | str
The location prefix of an App Engine project ID. Often this value is 's |
| Type | Description |
| bytes | A bytestring containing the key encoded as URL-safe base64. |
to_protobuf
to_protobuf
()
Return a protobuf corresponding to the key.
| Type | Description |
| `.entity_pb2.Key` | The protobuf representing the key. |
