Clients, Sessions & Configuration

Every AWS API call goes through a client instance; here are the side-by-side patterns for constructing, configuring, and reusing them.

Create a Service Client

Construct a low-level client for a service; reuse it for every call.

# --- Python (boto3) ---
import boto3
s3 = boto3.client("s3", region_name="us-east-1")
print(type(s3).__name__)  # S3Client

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: "us-east-1" });

Set an Explicit Region

Clients need a region to construct the endpoint URL; pass it during client creation.

# --- Python (boto3) ---
import boto3
client = boto3.client("dynamodb", region_name="eu-west-1")

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({ region: "eu-west-1" });

Named Profile / Session

Use a named AWS profile (from ~/.aws/config) or a boto3 Session to scope credentials and region.

# --- Python (boto3) ---
import boto3
session = boto3.Session(profile_name="dev-account")
s3 = session.client("s3")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({ profile: "dev-account" });

Override the Endpoint URL

Point the client at a custom endpoint (local testing, private endpoints, or S3-like services).

# --- Python (boto3) ---
import boto3
s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:9000"
)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
    endpoint: "http://localhost:9000",
    region: "us-east-1"
});

Reuse One Client Across Calls

Create a client at module level or in a singleton; do not create a new client per request.

# --- Python (boto3) ---
# clients.py
import boto3
s3_client = boto3.client("s3", region_name="us-east-1")
 
# app.py
from clients import s3_client
s3_client.list_buckets()

// --- TypeScript (AWS SDK v3) ---
// clients.ts
import { S3Client } from "@aws-sdk/client-s3";
export const s3 = new S3Client({ region: "us-east-1" });
 
// app.ts
import { s3 } from "./clients";
import { ListBucketsCommand } from "@aws-sdk/client-s3";
await s3.send(new ListBucketsCommand({}));

Configure Timeouts

Set socket connect and read timeouts to avoid hanging indefinitely on slow networks.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(
    connect_timeout=5,
    read_timeout=30
)
s3 = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { NodeHttpHandler } from "@smithy/node-http-handler";
const s3 = new S3Client({
    requestHandler: new NodeHttpHandler({
        connectionTimeout: 5_000,
        socketTimeout: 30_000
    })
});

Max Pool Connections / Sockets

Limit or increase the number of concurrent socket connections to AWS services.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(max_pool_connections=50)
s3 = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { NodeHttpHandler } from "@smithy/node-http-handler";
const s3 = new S3Client({
    requestHandler: new NodeHttpHandler({
        maxSockets: 50
    })
});

Set Retry Mode + Attempts

Configure automatic retry behavior with exponential backoff; choose standard or adaptive mode.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(
    retries={"mode": "standard", "max_attempts": 5}
)
client = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
    maxAttempts: 5
});

Default Region from Env

Omit the region argument to use AWS_REGION or AWS_DEFAULT_REGION environment variables.

# --- Python (boto3) ---
import boto3
# Reads AWS_REGION or AWS_DEFAULT_REGION
client = boto3.client("s3")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
// Reads AWS_REGION or AWS_DEFAULT_REGION
const s3 = new S3Client({});

Per-Call Credentials Override

Pass explicit credentials on individual API calls instead of relying on the default chain.

# --- Python (boto3) ---
import boto3
client = boto3.client("s3")
client.list_buckets(
    aws_access_key_id="AKIA...",
    aws_secret_access_key="..."
)

// --- TypeScript (AWS SDK v3) ---
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
const s3 = new S3Client({});
await s3.send(new ListBucketsCommand({}), {
    credentials: {
        accessKeyId: "AKIA...",
        secretAccessKey: "..."
    }
});

Inspect Resolved Region/Endpoint

Read the client's resolved configuration after construction to verify region or endpoint.

# --- Python (boto3) ---
import boto3
client = boto3.client("s3", region_name="us-west-2")
print(client.meta.region_name)  # us-west-2
print(client.meta.endpoint_url)  # https://s3.us-west-2.amazonaws.com

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: "us-west-2" });
const region = await s3.config.region();
console.log(region);  // us-west-2

Add a Custom User-Agent Suffix

Append a custom string to the User-Agent header for tracking or internal identification.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(user_agent_extra="my-app/1.0")
client = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
    customUserAgent: [["my-app", "1.0"]]
});

Dualstack / FIPS Endpoints

Route traffic through dual-stack (IPv4 + IPv6) or FIPS-compliant endpoints.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(
    s3={"use_dualstack_endpoint": True},
    use_fips_endpoint=True
)
client = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
    useDualstackEndpoint: true,
    useFipsEndpoint: true
});

Construct Many Per-Region Clients

Create one client per AWS region to avoid re-construction on each call.

# --- Python (boto3) ---
import boto3
clients = {
    region: boto3.client("s3", region_name=region)
    for region in ["us-east-1", "eu-west-1", "ap-south-1"]
}
clients["us-east-1"].list_buckets()

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const regions = ["us-east-1", "eu-west-1", "ap-south-1"];
const clients = Object.fromEntries(
    regions.map(r => [r, new S3Client({ region: r })])
);

Close / Destroy a Client

Shut down the client to release sockets and connection pools cleanly.

# --- Python (boto3) ---
import boto3
client = boto3.client("s3")
# Do work...
client.close()  # Release resources

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: "us-east-1" });
// Do work...
await s3.destroy();  // Release resources

Credentials & AssumeRole - resolving credentials for these clients and assuming cross-account roles
Error Handling - catching and inspecting service errors from client calls
Pagination, Waiters & Retries - paginating large result sets and waiting on eventual consistency

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Revisado por Chris St. John·Última atualização: 23 de jul. de 2026

Was this article helpful?

Reference Code Reference Configuration Clients Credentials

Clients, Sessions & Configuration

Every AWS API call goes through a client instance; here are the side-by-side patterns for constructing, configuring, and reusing them.

Create a Service Client

Construct a low-level client for a service; reuse it for every call.

# --- Python (boto3) ---
import boto3
s3 = boto3.client("s3", region_name="us-east-1")
print(type(s3).__name__)  # S3Client

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: "us-east-1" });

Set an Explicit Region

Clients need a region to construct the endpoint URL; pass it during client creation.

# --- Python (boto3) ---
import boto3
client = boto3.client("dynamodb", region_name="eu-west-1")

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({ region: "eu-west-1" });

Named Profile / Session

Use a named AWS profile (from ~/.aws/config) or a boto3 Session to scope credentials and region.

# --- Python (boto3) ---
import boto3
session = boto3.Session(profile_name="dev-account")
s3 = session.client("s3")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({ profile: "dev-account" });

Override the Endpoint URL

Point the client at a custom endpoint (local testing, private endpoints, or S3-like services).

# --- Python (boto3) ---
import boto3
s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:9000"
)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
    endpoint: "http://localhost:9000",
    region: "us-east-1"
});

Reuse One Client Across Calls

Create a client at module level or in a singleton; do not create a new client per request.

# --- Python (boto3) ---
# clients.py
import boto3
s3_client = boto3.client("s3", region_name="us-east-1")
 
# app.py
from clients import s3_client
s3_client.list_buckets()

// --- TypeScript (AWS SDK v3) ---
// clients.ts
import { S3Client } from "@aws-sdk/client-s3";
export const s3 = new S3Client({ region: "us-east-1" });
 
// app.ts
import { s3 } from "./clients";
import { ListBucketsCommand } from "@aws-sdk/client-s3";
await s3.send(new ListBucketsCommand({}));

Configure Timeouts

Set socket connect and read timeouts to avoid hanging indefinitely on slow networks.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(
    connect_timeout=5,
    read_timeout=30
)
s3 = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { NodeHttpHandler } from "@smithy/node-http-handler";
const s3 = new S3Client({
    requestHandler: new NodeHttpHandler({
        connectionTimeout: 5_000,
        socketTimeout: 30_000
    })
});

Max Pool Connections / Sockets

Limit or increase the number of concurrent socket connections to AWS services.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(max_pool_connections=50)
s3 = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
import { NodeHttpHandler } from "@smithy/node-http-handler";
const s3 = new S3Client({
    requestHandler: new NodeHttpHandler({
        maxSockets: 50
    })
});

Set Retry Mode + Attempts

Configure automatic retry behavior with exponential backoff; choose standard or adaptive mode.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(
    retries={"mode": "standard", "max_attempts": 5}
)
client = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
    maxAttempts: 5
});

Default Region from Env

Omit the region argument to use AWS_REGION or AWS_DEFAULT_REGION environment variables.

# --- Python (boto3) ---
import boto3
# Reads AWS_REGION or AWS_DEFAULT_REGION
client = boto3.client("s3")

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
// Reads AWS_REGION or AWS_DEFAULT_REGION
const s3 = new S3Client({});

Per-Call Credentials Override

Pass explicit credentials on individual API calls instead of relying on the default chain.

# --- Python (boto3) ---
import boto3
client = boto3.client("s3")
client.list_buckets(
    aws_access_key_id="AKIA...",
    aws_secret_access_key="..."
)

// --- TypeScript (AWS SDK v3) ---
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
const s3 = new S3Client({});
await s3.send(new ListBucketsCommand({}), {
    credentials: {
        accessKeyId: "AKIA...",
        secretAccessKey: "..."
    }
});

Inspect Resolved Region/Endpoint

Read the client's resolved configuration after construction to verify region or endpoint.

# --- Python (boto3) ---
import boto3
client = boto3.client("s3", region_name="us-west-2")
print(client.meta.region_name)  # us-west-2
print(client.meta.endpoint_url)  # https://s3.us-west-2.amazonaws.com

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: "us-west-2" });
const region = await s3.config.region();
console.log(region);  // us-west-2

Add a Custom User-Agent Suffix

Append a custom string to the User-Agent header for tracking or internal identification.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(user_agent_extra="my-app/1.0")
client = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
    customUserAgent: [["my-app", "1.0"]]
});

Dualstack / FIPS Endpoints

Route traffic through dual-stack (IPv4 + IPv6) or FIPS-compliant endpoints.

# --- Python (boto3) ---
from botocore.config import Config
import boto3
config = Config(
    s3={"use_dualstack_endpoint": True},
    use_fips_endpoint=True
)
client = boto3.client("s3", config=config)

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({
    useDualstackEndpoint: true,
    useFipsEndpoint: true
});

Construct Many Per-Region Clients

Create one client per AWS region to avoid re-construction on each call.

# --- Python (boto3) ---
import boto3
clients = {
    region: boto3.client("s3", region_name=region)
    for region in ["us-east-1", "eu-west-1", "ap-south-1"]
}
clients["us-east-1"].list_buckets()

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const regions = ["us-east-1", "eu-west-1", "ap-south-1"];
const clients = Object.fromEntries(
    regions.map(r => [r, new S3Client({ region: r })])
);

Close / Destroy a Client

Shut down the client to release sockets and connection pools cleanly.

# --- Python (boto3) ---
import boto3
client = boto3.client("s3")
# Do work...
client.close()  # Release resources

// --- TypeScript (AWS SDK v3) ---
import { S3Client } from "@aws-sdk/client-s3";
const s3 = new S3Client({ region: "us-east-1" });
// Do work...
await s3.destroy();  // Release resources

Credentials & AssumeRole - resolving credentials for these clients and assuming cross-account roles
Error Handling - catching and inspecting service errors from client calls
Pagination, Waiters & Retries - paginating large result sets and waiting on eventual consistency

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Revisado por Chris St. John·Última atualização: 23 de jul. de 2026

Was this article helpful?

Clients, Sessions & Configuration

Buscar na documentação

Clients, Sessions & Configuration