0
# Azure Common
1

2
Microsoft Azure common code library that provides shared utilities and functionality for all Azure Python SDK packages. It includes core exception classes for consistent error handling across Azure services, profile definitions for managing API versions across different Azure environments including hybrid cloud deployments, and client factory functions for creating Azure service clients.
3

4
## Package Information
5

6
- **Package Name**: azure-common
7
- **Language**: Python
8
- **Installation**: `pip install azure-common`
9

10
## Core Imports
11

12
```python
13
# Core exceptions and constants
14
from azure.common import AzureException, AzureHttpError, __version__, __author__
15

16
# Profile management  
17
from azure.profiles import KnownProfiles, ProfileDefinition
18
from azure.profiles.multiapiclient import MultiApiClientMixin, InvalidMultiApiClientError
19

20
# Client factory functions (deprecated)
21
from azure.common.client_factory import (
22
    get_client_from_cli_profile, 
23
    get_client_from_json_dict, 
24
    get_client_from_auth_file
25
)
26

27
# CLI credentials and cloud functions (deprecated)
28
from azure.common.credentials import (
29
    get_cli_profile,
30
    get_azure_cli_credentials
31
)
32
from azure.common.cloud import get_cli_active_cloud
33

34
# Exception and authentication re-exports
35
from azure.common.exceptions import (
36
    CloudError, 
37
    ClientException,
38
    SerializationError,
39
    DeserializationError,
40
    TokenExpiredError,
41
    ClientRequestError,
42
    AuthenticationError,
43
    HttpOperationError
44
)
45

46
# Authentication classes re-exported from credentials
47
from azure.common.credentials import (
48
    BasicAuthentication,
49
    BasicTokenAuthentication,
50
    OAuthTokenAuthentication,
51
    InteractiveCredentials,
52
    ServicePrincipalCredentials,
53
    UserPassCredentials
54
)
55
```
56

57
## Basic Usage
58

59
```python
60
from azure.common import AzureException, AzureHttpError, AzureConflictHttpError
61
from azure.profiles import KnownProfiles, ProfileDefinition
62

63
# Exception handling
64
try:
65
    # Some Azure operation that might fail
66
    pass
67
except AzureHttpError as e:
68
    if e.status_code == 404:
69
        print("Resource not found")
70
    elif e.status_code == 409:
71
        print("Resource conflict")
72
    else:
73
        print(f"HTTP error: {e.status_code}")
74
except AzureException as e:
75
    print(f"Azure error: {e}")
76

77
# Using predefined profiles for API version management
78
profile = KnownProfiles.v2020_09_01_hybrid
79
print(f"Using profile: {profile.value.label}")
80

81
# Creating custom profile
82
custom_profile = ProfileDefinition({
83
    "azure.mgmt.compute.ComputeManagementClient": {
84
        None: "2020-06-01"
85
    }
86
}, "custom-profile")
87
```
88

89
## Architecture
90

91
The azure-common library serves as the foundation layer for the Azure SDK ecosystem, providing:
92

93
- **Exception Hierarchy**: Consistent error handling patterns across all Azure services
94
- **Profile System**: API version management for different Azure environments (public cloud, government cloud, hybrid scenarios)
95
- **Client Factory Pattern**: Standardized client creation (deprecated in favor of azure-identity)
96
- **Cross-Service Utilities**: Shared functionality used by all Azure service clients
97

98
## Capabilities
99

100
### Exception Handling
101

102
Core exception classes providing consistent error handling across all Azure services. The exception hierarchy automatically creates appropriate subclasses based on HTTP status codes.
103

104
```python { .api }
105
class AzureException(Exception):
106
    """Base exception for Azure operations."""
107
    pass
108

109
class AzureHttpError(AzureException):
110
    """HTTP error with automatic subclass creation."""
111
    def __init__(self, message, status_code): ...
112

113
class AzureConflictHttpError(AzureHttpError):
114
    """HTTP 409 conflict error."""
115
    pass
116

117
class AzureMissingResourceHttpError(AzureHttpError):
118
    """HTTP 404 missing resource error."""
119
    pass
120
```
121

122
[Exception Handling](./exceptions.md)
123

124
### Profile Management
125

126
Profile definitions for managing API versions across different Azure environments, enabling applications to target specific API versions or switch between cloud environments.
127

128
```python { .api }
129
class ProfileDefinition:
130
    """Custom profile definition for API versions."""
131
    def __init__(self, profile_dict, label=None): ...
132
    def get_profile_dict(self): ...
133

134
class KnownProfiles(Enum):
135
    """Predefined Azure profiles with API version mappings."""
136
    default = ...
137
    latest = ...
138
    v2017_03_09_profile = ...
139
    v2018_03_01_hybrid = ...
140
    v2019_03_01_hybrid = ...
141
    v2020_09_01_hybrid = ...
142
```
143

144
[Profile Management](./profiles.md)
145

146
### Client Factory Functions
147

148
Deprecated client factory functions for creating Azure service clients from various authentication sources. These functions are deprecated as of version 1.1.28 in favor of azure-identity.
149

150
```python { .api }
151
def get_client_from_cli_profile(client_class, **kwargs):
152
    """Create SDK client from CLI credentials (deprecated)."""
153
    ...
154

155
def get_client_from_json_dict(client_class, config_dict, **kwargs):
156
    """Create SDK client from JSON auth dict (deprecated)."""
157
    ...
158

159
def get_client_from_auth_file(client_class, auth_path=None, **kwargs):
160
    """Create SDK client from auth file (deprecated)."""
161
    ...
162
```
163

164
[Client Factory](./client-factory.md)
165

166
### CLI Integration Functions
167

168
Deprecated functions for integrating with Azure CLI credentials and cloud configurations. These functions are deprecated as of version 1.1.28 in favor of azure-identity.
169

170
```python { .api }
171
def get_cli_profile():
172
    """Return a CLI profile class (deprecated)."""
173
    ...
174

175
def get_azure_cli_credentials(resource=None, with_tenant=False):
176
    """Return CLI credentials and subscription ID (deprecated)."""
177
    ...
178

179
def get_cli_active_cloud():
180
    """Return a CLI active cloud (deprecated)."""
181
    ...
182
```
183

184
### Package Constants
185

186
Package metadata constants providing version and author information.
187

188
```python { .api }
189
__version__: str
190
"""Package version string (e.g., '1.1.28')"""
191

192
__author__: str  
193
"""Author information: 'Microsoft Corp. <azpysdkhelp@microsoft.com>'"""
194
```