From 86b254898948250f639c22871ce534235a8da11f Mon Sep 17 00:00:00 2001 From: Leandro Damascena Date: Sat, 14 Nov 2026 13:01:07 +0000 Subject: [PATCH] chore(ci): regenerate the agent skill references in the release instead of after every docs merge --- .../references/idempotency.md | 22 ++++++-- .github/workflows/agent_skill_references.yml | 52 ------------------- .github/workflows/publish_v3_layer.yml | 5 +- AGENTS.md | 4 +- scripts/build_agent_skill_references.py | 4 +- 5 files changed, 26 insertions(+), 61 deletions(-) delete mode 100644 .github/workflows/agent_skill_references.yml diff --git a/.agents/skills/building-lambda-functions-with-powertools-python/references/idempotency.md b/.agents/skills/building-lambda-functions-with-powertools-python/references/idempotency.md index f097dcf1868..a6f47911eb9 100644 --- a/.agents/skills/building-lambda-functions-with-powertools-python/references/idempotency.md +++ b/.agents/skills/building-lambda-functions-with-powertools-python/references/idempotency.md @@ -484,6 +484,10 @@ When using the `output_serializer` parameter, the data will continue to be store Function returns must be annotated with a single type, optionally wrapped in `Optional` or `Union` with `None`. +Inference supports `from __future__ import annotations`. Define the output model at module scope so its name can be resolved when the function is decorated. +If the model is local to another function, pass an explicit serializer instance, such as `PydanticSerializer(model=OrderOutput)` or `DataclassSerializer(model=OrderOutput)`. +Containers such as `list[OrderOutput]` are not supported by these model serializers and raise `IdempotencyModelTypeError`. + **Pydantic** Use `PydanticSerializer` to automatically serialize what's retrieved from the persistent storage based on the return type annotated. @@ -491,6 +495,8 @@ Use `PydanticSerializer` to automatically serialize what's retrieved from the pe **Inferring via the return type** ```python +from __future__ import annotations + import os from aws_lambda_powertools.utilities.idempotency import ( @@ -601,6 +607,8 @@ def lambda_handler(event: dict, context: LambdaContext): **Inferring via the return type** ```python +from __future__ import annotations + import os from dataclasses import dataclass @@ -1109,12 +1117,16 @@ This means that if an invocation expired during execution, it will be quickly ex ### Handling exceptions -There are two failure modes that can cause new invocations to execute your code again despite having the same payload: +There are three failure modes that can cause new invocations to execute your code again despite having the same payload: * **Unhandled exception**. We catch them to delete the idempotency record to prevent inconsistencies, then propagate them. * **Persistent layer errors**. We raise **`IdempotencyPersistenceLayerError`** for any persistence layer errors _e.g., remove idempotency record_. +* **Response that can't be serialized**. When your function returns a value the output serializer or JSON can't convert _e.g., `datetime`, `set`, `bytes`_, we try to delete the in progress record, then raise **`IdempotencyPersistenceLayerError`**. + The next invocation runs your code again once that record is deleted, or after it expires if the deletion fails. + +If saving the response fails after it was serialized, we keep the record, as the write could have landed. New invocations return the saved response or wait until the in progress record expires. -If an exception is handled or raised **outside** your decorated function, then idempotency will be maintained. +Apart from a response that can't be serialized, if an exception is handled or raised **outside** your decorated function, then idempotency will be maintained. ```python title="working_with_exceptions.py" import os @@ -1136,7 +1148,7 @@ config = IdempotencyConfig() @idempotent_function(data_keyword_argument="data", config=config, persistence_store=persistence_layer) def call_external_service(data: dict): - # Any exception raised will lead to idempotency record to be deleted + # Any exception raised, or a response that can't be serialized, will lead to idempotency record to be deleted result: requests.Response = requests.post( "https://jsonplaceholder.typicode.com/comments/", json=data, @@ -2306,6 +2318,8 @@ For example, the `_put_record` method needs to raise an exception if a non-expir ### Manipulating the Idempotent Response +With a DynamoDB composite key, `DataRecord.idempotency_key` contains the sort key value identifying the operation, rather than the shared static partition key. Replayed records use this same key for local caching. + You can set up a `response_hook` in the `IdempotentConfig` class to manipulate the returned data when an operation is idempotent. The hook function will be called with the current deserialized response object and the Idempotency record. **Using an Idempotent Response Hook** @@ -2328,7 +2342,7 @@ from aws_lambda_powertools.utilities.typing import LambdaContext logger = Logger() def my_response_hook(response: dict, idempotent_data: DataRecord) -> dict: - # Return inserted Header data into the Idempotent Response + # With a composite key, this is the operation's sort key, not the shared partition key response["x-idempotent-key"] = idempotent_data.idempotency_key # expiry_timestamp can be None so include if set diff --git a/.github/workflows/agent_skill_references.yml b/.github/workflows/agent_skill_references.yml deleted file mode 100644 index 59041e6fa8f..00000000000 --- a/.github/workflows/agent_skill_references.yml +++ /dev/null @@ -1,52 +0,0 @@ -name: Regenerate agent skill references - -# PROCESS -# -# 1. Runs on every push to develop that touches the docs, the examples or the generator -# 2. Regenerates .agents/skills/*/references from the docs -# 3. Opens a PR with the result when anything changed; duplicates with the same title are closed by the action -# -# This keeps contributors out of it: a docs PR changes docs, the references catch up after the merge. - -on: - push: - branches: - - develop - paths: - - "docs/**" - - "examples/**" - - "scripts/build_agent_skill_references.py" - workflow_dispatch: {} - -env: - TEMP_BRANCH_PREFIX: "ci-agent-skill" - PULL_REQUEST_TITLE: "chore(docs): regenerate the agent skill references" - FILES_TO_COMMIT: ".agents/skills/building-lambda-functions-with-powertools-python/references" - -permissions: - contents: read - -jobs: - regenerate: - if: github.repository == 'aws-powertools/powertools-lambda-python' - concurrency: - group: agent-skill-references - runs-on: ubuntu-latest - permissions: - contents: write # create temporary branch with the references - pull-requests: write # create PR - steps: - - name: Checkout repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - fetch-depth: 0 - - name: Regenerate references - run: python3 scripts/build_agent_skill_references.py - - name: Create PR - id: create-pr - uses: ./.github/actions/create-pr - with: - files: ${{ env.FILES_TO_COMMIT }} - temp_branch_prefix: ${{ env.TEMP_BRANCH_PREFIX }} - pull_request_title: ${{ env.PULL_REQUEST_TITLE }} - github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/publish_v3_layer.yml b/.github/workflows/publish_v3_layer.yml index 08a76dae0ba..689dab9256c 100644 --- a/.github/workflows/publish_v3_layer.yml +++ b/.github/workflows/publish_v3_layer.yml @@ -277,6 +277,9 @@ jobs: - name: Replace layer versions in documentation run: ./layer_v3/scripts/update_layer_arn_v3.sh ${{ inputs.layer_documentation_version }} + # The agent skill references are generated from the docs; regenerate them here so the release PR carries both + - name: Regenerate agent skill references + run: python3 scripts/build_agent_skill_references.py # NOTE: It felt unnecessary creating yet another PR to update changelog w/ latest tag # since this is the only step in the release where we update docs from a temp branch - name: Update changelog with latest tag @@ -285,7 +288,7 @@ jobs: id: create-pr uses: ./.github/actions/create-pr with: - files: "docs/index.md docs/getting-started/install.md docs/includes/_layer_homepage_arm64.md docs/includes/_layer_homepage_x86.md examples CHANGELOG.md" + files: "docs/index.md docs/getting-started/install.md docs/includes/_layer_homepage_arm64.md docs/includes/_layer_homepage_x86.md examples CHANGELOG.md .agents/skills/building-lambda-functions-with-powertools-python/references" temp_branch_prefix: "ci-layer-docs" pull_request_title: "chore(ci): layer docs update" github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/AGENTS.md b/AGENTS.md index b918d6a21c1..743db8050a0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,7 +18,7 @@ make mypy # static typing, must pass uv run pytest tests/unit tests/functional/ # fast loop for one utility make test # full unit + functional + performance, what CI runs make pr # everything CI checks, run it before opening the PR -make agent-skill # optional: regenerate .agents/skills/*/references after changing docs/; pre-commit does it, and CI does it after merge +make agent-skill # optional: regenerate .agents/skills/*/references after changing docs/; pre-commit does it, and the release does it ``` Do not run the full suite with `pytest -n auto`; collection differs between workers and it fails for reasons unrelated to your change. @@ -58,6 +58,6 @@ Do not run the full suite with `pytest -n auto`; collection differs between work | Sample events | `tests/events/` | | Docs and examples | `docs//.md`, `examples//src/` | | Project premises | `docs/adr/` | -| Agent skill for library users | `.agents/skills/` (the `references/` folder is generated from `docs/` by `scripts/build_agent_skill_references.py`, and regenerated by CI after every docs merge; do not edit it or use it as a source, change `docs/`) | +| Agent skill for library users | `.agents/skills/` (the `references/` folder is generated from `docs/` by `scripts/build_agent_skill_references.py`, and regenerated on every release; do not edit it or use it as a source, change `docs/`) | | Layer build | `layer_v3/` | | Maintainer process | [MAINTAINERS.md](MAINTAINERS.md), [docs/maintainers.md](docs/maintainers.md) | diff --git a/scripts/build_agent_skill_references.py b/scripts/build_agent_skill_references.py index 4c75a221830..176a9bd3b1b 100644 --- a/scripts/build_agent_skill_references.py +++ b/scripts/build_agent_skill_references.py @@ -6,8 +6,8 @@ ``--check`` to report whether the committed references are out of date. Contributors do not need to run this: the pre-commit hook regenerates on docs changes for -those who have it installed, and a workflow regenerates on every push to ``develop`` that -touches the docs, opening a PR with the result. +those who have it installed, and the release workflow regenerates the references in the same +PR that updates the layer version in the docs. """ from __future__ import annotations