antsibull-nox 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

antsibull_nox/config.py

@@ -0,0 +1,378 @@
+# Author: Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
+# https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025, Ansible Project
+
+"""
+Config file schema.
+"""
+
+from __future__ import annotations
+
+import os
+import typing as t
+
+import pydantic as p
+
+from ._pydantic import forbid_extras, get_formatted_error_messages
+from .ansible import AnsibleCoreVersion
+from .utils import Version
+
+try:
+    from tomllib import load as _load_toml
+except ImportError:
+    from tomli import load as _load_toml  # type: ignore
+
+
+CONFIG_FILENAME = "antsibull-nox.toml"
+
+
+def _parse_version(value: t.Any) -> Version:
+    if isinstance(value, Version):
+        return value
+    if isinstance(value, str) and "." in value:
+        return Version.parse(value)
+    raise ValueError("Must be version string")
+
+
+def _parse_ansible_core_version(value: t.Any) -> AnsibleCoreVersion:
+    if isinstance(value, Version):
+        return value
+    if isinstance(value, str):
+        if value == "devel":
+            return "devel"
+        if value == "milestone":
+            return "milestone"
+        if "." in value:
+            return Version.parse(value)
+    raise ValueError("Must be ansible-core version string")
+
+
+def _validate_collection_name(value: str) -> str:
+    parts = value.split(".")
+    if len(parts) != 2:
+        raise ValueError("Collection name must be of the form '<namespace>.<name>'")
+    if not parts[0].isidentifier():
+        raise ValueError("Collection namespace must be Python identifier")
+    if not parts[1].isidentifier():
+        raise ValueError("Collection name must be Python identifier")
+    return value
+
+
+CollectionName = t.Annotated[str, p.AfterValidator(_validate_collection_name)]
+PVersion = t.Annotated[Version, p.BeforeValidator(_parse_version)]
+PAnsibleCoreVersion = t.Annotated[
+    AnsibleCoreVersion, p.BeforeValidator(_parse_ansible_core_version)
+]
+
+
+class _BaseModel(p.BaseModel):
+    model_config = p.ConfigDict(frozen=True, extra="allow", validate_default=True)
+
+
+class SessionLint(_BaseModel):
+    """
+    Lint session config.
+    """
+
+    default: bool = True
+    extra_code_files: list[str] = []
+
+    # isort:
+    run_isort: bool = True
+    isort_config: t.Optional[p.FilePath] = None
+    isort_package: str = "isort"
+
+    # black:
+    run_black: bool = True
+    run_black_modules: t.Optional[bool] = None
+    black_config: t.Optional[p.FilePath] = None
+    black_package: str = "black"
+
+    # flake8:
+    run_flake8: bool = True
+    flake8_config: t.Optional[p.FilePath] = None
+    flake8_package: str = "flake8"
+
+    # pylint:
+    run_pylint: bool = True
+    pylint_rcfile: t.Optional[p.FilePath] = None
+    pylint_modules_rcfile: t.Optional[p.FilePath] = None
+    pylint_package: str = "pylint"
+    pylint_ansible_core_package: t.Optional[str] = "ansible-core"
+    pylint_extra_deps: list[str] = []
+
+    # yamllint:
+    run_yamllint: bool = True
+    yamllint_config: t.Optional[p.FilePath] = None
+    yamllint_config_plugins: t.Optional[p.FilePath] = None
+    yamllint_config_plugins_examples: t.Optional[p.FilePath] = None
+    yamllint_package: str = "yamllint"
+
+    # mypy:
+    run_mypy: bool = True
+    mypy_config: t.Optional[p.FilePath] = None
+    mypy_package: str = "mypy"
+    mypy_ansible_core_package: t.Optional[str] = "ansible-core"
+    mypy_extra_deps: list[str] = []
+
+    # antsibull-nox config lint:
+    run_antsibullnox_config_lint: bool = True
+
+
+class SessionDocsCheck(_BaseModel):
+    """
+    Docs check session config.
+    """
+
+    default: bool = True
+
+    antsibull_docs_package: str = "antsibull-docs"
+    ansible_core_package: str = "ansible-core"
+    validate_collection_refs: t.Optional[t.Literal["self", "dependent", "all"]] = None
+    extra_collections: list[CollectionName] = []
+
+
+class SessionLicenseCheck(_BaseModel):
+    """
+    License check session config.
+    """
+
+    default: bool = True
+
+    run_reuse: bool = True
+    reuse_package: str = "reuse"
+    run_license_check: bool = True
+    license_check_extra_ignore_paths: list[str] = []
+
+
+class ActionGroup(_BaseModel):
+    """
+    Information about an action group.
+    """
+
+    # Name of the action group.
+    name: str
+    # Regex pattern to match modules that could belong to this action group.
+    pattern: str
+    # Doc fragment that members of the action group must have, but no other module
+    # must have
+    doc_fragment: str
+    # Exclusion list of modules that match the regex, but should not be part of the
+    # action group. All other modules matching the regex are assumed to be part of
+    # the action group.
+    exclusions: list[str] = []
+
+
+class SessionExtraChecks(_BaseModel):
+    """
+    Extra checks session config.
+    """
+
+    default: bool = True
+
+    # no-unwanted-files:
+    run_no_unwanted_files: bool = True
+    no_unwanted_files_module_extensions: list[str] = [".cs", ".ps1", ".psm1", ".py"]
+    no_unwanted_files_other_extensions: list[str] = [".py", ".pyi"]
+    no_unwanted_files_yaml_extensions: list[str] = [".yml", ".yaml"]
+    no_unwanted_files_skip_paths: list[str] = []
+    no_unwanted_files_skip_directories: t.Optional[list[str]] = []
+    no_unwanted_files_yaml_directories: t.Optional[list[str]] = [
+        "plugins/test/",
+        "plugins/filter/",
+    ]
+    no_unwanted_files_allow_symlinks: bool = False
+
+    # action-groups:
+    run_action_groups: bool = False
+    action_groups_config: list[ActionGroup] = []
+
+
+class SessionBuildImportCheck(_BaseModel):
+    """
+    Collection build and Galaxy import session config.
+    """
+
+    default: bool = True
+
+    ansible_core_package: str = "ansible-core"
+    run_galaxy_importer: bool = True
+    galaxy_importer_package: str = "galaxy-importer"
+    # https://github.com/ansible/galaxy-importer#configuration
+    galaxy_importer_config_path: t.Optional[p.FilePath] = None
+    galaxy_importer_always_show_logs: bool = False
+
+
+class DevelLikeBranch(_BaseModel):
+    """
+    A Git repository + branch for a devel-like branch of ansible-core.
+    """
+
+    repository: t.Optional[str] = None
+    branch: str
+
+    @p.model_validator(mode="before")
+    @classmethod
+    def _pre_validate(cls, values: t.Any) -> t.Any:
+        if isinstance(values, str):
+            return {"branch": values}
+        if (
+            isinstance(values, list)
+            and len(values) == 2
+            and all(isinstance(v, str) for v in values)
+        ):
+            return {"repository": values[0], "branch": values[1]}
+        return values
+
+
+class SessionAnsibleTestSanity(_BaseModel):
+    """
+    Ansible-test sanity tests session config.
+    """
+
+    default: bool = False
+
+    include_devel: bool = False
+    include_milestone: bool = False
+    add_devel_like_branches: list[DevelLikeBranch] = []
+    min_version: t.Optional[PVersion] = None
+    max_version: t.Optional[PVersion] = None
+    except_versions: list[PAnsibleCoreVersion] = []
+    skip_tests: list[str] = []
+    allow_disabled: bool = False
+    enable_optional_errors: bool = False
+
+
+class SessionAnsibleTestUnits(_BaseModel):
+    """
+    Ansible-test unit tests session config.
+    """
+
+    default: bool = False
+
+    include_devel: bool = False
+    include_milestone: bool = False
+    add_devel_like_branches: list[DevelLikeBranch] = []
+    min_version: t.Optional[PVersion] = None
+    max_version: t.Optional[PVersion] = None
+    except_versions: list[PAnsibleCoreVersion] = []
+
+
+class SessionAnsibleTestIntegrationWDefaultContainer(_BaseModel):
+    """
+    Ansible-test integration tests with default container session config.
+    """
+
+    default: bool = False
+
+    include_devel: bool = False
+    include_milestone: bool = False
+    add_devel_like_branches: list[DevelLikeBranch] = []
+    min_version: t.Optional[PVersion] = None
+    max_version: t.Optional[PVersion] = None
+    except_versions: list[PAnsibleCoreVersion] = []
+    core_python_versions: dict[t.Union[PAnsibleCoreVersion, str], list[PVersion]] = {}
+    controller_python_versions_only: bool = False
+
+    @p.model_validator(mode="after")
+    def _validate_core_keys(self) -> t.Self:
+        branch_names = [dlb.branch for dlb in self.add_devel_like_branches]
+        for key in self.core_python_versions:
+            if isinstance(key, Version) or key in {"devel", "milestone"}:
+                continue
+            if key in branch_names:
+                continue
+            raise ValueError(
+                f"Unknown ansible-core version or branch name {key!r} in core_python_versions"
+            )
+        return self
+
+
+class SessionAnsibleLint(_BaseModel):
+    """
+    Ansible-lint session config.
+    """
+
+    default: bool = True
+
+    ansible_lint_package: str = "ansible-lint"
+    strict: bool = False
+
+
+class Sessions(_BaseModel):
+    """
+    Configuration of nox sessions to add.
+    """
+
+    lint: t.Optional[SessionLint] = None
+    docs_check: t.Optional[SessionDocsCheck] = None
+    license_check: t.Optional[SessionLicenseCheck] = None
+    extra_checks: t.Optional[SessionExtraChecks] = None
+    build_import_check: t.Optional[SessionBuildImportCheck] = None
+    ansible_test_sanity: t.Optional[SessionAnsibleTestSanity] = None
+    ansible_test_units: t.Optional[SessionAnsibleTestUnits] = None
+    ansible_test_integration_w_default_container: t.Optional[
+        SessionAnsibleTestIntegrationWDefaultContainer
+    ] = None
+    ansible_lint: t.Optional[SessionAnsibleLint] = None
+
+
+class CollectionSource(_BaseModel):
+    """
+    Source from which to install a collection.
+    """
+
+    source: str
+
+    @p.model_validator(mode="before")
+    @classmethod
+    def _pre_validate(cls, values):
+        if isinstance(values, str):
+            return {"source": values}
+        return values
+
+
+class Config(_BaseModel):
+    """
+    The contents of a antsibull-nox config file.
+    """
+
+    collection_sources: dict[CollectionName, CollectionSource] = {}
+    sessions: Sessions = Sessions()
+
+
+def load_config_from_toml(path: str | os.PathLike) -> Config:
+    """
+    Load a config TOML file.
+    """
+    with open(path, "rb") as f:
+        try:
+            data = _load_toml(f)
+        except ValueError as exc:
+            raise ValueError(f"Error while reading {path}: {exc}") from exc
+    return Config.model_validate(data)
+
+
+def lint_config_toml() -> list[str]:
+    """
+    Lint config files
+    """
+    path = CONFIG_FILENAME
+    errors = []
+    forbid_extras(Config)
+    try:
+        with open(path, "rb") as f:
+            data = _load_toml(f)
+        Config.model_validate(data)
+    except p.ValidationError as exc:
+        for error in get_formatted_error_messages(exc):
+            errors.append(f"{path}:{error}")
+    except ValueError as exc:
+        errors.append(f"{path}:{exc}")
+    except FileNotFoundError:
+        errors.append(f"{path}: File does not exist")
+    except IOError as exc:
+        errors.append(f"{path}:{exc}")
+    return errors

antsibull_nox/data/action-groups.py

@@ -16,8 +16,8 @@ import typing as t
 
 import yaml
 
-from antsibull_nox.data_util import setup
-from antsibull_nox.sessions import ActionGroup
+from antsibull_nox.data.antsibull_nox_data_util import setup
+from antsibull_nox.sessions.extra_checks import ActionGroup
 
 
 def compile_patterns(
@@ -41,7 +41,7 @@ def load_redirects(
     try:
         with open(meta_runtime, "rb") as f:
             data = yaml.safe_load(f)
-        action_groups = data["action_groups"]
+        action_groups = data.get("action_groups", {})
     except Exception as exc:
         errors.append(f"{meta_runtime}: cannot load action groups: {exc}")
         return {}

antsibull_nox/data/antsibull-nox-lint-config.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python
+
+# Copyright (c) 2025, Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt
+# or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Run antsibull-nox lint-config."""
+
+from __future__ import annotations
+
+import sys
+
+from antsibull_nox.data.antsibull_nox_data_util import setup
+from antsibull_nox.lint_config import lint_config
+
+
+def main() -> int:
+    """Main entry point."""
+    _, __ = setup()
+
+    errors = lint_config()
+    for error in errors:
+        print(error)
+    return len(errors) > 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

antsibull_nox/data/antsibull_nox_data_util.py

@@ -0,0 +1,91 @@
+# Author: Felix Fontein <felix@fontein.de>
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or
+# https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+# SPDX-FileCopyrightText: 2025, Ansible Project
+
+"""
+Utility code for scripts in data.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import typing as t
+
+
+def setup() -> tuple[list[str], dict[str, t.Any]]:
+    """
+    Fetch list of paths and potential extra configuration.
+
+    First thing to call in an extra sanity check script in data/.
+    """
+    if len(sys.argv) == 3 and sys.argv[1] == "--data":
+        # Preferred way: load information from JSON file
+        path = sys.argv[2]
+        try:
+            with open(path, "rb") as f:
+                data = json.load(f)
+        except Exception as exc:
+            raise ValueError(f"Error while reading JSON from {path}") from exc
+        try:
+            paths = get_list_of_strings(data, "paths")
+        except ValueError as exc:
+            raise ValueError(f"Invalid JSON content in {path}: {exc}") from exc
+        data.pop("paths")
+        return paths, data
+    if len(sys.argv) >= 2:
+        # It's also possible to pass a list of paths on the command line, to simplify
+        # testing these scripts.
+        return sys.argv[1:], {}
+    # Alternatively one can pass a list of files from stdin, for example by piping
+    # the output of 'git ls-files' into this script. This is also for testing these
+    # scripts.
+    return sys.stdin.read().splitlines(), {}
+
+
+def get_list_of_strings(
+    data: dict[str, t.Any],
+    key: str,
+    *,
+    default: list[str] | None = None,
+) -> list[str]:
+    """
+    Retrieves a list of strings from key ``key`` of the JSON object ``data``.
+
+    If ``default`` is set to a list, a missing key results in this value being returned.
+    """
+    sentinel = object()
+    value = data.get(key, sentinel)
+    if value is sentinel:
+        if default is not None:
+            return default
+        raise ValueError(f"{key!r} is not a present")
+    if not isinstance(value, list):
+        raise ValueError(f"{key!r} is not a list, but {type(key)}")
+    if not all(isinstance(entry, str) for entry in value):
+        raise ValueError(f"{key!r} is not a list of strings")
+    return t.cast(list[str], value)
+
+
+def get_bool(
+    data: dict[str, t.Any],
+    key: str,
+    *,
+    default: bool | None = None,
+) -> bool:
+    """
+    Retrieves a boolean from key ``key`` of the JSON object ``data``.
+
+    If ``default`` is set to a boolean, a missing key results in this value being returned.
+    """
+    sentinel = object()
+    value = data.get(key, sentinel)
+    if value is sentinel:
+        if default is not None:
+            return default
+        raise ValueError(f"{key!r} is not a present")
+    if not isinstance(value, bool):
+        raise ValueError(f"{key!r} is not a bool, but {type(key)}")
+    return value

antsibull_nox/data/license-check.py

@@ -11,9 +11,10 @@ from __future__ import annotations
 
 import glob
 import os
+import stat
 import sys
 
-from antsibull_nox.data_util import get_list_of_strings, setup
+from antsibull_nox.data.antsibull_nox_data_util import get_list_of_strings, setup
 
 
 def format_license_list(licenses: list[str]) -> str:
@@ -108,7 +109,10 @@ def main() -> int:
             path = path[2:]
         if path in ignore_paths or path.startswith("tests/output/"):
             continue
-        if os.stat(path).st_size == 0:
+        sr = os.stat(path)
+        if not stat.S_ISREG(sr.st_mode):
+            continue
+        if sr.st_size == 0:
             continue
         if not path.endswith(".license") and os.path.exists(path + ".license"):
             path = path + ".license"

antsibull_nox/data/no-unwanted-files.py

@@ -12,7 +12,11 @@ from __future__ import annotations
 import os
 import sys
 
-from antsibull_nox.data_util import get_bool, get_list_of_strings, setup
+from antsibull_nox.data.antsibull_nox_data_util import (
+    get_bool,
+    get_list_of_strings,
+    setup,
+)
 
 
 def main() -> int: