Decorators¶

Click Extra’s decorators (@command, @group, @option, @argument, @version_option, the full @*_option family) are produced by a single factory that wraps cloup’s originals with three extra behaviors:

Subclass-enforced cls=: every @command / @group always yields an ExtraCommand / ExtraGroup (or a user-supplied subclass thereof), so click-extra’s machinery — config loading, theme registry, --show-params introspection — can’t be silently bypassed by passing a vanilla click.Command class.
Default-parameter injection: default_extra_params() (the global option set: --time, --config, --color, --theme, …) is passed as a callable, so each command gets its own freshly-instantiated option list rather than sharing the same mutable instances.
Optional-parenthesis decoration: @command and @command() are both legal call forms, matching the convention requested in Cloup #127.

If you only ever use the decorators click-extra ships out of the box, you don’t need to read further. This page is for downstream code that wants to wire its own @my_option decorator into the same factory.

`decorator_factory(dec, *new_args, **new_defaults)`¶

Clone a base decorator with a new set of default arguments, while validating that any user-supplied cls= is a subclass of the factory’s cls=. The result is itself a decorator that accepts the same arguments as dec and forwards them with the new defaults merged in.

The signature reads like this in click-extra’s own decorator file:

# click_extra/decorators.py
from .commands import ExtraCommand, ExtraGroup, default_extra_params

command = decorator_factory(
    dec=cloup.command,
    cls=ExtraCommand,
    params=default_extra_params,
)
group = decorator_factory(
    dec=cloup.group,
    cls=ExtraGroup,
    params=default_extra_params,
)

After that wiring, @command always produces an ExtraCommand, and @command(cls=MyExtraCommand) is accepted only if MyExtraCommand is a subclass of ExtraCommand. Anything else raises a TypeError with a full MRO listing of the offending class, so the caller sees why their override was rejected:

MyExtraCommand
TypeError("The 'cls' argument must be a subclass of ExtraCommand, got: click.core.Command, builtins.object")

Callable `params=`¶

When the factory is given params= as a callable (e.g. default_extra_params), it’s invoked once per decorated command so each command receives a fresh list of option instances. Without this indirection, two commands declared in the same module would share the same TimerOption instance, the same ConfigOption instance, and so on — which sounds harmless but produces subtle bugs (a callback registered by one command runs again when the second command exits, the parameter source map carries stale entries, …). Pass any zero-argument callable that returns a list of click.Parameter instances.

`allow_missing_parenthesis(dec_factory)`¶

A small wrapper that lets a decorator-factory be called either with parentheses (the standard @dec() form) or without (@dec). decorator_factory applies it automatically to every decorator it produces.

default
default
hi

The standard decorator suite¶

Every default option ships with a matching decorator built via decorator_factory:

Decorator	Wraps
`command`	`cloup.command(cls=ExtraCommand, params=default_extra_params)`
`group`	`cloup.group(cls=ExtraGroup, params=default_extra_params)`
`lazy_group`	`group(cls=LazyGroup)`
`option`	`cloup.option(cls=Option)`
`argument`	`cloup.argument(cls=Argument)`
`help_option`	`click.decorators.help_option(*DEFAULT_HELP_NAMES)`
`version_option`	`option(cls=ExtraVersionOption)`
`color_option`	`option(cls=ColorOption)`
`config_option`	`option(cls=ConfigOption)`
`no_config_option`	`option(cls=NoConfigOption)`
`validate_config_option`	`option(cls=ValidateConfigOption)`
`jobs_option`	`option(cls=JobsOption)`
`show_params_option`	`option(cls=ShowParamsOption)`
`table_format_option`	`option(cls=TableFormatOption)`
`telemetry_option`	`option(cls=TelemetryOption)`
`theme_option`	`option(cls=ThemeOption)`
`timer_option`	`option(cls=TimerOption)`
`verbose_option`	`option(cls=VerboseOption)`
`verbosity_option`	`option(cls=VerbosityOption)`

Every entry in this list is an allow_missing_parenthesis-wrapped factory, so @theme_option and @theme_option() are both legal, and @theme_option(default="light") overrides the default while keeping the click-extra subclass guarantee.

Rolling your own¶

To plug a custom ExtraOption subclass into the same machinery, instantiate decorator_factory(dec=option, cls=MyOption):

--retries: type=CounterOption, default=0
--workers: type=CounterOption, default=0

This pattern is how click-extra builds every *_option decorator listed above, and how downstream projects can extend the suite without re-implementing the subclass-validation / fresh-params machinery.

`click_extra.decorators` API¶

Decorators for group, commands and options.

click_extra.decorators.allow_missing_parenthesis(dec_factory)[source]¶

Allow to use decorators with or without parenthesis.

As proposed in Cloup issue #127.

click_extra.decorators.decorator_factory(dec, *new_args, **new_defaults)[source]¶

Clone decorator with a set of new defaults.

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

Attention

The cls argument passed to the factory is used as the reference class from which the produced decorator’s cls argument must inherit.

The idea is to ensure that, for example, the @command decorator re-implemented by Click Extra is always a subclass of ExtraCommand, even when the user overrides the cls argument. That way it can always rely on the additional properties and methods defined in the Click Extra framework, where we have extended Cloup and Click so much that we want to prevent surprising side effects.

click_extra.decorators.command(*args, **kwargs)¶

Returns a new decorator instantiated with custom defaults.

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