LocalStack Python Client

Warnings

• breaking The environment variables `LOCALSTACK_HOST` and `USE_SSL` are deprecated for configuring the LocalStack endpoint. They have been superseded by `AWS_ENDPOINT_URL`.
  Fix: Migrate your configuration to use `AWS_ENDPOINT_URL`. For example, set `os.environ['AWS_ENDPOINT_URL'] = 'http://localhost:4566'` before initializing the session.
• gotcha The `localstack-client` library acts as a wrapper for `boto3` to connect to LocalStack. It requires an *active and running* LocalStack instance to function. Without it, operations will fail.
  Fix: Ensure you have LocalStack installed (e.g., via `pip install localstack` and `localstack start`) and that the Docker container is running and accessible (typically on `localhost:4566`).
• gotcha When running applications (e.g., AWS Lambda functions, Docker containers) that need to connect to LocalStack, direct usage of `localhost` or `127.0.0.1` from within those containers might not work due to networking isolation. LocalStack itself only binds to IPv4 addresses.
  Fix: Use appropriate hostnames like `host.docker.internal` (Docker Desktop), or configure your Docker network and `AWS_ENDPOINT_URL` environment variable to point to the correct IP address or service name for LocalStack. Consult LocalStack's networking documentation for specific scenarios.
• gotcha The `localstack-client` is a thin wrapper. Compatibility with specific AWS service behaviors relies heavily on the underlying LocalStack version. New or changed AWS API features might not be supported if your LocalStack instance is outdated, or conversely, older LocalStack versions might have compatibility issues with newer AWS SDK (boto3) features.
  Fix: Regularly update your LocalStack Docker image (e.g., `localstack update docker-images` or by pulling the `latest` or a specific version tag for `localstack/localstack-pro` Docker image). Consult LocalStack's release notes and feature coverage for service-specific compatibility.
• gotcha LocalStack (the emulator) has undergone significant breaking changes in versions 3.0 and 4.0, including changes to configuration variables (e.g., removal of `AUTOSTART_UTIL_CONTAINERS`, changes to CloudPods client) and authentication methods (`localstack auth login` deprecated). These changes in the core LocalStack platform can indirectly affect how you set up your environment for the Python client.
  Fix: Refer to the LocalStack upgrade guides for versions 3.0 and 4.0 to understand necessary environment and configuration adjustments. Always ensure your LocalStack CLI is up-to-date (`pip install --upgrade localstack`).

Install

• pip install localstack-client Install with pip

Imports

• Session

  from localstack_client.session import Session

  While 'import localstack_client.session as boto3' is a common pattern for transparent usage, directly importing 'boto3' will bypass LocalStack and connect to real AWS services unless you manually configure the endpoint_url in every client instantiation.

Quickstart

This quickstart demonstrates how to initialize a session with localstack-client and interact with a local S3 service. It creates a bucket, uploads a file, lists buckets, and downloads the file, all against a running LocalStack instance. Remember that a LocalStack instance must be running and accessible before executing this code.

import os
from localstack_client.session import Session

# Ensure LocalStack is running before executing this code.
# If running LocalStack in Docker, make sure port 4566 is mapped.

# You can optionally set AWS_ENDPOINT_URL, but localstack-client defaults to localhost:4566
# os.environ['AWS_ENDPOINT_URL'] = 'http://localhost:4566'

session = Session()
s3_client = session.client('s3')

try:
    # Create a bucket (ensure it doesn't already exist)
    bucket_name = 'my-local-bucket-123'
    s3_client.create_bucket(Bucket=bucket_name)
    print(f"Bucket '{bucket_name}' created successfully.")

    # List buckets to verify
    response = s3_client.list_buckets()
    print("\nExisting buckets:")
    for bucket in response['Buckets']:
        print(f"- {bucket['Name']}")

    # Upload a file
    file_content = b'Hello from LocalStack!'
    file_name = 'hello.txt'
    s3_client.put_object(Bucket=bucket_name, Key=file_name, Body=file_content)
    print(f"\nFile '{file_name}' uploaded to '{bucket_name}'.")

    # Download the file
    download_response = s3_client.get_object(Bucket=bucket_name, Key=file_name)
    downloaded_content = download_response['Body'].read().decode('utf-8')
    print(f"\nDownloaded content: '{downloaded_content}'")

except Exception as e:
    print(f"An error occurred: {e}")