Add flat BaseChart transformation fields

[palewire]

Summary

• Adds top-level BaseChart transformation fields (transpose, column_order, column_format, changes, external-data settings, etc.) as a narrow ergonomic layer over the existing Transform model.
• Keeps the nested transformations= API intact and merges flat fields into the same metadata.data serialization shape Datawrapper expects.
• Raises a validation error when callers provide conflicting flat and nested values for the same transformation; matching duplicate values are accepted.
• Adds focused docs and examples showing when to use the flat shortcuts vs. dw.Transform(...).

Compatibility design

The nested transformations model remains the source of truth for API-shaped data and round trips. Flat fields are exclude=True Pydantic fields, so model_dump() does not introduce a second representation; construction and assignment merge them into chart.transformations, and serialize_model() writes the merged result under metadata.data.

Supported flat fields are intentionally limited to the current Transform model: transpose, vertical_header, horizontal_header, column_order, column_format, changes, external_data, use_datawrapper_cdn, and upload_method.

Closes #499.

Validation

• uv run pytest tests/unit/serializers/test_base_transformations.py -q
• uv run pytest tests/unit/serializers/test_base_transformations.py tests/unit/models/test_transform.py tests/unit/serializers/test_base_serializer.py tests/integration/test_base_metadata_structure.py -q
• uv run ruff check ./datawrapper ./tests
• uv run ruff format --check ./datawrapper ./tests
• uv run mypy ./datawrapper --ignore-missing-imports
• uv run pre-commit run --all-files
• uv run pytest — 1127 passed, 3 skipped
• uv build --sdist --wheel

[palewire]

This is too complicated. I don't want to do it.

[Copilot]

Pull request overview

Adds an ergonomic “flat” set of transformation fields on BaseChart (e.g., transpose, column_order, column_format, changes, external data settings) that transparently merge into the existing nested Transform model and serialize into the same metadata.data payload shape expected by the Datawrapper API.

Changes:

• Introduces top-level, exclude=True Pydantic fields on BaseChart for common transformation settings and merges them into transformations (with conflict detection).
• Updates serialization to always emit the merged transformation state under metadata.data.
• Adds documentation and unit tests demonstrating flat vs nested transformation usage and conflict behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
datawrapper/charts/base.py	Adds flat transformation fields and implements merge + conflict validation into the nested Transform before serialization.
tests/unit/serializers/test_base_transformations.py	Adds unit tests for flat field serialization, composition with nested Transform, assignment behavior, and conflict validation.
docs/user-guide/charts/line-charts.md	Updates examples to use the new high-level column_format shortcut; minor formatting cleanup.
docs/user-guide/charts/area-charts.md	Updates example to use transpose=True shortcut instead of nested transformations dict.
docs/user-guide/advanced/transformations.md	Adds a dedicated guide explaining flat transformation fields, Transform, and conflict behavior.
docs/index.md	Adds the new transformations guide to the documentation index.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.