Feature: add partial pattern matching (partial=True) for callbacks

[i-murray]

Feature: Partial Pattern Matching (partial=True) for Callbacks

Description

Dash's pattern-matching callbacks currently require the pattern and component IDs to have exactly the same set of keys. This means a pattern like {"type": "btn"} will not match a component with ID {"type": "btn", "index": 1} — even though the component clearly has the key and value the pattern cares about.

This PR adds an opt-in partial=True flag on Input, Output, and State that relaxes the key-matching constraint: a pattern's keys only need to be a subset of the component's keys. Extra keys on the component are ignored.

Closes #3764

Usage

@app.callback(
    Output("output", "children"),
    Input({"type": "btn"}, "n_clicks", partial=True),
    prevent_initial_call=True,
)
def on_btn_click(n_clicks):
    return f"clicked {n_clicks}"

This fires for any component whose ID contains "type": "btn", regardless of other keys:

• {"type": "btn", "index": 1}
• {"type": "btn", "page": "home", "section": "main"}
• {"type": "btn", "index": 2, "tab": "first"}

Works with wildcards:

Input({"type": ALL}, "n_clicks", partial=True)    # collects all components with a "type" key
Input({"type": MATCH}, "n_clicks", partial=True)   # matches one-at-a-time on "type"

Design choices

• Per-dependency opt-in — not a new wildcard type, not a per-callback flag. Each Input/Output/State independently opts in, so partial and non-partial deps can coexist in the same callback.
• Extra keys are ignored — component keys not present in the pattern are treated as if they matched. This is the most permissive and intuitive behavior.
• Literal-only partial patterns are implicitly multi-valued — a pattern like {"type": "btn"} with partial=True can match multiple components, so the callback receives a list (same as ALL). Patterns with MATCH still resolve one-at-a-time.
• Zero-cost when unused — a hasPartialPatterns boolean guard on the callback graph ensures apps without partial=True pay no additional overhead. All new loops are skipped entirely.

---

Contributor Checklist

• I have broken down my PR scope into the following TODO tasks
  • Add partial attribute to DashDependency, Input, Output, State (Python)
  • Update _id_matches() for subset key matching when partial=True
  • Serialize partial flag via to_dict() and propagate through insert_callback()
  • Add addPartialPattern() and partialIdMatch() to frontend (dependencies.js)
  • Update computeGraphs() to detect partial flags and set hasPartialPatterns
  • Update getWatchedKeys(), getCallbackByOutput(), getUnfilteredLayoutCallbacks() with partial pattern loops
  • Add resolvePartialDeps() and update getCallbacksByInput() in dependencies_ts.ts
  • Update isMultiValued() for implicit multi-valued partial patterns
  • Fix requestedCallbacks.ts type compatibility for updated isMultiValued signature
  • Add hasPartialPatterns guard to all new loops for zero-cost when unused
• I have run the tests locally and they passed. (refer to testing section in contributing)
• I have added tests, or extended existing tests, to cover any new features or bugs fixed in this PR
  • 16 unit tests in tests/unit/test_partial_matching.py — subset matching, wildcards, serialization, bidirectional checks, negative cases
  • 6 integration tests in tests/integration/callbacks/test_partial_wildcards.py — basic partial match, ALL collection, literal filtering, mixed key sets

Optionals

• I have added entry in the CHANGELOG.md
• If this PR needs a follow-up in dash docs, community thread, I have mentioned the relevant URLs as follows
  • this GitHub #PR number updates the dash docs
  • here is the show and tell thread in Plotly Dash community

---

Performance

Partial matching requires cross-keyStr searches in several hot-path functions that were previously $O(1)$ hash lookups:

Function	Original	With partial patterns
getWatchedKeys()	$O(1)$	$O(K \cdot p)$
getCallbacksByInput()	$O(1)$	$O(K \cdot p)$
getCallbackByOutput()	$O(1)$	$O(K \cdot p)$
getUnfilteredLayoutCallbacks()	$O(N)$	$O(N \cdot K \cdot p)$

Where $K$ = number of distinct keyStr entries in the pattern index, $p$ = number of keys in the pattern (typically 1–5), and $N$ = number of components in a layout chunk.

hasPartialPatterns guard

To ensure zero cost for apps that don't use partial=True, computeGraphs() sets a hasPartialPatterns boolean on the graph in $O(D)$ time (where $D$ = total dependencies). Every new loop is guarded:

if (graphs.hasPartialPatterns) {
    for (const patKeyStr in graphs.inputPatterns) { ... }
}

Scenario	Per-event cost
No partial patterns (common case)	$O(1)$ — single boolean check, same as before
With partial patterns	$O(K \cdot p)$ — unavoidable cross-keyStr search

[i-murray]

If, instead of partial, you prefer a more descriptive keyword argument for Input/State/Output, I would suggest alternatives such as partial_match, partial_pattern, allow_partial or exact (with inverse logic & defaulting to True).

Additionally, if this feature is integrated, the relevant Dash documentation Pattern-Matching Callbacks would need to be updated.

[sonarqubecloud]

Quality Gate passed

Issues
26 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
2.5% Duplication on New Code

See analysis details on SonarQube Cloud

[T4rk1n]

If, instead of partial, you prefer a more descriptive keyword argument for Input/State/Output, I would suggest alternatives such as partial_match, partial_pattern, allow_partial or exact (with inverse logic & defaulting to True).

Additionally, if this feature is integrated, the relevant Dash documentation Pattern-Matching Callbacks would need to be updated.

I like this feature, but yea partial is too broad in Input kwargs, it should be specific to the pattern matching. As such I think partial_pattern would be best.

[camdecoster]

@i-murray are you still interested in finishing this PR?

[i-murray]

@camdecoster this branch should be ready for a review. I've just renamed the keyword argument from partial to partial_pattern as suggested by @T4rk1n.

[sonarqubecloud]

Quality Gate passed

Issues
24 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
2.5% Duplication on New Code

See analysis details on SonarQube Cloud

[T4rk1n]

The perf section's "zero cost when unused" doesn't hold — some of the new work runs even when no callback sets partial_pattern, and a single partial callback flips the global flag so the extra loops then run for all wildcard callbacks. Three spots below to tighten before merge.

[T4rk1n]

Second sort of the same keys — keyStr above already did Object.keys(id).sort(). And _keys is only read inside the hasPartialPatterns blocks, but it runs for every component regardless. Compute the sorted array once and build keyStr from it.

[T4rk1n]

Lost the early return when there are no keyPatterns, so we now run the newProps.filter(...) even when there's nothing to match. Bail early when there are no keyPatterns and no partial patterns; only enter the per-prop loop when there's something to check.

[T4rk1n]

The loops in getWatchedKeys / getCallbacksByInput / getCallbackByOutput / getUnfilteredLayoutCallbacks walk every keyStr and only find out it's not partial after the split + subset check. Build partialInputPatterns / partialOutputPatterns here in the same O(D) pass so those loops scan only the partial keyStrs.