Validate workflow and task handler/mail event names

[MetRonnie]

Closes #2756

The names set in these settings are now validated:

• [scheduler][events]handler events
• [scheduler][events]mail events
• [runtime][X][events]handler events
• [runtime][X][events]mail events

Any invalid event names will raise an IllegalValueError or WorkflowConfigError.

If there are any outdated Cylc 7 [scheduler][events]handler/mail events they are automatically upgraded.

Check List

• I have read CONTRIBUTING.md and added my name as a Code Contributor.
• Contains logically grouped changes (else tidy your branch by rebase).
• Does not contain off-topic changes (use other PRs for other changes).
• No dependency changes
• Tests are included (or explain why tests are not needed).
• Changelog entry included if this is a change that can affect users
• Amend workflow events docs cylc-doc#840
• If this is a bug fix, PR should be raised against the relevant ?.?.x branch.

[oliver-sanders]

Closes #2756

Wow, 2018 issue!

Maybe a matter for another PR, but I think mail events aren't handled either:

$ cat global.cylc 
[scheduler]
  [[events]]
    mail events = elephant
$ CYLC_CONF_PATH=$PWD cylc config
[scheduler]
    [[events]]
        mail events = elephant

Both [scheduler][events]handler events and [runtime][X][events]handler events names are now validated.

Parsec has an options parameter which allows us to define valid options, e.g:

cylc-flow/cylc/flow/cfgspec/globalcfg.py

Lines 1005 to 1007 in 0711cc9

	'method', VDR.V_STRING, 'name',
	options=['name', 'address', 'hardwired'],
	desc=f'''

This provides validation, but also gets pulled through into the config when documented:

https://cylc.github.io/cylc-doc/stable/html/reference/config/global.html#global.cylc[scheduler][host%20self-identification]method

I don't know if this supports VDR.V_STRING_LIST configs like this one where multiple options can be picked, but it would be great if it did as we would have a single-source-of-truth and all legit values would get automatically pulled through into the docs.

Can you not just use the parsec.upgrader.deprecate logic

I think parsec only offers deprecate and obsolete functions. We don't want to deprecate / obsolete the handler events config, only particular values of it.

The deprecate thinggy accepts a function that can be used to upgrade values from one format to another which is what we want, but I think we would need a new in-situ upgrade function for parsec for this use case.

We could develop this functionality in parsec, it might come in handy again and the closer the functionality is to parsec, the closer it is to the docs. But at the end of the day, meh, whatever works!

[MetRonnie]

I have moved validation of workflow event names to parsec. However, this is not possible for task event names as any custom output is a valid task event name.

[oliver-sanders]

Even if we can't validate these at the parsec level, it would be great to document them there.

I think something like this will make list the options in the same format the parsec autodoc would:

With conf('task events', desc = f'''
    :Options: ``{"``, ``".join(STD_EVENTS)}}``, any custom event

    Configure the task event handling system.
''')

Punt to issue if short on time.

[oliver-sanders]

#6870

[oliver-sanders]

[minor] We could potentially make depr_options a dict of {deprecated_opt: replacement} and handle this in the parsec layer if we thought this functionality would be reused elsewhere.

[oliver-sanders]

Looks good, this is a huge improvement in the docs! Thanks for looking into the parsec changes.