Skip to content

AGENTS.md

Latest commit

 

History

History
92 lines (76 loc) · 5.8 KB

AGENTS.md

File metadata and controls

92 lines (76 loc) · 5.8 KB
Raw

AWS Durable Execution SDK for Python - Agent Guide

This repository contains the AWS Durable Execution SDK for Python and its companion packages, used to author AWS Lambda durable functions.

Use the developer guide, not this file, for APIs

Do not rely on this file for method signatures, configuration objects, or code examples. The canonical reference is the AWS Durable Execution SDK Developer Guide, which is maintained alongside SDK releases and covers TypeScript, Python, and Java. Key sections:

Topic Link
Key concepts and quickstart https://docs.aws.amazon.com/durable-execution/getting-started/key-concepts/
Steps https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/step/
Waits https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/wait/
Wait for condition (polling) https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/wait-for-condition/
Callbacks and wait for callback https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/callback/
Invoke (function chaining) https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/invoke/
Parallel https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/parallel/
Map https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/map/
Child contexts https://docs.aws.amazon.com/durable-execution/sdk-reference/operations/child-context/
Errors and retries https://docs.aws.amazon.com/durable-execution/sdk-reference/error-handling/errors/
Serialization https://docs.aws.amazon.com/durable-execution/sdk-reference/state/serialization/
Logging and plugins https://docs.aws.amazon.com/durable-execution/sdk-reference/observability/logging/
Python language guide https://docs.aws.amazon.com/durable-execution/sdk-reference/languages/python/
Testing (local runner, assertions) https://docs.aws.amazon.com/durable-execution/testing/
Best practices (determinism, idempotency, state) https://docs.aws.amazon.com/durable-execution/patterns/best-practices/

For Lambda service topics such as deployment, infrastructure as code, invocation, IAM permissions, and quotas, see the Lambda durable functions guide.

Critical rules: the replay model

Durable functions use checkpoint and replay. After a wait, failure, or resume, code re-runs from the beginning. Completed steps return their checkpointed results without re-executing, and code outside steps runs again on every replay. This implies four rules:

  1. Code outside steps must be deterministic. Wrap timestamps, random values, UUID generation, API calls, and any other non-deterministic work in a step.
  2. Never call durable operations inside a step. Use a child context to group operations.
  3. Closure mutations inside steps are lost on replay. Return values from steps instead of mutating enclosing scope.
  4. Side effects outside steps repeat on every replay. Put side effects in steps. context.logger is the exception: it is replay-aware and safe anywhere.

See Determinism and Replay for worked examples.

Security-sensitive parsing

  • Do not use yaml.load() or yaml.load_all(), including with Loader= arguments or suppression comments. CodeQL and security scanners flag the unsafe call form even when the loader subclasses yaml.SafeLoader.
  • Use yaml.safe_load() or yaml.safe_load_all() for plain YAML.
  • For CloudFormation or SAM templates with short-form tags such as !Ref, !Sub, !GetAtt, or !If, use a yaml.SafeLoader subclass with explicit tag constructors so the tags are preserved.
  • For custom safe loaders, instantiate the loader directly, call get_single_data() or the equivalent multi-document API, and call dispose() in a finally block. This matches what yaml.safe_load() does internally while preserving custom tag support.
  • Before finishing YAML-related changes, check Python code for unsafe call forms: rg -n --glob '*.py' "yaml\\.load\\b|yaml\\.load_all\\b|from yaml import load\\b|from yaml import load_all\\b" .

Testing Requirements

All changes MUST include related tests. At minimum, include unit tests. Include e2e integration tests (in the tests/e2e/ directory) when the change affects cross-component behavior, public API surfaces, or end-to-end workflows. For isolated bug fixes where a unit test alone sufficiently covers the fix, integration tests are not required.

Do NOT add or modify conformance tests without coordinating with the team. Conformance test requirements and the runner live in a separate repository (aws-durable-execution-conformance-tests). If a change warrants a new conformance test, note it in the PR description or open an issue in that repository.

Working in this repository

  • Packages live under packages/: the core SDK (aws-durable-execution-sdk-python), the testing library (aws-durable-execution-sdk-python-testing), the OpenTelemetry plugin (aws-durable-execution-sdk-python-otel), and examples (aws-durable-execution-sdk-python-examples).
  • Read CONTRIBUTING.md before making changes. Use hatch for all tests, type checks, and formatting (for example hatch run dev-core:test, hatch run dev-core:typecheck, and hatch fmt --check from a package directory).
  • When the developer guide and the installed SDK source disagree, trust the source in this repository and report the discrepancy.