pdfstrip 0.1.0__tar.gz

pdfstrip-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pdfstrip-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

pdfstrip-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

pdfstrip-0.1.0/CLAUDE.md

@@ -0,0 +1,35 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+pdfstrip is a CLI tool that removes passwords from PDF files. Built with pikepdf, Typer, and Rich. Managed with `uv`.
+
+## Commands
+
+- **Run**: `uv run pdfstrip <files> -p <password>`
+- **Help**: `uv run pdfstrip --help`
+- **Tests**: `uv run pytest`
+- **Single test**: `uv run pytest tests/test_core.py::TestUnlockPdf::test_success`
+- **Sync deps**: `uv sync`
+- **Add dep**: `uv add <package>`
+- **Install globally**: `uv tool install -e .`
+
+## Architecture
+
+Three-module split with strict import boundaries:
+
+- **`core.py`** — Pure logic, no CLI or Rich imports. Every `unlock_pdf()` call returns a frozen `UnlockResult` dataclass (never raises). This makes batch processing trivial — collect results, then render.
+- **`output.py`** — Rich rendering (progress bar, colored results, summary table, password prompt). Imports from core only.
+- **`cli.py`** — Typer app that wires core + output together. Handles argument parsing, validation, single vs batch dispatch.
+
+Key patterns:
+- In-place unlock uses tempfile + `shutil.move()` because pikepdf can't overwrite its input while open.
+- Directory expansion is non-recursive (`*.pdf` glob, not `**/*.pdf`).
+- `--output`, `--output-dir`, and `--in-place` are mutually exclusive; validated before any work starts.
+- Password prompt is deferred until after file validation.
+
+## Tests
+
+Test fixtures in `conftest.py` generate real encrypted/unencrypted PDFs with pikepdf. CLI tests use `typer.testing.CliRunner`.

pdfstrip-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maximilian Walterskirchen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdfstrip-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: pdfstrip
+Version: 0.1.0
+Summary: Remove passwords from PDF files
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: pikepdf>=9
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# pdfstrip
+
+Remove passwords from PDF files.
+
+## Install
+
+```bash
+pipx install pdfstrip
+```
+
+Or with `uv`:
+
+```bash
+uv tool install pdfstrip
+```
+
+## Usage
+
+```bash
+# Unlock a single file
+pdfstrip secret.pdf -p mypassword
+
+# Unlock to a specific output
+pdfstrip secret.pdf -p mypassword -o unlocked.pdf
+
+# Unlock in place
+pdfstrip secret.pdf -p mypassword --in-place
+
+# Batch unlock a directory
+pdfstrip ./pdfs/ -p mypassword --skip-unprotected
+
+# Dry run
+pdfstrip secret.pdf -p mypassword --dry-run
+```
+
+## Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--password` | `-p` | PDF password |
+| `--output` | `-o` | Output file path (single file only) |
+| `--output-dir` | `-d` | Output directory for unlocked files |
+| `--in-place` | `-i` | Overwrite original files |
+| `--force` | `-f` | Overwrite existing output files |
+| `--skip-unprotected` | `-s` | Skip files that are not encrypted |
+| `--dry-run` | `-n` | Show what would be done without writing |

pdfstrip-0.1.0/README.md

@@ -0,0 +1,46 @@
+# pdfstrip
+
+Remove passwords from PDF files.
+
+## Install
+
+```bash
+pipx install pdfstrip
+```
+
+Or with `uv`:
+
+```bash
+uv tool install pdfstrip
+```
+
+## Usage
+
+```bash
+# Unlock a single file
+pdfstrip secret.pdf -p mypassword
+
+# Unlock to a specific output
+pdfstrip secret.pdf -p mypassword -o unlocked.pdf
+
+# Unlock in place
+pdfstrip secret.pdf -p mypassword --in-place
+
+# Batch unlock a directory
+pdfstrip ./pdfs/ -p mypassword --skip-unprotected
+
+# Dry run
+pdfstrip secret.pdf -p mypassword --dry-run
+```
+
+## Options
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--password` | `-p` | PDF password |
+| `--output` | `-o` | Output file path (single file only) |
+| `--output-dir` | `-d` | Output directory for unlocked files |
+| `--in-place` | `-i` | Overwrite original files |
+| `--force` | `-f` | Overwrite existing output files |
+| `--skip-unprotected` | `-s` | Skip files that are not encrypted |
+| `--dry-run` | `-n` | Show what would be done without writing |

pdfstrip-0.1.0/pdfstrip/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pdfstrip-0.1.0/pdfstrip/cli.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from pdfstrip.core import UnlockResult, UnlockStatus, collect_pdf_files, unlock_pdf
+from pdfstrip.output import (
+    confirm,
+    console,
+    create_progress,
+    print_result,
+    print_summary,
+    prompt_password,
+)
+
+app = typer.Typer(add_completion=False)
+
+
+def _validate_options(
+    output: Path | None,
+    output_dir: Path | None,
+    in_place: bool,
+) -> None:
+    set_count = sum([output is not None, output_dir is not None, in_place])
+    if set_count > 1:
+        console.print("[red]Error:[/] --output, --output-dir, and --in-place are mutually exclusive")
+        raise typer.Exit(1)
+
+
+@app.command()
+def main(
+    files: Annotated[list[Path], typer.Argument(help="PDF files or directories to unlock")],
+    password: Annotated[Optional[str], typer.Option("--password", "-p", help="PDF password")] = None,
+    output: Annotated[Optional[Path], typer.Option("--output", "-o", help="Output file path (single file only)")] = None,
+    output_dir: Annotated[Optional[Path], typer.Option("--output-dir", "-d", help="Output directory for unlocked files")] = None,
+    in_place: Annotated[bool, typer.Option("--in-place", "-i", help="Overwrite original files")] = False,
+    force: Annotated[bool, typer.Option("--force", "-f", help="Overwrite existing output files")] = False,
+    skip_unprotected: Annotated[bool, typer.Option("--skip-unprotected", "-s", help="Skip files that are not encrypted")] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", "-n", help="Show what would be done without writing")] = False,
+) -> None:
+    """Remove passwords from PDF files."""
+    _validate_options(output, output_dir, in_place)
+
+    pdf_files = collect_pdf_files(files)
+    if not pdf_files:
+        console.print("[yellow]No PDF files found.[/]")
+        raise typer.Exit(0)
+
+    if output is not None and len(pdf_files) > 1:
+        console.print("[red]Error:[/] --output can only be used with a single file")
+        raise typer.Exit(1)
+
+    if in_place and not dry_run:
+        if not confirm("Overwrite original files?"):
+            raise typer.Exit(0)
+
+    if password is None:
+        password = prompt_password()
+
+    batch = len(pdf_files) > 1
+    results: list[UnlockResult] = []
+
+    if batch:
+        progress = create_progress()
+        with progress:
+            task = progress.add_task("Unlocking", total=len(pdf_files))
+            for f in pdf_files:
+                result = unlock_pdf(
+                    f,
+                    password,
+                    output=None,
+                    output_dir=output_dir,
+                    in_place=in_place,
+                    dry_run=dry_run,
+                    force=force,
+                    skip_unprotected=skip_unprotected,
+                )
+                results.append(result)
+                progress.advance(task)
+        for r in results:
+            print_result(r)
+        print_summary(results)
+    else:
+        result = unlock_pdf(
+            pdf_files[0],
+            password,
+            output=output,
+            output_dir=output_dir,
+            in_place=in_place,
+            dry_run=dry_run,
+            force=force,
+            skip_unprotected=skip_unprotected,
+        )
+        results.append(result)
+        print_result(result)
+
+    if any(r.status in {UnlockStatus.WRONG_PASSWORD, UnlockStatus.FILE_NOT_FOUND, UnlockStatus.ERROR, UnlockStatus.OUTPUT_EXISTS} for r in results):
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()

pdfstrip-0.1.0/pdfstrip/core.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import shutil
+import tempfile
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+import pikepdf
+
+
+class UnlockStatus(Enum):
+    SUCCESS = "success"
+    ALREADY_UNLOCKED = "already_unlocked"
+    WRONG_PASSWORD = "wrong_password"
+    FILE_NOT_FOUND = "file_not_found"
+    OUTPUT_EXISTS = "output_exists"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class UnlockResult:
+    source: Path
+    destination: Path | None
+    status: UnlockStatus
+    message: str
+
+
+def is_encrypted(path: Path) -> bool:
+    """Check if a PDF file is password-protected."""
+    try:
+        with pikepdf.open(path):
+            return False
+    except pikepdf.PasswordError:
+        return True
+
+
+def collect_pdf_files(paths: list[Path]) -> list[Path]:
+    """Expand directories to *.pdf (non-recursive), pass files through."""
+    result: list[Path] = []
+    for p in paths:
+        if p.is_dir():
+            result.extend(sorted(p.glob("*.pdf")))
+        else:
+            result.append(p)
+    return result
+
+
+def resolve_output_path(
+    source: Path,
+    *,
+    output: Path | None = None,
+    output_dir: Path | None = None,
+    in_place: bool = False,
+) -> Path:
+    """Determine the destination path for an unlocked PDF."""
+    if output is not None:
+        return output
+    if output_dir is not None:
+        return output_dir / source.name
+    if in_place:
+        return source
+    # Default: <name>_unlocked.pdf in the same directory
+    return source.with_stem(f"{source.stem}_unlocked")
+
+
+def unlock_pdf(
+    source: Path,
+    password: str,
+    *,
+    output: Path | None = None,
+    output_dir: Path | None = None,
+    in_place: bool = False,
+    dry_run: bool = False,
+    force: bool = False,
+    skip_unprotected: bool = False,
+) -> UnlockResult:
+    """Unlock a single PDF file. Returns a structured result."""
+    if not source.exists():
+        return UnlockResult(source, None, UnlockStatus.FILE_NOT_FOUND, "File not found")
+
+    if not is_encrypted(source):
+        if skip_unprotected:
+            return UnlockResult(source, None, UnlockStatus.ALREADY_UNLOCKED, "Skipped (not encrypted)")
+        return UnlockResult(source, None, UnlockStatus.ALREADY_UNLOCKED, "File is not encrypted")
+
+    dest = resolve_output_path(source, output=output, output_dir=output_dir, in_place=in_place)
+
+    if not in_place and dest.exists() and not force:
+        return UnlockResult(source, dest, UnlockStatus.OUTPUT_EXISTS, f"Output already exists: {dest}")
+
+    if dry_run:
+        return UnlockResult(source, dest, UnlockStatus.SUCCESS, "Would unlock (dry run)")
+
+    try:
+        with pikepdf.open(source, password=password) as pdf:
+            # Write to a temp file in the same directory, then move into place.
+            # pikepdf cannot overwrite its own input while the handle is open.
+            fd, tmp = tempfile.mkstemp(suffix=".pdf", dir=dest.parent)
+            try:
+                pdf.save(tmp)
+            except Exception:
+                Path(tmp).unlink(missing_ok=True)
+                raise
+        # Handle is closed — safe to move now.
+        shutil.move(tmp, dest)
+    except pikepdf.PasswordError:
+        return UnlockResult(source, dest, UnlockStatus.WRONG_PASSWORD, "Wrong password")
+    except Exception as exc:
+        return UnlockResult(source, dest, UnlockStatus.ERROR, str(exc))
+
+    return UnlockResult(source, dest, UnlockStatus.SUCCESS, f"Unlocked → {dest}")

pdfstrip-0.1.0/pdfstrip/output.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from rich.console import Console
+from rich.progress import BarColumn, MofNCompleteColumn, Progress, TextColumn
+from rich.table import Table
+
+from pdfstrip.core import UnlockResult, UnlockStatus
+
+console = Console()
+
+STATUS_STYLES: dict[UnlockStatus, tuple[str, str]] = {
+    UnlockStatus.SUCCESS: ("green", "Unlocked"),
+    UnlockStatus.ALREADY_UNLOCKED: ("yellow", "Already unlocked"),
+    UnlockStatus.WRONG_PASSWORD: ("red", "Wrong password"),
+    UnlockStatus.FILE_NOT_FOUND: ("red", "Not found"),
+    UnlockStatus.OUTPUT_EXISTS: ("red", "Output exists"),
+    UnlockStatus.ERROR: ("red", "Error"),
+}
+
+
+def create_progress() -> Progress:
+    return Progress(
+        TextColumn("[bold blue]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        console=console,
+    )
+
+
+def print_result(result: UnlockResult) -> None:
+    color, label = STATUS_STYLES[result.status]
+    console.print(f"[{color}]{label}[/] {result.source} — {result.message}")
+
+
+def print_summary(results: list[UnlockResult]) -> None:
+    counts: dict[UnlockStatus, int] = {}
+    for r in results:
+        counts[r.status] = counts.get(r.status, 0) + 1
+
+    table = Table(title="Summary")
+    table.add_column("Status", style="bold")
+    table.add_column("Count", justify="right")
+
+    for status, (color, label) in STATUS_STYLES.items():
+        count = counts.get(status, 0)
+        if count:
+            table.add_row(f"[{color}]{label}[/]", str(count))
+
+    console.print(table)
+
+
+def confirm(message: str) -> bool:
+    answer = console.input(f"{message} [y/N] ")
+    return answer.strip().lower() == "y"
+
+
+def prompt_password() -> str:
+    return console.input("[bold]Password: [/]", password=True)

pdfstrip-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "pdfstrip"
+version = "0.1.0"
+description = "Remove passwords from PDF files"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+classifiers = [
+    "Environment :: Console",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "pikepdf>=9",
+    "typer>=0.12",
+    "rich>=13",
+]
+
+[project.scripts]
+pdfstrip = "pdfstrip.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+]

pdfstrip-0.1.0/tests/conftest.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pikepdf
+import pytest
+
+
+def _make_pdf(path: Path, *, password: str | None = None) -> Path:
+    """Create a minimal PDF, optionally password-protected."""
+    pdf = pikepdf.new()
+    pdf.add_blank_page(page_size=(200, 200))
+    encryption = pikepdf.Encryption(owner=password, user=password) if password else None
+    pdf.save(path, encryption=encryption)
+    pdf.close()
+    return path
+
+
+@pytest.fixture()
+def protected_pdf(tmp_path: Path) -> Path:
+    return _make_pdf(tmp_path / "secret.pdf", password="pass123")
+
+
+@pytest.fixture()
+def unprotected_pdf(tmp_path: Path) -> Path:
+    return _make_pdf(tmp_path / "open.pdf")
+
+
+@pytest.fixture()
+def batch_dir(tmp_path: Path) -> Path:
+    d = tmp_path / "batch"
+    d.mkdir()
+    _make_pdf(d / "a.pdf", password="pass123")
+    _make_pdf(d / "b.pdf", password="pass123")
+    _make_pdf(d / "c.pdf", password="pass123")
+    _make_pdf(d / "open.pdf")
+    return d

pdfstrip-0.1.0/tests/test_cli.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from pdfstrip.cli import app
+
+runner = CliRunner()
+
+
+class TestCliSingleFile:
+    def test_unlock(self, protected_pdf: Path) -> None:
+        result = runner.invoke(app, [str(protected_pdf), "-p", "pass123"])
+        assert result.exit_code == 0
+        assert "Unlocked" in result.output
+
+    def test_wrong_password(self, protected_pdf: Path) -> None:
+        result = runner.invoke(app, [str(protected_pdf), "-p", "wrong"])
+        assert result.exit_code == 1
+        assert "Wrong password" in result.output
+
+    def test_unprotected(self, unprotected_pdf: Path) -> None:
+        result = runner.invoke(app, [str(unprotected_pdf), "-p", "pass123"])
+        assert result.exit_code == 0
+        assert "not encrypted" in result.output
+
+    def test_dry_run(self, protected_pdf: Path) -> None:
+        result = runner.invoke(app, [str(protected_pdf), "-p", "pass123", "--dry-run"])
+        assert result.exit_code == 0
+        assert "dry run" in result.output
+
+    def test_in_place(self, protected_pdf: Path) -> None:
+        result = runner.invoke(app, [str(protected_pdf), "-p", "pass123", "--in-place"], input="y\n")
+        assert result.exit_code == 0
+        assert "Unlocked" in result.output
+
+
+class TestCliBatch:
+    def test_directory(self, batch_dir: Path) -> None:
+        result = runner.invoke(app, [str(batch_dir), "-p", "pass123", "--skip-unprotected"])
+        assert result.exit_code == 0
+        assert "Summary" in result.output
+
+    def test_dry_run(self, batch_dir: Path) -> None:
+        result = runner.invoke(app, [str(batch_dir), "-p", "pass123", "--dry-run"])
+        assert result.exit_code == 0
+        assert "dry run" in result.output
+
+
+class TestCliValidation:
+    def test_mutually_exclusive(self, protected_pdf: Path) -> None:
+        result = runner.invoke(app, [str(protected_pdf), "-p", "pass", "--in-place", "-o", "out.pdf"], input="y\n")
+        assert result.exit_code == 1
+        assert "mutually exclusive" in result.output
+
+    def test_output_with_multiple_files(self, batch_dir: Path) -> None:
+        result = runner.invoke(app, [str(batch_dir), "-p", "pass", "-o", "out.pdf"])
+        assert result.exit_code == 1
+        assert "single file" in result.output