TopolearnMulti-account and multi-region code needs explicit sessions instead of boto3's hidden default session.
boto3.client(...) uses a hidden default session configured from the environment. A Session holds configuration (credentials, region, profile) and creates clients and resources from it. Creating your own gives explicit control:
boto3.Session(profile_name="prod")uses a specific profile from your AWS config.boto3.Session(region_name="eu-central-1")sets the default region for its clients.boto3.Session(aws_access_key_id=..., aws_secret_access_key=..., aws_session_token=...)wraps temporary credentials, such as those from an assumed role.
Then session.client("s3"), optionally overriding the region per client.
Handy introspection: session.available_profiles, session.region_name, session.get_available_regions("ec2") (regions the SDK knows for a service) and session.get_credentials().
Rules of thumb:
- Applications with one identity and region can use the default session.
- Tools that iterate over accounts or regions create one session per account and clients per region.
- Sessions aren't thread-safe: create a session per thread, or create clients up front and share those (clients are thread-safe).
Note that a profile set explicitly with profile_name= makes boto3 skip credential environment variables, whereas AWS_PROFILE is just one more input to the chain.
Example
import boto3
dev = boto3.Session(region_name="us-east-1") # env/default profile
# prod = boto3.Session(profile_name="prod") # a named profile
print(dev.region_name) # us-east-1
regions = dev.get_available_regions("ec2")
print(len(regions) > 10, "eu-west-1" in regions) # True True
# one client per region from the same session
clients = {r: dev.client("sqs", region_name=r) for r in ["us-east-1", "eu-west-1"]}
for region, sqs in clients.items():
print(region, sqs.meta.region_name)
# us-east-1 us-east-1
# eu-west-1 eu-west-1
creds = dev.get_credentials()
print(creds.method) # e.g. 'env', 'sso', 'shared-credentials-file', 'iam-role'Remember
- boto3.client() uses a hidden default session
- Session(profile_name=..., region_name=...) for explicit configuration
- Create clients per region from one session
- Sessions aren't thread-safe; clients are
Watch out for
- Mutating the default session's region inside library code and surprising every other caller.