pdfcleanerx

1 · Project Workflow

When you run a CLI command, execution passes through exactly four stages:

1. cli.py — entry point Typer parses your arguments (pdf path, --output, --verbose). Validates the file exists. Sets up logging. Calls Converter.convert_to_file(). Catches all errors and shows user-friendly messages — no raw stack traces ever reach the terminal.
2. converter.py — orchestrator The only file that knows all layers exist. Wires together the extractor, pipeline, and formatter via dependency injection. Calls them in order and writes the final string to disk.
3. extractor/pdfplumber_extractor.py — reads PDF Opens the PDF with pdfplumber. Groups words into line-level TextBlock objects, capturing font size and name per line. Produces a Document (list of PageData) passed to the next stage.
4. cleaners/pipeline.py — cleaning chain Runs four cleaners in order: PageNumberCleaner strips standalone digits and "Page N of M". WhitespaceCleaner collapses spaces and removes empty blocks. HeadingDetector tags blocks by font size and regex. LineWrapCleaner merges soft-wrapped lines.
5. formatter/markdown.py — renders output Reads each block's _heading_level attribute (set by HeadingDetector) and renders #, ##, ### or plain paragraph text. Collapses blank lines. Returns a clean Markdown string.

2 · File Roles

3 · Context Diagram

4 · Changing the Command Name

The CLI command name is defined in exactly one place — pyproject.toml:

# pyproject.toml
[project.scripts]
pdfcleanerx = "pdfcleanerx.cli:app"
# ↑ this is what you type in terminal

To rename to, say, cleanpdf:

[project.scripts]
cleanpdf = "pdfcleanerx.cli:app"

Then reinstall:

pip install -e .

5 · PDF Path Handling

You can pass any path — relative, absolute, or shell glob. The PDF does not need to be in your current directory.

# relative path
pdfcleanerx convert report.pdf
pdfcleanerx convert ./docs/report.pdf

# absolute path
pdfcleanerx convert /home/user/Downloads/report.pdf

# glob — shell expands, all matched PDFs are converted
pdfcleanerx convert ~/Documents/*.pdf --output-dir ./out

Internally, cli.py passes the path to converter.py, which wraps it in Python's pathlib.Path. Typer validates the file exists before any PDF logic runs. Relative paths resolve against wherever you run the command.

6 · Configuration Reference (.env)

Copy .env.example to .env. All values have defaults — you only need to set what you want to override.

7 · Quick Start

Install

pip install -e ".[dev]"
cp .env.example .env

CLI Usage

# single file → output/report.md
pdfcleanerx convert report.pdf

# named output
pdfcleanerx convert report.pdf --output clean.md

# print to stdout
pdfcleanerx convert report.pdf --stdout

# batch
pdfcleanerx convert docs/*.pdf --output-dir ./markdown

# debug logging
pdfcleanerx convert report.pdf --verbose

Python SDK

from pdfcleanerx import Converter

converter = Converter()
markdown = converter.convert("report.pdf")
converter.convert_to_file("report.pdf", "report.md")

Custom Pipeline (Dependency Injection)

from pdfcleanerx import Converter
from pdfcleanerx.cleaners import CleanerPipeline, PageNumberCleaner, WhitespaceCleaner

pipeline = CleanerPipeline([PageNumberCleaner(), WhitespaceCleaner()])
converter = Converter(pipeline=pipeline)
markdown = converter.convert("report.pdf")

Run Tests

pytest                            # 43 tests
pytest --cov=pdfcleanerx         # with coverage

Build & Publish

pip install build twine
python -m build
twine upload --repository testpypi dist/*   # test first
twine upload dist/*                         # then publish

8 · Adding Custom Extensions

Custom Cleaner

from pdfcleanerx.cleaners.base import BaseCleaner
from pdfcleanerx.models import Document

class MyCleaner(BaseCleaner):
    def clean(self, document: Document) -> Document:
        for page in document.pages:
            for block in page.blocks:
                block.text = block.text.replace("©", "")
        return document

Custom Formatter (e.g. HTML output)

from pdfcleanerx.formatter.base import BaseFormatter
from pdfcleanerx.models import Document

class HtmlFormatter(BaseFormatter):
    def format(self, document: Document) -> str:
        ...

converter = Converter(formatter=HtmlFormatter())

Future Extension Points