Rose Upgrade Macro API¶

Rose upgrade macros are used to upgrade application configurations between metadata versions. They are classes, very similar to transformer macros, but with a few differences:

An upgrade method instead of a transform method
An optional downgrade method, identical in API to the upgrade method, but intended for performing the reverse operation
A more helpful API via rose.upgrade.MacroUpgrade methods
BEFORE_TAG and AFTER_TAG attributes - the version of metadata they apply to (BEFORE_TAG) and the version they upgrade to (AFTER_TAG)

An example upgrade macro might look like this:

class Upgrade272to273(rose.upgrade.MacroUpgrade):

"""Upgrade from 27.2 to 27.3."""

BEFORE_TAG = "27.2"
AFTER_TAG = "27.3"

def upgrade(self, config, meta_config=None):
    self.add_setting(config, ["env", "NEW_VARIABLE"], "0")
    self.remove_setting(config, ["namelist:old_things", "OLD_VARIABLE"])
    return config, self.reports

Note

The class name is unimportant - the BEFORE_TAG and AFTER_TAG identify the macro.

Metadata versions are usually structured in a rose-meta/CATEGORY/VERSION/ hierarchy - where CATEGORY denotes the type or family of application (sometimes it is the command used), and VERSION is the particular version e.g. 27.2 or HEAD.

Upgrade macros live under the CATEGORY directory in a versions.py file - rose-meta/CATEGORY/versions.py.

Tip

If you have many upgrade macros, you may want to separate them into different modules in the same directory. You can then import from those in versions.py, so that they are still exposed in that module. You’ll need to make your directory a package by creating an __init__.py file, which should contain the line import versions. To avoid conflict with other CATEGORY upgrade modules (or other Python modules), please name these very modules carefully or use absolute or package level imports like this: from .versionXX_YY import FooBar.

Upgrade macros are subclasses of rose.upgrade.MacroUpgrade. They have all the functionality of the transformer macros.

class rose.upgrade.MacroUpgrade[source]¶

Class derived from MacroBase to aid upgrade functionality.

act_from_files(config, downgrade=False)[source]¶

Parse a change configuration into actions.

Searches for:

etc/VERSION/rose-macro-add.conf (settings to be added)
etc/VERSION/rose-macro-remove.conf (settings to be removed)

Where VERSION is equal to self.BEFORE_TAG.

If settings are defined in either file, and changes can be made, the self.reports will be updated automatically.

Note that act_from_files can be used in combination with other methods as part of the same upgrade.

Parameters:	config (rose.config.ConfigNode) – The application configuration. downgrade (bool) – True if downgrading.
Returns:	None

add_setting(config, keys, value=None, forced=False, state=None, comments=None, info=None)[source]¶

Add a setting to the configuration.

Parameters:

config (rose.config.ConfigNode) – The application configuration.
keys (list) – A list defining a hierarchy of node.value ‘keys’. A section will be a list of one keys, an option will have two.
value (string - optional) – String denoting the new setting value. Required for options but not for settings.
forced (bool - optional) – If True override value if the setting already exists.
state (str - optional) – The state of the new setting - should be one of the rose.config.ConfigNode states e.g. rose.config.ConfigNode.STATE_USER_IGNORED. Defaults to rose.config.ConfigNode.STATE_NORMAL.
comments (list - optional) – List of comment lines (strings) for the new setting or None.
info (string - optional) – A short string containing no new lines, describing the addition of the setting.

Returns:

None

change_setting_value(config, keys, value, forced=False, comments=None, info=None)[source]¶

Change a setting (option) value in the configuration.

Parameters:

config (rose.config.ConfigNode) – The application configuration.
keys (list) – A list defining a hierarchy of node.value ‘keys’. A section will be a list of one keys, an option will have two.
value (string) – The new value. Required for options, can be None for sections.
forced (bool) – Create the setting if it is not present in config.
comments (list - optional) – List of comment lines (strings) for the new setting or None.
info (string - optional) – A short string containing no new lines, describing the addition of the setting.

Returns:

None

enable_setting(config, keys, info=None)[source]¶

Enable a setting in the configuration.

Parameters:	config (rose.config.ConfigNode) – The application configuration. keys (list) – A list defining a hierarchy of node.value ‘keys’. A section will be a list of one keys, an option will have two. info (string - optional) – A short string containing no new lines, describing the addition of the setting.
Returns:	False - if the setting’s state is not changed else `None`.

get_setting_value(config, keys, no_ignore=False)[source]¶

Return the value of a setting or None if not set.

Parameters:	config (rose.config.ConfigNode) – The application configuration. keys (list) – A list defining a hierarchy of node.value ‘keys’. A section will be a list of one keys, an option will have two. no_ignore (bool - optional) – If `True` return `None` if the setting is ignored (else return the value).
Returns:	object - The setting value or `None` if not defined.

ignore_setting(config, keys, info=None, state='!')[source]¶

User-ignore a setting in the configuration.

Parameters:

config (rose.config.ConfigNode) – The application configuration.
keys (list) – A list defining a hierarchy of node.value ‘keys’. A section will be a list of one keys, an option will have two.
info (string - optional) – A short string containing no new lines, describing the addition of the setting.
state (string - optional) – A rose.config.ConfigNode state. STATE_USER_IGNORED by default.

Returns:

False - if the setting’s state is not changed else None.

remove_setting(config, keys, info=None)[source]¶

Remove a setting from the configuration.

Parameters:	config (rose.config.ConfigNode) – The application configuration. keys (list) – A list defining a hierarchy of node.value ‘keys’. A section will be a list of one keys, an option will have two. info (string - optional) – A short string containing no new lines, describing the addition of the setting.
Returns:	None

rename_setting(config, keys, new_keys, info=None)[source]¶

Rename a setting in the configuration.

Parameters:	config (rose.config.ConfigNode) – The application configuration. keys (list) – A list defining a hierarchy of node.value ‘keys’. A section will be a list of one keys, an option will have two. new_keys (list) – The new hierarchy of node.value ‘keys’. info (string - optional) – A short string containing no new lines, describing the addition of the setting.
Returns:	None