modpdf 0.1.0__tar.gz

modpdf-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,135 @@
+name: release
+
+# Pushing a tag like v0.1.0 publishes that version to PyPI, then creates a
+# GitHub Release with the same files, an SBOM, and an unsigned macOS app.
+#
+# Running it by hand (Actions → release → Run workflow) is a dry run: it
+# builds and publishes to TestPyPI instead, and creates no GitHub Release.
+#
+# Publishing uses PyPI's Trusted Publishing: PyPI trusts this workflow, in this
+# repository, running in the `pypi` environment, and nothing else. There is no
+# API token stored anywhere to be stolen.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v10.1.0
+
+      # A tag that doesn't match pyproject.toml would publish one version
+      # under another's name. Stop before anything is built.
+      - name: Tag matches the project version
+        if: github.event_name == 'push'
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "${GITHUB_REF_NAME#v}" != "$version" ]; then
+            echo "tag $GITHUB_REF_NAME does not match pyproject.toml version $version" >&2
+            exit 1
+          fi
+
+      - name: Build the sdist and wheel
+        run: uv build
+
+      # The SBOM lists every runtime dependency, desktop extra included, at the
+      # exact versions uv.lock pins.
+      - name: SBOM
+        run: |
+          uv export --locked --no-dev --extra gui --no-emit-project --no-hashes \
+            --output-file requirements-runtime.txt
+          uvx --from cyclonedx-bom==7.4.0 cyclonedx-py requirements \
+            --pyproject pyproject.toml --of JSON --output-reproducible \
+            -o sbom.cdx.json requirements-runtime.txt
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sbom
+          path: sbom.cdx.json
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/modpdf
+    permissions:
+      id-token: write  # what Trusted Publishing uses instead of a token
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@v1.14.2
+        with:
+          repository-url: ${{ github.event_name == 'workflow_dispatch' && 'https://test.pypi.org/legacy/' || 'https://upload.pypi.org/legacy/' }}
+          # A second dry run of the same version would otherwise fail on
+          # TestPyPI; a real release must never silently skip.
+          skip-existing: ${{ github.event_name == 'workflow_dispatch' }}
+
+  github-release:
+    needs: publish
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: actions/download-artifact@v8
+        with:
+          name: sbom
+
+      # The release notes are this version's own section of CHANGELOG.md.
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v v="$version" '
+            $0 ~ "^## \\[" v "\\]" { found = 1; next }
+            found && /^## \[/ { exit }
+            found { print }
+          ' CHANGELOG.md > notes.md
+          if [ ! -s notes.md ]; then
+            echo "CHANGELOG.md has no section for $version" >&2
+            exit 1
+          fi
+          gh release create "$GITHUB_REF_NAME" dist/* sbom.cdx.json \
+            --title "ModPDF $version" --notes-file notes.md
+
+  # Separate from the release above, so a problem building the app can't stop
+  # the PyPI release or the GitHub Release from happening.
+  macos-app:
+    needs: github-release
+    runs-on: macos-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v10.1.0
+      - name: Install
+        run: |
+          uv sync --locked --all-groups --python 3.13
+          uv pip install pyinstaller
+      - name: Build ModPDF.app
+        run: packaging/macos/build.sh
+      - name: Attach it to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ditto -c -k --keepParent dist/ModPDF.app "ModPDF-${GITHUB_REF_NAME}-macos-arm64.zip"
+          gh release upload "$GITHUB_REF_NAME" "ModPDF-${GITHUB_REF_NAME}-macos-arm64.zip"

modpdf-0.1.0/.github/workflows/security.yml

@@ -0,0 +1,62 @@
+name: security
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Dependencies pick up CVEs while nobody is pushing. Check weekly.
+    - cron: "17 6 * * 1"
+
+permissions:
+  contents: read
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v10.1.0
+
+      - name: Install
+        run: uv sync --locked --all-groups
+
+      # Audit the lockfile rather than the environment. modpdf itself is not on
+      # PyPI, and auditing the installed set makes --strict fail on it -- as an
+      # unauditable dependency, or as a skipped one under --skip-editable. The
+      # export is every locked version and nothing else, which is what we
+      # actually want checked.
+      - name: Known vulnerabilities in dependencies
+        run: |
+          uv export --locked --all-groups --no-emit-project --no-hashes \
+            --output-file requirements-audit.txt
+          uv run pip-audit --strict --desc --no-deps -r requirements-audit.txt
+
+      - name: Static analysis of our own code
+        run: uv run bandit -r src/ -c pyproject.toml
+
+  # An independent check on the no-network promise. netguard blocks sockets
+  # inside the process; this blocks them outside it. If a dependency starts
+  # phoning home, one of the two will catch it.
+  offline:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      # PySide6 links against these at import time, even for the "offscreen"
+      # platform the GUI tests run under — there is no display on this runner.
+      - name: Qt runtime libraries
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libegl1 libgl1 libxkbcommon0 libdbus-1-3
+
+      - uses: astral-sh/setup-uv@v10.1.0
+
+      - name: Install
+        run: uv sync --locked --all-groups
+
+      # Run the suite inside a network namespace with no interfaces but
+      # loopback. Firewalling the whole runner would also cut its own link to
+      # GitHub, so the job could never report what it found.
+      - name: Tests must pass with no network at all
+        run: sudo unshare --net .venv/bin/python -m pytest -v

modpdf-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,62 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Every OS on the newest Python, plus the oldest supported versions on Linux
+  # only. The older versions differ in the language, not the platform, so one
+  # OS is enough to catch them, and it keeps pull request feedback quick.
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.13"]
+        include:
+          - os: ubuntu-latest
+            python: "3.11"
+          - os: ubuntu-latest
+            python: "3.12"
+
+    steps:
+      - uses: actions/checkout@v5
+
+      # PySide6 links against these at import time, even for the "offscreen"
+      # platform the GUI tests run under — there is no display on this
+      # runner. Not needed on macOS or Windows: those wheels carry what they
+      # need.
+      - name: Qt runtime libraries (Linux only)
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libegl1 libgl1 libxkbcommon0 libdbus-1-3
+
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          enable-cache: true
+
+      - name: Install
+        run: uv sync --locked --all-groups --python ${{ matrix.python }}
+
+      - name: Lint
+        run: uv run ruff check --output-format=github .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Types
+        run: uv run mypy
+
+      - name: Tests
+        run: uv run pytest -v --cov --cov-report=term-missing

modpdf-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.hypothesis/
+
+# Test corpus downloaded by scripts/fetch_corpus.py — never committed
+tests/fixtures/corpus/
+
+# Never commit real documents. This is a privacy tool; treat it like one.
+*.pdf
+!tests/fixtures/generated/*.pdf
+
+# OS
+.DS_Store
+
+# Written by the audit job from uv.lock; never committed.
+requirements-audit.txt
+
+# Local design-tool exports (mockups, canvas layout). Not shipped code;
+# screenshots of the real, running app go in README.md instead.
+/design/
+
+# Local-only folders: documents to try the app on, and the helper that
+# regenerates the README's screenshots. Neither belongs in the repository.
+/PDFs/
+/scripts/make_readme_screenshots.py
+
+# Generated by packaging/macos/make_icon.py from mark_pixmap() — a build
+# artifact, not source, the same as dist/ and build/ above.
+packaging/macos/AppIcon.icns
+packaging/macos/AppIcon.iconset/

modpdf-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      # This is a privacy tool. A stray real document in a commit would be
+      # embarrassing at best, so keep the size ceiling low.
+      - id: check-added-large-files
+        args: ["--maxkb=512"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.7  # keep in step with ruff's version in uv.lock, or the two disagree
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  # The same scan the security workflow runs on src/. Here so a finding shows up
+  # before a push instead of after it, as a bare `assert` once did.
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.9.4  # keep in step with bandit's version in uv.lock
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml", "-q"]
+        files: ^src/

modpdf-0.1.0/CHANGELOG.md

@@ -0,0 +1,155 @@
+# Changelog
+
+All notable changes to this project are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+uses [semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-25
+
+### Added
+
+- `split`, `merge` and `reorder`. Page numbers are 1-based and inclusive, with
+  `-1` for the last page and `12-` for "to the end".
+- Bookmarks are rebuilt against the new page order instead of being dropped.
+  Entries orphaned by a removed parent heading are promoted rather than deleted,
+  and named destinations are resolved from both `/Dests` and `/Names`.
+- `inspect`, which reports what a PDF contains besides its pages: JavaScript,
+  automatic actions, embedded attachments, XFA forms, outbound links, metadata,
+  and earlier revisions still recoverable inside the file. `--json` included.
+- `sanitize`, which removes all of the above by rebuilding the document from its
+  pages, so payloads are absent from the output rather than merely unreferenced.
+  Plain links are kept unless `--strip-links` is given.
+- An enforced no-network guarantee. The process replaces its own socket, DNS and
+  TLS entry points with ones that refuse, and the test suite asserts both that
+  network calls fail and that PDF work still succeeds while they do.
+- Warnings when output is written into an iCloud Drive, Dropbox, Google Drive or
+  OneDrive folder, because a local-only tool writing into a sync folder is not
+  local in any way the user cares about.
+- Reporting when QPDF had to repair a damaged file, so a silently reconstructed
+  document is not mistaken for an intact one.
+- Encrypted documents, via `--password-stdin` or `MODPDF_PASSWORD`. There is
+  deliberately no flag that takes a password as its value.
+- File-size and page-count limits on every input, with clear refusals.
+- Atomic, mode-0600 output writing; split directories at mode 0700.
+- `compress`, with a quality gate (`modpdf/verify.py`) that renders every page
+  before and after and compares them, falling back to a lossless result — and
+  saying so — the moment any page looks different enough to matter.
+- Oversized images are downsampled and re-encoded with the codec their actual
+  pixel values call for: CCITT Group 4 for anything overwhelmingly near-black
+  or near-white, whatever colour space it happens to be stored in, JPEG for
+  genuine photographs. CMYK images, indexed images and anything carrying a
+  transparency mask are left untouched rather than risked.
+- `--lossless` and three tuned `--level` presets (`low`, `balanced`, `high`),
+  rather than a raw DPI number to guess at. Only `high` is allowed to accept
+  a more visibly different result in exchange for a smaller file; `low` and
+  `balanced` both still promise no visible loss.
+- `high` re-encodes every eligible image even when it was not oversized.
+  Otherwise a document whose images were already reasonably sized had
+  nothing left for "maximum compression" to do beyond what `balanced`
+  already did, and the report says so when that happens.
+- `balanced` and `high` can also rasterize a page whose own vector content —
+  not an image at all, a complex diagram exported as drawing commands — is
+  heavy enough to be worth it, each at its own resolution and JPEG quality,
+  since no image setting touches vector art. Every character of text on that
+  page, including text that is itself part of the diagram, stays exactly as
+  it was and stays selectable. `low` never does this. `balanced`'s flattened
+  result still has to clear the same strict quality gate as everything else
+  it does, so this did not loosen its no-visible-loss promise; only `high`
+  widens what the gate will accept.
+- `high`'s own image resolution and JPEG quality are kept deliberately close
+  to lossless — an early, more aggressive version made a flattened diagram's
+  own text hard to read. One consequence worth knowing: on an ordinary photo
+  or scan with no vector page to flatten, `high` has little left to trade,
+  and `balanced` can end up producing the smaller file.
+- A desktop application (`modpdf-gui`, optional extra `modpdf[gui]`, PySide6):
+  page thumbnails with selection, drag-to-reorder (tracked by the mouse
+  directly rather than through Qt's own drag-and-drop, which does not
+  reliably initiate a session at all), delete, duplicate, extract, split by
+  hand-built page ranges, compress, sanitize and merge-by-dropping. Edits are held in memory as an ordering of the source
+  pages, so nothing is written until you save and Revert is free. Thumbnails
+  are never written to disk and no recent-files list is kept.
+- The desktop app's Open button now builds a workspace out of more than one
+  file: with a document already open, choosing (or dropping) another one adds
+  its pages after the first's instead of replacing it, honouring whatever
+  reordering or deletion was already pending. No second button — Open is
+  overloaded rather than duplicated, since "bring this file into the
+  workspace" is one action either way. Backed by `tasks.append_document` and
+  a private, per-window `0700` scratch directory
+  (`security/fs.private_scratch_dir`) that is removed when the window closes.
+
+- A Settings dialog in the desktop app, behind a gear in the header: thumbnail
+  size (small, medium or large), the compression level the Compress panel
+  starts on, and light or dark. Every choice applies immediately. Switching
+  theme rebuilds the window in place and keeps the open document, page
+  selection, active panel, split ranges and compress choice as they were.
+  The three values are stored in the operating system's own per-user
+  settings location (`modpdf/gui/settings.py`). They are the only thing the
+  app remembers between runs, and none of them is a path or anything else
+  about a document.
+- `packaging/macos/build.sh`, which builds an unsigned `ModPDF.app` with
+  PyInstaller. Its icon is generated from the same drawn mark the window
+  uses, so there is still no image asset in the repository. Signing and
+  notarization are not done yet; see `packaging/macos/README.md`.
+
+- A release workflow. Pushing a version tag publishes to PyPI with Trusted
+  Publishing (no API token exists to leak), then creates a GitHub Release
+  with the package files, a CycloneDX SBOM of every runtime dependency, and
+  an unsigned macOS app. Running it by hand publishes to TestPyPI as a dry
+  run.
+- `bandit` now runs in pre-commit, on the same files the security workflow
+  scans.
+- ADRs for pikepdf over Ghostscript, the compression quality gate, blocking
+  the network at runtime, and the PDFium lock. `docs/compression.md` holds the
+  compression details that used to fill most of the README.
+
+### Changed
+
+- The README was rewritten to be shorter, with screenshots at the top.
+- The desktop app's layout was redesigned: a new header and toolbar, a
+  drop-zone empty state, a document details card, and a set of line icons
+  drawn in code (`modpdf/gui/icons.py`) rather than loaded from files or an
+  icon font.
+
+- Whole operations moved into `modpdf/tasks.py`, which the command line and the
+  desktop app both call. Neither interface implements a PDF operation of its own,
+  and neither can reach the filesystem without the security layer.
+- `Pdf.save` options can now be threaded through `document.save_pdf`, so a
+  caller that computed a file's size with particular save options (compression
+  does, for its structural pass) writes the file with the same ones — the
+  number in a report always matches the number on disk.
+
+### Fixed
+
+- `inspect` always reported "0 images". Its scan skipped every object that
+  wasn't a plain dictionary, and an image is always a stream. Soft masks are
+  not counted as images of their own, so a transparent picture counts once.
+- In dark mode, radio buttons were invisible until checked: the platform style
+  drew their rings in light-theme grey. They're now drawn by the app's own
+  stylesheet in both themes.
+- Hints under the Compress panel's options could lose their second line. The
+  indent was stylesheet padding, which QLabel's word wrap doesn't measure, and
+  a panel taller than the window was squashed to fit. Hints now use a real
+  margin, and every inspector panel scrolls when it doesn't fit.
+
+- The desktop app rendered every page thumbnail on its own window thread, so
+  opening a large document froze the window until the last page was done.
+  The renderer had been moved to a worker thread and then called directly —
+  and a direct call runs on the caller's thread regardless. Requests now go
+  out as queued signals. Each carries a generation number, so a thumbnail
+  still arriving for a document or size that has since been replaced is
+  dropped instead of landing on the wrong tile.
+- PDFium is not thread-safe, even across unrelated documents, and the desktop
+  app could enter it from two threads at once: the thumbnail renderer, and a
+  compression running in the background whose quality gate renders every
+  page. That can crash the whole process. Every PDFium call now holds one
+  process-wide lock (`modpdf/pdfium_lock.py`). The command line is
+  single-threaded, so the lock costs it nothing.
+
+- A desktop-app background job started from inside another job's own
+  completion callback — exactly what adding a second file does, by opening
+  the combined result it just wrote — could vanish silently: nothing kept the
+  first job's Python object alive between it emitting its result and the main
+  thread actually receiving it, so it was sometimes garbage collected in
+  between and the window was left saying "Adding…" forever, with no error.
+  `workers.run` now holds a reference to every job until its result has
+  actually been delivered.

modpdf-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+## Setup
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```
+git clone https://github.com/BryanIGD/ModPDF.git
+cd ModPDF
+uv sync --all-groups
+uv run pytest
+```
+
+Before opening a pull request, all of these should pass — they're exactly
+what CI runs:
+
+```
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest -v --cov
+uv run bandit -r src/ -c pyproject.toml
+```
+
+## YAGNI is enforced, not aspirational
+
+This is a security-focused tool, and bloat in a security tool is worse than
+bloat elsewhere: every abstraction is more code someone has to read before
+they can trust it. Concretely:
+
+- **Build only what a shipped command needs.** No feature flags, config
+  options, or extension points without a caller today.
+- **No abstraction before a second implementation exists.** We call pikepdf
+  directly; there is no `PdfEngine` interface, because there is no second
+  engine. If one ever appears, extract the interface then, informed by real
+  requirements instead of a guess.
+- **Every dependency must be load-bearing.** Adding one means updating the
+  comment in `pyproject.toml` that names the count, adding an inline comment
+  saying what it's for, and — if it changes the shape of a real decision, not
+  just a version bump — a note in `docs/adr/`.
+- **Flat over deep.** One module per concept. Split a file when it's
+  genuinely hard to read, not in anticipation of it becoming so.
+
+If a change adds a layer "for future flexibility," it needs a real, current
+caller in the same pull request, or the flexibility waits until something
+actually needs it.
+
+## How this project writes documentation
+
+The README and this file are written the way a person explains something to
+another person, not the way software project marketing usually reads. In
+practice:
+
+- No emoji in headings, no "blazing fast," no badge walls.
+- Examples show real output from the actual commands, not invented sample
+  text — the point of `tests/conftest.py`'s generated fixtures is that
+  examples can be captured and stay true.
+- A limitations section should be specific and slightly unflattering. "This
+  won't shrink a text-only PDF much, here's why" is worth more than silence
+  on the subject.
+- If a sentence could be deleted without losing information, delete it.
+
+## Tests
+
+Every PDF the test suite touches is generated at test time by
+`tests/conftest.py`; no real document is ever committed, and pages carry a
+marker so a test can assert that page 3 really is the page that started as
+page 3 after a split or reorder — not just that the page *count* looks right.
+
+- An operation change needs a test asserting page **identity**, not only page
+  count.
+- A change to anything in `modpdf/security/` needs a test in
+  `tests/security/`, and if it touches the network guard specifically,
+  confirm the change still passes with the network blocked.
+- A GUI change that reaches `modpdf.tasks` needs the window-level test to
+  call the task function directly (as the existing GUI tests do) rather than
+  only exercising it through a live `QThreadPool` job — except when the
+  threading itself is what's being tested, as in `tests/gui/test_workers.py`.
+
+## Structure
+
+The command line and the desktop app are two interfaces over one set of
+functions in `modpdf/tasks.py`. Neither implements a PDF operation of its
+own, and neither can reach the filesystem without going through
+`modpdf/security/`. A change that adds behavior only one interface can use is
+a sign it belongs in the wrong layer.
+
+## Commit messages and pull requests
+
+Say what changed and why, the way the rest of this codebase's comments do.
+"Fix bug" is not that; "the page-count check ran before the password prompt,
+so an encrypted file always failed" is.