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

antsibull_nox/__init__.py

@@ -10,71 +10,27 @@ Antsibull Nox Helper.
 
 from __future__ import annotations
 
-from .collection import CollectionSource, setup_collection_sources
-from .config import load_config_from_toml
-from .interpret_config import interpret_config
-from .sessions import (
-    ActionGroup,
-    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_ansible_test_sanity_test_session,
-    add_ansible_test_session,
-    add_ansible_test_unit_test_session,
-    add_build_import_check,
-    add_docs_check,
-    add_extra_checks,
-    add_license_check,
-    add_lint_sessions,
-    add_matrix_generator,
+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.2.0"
-
-
-def setup(
-    *,
-    collection_sources: dict[str, str | CollectionSource] | None = None,
-) -> None:
-    """
-    Set-up antsibull-nox.
-    """
-    if collection_sources:
-        setup_collection_sources(
-            {
-                name: CollectionSource.parse(name, source)
-                for name, source in collection_sources.items()
-            }
-        )
+__version__ = "0.3.0"
 
 
 def load_antsibull_nox_toml() -> None:
     """
     Load and interpret antsibull-nox.toml config file.
     """
-    config = load_config_from_toml("antsibull-nox.toml")
+    config = load_config_from_toml(CONFIG_FILENAME)
     interpret_config(config)
 
 
 # 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",
-    "add_ansible_test_sanity_test_session",
-    "add_all_ansible_test_sanity_test_sessions",
-    "add_ansible_test_unit_test_session",
-    "add_all_ansible_test_unit_test_sessions",
-    "add_ansible_test_integration_sessions_default_container",
-    "add_ansible_lint",
-    "add_matrix_generator",
-    "CollectionSource",
-    "setup",
     "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/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

@@ -21,7 +21,7 @@ from .install import (
     setup_collections,
     setup_current_tree,
 )
-from .search import CollectionList, load_collection_data_from_disk
+from .search import GALAXY_YML, CollectionList, load_collection_data_from_disk
 
 
 def force_collection_version(path: Path, *, version: str) -> bool:
@@ -31,7 +31,7 @@ def force_collection_version(path: Path, *, version: str) -> bool:
     Returns ``True`` if the version was changed, and ``False`` if the version
     was already set to this value.
     """
-    galaxy_yml = path / "galaxy.yml"
+    galaxy_yml = path / GALAXY_YML
     try:
         data = load_yaml_file(galaxy_yml)
     except Exception as exc:

antsibull_nox/collection/search.py

@@ -28,6 +28,10 @@ from .data import CollectionData
 Runner = t.Callable[[list[str]], tuple[bytes, bytes]]
 
 
+GALAXY_YML = "galaxy.yml"
+MANIFEST_JSON = "MANIFEST.json"
+
+
 @dataclass(frozen=True)
 class _GlobalCache:
     root: Path
@@ -80,19 +84,19 @@ def load_collection_data_from_disk(
     """
     Load collection data from disk.
     """
-    galaxy_yml = path / "galaxy.yml"
-    manifest_json = path / "MANIFEST.json"
+    galaxy_yml = path / GALAXY_YML
+    manifest_json = path / MANIFEST_JSON
     found: Path
     if galaxy_yml.is_file():
         found = galaxy_yml
         data = _load_galaxy_yml(galaxy_yml)
     elif not accept_manifest:
-        raise ValueError(f"Cannot find galaxy.yml in {path}")
+        raise ValueError(f"Cannot find {GALAXY_YML} in {path}")
     elif manifest_json.is_file():
         found = manifest_json
         data = _load_manifest_json_collection_info(manifest_json)
     else:
-        raise ValueError(f"Cannot find galaxy.yml or MANIFEST.json in {path}")
+        raise ValueError(f"Cannot find {GALAXY_YML} or {MANIFEST_JSON} in {path}")
 
     ns = data.get("namespace")
     if not isinstance(ns, str):

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,7 @@ class Config(_BaseModel):
     The contents of a antsibull-nox config file.
     """
 
-    collection_sources: dict[str, CollectionSource] = {}
+    collection_sources: dict[CollectionName, CollectionSource] = {}
     sessions: Sessions = Sessions()
 
 
@@ -330,3 +353,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/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

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import ast
 import io
+import os
 import re
 import sys
 import traceback
@@ -219,6 +220,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
 
 
@@ -116,6 +118,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 +175,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 +192,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(