{"id":6282,"library":"types-aws-xray-sdk","title":"Typing Stubs for AWS X-Ray SDK for Python","description":"This package provides static type annotations (stubs) for the `aws-xray-sdk` Python library. It enables type checkers like MyPy, Pyright, or Pylance to perform static analysis and provide better autocompletion and error detection for code using `aws-xray-sdk`. It is part of the `typeshed` project and receives regular updates, with the current version targeting `aws-xray-sdk==2.15.*`.","status":"active","version":"2.15.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","aws","xray","typeshed","static analysis","observability"],"install":[{"cmd":"pip install types-aws-xray-sdk","lang":"bash","label":"Install stubs"},{"cmd":"pip install aws-xray-sdk types-aws-xray-sdk mypy","lang":"bash","label":"Install runtime, stubs, and type checker"}],"dependencies":[{"reason":"Provides runtime functionality that these stubs type-check. Must be installed separately for application execution.","package":"aws-xray-sdk","optional":false},{"reason":"A common type checker used to leverage these stubs for static analysis.","package":"mypy","optional":true}],"imports":[{"note":"Stubs provide type hints for imports from the 'aws-xray-sdk' runtime library, not for imports directly from 'types-aws-xray-sdk'.","symbol":"XRayRecorder","correct":"from aws_xray_sdk.core import xray_recorder"},{"note":"The 'patch_all' function is part of the runtime SDK and is used for automatic instrumentation, type-checked by these stubs.","symbol":"patch_all","correct":"from aws_xray_sdk.core import patch_all"}],"quickstart":{"code":"import os\nfrom aws_xray_sdk.core import xray_recorder, patch_all\nfrom aws_xray_sdk.core.segments import Segment\n\n# Install the X-Ray daemon locally or ensure it's available\n# Docs: https://docs.aws.amazon.com/xray/latest/devguide/xray-daemon.html\n\n# Configure X-Ray Recorder (example values)\nxray_recorder.configure(\n    service='MyApplication',\n    sampling=False, # For simplicity in this example\n    context_missing='LOG_ERROR',\n    daemon_address=os.environ.get('AWS_XRAY_DAEMON_ADDRESS', '127.0.0.1:2000')\n)\n\n# Apply patches for supported libraries (e.g., boto3, requests)\npatch_all()\n\ndef my_traced_function(item_id: str) -> str:\n    # Type checking will ensure 'begin_segment' returns a Segment\n    with xray_recorder.in_segment('MyFunctionSegment') as segment: # type: Segment\n        segment.put_annotation('item_id', item_id)\n        print(f\"Processing item {item_id} within segment {segment.id}\")\n        return f\"Processed {item_id}\"\n\nif __name__ == '__main__':\n    # Example usage - this code will run and potentially send traces\n    # For type checking, save this as `app.py` and run `mypy app.py`\n    result = my_traced_function(\"12345\")\n    print(result)\n\n    # Demonstrate a type error (uncomment and run mypy to see it)\n    # xray_recorder.configure(service=123) # Expected str, got int\n","lang":"python","description":"This quickstart demonstrates how to use the underlying `aws-xray-sdk` library, which `types-aws-xray-sdk` provides type hints for. It includes configuration, patching, and a basic traced function using a context manager. To verify the stubs, you would typically run a type checker like MyPy against this code. The commented-out line shows an example of a type error that `types-aws-xray-sdk` would help detect. Remember that for actual tracing, the AWS X-Ray daemon must be running and accessible."},"warnings":[{"fix":"For new development, consider migrating to OpenTelemetry-based instrumentation for AWS X-Ray. For existing applications, continue using `aws-xray-sdk` and `types-aws-xray-sdk` with the understanding that only critical bug fixes and security updates will be provided for the runtime library.","message":"The AWS X-Ray SDKs and Daemon (the runtime library this package stubs) entered maintenance mode on February 25, 2026. AWS recommends migrating to AWS Distro for OpenTelemetry (ADOT) or OpenTelemetry Instrumentation for new applications to ensure continued feature updates and broader community support.","severity":"breaking","affected_versions":"aws-xray-sdk versions from 2.15.0 onwards, and by extension, types-aws-xray-sdk versions for those releases."},{"fix":"Always install the runtime library (`pip install aws-xray-sdk`) in your application's environment in addition to the type stubs (`pip install types-aws-xray-sdk`).","message":"This package (`types-aws-xray-sdk`) contains only type stubs and provides no runtime code or functionality. It must be installed alongside the actual `aws-xray-sdk` library for any application execution. Installing only the stubs will lead to `ModuleNotFoundError` at runtime if `aws-xray-sdk` is not also present.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor your type checker's output. If issues arise, ensure your `aws-xray-sdk` and `types-aws-xray-sdk` versions are as close as possible, ideally with the `types-` package's major.minor.patch matching the runtime library. Pinning stub versions (e.g., `types-aws-xray-sdk==X.Y.Z.*`) can provide stability, but may delay benefits from stub improvements.","message":"The versioning of `types-` packages from Typeshed (e.g., `2.15.0.20260408`) typically indicates compatibility with the corresponding major/minor runtime version (e.g., `aws-xray-sdk==2.15.*`). However, there's no strict guarantee of perfect alignment or that patch versions will always be in sync. A mismatch between the stub version and the runtime library version can lead to incorrect type-checking results or `mypy` errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}