paperless-export 0.0.2__tar.gz

paperless_export-0.0.2/.env.example

@@ -0,0 +1,9 @@
+# Copy to .env (never commit the real one) or export in your shell.
+# Both are optional: they enable the API preflight check (fail fast on a bad
+# token before running the exporter). Token: Paperless → Settings → API Tokens.
+PAPERLESS_URL=https://paperless.local:8000
+PAPERLESS_TOKEN=your-token-here
+
+# Override how document_exporter is invoked if Paperless doesn't run via
+# `docker compose exec -T webserver ...` (e.g. bare-metal or a named container).
+#PAPERLESS_EXPORTER_CMD=docker exec -i paperless-webserver document_exporter

paperless_export-0.0.2/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @gykonik

paperless_export-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: ci
+on: [push, pull_request, workflow_dispatch]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --all-extras --dev
+
+      - name: lint
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: typecheck
+        run: uv run mypy
+
+      - name: test
+        run: uv run pytest -q
+
+      - name: build
+        run: uv build

paperless_export-0.0.2/.github/workflows/release.yml

@@ -0,0 +1,48 @@
+name: release
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write # tag + GitHub Release
+  id-token: write # PyPI Trusted Publishing (OIDC, no token)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    concurrency: release
+    steps:
+      # `git push` authenticates with the credentials checkout persists into the
+      # remote's extraheader — NOT with the token handed to the semantic-release
+      # action below (that one only signs GitHub API calls). The version commit
+      # lands on protected `main`, so the pushing identity needs a ruleset bypass:
+      # SEMANTIC_RELEASE_TOKEN is a PAT acting as an org owner, who has one.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+          token: ${{ secrets.SEMANTIC_RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+
+      - name: Semantic release (version, tag, changelog, GitHub Release)
+        id: semrel
+        uses: python-semantic-release/python-semantic-release@v9
+        with:
+          github_token: ${{ secrets.SEMANTIC_RELEASE_TOKEN || secrets.GITHUB_TOKEN }}
+
+      # No build step here on purpose. python-semantic-release already builds the
+      # sdist + wheel into dist/ via its `build_command` in pyproject.toml. It is
+      # a Docker action running as root, so those files are root-owned; a second
+      # `uv build` as the unprivileged runner user cannot overwrite them and dies
+      # with PermissionError, taking publish and the brew bump down with it.
+      - name: Publish to PyPI (OIDC)
+        if: steps.semrel.outputs.released == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Bump Homebrew formula
+        if: steps.semrel.outputs.released == 'true'
+        run: |
+          gh workflow run bump.yml -R fileworks/homebrew-tap \
+            -f formula=paperless-export \
+            -f version=${{ steps.semrel.outputs.version }}
+        env:
+          GH_TOKEN: ${{ secrets.TAP_DISPATCH_TOKEN }}

paperless_export-0.0.2/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.env
+.DS_Store

paperless_export-0.0.2/CHANGELOG.md

@@ -0,0 +1,66 @@
+# CHANGELOG
+
+
+## v0.0.2 (2026-07-13)
+
+### Bug Fixes
+
+- **release**: Drop the duplicate build that broke publishing
+  ([#3](https://github.com/fileworks/paperless-export/pull/3),
+  [`a51f396`](https://github.com/fileworks/paperless-export/commit/a51f3963604e0777966a317f01d27cc9f1eec1bc))
+
+The release job died at 'Build sdist + wheel' with
+
+PermissionError: [Errno 13] Permission denied: dist/<pkg>-0.0.1.tar.gz
+
+python-semantic-release already builds the sdist and wheel into dist/ via the build_command in
+  pyproject.toml. It is a Docker action running as root, so those artefacts are root-owned. The
+  workflow then ran a second, redundant 'uv build' as the unprivileged runner user, which cannot
+  overwrite them.
+
+Publish to PyPI and the Homebrew bump are both gated on that step, so a permission error on a build
+  that never needed to happen silently took out the entire release.
+
+Remove the duplicate build and the setup-uv step that only served it, and let the publish action
+  consume the dist/ that semantic-release produced.
+
+
+## v0.0.1 (2026-07-12)
+
+### Bug Fixes
+
+- **release**: Give checkout the release token so the version push is allowed
+  ([#2](https://github.com/fileworks/paperless-export/pull/2),
+  [`e201478`](https://github.com/fileworks/paperless-export/commit/e201478af0f822dbe19163edcfb1431f4427926d))
+
+The release job fails with GH013 — the chore(release) version commit cannot be pushed to protected
+  main.
+
+Handing SEMANTIC_RELEASE_TOKEN to the python-semantic-release action is not enough: that input only
+  authenticates GitHub API calls. The actual git push uses the credentials actions/checkout persists
+  into the remote's extraheader, which were still the default GITHUB_TOKEN — an identity with no
+  ruleset bypass.
+
+Set the token on checkout as well, mirroring media-sorter's semantic-release workflow, so the push
+  authenticates as an org owner and the always-bypass applies.
+
+### Continuous Integration
+
+- Allow CI to be triggered manually ([#1](https://github.com/fileworks/paperless-export/pull/1),
+  [`ff5c192`](https://github.com/fileworks/paperless-export/commit/ff5c192cfcca77171f324f6f200c136a0a9f9879))
+
+* ci: allow CI to be triggered manually
+
+workflow_dispatch makes it possible to re-run checks without pushing a commit — needed while
+  verifying the org's Actions allow-list, and useful any time a run fails for reasons outside the
+  code.
+
+* fix(release): push the version commit with a token that can bypass the ruleset
+
+semantic-release commits the version bump to main. The branch ruleset requires a PR, and the default
+  GITHUB_TOKEN has no bypass — GitHub rejects the Actions app as a bypass actor ("must be part of
+  the ruleset source or owner organization"), so the release job could never land its commit.
+
+SEMANTIC_RELEASE_TOKEN is a fine-grained PAT that acts as an org owner, who already holds an
+  always-bypass on the ruleset. Falls back to GITHUB_TOKEN so nothing breaks where the secret is
+  absent.

paperless_export-0.0.2/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.

paperless_export-0.0.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,110 @@
+# 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/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "paperless-export"
+version = "0.0.2"
+description = "Scheduled wrapper around Paperless-ngx's document_exporter plus a _Steuer/YYYY tax-view post-processor."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "gykonik" }]
+requires-python = ">=3.12"
+keywords = ["paperless-ngx", "export", "backup", "documents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Archiving :: Backup",
+]
+dependencies = [
+  "httpx>=0.28",
+  "pydantic>=2.9",
+  "typer>=0.15",
+]
+
+[project.optional-dependencies]
+pdf = ["pikepdf>=9.0"]
+
+[project.urls]
+Repository = "https://github.com/fileworks/paperless-export"
+Issues = "https://github.com/fileworks/paperless-export/issues"
+
+[project.scripts]
+paperless-export = "paperless_export.cli:app"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.13",
+  "pikepdf>=9.0",
+  "pytest>=8.3",
+  "respx>=0.22",
+  "ruff>=0.8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/paperless_export"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "A", "C4", "SIM", "RUF", "PTH", "RET", "ARG"]
+
+[tool.ruff.lint.per-file-ignores]
+# pytest fixtures are frequently used only for their side effect
+"tests/**" = ["ARG001"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src", "tests"]
+
+[[tool.mypy.overrides]]
+module = "pikepdf.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/paperless_export/__init__.py:__version__"]
+commit_message = "chore(release): {version} [skip ci]"
+build_command = "python -m pip install uv && uv build"
+allow_zero_version = true
+
+[tool.semantic_release.branches.main]
+match = "main"
+
+[tool.semantic_release.changelog.default_templates]
+changelog_file = "CHANGELOG.md"

paperless_export-0.0.2/renovate.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended", ":semanticCommits", ":dependencyDashboard"],
+  "timezone": "Europe/Berlin",
+  "schedule": ["before 6am on monday"],
+  "prConcurrentLimit": 5,
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": ["before 6am on the first day of the month"]
+  },
+  "vulnerabilityAlerts": {
+    "labels": ["security"],
+    "schedule": ["at any time"],
+    "automerge": true
+  },
+  "packageRules": [
+    {
+      "description": "Auto-merge patch/minor once CI (lint/typecheck/test/build) is green — low risk, keeps the tree current without manual review.",
+      "matchUpdateTypes": ["patch", "minor", "digest"],
+      "automerge": true,
+      "automergeType": "pr",
+      "platformAutomerge": true
+    },
+    {
+      "description": "Major bumps always get a PR, never auto-merged — API/behaviour changes need a look.",
+      "matchUpdateTypes": ["major"],
+      "automerge": false,
+      "labels": ["major-update"]
+    },
+    {
+      "description": "Group all GitHub Actions bumps into one PR.",
+      "matchManagers": ["github-actions"],
+      "groupName": "GitHub Actions",
+      "automerge": true
+    }
+  ]
+}

paperless_export-0.0.2/src/paperless_export/__init__.py

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

paperless_export-0.0.2/src/paperless_export/__main__.py

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