Metadata-Version: 2.5
Name: apdf
Version: 1.2
Summary: Meet another powerful PDF editing tool, designed to modify raw PDF data in hexadecimal format as well as Unicode text.
Author: Abodx9
License-Expression: MIT
Keywords: Hex,PDFs,Raw,Text,Tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: fonttools==4.63.0
Requires-Dist: pypdf==6.16.1
Description-Content-Type: text/markdown

# A-PDF

**A-PDF** is a fast, command-line tool designed to replace Unicode and Hex text directly within PDF content streams. 

## Features
- **Direct Stream Replacement**: Modifies the underlying PDF streams directly for fast and precise text replacement.
- **Unicode & Hex Support**: Replace text using standard string replacements that are automatically encoded to the document's fonts.
- **Spacing Compensation**: Automatically compensates for `TJ` (Text Justification) width adjustments after text replacements to preserve document layout (can be disabled).
- **Strict Mode**: Optionally fail replacements if text is missing or the font cannot encode the requested characters.
- **Fallback Font Support**: Embed a custom TrueType font when the PDF's subset font lacks a glyph, or disable fallback entirely.
- **Page Selection**: Select specific pages to process.

## Installation

You can run the tool directly using [uv](https://github.com/astral-sh/uv), which will automatically handle dependencies:
```bash
uv add apdf # or As a tool: uv tool install apdf
# then Run it
uv run apdf --help
```
Or simply use it in your standard Python environment.
```bash
pip install apdf

# Run 
apdf --help
```

## Usage As Library

```python
from apdf import replace_pdf_text_detailed

rep = replace_pdf_text_detailed(
    input_pdf="Test1.pdf",
    output_pdf="Test1_out.pdf",
    replacements={
        "Old Text": "New Text",
        # "Hello": "World",
        # "2026": "2027", 
    },

    # Optional parameters:
    pages={2, 3, 4},       # Only these pages
    # pages=2,             # Only page 2
    # pages=range(1, 6),   # Pages 1 through 5
    # pages=None,          # All pages (default)

    # fallback_font="FONT.ttf",
    # font_fallback=True,
    # strict=True,
)

print("Replacements:", rep.replacements)
print("Changed streams:", rep.changed_streams)
print("Scanned streams:", rep.scanned_streams)
print("Missing:", rep.missing)
print("Encoding failures:", rep.encoding_failures)
```

## Usage As CLI Tool

```bash
apdf [-h] [-r OLD=NEW] [-nopa] [-s] [-ff FONT.ttf] [-no-ff] input [output]
```

### Examples

**Basic replacement:**
```bash
apdf input.pdf output.pdf -r "OldText=NewText"
```

**Multiple replacements:**
```bash
apdf document.pdf updated_document.pdf \
    -r "Draft=Final" \
    -r "2023=2024"
```

**Disable width compensation** (if characters are bunching up or spacing is incorrect):
```bash
apdf input.pdf output.pdf -r "foo=bar" -nopa
```

**Strict mode** (fails if the replacement target is not found):
```bash
apdf input.pdf output.pdf -r "foo=bar" -s
```

### Arguments

* `input`: The source PDF file.
* `output`: (Optional) The destination PDF file. Defaults to `output.pdf`.
* `-r OLD=NEW`: Replace. The text replacement pair. You can supply this argument multiple times.
* `-p 2`, `-p 2,3,4`, or `-p 1-5` to edit only selected pages. Without
  `-p`, all pages are processed.
* `-nopa`: No preserve advance. Do not compensate `TJ` text widths after making replacements.
* `-s`: Strict. Fail if the original text is missing or the selected font cannot encode the new text.
* `-ff FONT.ttf`: Fallback font. TrueType font to embed when the PDF's subset font lacks a glyph.
* `-no-ff`: No font fallback. Reject missing glyphs instead of embedding a fallback font.
