add pass_meta_key decorator

Author: davidism

CHANGES.rst

@@ -184,6 +184,9 @@ Unreleased
     return a path object instead of a string. :issue:`405`
 -   ``TypeError`` is raised when parameter with ``multiple=True`` or
     ``nargs > 1`` has non-iterable default. :issue:`1749`
+-   Add a ``pass_meta_key`` decorator for passing a key from
+    ``Context.meta``. This is useful for extensions using ``meta`` to
+    store information. :issue:`1739`
 
 
 Version 7.1.2

docs/api.rst

@@ -31,6 +31,9 @@ Decorators
 
 .. autofunction:: make_pass_decorator
 
+.. autofunction:: click.decorators.pass_meta_key
+
+
 Utilities
 ---------
 

src/click/decorators.py

@@ -1,4 +1,5 @@
 import inspect
+import typing as t
 from functools import update_wrapper
 
 from .core import Argument
@@ -8,6 +9,8 @@
 from .globals import get_current_context
 from .utils import echo
 
+if t.TYPE_CHECKING:
+    F = t.TypeVar("F", bound=t.Callable[..., t.Any])
 
 def pass_context(f):
     """Marks a callback as wanting to receive the current context
@@ -75,6 +78,39 @@ def new_func(*args, **kwargs):
     return decorator
 
 
+def pass_meta_key(
+    key: str, *, doc_description: t.Optional[str] = None
+) -> "t.Callable[[F], F]":
+    """Create a decorator that passes a key from
+    :attr:`click.Context.meta` as the first argument to the decorated
+    function.
+
+    :param key: Key in ``Context.meta`` to pass.
+    :param doc_description: Description of the object being passed,
+        inserted into the decorator's docstring. Defaults to "the 'key'
+        key from Context.meta".
+
+    .. versionadded:: 8.0
+    """
+
+    def decorator(f: "F") -> "F":
+        def new_func(*args, **kwargs):
+            ctx = get_current_context()
+            obj = ctx.meta[key]
+            return ctx.invoke(f, obj, *args, **kwargs)
+
+        return update_wrapper(t.cast("F", new_func), f)
+
+    if doc_description is None:
+        doc_description = f"the {key!r} key from :attr:`click.Context.meta`"
+
+    decorator.__doc__ = (
+        f"Decorator that passes {doc_description} as the first argument"
+        " to the decorated function."
+    )
+    return decorator
+
+
 def _make_command(f, name, attrs, cls):
     if isinstance(f, Command):
         raise TypeError("Attempted to convert a callback into a command twice.")

tests/test_context.py

@@ -4,6 +4,7 @@
 
 import click
 from click.core import ParameterSource
+from click.decorators import pass_meta_key
 
 
 def test_ensure_context_objects(runner):
@@ -151,6 +152,28 @@ def cli(ctx):
     runner.invoke(cli, [], catch_exceptions=False)
 
 
+def test_make_pass_meta_decorator(runner):
+    @click.group()
+    @click.pass_context
+    def cli(ctx):
+        ctx.meta["value"] = "good"
+
+    @cli.command()
+    @pass_meta_key("value")
+    def show(value):
+        return value
+
+    result = runner.invoke(cli, ["show"], standalone_mode=False)
+    assert result.return_value == "good"
+
+
+def test_make_pass_meta_decorator_doc():
+    pass_value = pass_meta_key("value")
+    assert "the 'value' key from :attr:`click.Context.meta`" in pass_value.__doc__
+    pass_value = pass_meta_key("value", doc_description="the test value")
+    assert "passes the test value" in pass_value.__doc__
+
+
 def test_context_pushing():
     rv = []