diff --git a/docs/polyglot/cli-python-parity.md b/docs/polyglot/cli-python-parity.md index c713ff5eb6c..f2cd76f5546 100644 --- a/docs/polyglot/cli-python-parity.md +++ b/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. diff --git a/docs/polyglot/python.md b/docs/polyglot/python.md index 900cb4fb7ba..18f42806e1f 100644 --- a/docs/polyglot/python.md +++ b/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). diff --git a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md index 9ac4734ce88..c855bce5343 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md +++ b/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 diff --git a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/python.md index 0c2bc38cc1a..2b8d68ed8a6 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/de/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -115,6 +115,7 @@ Python-SDK 2.15 und 2.16 ergänzen: - **Sticky-History-Suffixe (2.16).** Worker mit Sticky-Cache (`sticky_cache_capacity > 0`) melden `sticky_history_suffix`. Auf Server 3.5.0 oder neuer erhält ein Sticky-Treffer nur die Historie nach der zwischengespeicherten Sequenz. Ein Suffix, das die zwischengespeicherte Historie nicht exakt fortsetzt, wird verworfen und die vollständige Historie abgerufen. - **Typisierte Workflow-Werte (2.15).** `@workflow.defn(..., typed=True)` dekodiert Argumente von `run` und Handlern gemäß ihren Annotationen, und `result_type=` dekodiert Ergebnisse von Kind-Workflows und Clients. Untypisierte Workflows erhalten wie bisher einfache Werte, laufende Historien werden also unverändert abgespielt. - **Lazy Seiten (2.15).** `Client.iter_workflows`, `Client.iter_history` und `WorkflowHandle.iter_history` folgen Seiten-Tokens und halten dabei nur eine Seite. + Siehe [Seiten für Workflow-Listen und Verlauf](#workflow-list-and-history-pages) für Traversierung, Fortsetzung und Fehlerbehandlung. - **Aktivitäten einer Ausführung (2.15).** `Client.get_run_activities` und `WorkflowHandle.get_activities` liefern typisierte Aktivitäts- und Versuchsmetadaten, und `ActivityInfo.activity_execution_id` stellt die logische Aktivitätsidentität bereit. - **Backoff lokaler Aktivitäten (2.15.1).** Wiederholungen nach dem Ende der Backoff-Liste verwenden erneut den letzten Eintrag, statt sofort erneut zu versuchen. @@ -407,10 +408,13 @@ Die entsprechenden CLI-Befehle sind `dw task-queue:build-ids`, | --- | --- | --- | | `await client.start_workflow(...)` | `WorkflowHandle` | `WorkflowAlreadyStarted`, `InvalidArgument`, `Unauthorized`, `ServerError` | | `await client.describe_workflow(workflow_id)` | `WorkflowExecution` | `WorkflowNotFound`, Authentifizierungs-/Serverfehler | -| `await client.list_workflows(...)` | `WorkflowList` | Authentifizierungs-/Serverfehler | +| `await client.list_workflows(...)` | `WorkflowList` (eine Seite) | Authentifizierungs-/Serverfehler | +| `client.iter_workflows(...)` | `AsyncIterator[WorkflowExecution]` | Seitenfehler und Abbruch werden während der Iteration weitergegeben. [Seitennavigation](#workflow-list-and-history-pages). | | `await client.list_workflow_runs(workflow_id)` | `WorkflowRunList` | `WorkflowNotFound`, Authentifizierungs-/Serverfehler | | `await client.describe_workflow_run(workflow_id, run_id)` | `WorkflowRun` | `WorkflowNotFound`, Authentifizierungs-/Serverfehler | -| `await client.get_history(workflow_id, run_id)` | decodierte Historiennutzlast | `WorkflowNotFound`, Authentifizierungs-/Serverfehler | +| `await client.get_history(workflow_id, run_id, ...)` | eine Seite dekodierter Historie | `WorkflowNotFound`, Authentifizierungs-/Serverfehler | +| `client.iter_history(workflow_id, run_id, ...)` | `AsyncIterator[dict[str, Any]]` | Seitenfehler und Abbruch werden während der Iteration weitergegeben. | +| `handle.iter_history(...)` | `AsyncIterator[dict[str, Any]]` | Dieselbe Historientraversierung. Erfordert ein Handle mit expliziter `run_id`. | | `await client.export_history(workflow_id, run_id)` | decodierte Archivhistoriennutzlast | `WorkflowNotFound`, Authentifizierungs-/Serverfehler | | `await client.signal_workflow(workflow_id, signal_name, args=None)` | Annahmequittung (`dict`) | `WorkflowNotFound`, `InvalidArgument`, Authentifizierungs-/Serverfehler | | `await client.query_workflow(workflow_id, query_name, args=None)` | Query-Quittung (`dict`) | `QueryFailed`, `WorkflowNotFound`, Authentifizierungs-/Serverfehler | @@ -2199,4 +2203,12 @@ bereit. Setzen Sie keine selbst gehostete Server-Adresse ein. Siehe ## Seiten für Workflow-Listen und Verlauf {#workflow-list-and-history-pages} -Diese veröffentlichten Aufrufe liefern **eine Seite**, keinen automatischen vollständigen Abruf: `await client.list_workflows(...)` / `await client.get_history(workflow_id, run_id, ...)`. Setzen Sie mit dem zurückgegebenen undurchsichtigen Token fort und behalten Sie Namespace, Filter und Workflow/Lauf bei. Enden Sie beim letzten null/leeren Token und behandeln Sie Seitenfehler ausdrücklich. Eine Teilseite ist kein Replay-Bundle. Nutzen Sie für Offline-Replay die Verlaufsexport-API des SDK. Der [veröffentlichte Client Python 2.9.0](https://github.com/durable-workflow/sdk-python/blob/2.9.0/src/durable_workflow/client.py) definiert aktuelle Parameter; neue automatische Iteratoren werden damit nicht zugesagt. +Das ausgewählte stabile Python SDK bietet die verzögerten Iteratoren `Client.iter_workflows`, `Client.iter_history` und `WorkflowHandle.iter_history`. Verwenden Sie `async for`, um Workflow-Ausführungen oder Dictionaries mit Historienereignissen in der Reihenfolge des Servers zu lesen. Siehe die [SDK-eigenen Beispiele und die Referenz zur Seitennavigation](https://python.durable-workflow.com/sdk-reference/#whole-run-histories-and-workflow-lists) und den [veröffentlichten Client-Quellcode](https://github.com/durable-workflow/sdk-python/blob/2.17.2/src/durable_workflow/client.py). + +Jeder Iterator lädt jeweils eine Seite und behält frühere Ergebnisseiten nicht im Speicher. Er folgt auch leeren Seiten mit Fortsetzung und endet, wenn die Fortsetzung fehlt, `None` oder leer ist. Nach dem Beenden der Iteration wird keine weitere Seite geladen. HTTP-Fehler, Abbruch, Historienseiten, deren `events`-Feld keine Liste von Dictionaries ist, sowie ungültige oder zyklische Fortsetzungen werden weitergegeben. Bereits gelieferte Elemente werden nicht zurückgenommen. Behandeln Sie daher eine unterbrochene Traversierung als unvollständig. + +Behalten Sie Namespace, Filter und Seitengröße während der Traversierung bei. Die Historie erfordert außerdem dieselben expliziten Werte für `workflow_id` und `run_id`. Der Handle-Helfer lehnt ein Handle ohne `run_id` ab. Eine Namespace-Änderung wird vor der nächsten Anfrage abgelehnt. Übergeben Sie `next_page_token`, um dieselbe Auswahl an einer undurchsichtigen Fortsetzung fortzusetzen. Parsen oder verändern Sie das Token nicht und verwenden Sie es nicht für andere Filter, Namespaces oder Läufe. Die Traversierung einer sich ändernden Workflow-Liste erzeugt keinen Snapshot. + +Die bestehenden Aufrufe `await client.list_workflows(...)` und `await client.get_history(workflow_id, run_id, ...)` liefern weiterhin **eine Seite**. Übergeben Sie bei manueller Seitennavigation das zurückgegebene `next_page_token` an den nächsten Aufruf und enden Sie beim letzten fehlenden/null/leeren Token. Eine Teilseite oder eine Folge von Ereignis-Dictionaries ist kein Replay-Bundle. Verwenden Sie für Offline-Replay `await client.export_history(workflow_id, run_id)` oder `await handle.export_history()`. + +Die [Pagination-Prüfung mit installiertem SDK 2.17.2 / nativem Server 3.9.2](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877331165) deckte gefilterte Listen, die Historie eines ausgewählten Laufs, undurchsichtige Fortsetzung, frühzeitiges Schließen und die Ablehnung einer Namespace-Änderung ab, mit [unabhängiger Abnahme](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877373099). diff --git a/i18n/de/source-hashes.json b/i18n/de/source-hashes.json index e93c4a06a01..27457e918dd 100644 --- a/i18n/de/source-hashes.json +++ b/i18n/de/source-hashes.json @@ -69,7 +69,7 @@ "platform-protocol-specs.md": "ba9c69adfca7fb4a0dd982464b0ca69dd5a21de1e340edbe23b075ec0fb0c35c", "polyglot/avro-value-protocol.md": "602e66c6288c1dd69d2b400c64e4739ad3a0493b5be269cee40f7848b11f260a", "polyglot/cancellation.md": "f676cd3ddb39246a0f580a1e16c83bc36d2ed9458b9e6009af4cc192d299ac62", - "polyglot/cli-python-parity.md": "acf1acbf15ca9cdf069154699c5fbf8c1d1fd3241a32d201ac10b8ec76c038be", + "polyglot/cli-python-parity.md": "70aa49ac5a4cb3413c4ed91cc0bdf232aa5c6726f3e1a4d406c4992658b7a1eb", "polyglot/cli-reference.md": "665c65192f9bfd41610f2aca54a66c2a3aa125e2d2b637d744d9c5f4243bee24", "polyglot/cli.mdx": "9dac7bb6b711737c9f16916ef462d85c642539f4b6e4a1bdac59320a09632c1f", "polyglot/cloud-control-plane.md": "bb375e598dd1afa3207171047fb81b0cb82c382ce535ab415cb09dc10f6d748e", @@ -84,7 +84,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "57734052d6ffae8d660083626bf47fb7c392c492ab0581a8942401046bb25d38", + "polyglot/python.md": "5af6d33bf37899330c4f3026c819081b455a6d15eeeed3888ba05a013d6fa0dc", "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", diff --git a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md index de63bc31098..c3c169feb1e 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md @@ -21,7 +21,7 @@ Esta guía de todos los clientes conserva la ruta original | Consultas | **Compatible:** ejecutar una consulta con nombre de solo lectura con salida estructurada. [Comandos](./cli-reference.md#workflow-commands) | **Compatible:** consultas mediante cliente y handle, más manejadores de consulta registrados en workers. [API de PHP](./php.md#lifecycle-updates-schedules-and-visibility) | **Compatible:** consultas del cliente asíncrono y manejadores de consulta del worker mediante reproducción. [Mensajes](./python.md#signals-queries-and-updates) | **Compatible:** consultas del cliente y manejadores de consulta del worker mediante reproducción cuando el descubrimiento anuncia tareas de consulta. [API de Rust](https://rust.durable-workflow.com/) | | Actualizaciones | **Compatible:** enviar y esperar resultados aceptados o completados. [Comandos](./cli-reference.md#workflow-commands) | **Compatible:** `updateWorkflow` y `registerUpdate`; el SDK de PHP no permite definir validadores y no declara ninguno. [API de PHP](./php.md#lifecycle-updates-schedules-and-visibility) | **Compatible:** clientes, manejadores de workflow y validadores síncronos declarados cuando el descubrimiento anuncia el contrato previo a la aceptación. Los workers con validadores rechazan runtimes incompatibles. [Mensajes](./python.md#signals-queries-and-updates) | **Compatible:** interfaces de cliente, handle, cargas útiles Avro y actualizaciones registradas en workers; el SDK de Rust no permite definir validadores y no declara ninguno. [Actualizaciones](./rust.md#workflow-updates) | | Programaciones | **Compatible:** ciclo de vida completo de programaciones, ejecución retroactiva e historial de auditoría. [Comandos](./cli-reference.md#schedule-commands) | **Compatible:** ciclo de vida completo y listado de programaciones mediante `Client`. [API de PHP](./php.md#lifecycle-updates-schedules-and-visibility) | **Compatible:** ciclo de vida asíncrono completo de programaciones y paginación del historial de auditoría. [Programaciones](./python.md#schedules) | **No compatible:** el SDK actual de Rust no ofrece una API de gestión de programaciones. Utiliza la CLI, PHP, Python o la API del servidor. | -| Visibilidad | **Compatible:** búsqueda de workflows/ejecuciones, workers, colas de tareas, historial y JSON de diagnóstico. [Comandos](./cli-reference.md#workflow-commands) | **Compatible:** filtrado/paginación de workflows, historial, espacios de nombres, workers y colas de tareas. [Evidencia de visibilidad](./php.md#lifecycle-updates-schedules-and-visibility) | **Compatible:** interfaces de cliente para workflows, programaciones, espacios de nombres, workers, colas, historial y atributos de búsqueda. [API del cliente](./python.md#client-api-reference) | **Diferente:** admite descripción/resultado de la ejecución seleccionada; no ofrece listado/búsqueda de toda la flota ni administración de espacios de nombres. [Cliente de Rust](./rust.md#package-and-source) | +| Visibilidad | **Compatible:** búsqueda de workflows/ejecuciones, workers, colas de tareas, historial y JSON de diagnóstico. [Comandos](./cli-reference.md#workflow-commands) | **Compatible:** filtrado/paginación de workflows, historial, espacios de nombres, workers y colas de tareas. [Evidencia de visibilidad](./php.md#lifecycle-updates-schedules-and-visibility) | **Compatible:** interfaces de cliente para workflows, programaciones, espacios de nombres, workers, colas, historial y atributos de búsqueda, incluidos iteradores diferidos de listas de workflows y del historial de una ejecución explícita. [Paginación](./python.md#workflow-list-and-history-pages) | **Diferente:** admite descripción/resultado de la ejecución seleccionada; no ofrece listado/búsqueda de toda la flota ni administración de espacios de nombres. [Cliente de Rust](./rust.md#package-and-source) | | Ejecución de workers | **Diferencia deliberada:** los comandos de protocolo de workers de bajo nivel sirven para diagnóstico y conformidad; `dw` no es un runtime de workers de aplicación. [Comandos de workers](./cli-reference.md#worker-protocol-commands) | **Compatible:** manejadores remotos de workflows, actividades, consultas y actualizaciones mediante `durable-workflow/sdk`. [Worker de PHP](./php.md#run-a-remote-php-worker) | **Compatible:** workers deterministas de workflows y actividades. [Worker de Python](./python.md#worker) | **Compatible:** manejadores nativos de workflows, actividades, consultas y actualizaciones. [API de workers de Rust](https://rust.durable-workflow.com/) | **Compatible** significa que la interfaz de la versión actual indicada ofrece diff --git a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/python.md index 717f369f800..b1232334dce 100644 --- a/i18n/es/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/es/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -116,6 +116,7 @@ Python SDK 2.15 y 2.16 añaden: - **Sufijos de historial sticky (2.16).** Los workers con caché sticky (`sticky_cache_capacity > 0`) anuncian `sticky_history_suffix`. En Server 3.5.0 o posterior, un acierto sticky recibe solo el historial posterior a la secuencia en caché. Un sufijo que no continúa exactamente el historial en caché se descarta y se obtiene el historial completo. - **Valores de workflow tipados (2.15).** `@workflow.defn(..., typed=True)` decodifica los argumentos de `run` y de los handlers según sus anotaciones, y `result_type=` decodifica resultados de workflows hijos y del cliente. Los workflows sin tipos reciben valores simples como antes, así que los historiales en curso se reproducen sin cambios. - **Páginas diferidas (2.15).** `Client.iter_workflows`, `Client.iter_history` y `WorkflowHandle.iter_history` siguen tokens de página manteniendo solo una página. + Consulte [páginas de lista e historial de workflows](#workflow-list-and-history-pages) para el recorrido, la reanudación y el manejo de errores. - **Actividades de una ejecución (2.15).** `Client.get_run_activities` y `WorkflowHandle.get_activities` devuelven metadatos tipados de actividades e intentos, y `ActivityInfo.activity_execution_id` expone la identidad lógica de la actividad. - **Backoff de actividades locales (2.15.1).** Los reintentos después del final de la lista de backoff repiten la última entrada en lugar de reintentar de inmediato. @@ -406,10 +407,13 @@ Los equivalentes CLI son `dw task-queue:build-ids`, `dw task-queue:drain` y | --- | --- | --- | | `await client.start_workflow(...)` | `WorkflowHandle` | `WorkflowAlreadyStarted`, `InvalidArgument`, `Unauthorized`, `ServerError` | | `await client.describe_workflow(workflow_id)` | `WorkflowExecution` | `WorkflowNotFound`, errores de autenticación/servidor | -| `await client.list_workflows(...)` | `WorkflowList` | Errores de autenticación/servidor | +| `await client.list_workflows(...)` | `WorkflowList` (una página) | Errores de autenticación/servidor | +| `client.iter_workflows(...)` | `AsyncIterator[WorkflowExecution]` | Los errores de página y la cancelación se propagan durante la iteración. [Paginación](#workflow-list-and-history-pages). | | `await client.list_workflow_runs(workflow_id)` | `WorkflowRunList` | `WorkflowNotFound`, errores de autenticación/servidor | | `await client.describe_workflow_run(workflow_id, run_id)` | `WorkflowRun` | `WorkflowNotFound`, errores de autenticación/servidor | -| `await client.get_history(workflow_id, run_id)` | carga de historial decodificada | `WorkflowNotFound`, errores de autenticación/servidor | +| `await client.get_history(workflow_id, run_id, ...)` | una página de historial decodificado | `WorkflowNotFound`, errores de autenticación/servidor | +| `client.iter_history(workflow_id, run_id, ...)` | `AsyncIterator[dict[str, Any]]` | Los errores de página y la cancelación se propagan durante la iteración. | +| `handle.iter_history(...)` | `AsyncIterator[dict[str, Any]]` | El mismo recorrido del historial. Requiere un handle con `run_id` explícito. | | `await client.export_history(workflow_id, run_id)` | carga de historial para archivo decodificada | `WorkflowNotFound`, errores de autenticación/servidor | | `await client.signal_workflow(workflow_id, signal_name, args=None)` | recibo de admisión (`dict`) | `WorkflowNotFound`, `InvalidArgument`, errores de autenticación/servidor | | `await client.query_workflow(workflow_id, query_name, args=None)` | recibo de consulta (`dict`) | `QueryFailed`, `WorkflowNotFound`, errores de autenticación/servidor | @@ -2152,4 +2156,12 @@ el namespace: no sustituyas por una dirección autogestionada. Consulta ## Páginas de lista e historial de workflows {#workflow-list-and-history-pages} -Estas llamadas publicadas devuelven **una página**, no una lectura completa automática: `await client.list_workflows(...)` / `await client.get_history(workflow_id, run_id, ...)`. Continúe con el token opaco devuelto manteniendo namespace, filtros y workflow/ejecución seleccionados; termine con token nulo/vacío y gestione los errores de página. Una página parcial no es un bundle de reproducción. Use la API de exportación de historial del SDK para reproducción sin servidor. El [cliente publicado Python 2.9.0](https://github.com/durable-workflow/sdk-python/blob/2.9.0/src/durable_workflow/client.py) define los parámetros actuales; no se implica un nuevo iterador. +El SDK de Python estable seleccionado ofrece `Client.iter_workflows`, `Client.iter_history` y `WorkflowHandle.iter_history` como iteradores diferidos. Use `async for` para consumir ejecuciones de workflows o diccionarios de eventos del historial en el orden del Server. Consulte los [ejemplos y la referencia de paginación del SDK](https://python.durable-workflow.com/sdk-reference/#whole-run-histories-and-workflow-lists) y el [código publicado del cliente](https://github.com/durable-workflow/sdk-python/blob/2.17.2/src/durable_workflow/client.py). + +Cada iterador obtiene una página a la vez sin retener las páginas de resultados anteriores. Sigue las páginas vacías que tengan continuación y termina cuando la continuación falta, es `None` o está vacía. Detener la iteración no obtiene páginas posteriores. Se propagan los errores HTTP, la cancelación, las páginas de historial cuyo campo `events` no es una lista de diccionarios y las continuaciones malformadas o cíclicas. Los elementos ya entregados no se revierten, por lo que un recorrido interrumpido debe tratarse como incompleto. + +Mantenga fijos el espacio de nombres, los filtros y el tamaño de página durante el recorrido. El historial también requiere los mismos `workflow_id` y `run_id` explícitos. El helper del handle rechaza un handle sin `run_id`. Un cambio de espacio de nombres se rechaza antes de la siguiente solicitud. Proporcione `next_page_token` para reanudar desde una continuación opaca de la misma selección. No lo analice, modifique ni reutilice con otros filtros, espacios de nombres o ejecuciones. Recorrer una lista de workflows que cambia no crea una instantánea. + +Las llamadas existentes `await client.list_workflows(...)` y `await client.get_history(workflow_id, run_id, ...)` siguen devolviendo **una página**. Para paginar manualmente, pase el `next_page_token` devuelto a la siguiente llamada y termine cuando el token final falte, sea nulo o esté vacío. Una página parcial o una secuencia de diccionarios de eventos no es un bundle de reproducción. Use `await client.export_history(workflow_id, run_id)` o `await handle.export_history()` para reproducción sin servidor. + +La [prueba de paginación con SDK 2.17.2 instalado / Server nativo 3.9.2](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877331165) cubrió listas filtradas, historial de una ejecución seleccionada, reanudación opaca, cierre anticipado y rechazo de un cambio de espacio de nombres, con [aceptación independiente](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877373099). diff --git a/i18n/es/source-hashes.json b/i18n/es/source-hashes.json index e93c4a06a01..27457e918dd 100644 --- a/i18n/es/source-hashes.json +++ b/i18n/es/source-hashes.json @@ -69,7 +69,7 @@ "platform-protocol-specs.md": "ba9c69adfca7fb4a0dd982464b0ca69dd5a21de1e340edbe23b075ec0fb0c35c", "polyglot/avro-value-protocol.md": "602e66c6288c1dd69d2b400c64e4739ad3a0493b5be269cee40f7848b11f260a", "polyglot/cancellation.md": "f676cd3ddb39246a0f580a1e16c83bc36d2ed9458b9e6009af4cc192d299ac62", - "polyglot/cli-python-parity.md": "acf1acbf15ca9cdf069154699c5fbf8c1d1fd3241a32d201ac10b8ec76c038be", + "polyglot/cli-python-parity.md": "70aa49ac5a4cb3413c4ed91cc0bdf232aa5c6726f3e1a4d406c4992658b7a1eb", "polyglot/cli-reference.md": "665c65192f9bfd41610f2aca54a66c2a3aa125e2d2b637d744d9c5f4243bee24", "polyglot/cli.mdx": "9dac7bb6b711737c9f16916ef462d85c642539f4b6e4a1bdac59320a09632c1f", "polyglot/cloud-control-plane.md": "bb375e598dd1afa3207171047fb81b0cb82c382ce535ab415cb09dc10f6d748e", @@ -84,7 +84,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "57734052d6ffae8d660083626bf47fb7c392c492ab0581a8942401046bb25d38", + "polyglot/python.md": "5af6d33bf37899330c4f3026c819081b455a6d15eeeed3888ba05a013d6fa0dc", "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md index 1714e5d0e69..461d571364d 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md @@ -22,7 +22,7 @@ Ce guide consacré à tous les clients conserve sa route d'origine | Requêtes de lecture | **Prise en charge :** exécuter une requête de lecture nommée avec une sortie structurée. [Commandes](./cli-reference.md#workflow-commands) | **Prise en charge :** requêtes du client et du handle, et gestionnaires de requêtes enregistrés sur le worker. [API PHP](./php.md#lifecycle-updates-schedules-and-visibility) | **Prise en charge :** requêtes du client asynchrone et gestionnaires de requêtes du worker exécutés par relecture. [Messages](./python.md#signals-queries-and-updates) | **Prise en charge :** requêtes du client et gestionnaires de requêtes du worker exécutés par relecture quand la découverte du runtime annonce la prise en charge des tâches de requête. [API Rust](https://rust.durable-workflow.com/) | | Mises à jour | **Prise en charge :** soumettre et attendre l'acceptation ou la fin. [Commandes](./cli-reference.md#workflow-commands) | **Prise en charge :** `updateWorkflow` et `registerUpdate` ; le SDK PHP ne permet pas d'écrire de validateurs et n'en déclare aucun. [API PHP](./php.md#lifecycle-updates-schedules-and-visibility) | **Prise en charge :** clients, gestionnaires de workflow et validateurs synchrones déclarés lorsque la découverte annonce le contrat préalable à l'acceptation. Les workers déclarant des validateurs refusent les runtimes incompatibles. [Messages](./python.md#signals-queries-and-updates) | **Prise en charge :** interfaces de mise à jour du client, du handle, des charges utiles Avro et des gestionnaires enregistrés sur le worker ; le SDK Rust ne permet pas d'écrire de validateurs et n'en déclare aucun. [Mises à jour](./rust.md#workflow-updates) | | Planifications | **Prise en charge :** cycle de vie complet, rattrapage et historique d'audit des planifications. [Commandes](./cli-reference.md#schedule-commands) | **Prise en charge :** cycle de vie complet et listage des planifications via `Client`. [API PHP](./php.md#lifecycle-updates-schedules-and-visibility) | **Prise en charge :** cycle de vie asynchrone complet des planifications et pagination de l'historique d'audit. [Planifications](./python.md#schedules) | **Non prise en charge :** le SDK Rust actuel ne revendique aucune API de gestion des planifications. Utilisez la CLI, PHP, Python ou l'API du serveur. | -| Visibilité | **Prise en charge :** recherche de workflows/exécutions, workers, files de tâches, historique et JSON de diagnostic. [Commandes](./cli-reference.md#workflow-commands) | **Prise en charge :** filtrage/pagination des workflows, historique, espaces de noms, workers et files de tâches. [Éléments de preuve de visibilité](./php.md#lifecycle-updates-schedules-and-visibility) | **Prise en charge :** interfaces client des workflows, planifications, espaces de noms, workers, files, historiques et attributs de recherche. [API client](./python.md#client-api-reference) | **Périmètre différent :** la description et le résultat d'une exécution sélectionnée sont pris en charge ; le listage/la recherche sur toute la flotte et l'administration des espaces de noms ne sont pas revendiqués. [Client Rust](./rust.md#package-and-source) | +| Visibilité | **Prise en charge :** recherche de workflows/exécutions, workers, files de tâches, historique et JSON de diagnostic. [Commandes](./cli-reference.md#workflow-commands) | **Prise en charge :** filtrage/pagination des workflows, historique, espaces de noms, workers et files de tâches. [Éléments de preuve de visibilité](./php.md#lifecycle-updates-schedules-and-visibility) | **Prise en charge :** interfaces client pour les workflows, planifications, espaces de noms, workers, files, historiques et attributs de recherche, dont les itérateurs paresseux de listes de workflows et d’historique d’une exécution explicite. [Pagination](./python.md#workflow-list-and-history-pages) | **Périmètre différent :** la description et le résultat d'une exécution sélectionnée sont pris en charge ; le listage/la recherche sur toute la flotte et l'administration des espaces de noms ne sont pas revendiqués. [Client Rust](./rust.md#package-and-source) | | Exécution des workers | **Périmètre volontairement différent :** les commandes de bas niveau du protocole worker servent au diagnostic et à la conformité ; `dw` n'est pas un runtime de worker applicatif. [Commandes worker](./cli-reference.md#worker-protocol-commands) | **Prise en charge :** gestionnaires distants de workflows, activités, requêtes de lecture et mises à jour via `durable-workflow/sdk`. [Worker PHP](./php.md#run-a-remote-php-worker) | **Prise en charge :** workers déterministes de workflows et d'activités. [Worker Python](./python.md#worker) | **Prise en charge :** gestionnaires natifs de workflows, activités, requêtes de lecture et mises à jour. [API worker Rust](https://rust.durable-workflow.com/) | **Prise en charge** signifie que l'interface de la version actuelle nommée diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/python.md index 51044c2d2a1..df4689a8577 100644 --- a/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/fr/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -118,6 +118,7 @@ Les versions 2.15 et 2.16 du SDK Python ajoutent : - **Suffixes d'historique sticky (2.16).** Les workers dotés d'un cache sticky (`sticky_cache_capacity > 0`) annoncent `sticky_history_suffix`. Sur Server 3.5.0 ou ultérieur, un succès sticky ne reçoit que l'historique postérieur à la séquence en cache. Un suffixe qui ne prolonge pas exactement l'historique en cache est ignoré et l'historique complet est récupéré. - **Valeurs de workflow typées (2.15).** `@workflow.defn(..., typed=True)` décode les arguments de `run` et des handlers selon leurs annotations, et `result_type=` décode les résultats des workflows enfants et du client. Les workflows non typés reçoivent des valeurs simples comme avant, donc les historiques en cours se rejouent sans changement. - **Pages paresseuses (2.15).** `Client.iter_workflows`, `Client.iter_history` et `WorkflowHandle.iter_history` suivent les jetons de page en ne conservant qu'une page. + Voir les [pages de liste et d’historique des workflows](#workflow-list-and-history-pages) pour le parcours, la reprise et la gestion des erreurs. - **Activités d'une exécution (2.15).** `Client.get_run_activities` et `WorkflowHandle.get_activities` renvoient des métadonnées typées d'activités et de tentatives, et `ActivityInfo.activity_execution_id` expose l'identité logique de l'activité. - **Backoff des activités locales (2.15.1).** Les tentatives au-delà de la fin de la liste de backoff répètent la dernière entrée au lieu de réessayer immédiatement. @@ -412,10 +413,13 @@ parcours complet. Les équivalents CLI sont `dw task-queue:build-ids`, | --- | --- | --- | | `await client.start_workflow(...)` | `WorkflowHandle` | `WorkflowAlreadyStarted`, `InvalidArgument`, `Unauthorized`, `ServerError` | | `await client.describe_workflow(workflow_id)` | `WorkflowExecution` | `WorkflowNotFound`, erreurs d'authentification/serveur | -| `await client.list_workflows(...)` | `WorkflowList` | Erreurs d'authentification/serveur | +| `await client.list_workflows(...)` | `WorkflowList` (une page) | Erreurs d'authentification/serveur | +| `client.iter_workflows(...)` | `AsyncIterator[WorkflowExecution]` | Les erreurs de page et l’annulation se propagent pendant l’itération. [Pagination](#workflow-list-and-history-pages). | | `await client.list_workflow_runs(workflow_id)` | `WorkflowRunList` | `WorkflowNotFound`, erreurs d'authentification/serveur | | `await client.describe_workflow_run(workflow_id, run_id)` | `WorkflowRun` | `WorkflowNotFound`, erreurs d'authentification/serveur | -| `await client.get_history(workflow_id, run_id)` | charge utile d'historique décodée | `WorkflowNotFound`, erreurs d'authentification/serveur | +| `await client.get_history(workflow_id, run_id, ...)` | une page d’historique décodé | `WorkflowNotFound`, erreurs d'authentification/serveur | +| `client.iter_history(workflow_id, run_id, ...)` | `AsyncIterator[dict[str, Any]]` | Les erreurs de page et l’annulation se propagent pendant l’itération. | +| `handle.iter_history(...)` | `AsyncIterator[dict[str, Any]]` | Même parcours de l’historique. Nécessite un handle avec un `run_id` explicite. | | `await client.export_history(workflow_id, run_id)` | historique d'archivage décodé | `WorkflowNotFound`, erreurs d'authentification/serveur | | `await client.signal_workflow(workflow_id, signal_name, args=None)` | reçu d’admission (`dict`) | `WorkflowNotFound`, `InvalidArgument`, erreurs d'authentification/serveur | | `await client.query_workflow(workflow_id, query_name, args=None)` | reçu de requête (`dict`) | `QueryFailed`, `WorkflowNotFound`, erreurs d'authentification/serveur | @@ -2202,4 +2206,12 @@ l'espace. Ne remplacez pas son adresse par un Server auto-hébergé. Consultez l ## Pages de liste et d’historique des workflows {#workflow-list-and-history-pages} -Ces appels publiés renvoient **une page**, pas une lecture complète automatique : `await client.list_workflows(...)` / `await client.get_history(workflow_id, run_id, ...)`. Continuez avec le token opaque retourné en conservant namespace, filtres et workflow/exécution sélectionnés ; terminez au token nul/vide et traitez explicitement les erreurs de page. Une page partielle n’est pas un bundle de replay. Utilisez l’API d’export d’historique du SDK pour le replay hors ligne. Le [client publié Python 2.9.0](https://github.com/durable-workflow/sdk-python/blob/2.9.0/src/durable_workflow/client.py) définit les paramètres actuels ; aucun nouvel itérateur n’est annoncé. +Le SDK Python stable sélectionné fournit les itérateurs paresseux `Client.iter_workflows`, `Client.iter_history` et `WorkflowHandle.iter_history`. Utilisez `async for` pour lire les exécutions de workflows ou les dictionnaires d’événements d’historique dans l’ordre du serveur. Consultez les [exemples et la référence de pagination du SDK](https://python.durable-workflow.com/sdk-reference/#whole-run-histories-and-workflow-lists) et le [code publié du client](https://github.com/durable-workflow/sdk-python/blob/2.17.2/src/durable_workflow/client.py). + +Chaque itérateur charge une page à la fois sans conserver les pages de résultats précédentes. Il suit les pages vides qui ont une continuation et s’arrête si la continuation est absente, vaut `None` ou est vide. L’arrêt de l’itération ne charge aucune page suivante. Les erreurs HTTP, l’annulation, les pages d’historique dont le champ `events` n’est pas une liste de dictionnaires et les continuations mal formées ou cycliques se propagent. Les éléments déjà fournis ne sont pas annulés. Traitez donc tout parcours interrompu comme incomplet. + +Conservez le même espace de noms, les mêmes filtres et la même taille de page pendant le parcours. L’historique exige aussi les mêmes `workflow_id` et `run_id` explicites. Le helper du handle refuse un handle sans `run_id`. Un changement d’espace de noms est refusé avant la requête suivante. Fournissez `next_page_token` pour reprendre à une continuation opaque de la même sélection. Ne l’analysez pas, ne le modifiez pas et ne le réutilisez pas pour d’autres filtres, espaces de noms ou exécutions. Parcourir une liste de workflows qui évolue ne crée pas un instantané. + +Les appels existants `await client.list_workflows(...)` et `await client.get_history(workflow_id, run_id, ...)` renvoient toujours **une page**. Pour paginer manuellement, transmettez le `next_page_token` reçu à l’appel suivant et arrêtez-vous au jeton final absent, nul ou vide. Une page partielle ou une suite de dictionnaires d’événements n’est pas un bundle de relecture. Utilisez `await client.export_history(workflow_id, run_id)` ou `await handle.export_history()` pour la relecture hors ligne. + +La [vérification de pagination avec le SDK 2.17.2 installé / Server natif 3.9.2](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877331165) a couvert les listes filtrées, l’historique d’une exécution sélectionnée, la reprise opaque, la fermeture anticipée et le refus d’un changement d’espace de noms, avec [acceptation indépendante](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877373099). diff --git a/i18n/fr/source-hashes.json b/i18n/fr/source-hashes.json index e93c4a06a01..27457e918dd 100644 --- a/i18n/fr/source-hashes.json +++ b/i18n/fr/source-hashes.json @@ -69,7 +69,7 @@ "platform-protocol-specs.md": "ba9c69adfca7fb4a0dd982464b0ca69dd5a21de1e340edbe23b075ec0fb0c35c", "polyglot/avro-value-protocol.md": "602e66c6288c1dd69d2b400c64e4739ad3a0493b5be269cee40f7848b11f260a", "polyglot/cancellation.md": "f676cd3ddb39246a0f580a1e16c83bc36d2ed9458b9e6009af4cc192d299ac62", - "polyglot/cli-python-parity.md": "acf1acbf15ca9cdf069154699c5fbf8c1d1fd3241a32d201ac10b8ec76c038be", + "polyglot/cli-python-parity.md": "70aa49ac5a4cb3413c4ed91cc0bdf232aa5c6726f3e1a4d406c4992658b7a1eb", "polyglot/cli-reference.md": "665c65192f9bfd41610f2aca54a66c2a3aa125e2d2b637d744d9c5f4243bee24", "polyglot/cli.mdx": "9dac7bb6b711737c9f16916ef462d85c642539f4b6e4a1bdac59320a09632c1f", "polyglot/cloud-control-plane.md": "bb375e598dd1afa3207171047fb81b0cb82c382ce535ab415cb09dc10f6d748e", @@ -84,7 +84,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "57734052d6ffae8d660083626bf47fb7c392c492ab0581a8942401046bb25d38", + "polyglot/python.md": "5af6d33bf37899330c4f3026c819081b455a6d15eeeed3888ba05a013d6fa0dc", "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md index ccf5e609ce8..cae68d7dff0 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md @@ -18,7 +18,7 @@ description: CLI、PHP SDK、Python SDK、Rust SDK のクライアント機能 | クエリ | **対応:** 名前付きの読み取り専用クエリを実行し、構造化出力を返す。[コマンド](./cli-reference.md#workflow-commands) | **対応:** クライアントとハンドルのクエリ、および登録した Worker のクエリハンドラー。[PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **対応:** 非同期クライアントのクエリと、リプレイされる Worker のクエリハンドラー。[メッセージ](./python.md#signals-queries-and-updates) | **対応:** ランタイムディスカバリーがクエリタスク対応を広告する場合、クライアントのクエリとリプレイされる Worker のクエリハンドラー。[Rust API](https://rust.durable-workflow.com/) | | 更新 | **対応:** 送信し、受理または完了の結果を待機。[コマンド](./cli-reference.md#workflow-commands) | **対応:** `updateWorkflow` と `registerUpdate`。PHP SDK はバリデーターの記述を公開せず、バリデーターなしと宣言する。[PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **対応:** クライアント、ワークフローハンドラー、およびディスカバリーが事前受理契約を広告する場合の同期宣言バリデーター。バリデーターを持つ Worker は未対応ランタイムを拒否する。[メッセージ](./python.md#signals-queries-and-updates) | **対応:** クライアント、ハンドル、Avro ペイロード、登録した Worker の更新サーフェス。Rust SDK はバリデーターの記述を公開せず、バリデーターなしと宣言する。[更新](./rust.md#workflow-updates) | | スケジュール | **対応:** スケジュールの完全なライフサイクル、バックフィル、監査履歴。[コマンド](./cli-reference.md#schedule-commands) | **対応:** `Client` によるスケジュールの完全なライフサイクルと一覧。[PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **対応:** 完全な非同期スケジュールライフサイクルと監査履歴のページング。[スケジュール](./python.md#schedules) | **未対応:** 現在の Rust SDK はスケジュール管理 API を提供すると表明していない。CLI、PHP、Python、または Server API を使う。 | -| 可視性 | **対応:** ワークフロー・実行の検索、Worker、タスクキュー、履歴、診断 JSON。[コマンド](./cli-reference.md#workflow-commands) | **対応:** ワークフローのフィルタリング・ページング、履歴、名前空間、Worker、タスクキュー。[可視性の根拠](./php.md#lifecycle-updates-schedules-and-visibility) | **対応:** ワークフロー、スケジュール、名前空間、Worker、キュー、履歴、検索属性のクライアントサーフェス。[クライアント API](./python.md#client-api-reference) | **相違:** 選択した実行の説明・結果には対応。全体の一覧・検索と名前空間管理は提供すると表明していない。[Rust クライアント](./rust.md#package-and-source) | +| 可視性 | **対応:** ワークフロー・実行の検索、Worker、タスクキュー、履歴、診断 JSON。[コマンド](./cli-reference.md#workflow-commands) | **対応:** ワークフローのフィルタリング・ページング、履歴、名前空間、Worker、タスクキュー。[可視性の根拠](./php.md#lifecycle-updates-schedules-and-visibility) | **対応：** ワークフロー、スケジュール、名前空間、Worker、キュー、履歴、検索属性のクライアント機能。ワークフロー一覧と明示的な実行の履歴を読む遅延イテレーターを含みます。[ページング](./python.md#workflow-list-and-history-pages) | **相違:** 選択した実行の説明・結果には対応。全体の一覧・検索と名前空間管理は提供すると表明していない。[Rust クライアント](./rust.md#package-and-source) | | Worker の実行 | **意図的な相違:** 低レベルの Worker プロトコルコマンドは診断と適合性検証に対応する。`dw` はアプリケーションの Worker ランタイムではない。[Worker コマンド](./cli-reference.md#worker-protocol-commands) | **対応:** `durable-workflow/sdk` によるリモートのワークフロー、アクティビティ、クエリ、更新のハンドラー。[PHP Worker](./php.md#run-a-remote-php-worker) | **対応:** 決定的なワークフローとアクティビティの Worker。[Python Worker](./python.md#worker) | **対応:** ネイティブのワークフロー、アクティビティ、クエリ、更新のハンドラー。[Rust Worker API](https://rust.durable-workflow.com/) | **対応**は、指定した現行リリースのサーフェスがその機能を公開することを意味します。**相違**は意図的なスコープ境界です。**未対応**は明示的な現在の不足であり、暗黙の約束ではありません。機能がネゴシエーションした Worker プロトコルに依存する場合、ランタイムのプロトコルディスカバリーが引き続き正本です。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/python.md index 70bbeeda538..17ab9923529 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -84,6 +84,7 @@ Python SDK 2.15 と 2.16 では次が追加されています。 - **sticky 履歴サフィックス（2.16）。** sticky キャッシュを持つワーカー（`sticky_cache_capacity > 0`）は `sticky_history_suffix` を示します。Server 3.5.0 以降では、sticky ヒットはキャッシュしたシーケンスより後の履歴だけを受け取ります。キャッシュした履歴に正確に続かないサフィックスは破棄され、完全な履歴を取得します。 - **型付きワークフロー値（2.15）。** `@workflow.defn(..., typed=True)` は `run` とハンドラーの引数をアノテーションに従ってデコードし、`result_type=` は子ワークフローとクライアントの結果をデコードします。型なしのワークフローはこれまでどおりプレーンな値を受け取るため、進行中の履歴は変わらずリプレイされます。 - **遅延ページ（2.15）。** `Client.iter_workflows`、`Client.iter_history`、`WorkflowHandle.iter_history` は、1 ページだけを保持しながらページトークンをたどります。 + 走査、再開、エラー処理については[ワークフロー一覧と履歴のページ](#workflow-list-and-history-pages)を参照してください。 - **実行のアクティビティ（2.15）。** `Client.get_run_activities` と `WorkflowHandle.get_activities` は型付きのアクティビティと試行のメタデータを返し、`ActivityInfo.activity_execution_id` は論理的なアクティビティ ID を公開します。 - **ローカルアクティビティのバックオフ（2.15.1）。** バックオフリストの終わりを超えたリトライは、すぐにリトライせず最後の項目を繰り返します。 @@ -338,10 +339,13 @@ driver = external_storage_driver_from_policy( | --- | --- | --- | | `await client.start_workflow(...)` | `WorkflowHandle` | `WorkflowAlreadyStarted`、`InvalidArgument`、`Unauthorized`、`ServerError` | | `await client.describe_workflow(workflow_id)` | `WorkflowExecution` | `WorkflowNotFound`、認証・Server エラー | -| `await client.list_workflows(...)` | `WorkflowList` | 認証・Server エラー | +| `await client.list_workflows(...)` | `WorkflowList` (1 ページ) | 認証・Server エラー | +| `client.iter_workflows(...)` | `AsyncIterator[WorkflowExecution]` | ページのエラーとキャンセルは反復中に伝播します。 [ページング](#workflow-list-and-history-pages). | | `await client.list_workflow_runs(workflow_id)` | `WorkflowRunList` | `WorkflowNotFound`、認証・Server エラー | | `await client.describe_workflow_run(workflow_id, run_id)` | `WorkflowRun` | `WorkflowNotFound`、認証・Server エラー | -| `await client.get_history(workflow_id, run_id)` | デコード済み履歴ペイロード | `WorkflowNotFound`、認証・Server エラー | +| `await client.get_history(workflow_id, run_id, ...)` | デコードされた履歴の 1 ページ | `WorkflowNotFound`、認証・Server エラー | +| `client.iter_history(workflow_id, run_id, ...)` | `AsyncIterator[dict[str, Any]]` | ページのエラーとキャンセルは反復中に伝播します。 | +| `handle.iter_history(...)` | `AsyncIterator[dict[str, Any]]` | 同じ履歴の走査です。明示的な `run_id` を持つハンドルが必要です。 | | `await client.export_history(workflow_id, run_id)` | デコード済みアーカイブ履歴ペイロード | `WorkflowNotFound`、認証・Server エラー | | `await client.signal_workflow(workflow_id, signal_name, args=None)` | 受け付けレシート (`dict`) | `WorkflowNotFound`、`InvalidArgument`、認証・Server エラー | | `await client.query_workflow(workflow_id, query_name, args=None)` | クエリレシート (`dict`) | `QueryFailed`、`WorkflowNotFound`、認証・Server エラー | @@ -1885,4 +1889,12 @@ client = Client( ## ワークフロー一覧と履歴のページ {#workflow-list-and-history-pages} -公開されている次の呼び出しは、自動的な全件取得ではなく**1ページ**を返します：`await client.list_workflows(...)` / `await client.get_history(workflow_id, run_id, ...)`。返された不透明な token で続け、namespace、フィルター、選択した workflow/run を維持してください。最後の null/空 token で終了し、ページのエラーを明示的に処理します。部分的なページは replay bundle ではありません。オフライン replay には SDK の履歴エクスポート API を使います。[公開 Python 2.9.0 クライアントのソース](https://github.com/durable-workflow/sdk-python/blob/2.9.0/src/durable_workflow/client.py)が現在の引数を定義しており、新たな自動イテレーターの提供を意味しません。 +選択されている安定版 Python SDK は、遅延イテレーター `Client.iter_workflows`、`Client.iter_history`、`WorkflowHandle.iter_history` を提供します。`async for` を使うと、ワークフロー実行や履歴イベントの辞書を Server の順序で読み取れます。[SDK 側の例とページングリファレンス](https://python.durable-workflow.com/sdk-reference/#whole-run-histories-and-workflow-lists)および[公開済みクライアントソース](https://github.com/durable-workflow/sdk-python/blob/2.17.2/src/durable_workflow/client.py)を参照してください。 + +各イテレーターは一度に 1 ページを取得し、以前の結果ページを保持しません。継続情報のある空のページにも進み、継続情報がない、`None`、または空の場合に終了します。反復を停止すると、後続ページは取得されません。HTTP エラー、キャンセル、`events` フィールドが辞書のリストでない履歴ページ、不正または循環する継続情報は伝播します。すでに渡された項目は取り消されないため、中断された走査は未完了として扱ってください。 + +走査中は名前空間、フィルター、ページサイズを固定してください。履歴では、同じ明示的な `workflow_id` と `run_id` も必要です。ハンドルのヘルパーは `run_id` のないハンドルを拒否します。名前空間の変更は次のリクエスト前に拒否されます。同じ選択の不透明な継続位置から再開するには `next_page_token` を指定してください。トークンを解析、変更したり、異なるフィルター、名前空間、実行に再利用したりしないでください。変化するワークフロー一覧を走査してもスナップショットにはなりません。 + +既存の `await client.list_workflows(...)` と `await client.get_history(workflow_id, run_id, ...)` は引き続き **1 ページ**を返します。手動でページングする場合、返された `next_page_token` を次の呼び出しに渡し、最後のトークンが欠落、null、または空なら終了してください。部分的なページやイベント辞書の列はリプレイバンドルではありません。オフラインリプレイには `await client.export_history(workflow_id, run_id)` または `await handle.export_history()` を使用してください。 + +[インストール済み SDK 2.17.2 / ネイティブ Server 3.9.2 のページング検証](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877331165)では、フィルター付き一覧、選択した実行の履歴、不透明な継続情報による再開、早期終了、名前空間変更の拒否を確認し、[独立した受け入れ確認](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877373099)を得ています。 diff --git a/i18n/ja/source-hashes.json b/i18n/ja/source-hashes.json index e93c4a06a01..27457e918dd 100644 --- a/i18n/ja/source-hashes.json +++ b/i18n/ja/source-hashes.json @@ -69,7 +69,7 @@ "platform-protocol-specs.md": "ba9c69adfca7fb4a0dd982464b0ca69dd5a21de1e340edbe23b075ec0fb0c35c", "polyglot/avro-value-protocol.md": "602e66c6288c1dd69d2b400c64e4739ad3a0493b5be269cee40f7848b11f260a", "polyglot/cancellation.md": "f676cd3ddb39246a0f580a1e16c83bc36d2ed9458b9e6009af4cc192d299ac62", - "polyglot/cli-python-parity.md": "acf1acbf15ca9cdf069154699c5fbf8c1d1fd3241a32d201ac10b8ec76c038be", + "polyglot/cli-python-parity.md": "70aa49ac5a4cb3413c4ed91cc0bdf232aa5c6726f3e1a4d406c4992658b7a1eb", "polyglot/cli-reference.md": "665c65192f9bfd41610f2aca54a66c2a3aa125e2d2b637d744d9c5f4243bee24", "polyglot/cli.mdx": "9dac7bb6b711737c9f16916ef462d85c642539f4b6e4a1bdac59320a09632c1f", "polyglot/cloud-control-plane.md": "bb375e598dd1afa3207171047fb81b0cb82c382ce535ab415cb09dc10f6d748e", @@ -84,7 +84,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "57734052d6ffae8d660083626bf47fb7c392c492ab0581a8942401046bb25d38", + "polyglot/python.md": "5af6d33bf37899330c4f3026c819081b455a6d15eeeed3888ba05a013d6fa0dc", "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md index 11d0329cb4f..9daf306f7d3 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md @@ -22,7 +22,7 @@ Este guia de todos os clientes permanece na rota original | Consultas | **Suportado:** executar uma consulta nomeada somente leitura com saída estruturada. [Comandos](./cli-reference.md#workflow-commands) | **Suportado:** consultas por cliente e handle, além de handlers registrados no worker. [API PHP](./php.md#lifecycle-updates-schedules-and-visibility) | **Suportado:** consultas pelo cliente assíncrono e handlers de consulta por replay no worker. [Mensagens](./python.md#signals-queries-and-updates) | **Suportado:** consultas pelo cliente e handlers de consulta por replay no worker quando a descoberta do runtime anuncia suporte a tarefas de consulta. [API Rust](https://rust.durable-workflow.com/) | | Atualizações | **Suportado:** enviar e aguardar resultados aceitos ou concluídos. [Comandos](./cli-reference.md#workflow-commands) | **Suportado:** `updateWorkflow` e `registerUpdate`; o SDK PHP não expõe autoria de validadores e não declara validadores. [API PHP](./php.md#lifecycle-updates-schedules-and-visibility) | **Suportado:** clientes, handlers de workflow e validadores declarados síncronos quando a descoberta anuncia o contrato anterior à aceitação. Workers com validadores recusam runtimes sem suporte. [Mensagens](./python.md#signals-queries-and-updates) | **Suportado:** cliente, handle, payloads Avro e interfaces registradas de atualização no worker; o SDK Rust não expõe autoria de validadores e não declara validadores. [Atualizações](./rust.md#workflow-updates) | | Agendamentos | **Suportado:** ciclo de vida completo, preenchimento retroativo e histórico de auditoria. [Comandos](./cli-reference.md#schedule-commands) | **Suportado:** ciclo de vida completo e listagem por `Client`. [API PHP](./php.md#lifecycle-updates-schedules-and-visibility) | **Suportado:** ciclo de vida assíncrono completo e paginação do histórico de auditoria. [Agendamentos](./python.md#schedules) | **Não suportado:** o SDK Rust atual não declara uma API de gestão de agendamentos. Use CLI, PHP, Python ou a API do servidor. | -| Visibilidade | **Suportado:** busca de workflows/execuções, workers, filas de tarefas, histórico e JSON diagnóstico. [Comandos](./cli-reference.md#workflow-commands) | **Suportado:** filtragem/paginação de workflows, histórico, namespaces, workers e filas de tarefas. [Evidências de visibilidade](./php.md#lifecycle-updates-schedules-and-visibility) | **Suportado:** interfaces de cliente para workflows, agendamentos, namespaces, workers, filas, histórico e atributos de busca. [API do cliente](./python.md#client-api-reference) | **Diferente:** descrição/resultado da execução selecionada são suportados; não se declara listagem/busca em toda a frota nem administração de namespaces. [Cliente Rust](./rust.md#package-and-source) | +| Visibilidade | **Suportado:** busca de workflows/execuções, workers, filas de tarefas, histórico e JSON diagnóstico. [Comandos](./cli-reference.md#workflow-commands) | **Suportado:** filtragem/paginação de workflows, histórico, namespaces, workers e filas de tarefas. [Evidências de visibilidade](./php.md#lifecycle-updates-schedules-and-visibility) | **Suportado:** interfaces de cliente para workflows, agendamentos, namespaces, workers, filas, histórico e atributos de busca, incluindo iteradores sob demanda para listas de workflows e histórico de uma execução explícita. [Paginação](./python.md#workflow-list-and-history-pages) | **Diferente:** descrição/resultado da execução selecionada são suportados; não se declara listagem/busca em toda a frota nem administração de namespaces. [Cliente Rust](./rust.md#package-and-source) | | Execução de workers | **Intencionalmente diferente:** comandos de baixo nível do protocolo de workers servem para diagnóstico e conformidade; `dw` não é um runtime de worker de aplicação. [Comandos de workers](./cli-reference.md#worker-protocol-commands) | **Suportado:** handlers remotos de workflow, atividade, consulta e atualização por `durable-workflow/sdk`. [Worker PHP](./php.md#run-a-remote-php-worker) | **Suportado:** workers determinísticos de workflows e atividades. [Worker Python](./python.md#worker) | **Suportado:** handlers nativos de workflow, atividade, consulta e atualização. [API de worker Rust](https://rust.durable-workflow.com/) | **Suportado** significa que a interface do release atual indicado expõe a diff --git a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/python.md index cb546ed266b..e2803306d02 100644 --- a/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/pt-BR/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -117,6 +117,7 @@ O SDK Python 2.15 e 2.16 adicionam: - **Sufixos de histórico sticky (2.16).** Workers com cache sticky (`sticky_cache_capacity > 0`) anunciam `sticky_history_suffix`. No Server 3.5.0 ou posterior, um acerto sticky recebe só o histórico após a sequência em cache. Um sufixo que não continua exatamente o histórico em cache é descartado e o histórico completo é buscado. - **Valores de workflow tipados (2.15).** `@workflow.defn(..., typed=True)` decodifica os argumentos de `run` e dos handlers conforme suas anotações, e `result_type=` decodifica resultados de workflows filhos e do cliente. Workflows sem tipos recebem valores simples como antes, então históricos em andamento são reproduzidos sem mudança. - **Páginas preguiçosas (2.15).** `Client.iter_workflows`, `Client.iter_history` e `WorkflowHandle.iter_history` seguem tokens de página mantendo só uma página. + Veja [páginas de lista e histórico de workflows](#workflow-list-and-history-pages) para travessia, retomada e tratamento de erros. - **Atividades de uma execução (2.15).** `Client.get_run_activities` e `WorkflowHandle.get_activities` retornam metadados tipados de atividades e tentativas, e `ActivityInfo.activity_execution_id` expõe a identidade lógica da atividade. - **Backoff de atividades locais (2.15.1).** Tentativas após o fim da lista de backoff repetem a última entrada em vez de tentar de novo imediatamente. @@ -411,10 +412,13 @@ o procedimento completo; os equivalentes CLI são `dw task-queue:build-ids`, | --- | --- | --- | | `await client.start_workflow(...)` | `WorkflowHandle` | `WorkflowAlreadyStarted`, `InvalidArgument`, `Unauthorized`, `ServerError` | | `await client.describe_workflow(workflow_id)` | `WorkflowExecution` | `WorkflowNotFound`, erros de autenticação/servidor | -| `await client.list_workflows(...)` | `WorkflowList` | Erros de autenticação/servidor | +| `await client.list_workflows(...)` | `WorkflowList` (uma página) | Erros de autenticação/servidor | +| `client.iter_workflows(...)` | `AsyncIterator[WorkflowExecution]` | Erros de página e cancelamento são propagados durante a iteração. [Paginação](#workflow-list-and-history-pages). | | `await client.list_workflow_runs(workflow_id)` | `WorkflowRunList` | `WorkflowNotFound`, erros de autenticação/servidor | | `await client.describe_workflow_run(workflow_id, run_id)` | `WorkflowRun` | `WorkflowNotFound`, erros de autenticação/servidor | -| `await client.get_history(workflow_id, run_id)` | payload de histórico decodificado | `WorkflowNotFound`, erros de autenticação/servidor | +| `await client.get_history(workflow_id, run_id, ...)` | uma página de histórico decodificado | `WorkflowNotFound`, erros de autenticação/servidor | +| `client.iter_history(workflow_id, run_id, ...)` | `AsyncIterator[dict[str, Any]]` | Erros de página e cancelamento são propagados durante a iteração. | +| `handle.iter_history(...)` | `AsyncIterator[dict[str, Any]]` | A mesma travessia de histórico. Requer um handle com `run_id` explícito. | | `await client.export_history(workflow_id, run_id)` | payload de histórico de arquivo decodificado | `WorkflowNotFound`, erros de autenticação/servidor | | `await client.signal_workflow(workflow_id, signal_name, args=None)` | recibo de admissão (`dict`) | `WorkflowNotFound`, `InvalidArgument`, erros de autenticação/servidor | | `await client.query_workflow(workflow_id, query_name, args=None)` | recibo de consulta (`dict`) | `QueryFailed`, `WorkflowNotFound`, erros de autenticação/servidor | @@ -2199,4 +2203,12 @@ sua administração. Veja [Runtime gerenciado do Cloud](/docs/polyglot/cloud-con ## Páginas de lista e histórico de workflows {#workflow-list-and-history-pages} -Estas chamadas publicadas retornam **uma página**, não uma leitura completa automática: `await client.list_workflows(...)` / `await client.get_history(workflow_id, run_id, ...)`. Continue com o token opaco retornado preservando namespace, filtros e workflow/execução selecionados; encerre no token nulo/vazio e trate erros de página. Uma página parcial não é um bundle de replay. Use a API de exportação de histórico do SDK para replay sem servidor. O [cliente publicado Python 2.9.0](https://github.com/durable-workflow/sdk-python/blob/2.9.0/src/durable_workflow/client.py) define os parâmetros atuais; não se afirma um novo iterador. +O SDK Python estável selecionado fornece os iteradores sob demanda `Client.iter_workflows`, `Client.iter_history` e `WorkflowHandle.iter_history`. Use `async for` para consumir execuções de workflows ou dicionários de eventos de histórico na ordem do Server. Veja os [exemplos e a referência de paginação do SDK](https://python.durable-workflow.com/sdk-reference/#whole-run-histories-and-workflow-lists) e o [código publicado do cliente](https://github.com/durable-workflow/sdk-python/blob/2.17.2/src/durable_workflow/client.py). + +Cada iterador busca uma página por vez sem reter as páginas de resultados anteriores. Ele segue páginas vazias que tenham continuação e termina quando a continuação está ausente, é `None` ou está vazia. Encerrar a iteração não busca páginas seguintes. Erros HTTP, cancelamento, páginas de histórico cujo campo `events` não é uma lista de dicionários e continuações malformadas ou cíclicas são propagados. Os itens já entregues não são revertidos, portanto trate uma travessia interrompida como incompleta. + +Mantenha namespace, filtros e tamanho de página fixos durante a travessia. O histórico também exige os mesmos `workflow_id` e `run_id` explícitos. O helper do handle recusa um handle sem `run_id`. Uma mudança de namespace é recusada antes da próxima solicitação. Forneça `next_page_token` para retomar em uma continuação opaca da mesma seleção. Não analise, altere ou reutilize esse token com outros filtros, namespaces ou execuções. Percorrer uma lista de workflows que muda não cria um snapshot. + +As chamadas existentes `await client.list_workflows(...)` e `await client.get_history(workflow_id, run_id, ...)` continuam retornando **uma página**. Para paginação manual, passe o `next_page_token` retornado à próxima chamada e termine quando o token final estiver ausente, for nulo ou estiver vazio. Uma página parcial ou sequência de dicionários de eventos não é um bundle de replay. Use `await client.export_history(workflow_id, run_id)` ou `await handle.export_history()` para replay offline. + +A [verificação de paginação com SDK 2.17.2 instalado / Server nativo 3.9.2](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877331165) cobriu listas filtradas, histórico de uma execução selecionada, retomada opaca, fechamento antecipado e recusa de mudança de namespace, com [aceitação independente](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877373099). diff --git a/i18n/pt-BR/source-hashes.json b/i18n/pt-BR/source-hashes.json index e93c4a06a01..27457e918dd 100644 --- a/i18n/pt-BR/source-hashes.json +++ b/i18n/pt-BR/source-hashes.json @@ -69,7 +69,7 @@ "platform-protocol-specs.md": "ba9c69adfca7fb4a0dd982464b0ca69dd5a21de1e340edbe23b075ec0fb0c35c", "polyglot/avro-value-protocol.md": "602e66c6288c1dd69d2b400c64e4739ad3a0493b5be269cee40f7848b11f260a", "polyglot/cancellation.md": "f676cd3ddb39246a0f580a1e16c83bc36d2ed9458b9e6009af4cc192d299ac62", - "polyglot/cli-python-parity.md": "acf1acbf15ca9cdf069154699c5fbf8c1d1fd3241a32d201ac10b8ec76c038be", + "polyglot/cli-python-parity.md": "70aa49ac5a4cb3413c4ed91cc0bdf232aa5c6726f3e1a4d406c4992658b7a1eb", "polyglot/cli-reference.md": "665c65192f9bfd41610f2aca54a66c2a3aa125e2d2b637d744d9c5f4243bee24", "polyglot/cli.mdx": "9dac7bb6b711737c9f16916ef462d85c642539f4b6e4a1bdac59320a09632c1f", "polyglot/cloud-control-plane.md": "bb375e598dd1afa3207171047fb81b0cb82c382ce535ab415cb09dc10f6d748e", @@ -84,7 +84,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "57734052d6ffae8d660083626bf47fb7c392c492ab0581a8942401046bb25d38", + "polyglot/python.md": "5af6d33bf37899330c4f3026c819081b455a6d15eeeed3888ba05a013d6fa0dc", "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", diff --git a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md index d421184b100..9a33dc74042 100644 --- a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md +++ b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md @@ -21,7 +21,7 @@ Python і Rust використовують спільні контракти п | Query | **Підтримується:** виконання іменованого query лише для читання зі структурованим виводом. [Команди](./cli-reference.md#workflow-commands) | **Підтримується:** query клієнта й handle та зареєстровані обробники query worker. [PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **Підтримується:** query async-клієнта та обробники query worker через replay. [Повідомлення](./python.md#signals-queries-and-updates) | **Підтримується:** query клієнта та обробники query worker через replay, коли виявлення runtime оголошує підтримку завдань query. [Rust API](https://rust.durable-workflow.com/) | | Update | **Підтримується:** подання й очікування прийнятого або завершеного результату. [Команди](./cli-reference.md#workflow-commands) | **Підтримується:** `updateWorkflow` і `registerUpdate`. PHP SDK не має написання валідаторів і не оголошує їх. [PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **Підтримується:** клієнти, обробники workflow та синхронні оголошені валідатори, коли виявлення оголошує контракт перевірки перед прийняттям. Worker із валідаторами відхиляють непідтримувані runtime. [Повідомлення](./python.md#signals-queries-and-updates) | **Підтримується:** клієнт, handle, payload Avro та зареєстровані інтерфейси update worker. Rust SDK не має написання валідаторів і не оголошує їх. [Update](./rust.md#workflow-updates) | | Розклади | **Підтримується:** повний життєвий цикл розкладу, backfill та історія аудиту. [Команди](./cli-reference.md#schedule-commands) | **Підтримується:** повний життєвий цикл розкладу та список через `Client`. [PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **Підтримується:** повний async-життєвий цикл розкладу та посторінкова історія аудиту. [Розклади](./python.md#schedules) | **Не підтримується:** поточний Rust SDK не заявляє API керування розкладами. Використовуйте CLI, PHP, Python або Server API. | -| Видимість | **Підтримується:** пошук workflow/run, worker, черги завдань, історія та JSON діагностики. [Команди](./cli-reference.md#workflow-commands) | **Підтримується:** фільтрування/посторінковий перегляд workflow, історія, простори імен, worker та черги завдань. [Докази видимості](./php.md#lifecycle-updates-schedules-and-visibility) | **Підтримується:** клієнтські інтерфейси workflow, розкладів, просторів імен, worker, черг, історії та пошукових атрибутів. [Client API](./python.md#client-api-reference) | **Відрізняється:** опис/результат обраного run підтримуються. Загальний список/пошук усіх worker/run та адміністрування просторів імен не заявлені. [Клієнт Rust](./rust.md#package-and-source) | +| Видимість | **Підтримується:** пошук workflow/run, worker, черги завдань, історія та JSON діагностики. [Команди](./cli-reference.md#workflow-commands) | **Підтримується:** фільтрування/посторінковий перегляд workflow, історія, простори імен, worker та черги завдань. [Докази видимості](./php.md#lifecycle-updates-schedules-and-visibility) | **Підтримується:** клієнтські інтерфейси workflow, розкладів, просторів імен, worker, черг, історії та пошукових атрибутів, зокрема ліниві ітератори списку workflow та історії явно вибраного run. [Посторінковий обхід](./python.md#workflow-list-and-history-pages) | **Відрізняється:** опис/результат обраного run підтримуються. Загальний список/пошук усіх worker/run та адміністрування просторів імен не заявлені. [Клієнт Rust](./rust.md#package-and-source) | | Виконання worker | **Навмисно відрізняється:** низькорівневі команди протоколу worker підтримують діагностику й перевірку відповідності. `dw` не є runtime worker застосунку. [Команди worker](./cli-reference.md#worker-protocol-commands) | **Підтримується:** віддалені обробники workflow, activity, query та update через `durable-workflow/sdk`. [Worker PHP](./php.md#run-a-remote-php-worker) | **Підтримується:** детерміновані worker workflow та activity. [Worker Python](./python.md#worker) | **Підтримується:** власні обробники workflow, activity, query та update. [API worker Rust](https://rust.durable-workflow.com/) | **Підтримується** означає, що названий інтерфейс поточного випуску має diff --git a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/python.md index dd61b1ff583..261113ef5c6 100644 --- a/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/uk/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -115,6 +115,7 @@ Python SDK 2.15 і 2.16 додають: - **Sticky-суфікси історії (2.16).** Workers зі sticky-кешем (`sticky_cache_capacity > 0`) оголошують `sticky_history_suffix`. На Server 3.5.0 або новішому sticky-влучання отримує лише історію після закешованої послідовності. Суфікс, що не продовжує закешовану історію точно, відкидається, і завантажується повна історія. - **Типізовані значення workflow (2.15).** `@workflow.defn(..., typed=True)` декодує аргументи `run` і handlers за їхніми анотаціями, а `result_type=` декодує результати дочірніх workflows і клієнта. Нетипізовані workflows, як і раніше, отримують прості значення, тож поточні історії відтворюються без змін. - **Ліниві сторінки (2.15).** `Client.iter_workflows`, `Client.iter_history` і `WorkflowHandle.iter_history` переходять за токенами сторінок, тримаючи лише одну сторінку. + Див. [сторінки списку workflow та історії](#workflow-list-and-history-pages) щодо обходу, відновлення та обробки помилок. - **Активності запуску (2.15).** `Client.get_run_activities` і `WorkflowHandle.get_activities` повертають типізовані метадані активностей і спроб, а `ActivityInfo.activity_execution_id` надає логічну ідентичність активності. - **Backoff локальних активностей (2.15.1).** Повторні спроби після кінця списку backoff повторюють останній запис замість негайної повторної спроби. @@ -405,10 +406,13 @@ Namespace є межею орендарів workflow, schedule, атрибуті | --- | --- | --- | | `await client.start_workflow(...)` | `WorkflowHandle` | `WorkflowAlreadyStarted`, `InvalidArgument`, `Unauthorized`, `ServerError` | | `await client.describe_workflow(workflow_id)` | `WorkflowExecution` | `WorkflowNotFound`, помилки автентифікації/Server | -| `await client.list_workflows(...)` | `WorkflowList` | Помилки автентифікації/Server | +| `await client.list_workflows(...)` | `WorkflowList` (одна сторінка) | Помилки автентифікації/Server | +| `client.iter_workflows(...)` | `AsyncIterator[WorkflowExecution]` | Помилки сторінок і скасування поширюються під час ітерації. [Посторінковий обхід](#workflow-list-and-history-pages). | | `await client.list_workflow_runs(workflow_id)` | `WorkflowRunList` | `WorkflowNotFound`, помилки автентифікації/Server | | `await client.describe_workflow_run(workflow_id, run_id)` | `WorkflowRun` | `WorkflowNotFound`, помилки автентифікації/Server | -| `await client.get_history(workflow_id, run_id)` | декодований payload історії | `WorkflowNotFound`, помилки автентифікації/Server | +| `await client.get_history(workflow_id, run_id, ...)` | одна сторінка декодованої історії | `WorkflowNotFound`, помилки автентифікації/Server | +| `client.iter_history(workflow_id, run_id, ...)` | `AsyncIterator[dict[str, Any]]` | Помилки сторінок і скасування поширюються під час ітерації. | +| `handle.iter_history(...)` | `AsyncIterator[dict[str, Any]]` | Той самий обхід історії. Потрібен handle з явним `run_id`. | | `await client.export_history(workflow_id, run_id)` | декодований архівний payload історії | `WorkflowNotFound`, помилки автентифікації/Server | | `await client.signal_workflow(workflow_id, signal_name, args=None)` | квитанція прийняття (`dict`) | `WorkflowNotFound`, `InvalidArgument`, помилки автентифікації/Server | | `await client.query_workflow(workflow_id, query_name, args=None)` | квитанція запиту (`dict`) | `QueryFailed`, `WorkflowNotFound`, помилки автентифікації/Server | @@ -2169,4 +2173,12 @@ Cloud створює namespace. Не заміняйте URL адресою са ## Сторінки списку workflow та історії {#workflow-list-and-history-pages} -Ці опубліковані виклики повертають **одну сторінку**, а не автоматично повний результат: `await client.list_workflows(...)` / `await client.get_history(workflow_id, run_id, ...)`. Продовжуйте з повернутим непрозорим token, зберігаючи namespace, фільтри та вибрані workflow/run; зупиняйтеся на null/порожньому token й явно обробляйте помилки сторінок. Часткова сторінка не є replay-bundle. Для офлайн-replay використовуйте API експорту історії SDK. [Опублікований клієнт Python 2.9.0](https://github.com/durable-workflow/sdk-python/blob/2.9.0/src/durable_workflow/client.py) визначає поточні параметри; нові ітератори не заявляються. +Вибраний стабільний Python SDK надає ліниві ітератори `Client.iter_workflows`, `Client.iter_history` і `WorkflowHandle.iter_history`. Використовуйте `async for`, щоб читати запуски workflow або словники подій історії в порядку Server. Див. [приклади та довідник посторінкового обходу SDK](https://python.durable-workflow.com/sdk-reference/#whole-run-histories-and-workflow-lists) і [опублікований код клієнта](https://github.com/durable-workflow/sdk-python/blob/2.17.2/src/durable_workflow/client.py). + +Кожен ітератор отримує одну сторінку за раз і не зберігає попередні сторінки результатів. Він проходить порожні сторінки з продовженням і завершується, коли продовження відсутнє, дорівнює `None` або порожнє. Зупинка ітерації не отримує наступні сторінки. Помилки HTTP, скасування, сторінки історії, чиє поле `events` не є списком словників, а також некоректні або циклічні продовження поширюються до викликача. Уже видані елементи не відкочуються, тому перерваний обхід слід вважати неповним. + +Протягом обходу зберігайте незмінними namespace, фільтри та розмір сторінки. Історія також потребує тих самих явних `workflow_id` і `run_id`. Допоміжний метод handle відмовляє для handle без `run_id`. Зміна namespace відхиляється перед наступним запитом. Передайте `next_page_token`, щоб відновити обхід із непрозорого продовження того самого вибору. Не розбирайте, не змінюйте й не використовуйте його для інших фільтрів, namespace або run. Обхід списку workflow, який змінюється, не створює знімка. + +Наявні виклики `await client.list_workflows(...)` і `await client.get_history(workflow_id, run_id, ...)` і далі повертають **одну сторінку**. Для ручного обходу передавайте отриманий `next_page_token` до наступного виклику й завершуйтеся, коли останній токен відсутній, null або порожній. Часткова сторінка або послідовність словників подій не є replay-bundle. Для офлайн-replay використовуйте `await client.export_history(workflow_id, run_id)` або `await handle.export_history()`. + +[Перевірка пагінації зі встановленим SDK 2.17.2 / native Server 3.9.2](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877331165) охопила фільтровані списки, історію вибраного run, відновлення за непрозорим токеном, дострокове закриття та відмову при зміні namespace, з [незалежним підтвердженням](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877373099). diff --git a/i18n/uk/source-hashes.json b/i18n/uk/source-hashes.json index e93c4a06a01..27457e918dd 100644 --- a/i18n/uk/source-hashes.json +++ b/i18n/uk/source-hashes.json @@ -69,7 +69,7 @@ "platform-protocol-specs.md": "ba9c69adfca7fb4a0dd982464b0ca69dd5a21de1e340edbe23b075ec0fb0c35c", "polyglot/avro-value-protocol.md": "602e66c6288c1dd69d2b400c64e4739ad3a0493b5be269cee40f7848b11f260a", "polyglot/cancellation.md": "f676cd3ddb39246a0f580a1e16c83bc36d2ed9458b9e6009af4cc192d299ac62", - "polyglot/cli-python-parity.md": "acf1acbf15ca9cdf069154699c5fbf8c1d1fd3241a32d201ac10b8ec76c038be", + "polyglot/cli-python-parity.md": "70aa49ac5a4cb3413c4ed91cc0bdf232aa5c6726f3e1a4d406c4992658b7a1eb", "polyglot/cli-reference.md": "665c65192f9bfd41610f2aca54a66c2a3aa125e2d2b637d744d9c5f4243bee24", "polyglot/cli.mdx": "9dac7bb6b711737c9f16916ef462d85c642539f4b6e4a1bdac59320a09632c1f", "polyglot/cloud-control-plane.md": "bb375e598dd1afa3207171047fb81b0cb82c382ce535ab415cb09dc10f6d748e", @@ -84,7 +84,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "57734052d6ffae8d660083626bf47fb7c392c492ab0581a8942401046bb25d38", + "polyglot/python.md": "5af6d33bf37899330c4f3026c819081b455a6d15eeeed3888ba05a013d6fa0dc", "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314", diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md index e0c226bc9f9..9a797743bff 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/cli-python-parity.md @@ -18,7 +18,7 @@ description: 比较 CLI、PHP SDK、Python SDK 和 Rust SDK 的客户端与 Work | 查询 | **支持：**执行具名只读查询并输出结构化结果。[命令](./cli-reference.md#workflow-commands) | **支持：**客户端与句柄查询，以及已注册的 Worker 查询处理器。[PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **支持：**异步客户端查询，以及经重放的 Worker 查询处理器。[消息](./python.md#signals-queries-and-updates) | **支持：**当运行时发现公布查询任务支持时，支持客户端查询及经重放的 Worker 查询处理器。[Rust API](https://rust.durable-workflow.com/) | | 更新 | **支持：**提交并等待已接受或已完成的结果。[命令](./cli-reference.md#workflow-commands) | **支持：**`updateWorkflow` 和 `registerUpdate`；PHP SDK 不提供验证器编写接口，也不声明任何验证器。[PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **支持：**当发现结果公布接受前契约时，支持客户端、工作流处理器及同步声明的验证器。带验证器的 Worker 会拒绝不支持的运行时。[消息](./python.md#signals-queries-and-updates) | **支持：**客户端、句柄、Avro 载荷及已注册的 Worker 更新接口；Rust SDK 不提供验证器编写接口，也不声明任何验证器。[更新](./rust.md#workflow-updates) | | 调度 | **支持：**完整调度生命周期、补跑及审计历史。[命令](./cli-reference.md#schedule-commands) | **支持：**通过 `Client` 管理完整调度生命周期并列出调度。[PHP API](./php.md#lifecycle-updates-schedules-and-visibility) | **支持：**完整异步调度生命周期及审计历史分页。[调度](./python.md#schedules) | **不支持：**当前 Rust SDK 不声明调度管理 API。请使用 CLI、PHP、Python 或 Server API。 | -| 可观测性 | **支持：**工作流/运行搜索、Worker、任务队列、历史及诊断 JSON。[命令](./cli-reference.md#workflow-commands) | **支持：**工作流过滤/分页、历史、命名空间、Worker 及任务队列。[可观测性证据](./php.md#lifecycle-updates-schedules-and-visibility) | **支持：**工作流、调度、命名空间、Worker、队列、历史及搜索属性客户端接口。[客户端 API](./python.md#client-api-reference) | **范围不同：**支持选定运行的描述/结果；不声明整个集群的列表/搜索及命名空间管理能力。[Rust 客户端](./rust.md#package-and-source) | +| 可观测性 | **支持：**工作流/运行搜索、Worker、任务队列、历史及诊断 JSON。[命令](./cli-reference.md#workflow-commands) | **支持：**工作流过滤/分页、历史、命名空间、Worker 及任务队列。[可观测性证据](./php.md#lifecycle-updates-schedules-and-visibility) | **支持：**工作流、调度、命名空间、Worker、队列、历史及搜索属性客户端接口，包括工作流列表和显式运行历史的惰性迭代器。[分页](./python.md#workflow-list-and-history-pages) | **范围不同：**支持选定运行的描述/结果；不声明整个集群的列表/搜索及命名空间管理能力。[Rust 客户端](./rust.md#package-and-source) | | Worker 执行 | **有意区分：**底层 Worker 协议命令用于诊断和一致性验证；`dw` 不是应用 Worker 运行时。[Worker 命令](./cli-reference.md#worker-protocol-commands) | **支持：**通过 `durable-workflow/sdk` 提供远程工作流、活动、查询及更新处理器。[PHP Worker](./php.md#run-a-remote-php-worker) | **支持：**确定性工作流及活动 Worker。[Python Worker](./python.md#worker) | **支持：**原生工作流、活动、查询及更新处理器。[Rust Worker API](https://rust.durable-workflow.com/) | **支持**表示所列当前发布版本的接口提供该能力。**范围不同**表示有意设置的范围边界。**不支持**表示明确的当前缺口，不是隐藏承诺。当能力依赖协商的 Worker 协议时，以运行时协议发现为准。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/python.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/python.md index 1e4d8f0cadd..a32988ab686 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/python.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/polyglot/python.md @@ -81,6 +81,7 @@ Python SDK 2.15 和 2.16 新增： - **Sticky 历史后缀（2.16）。** 带 sticky 缓存（`sticky_cache_capacity > 0`）的 worker 声明 `sticky_history_suffix`。在 Server 3.5.0 或更高版本上，sticky 命中只接收缓存序列之后的历史。不能精确接续缓存历史的后缀会被丢弃，并重新获取完整历史。 - **类型化工作流值（2.15）。** `@workflow.defn(..., typed=True)` 按注解解码 `run` 和处理器的参数，`result_type=` 解码子工作流和客户端的结果。未类型化的工作流仍像以前一样接收普通值，因此进行中的历史会原样重放。 - **惰性分页（2.15）。** `Client.iter_workflows`、`Client.iter_history` 和 `WorkflowHandle.iter_history` 按分页令牌遍历，同时只保留一页。 + 遍历、恢复和错误处理请参阅[工作流列表与历史页面](#workflow-list-and-history-pages)。 - **运行的活动（2.15）。** `Client.get_run_activities` 和 `WorkflowHandle.get_activities` 返回类型化的活动和尝试元数据，`ActivityInfo.activity_execution_id` 暴露逻辑活动标识。 - **本地活动的退避（2.15.1）。** 超出退避列表末尾的重试会重复最后一项，而不是立即重试。 @@ -335,10 +336,13 @@ driver = external_storage_driver_from_policy( | --- | --- | --- | | `await client.start_workflow(...)` | `WorkflowHandle` | `WorkflowAlreadyStarted`, `InvalidArgument`, `Unauthorized`, `ServerError` | | `await client.describe_workflow(workflow_id)` | `WorkflowExecution` | `WorkflowNotFound`, 认证/Server 错误 | -| `await client.list_workflows(...)` | `WorkflowList` | 认证/Server 错误 | +| `await client.list_workflows(...)` | `WorkflowList` (一页) | 认证/Server 错误 | +| `client.iter_workflows(...)` | `AsyncIterator[WorkflowExecution]` | 页面错误和取消会在迭代期间向上传播。 [分页](#workflow-list-and-history-pages). | | `await client.list_workflow_runs(workflow_id)` | `WorkflowRunList` | `WorkflowNotFound`, 认证/Server 错误 | | `await client.describe_workflow_run(workflow_id, run_id)` | `WorkflowRun` | `WorkflowNotFound`, 认证/Server 错误 | -| `await client.get_history(workflow_id, run_id)` | 已解码历史负载 | `WorkflowNotFound`, 认证/Server 错误 | +| `await client.get_history(workflow_id, run_id, ...)` | 一页已解码历史 | `WorkflowNotFound`, 认证/Server 错误 | +| `client.iter_history(workflow_id, run_id, ...)` | `AsyncIterator[dict[str, Any]]` | 页面错误和取消会在迭代期间向上传播。 | +| `handle.iter_history(...)` | `AsyncIterator[dict[str, Any]]` | 相同的历史遍历方式。需要带有显式 `run_id` 的句柄。 | | `await client.export_history(workflow_id, run_id)` | 已解码归档历史负载 | `WorkflowNotFound`, 认证/Server 错误 | | `await client.signal_workflow(workflow_id, signal_name, args=None)` | 接纳回执 (`dict`) | `WorkflowNotFound`, `InvalidArgument`, 认证/Server 错误 | | `await client.query_workflow(workflow_id, query_name, args=None)` | 查询回执 (`dict`) | `QueryFailed`, `WorkflowNotFound`, 认证/Server 错误 | @@ -1848,4 +1852,12 @@ client = Client( ## 工作流列表与历史页面 {#workflow-list-and-history-pages} -这些已发布调用每次返回**一页**，不会自动完整读取：`await client.list_workflows(...)` / `await client.get_history(workflow_id, run_id, ...)`。继续请求时使用返回的不透明 token，并保持 namespace、筛选条件和所选 workflow/run 不变；最终 null/空 token 表示结束，页面错误必须明确处理。部分页面不是 replay bundle。离线 replay 请使用 SDK 的历史导出 API。[已发布的 Python 2.9.0 客户端源码](https://github.com/durable-workflow/sdk-python/blob/2.9.0/src/durable_workflow/client.py)定义当前参数；这里不声称新增自动迭代器。 +所选稳定版 Python SDK 提供惰性迭代器 `Client.iter_workflows`、`Client.iter_history` 和 `WorkflowHandle.iter_history`。使用 `async for` 可按 Server 顺序读取工作流运行或历史事件字典。请参阅 [SDK 提供的示例与分页参考](https://python.durable-workflow.com/sdk-reference/#whole-run-histories-and-workflow-lists)和[已发布客户端源码](https://github.com/durable-workflow/sdk-python/blob/2.17.2/src/durable_workflow/client.py)。 + +每个迭代器一次获取一页，不保留之前的结果页。即使页面为空，只要有继续标记就会继续；继续标记缺失、为 `None` 或为空时结束。停止迭代不会再获取后续页面。HTTP 错误、取消、`events` 字段不是字典列表的历史页面，以及格式错误或形成循环的继续标记都会向上传播。已返回的条目不会回滚，因此应将中断的遍历视为未完成。 + +遍历期间保持命名空间、筛选条件和页面大小不变。历史还要求使用相同且显式指定的 `workflow_id` 和 `run_id`。句柄辅助方法会拒绝没有 `run_id` 的句柄。命名空间更改会在下一个请求前被拒绝。传入 `next_page_token` 可从同一选择的不透明继续位置恢复。不要解析、修改令牌，也不要将其用于其他筛选条件、命名空间或运行。遍历正在变化的工作流列表不会创建快照。 + +现有的 `await client.list_workflows(...)` 和 `await client.get_history(workflow_id, run_id, ...)` 仍然只返回**一页**。手动分页时，将返回的 `next_page_token` 传给下一次调用，并在最终令牌缺失、为 null 或为空时结束。部分页面或事件字典序列不是重放包。离线重放请使用 `await client.export_history(workflow_id, run_id)` 或 `await handle.export_history()`。 + +[已安装 SDK 2.17.2 / 原生 Server 3.9.2 的分页验证](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877331165)覆盖了筛选列表、所选运行的历史、不透明令牌恢复、提前关闭及命名空间更改拒绝，并已获得[独立验收](https://github.com/durable-workflow/sdk-python/pull/332#issuecomment-6877373099)。 diff --git a/i18n/zh-Hans/source-hashes.json b/i18n/zh-Hans/source-hashes.json index e93c4a06a01..27457e918dd 100644 --- a/i18n/zh-Hans/source-hashes.json +++ b/i18n/zh-Hans/source-hashes.json @@ -69,7 +69,7 @@ "platform-protocol-specs.md": "ba9c69adfca7fb4a0dd982464b0ca69dd5a21de1e340edbe23b075ec0fb0c35c", "polyglot/avro-value-protocol.md": "602e66c6288c1dd69d2b400c64e4739ad3a0493b5be269cee40f7848b11f260a", "polyglot/cancellation.md": "f676cd3ddb39246a0f580a1e16c83bc36d2ed9458b9e6009af4cc192d299ac62", - "polyglot/cli-python-parity.md": "acf1acbf15ca9cdf069154699c5fbf8c1d1fd3241a32d201ac10b8ec76c038be", + "polyglot/cli-python-parity.md": "70aa49ac5a4cb3413c4ed91cc0bdf232aa5c6726f3e1a4d406c4992658b7a1eb", "polyglot/cli-reference.md": "665c65192f9bfd41610f2aca54a66c2a3aa125e2d2b637d744d9c5f4243bee24", "polyglot/cli.mdx": "9dac7bb6b711737c9f16916ef462d85c642539f4b6e4a1bdac59320a09632c1f", "polyglot/cloud-control-plane.md": "bb375e598dd1afa3207171047fb81b0cb82c382ce535ab415cb09dc10f6d748e", @@ -84,7 +84,7 @@ "polyglot/polling-patterns.md": "30875099a23731c6c471b481a771378acc6ff57eed2fda4405a509057534c989", "polyglot/portable-worker-affinity.md": "40973c6a31a76845b4f95e9a505e68ad76abd5174bbdccf37993cdebc8904959", "polyglot/prerelease-history-migration.md": "a57f05f492228a8a67791f9152648a1e5f80856325b78777cf63b6ef49b7413c", - "polyglot/python.md": "57734052d6ffae8d660083626bf47fb7c392c492ab0581a8942401046bb25d38", + "polyglot/python.md": "5af6d33bf37899330c4f3026c819081b455a6d15eeeed3888ba05a013d6fa0dc", "polyglot/runtime-migration.md": "5a78713bb8cb74aea58f6d5d826400d968a405f69c6ff17fdf2f7decb1d14b71", "polyglot/rust-cloud-quickstart.md": "2303434fc9302a81a8381ad4836423ef9952eb3201a4574c432254e3cb68c5f3", "polyglot/rust.md": "602f61be5ec561f27845d4ca0657d71c8f6cc3f08e30d1f657bd62c23dc53314",