def reference(self):
"""The ``Reference`` protobuf object for this key.
The return value will be stored on the current key, so the caller
promises not to mutate it.
.. doctest:: key-reference
>>> key = ndb.Key("Trampoline", 88, app="xy", namespace="zt")
>>> key.reference()
app: "xy"
path {
Element {
type: "Trampoline"
id: 88
}
}
name_space: "zt"
<BLANKLINE>
"""
if self._reference is None:
self._reference = _app_engine_key_pb2.Reference(
app=self._key.project,
path=_to_legacy_path(self._key.path),
name_space=self._key.namespace,
)
return self._reference
def from_legacy_urlsafe(cls, urlsafe):
"""Convert urlsafe string to :class:`~google.cloud.datastore.key.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()``.
:type urlsafe: bytes or unicode
:param urlsafe: The base64 encoded (ASCII) string corresponding to a
datastore "Key" / "Reference".
:rtype: :class:`~google.cloud.datastore.key.Key`.
:returns: The key corresponding to ``urlsafe``.
"""
urlsafe = _to_bytes(urlsafe, encoding="ascii")
padding = b"=" * (-len(urlsafe) % 4)
urlsafe += padding
raw_bytes = base64.urlsafe_b64decode(urlsafe)
reference = _app_engine_key_pb2.Reference()
reference.ParseFromString(raw_bytes)
project = _clean_app(reference.app)
namespace = _get_empty(reference.name_space, u"")
_check_database_id(reference.database_id)
flat_path = _get_flat_path(reference.path)
return cls(*flat_path, project=project, namespace=namespace)
def make_reference(
path=({"type": "Parent", "id": 59}, {"type": "Child", "name": "Feather"}),
app="s~sample-app",
namespace="space",
):
elements = [
_app_engine_key_pb2.Path.Element(**element) for element in path
]
return _app_engine_key_pb2.Reference(
app=app,
path=_app_engine_key_pb2.Path(element=elements),
name_space=namespace,
)
def to_legacy_urlsafe(self):
"""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=...)``.
:rtype: bytes
:returns: A bytestring containing the key encoded as URL-safe base64.
"""
reference = _app_engine_key_pb2.Reference(
app=self.project,
path=_to_legacy_path(self._path), # Avoid the copy.
name_space=self.namespace,
)
raw_bytes = reference.SerializeToString()
return base64.urlsafe_b64encode(raw_bytes)
def _from_serialized(serialized, app, namespace):
"""Convert serialized protobuf to :class:`~google.cloud.datastore.key.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 ``serialized`` was created within an App
Engine app via something like ``ndb.Key(...).serialized()``.
Args:
serialized (bytes): A reference protobuf serialized to bytes.
app (Optional[str]): The application ID / project ID for the
constructed key.
namespace (Optional[str]): The namespace for the constructed key.
Returns:
Tuple[google.cloud.datastore.key.Key, .Reference]: The key
corresponding to ``serialized`` and the Reference protobuf.
"""
reference = _app_engine_key_pb2.Reference()
reference.ParseFromString(serialized)
return _from_reference(reference, app, namespace), reference
def to_legacy_urlsafe(self, 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.
:type location_prefix: str
:param location_prefix: 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.
:rtype: bytes
:returns: A bytestring containing the key encoded as URL-safe base64.
"""
if location_prefix is None:
project_id = self.project
else:
project_id = location_prefix + self.project
reference = _app_engine_key_pb2.Reference(
app=project_id,
path=_to_legacy_path(self._path), # Avoid the copy.
name_space=self.namespace,
)
raw_bytes = reference.SerializeToString()
return base64.urlsafe_b64encode(raw_bytes).strip(b"=")
