Client Initialization Best Practices (Python)

Core Rules

• Client is thread-safe — safe to share across threads without additional locking.
• Use singleton pattern — do NOT create new client instances per request. Frequent client creation wastes resources.
• Prefer explicit endpoint over region-based endpoint resolution.

Recommended Client Creation

import os
from threading import Lock
from alibabacloud_tea_openapi.models import Config
from alibabacloud_ecs20140526.client import Client as EcsClient

_client = None
_lock = Lock()

def get_ecs_client() -> EcsClient:
    global _client
    if _client is None:
        with _lock:
            if _client is None:
                config = Config(
                    access_key_id=os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'],
                    access_key_secret=os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'],
                    endpoint='ecs.cn-hangzhou.aliyuncs.com',
                )
                _client = EcsClient(config)
    return _client

Endpoint Configuration

Priority: explicit endpoint > region-based resolution via region_id.

# Preferred: explicit endpoint
config = Config(endpoint='ecs.cn-hangzhou.aliyuncs.com')

# Alternative: SDK resolves endpoint from region
config = Config(region_id='cn-hangzhou')

VPC Endpoints

Use VPC endpoints when running inside Alibaba Cloud VPC:

config = Config(endpoint='ecs-vpc.cn-hangzhou.aliyuncs.com')

File Upload APIs (Advance)

Set both region_id and endpoint to the same region. Optionally set open_platform_endpoint and endpoint_type for VPC:

config = Config(
    region_id='cn-shanghai',
    endpoint='objectdet.cn-shanghai.aliyuncs.com',
    open_platform_endpoint='openplatform-vpc.cn-shanghai.aliyuncs.com',
    endpoint_type='internal',
)

SDK Components

Async Mode

Python SDK supports async calls via _async method suffix:

import asyncio
from alibabacloud_ecs20140526.client import Client
from alibabacloud_ecs20140526.models import DescribeImagesRequest
from alibabacloud_tea_openapi.models import Config

async def main():
    config = Config(
        access_key_id=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'),
        access_key_secret=os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
        endpoint='ecs-cn-hangzhou.aliyuncs.com',
    )
    client = Client(config)
    request = DescribeImagesRequest(region_id='cn-hangzhou')
    response = await client.describe_images_async(request)
    return response

asyncio.run(main())