As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

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=...>

To create a key from a non-default database:

>>> Key('EntityKind', 1234, project=project, database='mydb')
<Key('EntityKind', 1234), project=my-special-pony, database=mydb>

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.
database (string): The database associated with the key.
parent (Key): The parent of the key.

The project argument is required unless it has been set implicitly.

__eq__(other)[source]¶

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, database, and namespace.

(Note that database=None is considered to refer to the default database.)

Return type: bool
Returns: True if the keys compare equal, else False.

__hash__()[source]¶

Hash this key for use in a dictionary lookup.

Return type: int
Returns: a hash of the key’s state.

__ne__(other)[source]¶

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, database, and namespace.

(Note that database=None is considered to refer to the default database.)

Return type: bool
Returns: False if the keys compare equal, else True.

__repr__()[source]¶

String representation of this key.

Includes the project and database, but suppresses them if they are equal to the default values.

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 database¶

Database getter.

Return type: str
Returns: The database of the current key.

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().

Note

from_legacy_urlsafe only supports the default database.

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.

Note

to_legacy_urlsafe only supports the default database

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.

Keys¶

google-cloud-datastore

Navigation

Related Topics