tiled.client.base.BaseClient.build_metadata_patches

BaseClient.build_metadata_patches(metadata=None, specs=None)[source]

Build valid JSON Patches (RFC6902) for metadata and metadata validation specs accepted by patch_metadata.

Parameters:

metadatadict, optional: User metadata. May be nested. Must contain only basic types (e.g. numbers, strings, lists, dicts) that are JSON-serializable.
specslist[Spec], optional: Metadata validation specifications.

Returns:

metadata_patchlist[dict]: A JSON serializable object representing a valid JSON patch (RFC6902) for metadata.
specs_patchlist[dict]: A JSON serializable object representing a valid JSON patch (RFC6902) for metadata validation specifications.

See also

patch_metadata
update_metadata

Notes

build_metadata_patch constructs a JSON Patch (RFC6902) by comparing user updates to existing metadata/specs. It uses a slight variation of JSON Merge Patch (RFC7386) as an intermediary to implement a python dict.update-like user-friendly interface, but with additional features like key deletion (see examples) and support for None (null) values.

Examples

Build a patch for adding/updating a key-value pair at the top or a nested level

>>> patches = node.build_metadata_patches({'key': new_value})
>>> patches = node.build_metadata_patches({'top_key': {'nested_key': new_value}})

Build patches for metadata and specs (“mp”, “sp”)

>>> mp, sp = node.build_metadata_patches(metadata=metadata, specs=specs)

Build a patch for removing an existing key

>>> from tiled.client.metadata_update import DELETE_KEY
>>> node.build_metadata_patches({'key_to_be_deleted': DELETE_KEY})

Interactively build a patch for complex metadata (e.g., in iPython you may use tab completion to navigate nested metadata)

>>> md = node.metadata_copy()[0]
>>> md['L1_key']['L2_key']['L3_key'] = new_value  # use tab completion
>>> md['unwanted_key'] = DELETE_KEY
>>> node.build_metadata_patches(metadata=md)  # Generate the patch