# 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.
"""Resolution of the reserved subcommand keys a configuration file can declare.
`_default_subcommands` and `_prepend_subcommands` are read from the loaded
configuration and turned into subcommand names, which
{meth}`~click_extra.config.option.ConfigOption.handle_parse_result` splices into
the residual arguments Click dispatches on.
```{note}
The keys are honored by whichever group carries the `--config` option, not only
by click-extra's own {class}`~click_extra.commands.Group`. Injection happens at
parse time, from the option itself, because a plain `click.Group` offers
click-extra no other hook: a third-party framework building its group on
`click.Group` still gets the feature.
```
```{caution}
The option never sees two cases. Click prints the `no_args_is_help` screen of a
bare invocation before it processes any option, and a group reached through an
ancestor's `--config` carries no option of its own. The first
{class}`~click_extra.config.option.ConfigOption` a process builds puts
{func}`_group_parse_args` in place of `click.Group.parse_args` for the whole
process to cover both, whatever class the group is built on: see its
documentation.
```
"""
from __future__ import annotations
import logging
from threading import Lock
import click
from .. import context
from .schema import DEFAULT_SUBCOMMANDS_KEY, PREPEND_SUBCOMMANDS_KEY
TYPE_CHECKING = False
if TYPE_CHECKING:
from collections.abc import Callable
from typing import Any
from .option import ConfigOption
logger = logging.getLogger(__name__)
def _descend_to_group_config(ctx: click.Context) -> dict[str, Any] | None:
"""Return the loaded config section for the current group's command path.
Reads the full configuration document from `ctx.meta`, descends into the
root command's section, then walks from the root context down to `ctx`
following each group name. Returns the resolved mapping, or `None` when no
configuration was loaded or any segment along the path is missing.
"""
full_config = context.get(ctx, context.CONF_FULL)
if not full_config:
return None
root_ctx = ctx.find_root()
config_branch = full_config.get(root_ctx.command.name)
if not isinstance(config_branch, dict):
return None
# Walk from root context down to the current group.
path: list[str] = []
current: click.Context | None = ctx
while current is not None and current is not root_ctx:
if current.command.name is not None:
path.append(current.command.name)
current = current.parent
path.reverse()
for segment in path:
config_branch = config_branch.get(segment)
if not isinstance(config_branch, dict):
return None
return config_branch
def _dedupe_subcommands(raw: list[str], key: str) -> list[str]:
"""Drop duplicate subcommand names, keeping the first occurrence.
Warns when duplicates are dropped, naming the configuration `key` they
came from.
"""
deduped = list(dict.fromkeys(raw))
if len(deduped) < len(raw):
logger.warning(
f"Duplicate entries in {key}: {raw!r}. "
f"Keeping first occurrences: {deduped!r}."
)
return deduped
def _read_subcommand_list(
ctx: click.Context,
group: click.Group,
key: str,
) -> list[str] | None:
"""Read, validate, dedupe, and existence-check a subcommand-list config key.
Returns the deduplicated list of subcommand names declared under `key`
in the loaded configuration, or `None` when the key is absent or empty.
Shared by {func}`resolve_default_subcommands` and
{func}`resolve_prepend_subcommands`; each caller layers on its own chain-mode
rule (the only behavior that differs between the two keys).
:raises click.UsageError: when the value is not a list of strings, or when
a listed subcommand does not exist in `group`.
"""
config_branch = _descend_to_group_config(ctx)
if config_branch is None:
return None
raw = config_branch.get(key)
if raw is None:
return None
# Validate type.
if not isinstance(raw, list) or not all(isinstance(s, str) for s in raw):
raise click.UsageError(f"{key} must be a list of strings, got {raw!r}.")
if not raw:
return None
raw = _dedupe_subcommands(raw, key)
# Validate that all subcommands exist.
for name in raw:
if group.get_command(ctx, name) is None:
raise click.UsageError(
f"Subcommand {name!r} from {key} not found in group {group.name!r}."
)
return raw
[docs]
def resolve_default_subcommands(
ctx: click.Context,
group: click.Group,
) -> list[str] | None:
"""Read and validate `_default_subcommands` from the loaded configuration."""
raw = _read_subcommand_list(ctx, group, DEFAULT_SUBCOMMANDS_KEY)
if raw is None:
return None
# Non-chained groups can only have one default subcommand.
if not group.chain and len(raw) > 1:
raise click.UsageError(
f"Non-chained group {group.name!r} can have at most 1 default "
f"subcommand, got {len(raw)}: {raw!r}."
)
return raw
[docs]
def resolve_prepend_subcommands(
ctx: click.Context,
group: click.Group,
) -> list[str] | None:
"""Read and validate `_prepend_subcommands` from the loaded configuration."""
raw = _read_subcommand_list(ctx, group, PREPEND_SUBCOMMANDS_KEY)
if raw is None:
return None
# Prepend subcommands only work with chained groups.
if not group.chain:
raise click.UsageError(
f"{PREPEND_SUBCOMMANDS_KEY} requires chain=True on group {group.name!r}."
)
return raw
[docs]
def inject_reserved_subcommands(ctx: click.Context, args: list[str]) -> list[str]:
"""Return `args` with the reserved subcommand keys applied.
`_default_subcommands` fills in for an invocation that names no subcommand.
The command line always wins: when `args` already carries one, the
configured defaults are logged and dropped.
`_prepend_subcommands` goes in front of whatever remains, whether the
subcommand came from the command line or from the defaults. It requires a
`chain=True` group.
Applies at most once per group, tracked in
{data}`~click_extra.context.SUBCOMMANDS_APPLIED`. A group can be visited
twice, by the pre-pass of a bare invocation and then by the regular
parameter loop, and prepending the same subcommand on both passes would run
it twice.
:raises click.UsageError: on an invalid value, an unknown subcommand, or a
chain-mode violation.
"""
group = ctx.command
if not isinstance(group, click.Group):
return args
applied = context.setdefault(ctx, context.SUBCOMMANDS_APPLIED, set)
if ctx.command_path in applied:
return args
applied.add(ctx.command_path)
default_subcmds = resolve_default_subcommands(ctx, group)
if default_subcmds is not None:
if args:
logger.debug(
f"CLI subcommands provided; ignoring {DEFAULT_SUBCOMMANDS_KEY}"
f" config: {default_subcmds!r}."
)
else:
args = list(default_subcmds)
prepend_subcmds = resolve_prepend_subcommands(ctx, group)
if prepend_subcmds is not None:
logger.info(
f"Prepending {PREPEND_SUBCOMMANDS_KEY} config: {prepend_subcmds!r}."
)
args = list(prepend_subcmds) + args
return args
_GROUP_PATCH_LOCK = Lock()
"""Serializes {func}`_patch_group_parse_args`, which two threads can enter at once
when each builds a `ConfigOption`."""
_click_group_parse_args: (
Callable[[click.Group, click.Context, list[str]], list[str]] | None
) = None
"""`click.Group.parse_args` as {func}`_patch_group_parse_args` found it.
`None` while Click is untouched, which is until the first `ConfigOption` is built.
"""
_config_option_class: type[ConfigOption] | None = None
"""The `ConfigOption` class {func}`_group_parse_args` looks for in a group.
Handed over by {func}`_patch_group_parse_args`, so this module needs no import of
{mod}`~click_extra.config.option`, which imports it.
"""
def _group_parse_args(
self: click.Group,
ctx: click.Context,
args: list[str],
) -> list[str]:
"""Stand in for `click.Group.parse_args`, applying the reserved subcommand keys.
{meth}`~click_extra.config.option.ConfigOption.handle_parse_result` splices the
subcommands named by the configuration into the arguments of the group carrying
the option. Two cases never reach it, and this function covers both:
- A bare invocation. Click raises its `no_args_is_help` screen before it runs
any parameter, so the group's `ConfigOption` is asked for the names ahead of
that check. They go to Click in place of the empty command line, and an empty
answer leaves the help screen in place.
- A group reached through an ancestor's `--config`. It holds no option of its
own, so its `[parent.group]` section is applied here. The document is already
loaded by the time a subgroup is parsed.
Every other call goes to Click unchanged. That covers each group of a CLI
carrying no `ConfigOption`, since nothing loads a document for it.
"""
if not ctx.resilient_parsing:
bare = not args and self.no_args_is_help
loaded = bool(context.get(ctx, context.CONF_FULL))
if bare or loaded:
# The patch hands the class over before it installs this function.
assert _config_option_class is not None
config_option = next(
(
p
for p in self.get_params(ctx)
if isinstance(p, _config_option_class)
),
None,
)
if config_option is None and loaded:
# Injecting before delegating also settles no_args_is_help, since
# an injected subcommand makes the invocation non-empty.
args = inject_reserved_subcommands(ctx, args)
elif config_option is not None and bare:
args = config_option._resolve_subcommands_eagerly(ctx)
# The patch sets the original before it installs this function.
assert _click_group_parse_args is not None
return _click_group_parse_args(self, ctx, args)
def _patch_group_parse_args(config_option_class: type[ConfigOption]) -> None:
"""Put {func}`_group_parse_args` in place of `click.Group.parse_args`, once.
Runs as each `ConfigOption` is built, so a process declaring no `--config`
leaves Click untouched. The replacement then stays for the life of the process,
and reaches every `click.Group` in it, whichever library built the group.
A group class click-extra does not own offers no other way in. Click calls
nothing on a parameter ahead of the no-args check, and a subgroup holds no
parameter of click-extra's.
:param config_option_class: the class whose instances
{func}`_group_parse_args` looks for among the parameters of a group.
"""
global _click_group_parse_args, _config_option_class
with _GROUP_PATCH_LOCK:
if _click_group_parse_args is None:
_config_option_class = config_option_class
_click_group_parse_args = click.Group.parse_args
click.Group.parse_args = _group_parse_args # type: ignore[method-assign]