antsibull-nox 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

antsibull_nox/config.py

@@ -15,6 +15,7 @@ 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
 
@@ -24,6 +25,9 @@ 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
@@ -45,6 +49,18 @@ def _parse_ansible_core_version(value: t.Any) -> AnsibleCoreVersion:
     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)
@@ -101,6 +117,9 @@ class SessionLint(_BaseModel):
     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):
     """
@@ -112,7 +131,7 @@ class SessionDocsCheck(_BaseModel):
     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[str] = []
+    extra_collections: list[CollectionName] = []
 
 
 class SessionLicenseCheck(_BaseModel):
@@ -183,6 +202,7 @@ class SessionBuildImportCheck(_BaseModel):
     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):
@@ -220,6 +240,9 @@ class SessionAnsibleTestSanity(_BaseModel):
     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):
@@ -316,7 +339,10 @@ class Config(_BaseModel):
     The contents of a antsibull-nox config file.
     """
 
-    collection_sources: dict[str, CollectionSource] = {}
+    collection_sources: dict[CollectionName, CollectionSource] = {}
+    collection_sources_per_ansible: dict[
+        PAnsibleCoreVersion, dict[CollectionName, CollectionSource]
+    ] = {}
     sessions: Sessions = Sessions()
 
 
@@ -330,3 +356,26 @@ def load_config_from_toml(path: str | os.PathLike) -> Config:
         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

@@ -17,7 +17,7 @@ import typing as t
 import yaml
 
 from antsibull_nox.data.antsibull_nox_data_util import setup
-from antsibull_nox.sessions import ActionGroup
+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/file-yamllint.py

@@ -0,0 +1,138 @@
+#!/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
+
+"""Make sure all plugin and module documentation adheres to yamllint."""
+
+from __future__ import annotations
+
+import io
+import os
+import sys
+import traceback
+import typing as t
+
+from antsibull_nox_data_util import setup  # type: ignore
+from yamllint import linter
+from yamllint.cli import find_project_config_filepath
+from yamllint.config import YamlLintConfig
+from yamllint.linter import PROBLEM_LEVELS
+
+REPORT_LEVELS: set[PROBLEM_LEVELS] = {
+    "warning",
+    "error",
+}
+
+
+def lint(
+    *,
+    errors: list[dict[str, t.Any]],
+    path: str,
+    data: str,
+    config: YamlLintConfig,
+) -> None:
+    try:
+        problems = linter.run(
+            io.StringIO(data),
+            config,
+            path,
+        )
+        for problem in problems:
+            if problem.level not in REPORT_LEVELS:
+                continue
+            msg = f"{problem.level}: {problem.desc}"
+            if problem.rule:
+                msg += f"  ({problem.rule})"
+            errors.append(
+                {
+                    "path": path,
+                    "line": problem.line,
+                    "col": problem.column,
+                    "message": msg,
+                }
+            )
+    except Exception as exc:
+        error = str(exc).replace("\n", " / ")
+        errors.append(
+            {
+                "path": path,
+                "line": 1,
+                "col": 1,
+                "message": (
+                    f"Internal error while linting YAML: exception {type(exc)}:"
+                    f" {error}; traceback: {traceback.format_exc()!r}"
+                ),
+            }
+        )
+
+
+def process_yaml_file(
+    errors: list[dict[str, t.Any]],
+    path: str,
+    config: YamlLintConfig,
+) -> None:
+    try:
+        with open(path, "rt", encoding="utf-8") as stream:
+            data = stream.read()
+    except Exception as exc:
+        errors.append(
+            {
+                "path": path,
+                "line": 1,
+                "col": 1,
+                "message": (
+                    f"Error while parsing Python code: exception {type(exc)}:"
+                    f" {exc}; traceback: {traceback.format_exc()!r}"
+                ),
+            }
+        )
+        return
+
+    lint(
+        errors=errors,
+        path=path,
+        data=data,
+        config=config,
+    )
+
+
+def main() -> int:
+    """Main entry point."""
+    paths, extra_data = setup()
+    config: str | None = extra_data.get("config")
+
+    if config is None:
+        config = find_project_config_filepath()
+
+    if config:
+        yamllint_config = YamlLintConfig(file=config)
+    else:
+        yamllint_config = YamlLintConfig(content="extends: default")
+
+    errors: list[dict[str, t.Any]] = []
+    for path in paths:
+        if not os.path.isfile(path):
+            continue
+        process_yaml_file(errors, path, yamllint_config)
+
+    errors.sort(
+        key=lambda error: (error["path"], error["line"], error["col"], error["message"])
+    )
+    for error in errors:
+        prefix = f"{error['path']}:{error['line']}:{error['col']}: "
+        msg = error["message"]
+        if "note" in error:
+            msg = f"{msg}\nNote: {error['note']}"
+        for i, line in enumerate(msg.splitlines()):
+            print(f"{prefix}{line}")
+            if i == 0:
+                prefix = " " * len(prefix)
+
+    return len(errors) > 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

antsibull_nox/data/license-check.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import glob
 import os
+import stat
 import sys
 
 from antsibull_nox.data.antsibull_nox_data_util import get_list_of_strings, setup
@@ -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/plugin-yamllint.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-# Copyright (c) 2024, Felix Fontein <felix@fontein.de>
+# 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
@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import ast
 import io
+import os
 import re
 import sys
 import traceback
@@ -43,6 +44,13 @@ def lint(
     config: YamlLintConfig,
     extra_for_errors: dict[str, t.Any] | None = None,
 ) -> None:
+    # If the string start with optional whitespace + linebreak, skip that line
+    idx = data.find("\n")
+    if idx >= 0 and (idx == 0 or data[:idx].isspace()):
+        data = data[idx + 1 :]
+        row_offset += 1
+        col_offset = 0
+
     try:
         problems = linter.run(
             io.StringIO(data),
@@ -83,6 +91,20 @@ def lint(
             errors[-1].update(extra_for_errors)
 
 
+def iterate_targets(
+    assignment: ast.Assign,
+) -> t.Iterable[tuple[ast.Constant, str, str]]:
+    if not isinstance(assignment.value, ast.Constant):
+        return
+    if not isinstance(assignment.value.value, str):
+        return
+    for target in assignment.targets:
+        try:
+            yield assignment.value, assignment.value.value, target.id  # type: ignore
+        except AttributeError:
+            continue
+
+
 def process_python_file(
     errors: list[dict[str, t.Any]],
     path: str,
@@ -106,33 +128,39 @@ def process_python_file(
         )
         return
 
-    # We look for top-level assignments
+    is_doc_fragment = path.startswith("plugins/doc_fragments/")
+
+    # We look for top-level assignments and classes
     for child in root.body:
+        if (
+            is_doc_fragment
+            and isinstance(child, ast.ClassDef)
+            and child.name == "ModuleDocFragment"
+        ):
+            for fragment in child.body:
+                if not isinstance(fragment, ast.Assign):
+                    continue
+                for constant, data, fragment_name in iterate_targets(fragment):
+                    lint(
+                        errors=errors,
+                        path=path,
+                        data=data,
+                        row_offset=constant.lineno - 1,
+                        col_offset=constant.col_offset - 1,
+                        section=fragment_name,
+                        config=config,
+                    )
         if not isinstance(child, ast.Assign):
             continue
-        if not isinstance(child.value, ast.Constant):
-            continue
-        if not isinstance(child.value.value, str):
-            continue
-        for target in child.targets:
-            try:
-                section = target.id  # type: ignore
-            except AttributeError:
-                continue
+        for constant, data, section in iterate_targets(child):
             if section not in ("DOCUMENTATION", "EXAMPLES", "RETURN"):
                 continue
 
-            # Extract value and offsets
-            data = child.value.value
-            row_offset = child.value.lineno - 1
-            col_offset = child.value.col_offset - 1
-
-            # If the string start with optional whitespace + linebreak, skip that line
-            idx = data.find("\n")
-            if idx >= 0 and (idx == 0 or data[:idx].isspace()):
-                data = data[idx + 1 :]
-                row_offset += 1
-                col_offset = 0
+            # Handle special values
+            if data in ("#", " # ") and section == "RETURN":
+                # Not skipping it here could result in all kind of linting errors,
+                # like no document start, or trailing space.
+                continue
 
             # Check for non-YAML examples
             if section == EXAMPLES_SECTION:
@@ -145,8 +173,8 @@ def process_python_file(
                 errors=errors,
                 path=path,
                 data=data,
-                row_offset=row_offset,
-                col_offset=col_offset,
+                row_offset=constant.lineno - 1,
+                col_offset=constant.col_offset - 1,
                 section=section,
                 config=config_examples if section == EXAMPLES_SECTION else config,
             )
@@ -219,6 +247,8 @@ def main() -> int:
 
     errors: list[dict[str, t.Any]] = []
     for path in paths:
+        if not os.path.isfile(path):
+            continue
         if path.endswith(".py"):
             process_python_file(errors, path, yamllint_config, yamllint_config_examples)
         if path.endswith((".yml", ".yaml")):

antsibull_nox/init.py

@@ -0,0 +1,83 @@
+# 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
+
+"""Tool to create initial configuration."""
+
+from pathlib import Path
+
+from .collection.search import GALAXY_YML
+from .config import CONFIG_FILENAME
+from .lint_config import NOXFILE_PY
+
+NOXFILE_CONTENT = r"""
+# The following metadata allows Python runners and nox to install the required
+# dependencies for running this Python script:
+#
+# /// script
+# dependencies = ["nox>=2025.02.09", "antsibull-nox"]
+# ///
+
+import sys
+
+import nox
+
+
+# We try to import antsibull-nox, and if that doesn't work, provide a more useful
+# error message to the user.
+try:
+    import antsibull_nox
+except ImportError:
+    print("You need to install antsibull-nox in the same Python environment as nox.")
+    sys.exit(1)
+
+
+antsibull_nox.load_antsibull_nox_toml()
+
+
+# Allow to run the noxfile with `python noxfile.py`, `pipx run noxfile.py`, or similar.
+# Requires nox >= 2025.02.09
+if __name__ == "__main__":
+    nox.main()
+"""
+
+CONFIG_CONTENT = r"""
+[sessions]
+
+[sessions.lint]
+# disable reformatting for now
+run_isort = false
+
+# disable reformatting for now
+run_black = false
+
+# Add more configuration settings here to adjust to your collection;
+# see https://ansible.readthedocs.io/projects/antsibull-nox/config-file/#basic-linting-sessions
+
+[sessions.docs_check]
+# Add configuration settings here to adjust to your collection;
+# see https://ansible.readthedocs.io/projects/antsibull-nox/config-file/#collection-documentation-check
+"""
+
+
+def create_initial_config(*, path: Path | None = None) -> None:
+    """
+    Write noxfile.py and antsibull-nox.toml for a collection.
+    """
+    if path is None:
+        path = Path()
+
+    galaxy_yml = path / GALAXY_YML
+    if not galaxy_yml.is_file():
+        raise ValueError(f"Cannot find {galaxy_yml}")
+
+    noxfile = path / NOXFILE_PY
+    config_file = path / CONFIG_FILENAME
+    for file in (noxfile, config_file):
+        if file.exists():
+            raise ValueError(f"{file} already exists")
+
+    noxfile.write_text(NOXFILE_CONTENT)
+    config_file.write_text(CONFIG_CONTENT)

antsibull_nox/interpret_config.py

@@ -20,19 +20,21 @@ from .config import (
     DevelLikeBranch,
     Sessions,
 )
-from .sessions import (
-    ActionGroup,
+from .sessions import add_matrix_generator
+from .sessions.ansible_lint import add_ansible_lint
+from .sessions.ansible_test import (
     add_all_ansible_test_sanity_test_sessions,
     add_all_ansible_test_unit_test_sessions,
-    add_ansible_lint,
     add_ansible_test_integration_sessions_default_container,
-    add_build_import_check,
-    add_docs_check,
+)
+from .sessions.build_import_check import add_build_import_check
+from .sessions.docs_check import add_docs_check
+from .sessions.extra_checks import (
+    ActionGroup,
     add_extra_checks,
-    add_license_check,
-    add_lint_sessions,
-    add_matrix_generator,
 )
+from .sessions.license_check import add_license_check
+from .sessions.lint import add_lint_sessions
 from .utils import Version
 
 
@@ -44,6 +46,18 @@ def _interpret_config(config: Config) -> None:
                 for name, source in config.collection_sources.items()
             }
         )
+    if config.collection_sources_per_ansible:
+        for (
+            ansible_core_version,
+            collection_sources,
+        ) in config.collection_sources_per_ansible.items():
+            setup_collection_sources(
+                {
+                    name: CollectionSource(name=name, source=source.source)
+                    for name, source in collection_sources.items()
+                },
+                ansible_core_version=ansible_core_version,
+            )
 
 
 def _convert_action_groups(
@@ -116,6 +130,7 @@ def _add_sessions(sessions: Sessions) -> None:
             mypy_package=sessions.lint.mypy_package,
             mypy_ansible_core_package=sessions.lint.mypy_ansible_core_package,
             mypy_extra_deps=sessions.lint.mypy_extra_deps,
+            run_antsibullnox_config_lint=sessions.lint.run_antsibullnox_config_lint,
         )
     if sessions.docs_check:
         add_docs_check(
@@ -172,6 +187,9 @@ def _add_sessions(sessions: Sessions) -> None:
             run_galaxy_importer=sessions.build_import_check.run_galaxy_importer,
             galaxy_importer_package=sessions.build_import_check.galaxy_importer_package,
             galaxy_importer_config_path=sessions.build_import_check.galaxy_importer_config_path,
+            galaxy_importer_always_show_logs=(
+                sessions.build_import_check.galaxy_importer_always_show_logs
+            ),
         )
     if sessions.ansible_test_sanity:
         add_all_ansible_test_sanity_test_sessions(
@@ -186,6 +204,9 @@ def _add_sessions(sessions: Sessions) -> None:
             except_versions=_convert_except_versions(
                 sessions.ansible_test_sanity.except_versions
             ),
+            skip_tests=sessions.ansible_test_sanity.skip_tests,
+            allow_disabled=sessions.ansible_test_sanity.allow_disabled,
+            enable_optional_errors=sessions.ansible_test_sanity.enable_optional_errors,
         )
     if sessions.ansible_test_units:
         add_all_ansible_test_unit_test_sessions(