Update docs and type hints.

Author: domdfcoding

consolekit/__init__.py

@@ -33,11 +33,11 @@
 
 # 3rd party
 import click
-from click.parser import split_opt
-from click.utils import make_str
 
 # this package
 from consolekit import input, terminal_colours, utils
+from consolekit.commands import SuggestionGroup
+from consolekit.options import _Option
 
 __author__: str = "Dominic Davis-Foster"
 __copyright__: str = "2020 Dominic Davis-Foster"
@@ -46,7 +46,6 @@
 __email__: str = "[email protected]"
 
 if not bool(getattr(sys, "ps1", sys.flags.interactive)):  # pragma: no cover
-
 	try:
 		# stdlib
 		import readline
@@ -66,36 +65,18 @@
 		]
 
 CONTEXT_SETTINGS = dict(help_option_names=["-h", "--help"], max_content_width=120)
-click_command = partial(click.command, context_settings=CONTEXT_SETTINGS)
-click_group = partial(click.group, context_settings=CONTEXT_SETTINGS, cls=SuggestionGroup)
-
-
-class _Option(click.Option):
-
-	def prompt_for_value(self, ctx):
-		"""
-		This is an alternative flow that can be activated in the full value processing if a value does not exist.
-
-		It will prompt the user until a valid value exists and then returns the processed value as result.
-		"""
-
-		# Calculate the default before prompting anything to be stable.
-		default = self.get_default(ctx)
-
-		# If this is a prompt for a flag we need to handle this
-		# differently.
-		if self.is_bool_flag:
-			return input.confirm(self.prompt, default)
 
-		return input.prompt(
-				self.prompt,
-				default=default,
-				type=self.type,
-				hide_input=self.hide_input,
-				show_choices=self.show_choices,
-				confirmation_prompt=self.confirmation_prompt,
-				value_proc=lambda x: self.process_value(ctx, x),
-				)
+click_command = partial(click.command, context_settings=CONTEXT_SETTINGS)
+"""
+Shortcut to :func:`click.command`, with the ``-h``/``--help`` option enabled and a max width of ``120``.
+"""
 
+click_group = partial(click.group, context_settings=CONTEXT_SETTINGS, cls=SuggestionGroup)
+"""
+Shortcut to :func:`click.group`, with the ``-h``/``--help`` option enabled and a max width of ``120``.
+"""
 
 option = partial(click.option, cls=_Option)
+"""
+Shortcut to :func:`click.option`, but using :func:`consolekit.input.confirm` when prompting for a boolean flag.
+"""

consolekit/input.py

@@ -125,27 +125,25 @@ def prompt(
 	"""
 	Prompts a user for input.
 
-	This is a convenience function that can be used to prompt a user for input later.
-
 	If the user aborts the input by sending an interrupt signal, this
 	function will catch it and raise a :exc:`click.exceptions.Abort` exception.
 
 	:param text: The text to show for the prompt.
 	:param default: The default value to use if no input happens.
-		If this is not given it will prompt until it's aborted.
+		If this is not given it will prompt until it is aborted.
 	:param hide_input: If :py:obj:`True` then the input value will be hidden.
 	:param confirmation_prompt: Asks for confirmation for the value.
-	:param type: The type to use to check the value against.
-	:param value_proc: If this parameter is provided it's a function that
+	:param type: The type to check the value against.
+	:param value_proc: If this parameter is provided it must be a function that
 		is invoked instead of the type conversion to convert a value.
 	:param prompt_suffix: A suffix that should be added to the prompt.
 	:param show_default: Shows or hides the default value in the prompt.
 	:param err: If :py:obj:`True` the file defaults to ``stderr`` instead of
-		``stdout``, the same as with echo.
-	:param show_choices: Show or hide choices if the passed type is a Choice.
-			For example if type is a Choice of either day or week,
-			``show_choices`` is :py:obj:`True` and text is ``'Group by'`` then the
-			prompt will be ``'Group by (day, week): '``.
+		``stdout``, the same as with :func:`click.echo`.
+	:param show_choices: Show or hide choices if the passed type is a :class:`click.Choice`.
+		For example, if the choice is either ``day`` or ``week``,
+		``show_choices`` is :py:obj:`True` and ``text`` is ``'Group by'`` then the
+		prompt will be ``'Group by (day, week): '``.
 	"""
 
 	result = None  # noqa
@@ -169,6 +167,7 @@ def prompt_func(text):
 	while True:
 		while True:
 			value = prompt_func(prompt)
+
 			if value:
 				break
 			elif default is not None:
@@ -177,19 +176,24 @@ def prompt_func(text):
 					value = default
 					break
 				return default
+
 		try:
 			result = value_proc(value)
 		except UsageError as e:
 			click.echo(f"Error: {e.message}", err=err)  # noqa: B306
 			continue
+
 		if not confirmation_prompt:
 			return result
+
 		while True:
 			value2 = prompt_func("Repeat for confirmation: ")
 			if value2:
 				break
+
 		if value == value2:
 			return result
+
 		click.echo("Error: the two entered values do not match", err=err)
 
 
@@ -245,9 +249,11 @@ def stderr_input(prompt: str = '', file: IO = sys.stdout) -> str:  # pragma: no
 	Read a string from standard input, but prompt to standard error.
 
 	The trailing newline is stripped.
-	If the user hits EOF (Unix: Ctl-D, Windows: Ctl-Z+Return), raise EOFError.
-	On Unix, GNU readline is used if enabled. The prompt string, if given,
-	is printed to stderr without a trailing newline before reading.
+	If the user hits EOF (Unix: :kbd:`Ctrl-D`, Windows: :kbd:`Ctrl-Z+Return`), raise :exc:`EOFError`.
+
+	On Unix, GNU readline is used if enabled.
+
+	The ``prompt`` string, if given, is printed to stderr without a trailing newline before reading.
 	"""
 
 	if file is sys.stdout:
@@ -341,7 +347,7 @@ def choice(
 	:param options:
 	:param text: The text to show for the prompt.
 	:param default: The index of the default value to use if no input happens.
-		If this is not given it will prompt until it's aborted.
+		If this is not given it will prompt until it is aborted.
 	:param prompt_suffix: A suffix that should be added to the prompt.
 	:param show_default: Shows or hides the default value in the prompt.
 	:param err: If :py:obj:`True` the file defaults to ``stderr`` instead of

consolekit/options.py

@@ -60,14 +60,15 @@
 
 # stdlib
 import inspect
-from typing import Any, Callable, List, Optional, cast
+from typing import Any, Callable, List, Optional, TypeVar, cast
 
 # 3rd party
 import click
-from click import Context, Option, OptionParser
+from click import Argument, Context, Option, OptionParser
 from click.decorators import _param_memo  # type: ignore
 
 # this package
+import consolekit.input
 from consolekit._types import Callback, _ConvertibleType
 
 __all__ = [
@@ -81,8 +82,11 @@
 		"auto_default_option",
 		]
 
+_A = TypeVar("_A", bound=click.Argument)
+_C = TypeVar("_C", bound=click.Command)
 
-def verbose_option(help_text: str = "Show verbose output.") -> Callable:
+
+def verbose_option(help_text: str = "Show verbose output.") -> Callable[..., click.Command]:
 	"""
 	Adds an option (via the parameter ``verbose``: :class:`int`) to enable verbose output.
 
@@ -101,15 +105,32 @@ def verbose_option(help_text: str = "Show verbose output.") -> Callable:
 			)
 
 
-def version_option(callback: Callable[[Context, Option, int], Any]) -> Callable:
+def version_option(callback: Callable[[Context, Option, int], Any]) -> Callable[..., click.Command]:
 	"""
 	Adds an option to show the version and exit.
 
 	The option can be provided multiple times by the user.
+	The count is stored as an integer and passed as the third parameter to the callback function.
 
 	.. versionadded:: 0.4.0
 
 	:param callback: The callback to invoke when the option is provided.
+
+	The callback function might look like:
+
+	.. code-block:: python
+
+		def version_callback(ctx: click.Context, param: click.Option, value: int):
+			if not value or ctx.resilient_parsing:
+				return
+
+			if value > 1:
+				click.echo(f"consolekit version {__version__}, Python {sys.version}")
+			else:
+				click.echo(f"consolekit version {__version__}")
+
+			ctx.exit()
+
 	"""
 
 	return click.option(
@@ -122,7 +143,7 @@ def version_option(callback: Callable[[Context, Option, int], Any]) -> Callable:
 			)
 
 
-def colour_option(help_text="Whether to use coloured output.") -> Callable:
+def colour_option(help_text="Whether to use coloured output.") -> Callable[..., click.Command]:
 	"""
 	Adds an option (via the parameter ``colour``: :class:`bool`) to enable verbose output.
 
@@ -138,7 +159,7 @@ def colour_option(help_text="Whether to use coloured output.") -> Callable:
 			)
 
 
-def force_option(help_text: str) -> Callable:
+def force_option(help_text: str) -> Callable[..., click.Command]:
 	"""
 	Decorator to add the ``-f / --force`` option to a click command.
 
@@ -150,10 +171,12 @@ def force_option(help_text: str) -> Callable:
 	return flag_option("-f", "--force", help=help_text)
 
 
-def no_pager_option(help_text="Disable the output pager.") -> Callable:
+def no_pager_option(help_text="Disable the output pager.") -> Callable[..., click.Command]:
 	"""
 	Decorator to add the ``--no-pager`` option to a click command.
 
+	The value is exposed via the parameter ``no_pager``: :class:`bool`.
+
 	.. versionadded:: 0.5.0
 
 	:param help_text: The help text for the option.
@@ -162,7 +185,7 @@ def no_pager_option(help_text="Disable the output pager.") -> Callable:
 	return flag_option("--no-pager", help=help_text)
 
 
-def flag_option(*args, default: Optional[bool] = False, **kwargs) -> Callable:
+def flag_option(*args, default: Optional[bool] = False, **kwargs) -> Callable[..., click.Command]:
 	r"""
 	Decorator to a flag option to a click command.
 
@@ -181,7 +204,7 @@ def flag_option(*args, default: Optional[bool] = False, **kwargs) -> Callable:
 			)
 
 
-def auto_default_option(*param_decls, **attrs) -> Callable:
+def auto_default_option(*param_decls, **attrs) -> Callable[..., click.Command]:
 	"""
 	Attaches an option to the command, with a default value determined from the decorated function's signature.
 
@@ -195,7 +218,7 @@ def auto_default_option(*param_decls, **attrs) -> Callable:
 	:param cls: the option class to instantiate. This defaults to :class:`click.Option`.
 	"""
 
-	def decorator(f):
+	def decorator(f: _C) -> _C:
 		option_attrs = attrs.copy()
 
 		if "help" in option_attrs:
@@ -234,15 +257,30 @@ class MultiValueOption(click.Option):
 		The later is converted into the former automatically if supported.
 	:param required: Controls whether this is optional.
 	:param default: The default value if omitted.
-		This can also be a callable, in which case it's invoked when the default is needed without any arguments.
+		This can also be a callable, in which case it is invoked when the default is needed without any arguments.
 	:param callback: A callback that should be executed after the parameter was matched.
 		This is called as ``fn(ctx, param, value)`` and needs to return the value.
 	:param metavar: How the value is represented in the help page.
 	:param expose_value: If :py:obj:`True` then the value is passed onwards to the command callback
-		and stored on the context, otherwise it's skipped.
+		and stored on the context, otherwise it is skipped.
 	:param is_eager: Eager values are processed before non eager ones.
 
 	.. versionadded:: 0.6.0
+
+	Example usage:
+
+	.. code-block:: python
+
+		@click.option(
+				"--select",
+				type=click.STRING,
+				help="The checks to enable",
+				cls=MultiValueOption,
+				)
+		@click_command()
+		def main(select: Iterable[str]):
+			select = list(select)
+
 	"""
 
 	def __init__(
@@ -312,3 +350,30 @@ def parser_process(value, state):
 				break
 
 		return retval
+
+
+class _Option(click.Option):
+
+	def prompt_for_value(self, ctx):
+		"""
+		This is an alternative flow that can be activated in the full value processing if a value does not exist.
+
+		It will prompt the user until a valid value exists and then returns the processed value as result.
+		"""
+
+		# Calculate the default before prompting anything to be stable.
+		default = self.get_default(ctx)
+
+		# If this is a prompt for a flag we need to handle this differently.
+		if self.is_bool_flag:
+			return consolekit.input.confirm(self.prompt, default)
+
+		return consolekit.input.prompt(
+				self.prompt,
+				default=default,
+				type=self.type,
+				hide_input=self.hide_input,
+				show_choices=self.show_choices,
+				confirmation_prompt=self.confirmation_prompt,
+				value_proc=lambda x: self.process_value(ctx, x),
+				)

consolekit/terminal_colours.py

@@ -123,13 +123,16 @@
 style_stack: List[str] = []
 
 
-def resolve_color_default(color: Optional[bool] = None) -> Optional[bool]:
+def resolve_color_default(color: ColourTrilean = None) -> ColourTrilean:
 	"""
 	Internal helper to get the default value of the color flag. If a
 	value is passed it's returned unchanged, otherwise it's looked up from
 	the current context.
 
-	If the environment variable ``PYCHARM_HOSTED`` is 1
+	If a value is passed it is returned unchanged,
+	otherwise it's looked up from the current context.
+
+	If the environment variable ``PYCHARM_HOSTED`` is ``1``
 	(which is the case if running in PyCharm)
 	the output will be coloured by default.
 

consolekit/utils.py

@@ -29,6 +29,8 @@
 # stdlib
 import difflib
 import os
+import sys
+from functools import lru_cache
 from itertools import cycle
 from types import ModuleType
 from typing import IO, List, Sequence
@@ -39,7 +41,7 @@
 from domdf_python_tools.stringlist import StringList
 
 # this package
-from consolekit.terminal_colours import Colour, Cursor, Fore
+from consolekit.terminal_colours import Colour, Cursor, Fore, Style, code_to_chars
 
 __all__ = [
 		"get_env_vars",