Merge pull request #2555 from sopel-irc/priority-literal

plugin: type-hint `priority` argument as `Literal[]`

sopel/plugin.py

@@ -15,6 +15,7 @@
 import re
 from typing import (
     Callable,
+    Literal,
     Optional,
     Pattern,
     Protocol,
@@ -1012,13 +1013,14 @@ def add_attribute(function):
     return add_attribute
 
 
-def priority(value: str) -> Callable:
+def priority(value: Literal['low', 'medium', 'high']) -> Callable:
     """Decorate a function to be executed with higher or lower priority.
 
-    :param value: one of ``high``, ``medium``, or ``low``; defaults to ``medium``
+    :param value: one of ``high``, ``medium``, or ``low``
 
-    The priority allows you to control the order of callable execution, if your
-    plugin needs it.
+    The priority allows you some control over the order of callable execution,
+    if your plugin needs it. If a callable does not specify its ``priority``,
+    Sopel assumes ``medium``.
     """
     def add_attribute(function):
         function.priority = value