diffnc 0.0.1__py3-none-any.whl

diffnc/diff.py

@@ -0,0 +1,353 @@
+"""Structural diff engine.
+
+The algorithm walks two :class:`~diffnc.ir.ConfigTree`'s in parallel, computing per-level
+opcodes with :class:`difflib.SequenceMatcher` keyed on each node's ``line``. For matched
+sections we recurse so that only their *changed descendants* surface; the matched section
+header itself is emitted as a context line so the user can see the surrounding scope.
+
+Two flavours are exposed, both modelled on :mod:`difflib`:
+
+* :func:`unified_diff` — compact: only changed lines plus the section path leading to them
+  (and ``--- a`` / ``+++ b`` headers if file names are supplied).
+* :func:`ndiff` — verbose: every line is shown, prefixed with ``- ``, ``+ `` or ``  ``.
+
+Both functions accept either ``str`` (raw config text) or ``list[str]`` (already-split
+lines, joined internally) for parity with :mod:`difflib`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+
+from diffnc import vendors as _vendors
+from diffnc.detect import detect_vendor
+from diffnc.errors import VendorMismatchError
+from diffnc.ir import ConfigNode, ConfigTree
+from diffnc.vendors.base import VendorParser, is_order_sensitive_for, render_subtree
+
+
+@dataclass(frozen=True)
+class _Event:
+    op: str  # one of ' ', '-', '+', '!'
+    text: str  # already-indented line, no marker prefix
+
+
+def unified_diff(
+    a: str | Iterable[str],
+    b: str | Iterable[str],
+    fromfile: str = "",
+    tofile: str = "",
+    lineterm: str = "",
+    *,
+    vendor: str | None = None,
+) -> Iterator[str]:
+    """Yield a structural unified diff of *a* vs *b*.
+
+    Equal leaves are omitted; only changed lines are shown, along with the path of
+    enclosing sections (as ``  `` context lines) so the diff stays readable.
+
+    Args:
+        a, b: configuration text. ``str`` is taken verbatim; an iterable of strings is
+            joined with newlines before parsing.
+        fromfile, tofile: optional file names rendered as ``--- a`` / ``+++ b`` headers.
+        lineterm: line terminator appended to each yielded line. Defaults to the empty
+            string; callers that need newline-terminated lines should pass ``"\\n"``.
+        vendor: skip auto-detection and force a specific parser. Ignored when unset.
+
+    Raises:
+        VendorMismatchError, ParseError: see :mod:`diffnc.errors`.
+    """
+
+    events = _structural_events(a, b, vendor=vendor)
+    if not events:
+        return
+
+    if fromfile or tofile:
+        yield f"--- {fromfile}{lineterm}"
+        yield f"+++ {tofile}{lineterm}"
+    for ev in events:
+        yield f"{ev.op}{ev.text}{lineterm}"
+
+
+def ndiff(
+    a: str | Iterable[str],
+    b: str | Iterable[str],
+    lineterm: str = "",
+    *,
+    vendor: str | None = None,
+) -> Iterator[str]:
+    """Yield a verbose, every-line diff using ``- ``/``+ ``/``! ``/``  `` markers.
+
+    ``lineterm`` defaults to the empty string; pass ``"\\n"`` for newline-terminated
+    output.
+    """
+
+    parser, tree_a, tree_b = _prepare(a, b, vendor=vendor)
+    events = list(
+        _diff_children(parser, tree_a.root, tree_b.root, depth=0, hide_equal=False, path=())
+    )
+    for ev in events:
+        marker = f"{ev.op} " if ev.op != " " else "  "
+        yield f"{marker}{ev.text}{lineterm}"
+
+
+# ---------------------------------------------------------------------------
+# internals
+# ---------------------------------------------------------------------------
+
+
+def _structural_events(
+    a: str | Iterable[str],
+    b: str | Iterable[str],
+    *,
+    vendor: str | None,
+) -> list[_Event]:
+    parser, tree_a, tree_b = _prepare(a, b, vendor=vendor)
+    return list(_diff_children(parser, tree_a.root, tree_b.root, depth=0, hide_equal=True, path=()))
+
+
+def _prepare(
+    a: str | Iterable[str],
+    b: str | Iterable[str],
+    *,
+    vendor: str | None,
+) -> tuple[VendorParser, ConfigTree, ConfigTree]:
+    text_a = _coerce(a)
+    text_b = _coerce(b)
+
+    if vendor is None:
+        vendor_a = detect_vendor(text_a)
+        vendor_b = detect_vendor(text_b)
+        if vendor_a != vendor_b:
+            raise VendorMismatchError(vendor_a, vendor_b)
+        vendor_name = vendor_a
+    else:
+        vendor_name = vendor
+
+    parser = _vendors.get(vendor_name)
+    tree_a = parser.parse(text_a)
+    tree_b = parser.parse(text_b)
+    return parser, tree_a, tree_b
+
+
+def _coerce(value: str | Iterable[str]) -> str:
+    if isinstance(value, str):
+        return value
+    return "\n".join(value)
+
+
+def _diff_children(
+    parser: VendorParser,
+    node_a: ConfigNode,
+    node_b: ConfigNode,
+    depth: int,
+    *,
+    hide_equal: bool,
+    path: tuple[str, ...],
+) -> Iterator[_Event]:
+    if is_order_sensitive_for(parser, path):
+        yield from _diff_children_ordered(
+            parser, node_a, node_b, depth, hide_equal=hide_equal, path=path
+        )
+    else:
+        yield from _diff_children_unordered(
+            parser, node_a, node_b, depth, hide_equal=hide_equal, path=path
+        )
+
+
+def _diff_children_ordered(
+    parser: VendorParser,
+    node_a: ConfigNode,
+    node_b: ConfigNode,
+    depth: int,
+    *,
+    hide_equal: bool,
+    path: tuple[str, ...],
+) -> Iterator[_Event]:
+    """Positional matching via :class:`difflib.SequenceMatcher`.
+
+    Used for parents whose children's evaluation order is semantically meaningful — e.g.
+    Junos ``firewall filter`` terms, Cisco ``ip access-list`` ACEs, ``policy-map`` class
+    blocks. Pure reorders (children whose rendered subtree is byte-identical on both
+    sides) surface once with the ``!`` marker; genuine changes still show as ``-``/``+``
+    pairs.
+    """
+
+    a_children = node_a.children
+    b_children = node_b.children
+    a_keys = [c.line for c in a_children]
+    b_keys = [c.line for c in b_children]
+    matcher = SequenceMatcher(a=a_keys, b=b_keys, autojunk=False)
+    opcodes = matcher.get_opcodes()
+
+    reordered_a, reordered_b = _collect_reorder_pairs(opcodes, a_children, b_children, parser)
+
+    for tag, i1, i2, j1, j2 in opcodes:
+        if tag == "equal":
+            for k in range(i2 - i1):
+                child_a = a_children[i1 + k]
+                child_b = b_children[j1 + k]
+                yield from _equal_pair(parser, child_a, child_b, depth, hide_equal, path)
+        elif tag == "delete":
+            for k in range(i1, i2):
+                op = "!" if k in reordered_a else "-"
+                yield from _emit_one_side(parser, a_children[k], depth, op)
+        elif tag == "insert":
+            for k in range(j1, j2):
+                if k in reordered_b:
+                    continue
+                yield from _emit_one_side(parser, b_children[k], depth, "+")
+        elif tag == "replace":
+            a_indices = list(range(i1, i2))
+            b_indices = [k for k in range(j1, j2) if k not in reordered_b]
+            for step in range(max(len(a_indices), len(b_indices))):
+                if step < len(a_indices):
+                    ka = a_indices[step]
+                    op = "!" if ka in reordered_a else "-"
+                    yield from _emit_one_side(parser, a_children[ka], depth, op)
+                if step < len(b_indices):
+                    kb = b_indices[step]
+                    yield from _emit_one_side(parser, b_children[kb], depth, "+")
+
+
+def _collect_reorder_pairs(
+    opcodes: Sequence[tuple[str, int, int, int, int]],
+    a_children: list[ConfigNode],
+    b_children: list[ConfigNode],
+    parser: VendorParser,
+) -> tuple[set[int], set[int]]:
+    """Find delete/insert pairs whose subtrees render identically — i.e. pure reorders.
+
+    Returns ``(reordered_a_indices, reordered_b_indices)``. The A-side index is where
+    we will emit a single ``!`` line; the B-side index marks the matching insert that
+    should be suppressed.
+    """
+
+    a_indices: list[int] = []
+    b_indices: list[int] = []
+    for tag, i1, i2, j1, j2 in opcodes:
+        if tag in ("delete", "replace"):
+            a_indices.extend(range(i1, i2))
+        if tag in ("insert", "replace"):
+            b_indices.extend(range(j1, j2))
+
+    b_by_render: dict[tuple[str, ...], list[int]] = {}
+    for idx in b_indices:
+        key = tuple(render_subtree(parser, b_children[idx], 0))
+        b_by_render.setdefault(key, []).append(idx)
+
+    reordered_a: set[int] = set()
+    reordered_b: set[int] = set()
+    for idx in a_indices:
+        key = tuple(render_subtree(parser, a_children[idx], 0))
+        bucket = b_by_render.get(key)
+        if bucket:
+            reordered_a.add(idx)
+            reordered_b.add(bucket.pop(0))
+    return reordered_a, reordered_b
+
+
+def _diff_children_unordered(
+    parser: VendorParser,
+    node_a: ConfigNode,
+    node_b: ConfigNode,
+    depth: int,
+    *,
+    hide_equal: bool,
+    path: tuple[str, ...],
+) -> Iterator[_Event]:
+    """Set-like matching keyed on ``line``, interleaved by position.
+
+    Within a parent, the IR guarantees each child has a unique ``line`` (same-named
+    siblings are merged on parse), so we can pair children by key. Matching stays
+    order-insensitive (pure reorders produce no diff), but the display walks ``a`` and
+    splices in ``b``-only children at their natural position — i.e. before the next
+    matched anchor — so ``-`` / ``+`` lines surface near each other instead of clumping
+    at the start and end.
+    """
+
+    a_children = node_a.children
+    b_children = node_b.children
+    b_by_line = {child.line: child for child in b_children}
+    common = {child.line for child in a_children} & set(b_by_line)
+    b_match_index = {
+        child.line: idx for idx, child in enumerate(b_children) if child.line in common
+    }
+
+    b_pointer = 0
+    for child_a in a_children:
+        if child_a.line not in common:
+            yield from _emit_one_side(parser, child_a, depth, "-")
+            continue
+        b_pos = b_match_index[child_a.line]
+        if b_pos >= b_pointer:
+            for k in range(b_pointer, b_pos):
+                child_b = b_children[k]
+                if child_b.line not in common:
+                    yield from _emit_one_side(parser, child_b, depth, "+")
+            b_pointer = b_pos + 1
+        yield from _equal_pair(parser, child_a, b_by_line[child_a.line], depth, hide_equal, path)
+
+    for k in range(b_pointer, len(b_children)):
+        child_b = b_children[k]
+        if child_b.line not in common:
+            yield from _emit_one_side(parser, child_b, depth, "+")
+
+
+def _equal_pair(
+    parser: VendorParser,
+    child_a: ConfigNode,
+    child_b: ConfigNode,
+    depth: int,
+    hide_equal: bool,
+    path: tuple[str, ...],
+) -> Iterator[_Event]:
+    a_is_section = not child_a.is_leaf
+    b_is_section = not child_b.is_leaf
+
+    if not a_is_section and not b_is_section:
+        # Equal leaf at this level. Suppress in the compact view, show as context in ndiff.
+        if not hide_equal:
+            yield _Event(" ", parser.render_leaf(child_a, depth))
+        return
+
+    if a_is_section != b_is_section:
+        # One side became a section while the other stayed a leaf — emit as replace.
+        yield from _emit_one_side(parser, child_a, depth, "-")
+        yield from _emit_one_side(parser, child_b, depth, "+")
+        return
+
+    # Both are sections with matching headers. Diff their children; only surface the section
+    # header if any descendant differs (compact mode) or always (ndiff).
+    inner = list(
+        _diff_children(
+            parser,
+            child_a,
+            child_b,
+            depth + 1,
+            hide_equal=hide_equal,
+            path=(*path, child_a.line),
+        )
+    )
+    has_change = any(ev.op != " " for ev in inner)
+
+    if not has_change and hide_equal:
+        return
+
+    yield _Event(" ", parser.render_open(child_a, depth))
+    yield from inner
+    close = parser.render_close(child_a, depth)
+    if close is not None:
+        yield _Event(" ", close)
+
+
+def _emit_one_side(
+    parser: VendorParser,
+    node: ConfigNode,
+    depth: int,
+    op: str,
+) -> Iterator[_Event]:
+    for line in render_subtree(parser, node, depth):
+        yield _Event(op, line)

diffnc/errors.py

@@ -0,0 +1,22 @@
+"""Exception types used across diffnc."""
+
+from __future__ import annotations
+
+
+class DiffncError(Exception):
+    """Base class for all diffnc errors."""
+
+
+class ParseError(DiffncError):
+    """Raised when a configuration cannot be parsed or its vendor cannot be detected."""
+
+
+class VendorMismatchError(DiffncError):
+    """Raised when two configurations belong to different vendors."""
+
+    def __init__(self, vendor_a: str, vendor_b: str) -> None:
+        super().__init__(
+            f"cannot diff configurations from different vendors: {vendor_a!r} vs {vendor_b!r}"
+        )
+        self.vendor_a = vendor_a
+        self.vendor_b = vendor_b

diffnc/ir.py

@@ -0,0 +1,58 @@
+"""Internal representation of a network configuration.
+
+A configuration is modelled as a tree of :class:`ConfigNode`. Each node carries one logical
+command line plus its (ordered) children. The whole document is wrapped in :class:`ConfigTree`
+which records the originating vendor so that the diff engine can later format output back
+in the input's flavour.
+
+The constructors in this module also implement the normalisation rules described in the plan:
+
+* Same-name non-leaf siblings get merged (their children concatenate).
+* Duplicate leaf siblings collapse to one occurrence.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ConfigNode:
+    """A single configuration statement, optionally with nested children."""
+
+    line: str
+    children: list[ConfigNode] = field(default_factory=list)
+
+    @property
+    def is_leaf(self) -> bool:
+        return not self.children
+
+    def add_child(self, child: ConfigNode) -> ConfigNode:
+        """Append *child* (or fold it into an existing same-named sibling) and return the
+        node that now represents it in the tree.
+
+        Indent-based vendors (e.g. NX-OS) can't tell at insertion time whether a line will
+        end up being a leaf or a section, so the merge rule is intentionally simple: any
+        sibling with the same ``line`` absorbs the new node's children. This collapses
+        repeated blocks (``interface eth1`` appearing twice) into one.
+        """
+
+        for sibling in self.children:
+            if sibling.line == child.line:
+                for grandchild in child.children:
+                    sibling.add_child(grandchild)
+                return sibling
+        self.children.append(child)
+        return child
+
+
+@dataclass
+class ConfigTree:
+    """A parsed configuration document."""
+
+    root: ConfigNode
+    vendor: str
+
+    @classmethod
+    def empty(cls, vendor: str) -> ConfigTree:
+        return cls(root=ConfigNode(line=""), vendor=vendor)

diffnc/reconcile.py

@@ -0,0 +1,132 @@
+"""Generate config-mode commands that transform config *A* into config *B*.
+
+Walks two :class:`~diffnc.ir.ConfigTree`'s in parallel and emits a stream of
+:class:`ReconcileEvent`'s — one per added subtree, deleted subtree, or order-sensitive
+section that needs to be recreated wholesale. Each vendor's :meth:`render_reconcile` then
+translates those events into its own CLI syntax (``no`` / ``set`` / ``delete`` ...).
+
+Output is intentionally bare config-mode commands: no ``configure terminal`` / ``end`` /
+``commit`` wrappers, no indentation. The caller is expected to pipe the result into a
+session that's already in config mode (e.g. ``... | ssh device 'configure terminal; ...'``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+
+from diffnc.diff import _prepare
+from diffnc.ir import ConfigNode
+from diffnc.vendors.base import VendorParser, is_order_sensitive_for, render_subtree
+
+
+@dataclass(frozen=True)
+class ReconcileAdd:
+    """A subtree present in *B* but not in *A* at ``parent_path``."""
+
+    parent_path: tuple[str, ...]
+    node: ConfigNode
+
+
+@dataclass(frozen=True)
+class ReconcileDelete:
+    """A subtree present in *A* but not in *B* at ``parent_path``."""
+
+    parent_path: tuple[str, ...]
+    node: ConfigNode
+
+
+@dataclass(frozen=True)
+class ReconcileRecreate:
+    """An order-sensitive section whose children differ — wipe and recreate.
+
+    ``section_path`` is the full path *including* the section to recreate (its last
+    element is the section header). ``new_node`` is the B-side parent node, whose
+    children become the new contents of the section.
+    """
+
+    section_path: tuple[str, ...]
+    new_node: ConfigNode
+
+
+ReconcileEvent = ReconcileAdd | ReconcileDelete | ReconcileRecreate
+
+
+def reconcile(
+    a: str | Iterable[str],
+    b: str | Iterable[str],
+    *,
+    vendor: str | None = None,
+) -> Iterator[str]:
+    """Yield config-mode commands that, when entered on a device running config *A*,
+    bring it to the state described by config *B*.
+
+    Output lines do not include a trailing newline; callers that need newline-terminated
+    output should append one themselves (mirrors :func:`diffnc.unified_diff`).
+
+    Raises:
+        VendorMismatchError, ParseError: see :mod:`diffnc.errors`.
+        NotImplementedError: if the resolved vendor parser does not implement
+            :meth:`~diffnc.vendors.base.VendorParser.render_reconcile`.
+    """
+
+    parser, tree_a, tree_b = _prepare(a, b, vendor=vendor)
+    events = list(_collect_events(parser, tree_a.root, tree_b.root, parent_path=()))
+    if not events:
+        return
+    render = getattr(parser, "render_reconcile", None)
+    if render is None:
+        raise NotImplementedError(f"vendor {parser.name!r} does not support command generation")
+    yield from render(events)
+
+
+# ---------------------------------------------------------------------------
+# internals
+# ---------------------------------------------------------------------------
+
+
+def _collect_events(
+    parser: VendorParser,
+    node_a: ConfigNode,
+    node_b: ConfigNode,
+    parent_path: tuple[str, ...],
+) -> Iterator[ReconcileEvent]:
+    """Diff two parent nodes' children and yield reconcile events.
+
+    Mirrors the order-insensitive matching used by :func:`diffnc.diff._diff_children`
+    but emits semantic events instead of display lines, and short-circuits any
+    order-sensitive subsection into a single :class:`ReconcileRecreate`.
+    """
+
+    b_by_line = {c.line: c for c in node_b.children}
+    a_by_line = {c.line: c for c in node_a.children}
+
+    for child_a in node_a.children:
+        child_b = b_by_line.get(child_a.line)
+        if child_b is None:
+            yield ReconcileDelete(parent_path, child_a)
+            continue
+        if child_a.is_leaf and child_b.is_leaf:
+            continue
+        if child_a.is_leaf != child_b.is_leaf:
+            yield ReconcileDelete(parent_path, child_a)
+            yield ReconcileAdd(parent_path, child_b)
+            continue
+
+        next_path = (*parent_path, child_a.line)
+        if is_order_sensitive_for(parser, next_path):
+            if not _subtrees_equal(parser, child_a, child_b):
+                yield ReconcileRecreate(next_path, child_b)
+            continue
+
+        yield from _collect_events(parser, child_a, child_b, next_path)
+
+    for child_b in node_b.children:
+        if child_b.line not in a_by_line:
+            yield ReconcileAdd(parent_path, child_b)
+
+
+def _subtrees_equal(parser: VendorParser, a: ConfigNode, b: ConfigNode) -> bool:
+    """True iff *a* and *b* render to identical line sequences."""
+
+    return render_subtree(parser, a, 0) == render_subtree(parser, b, 0)

diffnc/vendors/__init__.py

@@ -0,0 +1,58 @@
+"""Vendor plugin registry.
+
+Importing this package automatically registers the built-in vendors (Junos, Junos set,
+NXOS, IOS, IOS-XE, IOS-XR, EOS). Third-party code can register additional vendors via
+:func:`register`.
+"""
+
+from __future__ import annotations
+
+from diffnc.vendors.base import VendorParser
+
+_REGISTRY: dict[str, VendorParser] = {}
+
+
+def register(parser: VendorParser) -> None:
+    """Register *parser* under its :attr:`~VendorParser.name`."""
+
+    _REGISTRY[parser.name] = parser
+
+
+def get(name: str) -> VendorParser:
+    """Look up the parser registered for *name*.
+
+    Raises:
+        KeyError: if no vendor with that name has been registered.
+    """
+
+    try:
+        return _REGISTRY[name]
+    except KeyError as exc:
+        raise KeyError(f"unknown vendor: {name!r}") from exc
+
+
+def names() -> list[str]:
+    """Return all registered vendor names, sorted alphabetically."""
+
+    return sorted(_REGISTRY)
+
+
+# Register built-in vendors. Imports are placed after the registry is defined to avoid
+# circular-import surprises when sub-modules call back into this package at import time.
+from diffnc.vendors import eos as _eos  # noqa: E402
+from diffnc.vendors import ios as _ios  # noqa: E402
+from diffnc.vendors import iosxe as _iosxe  # noqa: E402
+from diffnc.vendors import iosxr as _iosxr  # noqa: E402
+from diffnc.vendors import junos as _junos  # noqa: E402
+from diffnc.vendors import junos_set as _junos_set  # noqa: E402
+from diffnc.vendors import nxos as _nxos  # noqa: E402
+
+register(_junos.PARSER)
+register(_junos_set.PARSER)
+register(_nxos.PARSER)
+register(_ios.PARSER)
+register(_iosxe.PARSER)
+register(_iosxr.PARSER)
+register(_eos.PARSER)
+
+__all__ = ["VendorParser", "get", "names", "register"]