Skip to content

Bug: Tracer's BaseProvider declares in_subsegment_async as a synchronous context manager #8365

Closed
#8367
Closed
Bug: Tracer's BaseProvider declares in_subsegment_async as a synchronous context manager#8365
#8367
Labels
bugSomething isn't working

Description

@tibbe
tibbe
opened on Aug 5, 2026

Expected Behaviour

The type checker accepts async with tracer.provider.in_subsegment_async(...).

The abstract method in_subsegment_async in
aws_lambda_powertools/tracing/base.py returns an asynchronous context
manager. Its annotation shows this:
-> AbstractAsyncContextManager[BaseSegment]. The declaration does not
have the @contextmanager decorator.

Current Behaviour

The abstract method has the @contextmanager decorator. Its return
annotation is Generator[BaseSegment, None, None]. These declarations
tell the type checker that the method returns a synchronous context
manager.

This declaration does not agree with three parts of Powertools:

  1. Tracer._decorate_async_function enters the result with async with.
  2. The capture_method documentation shows in_subsegment_async with
    async with as the escape hatch for concurrent asynchronous functions.
  3. The default provider is the recorder from aws-xray-sdk. Its
    in_subsegment_async returns an asynchronous context manager.

Thus correct code causes a type error. The user must add a cast to
remove the error.

Code snippet

from aws_lambda_powertools import Tracer

tracer = Tracer()


async def handler_body() -> None:
    async with tracer.provider.in_subsegment_async(name="## example"):
        ...

mypy reports:

error: "_GeneratorContextManager[BaseSegment, None, None]" has no attribute "__aenter__"  [attr-defined]
error: "_GeneratorContextManager[BaseSegment, None, None]" has no attribute "__aexit__"; maybe "__exit__"?  [attr-defined]

Possible Solution

Change the declaration in BaseProvider:

  1. Remove the @contextmanager decorator from the abstract method.
  2. Change the return annotation to
    AbstractAsyncContextManager[BaseSegment].

This change makes the interface agree with _decorate_async_function,
with the documentation, and with the shipped X-Ray provider.

Steps to Reproduce

  1. Save the code snippet above to a file.
  2. Run mypy on the file.
  3. See the two errors above.

Powertools for AWS Lambda (Python) version

3.22.0

AWS Lambda function runtime

3.14

Packaging format used

PyPi

Debugging logs

Activity
  1. tibbe
    added 
    bugSomething isn't working
     
    triagePending triage from maintainers
     on Aug 5, 2026
  2. github-project-automation
    moved this to Triage in  Powertools for AWS Lambda (Python)on Aug 5, 2026
  3. github-project-automation
    added this to  Powertools for AWS Lambda (Python)on Aug 5, 2026
  4. vishwakt commented on Aug 8, 2026 
    @vishwakt
    vishwakt
    on Aug 8, 2026
    Contributor
    Confirmed. Tracer._decorate_async_function enters in_subsegment_async with async with, and the default X-Ray provider returns an async context manager, so the abstract declaration in BaseProvider is out of sync with both. I opened #8367 with the fix proposed here: drop the @contextmanager decorator and annotate the return as AbstractAsyncContextManager[BaseSegment]. Annotation only, no runtime change. Verified the mypy errors from the snippet are gone and tests pass.
  5. leandrodamascena commented on Aug 10, 2026 
    @leandrodamascena
    leandrodamascena
    on Aug 10, 2026
    Contributor
    Hey @tibbe, thanks for the really clear report, and @vishwakt thanks for jumping on it with a PR.
    

    I reproduced it and you're right on all three points. base.py declares in_subsegment_async with @contextmanager and a Generator return type, while:
    

      

    1. we ourselves enter it with async with in tracer.py:609
      2. 

    2. our own docs show async with as the escape hatch (tracer.py:530)
      3. 

    3. the shipped X-Ray provider returns AsyncSubsegmentContextManager, which has __aenter__
      4. 

    

    So correct code gets a type error and people have to add a cast to silence it. That's a genuine bug in our annotation.
    

    I applied the proposed fix locally to check it and it holds up:
    

      

    • mypy on your snippet goes clean
      • 

    • async with still works at runtime
      • 

    • tracer tests pass (44)
      • 

    • mypy clean across the whole tracing module
      • 

    

    And it's not a breaking change. The @contextmanager was on an abstract method with an empty body, so it never did anything at runtime. This is annotation only.
    

    @vishwakt your PR #8367 looks good to me, and putting AbstractAsyncContextManager under TYPE_CHECKING is nicer than what I had. One small thing to double check: contextmanager is still used by the sync in_subsegment just above, so that import needs to stay. Looks like it does in your diff, just confirming ruff didn't flag anything.
    

    Thanks both of you, this was an easy one to review because the report was so precise.
  6. leandrodamascena
    added a commit that references this issue on Aug 10, 2026
    fix(tracer): declare in_subsegment_async as an async context manager (#…
    ad15c7a
  7. leandrodamascena
    closed this as completedin #8367on Aug 10, 2026
  8. github-project-automation
    moved this from Triage to Coming soon in  Powertools for AWS Lambda (Python)on Aug 10, 2026
  9. powertools-for-aws-oss-automation
    removed 
    triagePending triage from maintainers
     on Aug 10, 2026
  10. powertools-for-aws-oss-automation commented on Aug 10, 2026 
    @powertools-for-aws-oss-automation
    powertools-for-aws-oss-automationbot
    on Aug 10, 2026 – with Powertools for AWS - OSS Automation
    Warning
    This issue is now closed. Please be mindful that future comments are hard for our team to see.
    
If you need more assistance, please either reopen the issue, or open a new issue referencing this one.
    
If you wish to keep having a conversation with other community members under this issue feel free to do so.
    

    
 
  11. powertools-for-aws-oss-automation
    added 
    pending-releaseFix or implementation already in dev waiting to be released
     on Aug 10, 2026
  12. github-actions commented on Aug 10, 2026 
    @github-actions
    github-actionsbot
    on Aug 10, 2026 – with GitHub Actions
    Contributor
    This is now released under 3.34.0 version!
  13. github-actions
    removed 
    pending-releaseFix or implementation already in dev waiting to be released
     on Aug 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Metadata
Metadata
Assignees
No one assigned
    Labels
    bugSomething isn't working
    Type
    No type
    Projects
    Milestone
    No milestone
    Relationships
    None yet
    Development
    No branches or pull requests
    Issue actions