Skip to content

Commit 541caab

Browse files
adriangbclaude
andauthored
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

File tree

‎datafusion/physical-plan/src/proto.rs‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@
3333
//! * [`ExecutionPlanEncode`] / [`ExecutionPlanDecode`] — internal dispatch
3434
//! traits, *defined* here but *implemented* in `datafusion-proto`, that the
3535
//! context types delegate to. This is the dependency inversion that keeps the
36-
//! proto types flowing in one direction only.
36+
//! proto types flowing in one direction only. They are `#[doc(hidden)]`: not
37+
//! public API, `pub` only because their implementors live in another crate.
3738
//!
3839
//! `datafusion-physical-plan` depends on the pure prost types in
3940
//! `datafusion-proto-models` (feature `proto`), never on `datafusion-proto`.
@@ -73,6 +74,11 @@ use crate::ExecutionPlan;
7374
///
7475
/// Implemented by `datafusion-proto`. Plan authors never name this trait; they
7576
/// call methods on [`ExecutionPlanEncodeCtx`] instead.
77+
///
78+
/// **Not public API.** `pub` only because the implementors live in another
79+
/// crate; `#[doc(hidden)]` records that, so encoding primitives can be added
80+
/// here as the serialization hooks grow without breaking downstream code.
81+
#[doc(hidden)]
7682
pub trait ExecutionPlanEncode {
7783
/// Serialize a child execution plan (recursing through the central
7884
/// serializer, so the child's own `try_to_proto` hook is honored).
@@ -98,6 +104,11 @@ pub trait ExecutionPlanEncode {
98104
///
99105
/// Implemented by `datafusion-proto`. Plan authors never name this trait; they
100106
/// call methods on [`ExecutionPlanDecodeCtx`] instead.
107+
///
108+
/// **Not public API.** `pub` only because the implementors live in another
109+
/// crate; `#[doc(hidden)]` records that, so decoding primitives can be added
110+
/// here as the serialization hooks grow without breaking downstream code.
111+
#[doc(hidden)]
101112
pub trait ExecutionPlanDecode {
102113
/// Deserialize a child execution plan (recursing through the central
103114
/// deserializer, so the child's own `try_from_proto` is honored).

0 commit comments

Comments
 (0)