feat(workflow): align history propagation API with go-sdk by nelson-parente · Pull Request #1047 · dapr/python-sdk

nelson-parente · 2026-05-20T21:08:25Z

Summary

Aligns the workflow history propagation surface added in #1025 with the freshly-renamed go-sdk helpers (durabletask-go#105, merged 2026-05-19). That rename landed four days after #1025 merged, so this is drift, not a defect — Cassie flagged it post-merge while building the cross-SDK quickstarts.

This brings python-sdk back in line for cross-SDK parity before 1.18 ships.

Read API renames

Mirror durabletask-go's GetLast*ByName form to make it obvious these return the most-recent occurrence (with plural get_*s_by_name siblings for the full list):

Old	New
`PropagatedHistory.get_workflow_by_name`	`get_last_workflow_by_name`
`WorkflowResult.get_activity_by_name`	`get_last_activity_by_name`
`WorkflowResult.get_child_workflow_by_name`	`get_last_child_workflow_by_name`

Plural variants (get_workflows_by_name, get_activities_by_name, get_child_workflows_by_name) and chain-level helpers (get_app_ids, get_events_by_*) are unchanged.

Scheduling — use the enum directly

The propagation scope is passed via the existing propagation= kwarg, using PropagationScope members:

import dapr.ext.workflow as wf

yield ctx.call_child_workflow(
    process_payment,
    input=req,
    propagation=wf.PropagationScope.OWN_HISTORY,
)

yield ctx.call_activity(
    log_summary,
    input=None,
    propagation=wf.PropagationScope.LINEAGE,
)

An earlier revision of this PR shipped propagate_lineage() / propagate_own_history() factory functions mirroring the go-sdk shape. Per review feedback from @seherv these were dropped (commit 69a78d6) — Go uses factories to compensate for the lack of enums; Python has them, so the enum members are clearer and play better with type checkers.

Non-goals

Kwarg name unchanged (propagation=). Renaming to with_history_propagation= would mirror go-sdk's WithHistoryPropagation() more literally but isn't idiomatic Python.
No proto / runtime changes. This PR is purely surface-level: renamed query methods are direct renames.

Test plan

uv run ruff check --fix && uv run ruff format — clean
uv run pytest ext/dapr-ext-workflow/tests/durabletask/test_propagation.py ext/dapr-ext-workflow/tests/durabletask/test_propagation_wiring.py — 29 passed
uv run python -m unittest discover -v ./ext/dapr-ext-workflow/tests — 133 passed
uv run pytest tests/examples/test_workflow.py::test_history_propagation against a 1.18-RC sidecar (output-based test; print statements unchanged, should still pass)
CI green

References

Closes (partially) Add support for workflow history propagation #1001
go-sdk reference rename: Add Last to the func name GetActivityByName and GetWorkflowByName & GetLastChildWorkflowByName durabletask-go#105
go-sdk reference impl + example: Feature workflow history propagation go-sdk#823
java-sdk parallel: Add support for workflow history propagation java-sdk#1739

cc @cicoyle @acroca

Cassie (durabletask-go author) flagged divergence between python-sdk dapr#1025 and the freshly-renamed go-sdk helpers in durabletask-go dapr#105 (merged 2026-05-19, after dapr#1025 landed). This brings python-sdk's surface back in line for cross-SDK parity before 1.18 ships. Read API renames (mirror durabletask-go GetLast*ByName): - PropagatedHistory.get_workflow_by_name -> get_last_workflow_by_name - WorkflowResult.get_activity_by_name -> get_last_activity_by_name - WorkflowResult.get_child_workflow_by_name -> get_last_child_workflow_by_name Plural variants (get_workflows_by_name, get_activities_by_name, get_child_workflows_by_name) and the chain-level helpers are unchanged. Scheduling helpers (mirror go-sdk workflow.PropagateLineage / workflow.PropagateOwnHistory): - propagate_lineage() -> PropagationScope.LINEAGE - propagate_own_history() -> PropagationScope.OWN_HISTORY PropagationScope enum is kept as the underlying value, so both `propagation=propagate_lineage()` and `propagation=PropagationScope.LINEAGE` work. Example, README snippet, and tests updated to use the renamed/new surface. No runtime/proto changes. Refs: dapr#1001, dapr/durabletask-go#105, dapr/go-sdk#823 Signed-off-by: Nelson Parente <nelson_parente@live.com.pt>

codecov · 2026-05-20T21:11:28Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.46%. Comparing base (bffb749) to head (69a78d6).
⚠️ Report is 134 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1047      +/-   ##
==========================================
- Coverage   86.63%   82.46%   -4.17%     
==========================================
  Files          84      146      +62     
  Lines        4473    14501   +10028     
==========================================
+ Hits         3875    11958    +8083     
- Misses        598     2543    +1945

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

seherv

Thanks for opening the PR! Left you one comment

PD: I agree with keeping it as propagation=

seherv · 2026-05-21T10:26:50Z

+- `propagation=propagate_own_history()` on a child workflow call —
  forwards the caller's events only.
- `propagation=PropagationScope.LINEAGE` on an activity call — forwards the
+- `propagation=propagate_lineage()` on an activity call — forwards the
  caller's events *plus* anything the caller itself received from its parent.


The way this is implemented would work fine, but IMO this is not idiomatic Python.

It also obscures things a bit (and might even mess with type checkers) because the return type of these functions only tells us that propagation=OwnHistory|Lineage, while the plain enum value tells us exactly what the value is without a doubt.

If I understand correctly, this is the way Go makes up for a lack of enums and is not a pattern we should apply in Python.

ty! Let me work around this feedback!

…ories Per review feedback, Go-style factory helpers are not idiomatic Python: they obscure the actual enum value at the call site and confuse static type checkers (return annotation only shows PropagationScope, not the specific member). Use PropagationScope.LINEAGE / PropagationScope.OWN_HISTORY directly instead. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt>

Cassie (durabletask-go author) flagged the .NET surface for cross-SDK divergence post-merge of dotnet-sdk#1802 / #1818. This rewrites the public history-propagation API to match the go-sdk shape — same one the python-sdk just adopted (python-sdk#1047). Issue dotnet-sdk#1801 was closed before her review; this PR delivers what the issue originally described. Three concrete gaps closed: 1. Activity-level opt-in (was missing entirely) - PropagationScope moved from ChildWorkflowTaskOptions to base WorkflowTaskOptions; ChildWorkflowTaskOptions inherits it. - WithHistoryPropagation() extension method added on the base record. - scheduleTaskAction.HistoryPropagationScope is now wired in WorkflowOrchestrationContext.CallActivityInternalAsync so activities can opt into propagation, matching CallChildWorkflowInternalAsync. - Without this, the Go SDK's reference example (SettlePayment activity using PropagateOwnHistory) literally cannot be ported to .NET. 2. Read API rewritten as high-level resolvers (was lossy FilterBy* + a PropagatedHistoryEvent record that dropped input/output/failure payloads) - PropagatedHistory.FilterByAppId/InstanceId/WorkflowName removed. - PropagatedHistory now exposes GetWorkflows(), GetWorkflowsByName(), GetLastWorkflowByName(), GetAppIds(), GetWorkflowsByAppId(), GetWorkflowsByInstanceId(). - New WorkflowResult class with InstanceId/AppId/Name plus GetActivitiesByName(), GetLastActivityByName(), GetChildWorkflowsByName(), GetLastChildWorkflowByName() — mirrors durabletask-go's GetLastWorkflowByName / GetLastActivityByName / GetLastChildWorkflowByName renames from durabletask-go#105. - New ActivityResult record carries Name, Started, Completed, Failed, Input, Output, FailureDetails — matching the Go/Python equivalents so chain-of-custody patterns line up. - New ChildWorkflowResult record with the equivalent shape. 3. Event payload preserved internally (was discarded by ConvertChunk) - ConvertChunk in WorkflowOrchestrationContext now parses raw events, walks them to resolve TaskScheduled <-> TaskCompleted/Failed and ChildWorkflowInstanceCreated <-> ChildWorkflowInstanceCompleted/ Failed by scheduleId, and produces fully-populated ActivityResult / ChildWorkflowResult instances. SDK retries reuse TaskExecutionId so matching is on scheduleId (matching Go/Python semantics). - Public API does not leak the proto HistoryEvent type — resolution happens at construction time inside Dapr.Workflow. Additional surface additions: - PropagationNotFoundException for missing-name lookups (mirrors Python's PropagationNotFoundError / Go's error returns). - Static WorkflowHistory.PropagateLineage() / PropagateOwnHistory() factory helpers for go-sdk call-site parity. Removed (clean break — 1.18 unreleased): PropagatedHistoryEntry, PropagatedHistoryEvent, HistoryEventKind, FilterByAppId, FilterByInstanceId, FilterByWorkflowName. Tests: - WorkflowHistoryPropagationTests.cs rewritten end-to-end to cover the new resolvers, query helpers, factory helpers, activity-level scope wiring, and child-workflow-level scope wiring. - HistoryPropagationWorkflowTests.cs (integration) updated to use GetWorkflows().Count in place of Entries.Count. Refs: #1801, dapr/durabletask-go#105, dapr/go-sdk#823, dapr/python-sdk#1047 Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> Co-authored-by: nelson-parente <20144601+nelson-parente@users.noreply.github.com>

* feat(workflow): align history propagation API with go-sdk Cassie (durabletask-go author) flagged the .NET surface for cross-SDK divergence post-merge of dotnet-sdk#1802 / #1818. This rewrites the public history-propagation API to match the go-sdk shape — same one the python-sdk just adopted (python-sdk#1047). Issue dotnet-sdk#1801 was closed before her review; this PR delivers what the issue originally described. Three concrete gaps closed: 1. Activity-level opt-in (was missing entirely) - PropagationScope moved from ChildWorkflowTaskOptions to base WorkflowTaskOptions; ChildWorkflowTaskOptions inherits it. - WithHistoryPropagation() extension method added on the base record. - scheduleTaskAction.HistoryPropagationScope is now wired in WorkflowOrchestrationContext.CallActivityInternalAsync so activities can opt into propagation, matching CallChildWorkflowInternalAsync. - Without this, the Go SDK's reference example (SettlePayment activity using PropagateOwnHistory) literally cannot be ported to .NET. 2. Read API rewritten as high-level resolvers (was lossy FilterBy* + a PropagatedHistoryEvent record that dropped input/output/failure payloads) - PropagatedHistory.FilterByAppId/InstanceId/WorkflowName removed. - PropagatedHistory now exposes GetWorkflows(), GetWorkflowsByName(), GetLastWorkflowByName(), GetAppIds(), GetWorkflowsByAppId(), GetWorkflowsByInstanceId(). - New WorkflowResult class with InstanceId/AppId/Name plus GetActivitiesByName(), GetLastActivityByName(), GetChildWorkflowsByName(), GetLastChildWorkflowByName() — mirrors durabletask-go's GetLastWorkflowByName / GetLastActivityByName / GetLastChildWorkflowByName renames from durabletask-go#105. - New ActivityResult record carries Name, Started, Completed, Failed, Input, Output, FailureDetails — matching the Go/Python equivalents so chain-of-custody patterns line up. - New ChildWorkflowResult record with the equivalent shape. 3. Event payload preserved internally (was discarded by ConvertChunk) - ConvertChunk in WorkflowOrchestrationContext now parses raw events, walks them to resolve TaskScheduled <-> TaskCompleted/Failed and ChildWorkflowInstanceCreated <-> ChildWorkflowInstanceCompleted/ Failed by scheduleId, and produces fully-populated ActivityResult / ChildWorkflowResult instances. SDK retries reuse TaskExecutionId so matching is on scheduleId (matching Go/Python semantics). - Public API does not leak the proto HistoryEvent type — resolution happens at construction time inside Dapr.Workflow. Additional surface additions: - PropagationNotFoundException for missing-name lookups (mirrors Python's PropagationNotFoundError / Go's error returns). - Static WorkflowHistory.PropagateLineage() / PropagateOwnHistory() factory helpers for go-sdk call-site parity. Removed (clean break — 1.18 unreleased): PropagatedHistoryEntry, PropagatedHistoryEvent, HistoryEventKind, FilterByAppId, FilterByInstanceId, FilterByWorkflowName. Tests: - WorkflowHistoryPropagationTests.cs rewritten end-to-end to cover the new resolvers, query helpers, factory helpers, activity-level scope wiring, and child-workflow-level scope wiring. - HistoryPropagationWorkflowTests.cs (integration) updated to use GetWorkflows().Count in place of Entries.Count. Refs: #1801, dapr/durabletask-go#105, dapr/go-sdk#823, dapr/python-sdk#1047 Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * fix(workflow): address code-review feedback on history-propagation alignment - Document the `new`-hiding contract on ChildWorkflowTaskOptions .WithHistoryPropagation and add a regression test that asserts the returned type is ChildWorkflowTaskOptions (not the base record), so InstanceId survives the with-expression. - Add the standard `()`, `(string)`, and `(string, Exception)` constructors on PropagationNotFoundException so callers can wrap inner exceptions. - Alias StringValue alongside the existing Timestamp alias in WorkflowOrchestrationContext so the propagation helper signature stays consistent with the rest of the file. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * test(workflow): clarify chunk-order test variable names Renames the test fixtures in GetPropagatedHistory_PreservesChunkOrder so the variable order matches the documented oldest-first chunk ordering (index 0 is the oldest ancestor, the last chunk is the immediate parent). No behavior change. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * fix(workflow): pass StringValue-wrapped fields directly as strings protoc unwraps google.protobuf.StringValue to a plain string in the generated C# (only the wire codec uses the wrapper). The StringValueOrNull(StringValue?) helper added in this branch expected the wrapper type, breaking the build with CS1503 at the three call sites in ResolveActivity / ResolveChildWorkflow. Drop the helper and pass the generated string fields straight through — they are already nullable at runtime and ActivityResult/ChildWorkflowResult accept string? for Input/Output. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * test(workflow): assign string directly to wrapper-typed fields Same StringValue mismatch as the production fix — protoc-generated properties for google.protobuf.StringValue fields are plain string, not the wrapper. Drop the new StringValue { Value = ... } wrappers in the test helpers. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * refactor(workflow): rename propagation types and adopt TryGet pattern Addresses Whit's review on #1825: - Rename ActivityResult -> PropagatedHistoryActivityResult - Rename ChildWorkflowResult -> PropagatedHistoryChildWorkflowResult - Rename WorkflowResult -> PropagatedHistoryEntry (primary constructor) - Drop WorkflowHistory static class; callers pass HistoryPropagationScope directly - Switch GetLast*ByName to TryGet*ByName + drop PropagationNotFoundException - Drop chunk/chain terminology from public XML docs - Surface malformed propagated event bytes via InvalidProtocolBufferException instead of silently skipping - Update unit tests to new names and TryGet asserts Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * test(workflow): rename propagation test cases to match renamed types Test names previously embedded the old type names (ActivityResult, ChildWorkflowResult); rename to the more general Activity_/ChildWorkflow_ prefix to avoid confusion with the renamed public types. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * fix(workflow): match propagated-history names and app IDs case-insensitively Workflow / activity names register through WorkflowsFactory with StringComparer.OrdinalIgnoreCase, and app IDs are matched case-insensitively on the invocation path. Align the propagated history lookups (GetAppIds, GetWorkflowsByName, TryGetLastWorkflowByName, GetWorkflowsByAppId, GetActivitiesByName, TryGetLastActivityByName, GetChildWorkflowsByName, TryGetLastChildWorkflowByName) with that contract so callers don't get surprising misses or duplicate logical IDs that only differ by casing. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * perf(workflow): pre-index completion events in ConvertChunk ConvertChunk previously rescanned the full event list inside ResolveActivity and ResolveChildWorkflow, making conversion O(n²) in the number of history events. Pre-index TaskCompleted / TaskFailed by TaskScheduledId (and the ChildWorkflowInstance counterparts) up front so each scheduled item resolves in O(1). Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * refactor(workflow): rename PropagatedHistory backing field to _entries The private field and ctor parameter on PropagatedHistory are now named after the value type they hold (PropagatedHistoryEntry) rather than the 'workflows' role those entries play today. Public API surface is unchanged. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * refactor(workflow): use generic propagated-history method names; add Status enum Addresses Whit's 2026-05-24 review. Rename the PropagatedHistory query family to scope-neutral names so the public surface need not change if propagated history ever carries non-workflow entries: GetWorkflows() -> GetEntries() GetWorkflowsByName() -> FilterByWorkflowName() GetWorkflowsByAppId() -> FilterByAppId() GetWorkflowsByInstanceId() -> FilterByInstanceId() Add PropagatedHistoryTaskStatus (Pending/Completed/Failed) and a computed Status property on PropagatedHistoryActivityResult and PropagatedHistoryChildWorkflowResult so callers can switch on a single value. The Started/Completed/Failed flags are retained for go-sdk/python-sdk parity; Status is a projection of them, with Failed taking precedence over Completed. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> * test(workflow): fix case-insensitive AppId filter expectation FilterByAppId matches case-insensitively, so two entries whose app IDs differ only in casing ("AppA" / "appa") both match a query for "APPA". The de-duped GetAppIds list collapses to one, but the filter returns both; assert two matches instead of one. Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> --------- Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> Co-authored-by: Whit Waldo <whit.waldo@innovian.net>

) * feat(workflow): align history propagation API with go-sdk Cassie (durabletask-go author) flagged divergence between python-sdk #1025 and the freshly-renamed go-sdk helpers in durabletask-go #105 (merged 2026-05-19, after #1025 landed). This brings python-sdk's surface back in line for cross-SDK parity before 1.18 ships. Read API renames (mirror durabletask-go GetLast*ByName): - PropagatedHistory.get_workflow_by_name -> get_last_workflow_by_name - WorkflowResult.get_activity_by_name -> get_last_activity_by_name - WorkflowResult.get_child_workflow_by_name -> get_last_child_workflow_by_name Plural variants (get_workflows_by_name, get_activities_by_name, get_child_workflows_by_name) and the chain-level helpers are unchanged. Scheduling helpers (mirror go-sdk workflow.PropagateLineage / workflow.PropagateOwnHistory): - propagate_lineage() -> PropagationScope.LINEAGE - propagate_own_history() -> PropagationScope.OWN_HISTORY PropagationScope enum is kept as the underlying value, so both `propagation=propagate_lineage()` and `propagation=PropagationScope.LINEAGE` work. Example, README snippet, and tests updated to use the renamed/new surface. No runtime/proto changes. Refs: #1001, dapr/durabletask-go#105, dapr/go-sdk#823 * refactor(workflow): drop propagate_lineage/propagate_own_history factories Per review feedback, Go-style factory helpers are not idiomatic Python: they obscure the actual enum value at the call site and confuse static type checkers (return annotation only shows PropagationScope, not the specific member). Use PropagationScope.LINEAGE / PropagationScope.OWN_HISTORY directly instead. --------- (cherry picked from commit 2fd3237) Signed-off-by: Nelson Parente <nelson_parente@live.com.pt> Signed-off-by: dapr-bot <dapr-bot@users.noreply.github.com> Co-authored-by: Nelson Parente <nelson_parente@live.com.pt> Co-authored-by: Sam <sam@diagrid.io>

nelson-parente requested review from a team as code owners May 20, 2026 21:08

nelson-parente mentioned this pull request May 20, 2026

feat(workflow): align history propagation API with go-sdk dapr/dotnet-sdk#1825

Merged

3 tasks

seherv suggested changes May 21, 2026

View reviewed changes

cicoyle approved these changes May 21, 2026

View reviewed changes

sicoyle approved these changes May 26, 2026

View reviewed changes

sicoyle added the backport release-1.18 label May 26, 2026

sicoyle added this pull request to the merge queue May 26, 2026

Merged via the queue into dapr:main with commit 2fd3237 May 26, 2026
20 of 21 checks passed

dapr-bot mentioned this pull request May 26, 2026

[Backport release-1.18] feat(workflow): align history propagation API with go-sdk #1055

Merged

sicoyle added this to the v1.18 milestone May 27, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(workflow): align history propagation API with go-sdk#1047

feat(workflow): align history propagation API with go-sdk#1047
sicoyle merged 2 commits into
dapr:mainfrom
nelson-parente:align-history-propagation-go-sdk

nelson-parente commented May 20, 2026 •

edited

Loading

Uh oh!

codecov Bot commented May 20, 2026 •

edited

Loading

Uh oh!

seherv left a comment

Uh oh!

seherv May 21, 2026

Uh oh!

nelson-parente May 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

nelson-parente commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Read API renames

Scheduling — use the enum directly

Non-goals

Test plan

References

Uh oh!

codecov Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

seherv left a comment

Choose a reason for hiding this comment

Uh oh!

seherv May 21, 2026

Choose a reason for hiding this comment

Uh oh!

nelson-parente May 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nelson-parente commented May 20, 2026 •

edited

Loading

codecov Bot commented May 20, 2026 •

edited

Loading