nestedpdfmerger 1.0.0__tar.gz

nestedpdfmerger-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nested-pdf-merger contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nestedpdfmerger-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: nestedpdfmerger
+Version: 1.0.0
+Summary: Merge PDFs recursively from a folder tree into a single PDF with hierarchical bookmarks.
+License: MIT License
+        
+        Copyright (c) 2026 nested-pdf-merger contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Repository, https://github.com/Lyutenant/nested-pdf-merger
+Keywords: pdf,merge,bookmarks,cli
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pypdf>=4.0
+Requires-Dist: natsort>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Dynamic: license-file
+
+# nestedpdfmerger
+
+Merge PDFs recursively from a folder tree into a single PDF with automatic hierarchical bookmarks based on the directory structure.
+
+## Installation
+
+```bash
+pip install nestedpdfmerger
+```
+
+## Quick start
+
+```bash
+nestedpdfmerger ./reports -o merged.pdf
+```
+
+## Example input tree
+
+```
+reports/
+├── intro.pdf
+├── chapter1/
+│   ├── part1.pdf
+│   └── part2.pdf
+└── appendix/
+    └── appendixA.pdf
+```
+
+Resulting bookmarks in `merged.pdf`:
+
+```
+intro
+chapter1
+ ├─ part1
+ └─ part2
+appendix
+ └─ appendixA
+```
+
+## Usage
+
+```
+nestedpdfmerger INPUT_DIR -o OUTPUT.pdf [options]
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `-o, --output PATH` | Output PDF path (default: `<INPUT_DIR>.pdf`) |
+| `--sort {natural,alpha,mtime}` | Sort mode (default: `natural`) |
+| `--reverse` | Reverse sort order |
+| `--exclude NAME [NAME ...]` | Directory names to skip |
+| `--exclude-hidden` | Skip hidden directories (starting with `.`) |
+| `--no-bookmarks` | Disable hierarchical bookmarks |
+| `--dry-run` | Preview merge order without writing output |
+| `--strict` | Stop on first PDF error instead of skipping |
+| `--verbose` | Show detailed progress |
+| `--quiet` | Suppress non-error output |
+| `--version` | Show version and exit |
+
+### Examples
+
+Preview what would be merged:
+
+```bash
+nestedpdfmerger ./reports --dry-run
+```
+
+Natural sort, exclude backup folders, verbose output:
+
+```bash
+nestedpdfmerger ./reports \
+  --output merged.pdf \
+  --sort natural \
+  --exclude Backup Data \
+  --verbose
+```
+
+Sort by modification time, newest last:
+
+```bash
+nestedpdfmerger ./reports -o merged.pdf --sort mtime --reverse
+```
+
+## Python API
+
+```python
+from nestedpdfmerger import merge_pdf_tree
+
+merge_pdf_tree(
+    input_dir="reports",
+    output_file="merged.pdf",
+    sort_mode="natural",
+    exclude=["Backup", "Data"],
+    bookmarks=True,
+)
+```
+
+## Sort modes
+
+| Mode | Description |
+|---|---|
+| `natural` | Human-friendly natural sort (1, 2, 10 not 1, 10, 2) |
+| `alpha` | Case-insensitive alphabetical |
+| `mtime` | File/directory modification time (oldest first) |
+
+## Error handling
+
+By default, corrupted, encrypted, or unreadable PDFs are **warned and skipped**. Use `--strict` to stop on the first error.
+
+## License
+
+MIT

nestedpdfmerger-1.0.0/README.md

@@ -0,0 +1,114 @@
+# nestedpdfmerger
+
+Merge PDFs recursively from a folder tree into a single PDF with automatic hierarchical bookmarks based on the directory structure.
+
+## Installation
+
+```bash
+pip install nestedpdfmerger
+```
+
+## Quick start
+
+```bash
+nestedpdfmerger ./reports -o merged.pdf
+```
+
+## Example input tree
+
+```
+reports/
+├── intro.pdf
+├── chapter1/
+│   ├── part1.pdf
+│   └── part2.pdf
+└── appendix/
+    └── appendixA.pdf
+```
+
+Resulting bookmarks in `merged.pdf`:
+
+```
+intro
+chapter1
+ ├─ part1
+ └─ part2
+appendix
+ └─ appendixA
+```
+
+## Usage
+
+```
+nestedpdfmerger INPUT_DIR -o OUTPUT.pdf [options]
+```
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `-o, --output PATH` | Output PDF path (default: `<INPUT_DIR>.pdf`) |
+| `--sort {natural,alpha,mtime}` | Sort mode (default: `natural`) |
+| `--reverse` | Reverse sort order |
+| `--exclude NAME [NAME ...]` | Directory names to skip |
+| `--exclude-hidden` | Skip hidden directories (starting with `.`) |
+| `--no-bookmarks` | Disable hierarchical bookmarks |
+| `--dry-run` | Preview merge order without writing output |
+| `--strict` | Stop on first PDF error instead of skipping |
+| `--verbose` | Show detailed progress |
+| `--quiet` | Suppress non-error output |
+| `--version` | Show version and exit |
+
+### Examples
+
+Preview what would be merged:
+
+```bash
+nestedpdfmerger ./reports --dry-run
+```
+
+Natural sort, exclude backup folders, verbose output:
+
+```bash
+nestedpdfmerger ./reports \
+  --output merged.pdf \
+  --sort natural \
+  --exclude Backup Data \
+  --verbose
+```
+
+Sort by modification time, newest last:
+
+```bash
+nestedpdfmerger ./reports -o merged.pdf --sort mtime --reverse
+```
+
+## Python API
+
+```python
+from nestedpdfmerger import merge_pdf_tree
+
+merge_pdf_tree(
+    input_dir="reports",
+    output_file="merged.pdf",
+    sort_mode="natural",
+    exclude=["Backup", "Data"],
+    bookmarks=True,
+)
+```
+
+## Sort modes
+
+| Mode | Description |
+|---|---|
+| `natural` | Human-friendly natural sort (1, 2, 10 not 1, 10, 2) |
+| `alpha` | Case-insensitive alphabetical |
+| `mtime` | File/directory modification time (oldest first) |
+
+## Error handling
+
+By default, corrupted, encrypted, or unreadable PDFs are **warned and skipped**. Use `--strict` to stop on the first error.
+
+## License
+
+MIT

nestedpdfmerger-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nestedpdfmerger"
+version = "1.0.0"
+description = "Merge PDFs recursively from a folder tree into a single PDF with hierarchical bookmarks."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+keywords = ["pdf", "merge", "bookmarks", "cli"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "pypdf>=4.0",
+    "natsort>=8.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+]
+
+[project.scripts]
+nestedpdfmerger = "nestedpdfmerger.cli:main"
+
+[project.urls]
+Repository = "https://github.com/Lyutenant/nested-pdf-merger"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+exclude = ["script.py", "examples/"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

nestedpdfmerger-1.0.0/setup.cfg

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

nestedpdfmerger-1.0.0/src/nestedpdfmerger/__init__.py

@@ -0,0 +1,6 @@
+"""nestedpdfmerger — merge PDFs recursively with hierarchical bookmarks."""
+
+from .merger import merge_pdf_tree
+
+__version__ = "1.0.0"
+__all__ = ["merge_pdf_tree", "__version__"]

nestedpdfmerger-1.0.0/src/nestedpdfmerger/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for ``python -m nestedpdfmerger``."""
+
+from .cli import main
+
+main()

nestedpdfmerger-1.0.0/src/nestedpdfmerger/bookmarks.py

@@ -0,0 +1,37 @@
+"""Bookmark data structure for hierarchical PDF outline entries."""
+
+from __future__ import annotations
+
+
+class Bookmark:
+    """Represents a single PDF outline (bookmark) entry with optional children."""
+
+    __slots__ = ("_page", "_title", "_children")
+
+    def __init__(self, page: int, title: str) -> None:
+        self._page = page
+        self._title = title
+        self._children: list[Bookmark] = []
+
+    @property
+    def page(self) -> int:
+        return self._page
+
+    @property
+    def title(self) -> str:
+        return self._title
+
+    @property
+    def children(self) -> list[Bookmark]:
+        return self._children
+
+    def add_child(self, child: Bookmark) -> None:
+        if not isinstance(child, Bookmark):
+            raise TypeError("child must be a Bookmark instance")
+        self._children.append(child)
+
+    def __repr__(self) -> str:
+        return (
+            f"Bookmark(page={self._page!r}, title={self._title!r},"
+            f" children={len(self._children)})"
+        )

nestedpdfmerger-1.0.0/src/nestedpdfmerger/cli.py

@@ -0,0 +1,132 @@
+"""Command-line interface for nestedpdfmerger."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import DEFAULT_SORT_MODE, VALID_SORT_MODES
+from .errors import MergeError
+from .merger import merge_pdf_tree
+
+
+def _setup_logging(verbose: bool, quiet: bool) -> None:
+    if quiet:
+        level = logging.ERROR
+    elif verbose:
+        level = logging.DEBUG
+    else:
+        level = logging.INFO
+    logging.basicConfig(level=level, format="%(message)s")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nestedpdfmerger",
+        description=(
+            "Merge PDFs recursively from a folder tree into a single PDF "
+            "with automatic hierarchical bookmarks."
+        ),
+    )
+    parser.add_argument(
+        "input_dir",
+        metavar="INPUT_DIR",
+        help="Root directory to scan for PDFs.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="PATH",
+        default=None,
+        help=(
+            "Output PDF file path. "
+            "Defaults to <INPUT_DIR>.pdf in the same parent directory."
+        ),
+    )
+    parser.add_argument(
+        "--sort",
+        choices=list(VALID_SORT_MODES),
+        default=DEFAULT_SORT_MODE,
+        metavar="{" + ",".join(VALID_SORT_MODES) + "}",
+        help="Sort mode for files and directories (default: %(default)s).",
+    )
+    parser.add_argument(
+        "--reverse",
+        action="store_true",
+        help="Reverse the sort order.",
+    )
+    parser.add_argument(
+        "--exclude",
+        nargs="+",
+        metavar="NAME",
+        default=[],
+        help="Directory names to exclude (space-separated).",
+    )
+    parser.add_argument(
+        "--exclude-hidden",
+        action="store_true",
+        help="Exclude hidden directories (names starting with '.').",
+    )
+    parser.add_argument(
+        "--no-bookmarks",
+        action="store_true",
+        help="Disable hierarchical bookmarks in the output PDF.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview merge order and bookmark structure without writing output.",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Stop on the first PDF error instead of skipping the file.",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show detailed progress (scanned folders, detected PDFs, etc.).",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress all non-error output.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    _setup_logging(args.verbose, args.quiet)
+
+    output = args.output
+    if output is None and not args.dry_run:
+        output = str(Path(args.input_dir).resolve().with_suffix(".pdf"))
+
+    try:
+        merge_pdf_tree(
+            input_dir=args.input_dir,
+            output_file=output,
+            sort_mode=args.sort,
+            reverse=args.reverse,
+            exclude=args.exclude,
+            bookmarks=not args.no_bookmarks,
+            exclude_hidden=args.exclude_hidden,
+            dry_run=args.dry_run,
+            strict=args.strict,
+            verbose=args.verbose,
+            quiet=args.quiet,
+        )
+    except (MergeError, ValueError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)

nestedpdfmerger-1.0.0/src/nestedpdfmerger/config.py

@@ -0,0 +1,8 @@
+"""Default configuration values for nestedpdfmerger."""
+
+DEFAULT_SORT_MODE = "natural"
+VALID_SORT_MODES = ("natural", "alpha", "mtime")
+DEFAULT_REVERSE = False
+DEFAULT_BOOKMARKS = True
+DEFAULT_STRICT = False
+DEFAULT_EXCLUDE_HIDDEN = False

nestedpdfmerger-1.0.0/src/nestedpdfmerger/errors.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for nestedpdfmerger."""
+
+
+class MergeError(Exception):
+    """Raised in strict mode when a PDF cannot be processed."""
+
+
+class EncryptedPDFError(MergeError):
+    """Raised when a PDF file is encrypted and cannot be merged."""
+
+
+class CorruptedPDFError(MergeError):
+    """Raised when a PDF file is corrupted and cannot be read."""