here.platform.adapter module — HERE Data SDK for Python documentation
- Last UpdatedMar 27, 2025
- 13 minute read
HERE platform, content adaptation, encoding and decoding.
- class here.platform.adapter.Adapter[source]#
Bases:
ABC
An adapter controls the encoding and decoding process of platform data. It transforms data from and to adapter-specific data structure and supports reading, writing, encoding and decoding a variety of MIME content types.
For the list of MIME content types supported when reading and writing a layer with
read_*
andwrite_*
functions of theLayer
and its subclasses, please see documentation of specific adapters, and the respectiveDecoder
andEncoder
class documentation.All the operations involving content passes through an adapter when the parameters
encode
ordecode
areTrue
, their default value. These are parameters of theread_*
andwrite_*
functions. If a content type is not supported, or if reading or writing raw content is preferred, passFalse
to skip encoding or decoding and deal with raw bytes instead.If no adapter is specified, a default one is provided that is generic enough to encode and decode a common content types from and to standard Python classes, such as lists and dictionaries.
More sophisticated adapters, subclasses of
Adapter
, are provided in separate packages.- abstract property content_adapter: ContentAdapter#
The adapter specialized for content.
- abstract from_feature_ids(feature_ids: Iterator[str], **kwargs)[source]#
Adapt a sequence of feature identifiers to the target format.
- Parameters:
feature_ids – sequence of feature identifiers
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract from_geo_features(features: Iterator[Feature], **kwargs)[source]#
Adapt a sequence of geographic features to the target format.
- Parameters:
features – sequence of geographic features
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract from_index_data(partitions_data: Iterator[Tuple[IndexPartition, bytes]], content_type: str, schema: Schema | None, **kwargs)[source]#
Adapt index partition metadata and data to the target format.
- Parameters:
partitions_data – sequence of partition metadata and data from an index layer
content_type – the MIME content type of the layer
schema – optional
Schema
of the layerkwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract from_index_metadata(partitions: Iterator[IndexPartition], **kwargs)[source]#
Adapt index partition metadata to the target format.
- Parameters:
partitions – sequence of partition metadata from an index layer
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract from_stream_data(partitions_data: Iterator[Tuple[StreamPartition, bytes]], content_type: str, schema: Schema | None, **kwargs)[source]#
Adapt stream partition metadata and data to the target format.
- Parameters:
partitions_data – sequence of partition metadata and data from a stream layer
content_type – the MIME content type of the layer
schema – optional
Schema
of the layerkwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract from_stream_metadata(partitions: Iterator[StreamPartition], **kwargs)[source]#
Adapt stream partition metadata to the target format.
- Parameters:
partitions – sequence of partition metadata from a stream layer
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract from_versioned_data(partitions_data: Iterator[Tuple[VersionedPartition, bytes]], content_type: str, schema: Schema | None, **kwargs)[source]#
Adapt versioned partition metadata and data to the target format.
- Parameters:
partitions_data – sequence of partition metadata and data from a versioned layer
content_type – the MIME content type of the layer
schema – optional
Schema
of the layerkwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract from_versioned_metadata(partitions: Iterator[VersionedPartition], **kwargs)[source]#
Adapt versioned partition metadata to the target format.
- Parameters:
partitions – sequence of partition metadata from a versioned layer
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract from_volatile_data(partitions_data: Iterator[Tuple[VolatilePartition, bytes]], content_type: str, schema: Schema | None, **kwargs)[source]#
Adapt volatile partition metadata and data to the target format.
- Parameters:
partitions_data – sequence of partition metadata and data from a volatile layer
content_type – the MIME content type of the layer
schema – optional
Schema
of the layerkwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract from_volatile_metadata(partitions: Iterator[VolatilePartition], **kwargs)[source]#
Adapt volatile partition metadata to the target format.
- Parameters:
partitions – sequence of partition metadata from a volatile layer
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports # noqa
- abstract to_feature_ids(data, **kwargs) Iterator[str] [source]#
Adapt data from the target format to a sequence of feature identifiers.
- Parameters:
data – adapter-specific, the data to adapt
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
sequence of feature identifiers # noqa
- abstract to_geo_features(data, **kwargs) Iterator[Feature] [source]#
Adapt data from the target format to a sequence of geographic features.
- Parameters:
data – adapter-specific, the data to adapt
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
sequence of geographic features # noqa
- abstract to_index_single_data(data, content_type: str, schema: Schema | None, **kwargs) bytes [source]#
Adapt index data from the target format.
- Parameters:
data – adapter-specific, please consult the documentation of the specific adapter to for the formats and types it supports
content_type – the MIME content type of the layer
schema – optional
Schema
of the layerkwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
data encoded for an index layer # noqa
- abstract to_stream_data(layer: StreamLayer, data, content_type: str, schema: Schema | None, timestamp: int | None, **kwargs) Iterator[Tuple[str | int, bytes, int | None]] [source]#
Adapt data from the target format to stream partition metadata and data.
- Parameters:
layer – the layer all the metadata and data belong to
data – adapter-specific, the data to adapt
content_type – the MIME content type of the layer
schema – optional
Schema
of the layertimestamp – optional timestamp for all the messages, if none is specified in data: in milliseconds since Unix epoch (1970-01-01T00:00:00 UTC)
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
sequence of partition id, data and timestamp for the stream layer # noqa
- abstract to_stream_metadata(layer: StreamLayer, partitions, **kwargs) Iterator[StreamPartition] [source]#
Adapt what to publish from the target format to stream partition metadata.
- Parameters:
layer – the layer all the metadata and data belong to
partitions – adapter-specific, the partitions metadata to publish
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
Iterator with the
StreamPartition
that are adapted
- abstract to_versioned_data(layer: VersionedLayer, data, content_type: str, schema: Schema | None, **kwargs) Iterator[Tuple[str | int, bytes]] [source]#
Adapt data from the target format to versioned partition metadata and data.
- Parameters:
layer – the layer all the metadata and data belong to
data – adapter-specific, the data to adapt
content_type – the MIME content type of the layer
schema – optional
Schema
of the layerkwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
sequence of partition id and data for the versioned layer # noqa
- abstract to_versioned_metadata(layer: VersionedLayer, partitions_update, partitions_delete, **kwargs) Tuple[Iterator[VersionedPartition], Iterator[str | int]] [source]#
Adapt what update and delete from the target format to versioned partition metadata.
- Parameters:
layer – the layer all the metadata and data belong to
partitions_update – adapter-specific, the partitions metadata to update, if any
partitions_delete – adapter-specific, the partitions metadata to delete, if any
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
Iterator with the
VersionedPartition
that are adapted
- abstract to_volatile_data(layer: VolatileLayer, data, content_type: str, schema: Schema | None, **kwargs) Iterator[Tuple[str | int, bytes]] [source]#
Adapt data from the target format to volatile partition metadata and data.
- Parameters:
layer – the layer all the metadata and data belong to
data – adapter-specific, the data to adapt
content_type – the MIME content type of the layer
schema – optional
Schema
of the layerkwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
sequence of partition id and data for the volatile layer # noqa
- abstract to_volatile_metadata(layer: VolatileLayer, partitions_update, partitions_delete, **kwargs) Tuple[Iterator[VolatilePartition], Iterator[str | int]] [source]#
Adapt what update and delete from the target format to volatile partition metadata.
- Parameters:
layer – the layer all the metadata and data belong to
partitions_update – adapter-specific, the partitions metadata to update, if any
partitions_delete – adapter-specific, the partitions metadata to delete, if any
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
tuple of Iterator, the first with the
VolatilePartition
that are adapted, the second with the partition ids to delete # noqa
- class here.platform.adapter.ContentAdapter[source]#
Bases:
ABC
Interface of the content adapters, an adapter specialized to work with content via the here-content package.
- abstract from_objects(fields: type, data: Iterator[object], single_element: bool = False, index_partition: None | str | Callable[[object], Partition] = None, index_id: None | str | Callable[[object], Identifier] = None, index_ref: None | str | Callable[[object], Ref | Iterable[Ref]] = None)[source]#
Adapt content form an object representation to the target format.
It can optionally perform indexing of objects, based on their partition, identifier and set of references to other objects. Indexing is specified by naming the field of the object that contains the value to index, or by passing a function that calculates that value from the object.
- Parameters:
fields – the fields to extract, as specified by a dataclass. Field names are looked up among the attributes of each object via
getattr`. When missing, ``None
or equivalent is used. Each field has a type that describes its semantic: it is used to adapt the value to the most appropriate representation for the output format.TypeError
is raised in case this is not possible.data – the objects to adapt to the target format. Fields not mentioned in
fields
are discarded. Expected but missing fields and identifiers are consideredNone
. Field values may be of any type compatible with the type declared for the field. Partition ids don’t have to be unique, but they have to be contiguous: all the objects with a given partition identifier must be returned in sequence. Object identifiers, when present, must be unique across the whole content.single_element – the data contains exactly one element, the content adapter case use this information to optimize or return a specialized representation
index_partition – index the content by partition
index_id – index the content by object identifier
index_ref – index the content by references. Each object can contain zero, one or more references, and references can be shared among multiple objects.
- Returns:
an adapter-specific representation of the structured content.
- Raises:
ValueError: if the fields are not described by a dataclass KeyError: in case partition id, object id or reference is needed but not present TypeError: in case partition or object id is not of type int or string. Also raised in case field values are not of the type declared for the field, or if they can’t be converted to it.
- class here.platform.adapter.Decoder[source]#
Bases:
ABC
A content decoder and its capabilities.
- abstract decode_blob(data: bytes, content_type: str, schema: Schema | None = None, **kwargs)[source]#
Decode one single blob of data.
- Parameters:
data – the encoded data
content_type – the MIME content type to be decoded
schema – the schema, if the content type requires one
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
the decoded blob, its type corresponds to the type declared in the property
supported_content_types
for the content type # noqa- Raises:
UnsupportedContentTypeDecodeException – in case the content type is not decodable
ValueError – if the schema is mandatory for the content type but missing
DecodeException – in case the blob can’t be properly decoded # noqa
SchemaException – in case the schema can’t be used to decode the content # noqa
- abstract property supported_content_types: Dict[str, type | Tuple[type, ...]]#
- Returns:
the dictionary of MIME content types supported when decoding single blobs # noqa
with the
decode_blob
function of this decoder, each with the type of the decoded data.
- class here.platform.adapter.Encoder[source]#
Bases:
ABC
A content encoder and its capabilities.
- abstract encode_blob(data, content_type: str, schema: Schema | None = None, **kwargs) bytes [source]#
Encode one single blob of data.
- Parameters:
data – the data to be encoded, its type corresponds to the type declared in the property
supported_content_types
for the content typecontent_type – the MIME content type to be encoded
schema – the schema, if the content type requires one
kwargs – adapter-specific, please consult the documentation of the specific adapter to for the parameters and types it supports
- Returns:
the encoded data # noqa
- Raises:
UnsupportedContentTypeEncodeException – in case the content type is not encodable
ValueError – if the schema is mandatory for the content type but missing
EncodeException – in case the blob can’t be properly encoded # noqa
SchemaException – in case the schema can’t be used to encode the content # noqa
- abstract property supported_content_types: Dict[str, type | Tuple[type, ...]]#
- Returns:
the dictionary of MIME content types supported when encoding single blobs # noqa
with the
encode_blob
function of this encoder, each with the type of the encoded data.
- class here.platform.adapter.Range(start: float | None, end: float | None)[source]#
Bases:
object
A [0, 1] range.
- end: float | None#
- start: float | None#
- class here.platform.adapter.Ref(partition: Partition, identifier: Identifier)[source]#
Bases:
object
A reference to an object in a partition.
- identifier: Identifier#
- partition: Partition#
- here.platform.adapter.make_cat_ref(partition: str | int | Partition, identifier: str | Identifier) Ref [source]#
Construct a new Category Reference given identifier and/or partition.
This supports a variety of parameter types and performs basics checks.
- Parameters:
partition – the partition name
identifier – the object or feature identifier
- Returns:
a reference
- Raises:
ValueError – in case of invalid or empty parameters
- here.platform.adapter.make_range(start: int | float | None, end: int | float | None) Range [source]#
Construct a new Range given start and end offsets.
This supports a variety of parameter types and performs basics checks.
- Parameters:
start – the start offset, when available and greater or equal 0.0
end – the end offset, when available and less or equal 1.0.
- Returns:
a range
- Raises:
ValueError – in case of parameters out of range
- here.platform.adapter.make_ref(partition: str | int | Partition, identifier: str | Identifier) Ref [source]#
Construct a new Reference given partition and identifier.
This supports a variety of parameter types and performs basics checks.
- Parameters:
partition – the partition name
identifier – the object or feature identifier
- Returns:
a reference
- Raises:
ValueError – in case of invalid or empty parameters