pdfslice-py 1.0.0__tar.gz

pdfslice_py-1.0.0/LICENSE.md

@@ -0,0 +1,52 @@
+# Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be
+bound by the terms and conditions of this Creative Commons
+Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public
+License"). To the extent this Public License may be interpreted as a contract,
+You are granted the Licensed Rights in consideration of Your acceptance of these
+terms and conditions, and the Licensor grants You such rights in consideration
+of benefits the Licensor receives from making the Licensed Material available
+under these terms and conditions.
+
+## Section 1 – Definitions.
+
+- **Licensed Material**: the artistic or literary work, database, or other
+  material to which the Licensor applied this Public License.
+- **Licensor**: the individual(s) or entity(ies) granting rights under this
+  Public License.
+- **You**: the individual or entity exercising the Licensed Rights under this
+  Public License.
+- **Share**: to provide material to the public by any means or process.
+- **Adapted Material**: material derived from or modified based on the Licensed
+  Material.
+- **NonCommercial**: not primarily intended for or directed towards commercial
+  advantage or monetary compensation.
+
+## Section 2 – Scope.
+
+### 2.1 License Grant
+
+Subject to the terms of this Public License, the Licensor grants You a
+worldwide, royalty-free, non-exclusive, irrevocable license to:
+
+- **Share**: copy and redistribute the Licensed Material in any medium or
+  format.
+- **Adapt**: remix, transform, and build upon the Licensed Material.
+
+### 2.2 Conditions
+
+- **Attribution (BY)**: You must give appropriate credit, provide a link to the
+  license, and indicate if changes were made.
+- **NonCommercial (NC)**: You may **not** use the material for commercial
+  purposes.
+- **ShareAlike (SA)**: If you remix, transform, or build upon the material, you
+  must distribute your contributions under the same license as the original.
+
+## Section 3 – Disclaimer.
+
+The Licensed Material is provided "as-is" without any warranties or guarantees.
+The Licensor is not liable for any damages arising from its use.
+
+**Full License Text:**
+[Creative Commons License](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode)

pdfslice_py-1.0.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: pdfslice-py
+Version: 1.0.0
+Summary: Split, gather, and verify PDF <-> page-image sets (Python port of pdfslice)
+Author: DuckyMomo20012
+License: # Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Public License
+        
+        By exercising the Licensed Rights (defined below), You accept and agree to be
+        bound by the terms and conditions of this Creative Commons
+        Attribution-NonCommercial-ShareAlike 4.0 International Public License ("Public
+        License"). To the extent this Public License may be interpreted as a contract,
+        You are granted the Licensed Rights in consideration of Your acceptance of these
+        terms and conditions, and the Licensor grants You such rights in consideration
+        of benefits the Licensor receives from making the Licensed Material available
+        under these terms and conditions.
+        
+        ## Section 1 – Definitions.
+        
+        - **Licensed Material**: the artistic or literary work, database, or other
+          material to which the Licensor applied this Public License.
+        - **Licensor**: the individual(s) or entity(ies) granting rights under this
+          Public License.
+        - **You**: the individual or entity exercising the Licensed Rights under this
+          Public License.
+        - **Share**: to provide material to the public by any means or process.
+        - **Adapted Material**: material derived from or modified based on the Licensed
+          Material.
+        - **NonCommercial**: not primarily intended for or directed towards commercial
+          advantage or monetary compensation.
+        
+        ## Section 2 – Scope.
+        
+        ### 2.1 License Grant
+        
+        Subject to the terms of this Public License, the Licensor grants You a
+        worldwide, royalty-free, non-exclusive, irrevocable license to:
+        
+        - **Share**: copy and redistribute the Licensed Material in any medium or
+          format.
+        - **Adapt**: remix, transform, and build upon the Licensed Material.
+        
+        ### 2.2 Conditions
+        
+        - **Attribution (BY)**: You must give appropriate credit, provide a link to the
+          license, and indicate if changes were made.
+        - **NonCommercial (NC)**: You may **not** use the material for commercial
+          purposes.
+        - **ShareAlike (SA)**: If you remix, transform, or build upon the material, you
+          must distribute your contributions under the same license as the original.
+        
+        ## Section 3 – Disclaimer.
+        
+        The Licensed Material is provided "as-is" without any warranties or guarantees.
+        The Licensor is not liable for any damages arising from its use.
+        
+        **Full License Text:**
+        [Creative Commons License](https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode)
+        
+Requires-Python: >=3.10
+License-File: LICENSE.md
+Requires-Dist: click>=8.1
+Requires-Dist: pypdf>=4.0
+Requires-Dist: pypdfium2>=4.30
+Requires-Dist: pillow>=10.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.6; extra == "lint"
+Dynamic: license-file

pdfslice_py-1.0.0/README.md

@@ -0,0 +1,230 @@
+# pdfslice-py
+
+PDF page-image splitter, gatherer, and integrity checker — Python port of
+[pdfslice](https://github.com/DuckyMomo20012/pdfslice) (TypeScript).
+
+pdfslice-py helps you break a PDF into one image per page, keep a manifest of
+the split output, verify whether all page images are present, and rebuild a
+PDF from those images when needed.
+
+## About the Project
+
+This project is designed for workflows where PDF pages need to be processed
+as images without losing the source document structure. It keeps the
+original PDF intact, writes page-level JPG files into a folder beside the
+source, and records metadata so the project can later verify or reconstruct
+the full document.
+
+### Features
+
+- Split PDF files into per-page JPG images
+- Keep a manifest with page hashes and metadata
+- Check for missing page images without rewriting a PDF
+- Gather page images back into a single PDF
+- Optionally flatten output folders across a directory tree
+- Support dry-run mode for safe previewing
+
+### Port notes (vs. the TypeScript original)
+
+- `pdf-to-img` + `sharp` → [`pypdfium2`](https://github.com/pypdfium2-team/pypdfium2)
+  + [`Pillow`](https://python-pillow.org/) for rasterizing pages and encoding
+  JPEGs. `pypdfium2` (Google's PDFium, BSD-licensed) was chosen over PyMuPDF
+  specifically to keep pdfslice-py permissively licensed — PyMuPDF is AGPL.
+- `pdf-lib` → [`pypdf`](https://pypdf.readthedocs.io/) for reading page
+  counts, and Pillow's multi-page PDF writer for rebuilding a PDF from images
+  in `gather`.
+- `winston` → a small stdlib-`logging`-based logger with the same
+  level/verbose/quiet/log-file behavior.
+- `@stricli/core` → [`click`](https://click.palletsprojects.com/) for the CLI.
+- The on-disk manifest (`.pdfslice-manifest.json`) uses the exact same
+  camelCase JSON schema as the TypeScript version, so a folder split by
+  either implementation can be gathered/checked by the other.
+
+## Getting Started
+
+### Prerequisites
+
+- Python >= 3.10
+- [uv](https://docs.astral.sh/uv/)
+
+```bash
+pip install uv
+```
+
+### Install
+
+Install the CLI globally with uv:
+
+```bash
+uv tool install .
+# or, once published: uv tool install pdfslice-py
+```
+
+Or set up for local development:
+
+```bash
+uv venv
+uv pip install -e ".[test]"
+uv run pdfslice --help
+```
+
+Install straight from GitHub:
+
+```bash
+uv tool install git+https://github.com/DuckyMomo20012/pdfslice-py.git
+```
+
+## Usage
+
+The CLI exposes three commands:
+
+```bash
+pdfslice split <input> [--level <n>] [--flatten] [--template <string>] [--dry-run] [--verbose] [--quiet] [--log-file <path>]
+pdfslice gather <input> [--backup/--no-backup] [--dry-run] [--verbose] [--quiet] [--log-file <path>]
+pdfslice check <input> [--verbose] [--quiet] [--log-file <path>]
+```
+
+(With `uv run`, prefix each command with `uv run`, e.g. `uv run pdfslice split ./documents`.)
+
+### 1) Split a PDF into images
+
+```bash
+pdfslice split ./documents
+```
+
+This scans the target folder for PDF files and creates a folder for each
+PDF, for example:
+
+```text
+documents/
+├── sample.pdf
+└── sample/
+    ├── sample.001.jpg
+    ├── sample.002.jpg
+    ├── sample.003.jpg
+    ├── sample.pdf
+    └── .pdfslice-manifest.json
+```
+
+The original PDF is preserved and copied into the generated output folder.
+
+#### Directory search depth
+
+```bash
+pdfslice split ./documents --level 2
+```
+
+Use `--level` to control how deep the search should go when scanning nested
+folders.
+
+#### Flatten output
+
+```bash
+pdfslice split ./documents --flatten
+```
+
+This places each generated output folder at the input root instead of
+beside each source PDF.
+
+#### Custom filename template
+
+```bash
+pdfslice split ./documents --template "page-{{page_number}}.jpg"
+```
+
+Use `{{filename}}` and `{{page_number}}` placeholders to control the page
+image filename (default: `{{filename}}.{{page_number}}.jpg`). Exactly one
+`{{page_number}}` is required. The template is saved in the manifest, so
+`gather`/`check` parse page numbers back out correctly without needing
+`--template` repeated.
+
+### 2) Gather images back into a PDF
+
+```bash
+pdfslice gather ./documents/sample
+```
+
+This rebuilds a combined PDF from the page images in the split unit folder
+and **overwrites the original PDF in place** (same filename, same location).
+A backup of the previous PDF (`sample.bak-<timestamp>.pdf`) is created first
+by default — pass `--no-backup` to skip it.
+
+If the PDF already reflects the current images (nothing has changed since
+the last gather), the project skips unnecessary regeneration.
+
+### 3) Check for missing page images
+
+```bash
+pdfslice check ./documents/sample
+```
+
+This reports missing pages without creating a PDF output. Exits with status
+code 1 if any unit has missing pages.
+
+## Common flags
+
+- `--dry-run`: preview actions without writing files
+- `--backup` / `--no-backup` (gather only, default on): back up the existing
+  PDF before overwriting it
+- `--template <string>` (split only): custom page-image filename template
+- `--verbose`: print debug logging
+- `--quiet`: print only errors
+- `--log-file <path>`: write logs as JSON lines as well as console
+
+## Example workflow
+
+```bash
+pdfslice split ./input --level 2
+pdfslice check ./input/report
+pdfslice gather ./input/report
+```
+
+## Project Structure
+
+```text
+src/pdfslice_py/
+├── __init__.py
+├── cli.py                 # click CLI: split, gather, check commands
+├── discover.py            # find_pdfs, find_images_deep, page_image_name
+├── filename_template.py   # {{filename}}/{{page_number}} template compiler
+├── gather.py               # rebuild PDF from images / check-only mode
+├── hash.py                 # streamed SHA-256 file hashing
+├── logger.py                # verbose/quiet/log-file logger
+├── manifest.py              # .pdfslice-manifest.json schema + read/write
+└── split.py                 # PDF -> per-page JPG splitting
+tests/
+├── test_discover.py
+├── test_filename_template.py
+├── test_manifest.py
+└── test_split_gather.py
+```
+
+## Running Tests
+
+```bash
+uv pip install -e ".[test]"
+uv run pytest -v
+```
+
+## Contributing
+
+Contributions are welcome.
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run the relevant checks and tests
+5. Open a pull request
+
+## License
+
+This project is licensed under the Creative Commons
+Attribution-NonCommercial-ShareAlike 4.0 International License, matching the
+[TypeScript original](https://github.com/DuckyMomo20012/pdfslice).
+
+See [LICENSE.md](LICENSE.md) for the full text.
+
+## Repository
+
+- Original (TypeScript): https://github.com/DuckyMomo20012/pdfslice
+- Author: DuckyMomo20012

pdfslice_py-1.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pdfslice-py"
+version = "1.0.0"
+description = "Split, gather, and verify PDF <-> page-image sets (Python port of pdfslice)"
+requires-python = ">=3.10"
+license = { file = "LICENSE.md" }
+authors = [{ name = "DuckyMomo20012" }]
+dependencies = [
+    "click>=8.1",
+    "pypdf>=4.0",
+    "pypdfium2>=4.30",
+    "pillow>=10.0",
+]
+
+[project.scripts]
+pdfslice = "pdfslice_py.cli:cli"
+
+[project.optional-dependencies]
+test = ["pytest>=8.0"]
+lint = ["ruff>=0.6"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "UP",  # pyupgrade
+    "B",   # flake8-bugbear
+    "A",   # flake8-builtins
+    "N",   # pep8-naming
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "N815", # camelCase attrs — manifest fields mirror the on-disk JSON schema on purpose
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["N802"] # test_* function names, camelCase-style asserts on manifest fields
+
+[tool.ruff.format]
+quote-style = "double"

pdfslice_py-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pdfslice_py-1.0.0/src/pdfslice_py/__init__.py

@@ -0,0 +1,6 @@
+"""pdfslice-py: split PDFs into page images, then gather or check them back.
+
+Python port of https://github.com/DuckyMomo20012/pdfslice (TypeScript).
+"""
+
+__version__ = "1.0.0"

pdfslice_py-1.0.0/src/pdfslice_py/cli.py

@@ -0,0 +1,130 @@
+"""CLI. Port of src/app.ts + src/commands/{split,gather,check}/{command,impl}.ts."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from .filename_template import DEFAULT_TEMPLATE
+from .gather import gather_all
+from .logger import create_logger
+from .split import split_all
+
+
+def _log_flags(f: click.decorators.FC) -> click.decorators.FC:
+    f = click.option("--verbose", is_flag=True, default=False, help="Enable debug logging")(f)
+    f = click.option("--quiet", is_flag=True, default=False, help="Only log errors")(f)
+    f = click.option("--log-file", default=None, help="Path to also write logs as JSON")(f)
+    return f
+
+
+@click.group()
+@click.version_option(version="0.1.0", prog_name="pdfslice")
+def cli() -> None:
+    """Split PDFs into page images, then gather or check them back."""
+
+
+@cli.command("split")
+@click.argument("input", type=str)
+@click.option(
+    "-l",
+    "--level",
+    type=int,
+    default=1,
+    help="How many directory levels deep to search for PDFs",
+)
+@click.option(
+    "-f",
+    "--flatten",
+    is_flag=True,
+    default=False,
+    help="Pull every discovered PDF's output folder to the input root, "
+    "instead of alongside each PDF",
+)
+@click.option(
+    "--template",
+    type=str,
+    default=DEFAULT_TEMPLATE,
+    help="Page image filename template. Placeholders: {{filename}}, "
+    "{{page_number}}. Must contain exactly one {{page_number}}.",
+)
+@click.option(
+    "--dry-run", is_flag=True, default=False, help="Preview actions without writing any files"
+)
+@_log_flags
+def split_cmd(
+    input: str,  # noqa: A002 - mirrors Click argument name and TS API
+    level: int,
+    flatten: bool,
+    template: str,
+    dry_run: bool,
+    verbose: bool,
+    quiet: bool,
+    log_file: str | None,
+) -> None:
+    """Split PDF(s) into per-page JPG images alongside the source file."""
+    logger = create_logger(verbose=verbose, quiet=quiet, log_file=log_file)
+    results = split_all(
+        input,
+        logger,
+        level=level,
+        flatten=flatten,
+        template=template,
+        dry_run=dry_run,
+    )
+    logger.info(f"Done. Processed {len(results)} PDF(s).")
+
+
+@cli.command("gather")
+@click.argument("input", type=str)
+@click.option(
+    "--dry-run", is_flag=True, default=False, help="Preview actions without writing any files"
+)
+@click.option(
+    "--backup/--no-backup",
+    default=True,
+    help="Back up the existing PDF before overwriting it",
+)
+@_log_flags
+def gather_cmd(
+    input: str,  # noqa: A002 - mirrors Click argument name and TS API
+    dry_run: bool,
+    backup: bool,
+    verbose: bool,
+    quiet: bool,
+    log_file: str | None,
+) -> None:
+    """Gather page images back into a PDF, reporting any missing pages."""
+    logger = create_logger(verbose=verbose, quiet=quiet, log_file=log_file)
+    reports = gather_all(input, logger, dry_run=dry_run, check_only=False, backup=backup)
+
+    with_missing = [r for r in reports if r.missing_pages]
+    if with_missing:
+        logger.warn(f"{len(with_missing)} unit(s) have missing pages")
+    logger.info(f"Done. Processed {len(reports)} unit folder(s).")
+
+
+@cli.command("check")
+@click.argument("input", type=str)
+@_log_flags
+def check_cmd(
+    input: str,  # noqa: A002 - mirrors Click argument name and TS API
+    verbose: bool,
+    quiet: bool,
+    log_file: str | None,
+) -> None:
+    """Report missing page images without writing any PDF (read-only)."""
+    logger = create_logger(verbose=verbose, quiet=quiet, log_file=log_file)
+    reports = gather_all(input, logger, check_only=True)
+
+    with_missing = [r for r in reports if r.missing_pages]
+    if with_missing:
+        logger.warn(f"{len(with_missing)} unit(s) have missing pages")
+        sys.exit(1)
+    else:
+        logger.info(f"All {len(reports)} unit(s) complete.")
+
+
+if __name__ == "__main__":
+    cli()

pdfslice_py-1.0.0/src/pdfslice_py/discover.py

@@ -0,0 +1,67 @@
+"""PDF/image discovery on the filesystem. Direct port of lib/discover.ts."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from .filename_template import DEFAULT_TEMPLATE, compile_template
+
+_IMAGE_SUFFIXES = {".jpg", ".jpeg"}
+
+
+def find_pdfs(root: str | Path, level: int = 1) -> list[str]:
+    """Find all PDF files under `root`, descending up to `level` directories
+    deep. level=1 (default): PDFs directly in `root` only. level=2: `root`
+    and one subfolder deep. Etc. If `root` itself is a PDF file, returns
+    just that file."""
+    root = Path(root)
+    if root.is_file():
+        return [str(root)] if root.suffix.lower() == ".pdf" else []
+
+    results: list[str] = []
+
+    def walk(directory: Path, depth: int) -> None:
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                full = Path(entry.path)
+                if entry.is_file() and full.suffix.lower() == ".pdf":
+                    results.append(str(full))
+                elif entry.is_dir() and depth < level:
+                    walk(full, depth + 1)
+
+    walk(root, 1)
+    return results
+
+
+def find_images_deep(root: str | Path) -> list[str]:
+    """Recursively find all image files (jpg/jpeg) under `root`, any depth.
+    Used by gather/check, since split output can be nested by flatten mode."""
+    root = Path(root)
+    results: list[str] = []
+
+    def walk(directory: Path) -> None:
+        with os.scandir(directory) as entries:
+            for entry in entries:
+                full = Path(entry.path)
+                if entry.is_file() and full.suffix.lower() in _IMAGE_SUFFIXES:
+                    results.append(str(full))
+                elif entry.is_dir():
+                    walk(full)
+
+    walk(root)
+    return results
+
+
+def page_image_name(base_name: str, page: int, template: str = DEFAULT_TEMPLATE) -> str:
+    """Build the page-image filename using a template (default:
+    "{{filename}}.{{page_number}}.jpg"). Page number is zero-padded to 3
+    digits; if the number itself is wider than 3 digits, no padding is
+    applied (natural width is used)."""
+    return compile_template(template).render(base_name, page)
+
+
+def parse_page_from_image_name(file_name: str, template: str = DEFAULT_TEMPLATE) -> int | None:
+    """Parse a page number back out of a name produced by page_image_name,
+    using the same template it was generated with."""
+    return compile_template(template).parse_page(file_name)

pdfslice_py-1.0.0/src/pdfslice_py/filename_template.py

@@ -0,0 +1,55 @@
+"""Page-image filename templating. Direct port of lib/filename-template.ts."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+
+DEFAULT_TEMPLATE = "{{filename}}.{{page_number}}.jpg"
+
+_PLACEHOLDER_PATTERN = re.compile(r"(\{\{filename\}\}|\{\{page_number\}\})")
+
+
+def _pad_page_number(page: int) -> str:
+    return str(page).zfill(3) if page < 1000 else str(page)
+
+
+@dataclass(frozen=True)
+class FilenameTemplate:
+    render: Callable[[str, int], str]
+    parse_page: Callable[[str], int | None]
+
+
+def compile_template(template: str) -> FilenameTemplate:
+    page_count = template.count("{{page_number}}")
+    if page_count != 1:
+        raise ValueError(
+            f"Template must contain exactly one {{{{page_number}}}} placeholder, "
+            f'found {page_count} in "{template}"'
+        )
+
+    parts = _PLACEHOLDER_PATTERN.split(template)
+    regex_source = ""
+    for i, part in enumerate(parts):
+        if i % 2 == 0:
+            regex_source += re.escape(part)
+        elif part == "{{page_number}}":
+            regex_source += r"(\d+)"
+        elif part == "{{filename}}":
+            regex_source += ".+?"
+
+    regex = re.compile(f"^{regex_source}$", re.IGNORECASE)
+
+    def render(base_name: str, page: int) -> str:
+        return template.replace("{{filename}}", base_name).replace(
+            "{{page_number}}", _pad_page_number(page)
+        )
+
+    def parse_page(file_name: str) -> int | None:
+        m = regex.match(file_name)
+        if not m:
+            return None
+        return int(m.group(1))
+
+    return FilenameTemplate(render=render, parse_page=parse_page)