scanmate-merge 0.0.1__tar.gz

scanmate_merge-0.0.1/.gitignore

@@ -0,0 +1,70 @@
+# See https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files for more about ignoring files.
+
+# compiled output
+dist
+tmp
+out-tsc
+
+# tsc --build writes one of these beside every solution tsconfig.
+*.tsbuildinfo
+
+# playground scratch output (aligned.png, diff.png, ...)
+playground-output
+
+# dependencies
+node_modules
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# misc
+.eslintcache
+/.sass-cache
+/connect.lock
+/coverage
+/libpeerconnection.log
+npm-debug.log
+yarn-error.log
+testem.log
+/typings
+
+# System Files
+.DS_Store
+Thumbs.db
+
+.nx/cache
+.nx/workspace-data
+.cursor/rules/nx-rules.mdc
+.github/instructions/nx.instructions.md
+
+.claude/worktrees
+.claude/settings.local.json
+.nx/polygraph
+.nx/self-healing
+.nx/migrate-runs
+vitest.config.*.timestamp*
+# A corpus built from real documents never enters the repository.
+corpus/
+tools/calibration/corpus*/
+
+# Python. `mnci add python-lib` does not add these, and the first pytest run
+# writes bytecode and four tool caches straight into the source tree.
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/

scanmate_merge-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Russo
+
+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.

scanmate_merge-0.0.1/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: scanmate-merge
+Version: 0.0.1
+Summary: Many files in, one PDF out: PDFs, images and rasters, in the order given, mixed freely.
+Project-URL: Homepage, https://github.com/russoedu/scanmate/tree/main/python-packages/scanmate-merge#readme
+Project-URL: Repository, https://github.com/russoedu/scanmate
+Project-URL: Issues, https://github.com/russoedu/scanmate/issues
+Project-URL: Parallels (TypeScript), https://github.com/russoedu/scanmate/tree/main/packages/merge#readme
+Author: Eduardo Russo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: document,evidence,image,merge,pdf,scan
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Text Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.1
+Requires-Dist: pypdf>=5.1
+Requires-Dist: scanmate-ink>=0.0.1
+Description-Content-Type: text/markdown
+
+# scanmate-merge
+
+Many files in, one PDF out: PDFs, images and rasters, in the order given, mixed
+freely.
+
+A **parallel port** of [`@scanmate/merge`][ts], not a replacement for it. The
+TypeScript remains the reference — with one boundary, stated below, that this
+package cannot cross and does not pretend to.
+
+```sh
+pip install scanmate-merge
+```
+
+```python
+from scanmate_merge import merge_documents
+
+result = merge_documents(["scan1.jpg", "contract.pdf", "scan2.png"])
+result.page_count
+result.pages[0].embedding   # 'jpeg' - the source's own bytes, not re-compressed
+```
+
+## What it preserves
+
+- **A PDF's pages are copied, not re-rendered**, so their text layer, vectors
+  and any signatures stay as they were.
+- **A JPEG is embedded as its own bytes** — RGB or grey, no EXIF rotation
+  pending — so a scan is not compressed a second time on its way into evidence.
+- **A PNG's pixels are carried over losslessly.** Not the PNG *file*: a PDF
+  cannot hold one, so the pixels go in deflated, which is what the TypeScript
+  does too.
+- Anything else is decoded — EXIF rotation applied, transparency flattened onto
+  white, every page of a multi-page TIFF — and encoded **once**.
+
+**A single PDF on its own comes back byte for byte.** Re-saving a signed PDF
+breaks its signature, and a PDF "merged" alone has nothing to merge, so it is
+not touched at all. Asking for metadata turns that off, because writing metadata
+means writing a new file, and the result says which happened.
+
+## The parity boundary
+
+Every other package in this port is held to the TypeScript bit for bit. This one
+cannot be, and the reason is not a shortcut: **two PDF writers lay out objects,
+streams and the cross-reference table differently**, so two valid merges of the
+same sources are never the same file. pdf-lib and `pypdf` are different writers.
+
+So parity here is held at the level that actually means something:
+
+| Held exactly | Not held |
+| --- | --- |
+| page count, and which source each page came from | the produced PDF's bytes |
+| how each page was embedded (`jpeg`, `png`, `encoded-png`, …) | object numbering, stream order |
+| every page's size in points, and the dpi it was placed at | compression details |
+| whether a single PDF passed through untouched | |
+| page geometry: `place_image`, `resolve_dpi`, the viewport transforms | |
+| `mark_pages`' count and its warning sentences, verbatim | |
+
+That is the same boundary [`scanmate-ink`][ink] already draws around
+`resampleRaster` and `blurRaster`: where two engines cannot agree by
+construction, say so rather than write a golden nobody can meet.
+
+What the produced file *is* checked for: that it is a readable PDF, that its
+pages are the sizes the result reports, that a JPEG went in as `/DCTDecode` and
+a PNG's pixels as `/FlateDecode`, and that marking a page adds to its content
+rather than replacing it.
+
+## Marking a page
+
+`mark_pages` draws each expected field on the original, with its bleed around
+it — a way to see whether the positions a validation will use are where the
+fields actually are, before anything is measured with them.
+
+```python
+from scanmate_merge import PageMark, mark_pages
+
+result = mark_pages(pdf, [PageMark(page=1, x=72, y=520, width=180, height=36, id="signature")])
+result.warnings   # a mark on a page that does not exist, or one past the edge
+```
+
+Drawn as vectors on the document itself, so it stays sharp at any zoom. The
+coordinates are measured from the **top-left of the page as displayed**, with
+`/Rotate` and the crop box applied — the same frame `scanmate-extract` reports
+text in, so a list measured there can be drawn here unchanged. Getting between
+that frame and the PDF's own is pdf.js's `PageViewport` transform, ported line
+for line and inverted; it is exact, and it is where a "close enough" port would
+give false confidence on exactly the rotated and cropped pages that most need
+checking.
+
+## Two departures from the TypeScript
+
+**Nothing is `async`.** `mergeDocuments`, `markPages` and `readSource` are, for
+file reads and libvips; this reads files synchronously, as the rest of the
+Python port does.
+
+**`MergeOptions` and `MarkOptions` are dataclasses**, not object literals, so
+`page_size`, `image_dpi` and `pass_through` are snake_case keyword arguments.
+
+## Requirements
+
+Python 3.11 or newer, and `scanmate-ink`. Fully typed (PEP 561), `mypy --strict`
+clean. PDF reading and writing is [`pypdf`][pypdf].
+
+[ts]: https://github.com/russoedu/scanmate/tree/main/packages/merge#readme
+[ink]: https://github.com/russoedu/scanmate/tree/main/python-packages/scanmate-ink#readme
+[pypdf]: https://pypdf.readthedocs.io/

scanmate_merge-0.0.1/README.md

@@ -0,0 +1,104 @@
+# scanmate-merge
+
+Many files in, one PDF out: PDFs, images and rasters, in the order given, mixed
+freely.
+
+A **parallel port** of [`@scanmate/merge`][ts], not a replacement for it. The
+TypeScript remains the reference — with one boundary, stated below, that this
+package cannot cross and does not pretend to.
+
+```sh
+pip install scanmate-merge
+```
+
+```python
+from scanmate_merge import merge_documents
+
+result = merge_documents(["scan1.jpg", "contract.pdf", "scan2.png"])
+result.page_count
+result.pages[0].embedding   # 'jpeg' - the source's own bytes, not re-compressed
+```
+
+## What it preserves
+
+- **A PDF's pages are copied, not re-rendered**, so their text layer, vectors
+  and any signatures stay as they were.
+- **A JPEG is embedded as its own bytes** — RGB or grey, no EXIF rotation
+  pending — so a scan is not compressed a second time on its way into evidence.
+- **A PNG's pixels are carried over losslessly.** Not the PNG *file*: a PDF
+  cannot hold one, so the pixels go in deflated, which is what the TypeScript
+  does too.
+- Anything else is decoded — EXIF rotation applied, transparency flattened onto
+  white, every page of a multi-page TIFF — and encoded **once**.
+
+**A single PDF on its own comes back byte for byte.** Re-saving a signed PDF
+breaks its signature, and a PDF "merged" alone has nothing to merge, so it is
+not touched at all. Asking for metadata turns that off, because writing metadata
+means writing a new file, and the result says which happened.
+
+## The parity boundary
+
+Every other package in this port is held to the TypeScript bit for bit. This one
+cannot be, and the reason is not a shortcut: **two PDF writers lay out objects,
+streams and the cross-reference table differently**, so two valid merges of the
+same sources are never the same file. pdf-lib and `pypdf` are different writers.
+
+So parity here is held at the level that actually means something:
+
+| Held exactly | Not held |
+| --- | --- |
+| page count, and which source each page came from | the produced PDF's bytes |
+| how each page was embedded (`jpeg`, `png`, `encoded-png`, …) | object numbering, stream order |
+| every page's size in points, and the dpi it was placed at | compression details |
+| whether a single PDF passed through untouched | |
+| page geometry: `place_image`, `resolve_dpi`, the viewport transforms | |
+| `mark_pages`' count and its warning sentences, verbatim | |
+
+That is the same boundary [`scanmate-ink`][ink] already draws around
+`resampleRaster` and `blurRaster`: where two engines cannot agree by
+construction, say so rather than write a golden nobody can meet.
+
+What the produced file *is* checked for: that it is a readable PDF, that its
+pages are the sizes the result reports, that a JPEG went in as `/DCTDecode` and
+a PNG's pixels as `/FlateDecode`, and that marking a page adds to its content
+rather than replacing it.
+
+## Marking a page
+
+`mark_pages` draws each expected field on the original, with its bleed around
+it — a way to see whether the positions a validation will use are where the
+fields actually are, before anything is measured with them.
+
+```python
+from scanmate_merge import PageMark, mark_pages
+
+result = mark_pages(pdf, [PageMark(page=1, x=72, y=520, width=180, height=36, id="signature")])
+result.warnings   # a mark on a page that does not exist, or one past the edge
+```
+
+Drawn as vectors on the document itself, so it stays sharp at any zoom. The
+coordinates are measured from the **top-left of the page as displayed**, with
+`/Rotate` and the crop box applied — the same frame `scanmate-extract` reports
+text in, so a list measured there can be drawn here unchanged. Getting between
+that frame and the PDF's own is pdf.js's `PageViewport` transform, ported line
+for line and inverted; it is exact, and it is where a "close enough" port would
+give false confidence on exactly the rotated and cropped pages that most need
+checking.
+
+## Two departures from the TypeScript
+
+**Nothing is `async`.** `mergeDocuments`, `markPages` and `readSource` are, for
+file reads and libvips; this reads files synchronously, as the rest of the
+Python port does.
+
+**`MergeOptions` and `MarkOptions` are dataclasses**, not object literals, so
+`page_size`, `image_dpi` and `pass_through` are snake_case keyword arguments.
+
+## Requirements
+
+Python 3.11 or newer, and `scanmate-ink`. Fully typed (PEP 561), `mypy --strict`
+clean. PDF reading and writing is [`pypdf`][pypdf].
+
+[ts]: https://github.com/russoedu/scanmate/tree/main/packages/merge#readme
+[ink]: https://github.com/russoedu/scanmate/tree/main/python-packages/scanmate-ink#readme
+[pypdf]: https://pypdf.readthedocs.io/

scanmate_merge-0.0.1/project.json

@@ -0,0 +1,39 @@
+{
+  "name": "scanmate-merge",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "python-packages/scanmate-merge",
+  "targets": {
+    "lint": {
+      "executor": "@mnci/nx-python-pip:lint",
+      "options": {}
+    },
+    "typecheck": {
+      "executor": "@mnci/nx-python-pip:typecheck",
+      "options": {}
+    },
+    "test": {
+      "executor": "@mnci/nx-python-pip:test",
+      "options": {}
+    },
+    "build": {
+      "executor": "@mnci/nx-python-pip:build",
+      "outputs": [
+        "{projectRoot}/dist"
+      ],
+      "options": {}
+    },
+    "nx-release-publish": {
+      "executor": "@mnci/nx-python-pip:publish",
+      "dependsOn": [
+        "build"
+      ],
+      "options": {}
+    }
+  },
+  "release": {
+    "version": {
+      "versionActions": "@mnci/nx-python-pip/release/version-actions"
+    }
+  }
+}

scanmate_merge-0.0.1/pyproject.toml

@@ -0,0 +1,73 @@
+[project]
+name = "scanmate-merge"
+version = "0.0.1"
+description = "Many files in, one PDF out: PDFs, images and rasters, in the order given, mixed freely."
+keywords = ["pdf", "merge", "scan", "document", "image", "evidence"]
+license = "MIT"
+# A COPY of the repository's LICENSE, not a path to it. A Python distribution
+# cannot reference a file outside its own root - `../../LICENSE` builds a sdist
+# whose member escapes the archive, and `python -m build` refuses it outright.
+license-files = ["LICENSE"]
+authors = [{ name = "Eduardo Russo" }]
+readme = "README.md"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Text Processing",
+  "Typing :: Typed",
+]
+requires-python = ">=3.11"
+dependencies = [
+  "numpy>=2.1",
+  "pypdf>=5.1",
+  # >=0.0.1, not the real floor, and deliberately: a release never commits its
+  # version bump, so every manifest on disk stays at the scaffold version
+  # forever, and a real floor here makes the workspace-wide editable install
+  # unresolvable. `nx release` rewrites this to the true version as it
+  # publishes - "scanmate-ink>=0.0.1" becomes "scanmate-ink>=0.24.1" in the
+  # wheel. The same declaration scanmate-align carries.
+  "scanmate-ink>=0.0.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/russoedu/scanmate/tree/main/python-packages/scanmate-merge#readme"
+Repository = "https://github.com/russoedu/scanmate"
+Issues = "https://github.com/russoedu/scanmate/issues"
+"Parallels (TypeScript)" = "https://github.com/russoedu/scanmate/tree/main/packages/merge#readme"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["scanmate_merge"]
+# Tests sit beside the code, so they must be kept OUT of the wheel.
+exclude = ["**/test_*.py", "**/conftest.py"]
+
+[tool.pytest.ini_options]
+testpaths = ["scanmate_merge"]
+
+[tool.mypy]
+strict = true
+# Stub-less third-party packages, and ONLY those. Measured on a generated
+# project: plain strict passes out of the box, and the one thing that breaks it
+# in practice is importing a library that ships no type stubs - "import yaml"
+# fails as import-untyped on code you wrote normally and cannot fix. Disabling
+# that one code keeps every other strict check on your own code, and a module
+# that genuinely cannot be found still fails, as import-not-found.
+disable_error_code = ["import-untyped"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+# Pyflakes, pycodestyle, isort, bugbear, comprehensions, pyupgrade, naming.
+select = ["F", "E", "W", "I", "B", "C4", "UP", "N"]

scanmate_merge-0.0.1/scanmate_merge/__init__.py

@@ -0,0 +1,80 @@
+"""``scanmate-merge`` - many files in, one PDF out.
+
+.. code-block:: python
+
+    from scanmate_merge import merge_documents
+
+    result = merge_documents(["scan1.jpg", "contract.pdf", "scan2.png"])
+    result.page_count
+    result.pages[0].embedding   # 'jpeg', embedded as its own bytes
+"""
+
+from .document_merge import (
+    Embedding,
+    MergedPage,
+    MergeMetadata,
+    MergeOptions,
+    MergeResult,
+    merge_documents,
+)
+from .page_marking import (
+    Affine,
+    MarkOptions,
+    MarkResult,
+    PageGeometry,
+    PageMark,
+    mark_pages,
+    to_user_space,
+    viewport_size,
+    viewport_transform,
+)
+from .page_placement import (
+    MIN_RECORDED_DPI,
+    PAPER,
+    PageDimensions,
+    PageSize,
+    Placement,
+    place_image,
+    resolve_dpi,
+)
+from .source_reading import (
+    MergeSourceError,
+    PdfPasswordError,
+    ResolvedSource,
+    SourceKind,
+    is_pdf,
+    open_pdf,
+    read_source,
+)
+
+__all__ = [
+    "MIN_RECORDED_DPI",
+    "PAPER",
+    "Affine",
+    "Embedding",
+    "MarkOptions",
+    "MarkResult",
+    "MergeMetadata",
+    "MergeOptions",
+    "MergeResult",
+    "MergeSourceError",
+    "MergedPage",
+    "PageDimensions",
+    "PageGeometry",
+    "PageMark",
+    "PageSize",
+    "PdfPasswordError",
+    "Placement",
+    "ResolvedSource",
+    "SourceKind",
+    "is_pdf",
+    "mark_pages",
+    "merge_documents",
+    "open_pdf",
+    "place_image",
+    "read_source",
+    "resolve_dpi",
+    "to_user_space",
+    "viewport_size",
+    "viewport_transform",
+]

scanmate_merge-0.0.1/scanmate_merge/document_merge/__init__.py

@@ -0,0 +1,19 @@
+"""Many files in, one PDF out."""
+
+from .merge_documents_use_case import merge_documents
+from .merge_result_contract import (
+    Embedding,
+    MergedPage,
+    MergeMetadata,
+    MergeOptions,
+    MergeResult,
+)
+
+__all__ = [
+    "Embedding",
+    "MergeMetadata",
+    "MergeOptions",
+    "MergeResult",
+    "MergedPage",
+    "merge_documents",
+]