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

antsibull_nox/sessions/build_import_check.py

@@ -0,0 +1,147 @@
+# 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 build import check session.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+import nox
+
+from ..collection import (
+    force_collection_version,
+    load_collection_data_from_disk,
+)
+from ..paths import (
+    copy_collection,
+    remove_path,
+)
+from .utils import (
+    ci_group,
+    compose_description,
+    install,
+    nox_has_verbosity,
+    silence_run_verbosity,
+)
+
+
+def add_build_import_check(
+    *,
+    make_build_import_check_default: bool = True,
+    ansible_core_package: str = "ansible-core",
+    run_galaxy_importer: bool = True,
+    galaxy_importer_package: str = "galaxy-importer",
+    galaxy_importer_config_path: (
+        str | os.PathLike | None
+    ) = None,  # https://github.com/ansible/galaxy-importer#configuration
+    galaxy_importer_always_show_logs: bool = False,
+) -> None:
+    """
+    Add license-check session for license checks.
+    """
+
+    def compose_dependencies() -> list[str]:
+        deps = [ansible_core_package]
+        if run_galaxy_importer:
+            deps.append(galaxy_importer_package)
+        return deps
+
+    def build_import_check(session: nox.Session) -> None:
+        install(session, *compose_dependencies())
+
+        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}")
+
+        if run_galaxy_importer and tarball.is_file():
+            env = {}
+            if galaxy_importer_config_path:
+                env["GALAXY_IMPORTER_CONFIG"] = str(
+                    Path(galaxy_importer_config_path).absolute()
+                )
+            with session.chdir(collection_dir), silence_run_verbosity():
+                import_log = session.run(
+                    "python",
+                    "-m",
+                    "galaxy_importer.main",
+                    tarball.name,
+                    env=env,
+                    silent=True,
+                )
+            if import_log is not None:
+                with ci_group("Run Galaxy importer") as (indent, is_collapsed):
+                    if (
+                        is_collapsed
+                        or galaxy_importer_always_show_logs
+                        or nox_has_verbosity()
+                    ):
+                        for line in import_log.splitlines():
+                            print(f"{indent}{line}")
+                        sys.stdout.flush()
+                error_prefix = "ERROR:"
+                errors = []
+                for line in import_log.splitlines():
+                    if line.startswith(error_prefix):
+                        errors.append(line[len(error_prefix) :].strip())
+                if errors:
+                    messages = "\n".join(f"* {error}" for error in errors)
+                    session.warn(
+                        "Galaxy importer emitted the following non-fatal"
+                        f" error{'' if len(errors) == 1 else 's'}:\n{messages}"
+                    )
+
+    build_import_check.__doc__ = compose_description(
+        prefix={
+            "one": "Run build and import checker:",
+            "other": "Run build and import checkers:",
+        },
+        programs={
+            "build-collection": True,
+            "galaxy-importer": (
+                "test whether Galaxy will import built collection"
+                if run_galaxy_importer
+                else False
+            ),
+        },
+    )
+    nox.session(
+        name="build-import-check",
+        default=make_build_import_check_default,
+    )(build_import_check)
+
+
+__all__ = [
+    "add_build_import_check",
+]

antsibull_nox/sessions/collections.py

@@ -0,0 +1,137 @@
+# 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 ..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,
+    *,
+    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.
+    """
+    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,
+        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",
+]