diffpdf 0.3.1__tar.gz → 1.0.0__tar.gz

{diffpdf-0.3.1 → diffpdf-1.0.0}/.github/dependabot.yml

@@ -1,6 +1,6 @@
 version: 2
 updates:
-  - package-ecosystem: "pip"
+  - package-ecosystem: "uv"
     directory: "/"
     schedule:
       interval: "weekly"

diffpdf-1.0.0/.github/workflows/build.yml

@@ -0,0 +1,70 @@
+name: Build
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        # Tests compatibility across Ubuntu/Windows and Python/package version extremes
+        os: [ubuntu-latest, windows-latest]
+        dependencies: [locked, oldest]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      # When searching for a system Python version, uv will use the first compatible version - not the newest version.
+      # Therefore, make sure the newest version is available on the runner.
+      - name: Install Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+          
+      # At the time of writing there is no way to force uv select the lowest version of Python.
+      # Therefore, extract this from pyproject.toml
+      # More info: https://github.com/astral-sh/uv/issues/16333
+      - name: Extract minimum Python version from pyproject.toml
+        if: matrix.dependencies == 'oldest'
+        id: python-version
+        shell: bash
+        run: |
+          MIN_PY=$(grep 'requires-python' pyproject.toml | sed -E 's/[^0-9.]//g')
+          echo "min=$MIN_PY" >> $GITHUB_OUTPUT
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Install locked dependencies
+        if: matrix.dependencies == 'locked'
+        run: uv sync --locked
+
+      - name: Install oldest dependencies
+        if: matrix.dependencies == 'oldest'
+        run: uv sync --resolution lowest --python ${{ steps.python-version.outputs.min }}
+
+      - name: Run ruff (check)
+        if: matrix.dependencies == 'locked'
+        run: uv run ruff check
+
+      - name: Run ruff (format)
+        if: matrix.dependencies == 'locked'
+        run: uv run ruff format --check
+
+      - name: Run ty
+        if: matrix.dependencies == 'locked'
+        run: uv run ty check --output-format github
+
+      - name: Run pytest
+        run: uv run pytest
+
+      - name: Upload coverage reports to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.dependencies == 'locked'
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

diffpdf-1.0.0/.vscode/extensions.json

@@ -0,0 +1,16 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations.
+	// Extension identifier format: ${publisher}.${name}. Example: vscode.csharp
+
+	// List of extensions which should be recommended for users of this workspace.
+	"recommendations": [
+		"ms-python.python",
+		"charliermarsh.ruff",
+		"ryanluker.vscode-coverage-gutters",
+		"astral-sh.ty"
+	],
+	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
+	"unwantedRecommendations": [
+		"ms-python.vscode-pylance"
+	]
+}

diffpdf-1.0.0/.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    // Format with Ruff on save & sort imports
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.codeActionsOnSave": {
+        "source.organizeImports.ruff": "explicit"
+    },
+
+    // Configure Pytest
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+}

{diffpdf-0.3.1 → diffpdf-1.0.0}/PKG-INFO

@@ -1,26 +1,22 @@
 Metadata-Version: 2.4
 Name: diffpdf
-Version: 0.3.1
+Version: 1.0.0
 Summary: A tool for comparing PDF files
 Project-URL: Homepage, https://github.com/JustusRijke/DiffPDF
 Project-URL: Issues, https://github.com/JustusRijke/DiffPDF/issues
 Author-email: Justus Rijke <justusrijke@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.10
-Requires-Dist: click
-Requires-Dist: colorlog
+Classifier: Typing :: Typed
+Requires-Python: >=3.10.0
+Requires-Dist: click>=8
 Requires-Dist: pillow>=10.0.0
-Requires-Dist: pixelmatch-fast>=1.1.0
+Requires-Dist: pixelmatch-fast>=1.3.1
 Requires-Dist: pymupdf>=1.23.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == 'dev'
-Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # DiffPDF
@@ -29,6 +25,8 @@ Description-Content-Type: text/markdown
 [![codecov](https://codecov.io/gh/JustusRijke/DiffPDF/graph/badge.svg?token=O3ZJFG6X7A)](https://codecov.io/gh/JustusRijke/DiffPDF)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PyPI - Version](https://img.shields.io/pypi/v/DiffPDF)](https://pypi.org/project/DiffPDF/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dw/DiffPDF)](https://pypi.org/project/DiffPDF/)
 
 CLI tool for detecting structural, textual, and visual differences between PDF files, for use in automatic regression tests.
 
@@ -45,6 +43,8 @@ Each stage only runs if all previous stages pass.
 
 ## Installation
 
+Install Python (v3.10 or higher) and install the package:
+
 ```bash
 pip install diffpdf
 ```
@@ -59,8 +59,7 @@ Options:
   --threshold FLOAT       Pixelmatch threshold (0.0-1.0)
   --dpi INTEGER           Render resolution
   --output-dir DIRECTORY  Diff image output directory (optional, if not specified no diff images are saved)
-  -v, --verbose           Increase verbosity (-v for INFO, -vv for DEBUG)
-  --save-log              Write log output to log.txt
+  -v, --verbose           Increase verbosity
   --version               Show the version and exit.
   --help                  Show this message and exit.
 ```
@@ -79,16 +78,37 @@ from diffpdf import diffpdf
 # Basic usage (no diff images saved)
 diffpdf("reference.pdf", "actual.pdf")
 
-# With options (save diff images to ./output directory)
-diffpdf("reference.pdf", "actual.pdf", output_dir="./output", threshold=0.2, dpi=150, verbosity=2)
+# With options (save diff images to ./output directory, extract higher quality images)
+diffpdf("reference.pdf", "actual.pdf", output_dir="./output", dpi=300)
 ```
 
 ## Development
 
+Install [uv](https://github.com/astral-sh/uv?tab=readme-ov-file#installation). Then, install dependencies & activate the automatically generated virtual environment:
+
+```bash
+uv sync --locked
+source .venv/bin/activate
+```
+
+Skip `--locked` to use the newest dependencies (this might modify `uv.lock`)
+
+Run tests:
+```bash
+pytest
+```
+
+Check code quality:
+```bash
+ruff check
+ruff format --check
+ty check
+```
+
+Better yet, install the [pre-commit](.git/hooks/pre-commit) hook, which runs code quality checks before every commit:
 ```bash
-pip install -e .[dev]
-pytest tests/ -v
-ruff check .
+cp hooks/pre-commit .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
 ```
 
 ## Acknowledgements

{diffpdf-0.3.1 → diffpdf-1.0.0}/README.md

@@ -4,6 +4,8 @@
 [![codecov](https://codecov.io/gh/JustusRijke/DiffPDF/graph/badge.svg?token=O3ZJFG6X7A)](https://codecov.io/gh/JustusRijke/DiffPDF)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PyPI - Version](https://img.shields.io/pypi/v/DiffPDF)](https://pypi.org/project/DiffPDF/)
+[![PyPI - Downloads](https://img.shields.io/pypi/dw/DiffPDF)](https://pypi.org/project/DiffPDF/)
 
 CLI tool for detecting structural, textual, and visual differences between PDF files, for use in automatic regression tests.
 
@@ -20,6 +22,8 @@ Each stage only runs if all previous stages pass.
 
 ## Installation
 
+Install Python (v3.10 or higher) and install the package:
+
 ```bash
 pip install diffpdf
 ```
@@ -34,8 +38,7 @@ Options:
   --threshold FLOAT       Pixelmatch threshold (0.0-1.0)
   --dpi INTEGER           Render resolution
   --output-dir DIRECTORY  Diff image output directory (optional, if not specified no diff images are saved)
-  -v, --verbose           Increase verbosity (-v for INFO, -vv for DEBUG)
-  --save-log              Write log output to log.txt
+  -v, --verbose           Increase verbosity
   --version               Show the version and exit.
   --help                  Show this message and exit.
 ```
@@ -54,16 +57,37 @@ from diffpdf import diffpdf
 # Basic usage (no diff images saved)
 diffpdf("reference.pdf", "actual.pdf")
 
-# With options (save diff images to ./output directory)
-diffpdf("reference.pdf", "actual.pdf", output_dir="./output", threshold=0.2, dpi=150, verbosity=2)
+# With options (save diff images to ./output directory, extract higher quality images)
+diffpdf("reference.pdf", "actual.pdf", output_dir="./output", dpi=300)
 ```
 
 ## Development
 
+Install [uv](https://github.com/astral-sh/uv?tab=readme-ov-file#installation). Then, install dependencies & activate the automatically generated virtual environment:
+
+```bash
+uv sync --locked
+source .venv/bin/activate
+```
+
+Skip `--locked` to use the newest dependencies (this might modify `uv.lock`)
+
+Run tests:
+```bash
+pytest
+```
+
+Check code quality:
+```bash
+ruff check
+ruff format --check
+ty check
+```
+
+Better yet, install the [pre-commit](.git/hooks/pre-commit) hook, which runs code quality checks before every commit:
 ```bash
-pip install -e .[dev]
-pytest tests/ -v
-ruff check .
+cp hooks/pre-commit .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
 ```
 
 ## Acknowledgements

{diffpdf-0.3.1 → diffpdf-1.0.0}/hooks/pre-commit

@@ -38,22 +38,36 @@ EOF
 	exit 1
 fi
 
+# Check if uv is installed
+uv help -q
+if [ $? -ne 0 ]; then
+	echo "'uv' is not installed or not in your PATH"
+    exit 1
+fi
+
+# Check if the project is synced
+uv lock --check -q
+if [ $? -ne 0 ]; then
+    echo "Error: Environment is out of sync. Please run 'uv sync'."
+    exit 1
+fi
+
 # Ruff checks
-ruff check
-CHECK_EXIT=$?
-
-ruff format --check
-FORMAT_EXIT=$?
-
-if [ $CHECK_EXIT -ne 0 ] || [ $FORMAT_EXIT -ne 0 ]; then
-    if [ $CHECK_EXIT -ne 0 ]; then
-        echo "Ruff found linting errors. Run: ruff check --fix"
-    fi
-    if [ $FORMAT_EXIT -ne 0 ]; then
-        echo "Ruff found formatting issues. Run: ruff format"
-    fi
+uv run ruff check -q
+if [ $? -ne 0 ]; then
+	echo "Ruff found linting errors. Please run 'ruff check --fix'"
+	exit 1
+fi
+
+uv run ruff format --check -q
+if [ $? -ne 0 ]; then
+	echo "Ruff found formatting issues. Please run 'ruff format'"
     exit 1
 fi
 
-# If there are whitespace errors, print the offending file names and fail.
-exec git diff-index --check --cached $against --
+# Type annotation checks
+uv run ty check -q
+if [ $? -ne 0 ]; then
+	echo "Found type annotation errors. Please run 'ty check'"
+    exit 1
+fi

diffpdf-1.0.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = [
+    "hatchling",
+    "hatch-vcs",
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "diffpdf"
+dynamic = ["version"]
+description = "A tool for comparing PDF files"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Justus Rijke", email="justusrijke@gmail.com"}]
+requires-python = ">=3.10.0"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Development Status :: 5 - Production/Stable",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Typing :: Typed",
+]
+dependencies = [
+    "click>=8",
+    "pymupdf>=1.23.0",
+    "pixelmatch-fast>=1.3.1",
+    "Pillow>=10.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/JustusRijke/DiffPDF"
+Issues = "https://github.com/JustusRijke/DiffPDF/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9",
+    "pytest-cov>=6",
+    "ruff>=0.10",
+    "ty>=0.0.8",
+]
+
+[project.scripts]
+diffpdf = "diffpdf.cli:cli"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+local_scheme = "no-local-version"
+
+[tool.pytest]
+strict = true
+testpaths = ["tests"]
+filterwarnings = ["error"] # Treat all warnings as errors (e.g., deprecation warnings)
+addopts = [
+    "-v",                           # Verbose output
+    "--cov",                        # Enable coverage 
+    "--cov-branch",                 # Make sure to cover every decision branch
+    "--cov-report=term-missing",    # Report which lines aren't covered
+    "--cov-report=xml",             # Dump to XML for Codecov
+]
+
+[tool.ruff.lint]
+extend-select = [
+    "I",    # Sort imports
+    "ANN",  # Enforce type annotations
+    "PT",   # Common style issues or inconsistencies with pytest-based tests
+]
+
+[tool.ruff.lint.isort]
+combine-as-imports = true # Combines "as" imports on the same line
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["ANN"] # Do not enforce type annotations for tests

diffpdf-1.0.0/src/diffpdf/__init__.py

@@ -0,0 +1,49 @@
+from importlib.metadata import version
+from pathlib import Path
+
+from .hash_check import check_hash
+from .logger import setup_logging
+from .page_check import check_page_counts
+from .text_check import check_text_content
+from .visual_check import check_visual_content
+
+__version__ = version("diffpdf")
+
+
+def diffpdf(
+    reference: str | Path,
+    actual: str | Path,
+    threshold: float = 0.1,
+    dpi: int = 96,
+    output_dir: str | Path | None = None,
+    verbose: bool = False,
+) -> bool:
+    ref_path = Path(reference) if isinstance(reference, str) else reference
+    actual_path = Path(actual) if isinstance(actual, str) else actual
+    out_path = Path(output_dir) if isinstance(output_dir, str) else output_dir
+
+    logger = setup_logging(verbose)
+
+    logger.info("[1/4] Checking file hashes...")
+    if check_hash(ref_path, actual_path):
+        logger.info("Files are identical (hash match)")
+        return True
+    logger.info("Hashes differ, continuing checks")
+
+    logger.info("[2/4] Checking page counts...")
+    if not check_page_counts(ref_path, actual_path):
+        return False
+
+    logger.info("[3/4] Checking text content...")
+    if not check_text_content(ref_path, actual_path):
+        return False
+
+    logger.info("[4/4] Checking visual content...")
+    if not check_visual_content(ref_path, actual_path, threshold, dpi, out_path):
+        return False
+
+    logger.info("PDFs are equivalent")
+    return True
+
+
+__all__ = ["diffpdf", "__version__"]

{diffpdf-0.3.1 → diffpdf-1.0.0}/src/diffpdf/cli.py

@@ -3,7 +3,7 @@ from pathlib import Path
 
 import click
 
-from .comparators import compare_pdfs
+from . import diffpdf
 from .logger import setup_logging
 
 
@@ -25,22 +25,25 @@ from .logger import setup_logging
 @click.option(
     "-v",
     "--verbose",
-    "verbosity",
-    count=True,
-    help="Increase verbosity (-v for INFO, -vv for DEBUG)",
+    is_flag=True,
+    help="Increase verbosity",
 )
-@click.option("--save-log", is_flag=True, help="Write log output to log.txt")
 @click.version_option(package_name="diffpdf")
-def cli(reference, actual, threshold, dpi, output_dir, verbosity, save_log):
+def cli(
+    reference: Path,
+    actual: Path,
+    threshold: float,
+    dpi: int,
+    output_dir: Path | None,
+    verbose: bool,
+) -> None:
     """Compare two PDF files for structural, textual, and visual differences."""
-    logger = setup_logging(verbosity, save_log)
-    logger.debug("Debug logging enabled")
-
     try:
-        if compare_pdfs(reference, actual, threshold, dpi, output_dir, logger):
+        if diffpdf(reference, actual, threshold, dpi, output_dir, verbose):
             sys.exit(0)
         else:
             sys.exit(1)
     except Exception as e:  # pragma: no cover
+        logger = setup_logging(verbose)
         logger.critical(f"Error: {e}", exc_info=True)
         sys.exit(2)

diffpdf-1.0.0/src/diffpdf/logger.py

@@ -0,0 +1,24 @@
+import logging
+
+LOG_FORMAT = (
+    "%(asctime)s %(levelname)-8s %(filename)s:%(lineno)d (%(funcName)s): %(message)s"
+)
+DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+def setup_logging(verbose: bool) -> logging.Logger:
+    if verbose:
+        level = logging.INFO
+    else:
+        level = logging.WARNING
+
+    formatter = logging.Formatter(LOG_FORMAT, datefmt=DATE_FORMAT)
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(formatter)
+
+    logger = logging.getLogger()
+    logger.setLevel(level)
+    logger.addHandler(console_handler)
+
+    return logger

{diffpdf-0.3.1 → diffpdf-1.0.0}/src/diffpdf/page_check.py

@@ -1,3 +1,4 @@
+import logging
 from pathlib import Path
 
 import fitz
@@ -10,7 +11,8 @@ def get_page_count(pdf_path: Path) -> int:
     return count
 
 
-def check_page_counts(ref: Path, actual: Path, logger) -> bool:
+def check_page_counts(ref: Path, actual: Path) -> bool:
+    logger = logging.getLogger()
     ref_count = get_page_count(ref)
     actual_count = get_page_count(actual)
 

{diffpdf-0.3.1 → diffpdf-1.0.0}/src/diffpdf/text_check.py

@@ -1,4 +1,5 @@
 import difflib
+import logging
 import re
 from pathlib import Path
 from typing import Iterable
@@ -32,7 +33,8 @@ def generate_diff(
     return diff
 
 
-def check_text_content(ref: Path, actual: Path, logger) -> bool:
+def check_text_content(ref: Path, actual: Path) -> bool:
+    logger = logging.getLogger()
     # Extract text and remove whitespace
     ref_text = re.sub(r"\s+", " ", extract_text(ref)).strip()
     actual_text = re.sub(r"\s+", " ", extract_text(actual)).strip()

{diffpdf-0.3.1 → diffpdf-1.0.0}/src/diffpdf/visual_check.py

@@ -1,3 +1,4 @@
+import logging
 from pathlib import Path
 
 import fitz
@@ -21,7 +22,7 @@ def compare_images(
     output_path: Path | None,
 ) -> bool:
     mismatch_count = pixelmatch(
-        ref_img, actual_img, diff_path=output_path, threshold=threshold
+        ref_img, actual_img, output=output_path, threshold=threshold
     )
 
     if mismatch_count > 0:
@@ -31,8 +32,13 @@ def compare_images(
 
 
 def check_visual_content(
-    ref: Path, actual: Path, threshold: float, dpi: int, output_dir: Path | None, logger
+    ref: Path,
+    actual: Path,
+    threshold: float,
+    dpi: int,
+    output_dir: Path | None,
 ) -> bool:
+    logger = logging.getLogger()
     if output_dir is not None:
         output_dir.mkdir(parents=True, exist_ok=True)
 

diffpdf-1.0.0/tests/test_api.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+import pytest
+
+from diffpdf import diffpdf
+
+TEST_ASSETS_DIR = Path(__file__).parent / "assets"
+
+
+@pytest.mark.parametrize(
+    ("ref_pdf_rel", "actual_pdf_rel", "should_pass"),
+    [
+        # Pass cases
+        ("pass/identical-A.pdf", "pass/identical-B.pdf", True),
+        ("pass/hash-diff-A.pdf", "pass/hash-diff-B.pdf", True),
+        ("pass/minor-color-diff-A.pdf", "pass/minor-color-diff-B.pdf", True),
+        ("pass/multiplatform-diff-A.pdf", "pass/multiplatform-diff-B.pdf", True),
+        # Fail cases
+        ("fail/1-letter-diff-A.pdf", "fail/1-letter-diff-B.pdf", False),
+        ("fail/major-color-diff-A.pdf", "fail/major-color-diff-B.pdf", False),
+        ("fail/page-count-diff-A.pdf", "fail/page-count-diff-B.pdf", False),
+    ],
+)
+def test_api(ref_pdf_rel, actual_pdf_rel, should_pass):
+    ref_pdf = TEST_ASSETS_DIR / ref_pdf_rel
+    actual_pdf = TEST_ASSETS_DIR / actual_pdf_rel
+
+    result = diffpdf(ref_pdf, actual_pdf)
+
+    assert result == should_pass

{diffpdf-0.3.1 → diffpdf-1.0.0}/tests/test_cli.py

@@ -7,30 +7,28 @@ from diffpdf.cli import cli
 TEST_ASSETS_DIR = Path(__file__).parent / "assets"
 
 
-def test_verbose_flag():
+def test_cli_with_output_dir():
     runner = CliRunner()
-    result = runner.invoke(
-        cli,
-        [
-            str(TEST_ASSETS_DIR / "pass/identical-A.pdf"),
-            str(TEST_ASSETS_DIR / "pass/identical-B.pdf"),
-            "-v",
-        ],
-    )
-    assert result.exit_code == 0
-    assert "INFO" in result.output
-    assert "DEBUG" not in result.output
 
+    with runner.isolated_filesystem():
+        ref_pdf = str(TEST_ASSETS_DIR / "fail/major-color-diff-A.pdf")
+        actual_pdf = str(TEST_ASSETS_DIR / "fail/major-color-diff-B.pdf")
+
+        result = runner.invoke(cli, [ref_pdf, actual_pdf, "--output-dir", "./diff"])
+
+        assert result.exit_code == 1
+        assert Path("./diff").exists()
 
-def test_double_verbose_flag():
+
+def test_verbose_flag():
     runner = CliRunner()
     result = runner.invoke(
         cli,
         [
             str(TEST_ASSETS_DIR / "pass/identical-A.pdf"),
             str(TEST_ASSETS_DIR / "pass/identical-B.pdf"),
-            "-vv",
+            "-v",
         ],
     )
     assert result.exit_code == 0
-    assert "DEBUG" in result.output
+    assert "INFO" in result.output