geosoft.gxpy.metadata submodule¶
Geosoft metadata.
Classes: |
|
---|
See also
Note
Regression tests provide usage examples: metadata tests
New in version 9.3.
-
META_INVALID
= -1¶
-
META_ROOT_NODE
= -100¶
-
META_TYPE_ATTRIBUTE
= 1¶
-
META_TYPE_NODE
= 0¶
-
class
Metadata
(gxmeta=None)¶ Bases:
object
Simple interface to work with Geosoft metadata objects
geosoft.gxapi.GXMETA
.Parameters: gxmeta – geosoft.gxapi.GXMETA
instance, or None (default) in which case an empty metadata instance is created.Geosoft metadata objects contain metadata organized as a tree of information, with each node of the tree containing 0 or more attributes and 0 or more nested nodes.
One can think of a metadata structure as a dictionary in which items that reference a dictionary are nodes, that in turn can hold other nodes, and each node can also hold attributes. We refer to this as a “nested dictionary”.
The
meta_dict()
method will return the metadata content as a nested dictionary, and theupdate_dict()
method will add a dictionary to the metadata instance.While geosoft metadata can contain custom typed attributes and indeed any Geosoft object, this simple interface currently supports only Python types int, float, string and Python structures like tuple, arrays and dictionaries.
Nodes can identified by a string in the form:
/node/[...]/
. For example'/geosoft/data/'
is equivalent to a dictionary structure{'geosoft': 'data': {}}
.Attributes are identified by a string in the form:
/node/[...]/attribute
. For example, an attribute'geosoft/data/keywords'
with keyword content ‘mag’ and ‘Red Lake’ can be represented in a Python dictionary as{'geosoft': 'data': {'keywords': ('mag', 'Red Lake')}
.New in version 9.3.
-
attribute_token
(attr_name)¶ Returns the metadata token (integer) of an attribute.
Parameters: attr_name – name of the attribute (eg. 'my_metadata/parameters/frequency'
)Returns: metadata token number or META_INVALID
if the attribute does not exist.
-
get_attribute
(attr_name)¶ Retrieve an attribute setting.
Parameters: attr_name – attribute name (eg. ‘/my_metadata/parameters/frequency’) Returns: attribute setting New in version 9.3.
-
gxmeta
¶ The
geosoft.gxapi.GXMETA
instance handle.New in version 9.3.
-
has_attribute
(attribute_name)¶ Returns
True
if this attribute exists in the metadata.Parameters: attribute_name – name of a attribute (eg. 'geosoft/data/keywords'
)New in version 9.3.
-
has_node
(node_name)¶ Returns
True
if this node exists in the metadata.Parameters: node_name – name of a node (eg. 'geosoft/data/'
)New in version 9.3.
-
meta_dict
()¶ Metadata content as a nested dictionary.
Attributes will be normal Python objects where the attribute type is supported by Python. This includes basic types (like int and float), lists/tuples, and Python dictionaries, which are nodes in the metadata structucture.
Geosoft objects in an attribute, will appear only as a descriptive text string.
Returns: nested dictionary structure of metadata New in version 9.3.
-
meta_type
(meta_node)¶ Return if the content of this node is a node (
META_TYPE_NODE
) or an attribute (META_TYPE_ATTRIBUTE
).Returns
META_INVALID
if neither.Parameters: meta_node – metadata node as a string. e.g. ‘geosoft/dataset/title’ New in version 9.3.
-
node_attribute_token
(attr_name)¶ returns the node and attribute number of an attribute.
Parameters: attr_name – attribute name Returns: (node token, attribute token) New in version 9.3.
-
node_token
(node_name)¶ Returns the metadata token (integer) of a node. The node is created if it does not exist.
Parameters: node_name – name of the node (eg. 'my_metadata/parameters'
)Returns: metadata token number
-
set_attribute
(attr_name, value)¶ Set an attribute to a value. The attribute is created if it does not exist.
Parameters: - attr_name – attribute name (eg.
'/my_metadata/parameters/frequency'
) - value – int, float, string or a Python structure such as tuple, array or dict.
New in version 9.3.
- attr_name – attribute name (eg.
-
update_dict
(metadict, trunk_node='')¶ Update the metadata from the content of a dictionary.
Parameters: - metadict – dictionary of metadata to add/update
- trunk_node – trunk to which to add this meta, default is ‘’ which adds from the root.
New in version 9.3.1.
-
-
exception
MetadataException
(message)¶ Bases:
geosoft.GXRuntimeError
Exceptions from
geosoft.gxpy.metadata
.New in version 9.3.
-
get_node_from_meta_dict
(meta_node, meta_dict)¶ Get the node content from a metadata dictionary.
Parameters: - meta_node – node wanted, ‘/’ delimited. e.g. ‘geosoft/dataset/title’
- meta_dict – metadata dictionary (from
Metadata.meta_dict
)
Returns: node content, or None if not found
New in version 9.3.1.
-
set_node_in_meta_dict
(meta_node, meta_dict, content, replace=False)¶ Set a node in a metadata dictionary. Tree nodes are added if absent.
Parameters: - meta_node – node to set, ‘/’ delimited. e.g. ‘geosoft/dataset/title’
- meta_dict – meta dictionary (from
Metadata.meta_dict
) - content – content to set to the node
- replace – True to replace nodes that are attributes. The default is False, in which case an error is raised if a node in the tree is an attribute.
New in version 9.3.1.