Repository navigation
Commit 541caab
refactor: mark the ExecutionPlan proto dispatch traits as non-public API (#24001)
## Which issue does this PR close?
- Part of #23494. Precursor to #23915 (and to the remaining `DataSource`
/ `DataSink` items, #23497 / #23498).
## Rationale for this change
`ExecutionPlanEncode` / `ExecutionPlanDecode` (added in #23495) are
dispatch details of the
`try_to_proto` / `try_from_proto` hooks, not extension points. They are
defined in
`datafusion-physical-plan`, implemented only by `ConverterPlanEncoder` /
`ConverterPlanDecoder`
in `datafusion-proto`, and plans reach them exclusively through
`ExecutionPlanEncodeCtx` /
`ExecutionPlanDecodeCtx` — their own docs already say so:
> Internal dispatch trait backing [`ExecutionPlanEncodeCtx`].
Implemented by `datafusion-proto`.
> Plan authors never name this trait.
They are `pub` only because those adapters live in another crate.
Nothing said that to the tooling,
so every capability the epic still has to add to the ctx reads as a
major breaking change. #23915
hits this first: it needs `decode_plan_with_scalar_subquery_results` so
`ScalarSubqueryExec` can
decode its input with the subquery-results container in scope, and
`cargo-semver-checks` flags the
required method as `trait_method_added`. The `DataSource` / `DataSink`
families will want their own
primitives next.
`#[doc(hidden)]` states what was already true, and makes those additions
changes to something that
was never public API — rather than asking each follow-up PR to explain
away a breakage report.
## What changes are included in this PR?
Mark `ExecutionPlanEncode` and `ExecutionPlanDecode` `#[doc(hidden)]`,
and say why in their docs
and in the module overview. One file, no behavior, wire-format, or
signature changes.
A sealed-trait supertrait was the first thing I tried. It is worse here:
sealing across a crate
boundary needs a `pub` marker anyway, so it does not actually prevent a
downstream impl — it just
adds a public item in order to say "this is not public API", plus an
`impl` line for every
implementor including test doubles. `#[doc(hidden)]` says the same thing
by removing API surface
instead of adding it, and `cargo-semver-checks` honors both identically
(measured below).
## Are these changes tested?
The property this PR buys is a `cargo-semver-checks` classification, so
it is verified with that
tool directly — v0.49.0, the version CI installs, invoked the way CI
invokes it:
| baseline | change under test | result |
|---|---|---|
| `main` | add a required method to `ExecutionPlanDecode` |
`trait_method_added` — **major** |
| this PR | the same required method | 223 checks pass, **no semver
update required** |
Worth recording, since it drove the shape of this PR: the lint reads
`public_api_sealed` from the
**baseline**, so this has to land before the PRs that add methods, not
alongside them. Also,
`cargo-semver-checks` does not re-qualify the traits as public API even
though
`ExecutionPlanEncodeCtx::new` still names them in a public signature.
Also ran, on the pinned 1.97.0 toolchain: `cargo fmt --all -- --check`,
`cargo clippy --all-targets
--all-features` for both crates, `cargo doc` with `-D warnings` (no
broken intra-doc links from the
module docs to the now-hidden traits), and the full `datafusion-proto`
integration suite
(211 passed).
## Are there any user-facing changes?
`cargo-semver-checks` will report `trait_now_doc_hidden` on this PR, and
that is the intended
content of the change.
Real-world impact is nil: both traits were introduced by #23495, which
merged after `54.1.0` was
tagged, so no released version of `datafusion-physical-plan` contains
them. The load-bearing public
API — `ExecutionPlan::try_to_proto`, the two ctx types,
`AsExecutionPlan`, `PhysicalExtensionCodec`,
`PhysicalProtoConverterExtension` — is untouched, and `datafusion-proto`
needs no change at all.
Note for contributors on #23494: the expression-side equivalents
(`PhysicalExprEncode` /
`PhysicalExprDecode` in `physical-expr-common`) have the same shape and
the same argument, but
several test doubles across crates implement them. Left for a follow-up.
Co-authored-by: Claude Opus 5 <[email protected]>1 parent 3aef16c commit 541caab
1 file changed
Lines changed: 12 additions & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
36 | | - | |
| 36 | + | |
| 37 | + | |
37 | 38 | | |
38 | 39 | | |
39 | 40 | | |
| |||
73 | 74 | | |
74 | 75 | | |
75 | 76 | | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
76 | 82 | | |
77 | 83 | | |
78 | 84 | | |
| |||
98 | 104 | | |
99 | 105 | | |
100 | 106 | | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
101 | 112 | | |
102 | 113 | | |
103 | 114 | | |
| |||
0 commit comments