Metadata-Version: 2.4
Name: localpdf
Version: 0.2.2
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
Provides-Extra: ocr
Requires-Dist: ocrmypdf; extra == "ocr"
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

### pip

    pip install localpdf

The distribution is called `localpdf` because PyPI already has a project too
close to `pdfc`; the command it installs is still `pdfc`. Add `[ocr]` if you
want OCR: `pip install localpdf[ocr]`.

### Homebrew

    brew install 6meowscles/tap/pdfc

macOS or Linux. The formula builds a virtualenv of its own, and pulls in cairo
and pango because weasyprint loads them at import time.

### 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.

`pdfc` is not on the AUR; the PKGBUILD lives here, so it is built from the
checkout rather than fetched by an AUR helper.

### Fedora

There is no COPR repository yet, so build the RPM from the spec in this
repository:

    sudo dnf install rpm-build rpmdevtools python3-devel pyproject-rpm-macros
    rpmdev-setuptree
    spectool -g -R packaging/copr/pdfc.spec
    rpmbuild -ba packaging/copr/pdfc.spec
    sudo dnf install ~/rpmbuild/RPMS/noarch/pdfc-*.noarch.rpm

### 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.

OCR is the one dependency no install method pulls in for you, because it
drags the whole tesseract stack behind it. Add it deliberately:

    pip install localpdf[ocr]

or install your distribution's own `ocrmypdf` package.

## 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).
