Diff API Reference¶

def make_diff(
    a: str,
    b: str,
    filename_a: str = "a",
    filename_b: str = "b",
    context: int = 3,
) -> str:
    """Generate a unified diff between two strings.

    Args:
        a: Original text.
        b: Modified text.
        filename_a: Label for the original file in the diff header.
        filename_b: Label for the modified file in the diff header.
        context: Number of context lines around each change.

    Returns:
        A unified diff string, or an empty string if *a* and *b* are identical.
    """
    a_lines = a.splitlines(True)
    b_lines = b.splitlines(True)
    raw = list(
        difflib.unified_diff(
            a_lines,
            b_lines,
            fromfile=filename_a,
            tofile=filename_b,
            n=context,
        )
    )
    # difflib does not emit "\ No newline at end of file" markers.
    # Insert them after any diff body line that lacks a trailing newline.
    result: list[str] = []
    for line in raw:
        result.append(line)
        if line and not line.endswith("\n") and line[0] in (" ", "-", "+"):
            result.append("\n" + _NO_NEWLINE_MARKER + "\n")
    return "".join(result)

def parse_patch(patch_text: str) -> Patch:
    """Parse unified diff text into a structured :class:`Patch`.

    Args:
        patch_text: The unified diff text.

    Returns:
        A :class:`Patch` containing one :class:`PatchedFile` per file.

    Raises:
        PatchParseError: If the diff text is malformed.
    """
    files: list[PatchedFile] = []
    current_file: PatchedFile | None = None
    current_hunk: Hunk | None = None
    remaining_src = 0
    remaining_tgt = 0
    source_name: str | None = None

    raw_lines = patch_text.splitlines(True)

    for line_no_0, raw in enumerate(raw_lines):
        line_no = line_no_0 + 1
        stripped = raw.rstrip("\n").rstrip("\r")

        # --- source file header
        if stripped.startswith("--- "):
            source_name = _strip_filename_prefix(stripped[4:].strip())
            current_hunk = None
            continue

        # +++ target file header
        if stripped.startswith("+++ "):
            target_name = _strip_filename_prefix(stripped[4:].strip())
            current_file = PatchedFile(
                source_file=source_name,
                target_file=target_name,
                hunks=[],
            )
            files.append(current_file)
            source_name = None
            current_hunk = None
            continue

        # @@ hunk header
        m = _HUNK_HEADER_RE.match(stripped)
        if m:
            current_hunk = _make_hunk_from_header(m, current_file, line_no)
            remaining_src = current_hunk.src_len
            remaining_tgt = current_hunk.tgt_len
            continue

        # "\ No newline at end of file"
        if stripped.startswith("\\"):
            if current_hunk and current_hunk.lines:
                tag, content = current_hunk.lines[-1]
                current_hunk.lines[-1] = (tag, content.rstrip("\n"))
            continue

        # Hunk body lines
        if current_hunk is not None and (remaining_src > 0 or remaining_tgt > 0):
            if not raw:
                continue
            remaining_src, remaining_tgt = _classify_body_line(
                raw, line_no, current_hunk, remaining_src, remaining_tgt
            )
            continue

        # Lines outside hunks (diff --git preamble, index, mode, etc.)

    return Patch(files=files)

def apply_patch(source: str, patch: Patch | PatchedFile) -> str:
    """Apply a parsed patch to source text.

    Args:
        source: The original text to patch.
        patch: A :class:`Patch` (must contain exactly one file) or a
            single :class:`PatchedFile`.

    Returns:
        The patched text.

    Raises:
        PatchApplyError: If a context or deletion line does not match
            the source.
        DiffError: If a :class:`Patch` contains more than one file.
    """
    pf, early = _resolve_patched_file(source, patch)
    if early is not None:
        return early

    source_lines = source.splitlines(True)
    output: list[str] = []
    src_idx = 0  # current position in source_lines (0-based)

    for hunk_i, hunk in enumerate(pf.hunks):
        hunk_start = hunk.src_start - 1
        output.extend(source_lines[src_idx:hunk_start])
        hunk_output, src_idx = _apply_hunk_lines(hunk_i, hunk, source_lines)
        output.extend(hunk_output)

    # Copy remaining lines after the last hunk.
    output.extend(source_lines[src_idx:])
    return "".join(output)

def reverse_patch(patch: Patch) -> Patch:
    """Create a reversed copy of *patch*.

    Applying the reversed patch to the target reproduces the original source::

        assert apply_patch(b, reverse_patch(parse_patch(make_diff(a, b)))) == a

    Args:
        patch: The patch to reverse.

    Returns:
        A new :class:`Patch` with swapped source/target and inverted changes.
    """
    _TAG_SWAP = {"+": "-", "-": "+", " ": " "}

    new_files: list[PatchedFile] = []
    for pf in patch.files:
        new_hunks: list[Hunk] = []
        for hunk in pf.hunks:
            new_lines = [(_TAG_SWAP[tag], content) for tag, content in hunk.lines]
            new_hunks.append(
                Hunk(
                    src_start=hunk.tgt_start,
                    src_len=hunk.tgt_len,
                    tgt_start=hunk.src_start,
                    tgt_len=hunk.src_len,
                    lines=new_lines,
                )
            )
        new_files.append(
            PatchedFile(
                source_file=pf.target_file,
                target_file=pf.source_file,
                hunks=new_hunks,
            )
        )
    return Patch(files=new_files)

def merge3(
    base: str,
    ours: str,
    theirs: str,
    label_ours: str = "ours",
    label_theirs: str = "theirs",
) -> MergeResult:
    """Perform a three-way merge.

    Args:
        base: The common ancestor text.
        ours: Text from the first branch.
        theirs: Text from the second branch.
        label_ours: Label for conflict markers on the *ours* side.
        label_theirs: Label for conflict markers on the *theirs* side.

    Returns:
        A :class:`MergeResult` with the merged content and any conflicts.
    """
    base_lines = base.splitlines(True)
    ours_lines = ours.splitlines(True)
    theirs_lines = theirs.splitlines(True)

    sm_ours = difflib.SequenceMatcher(None, base_lines, ours_lines)
    sm_theirs = difflib.SequenceMatcher(None, base_lines, theirs_lines)

    ours_changes = _extract_changes(sm_ours.get_opcodes(), ours_lines)
    theirs_changes = _extract_changes(sm_theirs.get_opcodes(), theirs_lines)

    merged: list[str] = []
    conflicts: list[ConflictRegion] = []
    base_pos = 0
    oi = 0
    ti = 0
    sentinel = len(base_lines) + 1

    while base_pos < sentinel:
        o_change, o_start = _peek_change(ours_changes, oi, sentinel)
        t_change, t_start = _peek_change(theirs_changes, ti, sentinel)

        if o_change is None and t_change is None:
            merged.extend(base_lines[base_pos:])
            break

        # Emit base lines before the next change.
        next_start = min(o_start, t_start)
        if next_start > base_pos:
            merged.extend(base_lines[base_pos:next_start])
            base_pos = next_start

        if o_change is not None and t_change is not None:
            base_pos, oi, ti = _apply_both_changes(
                o_change,
                t_change,
                label_ours,
                label_theirs,
                ours_changes,
                theirs_changes,
                oi,
                ti,
                merged,
                conflicts,
            )
        elif o_change is not None:
            merged.extend(o_change[2])
            base_pos = o_change[1]
            oi += 1
        elif t_change is not None:
            merged.extend(t_change[2])
            base_pos = t_change[1]
            ti += 1

    return MergeResult(
        content="".join(merged),
        has_conflicts=len(conflicts) > 0,
        conflicts=conflicts,
    )