feat(python): workflow context propagation quickstart

[nelson-parente]

Summary

Python sibling of @cicoyle's canonical Go quickstart for workflow history propagation (Dapr 1.18). Same patient intake / e-prescribing scenario, same 3-level hierarchy, same workflow/activity names — so the Python and Go examples can be compared 1:1.

• Ported from: dapr/quickstarts#1315 (tutorials/workflow/go/history-propagation)
• Runtime: Dapr 1.18+ (dapr/dapr#9810)
• SDK: dapr-ext-workflow==1.18.0rc0 (dapr/python-sdk#1025)
• Targets release-1.18 to land alongside the Go example.

Scenario

Patient intake / e-prescribing pipeline. A compliance audit and a pharmacy dispense step refuse to act unless the propagated history proves the required upstream checks (insurance, allergies, drug interactions) actually ran.

PatientIntake (root)
  └─ VerifyInsurance       (activity, no propagation)
  └─ PrescribeMedication   (child wf, PropagationScope.LINEAGE)
        └─ CheckAllergies         (activity, no propagation)
        └─ ScreenDrugInteractions (activity, no propagation)
        └─ ComplianceAudit        (grandchild wf, PropagationScope.LINEAGE)
        |      reads PatientIntake + PrescribeMedication events
        └─ DispenseMedication     (activity, PropagationScope.OWN_HISTORY)
               reads PrescribeMedication events only
               refuses to dispense if the screening lineage is missing

ComplianceAudit uses LINEAGE to verify the full ancestor chain. DispenseMedication uses OWN_HISTORY as a trust boundary — the pharmacy step doesn't get to see the upstream patient-intake chain.

Two scenarios (matches the Go demo)

The app schedules both back-to-back and exits on its own — no Ctrl+C needed:

1. Lineage forwarded → PrescribeMedication calls DispenseMedication with PropagationScope.OWN_HISTORY; pharmacy verifies and dispenses.
2. Lineage withheld → PrescribeMedication calls DispenseMedication without propagation; pharmacy receives no history and refuses with a refused DispenseResult.

Python API used (from dapr/python-sdk#1025)

• PropagationScope.LINEAGE / PropagationScope.OWN_HISTORY
• propagation= kwarg on ctx.call_child_workflow() and ctx.call_activity()
• ctx.get_propagated_history() → PropagatedHistory | None
• PropagatedHistory.get_last_workflow_by_name(name) → WorkflowResult
• WorkflowResult.get_last_activity_by_name(name) → ActivityResult (with .completed, .output)
• PropagationNotFoundError

Replay safety

All print() calls inside workflows are guarded by if not ctx.is_replaying: so they only fire on the live execution, not on each durable replay.

Files

tutorials/workflow/python/history-propagation/
├── README.md          # mirrors the Go README, adapted for Python
├── dapr.yaml          # dapr run -f . config (appID=patient-app)
├── makefile           # wires the example into `make validate`
├── app.py             # registry + worker setup, schedules both scenarios
├── models.py          # PatientRecord, ComplianceResult, DispenseResult
├── workflow.py        # workflow + activity definitions, history helpers
└── requirements.txt   # Python deps (dapr-ext-workflow==1.18.0rc0)

Test plan

• pip3 install -r requirements.txt against dapr-ext-workflow==1.18.0rc0
• dapr run -f . against a Dapr 1.18 RC sidecar
• Scenario 1: ComplianceAudit reads full ancestor history via LINEAGE (sees PatientIntake + PrescribeMedication); DispenseMedication sees only PrescribeMedication events via OWN_HISTORY and dispenses
• Scenario 2: DispenseMedication receives no propagated history and returns refused, PrescribeMedication reports pharmacy refused to dispense
• Older sidecar (pre-1.18) gracefully returns None from get_propagated_history() without crash

References

• Go sibling (merged): dapr/quickstarts#1315 — tutorials/workflow/go/history-propagation
• Proposal: dapr/proposals#102
• Runtime: dapr/dapr#9810
• Python SDK: dapr/python-sdk#1025
• Go SDK reference: dapr/go-sdk#823
• .NET sibling: dapr/quickstarts#1310
• 1.18 endgame: dapr/dapr#9856

[nelson-parente]

Updated to align with @cicoyle's now-merged Go quickstart at tutorials/workflow/go/history-propagation (#1315). Summary of what changed since the last revision:

Location & target branch

• Moved files from workflows/python/sdk-context-propagation/order-processor/ → tutorials/workflow/python/history-propagation/, matching the Go sibling.
• Retargeted PR base from master → release-1.18 (where Cassie's PR landed).

File layout

• Split the previous single app.py into three files mirroring main.go / workflow.go / models.go:
  • app.py — registry + worker setup, schedules both scenarios.
  • workflow.py — workflow and activity definitions, history helpers.
  • models.py — PatientRecord, ComplianceResult, DispenseResult dataclasses.

Behavioural alignment with the Go canonical version

• Added forward_lineage: bool field to PatientRecord to control whether PrescribeMedication propagates its history to DispenseMedication.
• The app now runs two scenarios back-to-back (was: a single happy path):
  1. forward_lineage=True → pharmacy verifies the propagated history and dispenses.
  2. forward_lineage=False → pharmacy receives no propagated history and refuses with a refused DispenseResult (added reason field).
• After each scenario, the workflow state is purged so the demo exits on its own.

dapr.yaml

• appID: order-processor → appID: patient-app (matches the Go example's patient-app).
• resourcesPath: ../../components → resourcesPath: ../../resources (matches the convention used by sibling Python tutorials under tutorials/workflow/python/).
• Added appLogDestination: console and daprdLogDestination: console.

Python SDK API

• Switched to the correct method names from dapr-ext-workflow 1.18: get_last_workflow_by_name / get_last_activity_by_name (the previous draft used get_workflow_by_name / get_activity_by_name, which were renamed in Add history propagation python-sdk#1025).

README

• Rewrote to mirror the Go README's structure: title, propagation-scope table, key-demonstration block, both scenarios documented, <!-- STEP --> markers for make validate, expected-output snippets for both scenarios, file map at the bottom.

No SDK changes were required — the dependency stays at dapr-ext-workflow==1.18.0rc0 from #1307.