metadata.py
Alongside items.py
you may create another file called metadata.py
. It can be used to do advanced processing of the metadata you configured for your nodes and groups. Specifically, it allows each bundle to modify metadata before items.py
is evaluated.
This is accomplished through metadata processors. Metadata processors are functions that take the metadata dictionary generated so far as their single argument. You must then return a dictionary with any modifications you need to make plus at least one of several options:
@metadata_processor
def my_metadata_processor(metadata):
metadata["foo"] = node.name
return metadata, DONE
You must always return the modified metadata dictionary as the first element. After that, there are a few options you can return. Every metadata processor from every bundle is called repeatedly with the latest metadata dictionary until it indicates that it is done by returning the DONE
option or until all remaining metadata processors return RUN_ME_AGAIN
. You must always return one of DONE
or RUN_ME_AGAIN
. Use the latter if your metadata processor depends on metadata that is generated by another metadata processor (which may be called after yours). Here is another example:
@metadata_processor
def first_metadata_processor(metadata):
metadata["foo"] = node.name
return metadata, DONE
@metadata_processor
def second_metadata_processor(metadata):
if "foo" in metadata:
metadata["bar"] = metadata["foo"]
return metadata, DONE
else:
return metadata, RUN_ME_AGAIN
In this example, "bar"
can only be set once "foo"
is available and thus the second_metadata_processor
has to wait and request to RUN_ME_AGAIN
until first_metadata_processor
ran. This is necessary because the running order of metadata processors is undefined.
other_node.partial_metadata
instead of other_node.metadata
. For the same reason, always use the metadata
parameter to access the current node's metadata, never node.metadata
.Available options
Option | Description |
---|---|
DONE | Indicates that this metadata processor has done all it can and need not be called again. Return this whenever possible. |
RUN_ME_AGAIN | Indicates that this metadata processor is still waiting for metadata from another metadata processor to become available. |
DEFAULTS | The returned metadata dictionary will only be used to provide default values. The actual metadata generated so far will be recursively merged into the returned dict. |
OVERWRITE | The returned metadata dictionary will be recursively merged into the actual metadata generated so far (inverse of DEFAULTS ). |
Here is an example of how to use DEFAULTS
:
@metadata_processor
def my_metadata_processor(metadata):
return {
"foo": {
"bar": 47,
},
}, DONE, DEFAULTS
This means node.metadata["foo"]["bar"]
will be 47 by default, but can also be overridden in static metadata at the node/group level.
repo
, node
, metadata_processor
and all the options in metadata.py
without importing them.