Docs/migration 1x to 2x - #655
Conversation
GitHub Actions
Error
31f5f5e to
162361b
Compare
GitHub Actions
Error
GitHub Actions
Inactive
GitHub Actions
Inactive
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
162361b to
e4ae074
Compare
GitHub Actions
Inactive
GitHub Actions
Inactive
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
GitHub Actions
Failure
GitHub Actions
Failure
Add docs/migration-1.x-to-2.x.md covering the 2.x breaking changes: typed per-operation error hierarchy, first-run serialize/deserialize round trip, removed config types and fields, construction-time config validation, and wait_for_condition changes; plus the optional should_complete feature. Also document the initial_state serdes requirement on WaitForConditionConfig.
e4ae074 to
2681198
Compare
GitHub Actions
Inactive
GitHub Actions
Inactive
Codex AI reviewFound one blocking documentation correctness issue. No runtime behavior changed; tests were not run under the read-only review constraint. Reviewed commit |
Claude AI reviewThis is a documentation PR: a v1→v2 migration guide plus a docstring expansion on Almost everything checks out: the error hierarchy and its package-root exports ( One confirmed finding (see inline): the "New in 2.x: Custom Completion Predicate" section documents an API that does not exist in this repository — Residual note: this is a docs-only change, so there are no code tests to add; correctness here means the documented API matches the shipped SDK. Reviewed commit |
There was a problem hiding this comment.
Is the idea to link this guide from the README the tagged guide from the 2.0 GitHub release notes?
The plugin interface also changed incompatibly between 1.x and 2.x. Hook signatures changed, enums moved, and InvocationEndInfo.status became required. The interface is experimental, so it may be out of scope for this guide? If so, a single sentence saying the experimental plugin API changed would still save plugin authors a surprise.
| | `BatchResult.throw_if_error()` now raises a typed error | Catch `ChildContextError` instead of `CallableRuntimeError`. | | ||
| | First-run serialize/deserialize round trip for `step`, child contexts, `map`/`parallel`, and `wait_for_condition` | Make custom `SerDes` round-trip safe: `deserialize(serialize(x)) == x`. Ensure `wait_for_condition` `initial_state` is serializable by the configured serdes. For a transient serdes failure, raise the new `RetryableSerDesError` (retries) instead of `SerDesError` (permanent). | | ||
| | `InvokeConfig.timeout` and `InvokeConfig.timeout_seconds` removed | Remove them. Enforce any timeout inside the invoked function or as a separate timer. | | ||
| | Removed `ItemBatcher`, `ItemsPerBatchUnit`, `BatchedInput`, `TerminationMode`, `StepFuture`, `MapConfig.item_batcher`, `ChildConfig.item_serdes` | Remove all uses. Replace `ChildConfig.item_serdes` with `ChildConfig.serdes`. | |
There was a problem hiding this comment.
Missing removed names. ChainedInvokeFailedToStartType, ChainedInvokeTimeoutType, and ChainedInvokeStopType were also removed from lambda_service.
| | First-run serialize/deserialize round trip for `step`, child contexts, `map`/`parallel`, and `wait_for_condition` | Make custom `SerDes` round-trip safe: `deserialize(serialize(x)) == x`. Ensure `wait_for_condition` `initial_state` is serializable by the configured serdes. For a transient serdes failure, raise the new `RetryableSerDesError` (retries) instead of `SerDesError` (permanent). | | ||
| | `InvokeConfig.timeout` and `InvokeConfig.timeout_seconds` removed | Remove them. Enforce any timeout inside the invoked function or as a separate timer. | | ||
| | Removed `ItemBatcher`, `ItemsPerBatchUnit`, `BatchedInput`, `TerminationMode`, `StepFuture`, `MapConfig.item_batcher`, `ChildConfig.item_serdes` | Remove all uses. Replace `ChildConfig.item_serdes` with `ChildConfig.serdes`. | | ||
| | `MapConfig` / `ParallelConfig` / `CompletionConfig` now validate at construction | Wrap construction in `try/except ValidationError` if you build configs from external input. | |
There was a problem hiding this comment.
This row covers two items from fdc952b but misses four.
BatchResult.allnow omits never-started branches.total_countand index iteration change for early-completed batches.- Custom
summary_generatoroutput is now stored under a"summary"key inside an SDK-owned envelope. It no longer replaces the payload. Code parsing summary payloads from execution history sees a different shape. max_concurrency=0andmin_successful=0now raiseValidationError.min_successful > totalis validated at the.map()or.parallel()call, not atCompletionConfig()construction. The row text says "at construction", which is only partly true.
| context.logger.error("%s: %s", err.type, err.message) | ||
| ``` | ||
|
|
||
| ## Serialize/Deserialize Round Trip |
There was a problem hiding this comment.
Missing a catch-path break. In 1.x, serdes failures raised ExecutionError. In 2.x they raise SerDesError, which inherits from DurableExecutionsError and not from ExecutionError. Existing except ExecutionError blocks silently stop catching serialization failures. Needs a table row.
| checkpointed decision and never re-invokes it. | ||
| - New exports: `complete_batch`, `continue_batch`, `CompletionStatus`, | ||
| `CompletionDecision`, `CompletionOutcome`, `CompletionItemStatus`, | ||
| `BatchItemStatus`. |
2 participants
Issue #, if available: N/A
Description of changes:
Migration guide for python v2
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.