{"id":9309,"library":"smithy-aws-core","title":"Smithy AWS Core","description":"Smithy AWS Core provides foundational components for building AWS service clients using the Smithy framework in Python. It encapsulates AWS-specific logic for concerns like authentication (signing requests), endpoint resolution, and HTTP transport. Currently at version 0.5.0, it is part of the broader smithy-python ecosystem, meaning API adjustments are expected as it approaches a 1.0 stable release.","status":"active","version":"0.5.0","language":"en","source_language":"en","source_url":"https://github.com/smithy-lang/smithy-python/tree/develop/packages/smithy-aws-core/","tags":["aws","smithy","code-generation","cloud","sdk","api-client"],"install":[{"cmd":"pip install smithy-aws-core","lang":"bash","label":"Install smithy-aws-core"}],"dependencies":[{"reason":"Provides core Smithy runtime components and types, which smithy-aws-core extends.","package":"smithy-python","optional":false},{"reason":"Used for AWS credential and session management within the Smithy Python ecosystem.","package":"aiobotocore","optional":false}],"imports":[{"symbol":"AwsUserConfig","correct":"from smithy_aws_core.config import AwsUserConfig"},{"symbol":"AwsSigner","correct":"from smithy_aws_core.signing import AwsSigner"},{"note":"AwsHttpClient is an abstract base class; concrete implementations like aiohttp.AiohttpHttpClient are typically used via generated clients.","symbol":"AwsHttpClient","correct":"from smithy_aws_core.http import AwsHttpClient"},{"symbol":"AwsEndpointResolver","correct":"from smithy_aws_core.endpoint import AwsEndpointResolver"}],"quickstart":{"code":"import asyncio\nimport os\nimport datetime\nfrom smithy_aws_core.config import AwsUserConfig\nfrom smithy_aws_core.signing import AwsSigner\nfrom smithy_python.types import Credentials, UnresolvedUrl\nfrom smithy_python.http import HttpRequest\n\nasync def main():\n    # In a real application, consider using aiobotocore.session.get_session()\n    # for robust credential discovery. For this quickstart, we use environment variables.\n    aws_access_key_id = os.environ.get(\"AWS_ACCESS_KEY_ID\", \"AKIAIOSFODNN7EXAMPLE\")\n    aws_secret_access_key = os.environ.get(\"AWS_SECRET_ACCESS_KEY\", \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\")\n    aws_session_token = os.environ.get(\"AWS_SESSION_TOKEN\", None)\n\n    if aws_access_key_id == \"AKIAIOSFODNN7EXAMPLE\" or aws_secret_access_key == \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\":\n        print(\"Warning: Using dummy AWS credentials. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables for real usage.\")\n\n    credentials = Credentials(\n        access_key_id=aws_access_key_id,\n        secret_access_key=aws_secret_access_key,\n        token=aws_session_token\n    )\n\n    config = AwsUserConfig(\n        region=\"us-east-1\",\n        credentials=credentials,\n        endpoint_url=UnresolvedUrl(\"https://s3.us-east-1.amazonaws.com\") # Example S3 endpoint\n    )\n    print(f\"\\nCreated AWS User Config for region: {config.region}\")\n\n    # Demonstrate an AWS Signer\n    signer = AwsSigner(service_id=\"s3\", config=config) # 's3' is the service ID for S3\n    print(f\"Created AWS Signer for service: {signer.service_id}\")\n\n    # Prepare a dummy HTTP request to be signed\n    request = HttpRequest(\n        method=\"GET\",\n        url=\"https://s3.us-east-1.amazonaws.com/my-bucket\", # Example URL, typically resolved by client\n        headers={\n            \"Host\": \"s3.us-east-1.amazonaws.com\",\n            \"User-Agent\": \"smithy-python-quickstart/1.0\"\n        },\n        body=b\"\"\n    )\n\n    # Sign the request\n    # Note: The 'url' in HttpRequest must be a concrete string, not UnresolvedUrl, for signing.\n    # In a real client, endpoint resolution would convert UnresolvedUrl to a string.\n    signed_request = await signer.sign(request, credentials, datetime.datetime.now(datetime.timezone.utc))\n\n    print(f\"\\n--- Signed Request Details ---\")\n    print(f\"Method: {signed_request.method}\")\n    print(f\"URL: {signed_request.url}\")\n    print(f\"Headers: {signed_request.headers}\")\n    if 'Authorization' in signed_request.headers:\n        print(f\"Authorization header present (truncated): {signed_request.headers['Authorization'][:50]}...\")\n    else:\n        print(\"Authorization header NOT found.\")\n\nasyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to initialize core Smithy AWS components like `AwsUserConfig` for regional and credential settings, and how to use `AwsSigner` to sign a basic HTTP request, which is a fundamental step in interacting with AWS services. It uses environment variables for AWS credentials."},"warnings":[{"fix":"Refer to the `smithy-python` repository's changelog or release notes for specific breaking changes when upgrading.","message":"Smithy AWS Core is currently pre-1.0 (version 0.5.0). This means its API is not yet stable, and breaking changes may occur in minor versions without deprecation cycles.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Utilize `aiobotocore.session.get_session()` to retrieve `Credentials` objects compatible with `smithy-aws-core` components, or convert credentials from other sources to `smithy_python.types.Credentials`.","message":"AWS credential and session management within the Smithy Python ecosystem heavily relies on 'aiobotocore'. If you are accustomed to 'boto3', you might need to adapt your credential provider to work with 'aiobotocore' sessions.","severity":"gotcha","affected_versions":"all"},{"fix":"For making actual HTTP calls, rely on a generated Smithy client, which will provide a concrete HTTP client implementation, or instantiate a specific implementation like `smithy_python.http.aiohttp.AiohttpHttpClient`.","message":"Direct instantiation of abstract base classes like `AwsHttpClient` is not typically the way to make HTTP requests. These components are usually integrated into generated Smithy clients.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you have installed the necessary packages: `pip install smithy-aws-core smithy-python aiobotocore`. Verify your virtual environment is correctly activated.","cause":"The 'smithy-aws-core' library or its core dependencies ('smithy-python', 'aiobotocore') are not installed, or your virtual environment is not active.","error":"ModuleNotFoundError: No module named 'smithy_aws_core.config'"},{"fix":"Always create an instance of `AwsUserConfig` (specifying region, credentials, etc.) and pass it as the `config` argument to `smithy-aws-core` component constructors.","cause":"When initializing components like `AwsSigner` or `AwsEndpointResolver`, an `AwsUserConfig` (or similar configuration object) is a required argument.","error":"TypeError: __init__ missing 1 required positional argument: 'config'"},{"fix":"Ensure that AWS credentials are available in your environment (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` environment variables), in a shared credentials file, or explicitly passed as a `smithy_python.types.Credentials` object.","cause":"The `credentials` parameter provided to a component (e.g., `AwsUserConfig`, `AwsSigner`) was `None`, indicating that AWS credentials could not be loaded or were not provided.","error":"TypeError: argument 'credentials': Expected Credentials, got NoneType"}]}