Metadata-Version: 2.4
Name: localpdf
Version: 0.2.1
Summary: Local PDF converter CLI
Author: 6meowscles
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/6meowscles/pdfc
Project-URL: Repository, https://github.com/6meowscles/pdfc
Project-URL: Issues, https://github.com/6meowscles/pdfc/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click
Requires-Dist: rich
Requires-Dist: pymupdf
Requires-Dist: pillow
Requires-Dist: markdown
Requires-Dist: weasyprint
Requires-Dist: ocrmypdf
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# pdfc

A local PDF converter. Everything runs on this machine; nothing is uploaded.

## Install

### Arch Linux

    git clone https://github.com/6meowscles/pdfc
    cd pdfc/packaging/aur && makepkg -si

That builds a real package from the latest release and installs it with
pacman, so `pdfc` lands in `/usr/bin` and its dependencies come from the
official repositories. `makepkg` runs the test suite as part of the build.

### Anywhere else

    ./install.sh

That creates `.venv/`, installs the package, and links `~/.local/bin/pdfc`.
If a dependency has no wheel for your Python, rerun with an older one:
`PYTHON=python3.12 ./install.sh`.

Note that this install stays tied to the checkout: deleting or rebuilding
`.venv/` breaks the linked command. The Arch package has no such link.

## Use

    pdfc scan.pdf out/page.png --dpi 300   # render pages to images
    pdfc notes.md notes.pdf                # markdown to PDF, via HTML
    pdfc report.docx report.pdf            # needs libreoffice
    pdfc scan.pdf notes.txt                # extract text

    pdfc merge a.pdf b.pdf -o all.pdf
    pdfc split big.pdf --pages 1-5,9 -o out/
    pdfc split big.pdf --each -o pages/
    pdfc rotate scan.pdf --angle 90 -o fixed.pdf
    pdfc compress big.pdf --quality ebook -o small.pdf
    pdfc ocr scan.pdf -o searchable.pdf

`pdfc routes` lists every conversion and whether its dependencies are installed.

`--dry-run`, `-f/--force`, `--progress`, `-q` and `-v` belong to each command
rather than to `pdfc` itself, so they follow the positional arguments:

    pdfc notes.md notes.pdf --dry-run     # prints the route and the output paths
    pdfc split big.pdf --each -o pages/ -f

## Optional dependencies

| Feature | Needs |
|---|---|
| Office formats (docx, odt, pptx, xlsx) | libreoffice |
| OCR | tesseract, ocrmypdf |
| Compression, and the OCR text layer | ghostscript |
| Any PDF output | pango and cairo, for weasyprint |

You do not need to look these up. When a conversion needs something that is
missing, `pdfc` names it and prints the command for *your* system — pacman,
apt, dnf, zypper or brew, chosen from `/etc/os-release`:

    $ pdfc report.docx report.pdf
    error: converting docx → pdf needs libreoffice
           install it with: sudo apt install libreoffice

`pdfc routes` lists every conversion up front and marks which are blocked.

The pip install pulls ocrmypdf in automatically; a distro package leaves it
optional.

## Progress output

Each step prints its verb while it runs and again, past tense, when it finishes:

    rendering  pdf → png  ████████░░░░  8/12  0:03
    rendered   pdf → png  12 files → out/  4.2 MB  5.1s

Progress goes to stderr, so piping stdout stays clean. `--progress
bar|plain|none` overrides the default, which is a bar on a terminal and plain
lines everywhere else.

## Design

`docs/design.md` covers the architecture: the converter registry, the
two-hop routing rule, format detection, output-path templating, and the
error/exit-code contract.

## Tests

    .venv/bin/pytest

## License

GNU AGPL-3.0-or-later — see `LICENSE`.

This is not a preference so much as an inheritance: `pdfc` is built on
[PyMuPDF](https://pymupdf.readthedocs.io/), which is dual-licensed AGPL-3.0 or
commercial, and PyMuPDF does the real work here — rendering, text extraction,
and the page operations. A work built on it and distributed has to carry the
same terms, so a permissive license would be promising something these
dependencies do not allow.

The external tools `pdfc` shells out to — ghostscript, libreoffice, tesseract —
run as separate processes and do not affect this. The rest of the Python stack
is permissive: click and markdown (BSD), pillow (MIT-CMU), rich (MIT),
ocrmypdf (MPL-2.0).
