Pdiff: Pretty side-by-side diff

Warnings

• gotcha Pdiff is fundamentally a command-line interface (CLI) tool. It does not provide a Python API for direct programmatic interaction (e.g., `import pdiff` to use functions or classes). Users expecting a traditional Python library for in-script diffing should be aware that `pdiff` must be invoked via `subprocess` or similar methods.
  Fix: Use `subprocess.run()` to execute `pdiff` as an external command, passing file paths as arguments, and capture its `stdout` for processing.
• gotcha The output of `pdiff` utilizes ANSI escape codes for color highlighting, which are intended for terminal display. When piping the output to other tools or redirecting it to a file, these color codes may not render correctly or might appear as raw control characters. Using `less -R` is often recommended for viewing piped output.
  Fix: If piping, use tools that support ANSI escape codes (e.g., `less -R`). For programmatic capture, be prepared to strip ANSI codes if plain text is desired, or ensure the receiving environment can interpret them.
• gotcha When invoking `pdiff` from the command line, especially with filenames containing spaces or special characters, proper shell escaping or quoting is crucial. Failure to do so can lead to `FileNotFoundError` or incorrect file parsing.
  Fix: Always quote filenames (e.g., `pdiff "file with spaces.txt" other_file.txt`). When using `subprocess.run` in Python, pass filenames as separate elements in a list, which handles quoting automatically (e.g., `['pdiff', 'file with spaces.txt', 'other_file.txt']`).

Install

• pip install pdiff PyPI
• brew install nkouevda/nkouevda/pdiff Homebrew (macOS)

Imports

• pdiff (command-line)

  This library is primarily a command-line tool and does not expose a Python API for direct import and programmatic use within Python scripts. It should be invoked via a subprocess if used from Python.

  Pdiff is designed as a standalone command-line utility for console usage, not a Python library with a direct `import`able API.

Quickstart

Pdiff is invoked from the command line. This quickstart demonstrates how to use `subprocess.run` in Python to execute `pdiff` and capture its output, comparing two temporary text files. Remember to have `pdiff` installed and available in your system's PATH for this to work.

import subprocess
import os

# Create dummy files for demonstration
file1_content = """Line 1: Hello world
Line 2: This is a test file.
Line 3: Some text that is different.
Line 4: Common line.
"""

file2_content = """Line 1: Hello world!
Line 2: This is a modified test file.
Line 3: Completely new line here.
Line 4: Common line.
Line 5: An extra line in file2.
"""

with open('file1.txt', 'w') as f:
    f.write(file1_content)

with open('file2.txt', 'w') as f:
    f.write(file2_content)

print("Running pdiff on file1.txt and file2.txt:\n")

try:
    # Execute pdiff as a subprocess
    # Use text=True (or universal_newlines=True for older Python) to capture stdout as string
    # The '--' separates options from filenames, useful if filenames start with '-' or similar.
    result = subprocess.run(['pdiff', '--', 'file1.txt', 'file2.txt'], capture_output=True, text=True, check=True)
    print(result.stdout)
except subprocess.CalledProcessError as e:
    print(f"Error running pdiff: {e.stderr}")
except FileNotFoundError:
    print("Error: 'pdiff' command not found. Please ensure pdiff is installed and in your PATH.")
finally:
    # Clean up dummy files
    if os.path.exists('file1.txt'):
        os.remove('file1.txt')
    if os.path.exists('file2.txt'):
        os.remove('file2.txt')