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

antsibull_nox/sessions/collections.py

@@ -0,0 +1,145 @@
+# 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
+
+"""
+Create nox sessions.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import typing as t
+from dataclasses import dataclass
+from pathlib import Path
+
+import nox
+
+from ..ansible import AnsibleCoreVersion, parse_ansible_core_version
+from ..collection import (
+    CollectionData,
+    setup_collections,
+    setup_current_tree,
+)
+from ..paths import (
+    create_temp_directory,
+)
+
+
+@dataclass
+class CollectionSetup:
+    """
+    Information on the setup collections.
+    """
+
+    # The path of the ansible_collections directory where all dependent collections
+    # are installed. Is currently identical to current_root, but that might change
+    # or depend on options in the future.
+    collections_root: Path
+
+    # The directory in which ansible_collections can be found, as well as
+    # ansible_collections/<namespace>/<name> points to a copy of the current collection.
+    current_place: Path
+
+    # The path of the ansible_collections directory that contains the current collection.
+    # The following is always true:
+    #   current_root == current_place / "ansible_collections"
+    current_root: Path
+
+    # Data on the current collection (as in the repository).
+    current_collection: CollectionData
+
+    # The path of the current collection inside the collection tree below current_root.
+    # The following is always true:
+    #   current_path == current_root / current_collection.namespace / current_collection.name
+    current_path: Path
+
+    def prefix_current_paths(self, paths: list[str]) -> list[str]:
+        """
+        Prefix the list of given paths with ``current_path``.
+        """
+        result = []
+        for path in paths:
+            prefixed_path = (self.current_path / path).relative_to(self.current_place)
+            if prefixed_path.exists():
+                result.append(str(prefixed_path))
+        return result
+
+
+def _run_subprocess(args: list[str]) -> tuple[bytes, bytes]:
+    p = subprocess.run(args, check=True, capture_output=True)
+    return p.stdout, p.stderr
+
+
+def prepare_collections(
+    session: nox.Session,
+    *,
+    ansible_core_version: AnsibleCoreVersion | str | None = None,
+    install_in_site_packages: bool,
+    extra_deps_files: list[str | os.PathLike] | None = None,
+    extra_collections: list[str] | None = None,
+    install_out_of_tree: bool = False,  # can not be used with install_in_site_packages=True
+) -> CollectionSetup | None:
+    """
+    Install collections in site-packages.
+    """
+    parsed_ansible_core_version = (
+        parse_ansible_core_version(ansible_core_version)
+        if ansible_core_version is not None
+        else "devel"
+    )
+    if install_out_of_tree and install_in_site_packages:
+        raise ValueError(
+            "install_out_of_tree=True cannot be combined with install_in_site_packages=True"
+        )
+    if isinstance(session.virtualenv, nox.virtualenv.PassthroughEnv):
+        session.warn("No venv. Skip preparing collections...")
+        return None
+    if install_in_site_packages:
+        purelib = (
+            session.run(
+                "python",
+                "-c",
+                "import sysconfig; print(sysconfig.get_path('purelib'))",
+                silent=True,
+            )
+            or ""
+        ).strip()
+        if not purelib:
+            session.warn(
+                "Cannot find site-packages (probably due to install-only run)."
+                " Skip preparing collections..."
+            )
+            return None
+        place = Path(purelib)
+    elif install_out_of_tree:
+        place = create_temp_directory(f"antsibull-nox-{session.name}-collection-root-")
+    else:
+        place = Path(session.virtualenv.location) / "collection-root"
+    place.mkdir(exist_ok=True)
+    setup = setup_collections(
+        place,
+        _run_subprocess,
+        ansible_core_version=parsed_ansible_core_version,
+        extra_deps_files=extra_deps_files,
+        extra_collections=extra_collections,
+        with_current=False,
+        global_cache_dir=session.cache_dir,
+    )
+    current_setup = setup_current_tree(place, setup.current_collection)
+    return CollectionSetup(
+        collections_root=setup.root,
+        current_place=place,
+        current_root=current_setup.root,
+        current_collection=setup.current_collection,
+        current_path=t.cast(Path, current_setup.current_path),
+    )
+
+
+__all__ = [
+    "CollectionSetup",
+    "prepare_collections",
+]

antsibull_nox/sessions/docs_check.py

@@ -0,0 +1,78 @@
+# 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
+
+"""
+Create nox docs check session.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+import nox
+
+from .collections import (
+    CollectionSetup,
+    prepare_collections,
+)
+from .utils import install
+
+
+def add_docs_check(
+    *,
+    make_docs_check_default: bool = True,
+    antsibull_docs_package: str = "antsibull-docs",
+    ansible_core_package: str = "ansible-core",
+    validate_collection_refs: t.Literal["self", "dependent", "all"] | None = None,
+    extra_collections: list[str] | None = None,
+) -> None:
+    """
+    Add docs-check session for linting.
+    """
+
+    def compose_dependencies() -> list[str]:
+        deps = [antsibull_docs_package, ansible_core_package]
+        return deps
+
+    def execute_antsibull_docs(
+        session: nox.Session, prepared_collections: CollectionSetup
+    ) -> None:
+        with session.chdir(prepared_collections.current_path):
+            collections_path = f"{prepared_collections.current_place}"
+            command = [
+                "antsibull-docs",
+                "lint-collection-docs",
+                "--plugin-docs",
+                "--skip-rstcheck",
+                ".",
+            ]
+            if validate_collection_refs:
+                command.extend(["--validate-collection-refs", validate_collection_refs])
+            session.run(*command, env={"ANSIBLE_COLLECTIONS_PATH": collections_path})
+
+    def docs_check(session: nox.Session) -> None:
+        install(session, *compose_dependencies())
+        prepared_collections = prepare_collections(
+            session,
+            install_in_site_packages=False,
+            extra_collections=extra_collections,
+            install_out_of_tree=True,
+        )
+        if not prepared_collections:
+            session.warn("Skipping antsibull-docs...")
+        if prepared_collections:
+            execute_antsibull_docs(session, prepared_collections)
+
+    docs_check.__doc__ = "Run 'antsibull-docs lint-collection-docs'"
+    nox.session(
+        name="docs-check",
+        default=make_docs_check_default,
+    )(docs_check)
+
+
+__all__ = [
+    "add_docs_check",
+]

antsibull_nox/sessions/extra_checks.py

@@ -0,0 +1,127 @@
+# 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
+
+"""
+Create nox extra checks session.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+import nox
+
+from .utils import (
+    compose_description,
+    run_bare_script,
+)
+
+
+@dataclass
+class ActionGroup:
+    """
+    Defines 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] | None = None
+
+
+def add_extra_checks(
+    *,
+    make_extra_checks_default: bool = True,
+    # no-unwanted-files:
+    run_no_unwanted_files: bool = True,
+    no_unwanted_files_module_extensions: (
+        list[str] | None
+    ) = None,  # default: .cs, .ps1, .psm1, .py
+    no_unwanted_files_other_extensions: list[str] | None = None,  # default: .py, .pyi
+    no_unwanted_files_yaml_extensions: list[str] | None = None,  # default: .yml, .yaml
+    no_unwanted_files_skip_paths: list[str] | None = None,  # default: []
+    no_unwanted_files_skip_directories: list[str] | None = None,  # default: []
+    no_unwanted_files_yaml_directories: (
+        list[str] | None
+    ) = None,  # default: plugins/test/, plugins/filter/
+    no_unwanted_files_allow_symlinks: bool = False,
+    # action-groups:
+    run_action_groups: bool = False,
+    action_groups_config: list[ActionGroup] | None = None,
+) -> None:
+    """
+    Add extra-checks session for extra checks.
+    """
+
+    def execute_no_unwanted_files(session: nox.Session) -> None:
+        run_bare_script(
+            session,
+            "no-unwanted-files",
+            extra_data={
+                "module_extensions": no_unwanted_files_module_extensions
+                or [".cs", ".ps1", ".psm1", ".py"],
+                "other_extensions": no_unwanted_files_other_extensions
+                or [".py", ".pyi"],
+                "yaml_extensions": no_unwanted_files_yaml_extensions
+                or [".yml", ".yaml"],
+                "skip_paths": no_unwanted_files_skip_paths or [],
+                "skip_directories": no_unwanted_files_skip_directories or [],
+                "yaml_directories": no_unwanted_files_yaml_directories
+                or ["plugins/test/", "plugins/filter/"],
+                "allow_symlinks": no_unwanted_files_allow_symlinks,
+            },
+        )
+
+    def execute_action_groups(session: nox.Session) -> None:
+        if action_groups_config is None:
+            session.warn("Skipping action-groups since config is not provided...")
+            return
+        run_bare_script(
+            session,
+            "action-groups",
+            extra_data={
+                "config": [asdict(cfg) for cfg in action_groups_config],
+            },
+        )
+
+    def extra_checks(session: nox.Session) -> None:
+        if run_no_unwanted_files:
+            execute_no_unwanted_files(session)
+        if run_action_groups:
+            execute_action_groups(session)
+
+    extra_checks.__doc__ = compose_description(
+        prefix={
+            "one": "Run extra checker:",
+            "other": "Run extra checkers:",
+        },
+        programs={
+            "no-unwanted-files": (
+                "checks for unwanted files in plugins/"
+                if run_no_unwanted_files
+                else False
+            ),
+            "action-groups": "validate action groups" if run_action_groups else False,
+        },
+    )
+    nox.session(
+        name="extra-checks",
+        python=False,
+        default=make_extra_checks_default,
+    )(extra_checks)
+
+
+__all__ = [
+    "ActionGroup",
+    "add_extra_checks",
+]

antsibull_nox/sessions/license_check.py

@@ -0,0 +1,73 @@
+# 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
+
+"""
+Create nox license check session.
+"""
+
+from __future__ import annotations
+
+import nox
+
+from .utils import (
+    compose_description,
+    install,
+    run_bare_script,
+)
+
+
+def add_license_check(
+    *,
+    make_license_check_default: bool = True,
+    run_reuse: bool = True,
+    reuse_package: str = "reuse",
+    run_license_check: bool = True,
+    license_check_extra_ignore_paths: list[str] | None = None,
+) -> None:
+    """
+    Add license-check session for license checks.
+    """
+
+    def compose_dependencies() -> list[str]:
+        deps = []
+        if run_reuse:
+            deps.append(reuse_package)
+        return deps
+
+    def license_check(session: nox.Session) -> None:
+        install(session, *compose_dependencies())
+        if run_reuse:
+            session.run("reuse", "lint")
+        if run_license_check:
+            run_bare_script(
+                session,
+                "license-check",
+                extra_data={
+                    "extra_ignore_paths": license_check_extra_ignore_paths or [],
+                },
+            )
+
+    license_check.__doc__ = compose_description(
+        prefix={
+            "one": "Run license checker:",
+            "other": "Run license checkers:",
+        },
+        programs={
+            "reuse": run_reuse,
+            "license-check": (
+                "ensure GPLv3+ for plugins" if run_license_check else False
+            ),
+        },
+    )
+    nox.session(
+        name="license-check",
+        default=make_license_check_default,
+    )(license_check)
+
+
+__all__ = [
+    "add_license_check",
+]