here.platform.adapter module

HERE platform, content adaptation, encoding and decoding.

class here.platform.adapter.Adapter
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_* and write_* functions of the Layer and its subclasses, please see documentation of specific adapters, and the respective Decoder and Encoder class documentation.

All the operations involving content passes through an adapter when the parameters encode or decode are True, their default value. These are parameters of the read_* and write_* functions. If a content type is not supported, or if reading or writing raw content is preferred, pass False 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 property decoder: Decoder
The decoder associated with the adapter.

abstract property encoder: Encoder
The encoder associated with the adapter.

abstract from_feature_ids(feature_ids: Iterator[str], **kwargs)
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)
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)
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 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_index_metadata(partitions: Iterator[IndexPartition], **kwargs)
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)
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 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_metadata(partitions: Iterator[StreamPartition], **kwargs)
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)
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 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_metadata(partitions: Iterator[VersionedPartition], **kwargs)
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)
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 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_metadata(partitions: Iterator[VolatilePartition], **kwargs)
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]
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]
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
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 layer

• kwargs – 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]]
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 layer

• timestamp – 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]
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]]
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 layer

• kwargs – 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]]
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]]
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 layer

• kwargs – 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]]
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
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)
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, CODE_BLOCK_0 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 considered None. 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.

abstract from_tabular(columns, data, geometry_column='geometry')
Convert the given tabular data.

Parameters:

• columns – column names

• data – tabular data

• geometry_column – geometry column string

Returns:
data representation is function of the adapter # noqa

class here.platform.adapter.Decoder
Bases: ABC

A content decoder and its capabilities.

abstract decode_blob(data: bytes, content_type: str, schema: Schema | None = None, **kwargs)
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
Bases: ABC

A content encoder and its capabilities.

abstract encode_blob(data, content_type: str, schema: Schema | None = None, **kwargs) → bytes
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 type

• content_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)
Bases: object

A [0, 1] range.

end: float | None

start: float | None

class here.platform.adapter.Ref(partition: Partition, identifier: Identifier)
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

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

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

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