Document published Python workflow and history iterators

docs/polyglot/cli-python-parity.md

@@ -21,7 +21,7 @@ This all-client guide remains at the original
 | Queries | **Supported:** execute a named read-only query with structured output. [Commands](./cli-reference.md#workflow-commands) | **Supported:** client and handle queries plus registered worker query handlers. [PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **Supported:** async client queries plus replayed worker query handlers. [Messages](./python.md#signals-queries-and-updates) | **Supported:** client queries and replayed worker query handlers when runtime discovery advertises query-task support. [Rust API](https://rust.durable-workflow.com/) |
 | Updates | **Supported:** submit and wait for accepted or completed outcomes. [Commands](./cli-reference.md#workflow-commands) | **Supported:** `updateWorkflow` and `registerUpdate`; the PHP SDK does not expose validator authoring and declares no validators. [PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **Supported:** clients, workflow handlers, and synchronous declared validators when discovery advertises the pre-accept contract. Validator-bearing workers refuse unsupported runtimes. [Messages](./python.md#signals-queries-and-updates) | **Supported:** client, handle, Avro payloads, and registered worker update surfaces; the Rust SDK does not expose validator authoring and declares no validators. [Updates](./rust.md#workflow-updates) |
 | Schedules | **Supported:** complete schedule lifecycle, backfill, and audit history. [Commands](./cli-reference.md#schedule-commands) | **Supported:** complete schedule lifecycle and listing through `Client`. [PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **Supported:** complete async schedule lifecycle and audit-history paging. [Schedules](./python.md#schedules) | **Not supported:** the current Rust SDK does not claim a schedule-management API. Use CLI, PHP, Python, or the server API. |
-| Visibility | **Supported:** workflow/run search, workers, task queues, history, and diagnostic JSON. [Commands](./cli-reference.md#workflow-commands) | **Supported:** workflow filtering/pagination, history, namespaces, workers, and task queues. [Visibility evidence](./php.md#lifecycle-updates-schedules-and-visibility) | **Supported:** workflow, schedule, namespace, worker, queue, history, and search-attribute client surfaces. [Client API](./python.md#client-api-reference) | **Different:** selected-run describe/result is supported; fleet-wide list/search and namespace administration are not claimed. [Rust client](./rust.md#package-and-source) |
+| Visibility | **Supported:** workflow/run search, workers, task queues, history, and diagnostic JSON. [Commands](./cli-reference.md#workflow-commands) | **Supported:** workflow filtering/pagination, history, namespaces, workers, and task queues. [Visibility evidence](./php.md#lifecycle-updates-schedules-and-visibility) | **Supported:** workflow, schedule, namespace, worker, queue, history, and search-attribute client surfaces, including lazy workflow-list and explicit-run history iterators. [Pagination](./python.md#workflow-list-and-history-pages) | **Different:** selected-run describe/result is supported; fleet-wide list/search and namespace administration are not claimed. [Rust client](./rust.md#package-and-source) |
 | Worker execution | **Intentionally different:** low-level worker-protocol commands support diagnostics and conformance; `dw` is not an application worker runtime. [Worker commands](./cli-reference.md#worker-protocol-commands) | **Supported:** remote workflow, activity, query, and update handlers through `durable-workflow/sdk`. [PHP worker](./php.md#run-a-remote-php-worker) | **Supported:** deterministic workflow and activity workers. [Python worker](./python.md#worker) | **Supported:** native workflow, activity, query, and update handlers. [Rust worker API](https://rust.durable-workflow.com/) |
 
 **Supported** means the named current release surface exposes the capability.

docs/polyglot/python.md

@@ -121,6 +121,8 @@ Python SDK 2.15 and 2.16 add:
   so in-flight histories replay unchanged.
 - **Lazy pages (2.15).** `Client.iter_workflows`, `Client.iter_history` and
   `WorkflowHandle.iter_history` follow page tokens while holding one page.
+  See [workflow list and history pages](#workflow-list-and-history-pages)
+  for traversal, resume and error handling.
 - **Run activities (2.15).** `Client.get_run_activities` and
   `WorkflowHandle.get_activities` return typed activity and attempt metadata,
   and `ActivityInfo.activity_execution_id` exposes the logical activity
@@ -456,10 +458,13 @@ end-to-end rollout walkthrough; the CLI mirrors of these methods are
 | --- | --- | --- |
 | `await client.start_workflow(...)` | `WorkflowHandle` | `WorkflowAlreadyStarted`, `InvalidArgument`, `Unauthorized`, `ServerError` |
 | `await client.describe_workflow(workflow_id)` | `WorkflowExecution` | `WorkflowNotFound`, auth/server errors |
-| `await client.list_workflows(...)` | `WorkflowList` | Auth/server errors |
+| `await client.list_workflows(...)` | `WorkflowList` (one page) | Auth/server errors |
+| `client.iter_workflows(...)` | `AsyncIterator[WorkflowExecution]` | Page errors and cancellation propagate during iteration. See [pagination](#workflow-list-and-history-pages). |
 | `await client.list_workflow_runs(workflow_id)` | `WorkflowRunList` | `WorkflowNotFound`, auth/server errors |
 | `await client.describe_workflow_run(workflow_id, run_id)` | `WorkflowRun` | `WorkflowNotFound`, auth/server errors |
-| `await client.get_history(workflow_id, run_id)` | decoded history payload | `WorkflowNotFound`, auth/server errors |
+| `await client.get_history(workflow_id, run_id, ...)` | one page of decoded history | `WorkflowNotFound`, auth/server errors |
+| `client.iter_history(workflow_id, run_id, ...)` | `AsyncIterator[dict[str, Any]]` | Page errors and cancellation propagate during iteration. |
+| `handle.iter_history(...)` | `AsyncIterator[dict[str, Any]]` | Same history traversal. Requires a handle with an explicit `run_id`. |
 | `await client.export_history(workflow_id, run_id)` | decoded archival history payload | `WorkflowNotFound`, auth/server errors |
 | `await client.signal_workflow(workflow_id, signal_name, args=None)` | admission receipt (`dict`) | `WorkflowNotFound`, `InvalidArgument`, auth/server errors |
 | `await client.query_workflow(workflow_id, query_name, args=None)` | query receipt (`dict`) | `QueryFailed`, `WorkflowNotFound`, auth/server errors |
@@ -2245,4 +2250,35 @@ Server address. See
 
 ## Workflow list and history pages {#workflow-list-and-history-pages}
 
-These published calls return **one page**, not an automatic complete read: `await client.list_workflows(...)` / `await client.get_history(workflow_id, run_id, ...)`. Continue with the returned opaque token while keeping namespace, filters and selected workflow/run fixed; stop at the final null/empty token and handle page errors explicitly. A partial page is not a replay bundle. Use the SDK history-export API for offline replay. The [published Python 2.9.0 client source](https://github.com/durable-workflow/sdk-python/blob/2.9.0/src/durable_workflow/client.py) defines the current parameters; no new iterator capability is implied.
+The selected stable Python SDK provides lazy `Client.iter_workflows`,
+`Client.iter_history` and `WorkflowHandle.iter_history`. Use `async for` to
+consume workflow executions or history event dictionaries in Server order.
+See the [SDK-owned examples and pagination reference](https://python.durable-workflow.com/sdk-reference/#whole-run-histories-and-workflow-lists)
+and [published client source](https://github.com/durable-workflow/sdk-python/blob/2.17.2/src/durable_workflow/client.py).
+
+Each iterator fetches one page at a time without retaining earlier result pages.
+It follows empty pages that have a continuation and stops when the continuation
+is missing, `None` or empty. Stopping iteration fetches no subsequent page.
+HTTP errors, cancellation, history pages whose `events` field is not a list of
+dictionaries, and malformed or cyclic continuations propagate. Earlier yielded items are not rolled back, so
+handle an interrupted traversal as incomplete.
+
+Keep namespace, filters and page size fixed throughout a traversal. History
+also requires the same explicit `workflow_id` and `run_id`; the handle helper
+refuses a handle without `run_id`. A namespace change is refused before the
+next request. Supply `next_page_token` to resume at an opaque continuation
+from the same selection. Do not parse, alter or reuse it for different filters,
+namespaces or runs. Traversing a changing workflow list does not create a
+snapshot.
+
+The existing `await client.list_workflows(...)` and
+`await client.get_history(workflow_id, run_id, ...)` still return **one page**.
+For manual paging, pass the returned `next_page_token` to the next call and
+stop at the final missing/null/empty token. A partial page or a sequence of
+event dictionaries is not a replay bundle. Use
+`await client.export_history(workflow_id, run_id)` or
+`await handle.export_history()` for offline replay.
+
+The [installed SDK 2.17.2 / native Server 3.9.2 pagination check](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877331165)
+covered filtered lists, selected-run history, opaque resume, early close and
+namespace refusal, with [independent acceptance](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877373099).

i18n/de/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md

@@ -21,7 +21,7 @@ Dieser Leitfaden für alle Clients bleibt unter der ursprünglichen Route
 | Abfragen | **Unterstützt:** Ausführen einer benannten schreibgeschützten Abfrage mit strukturierter Ausgabe. [Befehle](./cli-reference.md#workflow-commands) | **Unterstützt:** Abfragen über Client und Handle sowie registrierte Abfrage-Handler im Worker. [PHP-API](./php.md#lifecycle-updates-schedules-and-visibility) | **Unterstützt:** Asynchrone Client-Abfragen sowie Abfrage-Handler mit Replay im Worker. [Nachrichten](./python.md#signals-queries-and-updates) | **Unterstützt:** Client-Abfragen und Abfrage-Handler mit Replay im Worker, wenn die Runtime-Erkennung Unterstützung für Abfrage-Tasks meldet. [Rust-API](https://rust.durable-workflow.com/) |
 | Updates | **Unterstützt:** Übermitteln und Warten auf angenommene oder abgeschlossene Ergebnisse. [Befehle](./cli-reference.md#workflow-commands) | **Unterstützt:** `updateWorkflow` und `registerUpdate`; das PHP SDK bietet keine Implementierung von Validatoren und deklariert keine. [PHP-API](./php.md#lifecycle-updates-schedules-and-visibility) | **Unterstützt:** Clients, Workflow-Handler und synchrone deklarierte Validatoren, wenn die Erkennung den Vertrag vor der Annahme meldet. Worker mit Validatoren lehnen nicht unterstützte Runtimes ab. [Nachrichten](./python.md#signals-queries-and-updates) | **Unterstützt:** Client, Handle, Avro-Nutzlasten und registrierte Update-Oberflächen im Worker; das Rust SDK bietet keine Implementierung von Validatoren und deklariert keine. [Updates](./rust.md#workflow-updates) |
 | Zeitpläne | **Unterstützt:** Vollständiger Zeitplan-Lebenszyklus, Nachholen und Audit-Verlauf. [Befehle](./cli-reference.md#schedule-commands) | **Unterstützt:** Vollständiger Zeitplan-Lebenszyklus und Auflisten über `Client`. [PHP-API](./php.md#lifecycle-updates-schedules-and-visibility) | **Unterstützt:** Vollständiger asynchroner Zeitplan-Lebenszyklus und seitenweises Lesen des Audit-Verlaufs. [Zeitpläne](./python.md#schedules) | **Nicht unterstützt:** Das aktuelle Rust SDK beansprucht keine API zur Zeitplanverwaltung. Verwenden Sie CLI, PHP, Python oder die Server-API. |
-| Einblick | **Unterstützt:** Workflow-/Laufsuche, Worker, Task-Warteschlangen, Verlauf und Diagnose-JSON. [Befehle](./cli-reference.md#workflow-commands) | **Unterstützt:** Workflow-Filterung und -Seitennavigation, Verlauf, Namespaces, Worker und Task-Warteschlangen. [Nachweise zur Einsicht](./php.md#lifecycle-updates-schedules-and-visibility) | **Unterstützt:** Client-Oberflächen für Workflows, Zeitpläne, Namespaces, Worker, Warteschlangen, Verlauf und Suchattribute. [Client-API](./python.md#client-api-reference) | **Abweichend:** Beschreibung/Ergebnis eines ausgewählten Laufs wird unterstützt; flottenweites Auflisten/Suchen und Namespace-Verwaltung werden nicht beansprucht. [Rust-Client](./rust.md#package-and-source) |
+| Einblick | **Unterstützt:** Workflow-/Laufsuche, Worker, Task-Warteschlangen, Verlauf und Diagnose-JSON. [Befehle](./cli-reference.md#workflow-commands) | **Unterstützt:** Workflow-Filterung und -Seitennavigation, Verlauf, Namespaces, Worker und Task-Warteschlangen. [Nachweise zur Einsicht](./php.md#lifecycle-updates-schedules-and-visibility) | **Unterstützt:** Client-Oberflächen für Workflows, Zeitpläne, Namespaces, Worker, Warteschlangen, Verlauf und Suchattribute, einschließlich verzögerter Iteratoren für Workflow-Listen und die Historie eines expliziten Laufs. [Seitennavigation](./python.md#workflow-list-and-history-pages) | **Abweichend:** Beschreibung/Ergebnis eines ausgewählten Laufs wird unterstützt; flottenweites Auflisten/Suchen und Namespace-Verwaltung werden nicht beansprucht. [Rust-Client](./rust.md#package-and-source) |
 | Worker-Ausführung | **Bewusst abweichend:** Worker-Protokollbefehle auf niedriger Ebene dienen Diagnose und Konformität; `dw` ist keine Runtime für Anwendungs-Worker. [Worker-Befehle](./cli-reference.md#worker-protocol-commands) | **Unterstützt:** Entfernte Workflow-, Aktivitäts-, Abfrage- und Update-Handler über `durable-workflow/sdk`. [PHP-Worker](./php.md#run-a-remote-php-worker) | **Unterstützt:** Deterministische Workflow- und Aktivitäts-Worker. [Python-Worker](./python.md#worker) | **Unterstützt:** Native Workflow-, Aktivitäts-, Abfrage- und Update-Handler. [Rust-Worker-API](https://rust.durable-workflow.com/) |
 
 **Unterstützt** bedeutet, dass die benannte Oberfläche des aktuellen Releases die