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

antsibull_nox/__init__.py

@@ -10,24 +10,27 @@ Antsibull Nox Helper.
 
 from __future__ import annotations
 
-from .sessions import (
-    ActionGroup,
-    add_build_import_check,
-    add_docs_check,
-    add_extra_checks,
-    add_license_check,
-    add_lint_sessions,
+from .config import (
+    CONFIG_FILENAME,
+    load_config_from_toml,
 )
+from .interpret_config import interpret_config
+from .sessions.ansible_test import add_ansible_test_session
+
+__version__ = "0.3.0"
+
+
+def load_antsibull_nox_toml() -> None:
+    """
+    Load and interpret antsibull-nox.toml config file.
+    """
+    config = load_config_from_toml(CONFIG_FILENAME)
+    interpret_config(config)
 
-__version__ = "0.1.0"
 
 # pylint:disable=duplicate-code
 __all__ = (
     "__version__",
-    "ActionGroup",
-    "add_build_import_check",
-    "add_docs_check",
-    "add_extra_checks",
-    "add_license_check",
-    "add_lint_sessions",
+    "add_ansible_test_session",
+    "load_antsibull_nox_toml",
 )

antsibull_nox/_pydantic.py

@@ -0,0 +1,98 @@
+# 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: Ansible Project, 2024
+
+# ========================================================================
+# **Vendored** from antsibull-core.
+#
+# I vendored this to avoid depending on antsibull-core only for this.
+# TBH, most of this should be part of pydantic anyway. See
+# https://github.com/pydantic/pydantic/discussions/2652 for a discussion
+# on this.
+#
+# pylint: disable=missing-function-docstring
+# ========================================================================
+
+"""
+Helpers for pydantic.
+"""
+
+from __future__ import annotations
+
+import typing as t
+from collections.abc import Callable, Collection
+
+import pydantic as p
+
+if t.TYPE_CHECKING:
+    from typing_extensions import TypeGuard
+
+
+def _is_basemodel(a_type: t.Any) -> TypeGuard[type[p.BaseModel]]:
+    try:
+        return issubclass(a_type, p.BaseModel)
+    except TypeError:
+        # If inspect.isclass(a_type) is checked first, no TypeError happens for
+        # Python 3.11+.
+
+        # On Python 3.9 and 3.10, issubclass(dict[int, int], p.BaseModel) raises
+        # "TypeError: issubclass() arg 1 must be a class".
+        # (https://github.com/pydantic/pydantic/discussions/5970)
+        return False
+
+
+def _modify_config(
+    cls: type[p.BaseModel],
+    processed_classes: set[type[p.BaseModel]],
+    change_config: Callable[[p.ConfigDict], bool],
+) -> bool:
+    if cls in processed_classes:
+        return False
+    change = False
+    for field_info in cls.model_fields.values():
+        if _is_basemodel(field_info.annotation):
+            change |= _modify_config(
+                field_info.annotation,
+                processed_classes,
+                change_config,
+            )
+        for subcls in t.get_args(field_info.annotation):
+            if _is_basemodel(subcls):
+                change |= _modify_config(subcls, processed_classes, change_config)
+    change |= change_config(cls.model_config)
+    if change:
+        cls.model_rebuild(force=True)
+    processed_classes.add(cls)
+    return change
+
+
+def set_extras(
+    models: type[p.BaseModel] | Collection[type[p.BaseModel]],
+    value: t.Literal["allow", "ignore", "forbid"],
+) -> None:
+    def change_config(model_config: p.ConfigDict) -> bool:
+        if model_config.get("extra") == value:
+            return False
+        model_config["extra"] = value
+        return True
+
+    processed_classes: set[type[p.BaseModel]] = set()
+    if isinstance(models, Collection):
+        for cls in models:
+            _modify_config(cls, processed_classes, change_config)
+    else:
+        _modify_config(models, processed_classes, change_config)
+
+
+def forbid_extras(models: type[p.BaseModel] | Collection[type[p.BaseModel]]) -> None:
+    set_extras(models, "forbid")
+
+
+def get_formatted_error_messages(error: p.ValidationError) -> list[str]:
+    def format_error(err) -> str:
+        location = " -> ".join(str(loc) for loc in err["loc"])
+        return f'{location}: {err["msg"]}'
+
+    return [format_error(err) for err in error.errors()]

antsibull_nox/ansible.py

@@ -0,0 +1,260 @@
+# 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
+
+"""
+Ansible-core version utilities.
+"""
+
+from __future__ import annotations
+
+import functools
+import typing as t
+from dataclasses import dataclass
+
+from antsibull_fileutils.yaml import load_yaml_file
+from packaging.specifiers import SpecifierSet as PckgSpecifierSet
+from packaging.version import Version as PckgVersion
+
+from .utils import Version, version_range
+
+AnsibleCoreVersion = t.Union[Version, t.Literal["milestone", "devel"]]
+
+
+@dataclass(frozen=True)
+class AnsibleCoreInfo:
+    """
+    Information on an ansible-core version.
+    """
+
+    ansible_core_version: Version
+    controller_python_versions: tuple[Version, ...]
+    remote_python_versions: tuple[Version, ...]
+
+
+_SUPPORTED_CORE_VERSIONS: dict[Version, AnsibleCoreInfo] = {
+    Version.parse(ansible_version): AnsibleCoreInfo(
+        ansible_core_version=Version.parse(ansible_version),
+        controller_python_versions=tuple(
+            Version.parse(v) for v in controller_python_versions
+        ),
+        remote_python_versions=tuple(Version.parse(v) for v in remote_python_versions),
+    )
+    for ansible_version, (controller_python_versions, remote_python_versions) in {
+        "2.9": [
+            ["2.7", "3.5", "3.6", "3.7", "3.8"],
+            ["2.6", "2.7", "3.5", "3.6", "3.7", "3.8"],
+        ],
+        "2.10": [
+            ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9"],
+            ["2.6", "2.7", "3.5", "3.6", "3.7", "3.8", "3.9"],
+        ],
+        "2.11": [
+            ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9"],
+            ["2.6", "2.7", "3.5", "3.6", "3.7", "3.8", "3.9"],
+        ],
+        "2.12": [
+            ["3.8", "3.9", "3.10"],
+            ["2.6", "2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10"],
+        ],
+        "2.13": [
+            ["3.8", "3.9", "3.10"],
+            ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10"],
+        ],
+        "2.14": [
+            ["3.9", "3.10", "3.11"],
+            ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10", "3.11"],
+        ],
+        "2.15": [
+            ["3.9", "3.10", "3.11"],
+            ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10", "3.11"],
+        ],
+        "2.16": [
+            ["3.10", "3.11", "3.12"],
+            ["2.7", "3.6", "3.7", "3.8", "3.9", "3.10", "3.11", "3.12"],
+        ],
+        "2.17": [
+            ["3.10", "3.11", "3.12"],
+            ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"],
+        ],
+        "2.18": [
+            ["3.11", "3.12", "3.13"],
+            ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"],
+        ],
+        "2.19": [
+            ["3.11", "3.12", "3.13"],
+            ["3.8", "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"],
+        ],
+        "2.22": [
+            ["3.13", "3.14", "3.15"],
+            ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"],
+        ],
+        "2.23": [
+            ["3.13", "3.14", "3.15"],
+            ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"],
+        ],
+        "2.24": [
+            ["3.14", "3.15", "3.16"],
+            ["3.11", "3.12", "3.13", "3.14", "3.15", "3.16"],
+        ],
+        "2.25": [
+            ["3.14", "3.15", "3.16"],
+            ["3.11", "3.12", "3.13", "3.14", "3.15", "3.16"],
+        ],
+    }.items()
+}
+
+_MIN_SUPPORTED_VERSION = Version.parse("2.9")
+_CURRENT_DEVEL_VERSION = Version.parse("2.19")
+_CURRENT_MILESTONE_VERSION = Version.parse("2.19")
+
+
+def get_ansible_core_info(
+    core_version: AnsibleCoreVersion,
+) -> AnsibleCoreInfo:
+    """
+    Retrieve information on an ansible-core version.
+    """
+    version: Version
+    if core_version == "devel":
+        version = _CURRENT_DEVEL_VERSION
+    elif core_version == "milestone":
+        version = _CURRENT_MILESTONE_VERSION
+    else:
+        version = core_version
+    if version in _SUPPORTED_CORE_VERSIONS:
+        return _SUPPORTED_CORE_VERSIONS[version]
+    raise ValueError(f"Unknown ansible-core version {version}")
+
+
+_ANSIBLE_REPO = "ansible/ansible"
+_ANSIBLE_EOL_REPO = "ansible-community/eol-ansible"
+_ANSIBLE_EOL_MAX_VERSION = Version(2, 14)
+
+
+def get_ansible_core_package_name(
+    core_version: AnsibleCoreVersion,
+    *,
+    source: t.Literal["git", "pypi"] = "git",
+    ansible_repo: str | None = None,
+    branch_name: str | None = None,
+) -> str:
+    """
+    Return the package name for a specific ansible-core version.
+
+    The result can be passed to pip to install that version of ansible-core.
+    """
+    if not isinstance(core_version, Version):
+        # milestone and devel are not available from PyPI
+        source = "git"
+
+    if source == "git":
+        if branch_name is None:
+            if isinstance(core_version, str):
+                branch_name = core_version
+            else:
+                branch_name = f"stable-{core_version}"
+        if ansible_repo is None:
+            if (
+                isinstance(core_version, Version)
+                and core_version <= _ANSIBLE_EOL_MAX_VERSION
+            ):
+                ansible_repo = _ANSIBLE_EOL_REPO
+            else:
+                ansible_repo = _ANSIBLE_REPO
+        return f"https://github.com/{ansible_repo}/archive/{branch_name}.tar.gz"
+
+    assert isinstance(core_version, Version)
+    next_core_version = core_version.next_minor_version()
+    base = "ansible-core"
+    if core_version == Version(2, 9):
+        base = "ansible"
+    elif core_version == Version(2, 10):
+        base = "ansible-base"
+    return f"{base}>={core_version},<{next_core_version}"
+
+
+@functools.cache
+def _read_requires_ansible() -> PckgSpecifierSet:
+    path = "meta/runtime.yml"
+    try:
+        runtime_data = load_yaml_file(path)
+    except FileNotFoundError as exc:
+        raise ValueError(f"Cannot open {path}") from exc
+    except Exception as exc:
+        raise ValueError(f"Cannot parse {path}: {exc}") from exc
+
+    requires_ansible = runtime_data.get("requires_ansible")
+    if not isinstance(requires_ansible, str):
+        raise ValueError(f"{path} does not contain an 'requires_ansible' string")
+    try:
+        return PckgSpecifierSet(requires_ansible)
+    except Exception as exc:
+        raise ValueError(
+            f"{path} contains an invalid 'requires_ansible' string: {exc}"
+        ) from exc
+
+
+@functools.cache
+def get_supported_core_versions(
+    *,
+    include_devel: bool = False,
+    include_milestone: bool = False,
+    min_version: Version | None = None,
+    max_version: Version | None = None,
+    except_versions: tuple[AnsibleCoreVersion, ...] | None = None,
+) -> list[AnsibleCoreVersion]:
+    """
+    Extracts a list of supported ansible-core versions from meta/runtime.yml.
+
+    If ``min_version`` is specified, no version below that version will be returned.
+    If ``max_version`` is specified, no version above that version will be returned.
+    If ``except_versions`` is specified, no version in that tuple will be returned.
+    """
+    if except_versions is None:
+        except_versions = ()
+
+    ra_specifier = _read_requires_ansible()
+
+    result: list[AnsibleCoreVersion] = []
+    for version in version_range(
+        _MIN_SUPPORTED_VERSION, _CURRENT_DEVEL_VERSION, inclusive=False
+    ):
+        if version in except_versions:
+            continue
+        if min_version is not None and version < min_version:
+            continue
+        if max_version is not None and version > max_version:
+            continue
+        # We're using x.y.999 to check whether *some* ansible-core x.y version is supported.
+        # This is not entirely correct, since collections might specfiy that only certain older x.y
+        # versions are OK, but I'd consider such behavior a bug of the collection and something
+        # you really shouldn't do as a collection maintainer.
+        v = PckgVersion(f"{version.major}.{version.minor}.999")
+        if v in ra_specifier:
+            result.append(version)
+    if include_milestone and "milestone" not in except_versions:
+        result.append("milestone")
+    if include_devel and "devel" not in except_versions:
+        result.append("devel")
+    return result
+
+
+__all__ = [
+    "AnsibleCoreInfo",
+    "get_ansible_core_info",
+    "get_ansible_core_package_name",
+]

antsibull_nox/cli.py

@@ -0,0 +1,132 @@
+# 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
+
+# PYTHON_ARGCOMPLETE_OK
+
+"""Entrypoint to the antsibull-docs script."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import os.path
+import sys
+from collections.abc import Callable
+
+from . import __version__
+from .init import create_initial_config as _create_initial_config
+from .lint_config import lint_config as _lint_config
+
+try:
+    import argcomplete
+
+    HAS_ARGCOMPLETE = True
+except ImportError:
+    HAS_ARGCOMPLETE = False
+
+
+def lint_config(_: argparse.Namespace) -> int:
+    """
+    Lint antsibull-nox config file.
+    """
+    errors = _lint_config()
+    for error in errors:
+        print(error)
+    return 0 if len(errors) == 0 else 3
+
+
+def create_initial_config(_: argparse.Namespace) -> int:
+    """
+    Create noxfile.py and antsibull-nox.toml.
+    """
+    try:
+        _create_initial_config()
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        print(f"Error: {exc}", file=sys.stderr)
+        return 3
+    return 0
+
+
+# Mapping from command line subcommand names to functions which implement those.
+# The functions need to take a single argument, the processed list of args.
+ARGS_MAP: dict[str, Callable[[argparse.Namespace], int]] = {
+    "lint-config": lint_config,
+    "init": create_initial_config,
+}
+
+
+class InvalidArgumentError(Exception):
+    """
+    Error while parsing arguments.
+    """
+
+
+def parse_args(program_name: str, args: list[str]) -> argparse.Namespace:
+    """
+    Parse the command line arguments.
+    """
+
+    toplevel_parser = argparse.ArgumentParser(
+        prog=program_name,
+        description="Script to manage generated documentation for ansible",
+    )
+    toplevel_parser.add_argument(
+        "--version",
+        action="version",
+        version=__version__,
+        help="Print the antsibull-nox version",
+    )
+    subparsers = toplevel_parser.add_subparsers(
+        title="Subcommands", dest="command", help="for help use: `SUBCOMMANDS -h`"
+    )
+    subparsers.required = True
+
+    subparsers.add_parser(
+        "lint-config",
+        description="Lint antsibull-nox configuration file",
+    )
+
+    subparsers.add_parser(
+        "init",
+        description="Create noxfile and antsibull-nox configuration file",
+    )
+
+    # This must come after all parser setup
+    if HAS_ARGCOMPLETE:
+        argcomplete.autocomplete(toplevel_parser)
+
+    parsed_args: argparse.Namespace = toplevel_parser.parse_args(args)
+    return parsed_args
+
+
+def run(args: list[str]) -> int:
+    """
+    Run the program.
+    """
+    program_name = os.path.basename(args[0])
+    try:
+        parsed_args: argparse.Namespace = parse_args(program_name, args[1:])
+    except InvalidArgumentError as e:
+        print(e, file=sys.stderr)
+        return 2
+
+    return ARGS_MAP[parsed_args.command](parsed_args)
+
+
+def main() -> int:
+    """
+    Entrypoint called from the script.
+
+    Return codes:
+        :0: Success
+        :1: Unhandled error.  See the Traceback for more information.
+        :2: There was a problem with the command line arguments
+    """
+    return run(sys.argv)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

antsibull_nox/collection/__init__.py

@@ -0,0 +1,56 @@
+# 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
+
+"""
+Handle Ansible collections.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from antsibull_fileutils.yaml import load_yaml_file, store_yaml_file
+
+from .data import CollectionData, CollectionSource, SetupResult
+from .install import (
+    Runner,
+    setup_collection_sources,
+    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
+
+
+__all__ = [
+    "CollectionData",
+    "CollectionList",
+    "CollectionSource",
+    "SetupResult",
+    "Runner",
+    "load_collection_data_from_disk",
+    "setup_collections",
+    "setup_current_tree",
+    "setup_collection_sources",
+]

antsibull_nox/collection/data.py

@@ -0,0 +1,106 @@
+# 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
+
+"""
+Data types for collections.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class CollectionData:  # pylint: disable=too-many-instance-attributes
+    """
+    An Ansible collection.
+    """
+
+    collections_root_path: Path | None
+    path: Path
+    namespace: str
+    name: str
+    full_name: str
+    version: str | None
+    dependencies: dict[str, str]
+    current: bool
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        collections_root_path: Path | None = None,
+        path: Path,
+        full_name: str,
+        version: str | None = None,
+        dependencies: dict[str, str] | None = None,
+        current: bool = False,
+    ):
+        """
+        Create a CollectionData object.
+        """
+        namespace, name = full_name.split(".", 1)
+        return CollectionData(
+            collections_root_path=collections_root_path,
+            path=path,
+            namespace=namespace,
+            name=name,
+            full_name=full_name,
+            version=version,
+            dependencies=dependencies or {},
+            current=current,
+        )
+
+
+@dataclass
+class SetupResult:
+    """
+    Information on how the collections are set up.
+    """
+
+    # The path of the ansible_collections directory.
+    root: Path
+
+    # Data on the current collection (as in the repository).
+    current_collection: CollectionData
+
+    # If it was installed, the path of the current collection inside the collection tree below root.
+    current_path: Path | None
+
+
+@dataclass
+class CollectionSource:
+    """
+    Collection installation source.
+    """
+
+    # The collection's name
+    name: str
+
+    # The collection's installation source (can be passed to 'ansible-galaxy collection install')
+    source: str
+
+    @staticmethod
+    def parse(collection_name: str, source: str | CollectionSource) -> CollectionSource:
+        """
+        Parse a CollectionSource object.
+        """
+        if isinstance(source, str):
+            return CollectionSource(name=collection_name, source=source)
+
+        if source.name != collection_name:
+            raise ValueError(
+                f"Collection name should be {collection_name!r}, but is {source.name!r}"
+            )
+        return source
+
+
+__all__ = [
+    "CollectionData",
+    "SetupResult",
+    "CollectionSource",
+]