paperless-export 0.0.2__py3-none-any.whl

paperless_export/__init__.py

@@ -0,0 +1,3 @@
+"""paperless-export — Paperless-ngx export wrapper + _Steuer/YYYY tax view."""
+
+__version__ = "0.0.2"

paperless_export/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m paperless_export`."""
+
+from .cli import app
+
+app()

paperless_export/cli.py

@@ -0,0 +1,219 @@
+"""Typer CLI: `run` (exporter + views, the nightly job) and `tax-view` (views only)."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+import sys
+import traceback
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from . import __version__
+from .errors import EXIT_UNEXPECTED, PaperlessExportError
+
+app = typer.Typer(add_completion=False, context_settings={"help_option_names": ["-h", "--help"]})
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        try:
+            version = importlib.metadata.version("paperless-export")
+        except importlib.metadata.PackageNotFoundError:
+            version = __version__
+        typer.echo(f"paperless-export {version}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version_flag: Annotated[
+        bool,
+        typer.Option("--version", callback=_version_callback, is_eager=True),
+    ] = False,
+) -> None:
+    """Paperless-ngx export wrapper + _Steuer/YYYY tax view."""
+
+
+def _guarded[T](verbose: bool, action: Callable[[], T]) -> T:
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.INFO,
+        format="%(levelname)s %(name)s: %(message)s" if verbose else "%(message)s",
+        stream=sys.stderr,
+    )
+    try:
+        return action()
+    except PaperlessExportError as exc:
+        if verbose:
+            traceback.print_exc()
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=exc.exit_code) from exc
+    except Exception as exc:
+        if verbose:
+            traceback.print_exc()
+        typer.secho(
+            f"Unexpected error: {exc} (re-run with --verbose for the full traceback)",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=EXIT_UNEXPECTED) from exc
+
+
+def _build_views(
+    export_dir: Path,
+    *,
+    copy: bool,
+    tax_tag_prefix: str,
+    embed_tags: bool,
+) -> None:
+    from .embed import embed_metadata
+    from .manifest import load_documents
+    from .taxview import build_tax_view
+
+    documents = load_documents(export_dir / "manifest.json")
+    result = build_tax_view(export_dir, documents, copy=copy, prefix=tax_tag_prefix)
+    typer.echo(
+        f"_Steuer view: {result.total} documents across years "
+        f"{', '.join(sorted(result.years)) or '—'} (see _Steuer/INDEX.csv)"
+    )
+    for missing in result.missing:
+        typer.secho(f"  missing on disk, not linked: {missing}", fg=typer.colors.YELLOW, err=True)
+    if embed_tags:
+        embedded = embed_metadata(export_dir, documents)
+        typer.echo(f"Embedded metadata into {embedded} PDFs.")
+
+
+@app.command()
+def run(
+    export_dir: Annotated[
+        Path,
+        typer.Option(
+            "--export-dir", help="Export directory on this host (where manifest.json lands)."
+        ),
+    ],
+    exporter_cmd: Annotated[
+        str,
+        typer.Option(
+            "--exporter-cmd",
+            envvar="PAPERLESS_EXPORTER_CMD",
+            help="How to invoke document_exporter.",
+        ),
+    ] = "docker compose exec -T webserver document_exporter",
+    exporter_target: Annotated[
+        str,
+        typer.Option(
+            "--exporter-target",
+            help="Export path as the exporter process sees it (inside the container).",
+        ),
+    ] = "../export",
+    filename_format: Annotated[
+        bool,
+        typer.Option(
+            "--filename-format/--no-filename-format",
+            help="Lay out the export by the storage-path template (--use-filename-format).",
+        ),
+    ] = True,
+    fallback: Annotated[
+        bool,
+        typer.Option(
+            "--fallback/--no-fallback",
+            help="On a path-too-long failure, retry as a flat export.",
+        ),
+    ] = True,
+    compare_checksums: Annotated[
+        bool,
+        typer.Option("--compare-checksums/--no-compare-checksums", help="Incremental re-export."),
+    ] = True,
+    delete: Annotated[
+        bool,
+        typer.Option(
+            "--delete/--no-delete",
+            help="Prune files for documents removed in Paperless (true mirror).",
+        ),
+    ] = True,
+    tax_view: Annotated[
+        bool, typer.Option("--tax-view/--no-tax-view", help="Build the _Steuer/YYYY view.")
+    ] = True,
+    copy: Annotated[
+        bool,
+        typer.Option("--copy", help="Copy into _Steuer instead of symlinking (FAT/exFAT targets)."),
+    ] = False,
+    tax_tag_prefix: Annotated[
+        str, typer.Option("--tax-tag-prefix", help="Tag prefix marking tax years.")
+    ] = "Steuer-",
+    embed_tags: Annotated[
+        bool,
+        typer.Option("--embed-tags", help="Embed tags into the exported PDFs' XMP (needs [pdf])."),
+    ] = False,
+    url: Annotated[
+        str, typer.Option("--url", envvar="PAPERLESS_URL", help="Paperless URL (preflight check).")
+    ] = "",
+    token: Annotated[
+        str, typer.Option("--token", envvar="PAPERLESS_TOKEN", help="Paperless API token.")
+    ] = "",
+    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
+) -> None:
+    """Run document_exporter, then build the _Steuer/YYYY tax view (the nightly job)."""
+
+    def action() -> None:
+        from .exporter import run_exporter
+        from .preflight import check_api
+
+        if url:
+            check_api(url, token)
+        result = run_exporter(
+            exporter_cmd,
+            exporter_target,
+            filename_format=filename_format,
+            compare_checksums=compare_checksums,
+            delete=delete,
+            fallback_on_long_paths=fallback,
+        )
+        if not result.used_filename_format and filename_format:
+            typer.secho(
+                "Note: fell back to a flat export (path too long) — see log above.",
+                fg=typer.colors.YELLOW,
+                err=True,
+            )
+        typer.echo("document_exporter finished.")
+        if tax_view:
+            _build_views(
+                export_dir, copy=copy, tax_tag_prefix=tax_tag_prefix, embed_tags=embed_tags
+            )
+
+    _guarded(verbose, action)
+
+
+@app.command(name="tax-view")
+def tax_view_cmd(
+    export_dir: Annotated[
+        Path,
+        typer.Option("--export-dir", help="Existing export directory containing manifest.json."),
+    ],
+    copy: Annotated[
+        bool,
+        typer.Option("--copy", help="Copy into _Steuer instead of symlinking (FAT/exFAT targets)."),
+    ] = False,
+    tax_tag_prefix: Annotated[
+        str, typer.Option("--tax-tag-prefix", help="Tag prefix marking tax years.")
+    ] = "Steuer-",
+    embed_tags: Annotated[
+        bool,
+        typer.Option("--embed-tags", help="Embed tags into the exported PDFs' XMP (needs [pdf])."),
+    ] = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
+) -> None:
+    """Rebuild only the _Steuer/YYYY view from an existing export (no exporter run)."""
+    _guarded(
+        verbose,
+        lambda: _build_views(
+            export_dir, copy=copy, tax_tag_prefix=tax_tag_prefix, embed_tags=embed_tags
+        ),
+    )
+
+
+if __name__ == "__main__":
+    app()

paperless_export/embed.py

@@ -0,0 +1,50 @@
+"""Optional: embed Paperless tags/correspondent/type into exported PDFs' XMP.
+
+Requires the `pdf` extra (`pipx install 'paperless-export[pdf]'`). Note that
+rewriting a PDF changes its checksum, so embedded files are re-exported (and
+re-embedded) on the next `--compare-checksums` run — manifest.json already
+preserves all metadata, so only enable this if you want tags *inside* the files.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from .errors import ConfigError
+from .manifest import ExportedDocument
+
+logger = logging.getLogger(__name__)
+
+
+def embed_metadata(export_dir: Path, documents: list[ExportedDocument]) -> int:
+    """Write tags/correspondent/type into each exported PDF; returns count embedded."""
+    try:
+        import pikepdf
+    except ImportError as exc:
+        raise ConfigError(
+            "--embed-tags needs pikepdf — install with: pipx install 'paperless-export[pdf]'"
+        ) from exc
+
+    embedded = 0
+    for doc in documents:
+        pdf_path = export_dir / doc.file_path
+        if pdf_path.suffix.lower() != ".pdf" or not pdf_path.is_file():
+            continue
+        try:
+            with pikepdf.open(pdf_path, allow_overwriting_input=True) as pdf:
+                with pdf.open_metadata() as meta:
+                    if doc.tags:
+                        meta["dc:subject"] = doc.tags
+                        meta["pdf:Keywords"] = ", ".join(doc.tags)
+                    if doc.title:
+                        meta["dc:title"] = doc.title
+                    if doc.correspondent:
+                        meta["dc:creator"] = [doc.correspondent]
+                    if doc.document_type:
+                        meta["dc:type"] = [doc.document_type]
+                pdf.save(pdf_path)
+            embedded += 1
+        except Exception as exc:  # one broken PDF must not kill the run
+            logger.warning("Could not embed metadata into %s: %s", doc.file_path, exc)
+    return embedded

paperless_export/errors.py

@@ -0,0 +1,46 @@
+"""User-facing errors with stable exit codes (never a raw traceback by default)."""
+
+from __future__ import annotations
+
+EXIT_UNEXPECTED = 1
+EXIT_CONFIG = 2
+EXIT_UNREACHABLE = 3
+EXIT_OUTPUT = 4
+
+
+class PaperlessExportError(Exception):
+    """Base for all errors that should surface as a one-line human message."""
+
+    exit_code: int = EXIT_UNEXPECTED
+
+
+class ConfigError(PaperlessExportError):
+    """Invalid flags, missing paths, malformed URL."""
+
+    exit_code = EXIT_CONFIG
+
+
+class AuthError(PaperlessExportError):
+    """Paperless token rejected (401/403)."""
+
+    exit_code = EXIT_CONFIG
+
+
+class ServerUnreachableError(PaperlessExportError):
+    """Paperless API or container not reachable."""
+
+    exit_code = EXIT_UNREACHABLE
+
+
+class OutputError(PaperlessExportError):
+    """Export directory unwritable or missing."""
+
+    exit_code = EXIT_OUTPUT
+
+
+class ExporterFailedError(PaperlessExportError):
+    """document_exporter exited non-zero; carries its exit code and stderr."""
+
+    def __init__(self, message: str, exit_code: int) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code if exit_code != 0 else EXIT_UNEXPECTED

paperless_export/exporter.py

@@ -0,0 +1,120 @@
+"""Thin wrapper around Paperless-ngx's built-in `document_exporter`.
+
+The exporter already does the heavy lifting (type-tree layout via
+`--use-filename-format`, incremental `--compare-checksums`, mirror `--delete`,
+full `manifest.json`). This module only builds the command, runs it, surfaces
+failures honestly, and falls back to a flat export when the filename-format
+layout exceeds OS path limits.
+"""
+
+from __future__ import annotations
+
+import logging
+import shlex
+import subprocess
+from dataclasses import dataclass
+
+from .errors import ExporterFailedError, ServerUnreachableError
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_EXPORTER_CMD = "docker compose exec -T webserver document_exporter"
+DEFAULT_TARGET = "../export"
+
+_PATH_TOO_LONG_MARKERS = (
+    "file name too long",
+    "name too long",
+    "enametoolong",
+    "path too long",
+)
+
+
+@dataclass(frozen=True)
+class ExporterRun:
+    command: list[str]
+    used_filename_format: bool
+    stdout: str
+
+
+def build_command(
+    exporter_cmd: str,
+    target: str,
+    *,
+    filename_format: bool,
+    compare_checksums: bool,
+    delete: bool,
+) -> list[str]:
+    command = [*shlex.split(exporter_cmd), target]
+    if filename_format:
+        command.append("--use-filename-format")
+    if compare_checksums:
+        command.append("--compare-checksums")
+    if delete:
+        command.append("--delete")
+    return command
+
+
+def _looks_like_path_too_long(stderr: str) -> bool:
+    lowered = stderr.lower()
+    return any(marker in lowered for marker in _PATH_TOO_LONG_MARKERS)
+
+
+def _run(command: list[str]) -> subprocess.CompletedProcess[str]:
+    logger.info("Running: %s", shlex.join(command))
+    try:
+        return subprocess.run(command, capture_output=True, text=True, check=False)
+    except FileNotFoundError as exc:
+        raise ServerUnreachableError(
+            f"Cannot run the exporter: {exc}. Is Docker (or the webserver container) available? "
+            "Override the command with --exporter-cmd if Paperless runs differently."
+        ) from exc
+
+
+def run_exporter(
+    exporter_cmd: str = DEFAULT_EXPORTER_CMD,
+    target: str = DEFAULT_TARGET,
+    *,
+    filename_format: bool = True,
+    compare_checksums: bool = True,
+    delete: bool = True,
+    fallback_on_long_paths: bool = True,
+) -> ExporterRun:
+    """Run `document_exporter`; on a path-length failure, retry flat once."""
+    command = build_command(
+        exporter_cmd,
+        target,
+        filename_format=filename_format,
+        compare_checksums=compare_checksums,
+        delete=delete,
+    )
+    proc = _run(command)
+    if proc.returncode == 0:
+        return ExporterRun(command, used_filename_format=filename_format, stdout=proc.stdout)
+
+    if filename_format and fallback_on_long_paths and _looks_like_path_too_long(proc.stderr):
+        logger.warning(
+            "Exporter failed because a path exceeded the OS limit. Falling back to a flat "
+            "export (no --use-filename-format) — the folder layout is lost for this run, but "
+            "manifest.json still preserves every tag/type/correspondent. Consider shortening "
+            "long document titles."
+        )
+        flat_command = build_command(
+            exporter_cmd,
+            target,
+            filename_format=False,
+            compare_checksums=compare_checksums,
+            delete=delete,
+        )
+        flat = _run(flat_command)
+        if flat.returncode == 0:
+            return ExporterRun(flat_command, used_filename_format=False, stdout=flat.stdout)
+        raise ExporterFailedError(
+            f"document_exporter failed even without --use-filename-format "
+            f"(exit {flat.returncode}):\n{flat.stderr.strip()}",
+            flat.returncode,
+        )
+
+    raise ExporterFailedError(
+        f"document_exporter failed (exit {proc.returncode}):\n{proc.stderr.strip()}",
+        proc.returncode,
+    )

paperless_export/manifest.py

@@ -0,0 +1,90 @@
+"""Parse the `manifest.json` written by Paperless-ngx's `document_exporter`.
+
+The manifest is Django dumpdata format: a JSON array of
+`{"model": ..., "pk": ..., "fields": {...}}` objects. The exporter annotates
+each `documents.document` entry with top-level `__exported_file_name__` /
+`__exported_archive_name__` keys pointing at the files it wrote.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+from .errors import OutputError
+
+EXPORTED_FILE_KEY = "__exported_file_name__"
+EXPORTED_ARCHIVE_KEY = "__exported_archive_name__"
+
+
+class ExportedDocument(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    pk: int
+    title: str
+    correspondent: str | None
+    document_type: str | None
+    tags: list[str]
+    created: str
+    """ISO date (YYYY-MM-DD) if present, else empty string."""
+    file_path: str
+    """Path of the exported original, relative to the export dir."""
+    archive_path: str | None
+    """Path of the exported PDF/A archive version, if one exists."""
+
+    def tax_years(self, tag_pattern: re.Pattern[str]) -> list[str]:
+        years = []
+        for tag in self.tags:
+            match = tag_pattern.fullmatch(tag)
+            if match:
+                years.append(match.group(1))
+        return sorted(years)
+
+
+def _names_by_pk(entries: list[dict[str, Any]], model: str) -> dict[int, str]:
+    return {
+        entry["pk"]: entry["fields"]["name"] for entry in entries if entry.get("model") == model
+    }
+
+
+def load_documents(manifest_path: Path) -> list[ExportedDocument]:
+    if not manifest_path.is_file():
+        raise OutputError(
+            f"No manifest at {manifest_path} — run the exporter first "
+            "(or point --export-dir at an existing export)."
+        )
+    try:
+        entries: list[dict[str, Any]] = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise OutputError(f"{manifest_path} is not valid JSON: {exc}") from exc
+
+    tags = _names_by_pk(entries, "documents.tag")
+    correspondents = _names_by_pk(entries, "documents.correspondent")
+    doc_types = _names_by_pk(entries, "documents.documenttype")
+
+    documents: list[ExportedDocument] = []
+    for entry in entries:
+        if entry.get("model") != "documents.document":
+            continue
+        fields = entry["fields"]
+        file_path = entry.get(EXPORTED_FILE_KEY)
+        if not file_path:
+            continue  # e.g. --data-only export: nothing on disk to link
+        created_raw = str(fields.get("created") or "")
+        documents.append(
+            ExportedDocument(
+                pk=entry["pk"],
+                title=fields.get("title", ""),
+                correspondent=correspondents.get(fields.get("correspondent")),
+                document_type=doc_types.get(fields.get("document_type")),
+                tags=[tags[pk] for pk in fields.get("tags", []) if pk in tags],
+                created=created_raw[:10],
+                file_path=file_path,
+                archive_path=entry.get(EXPORTED_ARCHIVE_KEY),
+            )
+        )
+    return documents

paperless_export/preflight.py

@@ -0,0 +1,39 @@
+"""Optional API preflight: fail fast on a bad token or unreachable Paperless.
+
+The exporter itself runs inside the Paperless container and needs no API
+access, so this check only runs when a URL is configured.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import httpx
+
+from .errors import AuthError, ConfigError, ServerUnreachableError
+
+
+def check_api(url: str, token: str, *, timeout: float = 15.0) -> None:
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https") or not parsed.netloc:
+        raise ConfigError(f"$PAPERLESS_URL must be an http(s) URL, got {url!r}.")
+    if not token:
+        raise AuthError("Authentication failed — check $PAPERLESS_TOKEN (it is empty).")
+    try:
+        response = httpx.get(
+            f"{url.rstrip('/')}/api/documents/",
+            params={"page_size": 1},
+            headers={"Authorization": f"Token {token}"},
+            timeout=timeout,
+            follow_redirects=True,
+        )
+    except httpx.TransportError as exc:
+        raise ServerUnreachableError(
+            f"Cannot reach Paperless at {url} ({exc}) — is the webserver container running?"
+        ) from exc
+    if response.status_code in (401, 403):
+        raise AuthError("Authentication failed — check $PAPERLESS_TOKEN.")
+    if response.status_code >= 400:
+        raise ServerUnreachableError(
+            f"Paperless at {url} answered {response.status_code} — is it healthy?"
+        )

paperless_export/taxview.py

@@ -0,0 +1,106 @@
+"""Materialize the `_Steuer/YYYY/` cross-cutting tax view from the manifest.
+
+The view is derived output, rebuilt from scratch on every run (idempotent).
+Cleanup only touches the `_Steuer/` directory itself — never the exported
+documents it points at.
+"""
+
+from __future__ import annotations
+
+import csv
+import logging
+import re
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .manifest import ExportedDocument
+
+logger = logging.getLogger(__name__)
+
+TAX_VIEW_DIR = "_Steuer"
+INDEX_FILE = "INDEX.csv"
+DEFAULT_TAG_PREFIX = "Steuer-"
+
+
+def tag_pattern(prefix: str = DEFAULT_TAG_PREFIX) -> re.Pattern[str]:
+    return re.compile(rf"{re.escape(prefix)}(\d{{4}})")
+
+
+@dataclass
+class TaxViewResult:
+    linked: int = 0
+    copied: int = 0
+    missing: list[str] = field(default_factory=list)
+    years: set[str] = field(default_factory=set)
+
+    @property
+    def total(self) -> int:
+        return self.linked + self.copied
+
+
+def _clear_view(view_root: Path) -> None:
+    if view_root.exists():
+        shutil.rmtree(view_root)
+    view_root.mkdir(parents=True)
+
+
+def _unique_name(directory: Path, name: str, pk: int) -> str:
+    if not (directory / name).exists() and not (directory / name).is_symlink():
+        return name
+    stem, dot, suffix = name.rpartition(".")
+    return f"{stem}-{pk}.{suffix}" if dot else f"{name}-{pk}"
+
+
+def build_tax_view(
+    export_dir: Path,
+    documents: list[ExportedDocument],
+    *,
+    copy: bool = False,
+    prefix: str = DEFAULT_TAG_PREFIX,
+) -> TaxViewResult:
+    """Create `_Steuer/<YYYY>/` links (or copies) + `_Steuer/INDEX.csv`."""
+    pattern = tag_pattern(prefix)
+    view_root = export_dir / TAX_VIEW_DIR
+    _clear_view(view_root)
+
+    result = TaxViewResult()
+    index_rows: list[tuple[str, str, str, str, str]] = []
+    use_copy = copy
+
+    for doc in sorted(documents, key=lambda d: (d.created, d.title)):
+        years = doc.tax_years(pattern)
+        if not years:
+            continue
+        source = export_dir / doc.file_path
+        if not source.is_file():
+            result.missing.append(doc.file_path)
+            continue
+        for year in years:
+            year_dir = view_root / year
+            year_dir.mkdir(parents=True, exist_ok=True)
+            link = year_dir / _unique_name(year_dir, source.name, doc.pk)
+            if use_copy:
+                shutil.copy2(source, link)
+                result.copied += 1
+            else:
+                try:
+                    link.symlink_to(Path("..") / ".." / doc.file_path)
+                    result.linked += 1
+                except OSError as exc:
+                    logger.warning(
+                        "Filesystem does not support symlinks (%s) — switching to copies.", exc
+                    )
+                    use_copy = True
+                    shutil.copy2(source, link)
+                    result.copied += 1
+            result.years.add(year)
+            index_rows.append(
+                (year, doc.title, doc.correspondent or "", doc.created, doc.file_path)
+            )
+
+    with (view_root / INDEX_FILE).open("w", newline="", encoding="utf-8") as fh:
+        writer = csv.writer(fh)
+        writer.writerow(["year", "title", "correspondent", "created", "original_path"])
+        writer.writerows(sorted(index_rows))
+    return result

paperless_export-0.0.2.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: paperless-export
+Version: 0.0.2
+Summary: Scheduled wrapper around Paperless-ngx's document_exporter plus a _Steuer/YYYY tax-view post-processor.
+Project-URL: Repository, https://github.com/fileworks/paperless-export
+Project-URL: Issues, https://github.com/fileworks/paperless-export/issues
+Author: gykonik
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backup,documents,export,paperless-ngx
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Archiving :: Backup
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.9
+Requires-Dist: typer>=0.15
+Provides-Extra: pdf
+Requires-Dist: pikepdf>=9.0; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# paperless-export
+
+A thin scheduled wrapper around [Paperless-ngx](https://docs.paperless-ngx.com)'s
+built-in `document_exporter`, plus the one thing it doesn't do: a materialized
+**`_Steuer/YYYY/` tax view** built from your `Steuer-YYYY` tags.
+
+Paperless's exporter already produces the full no-lock-in export — every
+document laid out by your storage-path template, originals *and* PDF/A archive
+versions, and a complete `manifest.json` (tags, correspondents, types, custom
+fields). This tool deliberately does **not** rebuild any of that. It:
+
+1. runs `document_exporter <target> --use-filename-format --compare-checksums --delete`
+   (each flag toggleable), surfacing failures honestly and **falling back to a
+   flat export with a clear warning when a path exceeds the OS limit**,
+2. reads `manifest.json` and builds `_Steuer/<YYYY>/` — one symlink (or copy)
+   per document tagged `Steuer-YYYY` — plus a greppable `_Steuer/INDEX.csv`,
+3. optionally embeds tags/correspondent/type into the exported PDFs' XMP
+   (`--embed-tags`, needs the `[pdf]` extra).
+
+```
+export/
+  Bescheid/Finanzamt/2024-05-01 Steuerbescheid.pdf   # ← document_exporter
+  manifest.json                                       # ← document_exporter
+  _Steuer/
+    2024/2024-05-01 Steuerbescheid.pdf → ../../Bescheid/Finanzamt/…
+    INDEX.csv                                         # year,title,correspondent,created,original_path
+```
+
+## Install
+
+```sh
+pipx install paperless-export          # + 'paperless-export[pdf]' for --embed-tags
+# or
+brew install fileworks/tap/paperless-export
+```
+
+*(Not yet published — first release pending; until then: `uv run paperless-export` from a checkout.)*
+
+## Usage
+
+```sh
+# the nightly job (run from the directory containing your compose file):
+paperless-export run --export-dir /volume1/paperless/export
+
+# rebuild only the tax view from an existing export:
+paperless-export tax-view --export-dir /volume1/paperless/export
+
+# FAT/exFAT or cloud targets that don't preserve symlinks:
+paperless-export run --export-dir ./export --copy
+```
+
+Notes:
+
+- `--exporter-target` (default `../export`) is the path **as the exporter
+  process sees it** inside the container; `--export-dir` is the same directory
+  **on this host**. With the standard compose setup they're the same bind mount.
+- `PAPERLESS_URL` + `PAPERLESS_TOKEN` (env or flags) enable a preflight check
+  so a bad token fails fast with a clear message — they're optional because the
+  exporter itself runs inside the container and needs no API access.
+- `--embed-tags` rewrites the exported PDFs, which changes their checksums, so
+  those files are re-exported on the next `--compare-checksums` run. The
+  manifest already preserves all metadata — only embed if you want tags
+  *inside* the files.
+
+## Behavior guarantees
+
+- **Read-only against Paperless** — writes only into the export directory.
+- **Idempotent** — the `_Steuer/` view is rebuilt from scratch each run; safe nightly.
+- **Verifiable** — after a run, `_Steuer/2025/` contains exactly the documents
+  tagged `Steuer-2025`; `INDEX.csv` matches a manifest query.
+- **Honest failures** — a non-zero `document_exporter` exit surfaces its stderr
+  and exit code; symlink-unsupported filesystems auto-switch to copies with a notice.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | success |
+| 2 | bad configuration / authentication failure |
+| 3 | Paperless (or Docker) not reachable |
+| 4 | export dir missing / manifest unreadable |
+| *n* | `document_exporter` failed with exit code *n* |
+
+## Scheduling on a Synology (DSM Task Scheduler)
+
+```sh
+cd /volume1/docker/paperless && \
+/usr/local/bin/paperless-export run --export-dir /volume1/paperless/export
+```
+
+Nightly, after the Paperless backup window; the export target should live on a
+share covered by your backup chain.
+
+## Development
+
+```sh
+uv sync --all-extras --dev
+uv run ruff check . && uv run ruff format --check .   # lint
+uv run mypy                                           # strict types
+uv run pytest                                         # tests
+uv build
+```
+
+Conventional Commits drive releases (`python-semantic-release`): merge to
+`main` → version bump + changelog + GitHub Release + PyPI publish (OIDC) +
+Homebrew formula bump.
+
+## License
+
+MIT

paperless_export-0.0.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+paperless_export/__init__.py,sha256=J0mUbS79dusyYi2d2DVNFvJDGPJPI2AEGu6ZrTlppXI,104
+paperless_export/__main__.py,sha256=dWWwwAlCqhis0PpSLsjqjosEBzPcO7KVpreNO7vU3FI,71
+paperless_export/cli.py,sha256=mICl0NwfM9UZ-ImcbCYCOcpzxeoIIf_esxd-TSsOYUM,7090
+paperless_export/embed.py,sha256=DrECC6hXurCF5_6Iv05sMrf84jaBkR53HQxYPJDaKB0,1974
+paperless_export/errors.py,sha256=GZgz7uwiNo92gvg48nkZF8_VreCMzbgsauX1SQ_LO2k,1158
+paperless_export/exporter.py,sha256=lQCCwtA0nvuH7yh7w_qchh1-AXNWC6auViVZ6HHKF9c,3877
+paperless_export/manifest.py,sha256=-gzleM3A0Jj326AYXxbY5d-dpr5PQUOMGCqT4g7xBQ8,3168
+paperless_export/preflight.py,sha256=1FgjDqVZBxZxL-3wLvG-CkN-uGi7sGZqIQ__IZGhO-8,1463
+paperless_export/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+paperless_export/taxview.py,sha256=-r4YJypoUImI5ZuQcZtnrV1w3rnPl5rBHVndMn__Gfw,3325
+paperless_export-0.0.2.dist-info/METADATA,sha256=gcxXIwA54pCnHg-QsYH1TAlgZoHcmLfNp1Q-I2iP4H8,5254
+paperless_export-0.0.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+paperless_export-0.0.2.dist-info/entry_points.txt,sha256=_60x-Q2l2iZfj7aJGE3V4baq-xXxuEPc3yjgwFuYJIk,62
+paperless_export-0.0.2.dist-info/licenses/LICENSE,sha256=oG7brPhLE_Yq3DGpgTEyiaP32j3EzC276DEgECB47eY,1071
+paperless_export-0.0.2.dist-info/RECORD,,

paperless_export-0.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

paperless_export-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+paperless-export = paperless_export.cli:app

paperless_export-0.0.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niklas Büchel
+
+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.