Source code for click_extra.config.builtin

# 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.
"""Click Extra's own built-in configuration schema and validators.

These are concrete *instances* of the configuration machinery, kept apart from
the reusable engine in :mod:`~click_extra.config.schema` and the option classes
in :mod:`~click_extra.config.option`:

- the dataclasses describing click-extra's own ``[tool.click-extra]`` section
  (:class:`ClickExtraConfig` and its ``test-suite`` and ``prebake`` sub-tables);
- :func:`_builtin_config_validators`, the validators click-extra registers on
  every :class:`~click_extra.config.option.ConfigOption`.

A downstream project defines its *own* equivalent of this module; click-extra
just happens to ship one, built on the same generic engine.
"""

from __future__ import annotations

from dataclasses import dataclass, field

from .schema import (
    CONFIG_PATH_METADATA_KEY,
    EXTENSION_METADATA_KEY,
    ConfigValidator,
)

THEMES_CONFIG_KEY: str = "themes"
"""Sub-key under ``[tool.<cli>]`` where user-defined themes live in config.

Used by :class:`~click_extra.config.option.ConfigOption` to find ``[tool.<cli>.themes.<name>]`` tables,
build them via :meth:`HelpTheme.from_dict
<click_extra.theme.HelpTheme.from_dict>`, and stash the result on
``ctx.meta[click_extra.context.THEME_OVERRIDES]``. The constant is the
single source of truth shared by ``_builtin_config_validators``,
``ConfigOption._apply_theme_overrides``, and
:func:`click_extra.theme.themes_from_config`.
"""




@dataclass
class TestSuiteConfig:
    """Config schema for a project's test suite, read from ``[tool.<cli>.test-suite]``.

    The ``test-suite`` CLI command resolves its cases from this config when no
    suite is given on the command line. Map it onto an app's config section with
    a field carrying ``metadata={CONFIG_PATH_METADATA_KEY: "test-suite"}``.
    """

    file: str = "./tests/cli-test-suite.toml"
    """Path to a test suite file, resolved relative to the project root.

    Its format is detected from the extension; the default is TOML, which (like
    JSON) parses with no optional dependency, unlike YAML and the others.
    """

    cases: list[dict] = field(
        default_factory=list,
        metadata={EXTENSION_METADATA_KEY: True},
    )
    """Test cases written natively in the config format, an alternative to a
    :attr:`file` suite, taking precedence over it when both are set.

    Each entry is a mapping of ``CLITestCase`` directive names, equivalent to one
    item of a suite list. In TOML this reads as a ``[[tool.<cli>.test-suite.cases]]``
    array of tables. Declared as an extension point so the configuration engine
    passes the raw mappings through unprocessed; the ``test-suite`` command turns
    them into :class:`~click_extra.test_suite.CLITestCase` instances.
    """

    timeout: int | None = None
    """Default timeout (seconds) for each case that does not set its own.

    ``None`` leaves cases unbounded unless ``--timeout`` is passed.
    """





@dataclass
class PrebakeConfig:
    """Config schema for the prebake commands, read from ``[tool.<cli>.prebake]``.

    Lets a project pin the target ``__init__.py`` once for its build pipeline,
    instead of passing ``--module`` to every ``click-extra prebake`` command.
    """

    module: str | None = None
    """Path to the ``__init__.py`` to pre-bake, resolved relative to the project
    root. Overrides the ``[project.scripts]`` auto-discovery; leave unset to keep
    it."""





@dataclass
class ClickExtraConfig:
    """Schema for the ``[tool.click-extra]`` configuration section.

    Wired as the ``config_schema`` of the top-level ``click-extra`` group, so
    every subcommand reads the same section and pulls its own sub-table through
    :func:`~click_extra.config.schema.get_tool_config`.
    """

    test_suite: TestSuiteConfig = field(
        default_factory=TestSuiteConfig,
        metadata={CONFIG_PATH_METADATA_KEY: "test-suite"},
    )
    """The ``[tool.click-extra.test-suite]`` sub-table (file/cases/timeout)."""

    prebake: PrebakeConfig = field(
        default_factory=PrebakeConfig,
        metadata={CONFIG_PATH_METADATA_KEY: "prebake"},
    )
    """The ``[tool.click-extra.prebake]`` sub-table (target module)."""



def _builtin_config_validators() -> tuple[ConfigValidator, ...]:
    """Return the validators click-extra registers on every :class:`~click_extra.config.option.ConfigOption`.

    Currently a single validator for ``[tool.<cli>.themes.<name>]`` tables.
    Lazy-imports :func:`~click_extra.theme.validate_themes_config` to avoid
    a load-time cycle: :mod:`click_extra.theme` is imported after
    :mod:`click_extra.config` from the package ``__init__``.
    """
    from ..theme import validate_themes_config

    return (
        ConfigValidator(
            extension_path=THEMES_CONFIG_KEY,
            validator=validate_themes_config,
            description=(
                "Validate user-defined and override themes declared under "
                "[tool.<cli>.themes.<name>]."
            ),
        ),
    )