dapla_metadata.datasets.compatibility package

dapla_metadata.datasets.compatibility.model_backwards_compatibility module

Upgrade old metadata files to be compatible with new versions.

An important principle of Datadoc is that we ALWAYS guarantee backwards compatibility of existing metadata documents. This means that we guarantee that a user will never lose data, even if their document is decades old.

For each document version we release with breaking changes, we implement a handler and register the version by defining a BackwardsCompatibleVersion instance. These documents will then be upgraded when they’re opened in Datadoc.

A test must also be implemented for each new version.

class BackwardsCompatibleVersion(version, handler)

Bases: object

A version which we support with backwards compatibility.

This class registers a version and its corresponding handler function for backwards compatibility.

Parameters:

• version (str)

• handler (Callable[[dict[str, Any]], dict[str, Any]])

handler: Callable[[dict[str, Any]], dict[str, Any]]

upgrade(metadata)

Upgrade metadata from the format of the previous version to the format of this version.

This method handles bumping the Document Version field so it’s not necessary to do this in the individual handler functions.

Parameters:

metadata (dict[str, Any]) – Metadata in the format of the previous version, to be upgraded.

Returns:

The metadata upgraded to the version specified

Return type:

dict[str, Any]

version: str

upgrade_metadata(fresh_metadata)

Upgrade the metadata to the latest version using registered handlers.

This function checks the version of the provided metadata and applies a series of upgrade handlers to migrate the metadata to the latest version. It starts from the provided version and applies all subsequent handlers in sequence. If the metadata is already in the latest version or the version cannot be determined, appropriate actions are taken.

Parameters:

fresh_metadata (dict[str, Any]) – The metadata dictionary to be upgraded. This dictionary must include version information that determines which handlers to apply.

Return type:

dict[str, Any]

Returns:

The upgraded metadata dictionary, after applying all necessary handlers.

Raises:

UnknownModelVersionError – If the metadata’s version is unknown or unsupported.