netadopt 0.1.0__py3-none-any.whl

netadopt/__init__.py

@@ -0,0 +1,2 @@
+# The avd submodule's tag, and pyavd's pin in the dev group.
+AVD_TESTED = "6.4.0"

netadopt/ansible.py

@@ -0,0 +1,144 @@
+"""Finding the Ansible to run.
+
+PATH first, the `ansible` extra behind it; `source` says which one answered.
+The answer is always a value -- never an exception, never sys.exit.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, replace
+from pathlib import Path
+
+# Probed rather than `ansible`: it is the one being run, and on a broken install the
+# two do not always agree.
+PLAYBOOK_EXE = "ansible-playbook"
+
+_CORE = re.compile(r"\[core ([^\]]+)\]")          # 2.10+  "ansible-playbook [core 2.16.3]"
+_OLD = re.compile(r"^\S+\s+([0-9][^\s]*)")        # 2.9    "ansible-playbook 2.9.27"
+
+
+@dataclass(frozen=True)
+class Ansible:
+    """What `ansible-playbook --version` said, or why it said nothing."""
+
+    exe: str | None = None
+    core: str | None = None
+    python: str | None = None
+    config_file: str | None = None
+    collections: tuple[str, ...] = ()
+    problem: str | None = None  # set if and only if unusable
+    source: str | None = None  # "given" | "PATH" | "bundled"
+
+    @property
+    def usable(self) -> bool:
+        return self.problem is None
+
+    def beside(self, name: str) -> Path | None:
+        """Another executable from this same install, or None if it is not there.
+
+        Taken from this install's own directory, not from PATH.
+        """
+        if self.exe is None:
+            return None
+        found = Path(self.exe).with_name(name)
+        return found if found.exists() else None
+
+    @property
+    def bundled(self) -> bool:
+        """True when the fallback answered, and not an Ansible already installed."""
+        return self.source == "bundled"
+
+
+def find_ansible(exe: str | None = None) -> Ansible:
+    """Locate an ansible-playbook and read its --version.
+
+    `exe` overrides PATH -- a name or a path; a venv is selected by pointing here.
+    """
+    target = exe or PLAYBOOK_EXE
+    found = shutil.which(target)
+    if found is None:
+        # a typed path and a name looked up on PATH fail for different reasons
+        where = "not found" if Path(target).name != target else "not found on PATH"
+        return Ansible(problem=f"{target} {where}")
+
+    try:
+        done = subprocess.run(
+            [found, "--version"],
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=60,
+            # closed, so a subprocess cannot stop for a prompt
+            stdin=subprocess.DEVNULL,
+        )
+    except OSError as err:  # not executable, wrong architecture, bad interpreter
+        return Ansible(exe=found, problem=f"{found} could not be run: {err}")
+    except subprocess.TimeoutExpired:
+        return Ansible(exe=found, problem=f"{found} --version did not return in 60s")
+
+    if done.returncode != 0:
+        # an install broken by its own dependencies fails here; its stderr, whole
+        detail = (done.stderr or done.stdout).strip() or f"exit {done.returncode}"
+        return Ansible(exe=found, problem=f"{found} --version failed: {detail}")
+
+    return _parse(found, done.stdout)
+
+
+def resolve_ansible(exe: str | None = None) -> Ansible:
+    """PATH first, the bundled ansible-core second."""
+    if exe:
+        return replace(find_ansible(exe), source="given")
+
+    found = find_ansible()
+    if found.usable:
+        return replace(found, source="PATH")
+
+    # The extra installs ansible-playbook beside this interpreter. Under uvx that
+    # directory need not be on PATH, so it is found by location and not by name.
+    bundled = Path(sys.executable).parent / PLAYBOOK_EXE
+    if not bundled.exists():
+        return found  # keep the PATH problem: with no fallback it is the one to report
+    return replace(find_ansible(str(bundled)), source="bundled")
+
+
+def _parse(exe: str, out: str) -> Ansible:
+    lines = out.splitlines()
+    head = lines[0] if lines else ""
+    match = _CORE.search(head) or _OLD.match(head)
+    core = match.group(1) if match else None
+
+    # The rest is "  key = value", and unknown keys are ignored rather than
+    # rejected: the set has changed across releases and will change again.
+    fields: dict[str, str] = {}
+    for line in lines[1:]:
+        key, sep, value = line.partition("=")
+        if sep:
+            fields[key.strip()] = value.strip()
+
+    python = fields.get("python version", "").split(" ", 1)[0] or None
+    config = fields.get("config file") or None
+    if config == "None":  # Ansible's own word for "no ansible.cfg was found"
+        config = None
+    # "ansible collection location", with the prefix -- unlike "config file".
+    raw = fields.get("ansible collection location", "")
+    collections = tuple(p for p in raw.split(":") if p)
+
+    if core is None:
+        return Ansible(
+            exe=exe,
+            python=python,
+            config_file=config,
+            collections=collections,
+            problem=f"could not read a version from: {head!r}",
+        )
+    return Ansible(
+        exe=exe,
+        core=core,
+        python=python,
+        config_file=config,
+        collections=collections,
+    )

netadopt/ansible_yaml.py

@@ -0,0 +1,80 @@
+"""Reading and writing YAML the way Ansible does.
+
+`!vault` and `!unsafe` are Ansible's, and `yaml.safe_load` raises on both. Here they
+become the shapes `ansible-inventory --list` prints: {"__ansible_vault": ...} and
+{"__ansible_unsafe": ...}. `dump` writes those shapes back as the tags.
+
+Any other tag still raises, with its name and the line it is on.
+"""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+import yaml
+
+VAULT_KEY = "__ansible_vault"
+UNSAFE_KEY = "__ansible_unsafe"
+
+
+class AnsibleLoader(yaml.SafeLoader):
+    """SafeLoader plus the two tags Ansible puts in ordinary vars files."""
+
+
+def _vault(loader: AnsibleLoader, node: yaml.Node) -> dict[str, str]:
+    # the ciphertext, whole -- carrying it needs no password
+    return {VAULT_KEY: loader.construct_scalar(node)}
+
+
+def _unsafe(loader: AnsibleLoader, node: yaml.Node) -> dict[str, str]:
+    # !unsafe means "do not template this". Losing the marker would turn a literal
+    # {{ ... }} into something Ansible would try to resolve.
+    return {UNSAFE_KEY: loader.construct_scalar(node)}
+
+
+AnsibleLoader.add_constructor("!vault", _vault)
+AnsibleLoader.add_constructor("!unsafe", _unsafe)
+
+
+def load(text: str, path: Path | str | None = None) -> object:
+    """Parse one document. Raises yaml.YAMLError, naming `path` in the message."""
+    stream = io.StringIO(text)
+    if path is not None:
+        # PyYAML reports the stream name in its error marks: the filename, not
+        # "<unicode string>".
+        stream.name = str(path)
+    return yaml.load(stream, AnsibleLoader)
+
+
+class AnsibleDumper(yaml.SafeDumper):
+    """SafeDumper writing the two shapes `load` makes back as Ansible's tags."""
+
+    def ignore_aliases(self, data: object) -> bool:
+        # an object met twice is written twice, never as &anchor and *alias
+        return True
+
+
+def _mapping(dumper: AnsibleDumper, data: dict) -> yaml.Node:
+    if len(data) == 1:
+        ((key, value),) = data.items()
+        if key == VAULT_KEY and isinstance(value, str):
+            return dumper.represent_scalar("!vault", value, style="|")
+        if key == UNSAFE_KEY and isinstance(value, str):
+            return dumper.represent_scalar("!unsafe", value)
+    return dumper.represent_dict(data)
+
+
+AnsibleDumper.add_representer(dict, _mapping)
+
+
+def dump(data: object) -> str:
+    """One document, keys in their own order, long strings never folded."""
+    return yaml.dump(
+        data,
+        Dumper=AnsibleDumper,
+        sort_keys=False,
+        allow_unicode=True,
+        default_flow_style=False,
+        width=float("inf"),
+    )

netadopt/ansiblecfg.py

@@ -0,0 +1,74 @@
+"""ansible.cfg as the repository writes it, for `Fabric.spec.ansibleCfg`.
+
+The one in the repository's root, and only that one: it is where Ansible looks when
+run in the repository. `ANSIBLE_CONFIG`, `~/.ansible.cfg` and `/etc/ansible/ansible.cfg`
+belong to whoever runs it.
+
+Parsed as Ansible parses it -- stdlib configparser, `;` as an inline comment, keys
+folded to lower case, a duplicate key an error -- so a value here is the value Ansible
+reads. Two settings keep the text as written: no interpolation, so a `%(name)s` is
+left for Ansible to expand; and `[DEFAULT]` stays a section of its own instead of
+being copied into every other one.
+"""
+
+from __future__ import annotations
+
+import configparser
+from dataclasses import dataclass, field
+from pathlib import Path
+
+CONFIG_FILE = "ansible.cfg"
+
+
+@dataclass(frozen=True)
+class AnsibleCfg:
+    path: Path | None = None  # None when the repository has no ansible.cfg
+    sections: dict[str, dict[str, str]] = field(default_factory=dict)
+    problem: str | None = None
+
+    @property
+    def usable(self) -> bool:
+        return self.problem is None
+
+    @property
+    def inventory(self) -> tuple[str, ...]:
+        """The sources `[defaults] inventory` names, split on commas as Ansible splits them."""
+        raw = self.sections.get("defaults", {}).get("inventory", "")
+        return tuple(part.strip() for part in raw.split(",") if part.strip())
+
+    @property
+    def vault_password_file(self) -> str | None:
+        """The path `[defaults] vault_password_file` names, as written."""
+        return self.sections.get("defaults", {}).get("vault_password_file") or None
+
+
+def read_ansible_cfg(repo: Path) -> AnsibleCfg:
+    """`repo/ansible.cfg`, section by section, every value the string it is written as.
+
+    No file is not a problem: Ansible then runs on its defaults, and `sections` is empty.
+    """
+    path = repo / CONFIG_FILE
+    if not path.is_file():
+        return AnsibleCfg()
+
+    try:
+        text = path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as err:
+        return AnsibleCfg(path=path, problem=f"{path} is not UTF-8: {err}")
+    except OSError as err:
+        return AnsibleCfg(path=path, problem=f"{path} could not be read: {err}")
+
+    parser = configparser.ConfigParser(
+        inline_comment_prefixes=(";",),
+        interpolation=None,
+        # A section header is never empty, so no section is the default one.
+        default_section="",
+    )
+    try:
+        parser.read_string(text, source=str(path))
+    except configparser.Error as err:
+        # what Ansible stops on as well: a duplicate key, a line before any section
+        return AnsibleCfg(path=path, problem=str(err).replace("\n", " "))
+
+    sections = {name: dict(parser[name]) for name in parser.sections()}
+    return AnsibleCfg(path=path, sections=sections)