core.metadata

This module provides functions for manipulating Item Metadata.

See the Metadata guide for details on the metadata structure.

core.metadata.get_all_namespaces(item_name)

This function will return a list of an Item’s namespaces.

Examples

# Get a list of an Item's namespaces
get_all_namespaces("Item_Name")
Parameters

  • item_name (str) – the name of the Item to retrieve the namespace names

  • for –

Returns

a list of strings representing the namespace names found for the specified Item

Return type

list

core.metadata.get_metadata(item_name, namespace)

This function will return the Metadata object associated with the specified Item.

Examples

# Get Metadata object from an Item's namespace
get_metadata("Item_Name", "Namespace_Name")
Parameters

  • item_name (str) – name of the Item

  • namespace (str) – name of the namespace

Returns

Metadata object containing the namespace value and configuration dictionary, but will be None if the namespace or the Item does not exist

Return type

Metadata object or None

core.metadata.set_metadata(item_name, namespace, configuration, value=None, overwrite=False)

This function creates or modifies Item metadata, optionally overwriting the existing data. If not overwriting, the provided keys and values will be overlaid on top of the existing keys and values.

Examples

# Add/change metadata in an Item's namespace (only overwrites existing keys and "value" is optional)
set_metadata("Item_Name", "Namespace_Name", {"Key_1": "key 1 value", "Key_2": 2, "Key_3": False}, "namespace_value")

# Overwrite metadata in an Item's namespace with new data
set_metadata("Item_Name", "Namespace_Name", {"Key_5": 5}, overwrite=True)
Parameters

  • item_name (str) – name of the Item

  • namespace (str) – name of the namespace

  • configuration (dict) – configuration dictionary to add to the namespace

  • value (str) – either the new namespace value or None

  • overwrite (bool) – if True, existing namespace data will be discarded

core.metadata.remove_metadata(item_name, namespace=None)

This function removes the Item metadata for the specified namepsace or for all namespaces.

Examples

# Remove a namespace from an Item
remove_metadata("Item_Name", "Namespace_Name")

# Remove ALL namespaces from an Item
remove_metadata("Item_Name")
Parameters

  • item_name (str) – name of the item

  • namespace (str) – name of the namespace or None, which will remove metadata in all namespaces for the specified Item

core.metadata.get_key_value(item_name, namespace, *args)

Ths function returns the configuration value for the specified key.

Examples

# Get key/value pair from Item's namespace "configuration"
get_key_value("Item_Name", "Namespace_Name", "Key", "Subkey", "Subsubkey")
Parameters

  • item_name (str) – name of the Item

  • namespace (str) – name of the namespace

  • key (str) – configuration key to return (multiple keys in descending branches can be used)

Returns

configuration key value or {} if the namespace, key or Item does not exist

Return type

string

core.metadata.set_key_value(item_name, namespace, *args)

This function creates or updates a key value in the specified namespace.

Examples

# Set key/value pair in Item's namespace "configuration"
set_key_value("Item_Name", "Namespace_Name", "Key", "Subkey", "Subsubkey", "Value")
Parameters

  • item_name (string) – name of the Item

  • namespace (string) – name of the namespace

  • key (string) – key to create or update (multiple keys in descending branches can be used)

  • value (string, decimal, boolean, dict or None) – value to set

core.metadata.remove_key_value(item_name, namespace, *args)

This function removes a key from a namespace’s configuration.

Examples

# Remove key/value pair from namespace ``configuration``
remove_key_value("Item_Name", "Namespace_Name", "Key", "Subkey", "Subsubkey")
Parameters

  • item_name (str) – name of the Item

  • namespace (str) – name of the namespace

  • key (str) – configuration key to remove (multiple keys in descending branches can be used)

core.metadata.get_value(item_name, namespace)

This function will return the Item metadata value for the specified namespace.

Examples

# Get Item's namespace "value"
get_value("Item_Name", "Namespace_Name")
Parameters

  • item_name (str) – name of the item

  • namespace (str) – name of the namespace

Returns

namespace value or None if the namespace or Item does not exist

Return type

string or None

core.metadata.set_value(item_name, namespace, value)

This function creates or updates the Item metadata value for the specified namespace.

Examples

# Set Item's namespace "value"
set_value("Item_Name", "Namespace_Name", "namespace value")
Parameters

  • item_name (str) – name of the Item

  • namespace (str) – name of the namespace

  • value (str) – new or updated namespace value