API Reference¶
cloudregion¶
cloudregion
¶
cloudregion - Simple Python library for cloud region mapping.
Converts between canonical city-based region names and provider-specific region identifiers across AWS, Azure, and Google Cloud Platform.
Basic usage
from cloudregion import region r = region('virginia') r.aws 'us-east-1' r.azure 'eastus' r.gcp 'us-east1'
CloudRegionError
¶
Bases: Exception
Base exception for cloud region errors.
Region
¶
Represents a canonical cloud region with provider-specific mappings.
A Region object provides access to provider-specific region identifiers through properties (.aws, .azure, .gcp) based on a canonical city name.
Example
r = Region('virginia') r.aws 'us-east-1' r.azure 'eastus' r.gcp 'us-east1'
aws
property
¶
Return the AWS region identifier.
azure
property
¶
Return the Azure region identifier.
canonical
property
¶
Return the canonical city-based region name.
gcp
property
¶
Return the Google Cloud Platform region identifier.
__eq__(other)
¶
Test equality with another Region object.
__hash__()
¶
Return hash for use in sets and as dictionary keys.
__init__(canonical_name)
¶
Initialize a Region with a canonical city-based name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
canonical_name
|
str
|
City-based region name (e.g., 'virginia', 'tokyo') |
required |
Raises:
| Type | Description |
|---|---|
UnknownRegionError
|
If the canonical name is not recognized |
__repr__()
¶
Return detailed string representation of the region.
__str__()
¶
Return string representation of the region.
UnknownRegionError
¶
Bases: CloudRegionError
Raised when a region name is not recognized.
__init__(region_name, available_regions)
¶
Initialize the exception with the unknown region and available options.
cloudregion.region¶
cloudregion.region
¶
Core Region class for cloud provider region mapping.
CloudRegionError
¶
Bases: Exception
Base exception for cloud region errors.
Region
¶
Represents a canonical cloud region with provider-specific mappings.
A Region object provides access to provider-specific region identifiers through properties (.aws, .azure, .gcp) based on a canonical city name.
Example
r = Region('virginia') r.aws 'us-east-1' r.azure 'eastus' r.gcp 'us-east1'
aws
property
¶
Return the AWS region identifier.
azure
property
¶
Return the Azure region identifier.
canonical
property
¶
Return the canonical city-based region name.
gcp
property
¶
Return the Google Cloud Platform region identifier.
__eq__(other)
¶
Test equality with another Region object.
__hash__()
¶
Return hash for use in sets and as dictionary keys.
__init__(canonical_name)
¶
Initialize a Region with a canonical city-based name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
canonical_name
|
str
|
City-based region name (e.g., 'virginia', 'tokyo') |
required |
Raises:
| Type | Description |
|---|---|
UnknownRegionError
|
If the canonical name is not recognized |
__repr__()
¶
Return detailed string representation of the region.
__str__()
¶
Return string representation of the region.
UnknownRegionError
¶
Bases: CloudRegionError
Raised when a region name is not recognized.
__init__(region_name, available_regions)
¶
Initialize the exception with the unknown region and available options.
cloudregion.integrations¶
cloudregion.integrations
¶
SDK integration helpers for cloud region mapping.
Provides wrapper functions for popular cloud SDKs that automatically resolve canonical region names to provider-specific identifiers.
IntegrationError
¶
Bases: CloudRegionError
Base exception for SDK integration errors.
__init__(region_name, provider)
¶
Initialize the exception for a region not available in a provider.
azure_credential_kwargs(region, **kwargs)
¶
Generate Azure credential kwargs with resolved region.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
region
|
str
|
Canonical region name or Azure region |
required |
**kwargs
|
Any
|
Additional credential parameters |
{}
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dictionary with resolved location parameter |
Example
cred_kwargs = azure_credential_kwargs('virginia')
Use with Azure SDK clients¶
boto3_client_kwargs(service, region, **kwargs)
¶
Generate boto3 client kwargs with resolved region.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
service
|
str
|
AWS service name (e.g., 'ec2', 's3') |
required |
region
|
str
|
Canonical region name or AWS region |
required |
**kwargs
|
Any
|
Additional client parameters |
{}
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dictionary of client parameters with resolved region_name |
Example
client_kwargs = boto3_client_kwargs('ec2', 'virginia') client = boto3.client(**client_kwargs)
boto3_session_kwargs(region, **kwargs)
¶
Generate boto3 Session kwargs with resolved region.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
region
|
str
|
Canonical region name or AWS region |
required |
**kwargs
|
Any
|
Additional Session parameters |
{}
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dictionary of Session parameters with resolved region_name |
Example
session_kwargs = boto3_session_kwargs('virginia', profile_name='dev') session = boto3.Session(**session_kwargs)
gcp_client_kwargs(region, **kwargs)
¶
Generate GCP client kwargs with resolved region.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
region
|
str
|
Canonical region name or GCP region |
required |
**kwargs
|
Any
|
Additional client parameters |
{}
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
Dictionary with resolved region parameter |
Example
client_kwargs = gcp_client_kwargs('virginia')
Use with Google Cloud client libraries¶
resolve_region_parameter(region_param, provider)
¶
Resolve a region parameter to provider-specific format.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
region_param
|
str
|
Region name (canonical or provider-specific) |
required |
provider
|
str
|
Cloud provider ('aws', 'azure', 'gcp') |
required |
Returns:
| Type | Description |
|---|---|
str
|
Provider-specific region identifier |
Raises:
| Type | Description |
|---|---|
IntegrationError
|
If region cannot be resolved |
cloudregion.region_data¶
cloudregion.region_data
¶
Region mapping data for cloud providers.
This module contains the core mapping data between canonical city-based region names and provider-specific region identifiers.