Adding @optgoup.help_option decorator (#50)

Author: SpaceshipOperations

click_option_group/_core.py

@@ -3,9 +3,9 @@
 import collections
 import inspect
 import weakref
-from collections.abc import Callable
 from typing import (
     Any,
+    Callable,
     Dict,
     List,
     Mapping,

click_option_group/_decorators.py

@@ -1,8 +1,8 @@
 # -*- coding: utf-8 -*-
 
-from typing import Optional, NamedTuple, List, Tuple, Dict, Any, Type
+from typing import (Callable, Optional, NamedTuple, List,
+                    Tuple, Dict, Any, Type, TypeVar)
 
-import collections.abc as abc
 import collections
 import warnings
 import inspect
@@ -15,6 +15,11 @@
     raise_mixing_decorators_error,
 )
 
+T = TypeVar('T')
+F = TypeVar('F', bound=Callable)
+
+Decorator = Callable[[F], F]
+
 
 class OptionStackItem(NamedTuple):
     param_decls: Tuple[str, ...]
@@ -62,8 +67,8 @@ class _OptGroup:
     """
 
     def __init__(self) -> None:
-        self._decorating_state: Dict[abc.Callable, List[OptionStackItem]] = collections.defaultdict(list)
-        self._not_attached_options: Dict[abc.Callable, List[click.Option]] = collections.defaultdict(list)
+        self._decorating_state: Dict[Callable, List[OptionStackItem]] = collections.defaultdict(list)
+        self._not_attached_options: Dict[Callable, List[click.Option]] = collections.defaultdict(list)
         self._outer_frame_index = 1
 
     def __call__(self,
@@ -140,7 +145,7 @@ def decorator(func):
 
         return decorator
 
-    def option(self, *param_decls, **attrs):
+    def option(self, *param_decls, **attrs) -> Decorator:
         """The decorator adds a new option to the group
 
         The decorator is lazy. It adds option decls and attrs.
@@ -164,7 +169,30 @@ def decorator(func):
 
         return decorator
 
-    def _add_not_attached_option(self, func, param_decls):
+    def help_option(self, *param_decls, **attrs) -> Decorator:
+        """This decorator adds a help option to the group, which prints
+        the command's help text and exits.
+        """
+        if not param_decls:
+            param_decls = ('--help',)
+
+        attrs.setdefault('is_flag', True)
+        attrs.setdefault('is_eager', True)
+        attrs.setdefault('expose_value', False)
+        attrs.setdefault('help', 'Show this message and exit.')
+
+        if 'callback' not in attrs:
+            def callback(ctx, _, value):
+                if not value or ctx.resilient_parsing:
+                    return
+                click.echo(ctx.get_help(), color=ctx.color)
+                ctx.exit()
+
+            attrs['callback'] = callback
+
+        return self.option(*param_decls, **attrs)
+
+    def _add_not_attached_option(self, func, param_decls) -> None:
         click.option(
             *param_decls,
             all_not_attached_options=self._not_attached_options,
@@ -175,7 +203,7 @@ def _add_not_attached_option(self, func, param_decls):
         self._not_attached_options[callback].append(params[-1])
 
     @staticmethod
-    def _filter_not_attached(options):
+    def _filter_not_attached(options: List[T]) -> List[T]:
         return [opt for opt in options if not isinstance(opt, _NotAttachedOption)]
 
     @staticmethod

click_option_group/_helpers.py

@@ -1,18 +1,19 @@
 # -*- coding: utf-8 -*-
 
-from typing import List, Tuple
+from typing import Callable, Tuple, List, TypeVar, NoReturn
 
-import collections.abc as abc
 import random
 import string
 
 import click
 
 
+F = TypeVar('F', bound=Callable)
+
 FAKE_OPT_NAME_LEN = 30
 
 
-def get_callback_and_params(func) -> Tuple[abc.Callable, List[click.Option]]:
+def get_callback_and_params(func) -> Tuple[Callable, List[click.Option]]:
     """Returns callback function and its parameters list
 
     :param func: decorated function or click Command
@@ -28,11 +29,11 @@ def get_callback_and_params(func) -> Tuple[abc.Callable, List[click.Option]]:
     return func, params
 
 
-def get_fake_option_name(name_len: int = FAKE_OPT_NAME_LEN, prefix: str = 'fake'):
+def get_fake_option_name(name_len: int = FAKE_OPT_NAME_LEN, prefix: str = 'fake') -> str:
     return f'--{prefix}-' + ''.join(random.choices(string.ascii_lowercase, k=name_len))
 
 
-def raise_mixing_decorators_error(wrong_option: click.Option, callback: abc.Callable):
+def raise_mixing_decorators_error(wrong_option: click.Option, callback: Callable) -> NoReturn:
     error_hint = wrong_option.opts or [wrong_option.name]
 
     raise TypeError((
@@ -41,6 +42,6 @@ def raise_mixing_decorators_error(wrong_option: click.Option, callback: abc.Call
     ))
 
 
-def resolve_wrappers(f):
+def resolve_wrappers(f: F) -> F:
     """Get the underlying function behind any level of function wrappers."""
     return resolve_wrappers(f.__wrapped__) if hasattr(f, "__wrapped__") else f

tests/test_click_option_group.py

@@ -733,6 +733,25 @@ def cli(foo, bar):
     assert "bar" not in result.output
 
 
+def test_help_option(runner):
+    @click.command()
+    @optgroup('Help Options')
+    @optgroup.help_option('-h', '--help')
+    def cli() -> None:
+        click.echo('Running command.')
+
+    result = runner.invoke(cli)
+    assert not result.exception
+    assert 'Running command.' in result.output
+    assert 'Usage:' not in result.output
+
+    result = runner.invoke(cli, ['-h'])
+    assert not result.exception
+    assert 'Running command.' not in result.output
+    assert 'Usage:' in result.output
+    assert '-h, --help' in result.output
+
+
 def test_wrapped_functions(runner):
     def make_z():
         """A unified option interface for making a `z`."""