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.

The dataclasses describing click-extra's own `[tool.click-extra]` section:
{class}`ClickExtraConfig` and its `test-suite` and `prebake` sub-tables. They
are a concrete *instance* 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`. Only the `click-extra` CLI reads them, so
`import click_extra` does not load this module.

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,
)


[docs] @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}`~click_extra.config.builtin.TestSuiteConfig.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. """
[docs] @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."""
[docs] @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)."""