Source code for click_extra.decorators

# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
#
# This program is Free Software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
"""Decorators for group, commands and options."""

from functools import wraps

import click
import cloup

from .colorize import ColorOption
from .commands import DEFAULT_HELP_NAMES, ExtraCommand, ExtraGroup, default_extra_params
from .config import ConfigOption, NoConfigOption
from .logging import VerboseOption, VerbosityOption
from .parameters import ShowParamsOption
from .table import TableFormatOption
from .telemetry import TelemetryOption
from .timer import TimerOption
from .version import ExtraVersionOption




def allow_missing_parenthesis(dec_factory):
    """Allow to use decorators with or without parenthesis.

    As proposed in
    `Cloup issue #127 <https://github.com/janluke/cloup/issues/127#issuecomment-1264704896>`_.
    """

    @wraps(dec_factory)
    def new_factory(*args, **kwargs):
        if args and callable(args[0]):
            return dec_factory(*args[1:], **kwargs)(args[0])
        return dec_factory(*args, **kwargs)

    return new_factory





def decorator_factory(dec, *new_args, **new_defaults):
    """Clone decorator with a set of new defaults.

    Used to create our own collection of decorators for our custom options, based on
    Cloup's.
    """

    @allow_missing_parenthesis
    def decorator(*args, **kwargs):
        """Returns a new decorator instantiated with custom defaults.

        These defaults values are merged with the user's own arguments.

        A special case is made for the ``params`` argument, to allow it to be callable.
        This limits the issue of the mutable options being shared between commands.

        This decorator can be used with or without arguments.
        """
        if not args:
            args = new_args

        # Use a copy of the defaults to avoid modifying the original dict.
        new_kwargs = new_defaults.copy()
        new_kwargs.update(kwargs)

        # If the params argument is a callable, we need to call it to get the actual
        # list of options.
        params_func = new_kwargs.get("params")
        if callable(params_func):
            new_kwargs["params"] = params_func()

        # Return the original decorator with the new defaults.
        return dec(*args, **new_kwargs)

    return decorator



# Redefine Cloup decorators to allow them to be used with or without parenthesis.
command = decorator_factory(dec=cloup.command)
group = decorator_factory(dec=cloup.group)

# Customize existing Click decorators with better default parameters.
help_option = decorator_factory(
    # XXX parameters are not named because of the way the default option names are
    # passed to HelpOption.
    # TODO: try the following instead once https://github.com/pallets/click/pull/2840
    # is merged:
    #   dec=click.decorators.help_option,
    #   param_decls=DEFAULT_HELP_NAMES,
    click.decorators.help_option,
    *DEFAULT_HELP_NAMES,
)

# Copy Click and Cloup decorators with better defaults, and prefix them with "extra_".
extra_command = decorator_factory(
    dec=cloup.command,
    cls=ExtraCommand,
    params=default_extra_params,
)
extra_group = decorator_factory(
    dec=cloup.group,
    cls=ExtraGroup,
    params=default_extra_params,
)
extra_version_option = decorator_factory(dec=cloup.option, cls=ExtraVersionOption)

# New option decorators provided by Click Extra.
color_option = decorator_factory(dec=cloup.option, cls=ColorOption)
config_option = decorator_factory(dec=cloup.option, cls=ConfigOption)
no_config_option = decorator_factory(dec=cloup.option, cls=NoConfigOption)
show_params_option = decorator_factory(dec=cloup.option, cls=ShowParamsOption)
table_format_option = decorator_factory(dec=cloup.option, cls=TableFormatOption)
telemetry_option = decorator_factory(dec=cloup.option, cls=TelemetryOption)
timer_option = decorator_factory(dec=cloup.option, cls=TimerOption)
verbose_option = decorator_factory(dec=cloup.option, cls=VerboseOption)
verbosity_option = decorator_factory(dec=cloup.option, cls=VerbosityOption)