pdfform 0.2.0__tar.gz

pdfform-0.2.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    # Actions are pinned to commit SHAs, so Dependabot is what keeps them
+    # current. The `ci` prefix makes its PR titles pass the Conventional
+    # Commits title lint, and keeps the bumps out of the changelog.
+    commit-message:
+      prefix: ci
+    groups:
+      github-actions:
+        patterns:
+          - "*"

pdfform-0.2.0/.github/workflows/check-pr.yml

@@ -0,0 +1,83 @@
+name: PR Title Lint
+
+# SECURITY NOTE: This workflow uses `pull_request_target` so that the
+# title-lint can write commit statuses on PRs from forks (the default
+# `pull_request` token is read-only for forks).
+#
+# `pull_request_target` runs with a privileged token in the context of
+# the BASE branch. That is only safe because this workflow:
+#   - never checks out or executes PR code (no actions/checkout),
+#   - never interpolates PR-controlled data (title, body, branch name)
+#     into `run:` scripts,
+#   - grants nothing by default (`permissions: {}` below), so only the job
+#     that reads the PR title opts in, to `pull-requests: read` plus
+#     `statuses: write` and nothing else.
+#
+# DO NOT add a checkout of PR code or run any PR-provided content here.
+# Doing so would let a fork execute arbitrary code with write access to
+# this repository ("pwn request"). If code from the PR ever needs to be
+# tested, use a separate workflow with the plain `pull_request` trigger.
+#
+# `merge_group` only runs the aggregator, so the required "PR Title Lint"
+# check reports on merge queue commits. The title was already linted before
+# the PR could enter the queue.
+on:
+  pull_request_target:
+    types: 
+      - opened
+      - edited
+      - synchronize
+      - reopened
+  merge_group:
+
+# Default-deny; each job opts in to what it needs. The aggregator needs nothing.
+permissions: {}
+
+jobs:
+  conventional-title:
+    name: Validate PR title (Conventional Commits)
+    if: github.event_name == 'pull_request_target'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read # read the PR title
+      statuses: write # post the lint result as a commit status
+    steps:
+      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            chore
+            docs
+            refactor
+            test
+            ci
+            build
+            perf
+            style
+            revert
+          requireScope: false
+          subjectPattern: ^[a-z].+[^.]$
+          subjectPatternError: |
+            Subject must start with lowercase letter and not end with a period.
+            Got: "{subject}"
+          wip: true
+
+  # Aggregator job: a single, stable check-run name to use as the required
+  # status check in branch protection, independent of the underlying job name.
+  pr-title-lint:
+    name: PR Title Lint
+    needs: [conventional-title]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Verify PR title lint did not fail
+        run: |
+          # Fail only on failure/cancelled; a skipped run is allowed.
+          result="${{ needs.conventional-title.result }}"
+          if [ "$result" = "failure" ] || [ "$result" = "cancelled" ]; then
+            echo "PR title lint did not pass: $result"
+            exit 1
+          fi

pdfform-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+  merge_group:
+  workflow_dispatch:
+
+env:
+  UV_VERSION: "0.11.6"
+  UV_PYTHON_PREFERENCE: "managed"
+
+jobs:
+  quality-checks:
+    name: Quality Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Ensure uv lockfile is up-to-date
+        run: uv lock --check
+
+      - name: Install project dependencies
+        run: uv sync --all-groups
+
+      - name: Check formatting
+        run: uv run tox -e format-check
+
+      - name: Linting
+        run: uv run tox -e lints
+
+      - name: Run type checking
+        run: uv run tox -e typecheck
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    needs: [quality-checks]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.14"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install project dependencies
+        run: uv sync --all-groups
+
+      - name: Run tests
+        run: uv run tox -e py${{ matrix.python-version }}
+
+  # Aggregator job: a single, stable check-run name to use as the required
+  # status check in branch protection. Stays valid even if the matrix or the
+  # individual job names change.
+  ci:
+    name: CI
+    needs: [quality-checks, test]
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Verify no upstream job failed
+        run: |
+          # Fail only on failure/cancelled. A skipped job is allowed
+          for result in "${{ needs.quality-checks.result }}" "${{ needs.test.result }}"; do
+            if [ "$result" = "failure" ] || [ "$result" = "cancelled" ]; then
+              echo "An upstream job did not pass: quality-checks=${{ needs.quality-checks.result }} test=${{ needs.test.result }}"
+              exit 1
+            fi
+          done

pdfform-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git ref to build and publish"
+        type: string
+        required: false
+  workflow_call:
+    inputs:
+      ref:
+        description: "Git ref to build and publish"
+        type: string
+        required: true
+
+env:
+  UV_VERSION: "0.11.6"
+
+jobs:
+  build-and-publish:
+    name: Build & Publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pdfform
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Build package
+        run: uv build --sdist --wheel --out-dir dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist

pdfform-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,79 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+env:
+  UV_VERSION: "0.11.6"
+  UV_PYTHON_PREFERENCE: "managed"
+
+jobs:
+  release-please:
+    name: Release Please
+    runs-on: ubuntu-latest
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+      prs: ${{ steps.release.outputs.prs }}
+    steps:
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        id: release
+        with:
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  refresh-lock:
+    name: Refresh uv.lock on release PR
+    needs: release-please
+    if: ${{ needs.release-please.outputs.prs != '' && needs.release-please.outputs.prs != '[]' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout release PR branch
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ fromJSON(needs.release-please.outputs.prs)[0].headBranchName }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Refresh uv.lock
+        run: |
+          uv lock
+          if git diff --quiet uv.lock; then
+            echo "uv.lock already in sync — nothing to commit."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add uv.lock
+          git commit -m "chore: refresh uv.lock for release"
+          git push
+
+  publish:
+    name: Publish to PyPI
+    needs: release-please
+    # Opt-in: set the repository variable PYPI_PUBLISH to "true" once trusted
+    # publishing is configured on PyPI. Without it a release just cuts a tag.
+    if: ${{ needs.release-please.outputs.release_created && vars.PYPI_PUBLISH == 'true' }}
+    permissions:
+      id-token: write
+      contents: read
+    uses: ./.github/workflows/publish.yml
+    with:
+      ref: ${{ needs.release-please.outputs.tag_name }}
+    secrets: inherit

pdfform-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+.devcontainer/
+.DS_Store
+*.egg-info/
+*.pyc
+*.log
+.vscode
+.venv
+.coverage
+coverage.xml
+.*.swp
+.tox/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+data/
+dist/
+
+# Sample forms used for manual testing are kept out of the repository.
+/*.pdf

pdfform-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

pdfform-0.2.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.2.0](https://github.com/hoeze-org/pdfform/compare/v0.1.0...v0.2.0) (2026-09-30)
+
+
+### Features
+
+* derive a JSON Schema from PDF forms and fill them ([4c8c660](https://github.com/hoeze-org/pdfform/commit/4c8c6602834902bb52472f776bf8c56a2c5c53f1))

pdfform-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to `pdfform`
+
+## Development environment
+
+The project uses [`uv`](https://docs.astral.sh/uv/) for dependency management.
+
+### Initial setup
+
+```bash
+# Create the conda env (provides Python + uv)
+micromamba env create -f environment-dev.yml
+micromamba activate pdfform
+
+# Install all dependency groups (runtime + dev + test + lint) into a uv-managed venv
+uv sync --all-groups
+```
+
+All subsequent commands assume the env is activated and `uv` is on `PATH`.
+
+## Running tasks
+
+The project standardises tasks through [`tox`](https://tox.wiki/) with the `tox-uv` runner. Run any environment with:
+
+```bash
+uv run tox -e <env>
+```
+
+Available environments (defined in `pyproject.toml`):
+
+| Env             | Purpose                                  |
+|-----------------|------------------------------------------|
+| `format-check`  | `ruff format --check .`                  |
+| `lints`         | `ruff check .`                           |
+| `typecheck`     | `mypy src/pdfform`                       |
+| `py3.12`        | Run pytest under Python 3.12             |
+| `py3.14`        | Run pytest under Python 3.14             |
+
+Run the full matrix CI runs with:
+
+```bash
+uv run tox
+```
+
+### Quick commands
+
+```bash
+# Format code
+uv run ruff format .
+
+# Lint with autofix
+uv run ruff check --fix .
+
+# Run tests directly (single Python)
+uv run pytest
+
+# Run a single test
+uv run pytest tests/test_fill.py::test_radio_can_be_cleared -x
+```
+
+## Test fixtures
+
+The test forms are built by hand in `tests/formbuilder.py` from `pypdf` primitives rather than with a form generator. That is deliberate: the cases worth testing are the ones a friendly generator smooths over, such as a check box whose on-state is `/Ja`, a radio group whose kids each carry a different on-state, a text field whose `/AP` `/N` is a stream and not a state dictionary, and hierarchical field names.
+
+`tests/formbuilder.py` is on the test `pythonpath`, so test modules import from it directly. Fixtures wrapping it live in `tests/conftest.py`.
+
+When adding support for a construct, add it to `build_form` rather than creating a one-off document, so the whole suite exercises it.
+
+## Releases
+
+Versioning and tagging are automated by [release-please](https://github.com/googleapis/release-please) (`.github/workflows/release-please.yml`). Publishing is handled by `.github/workflows/publish.yml`:
+
+- release-please watches commits on `main` and opens/maintains a release PR that bumps `pyproject.toml` and updates `CHANGELOG.md`.
+- Merging the release PR cuts a `vX.Y.Z` tag and a GitHub release.
+- Publishing to PyPI is opt-in: it only runs when the repository variable `PYPI_PUBLISH` is set to `true`, and it uses trusted publishing (OIDC). It can also be triggered by hand from the Actions tab.
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) on `main` so release-please can pick the next version (`fix:` → patch, `feat:` → minor, `feat!:` / `BREAKING CHANGE:` → major).

pdfform-0.2.0/LICENSE

@@ -0,0 +1,14 @@
+MIT License
+
+Copyright (c) 2026 Florian R. Hölzlwimmer
+
+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.

pdfform-0.2.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: pdfform
+Version: 0.2.0
+Summary: Derive a JSON Schema from a PDF form and fill it from the command line or as a library
+Author-email: "Florian R. Hölzlwimmer" <hoeze-minion@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acroform,forms,json-schema,pdf,xfa
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: pypdf>=5.1
+Description-Content-Type: text/markdown
+
+# pdfform
+
+Derive a JSON Schema from a PDF form, then fill the form from JSON. Usable as a command line tool or as a library.
+
+There is no single library that reads an AcroForm, describes it as a schema, and writes values back correctly. `pypdf` and `pikepdf` give you the raw dictionaries, `pdf-lib` gives you a typed field API in JavaScript, and the mapping to JSON Schema is left to you, along with the handful of details that decide whether a filled form actually shows anything in a viewer. `pdfform` is that missing layer.
+
+## Features
+
+- **Schema extraction.** One JSON Schema property per fillable field, with types, enums, `maxLength`, defaults and descriptions.
+- **Filling** from a JSON file, from `--set NAME=VALUE`, or from a Python dict.
+- **Correct button handling.** Check box on-states are read per widget, not assumed to be `Yes`, and both `/V` and `/AS` are written.
+- **Flattening** that bakes the appearance streams into the page content using the placement algorithm from the PDF spec, rather than only translating them.
+- **XFA awareness.** Static and dynamic XFA are told apart, static XFA layers can be dropped (the `pdftk drop_xfa` equivalent), and dynamic XFA fails loudly instead of producing an empty schema.
+- **Label inference.** Optional best-effort guessing of what a field called `Text12` actually means, from the text printed next to it.
+
+## Installation
+
+Requires Python >= 3.12.
+
+```bash
+pip install pdfform
+```
+
+From a checkout, `uv sync --all-groups` sets everything up; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Command line
+
+```bash
+# What is in this form?
+pdfform fields form.pdf
+
+# Derive a JSON Schema
+pdfform schema form.pdf -o schema.json
+
+# Dump the current values as a starting point, edit, then write them back
+pdfform values form.pdf --include-empty -o data.json
+pdfform fill form.pdf -d data.json -o filled.pdf
+
+# Or set a few fields directly
+pdfform fill form.pdf --set Name=Doe --set Agreed=true --set Colour=Blue -o filled.pdf
+
+# Produce a non-editable document
+pdfform fill form.pdf -d data.json -o filled.pdf --flatten
+```
+
+`pdfform fields` prints one line per field with its kind, page, options, current value and description:
+
+```
+FIELD                        KIND        PG  DETAIL
+Haushaltsjahr                text         1  max 4 “Haushaltsjahr”
+Grund_Probandenentgelt       checkbox     1  on=Ja [Ja] “Probandenentgelt”
+Mitarbeiter_des_Klinikums    radio        1  [Nein, Ja] “Ist der Zahlungsempfänger Mitarbeiter des Klinikums?”
+Antragsteller_Unterschrift   signature    2  “Unterschrift des Antragstellers”
+```
+
+Data can be checked against the derived schema before anything is written:
+
+```bash
+pdfform validate form.pdf -d data.json
+pdfform fill form.pdf -d data.json -o filled.pdf --validate   # refuses to write on a mismatch
+```
+
+Other commands: `pdfform strip-xfa` removes an XFA layer, `pdfform xfa` lists or dumps the XFA packets. `pdfform --help` covers the rest.
+
+## Library
+
+```python
+from pdfform import extract_form, build_schema, fill_form
+
+info = extract_form("form.pdf")
+schema = build_schema(info)  # a JSON Schema document
+
+fill_form("form.pdf", {"Name": "Doe", "Agreed": True}, "filled.pdf")
+```
+
+`fill_form` returns the resulting bytes, so the `output` argument is optional and fills can be chained. Values may be nested (`{"Address": {"Street": ...}}`) or flat with dot-separated keys (`{"Address.Street": ...}`).
+
+Working with the field inventory directly:
+
+```python
+for field in info.fillable:
+    print(field.name, field.kind, field.on_states, field.describe())
+```
+
+`extract_form` never raises on a document that simply has no form; it returns an empty `FormInfo`. Errors that do get raised (`DynamicXfaError`, `UnknownFieldError`, `FieldValueError`) all derive from `PdfFormError`.
+
+## How fields map to JSON Schema
+
+| Field kind  | JSON Schema |
+|-------------|-------------|
+| text        | `{"type": "string"}`, plus `maxLength` when `/MaxLen` is set |
+| check box   | `{"type": "boolean"}` |
+| radio group | `{"type": "string", "enum": [...on states...]}` |
+| dropdown    | `{"type": "string", "enum": [...]}`, or a free string for an editable combo box |
+| list box    | as dropdown, or an array of them when multi-select is set |
+| push button | omitted, it holds no value |
+| signature   | omitted by default, `pdfform` cannot sign |
+
+Read-only fields are omitted unless `--include-read-only` is given. Everything needed to write a value back is preserved under the `x-pdf` keyword, which validators ignore:
+
+```json
+"Grund_Probandenentgelt": {
+  "type": "boolean",
+  "description": "Probandenentgelt",
+  "x-pdf": {"field": "Grund_Probandenentgelt", "kind": "checkbox", "pages": [0], "onState": "Ja", "offState": "Off"}
+}
+```
+
+Filling accepts more than the schema strictly describes: a check box takes `true`/`false` as well as its on-state name, a radio group or dropdown takes an option's display label as well as its export value, and `null` clears a field. Unknown names and out-of-range values are errors by default and warnings under `--no-strict`. Use `validate` when the data is meant to be schema-clean, since it holds it to the stricter standard.
+
+### Compared to other tools
+
+`PyPDFForm` also emits a JSON Schema, but it is lossy where it matters: a radio group becomes `{"type": "integer"}` addressed by option index, so the actual export values are unrecoverable, and a check box becomes a bare boolean that discards the on-state. `pdfform` puts the real on-state names in the `enum` and keeps them in `x-pdf`, so a schema plus a filled JSON document is enough to reconstruct exactly what was written. `pdfcpu form export` produces the closest thing on the CLI side but is not JSON Schema, and its checkbox handling only recognises `/Yes` as checked.
+
+## Things that bite when filling PDF forms
+
+These are the reasons this tool exists rather than a forty-line script.
+
+**Check box on-states are not `/Yes`.** The checked value is whichever key appears in the widget's `/AP` `/N` dictionary, and it may be `/On`, `/1`, `/Ja`, `/x` or anything else. `pdfform` reads it per field.
+
+**`/V` alone is not enough.** `/V` is the logical value; `/AS` selects which appearance stream gets drawn. Set only `/V` and the file is correct while the box looks empty in every viewer. For a radio group the rule applies per widget: `/V` goes on the group, every kid gets `/AS`, and only the kid whose own on-state matches is switched on.
+
+**A button value is a name, not a string.** Written as a text string it is silently ignored.
+
+**Appearance streams.** Without regenerating appearances, Acrobat may show a value that Preview, Chrome's viewer or a printer does not. `pdfform` both generates appearance streams for text and choice fields and sets `/NeedAppearances`, since neither is reliable alone.
+
+**`/AP` `/N` is not always a state dictionary.** For text fields it is a single stream, whose dictionary keys are `/BBox`, `/Resources` and friends. Reading those as appearance states is the usual way to invent on-states that do not exist.
+
+**Field names are hierarchical.** The real name is the `/T` of every ancestor joined with `.`, and only the leaf is stored on the field itself. `--nested` splits them back into nested objects. A partial name may itself contain a literal dot, so the flat name stays available under `x-pdf.field`.
+
+**Widgets are usually not the field.** A field with one widget is normally merged into a single dictionary, but a field with several has them as `/Kids`, and the `/AP` sits on the kid. Looking only at the objects returned by a `get_fields()` style call finds no on-state for fields that visibly have check boxes.
+
+**XFA.** Many government and banking forms store the real definition in an XML `/XFA` packet. If AcroForm fields exist alongside it the form is *static* XFA: fillable, but Acrobat may re-read the XFA data on open and discard the values, so `pdfform fill` drops the XFA layer by default. If `/Fields` is empty the form is *dynamic* XFA: script-generated, with no fixed field list, and `pdfform` says so instead of emitting an empty schema. The `template` packet is a much richer schema source than the AcroForm; `pdfform xfa --packet template` dumps it.
+
+**Field names are often meaningless.** `Text12` and `Kontrollkästchen3` produce a schema that is structurally correct and semantically useless. The document's own `/TU` tooltip is used as the description when present. Failing that, `--infer-labels` guesses from the text printed next to each widget, including per-option labels for radio groups. It is a geometric heuristic, right most of the time and wrong some of the time, which is why it is opt-in.
+
+## Flattening
+
+`--flatten` draws each widget's current appearance into the page content stream and removes the form. The appearance is placed by transforming the `/BBox` by the form's `/Matrix`, taking the bounding box of the result, and mapping that onto the annotation `/Rect`, per PDF 32000-1 section 12.5.5. Translating to the rectangle corner instead, which is the common shortcut, misplaces any appearance whose `/BBox` is not at the origin.
+
+Widgets that are hidden, or that have no appearance stream at all, are removed without being painted. That matches what a viewer shows for them.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT