0
# Profile Management
1
2
Profile definitions for managing API versions across different Azure environments, enabling applications to target specific API versions, switch between cloud environments, and maintain compatibility with hybrid cloud deployments.
3
4
## Capabilities
5
6
### Profile Definition
7
8
Custom profile definition class for creating API version mappings.
9
10
```python { .api }
11
class ProfileDefinition:
12
"""
13
Custom Profile definition for API version mapping.
14
15
Allows defining custom profiles with specific API versions for different
16
Azure services, enabling consistent API version management across
17
applications targeting different Azure environments.
18
19
Args:
20
profile_dict (dict): Dictionary mapping service names to API versions
21
label (str, optional): Human-readable label for the profile
22
23
Note:
24
The dict format is internal and should not be considered stable.
25
"""
26
def __init__(self, profile_dict, label=None): ...
27
28
@property
29
def label(self):
30
"""The label associated to this profile definition."""
31
...
32
33
def get_profile_dict(self):
34
"""
35
Return the current profile dict.
36
37
This is internal information, and content should not be considered stable.
38
39
Returns:
40
dict: The internal profile dictionary
41
"""
42
...
43
44
def __repr__(self): ...
45
```
46
47
### Default Profile Management
48
49
Store and manage the default profile used across Azure clients.
50
51
```python { .api }
52
class DefaultProfile:
53
"""
54
Store a default profile.
55
56
Manages the default profile used by Azure clients when no specific
57
profile is provided. The profile can be changed dynamically to affect
58
all subsequently created clients.
59
60
Attributes:
61
profile (ProfileDefinition): The default profile as class attribute
62
"""
63
profile = None
64
65
def use(self, profile):
66
"""
67
Define a new default profile.
68
69
Args:
70
profile (KnownProfiles | ProfileDefinition): New default profile
71
72
Raises:
73
ValueError: If profile is not a valid profile type
74
"""
75
...
76
77
def definition(self):
78
"""
79
Get the current default profile definition.
80
81
Returns:
82
ProfileDefinition: Current default profile
83
"""
84
...
85
```
86
87
### Known Profiles
88
89
Enumeration of predefined Azure profiles with API version mappings for different environments.
90
91
```python { .api }
92
class KnownProfiles(Enum):
93
"""
94
Predefined Azure Profiles for different environments.
95
96
Provides pre-configured profiles for various Azure environments:
97
- latest: Always use latest available API version on each package
98
- default: Mutable profile that can be changed to affect all clients
99
- Versioned profiles: Specific API version sets for hybrid environments
100
101
If you change default, this changes all created packages on the fly to
102
this profile. This can be used to switch a complete set of API versions
103
without re-creating all clients.
104
"""
105
106
# Meta-profiles
107
default = DefaultProfile()
108
latest = ProfileDefinition(None, "latest")
109
110
# Versioned profiles for hybrid environments
111
v2017_03_09_profile = ProfileDefinition({...}, "2017-03-09-profile")
112
v2018_03_01_hybrid = ProfileDefinition({...}, "2018-03-01-hybrid")
113
v2019_03_01_hybrid = ProfileDefinition({...}, "2019-03-01-hybrid")
114
v2020_09_01_hybrid = ProfileDefinition({...}, "2020-09-01-hybrid")
115
116
def __init__(self, profile_definition): ...
117
118
def use(self, profile):
119
"""
120
Set profile (only for default profile).
121
122
Args:
123
profile (KnownProfiles | ProfileDefinition): Profile to use
124
125
Raises:
126
ValueError: If called on non-default profile
127
"""
128
...
129
130
def definition(self):
131
"""
132
Get profile definition (only for default profile).
133
134
Returns:
135
ProfileDefinition: Profile definition
136
137
Raises:
138
ValueError: If called on non-default profile
139
"""
140
...
141
142
@classmethod
143
def from_name(cls, profile_name):
144
"""
145
Get profile by name.
146
147
Args:
148
profile_name (str): Name of the profile to retrieve
149
150
Returns:
151
KnownProfiles: The requested profile
152
153
Raises:
154
ValueError: If profile name not found
155
"""
156
...
157
```
158
159
### Multi-API Client Support
160
161
Mixin class for clients that need to support multiple API versions based on profiles.
162
163
```python { .api }
164
class MultiApiClientMixin:
165
"""
166
Mixin that contains multi-api version profile management.
167
168
To use this mixin, a client must define two class attributes:
169
- LATEST_PROFILE: ProfileDefinition corresponding to latest profile
170
- _PROFILE_TAG: A tag that filters a full profile for this particular client
171
172
This should not be used directly and will only provide private methods.
173
"""
174
175
def __init__(self, *args, **kwargs):
176
"""
177
Initialize multi-API client with profile support.
178
179
Args:
180
api_version (str, optional): Specific API version to use
181
profile (KnownProfiles, optional): Profile to use for API versions
182
183
Raises:
184
ValueError: If both api_version and profile are specified
185
InvalidMultiApiClientError: If required class attributes missing
186
"""
187
...
188
189
def _get_api_version(self, operation_group_name):
190
"""
191
Get API version for a specific operation group.
192
193
Args:
194
operation_group_name (str): Name of the operation group
195
196
Returns:
197
str: API version to use for the operation group
198
199
Raises:
200
ValueError: If profile doesn't define the operation group
201
"""
202
...
203
```
204
205
```python { .api }
206
class InvalidMultiApiClientError(Exception):
207
"""
208
Exception raised when MultiApiClientMixin is used incorrectly.
209
210
Raised when the mixin is not used with a compatible class that
211
defines the required LATEST_PROFILE and _PROFILE_TAG attributes.
212
"""
213
pass
214
```
215
216
## Usage Examples
217
218
### Using Predefined Profiles
219
220
```python
221
from azure.profiles import KnownProfiles
222
223
# Use the latest API versions
224
profile = KnownProfiles.latest
225
print(f"Using profile: {profile.value.label}")
226
227
# Use a specific hybrid profile
228
hybrid_profile = KnownProfiles.v2020_09_01_hybrid
229
print(f"Using hybrid profile: {hybrid_profile.value.label}")
230
231
# Get profile by name
232
profile_by_name = KnownProfiles.from_name("2020-09-01-hybrid")
233
```
234
235
### Creating Custom Profiles
236
237
```python
238
from azure.profiles import ProfileDefinition
239
240
# Create a custom profile for specific API versions
241
custom_profile = ProfileDefinition({
242
"azure.mgmt.compute.ComputeManagementClient": {
243
None: "2020-06-01",
244
"disks": "2019-07-01",
245
"snapshots": "2019-07-01"
246
},
247
"azure.mgmt.storage.StorageManagementClient": {
248
None: "2019-06-01"
249
}
250
}, "my-custom-profile")
251
252
print(f"Created profile: {custom_profile.label}")
253
profile_dict = custom_profile.get_profile_dict()
254
```
255
256
### Managing Default Profile
257
258
```python
259
from azure.profiles import KnownProfiles
260
261
# Change the default profile for all new clients
262
KnownProfiles.default.use(KnownProfiles.v2020_09_01_hybrid)
263
264
# Get the current default profile
265
current_default = KnownProfiles.default.definition()
266
print(f"Current default: {current_default.label}")
267
```
268
269
### Multi-API Client Implementation
270
271
```python
272
from azure.profiles import KnownProfiles, ProfileDefinition
273
from azure.profiles.multiapiclient import MultiApiClientMixin
274
275
class MyAzureClient(MultiApiClientMixin):
276
_PROFILE_TAG = "azure.mgmt.myservice.MyServiceClient"
277
LATEST_PROFILE = ProfileDefinition({
278
_PROFILE_TAG: {
279
None: "2021-01-01"
280
}
281
}, "latest")
282
283
def __init__(self, credentials, **kwargs):
284
super().__init__(**kwargs)
285
self.credentials = credentials
286
287
def get_operations_api_version(self):
288
return self._get_api_version("operations")
289
290
# Use with specific API version
291
client = MyAzureClient(credentials, api_version="2020-01-01")
292
293
# Use with profile
294
client = MyAzureClient(credentials, profile=KnownProfiles.v2020_09_01_hybrid)
295
```
296
297
## Profile Structure
298
299
The predefined profiles contain API version mappings for various Azure services. Here are examples of the service mappings:
300
301
### v2020_09_01_hybrid Profile
302
303
```python
304
v2020_09_01_hybrid = ProfileDefinition({
305
"azure.keyvault.KeyVaultClient": {
306
None: "2016-10-01"
307
},
308
"azure.mgmt.authorization.AuthorizationManagementClient": {
309
None: "2016-09-01"
310
},
311
"azure.mgmt.compute.ComputeManagementClient": {
312
None: "2020-06-01",
313
'resource_skus': '2019-04-01',
314
'disks': '2019-07-01',
315
'snapshots': '2019-07-01'
316
},
317
"azure.mgmt.network.NetworkManagementClient": {
318
None: "2018-11-01"
319
},
320
"azure.mgmt.storage.StorageManagementClient": {
321
None: "2019-06-01"
322
}
323
# ... additional service mappings
324
}, "2020-09-01-hybrid")
325
```
326
327
Each service mapping can define:
328
- `None`: Default API version for the service
329
- Specific operation groups: Custom API versions for particular operations