plugin: add support for named plugin matchers

[bastimeyer]

This adds support for optionally named plugin matchers, e.g.:

@pluginmatcher(re.compile("http://foo"), name="foo")
@pluginmatcher(re.compile("http://bar"), name="bar")
class MyPlugin(Plugin):
    def _get_streams():
        if self.matches["foo"]:
            return self._get_streams_foo()
        else:
            return self._get_streams_bar()

Both Plugin.matchers and Plugin.matches can now be referenced by matcher index, like before, as well as matcher name, if it was set. Invalid values will raise an IndexError and KeyError respectively.

This is useful if multiple matchers are defined, so match results don't have to be referenced by matcher index, which depends on the (reverse) order of the pluginmatcher decorators.

[bastimeyer]

• https://deploy-preview-5103--streamlink.netlify.app/api.html#streamlink.plugin.Plugin.matchers
• https://deploy-preview-5103--streamlink.netlify.app/api.html#streamlink.plugin.Plugin.matches
• https://deploy-preview-5103--streamlink.netlify.app/api.html#streamlink.plugin.pluginmatcher
• https://deploy-preview-5103--streamlink.netlify.app/developing.html#adding-plugins

[mkbloke]

Just a thought on this: should/does there need to be a test for this in tests.plugins.PluginCanHandleUrl? should_match_matcher_name[]?

[bastimeyer]

True, I forgot about that. But thinking about it, it would result in lots of duplicates if we'd add should_match_matcher_name because of the regular should_match and should_match_groups tests. The groups tests is already a superset of the regular tests, so a third one doesn't really fit.

It would probably make more sense changing the str types of those two tests to Union[str,Tuple[str,str]], so we can have the optional name attribute included. Then the test methods need to check for that tuple type and compare the first item with the matcher's name attribute. Maybe also let them fail if there's a name but it's not tested.

I wanted to update the URL matcher tests at some point anyway, because error messages are currently not particularly nice due to how the parametrization is done. I also had the idea of making the URL matcher tests more "automagical" with automatic imports of the plugin classes (derived from the test module name, since the __plugin__ export is required), but that would result in a lack of plugin class references during static analysis, e.g. in IDEs or on GitHub's new code viewer, so jumping from the plugin definition to its tests would require finding it manually, which might be annoying.