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 metomi.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 metomi.rose.upgrade.MacroUpgrade. They have all the functionality of the transformer macros.

class metomi.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:
Returns:

None

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

Add a setting to the configuration.

Parameters:
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 (metomi.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 (str) – 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) – List of comment lines (strings) for the new setting or None.

  • info (str) – 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.

This will reset ignored and trigger ignored settings back to the default state.

Parameters:

  • config (metomi.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 (str) – 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 (metomi.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) – 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:
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 (metomi.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 (str) – 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 (metomi.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 (str) – A short string containing no new lines, describing the addition of the setting.

Returns:

None