antsibull-nox 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

antsibull_nox/__init__.py

@@ -17,7 +17,7 @@ from .config import (
 from .interpret_config import interpret_config
 from .sessions.ansible_test import add_ansible_test_session
 
-__version__ = "0.5.0"
+__version__ = "0.7.0"
 
 
 def load_antsibull_nox_toml() -> None:

antsibull_nox/ansible.py

@@ -87,13 +87,13 @@ _SUPPORTED_CORE_VERSIONS: dict[Version, AnsibleCoreInfo] = {
             ["3.11", "3.12", "3.13"],
             ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"],
         ],
+        "2.20": [
+            ["3.11", "3.12", "3.13"],
+            ["3.9", "3.10", "3.11", "3.12", "3.13"],
+        ],
         # The following might need updates. Look for the "``ansible-core`` support matrix" table in:
         # https://github.com/ansible/ansible-documentation/blob/devel/docs/docsite/rst/reference_appendices/release_and_maintenance.rst?plain=1
         # It contains commented-out entries for future ansible-core versions.
-        "2.20": [
-            ["3.12", "3.13", "3.14"],
-            ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"],
-        ],
         "2.21": [
             ["3.12", "3.13", "3.14"],
             ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"],
@@ -118,8 +118,8 @@ _SUPPORTED_CORE_VERSIONS: dict[Version, AnsibleCoreInfo] = {
 }
 
 _MIN_SUPPORTED_VERSION = Version.parse("2.9")
-_CURRENT_DEVEL_VERSION = Version.parse("2.19")
-_CURRENT_MILESTONE_VERSION = Version.parse("2.19")
+_CURRENT_DEVEL_VERSION = Version.parse("2.20")
+_CURRENT_MILESTONE_VERSION = Version.parse("2.20")
 
 
 def get_ansible_core_info(

antsibull_nox/collection/__init__.py

@@ -10,10 +10,7 @@ Handle Ansible collections.
 
 from __future__ import annotations
 
-from pathlib import Path
-
-from antsibull_fileutils.yaml import load_yaml_file, store_yaml_file
-
+from .build import build_collection
 from .data import CollectionData, CollectionSource, SetupResult
 from .install import (
     Runner,
@@ -21,27 +18,8 @@ from .install import (
     setup_collections,
     setup_current_tree,
 )
-from .search import GALAXY_YML, CollectionList, load_collection_data_from_disk
-
-
-def force_collection_version(path: Path, *, version: str) -> bool:
-    """
-    Make sure galaxy.yml contains this version.
-
-    Returns ``True`` if the version was changed, and ``False`` if the version
-    was already set to this value.
-    """
-    galaxy_yml = path / GALAXY_YML
-    try:
-        data = load_yaml_file(galaxy_yml)
-    except Exception as exc:
-        raise ValueError(f"Cannot parse {galaxy_yml}: {exc}") from exc
-    if data.get("version") == version:
-        return False
-    data["version"] = version
-    store_yaml_file(galaxy_yml, data)
-    return True
-
+from .search import CollectionList, load_collection_data_from_disk
+from .utils import force_collection_version
 
 __all__ = [
     "CollectionData",
@@ -49,6 +27,8 @@ __all__ = [
     "CollectionSource",
     "SetupResult",
     "Runner",
+    "build_collection",
+    "force_collection_version",
     "load_collection_data_from_disk",
     "setup_collections",
     "setup_current_tree",

antsibull_nox/collection/build.py

@@ -0,0 +1,69 @@
+# 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
+
+"""
+Build Ansible collections.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import nox
+
+from ..paths import (
+    copy_collection,
+    remove_path,
+)
+from .data import (
+    CollectionData,
+)
+from .search import (
+    load_collection_data_from_disk,
+)
+from .utils import (
+    force_collection_version,
+)
+
+
+def build_collection(
+    session: nox.Session,
+) -> tuple[Path | None, CollectionData, str]:
+    """
+    Build the current collection.
+
+    Return a tuple (path, collection_data, version), where path might be None in case
+    commands are not actually run.
+    """
+    tmp = Path(session.create_tmp())
+    collection_dir = tmp / "collection"
+    remove_path(collection_dir)
+    copy_collection(Path.cwd(), collection_dir)
+
+    collection = load_collection_data_from_disk(collection_dir, accept_manifest=False)
+    version = collection.version
+    if not version:
+        version = "0.0.1"
+        force_collection_version(collection_dir, version=version)
+
+    with session.chdir(collection_dir):
+        build_ran = session.run("ansible-galaxy", "collection", "build") is not None
+
+    tarball = (
+        collection_dir / f"{collection.namespace}-{collection.name}-{version}.tar.gz"
+    )
+    if build_ran and not tarball.is_file():
+        files = "\n".join(
+            f"* {path.name}" for path in collection_dir.iterdir() if not path.is_dir()
+        )
+        session.error(f"Cannot find file {tarball}! List of all files:\n{files}")
+
+    return tarball if build_ran else None, collection, version
+
+
+__all__ = [
+    "build_collection",
+]

antsibull_nox/collection/utils.py

@@ -0,0 +1,41 @@
+# 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
+
+"""
+Build Ansible collections.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from antsibull_fileutils.yaml import load_yaml_file, store_yaml_file
+
+from .search import GALAXY_YML
+
+
+def force_collection_version(path: Path, *, version: str) -> bool:
+    """
+    Make sure galaxy.yml contains this version.
+
+    Returns ``True`` if the version was changed, and ``False`` if the version
+    was already set to this value.
+    """
+    galaxy_yml = path / GALAXY_YML
+    try:
+        data = load_yaml_file(galaxy_yml)
+    except Exception as exc:
+        raise ValueError(f"Cannot parse {galaxy_yml}: {exc}") from exc
+    if data.get("version") == version:
+        return False
+    data["version"] = version
+    store_yaml_file(galaxy_yml, data)
+    return True
+
+
+__all__ = [
+    "force_collection_version",
+]

antsibull_nox/config.py

@@ -78,6 +78,8 @@ class SessionLint(_BaseModel):
 
     default: bool = True
     extra_code_files: list[str] = []
+    ruff_config: t.Optional[p.FilePath] = None
+    ruff_package: str = "ruff"
 
     # isort:
     run_isort: bool = True
@@ -90,6 +92,22 @@ class SessionLint(_BaseModel):
     black_config: t.Optional[p.FilePath] = None
     black_package: str = "black"
 
+    # ruff format:
+    run_ruff_format: bool = False
+    ruff_format_config: t.Optional[p.FilePath] = None
+    ruff_format_package: t.Optional[str] = None
+
+    # ruff autofix:
+    run_ruff_autofix: bool = False
+    ruff_autofix_config: t.Optional[p.FilePath] = None
+    ruff_autofix_package: t.Optional[str] = None
+    ruff_autofix_select: list[str] = []
+
+    # ruff check:
+    run_ruff_check: bool = False
+    ruff_check_config: t.Optional[p.FilePath] = None
+    ruff_check_package: t.Optional[str] = None
+
     # flake8:
     run_flake8: bool = True
     flake8_config: t.Optional[p.FilePath] = None
@@ -108,7 +126,9 @@ class SessionLint(_BaseModel):
     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_config_extra_docs: t.Optional[p.FilePath] = None
     yamllint_package: str = "yamllint"
+    yamllint_antsibull_docutils_package: str = "antsibull-docutils"
 
     # mypy:
     run_mypy: bool = True
@@ -133,6 +153,12 @@ class SessionDocsCheck(_BaseModel):
     validate_collection_refs: t.Optional[t.Literal["self", "dependent", "all"]] = None
     extra_collections: list[CollectionName] = []
 
+    codeblocks_restrict_types: t.Optional[list[str]] = None
+    codeblocks_restrict_type_exact_case: bool = True
+    codeblocks_allow_without_type: bool = True
+    codeblocks_allow_literal_blocks: bool = True
+    antsibull_docutils_package: str = "antsibull-docutils"
+
 
 class SessionLicenseCheck(_BaseModel):
     """
@@ -178,8 +204,8 @@ class SessionExtraChecks(_BaseModel):
     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]] = [
+    no_unwanted_files_skip_directories: list[str] = []
+    no_unwanted_files_yaml_directories: list[str] = [
         "plugins/test/",
         "plugins/filter/",
     ]
@@ -189,6 +215,11 @@ class SessionExtraChecks(_BaseModel):
     run_action_groups: bool = False
     action_groups_config: list[ActionGroup] = []
 
+    # no-trailing-whitespace:
+    run_no_trailing_whitespace: bool = False
+    no_trailing_whitespace_skip_paths: list[str] = []
+    no_trailing_whitespace_skip_directories: list[str] = []
+
 
 class SessionBuildImportCheck(_BaseModel):
     """

antsibull_nox/data/action-groups.py

@@ -59,12 +59,20 @@ def load_redirects(
 
     # Compare meta/runtime.yml content with config
     config_groups = {cfg.name for cfg in config}
-    for action_group in action_groups:
+    for action_group, elements in action_groups.items():
         if action_group not in config_groups:
+            if len(elements) == 1 and isinstance(elements[0], dict):
+                # Special case: if an action group is there with a single metadata entry,
+                # we don't complain that it shouldn't be there.
+                continue
             errors.append(
                 f"{meta_runtime}: found unknown action group"
                 f" {action_group!r}; likely noxfile needs updating"
             )
+        else:
+            action_groups[action_group] = [
+                element for element in elements if isinstance(element, str)
+            ]
     for action_group in config:
         if action_group.name not in action_groups:
             errors.append(

antsibull_nox/data/antsibull_nox_data_util.py

@@ -33,6 +33,8 @@ def setup() -> tuple[list[str], dict[str, t.Any]]:
             paths = get_list_of_strings(data, "paths")
         except ValueError as exc:
             raise ValueError(f"Invalid JSON content in {path}: {exc}") from exc
+        if paths is None:
+            raise ValueError(f"Broken JSON content in {path}: path is missing")
         data.pop("paths")
         return paths, data
     if len(sys.argv) >= 2:
@@ -45,12 +47,33 @@ def setup() -> tuple[list[str], dict[str, t.Any]]:
     return sys.stdin.read().splitlines(), {}
 
 
+_T = t.TypeVar("_T", default=None)
+
+
+@t.overload
+def get_list_of_strings(
+    data: dict[str, t.Any],
+    key: str,
+    *,
+    default: None = None,
+) -> list[str] | None: ...
+
+
+@t.overload
+def get_list_of_strings(
+    data: dict[str, t.Any],
+    key: str,
+    *,
+    default: _T,
+) -> list[str] | _T: ...
+
+
 def get_list_of_strings(
     data: dict[str, t.Any],
     key: str,
     *,
-    default: list[str] | None = None,
-) -> list[str]:
+    default: _T | None = None,
+) -> list[str] | _T | None:
     """
     Retrieves a list of strings from key ``key`` of the JSON object ``data``.
 

antsibull_nox/data/get-package-versions.py

@@ -0,0 +1,36 @@
+#!/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
+
+"""Retrieve the version of one or more packages."""
+
+from __future__ import annotations
+
+import json
+import sys
+from importlib.metadata import PackageNotFoundError, version
+
+from antsibull_nox_data_util import get_list_of_strings, setup  # type: ignore
+
+
+def main() -> int:
+    """Main entry point."""
+    paths, extra_data = setup()
+
+    packages = get_list_of_strings(extra_data, "packages", default=[])
+
+    result: dict[str, str | None] = {}
+    for package in packages:
+        try:
+            result[package] = version(package)
+        except PackageNotFoundError:
+            result[package] = None
+    print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

antsibull_nox/data/no-trailing-whitespace.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python
+
+# Copyright (c) Ansible Project
+# 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
+
+"""Prevent unwanted files from being added to the source tree."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from antsibull_nox.data.antsibull_nox_data_util import (
+    get_list_of_strings,
+    setup,
+)
+
+
+def main() -> int:
+    """Main entry point."""
+    paths, extra_data = setup()
+
+    skip_paths = set(get_list_of_strings(extra_data, "skip_paths", default=[]))
+
+    skip_directories = tuple(
+        get_list_of_strings(extra_data, "skip_directories", default=[])
+    )
+
+    errors: list[str] = []
+    for path in paths:
+        if path in skip_paths:
+            continue
+
+        if any(path.startswith(skip_directory) for skip_directory in skip_directories):
+            continue
+
+        if not os.path.isfile(path):
+            continue
+
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                for i, line in enumerate(f):
+                    line = line.rstrip("\n\r")
+                    if line.rstrip() != line:
+                        errors.append(f"{path}:{i + 1}: found trailing whitespace")
+        except UnicodeDecodeError:
+            errors.append(f"{path}: cannot parse file as UTF-8")
+        except Exception as e:
+            errors.append(f"{path}: unexpected error: {e}")
+
+    for error in sorted(errors):
+        print(error)
+    return len(errors) > 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

antsibull_nox/data/no-unwanted-files.py

@@ -65,7 +65,7 @@ def main() -> int:
     skip_paths = set(get_list_of_strings(extra_data, "skip_paths", default=[]))
 
     skip_directories = tuple(
-        get_list_of_strings(extra_data, "skip_prefixes", default=[])
+        get_list_of_strings(extra_data, "skip_directories", default=[])
     )
 
     yaml_directories = tuple(

antsibull_nox/data/rst-extra.py

@@ -0,0 +1,167 @@
+#!/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 os
+import sys
+import traceback
+import typing as t
+
+from antsibull_docutils.rst_code_finder import find_code_blocks
+from antsibull_nox_data_util import get_bool, get_list_of_strings, setup  # type: ignore
+
+
+def process_rst_file(
+    errors: list[dict[str, t.Any]],
+    path: str,
+    *,
+    codeblocks_restrict_types: list[str] | None,
+    codeblocks_restrict_type_exact_case: bool,
+    codeblocks_allow_without_type: bool,
+    codeblocks_allow_literal_blocks: bool,
+) -> None:
+    try:
+        with open(path, "rt", encoding="utf-8") as f:
+            content = f.read()
+    except Exception as exc:
+        errors.append(
+            {
+                "path": path,
+                "line": 1,
+                "col": 1,
+                "message": (
+                    f"Error while reading content: {type(exc)}:"
+                    f" {exc}; traceback: {traceback.format_exc()!r}"
+                ),
+            }
+        )
+        return
+
+    def warn_unknown_block(line: int | str, col: int, content: str) -> None:
+        if not codeblocks_allow_literal_blocks:
+            errors.append(
+                {
+                    "path": path,
+                    "line": line,
+                    "col": col,
+                    "message": (
+                        "Warning: found unknown literal block! Check for double colons '::'."
+                        " If that is not the cause, please report this warning."
+                        " It might indicate a bug in the checker"
+                        " or an unsupported Sphinx directive."
+                        f" Content: {content!r}"
+                    ),
+                }
+            )
+
+    for code_block in find_code_blocks(
+        content,
+        path=path,
+        root_prefix="docs/docsite/rst",
+        warn_unknown_block=warn_unknown_block,
+    ):
+        error_data = {
+            "path": path,
+            "line": code_block.row_offset + 1,
+            "col": code_block.col_offset + 1,
+        }
+        if not code_block.position_exact:
+            error_data["note"] = (
+                "The code block could not be exactly located in the source file."
+                " The line/column numbers might be off."
+            )
+
+        if code_block.language is None:
+            if not codeblocks_allow_without_type:
+                msg = "Every code block must have a language."
+                if codeblocks_restrict_types is not None:
+                    langs = ", ".join(sorted(codeblocks_restrict_types))
+                    msg = f"{msg} Allowed languages are: {langs}"
+                error_data["message"] = msg
+                errors.append(error_data)
+            continue
+
+        if codeblocks_restrict_types is None:
+            continue
+
+        language = code_block.language
+        if not codeblocks_restrict_type_exact_case:
+            language = language.lower()
+
+        if language not in codeblocks_restrict_types:
+            langs = ", ".join(sorted(codeblocks_restrict_types))
+            msg = (
+                f"Code block with disallowed language {code_block.language!r} found."
+                f" Allowed languages are: {langs}"
+            )
+            error_data["message"] = msg
+            errors.append(error_data)
+
+
+def main() -> int:
+    """Main entry point."""
+    paths, extra_data = setup()
+    codeblocks_restrict_types = get_list_of_strings(
+        extra_data, "codeblocks_restrict_types"
+    )
+    codeblocks_restrict_type_exact_case = get_bool(
+        extra_data, "codeblocks_restrict_type_exact_case", default=True
+    )
+    codeblocks_allow_without_type = get_bool(
+        extra_data, "codeblocks_allow_without_type", default=True
+    )
+    codeblocks_allow_literal_blocks = get_bool(
+        extra_data, "codeblocks_allow_literal_blocks", default=True
+    )
+
+    if (
+        codeblocks_restrict_types is not None
+        and not codeblocks_restrict_type_exact_case
+    ):
+        codeblocks_restrict_types = [
+            language.lower() for language in codeblocks_restrict_types
+        ]
+
+    errors: list[dict[str, t.Any]] = []
+    for path in paths:
+        if not os.path.isfile(path):
+            continue
+        process_rst_file(
+            errors,
+            path,
+            codeblocks_restrict_types=codeblocks_restrict_types,
+            codeblocks_restrict_type_exact_case=codeblocks_restrict_type_exact_case,
+            codeblocks_allow_without_type=codeblocks_allow_without_type,
+            codeblocks_allow_literal_blocks=codeblocks_allow_literal_blocks,
+        )
+
+    errors.sort(
+        key=lambda error: (
+            error["path"],
+            error["line"] if isinstance(error["line"], int) else 0,
+            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())