Skip to content

Commit ec33763

Browse files
ChenxiJiang333msyycCopilot
authored
[docs] create operation migration guide (#42323)
* Create operation_migration.md * Update operation_migration.md * Update doc/dev/mgmt/operation_migration.md Co-authored-by: Copilot <[email protected]> * Update doc/dev/mgmt/operation_migration.md Co-authored-by: Copilot <[email protected]> * Update doc/dev/mgmt/operation_migration.md Co-authored-by: Copilot <[email protected]> * Update operation_migration.md --------- Co-authored-by: Yuchao Yan <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 78fac7e commit ec33763

File tree

1 file changed

+128
-0
lines changed

1 file changed

+128
-0
lines changed

‎doc/dev/mgmt/operation_migration.md

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Azure SDK Migration Guide: New Operation Design Generation Breaking Changes
2+
3+
The direct link to this page can be found at aka.ms/azsdk/python/migrate/operations
4+
5+
This guide covers the breaking changes you'll encounter when upgrading to our new operation design and how to fix them in your code.
6+
7+
## Summary of Breaking Changes
8+
9+
When migrating to the operation design, expect these breaking changes:
10+
11+
| Change | Impact | Quick Fix |
12+
| ----------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------- |
13+
| [Query/Header Parameters](#queryheader-parameters-requiring-keywords) | Query and header signatures changed from positional to keyword-only | Convert all positional parameters to keyword arguments |
14+
| [Conditional Operation](#conditional-operation-parameters-changed) | header signatures `if_match`/`if_none_match` is replaced by `etag`/`match_condition` | Replace `if_match=<specific etag>` with `etag=<specific etag>, match_condition=MatchConditions.IfNotModified`,<br>Replace `if_none_match=<specific etag>` with `etag=<specific etag>, match_condition=MatchConditions.IfModified` |
15+
16+
## Detailed Breaking Changes
17+
18+
### Query/Header Parameters Requiring Keywords
19+
20+
**What changed**: Query and header parameters in operation methods have been changed from positional to keyword-only.
21+
22+
**What will break**:
23+
24+
- Code that passes positional parameters
25+
26+
**Before**:
27+
28+
```python
29+
from azure.mgmt.confluent import ConfluentManagementClient
30+
31+
client = ConfluentManagementClient(...)
32+
33+
# Pass query parameters positionally
34+
environments = client.organization_operations.list_environments(
35+
"resource_group",
36+
"org_name",
37+
10, # Pass page_size as positional
38+
"token" # Pass page_token as positional
39+
)
40+
```
41+
42+
**After**:
43+
44+
```python
45+
from azure.mgmt.confluent import ConfluentManagementClient
46+
47+
client = ConfluentManagementClient(...)
48+
49+
# ❌ Raises TypeError
50+
environments = client.organization_operations.list_environments(
51+
"resource_group",
52+
"org_name",
53+
10,
54+
"token"
55+
)
56+
57+
# ✅ Use these approaches instead
58+
environments = client.organization_operations.list_environments(
59+
"resource_group",
60+
"org_name",
61+
page_size=10, # Must be passed with a keyword
62+
page_token="token" # Must be passed with a keyword
63+
)
64+
```
65+
66+
**Migration steps:**
67+
68+
- Convert all positional parameters to keyword arguments
69+
70+
### Conditional Operation Parameters Changed
71+
72+
**What changed**: Conditional operation headers `if_match` and `if_none_match` have been replaced with more semantic `etag` and `match_condition` parameters that use enum values to describe match conditions.
73+
74+
**What will break**:
75+
76+
- Code using `if_match` or `if_none_match` parameters
77+
78+
**Before**:
79+
80+
```python
81+
from azure.mgmt.containerservicefleet import ContainerServiceFleetManagementClient
82+
83+
client = ContainerServiceFleetManagementClient(...)
84+
85+
# Update the resource only if the latest etag matches the value provided in this header
86+
fleet = client.fleets.begin_create_or_update(
87+
resource_group_name="rg",
88+
fleet_name="fleet1",
89+
resource=fleet_operation,
90+
if_match="<specific etag>"
91+
)
92+
```
93+
94+
**After**:
95+
96+
```python
97+
from azure.mgmt.containerservicefleet import ContainerServiceFleetManagementClient
98+
from azure.core import MatchConditions
99+
100+
client = ContainerServiceFleetManagementClient(...)
101+
102+
# Use enum to describe match condition
103+
fleet = client.fleets.begin_create_or_update(
104+
resource_group_name="rg",
105+
fleet_name="fleet1",
106+
resource=fleet_operation,
107+
etag="<specific etag>",
108+
match_condition=MatchConditions.IfNotModified
109+
)
110+
```
111+
112+
**Migration steps:**
113+
114+
- Import `MatchConditions` from `azure.core`
115+
- Replace `if_match="<specific etag>"` with `etag="<specific etag>", match_condition=MatchConditions.IfNotModified`
116+
- Replace `if_none_match="<specific etag>"` with `etag="<specific etag>", match_condition=MatchConditions.IfModified`
117+
- Replace `if_match="*"` with `match_condition=MatchConditions.IfPresent`
118+
- Replace `if_none_match="*"` with `match_condition=MatchConditions.IfMissing`
119+
120+
## Why These Changes?
121+
122+
Our operations prioritize consistency with the underlying REST API:
123+
124+
- **Better API Alignment**: Keyword-only parameters improve traceability between code and request body.
125+
- **Improved Developer Experience**: Keyword-only parameters enable IDEs to provide rich type hints with parameter names.
126+
- **Maintainability**: Enum-based conditions makes the SDK easier to maintain and understand.
127+
128+
If you encounter issues not covered here, please file an issue on [GitHub](https://github.com/microsoft/typespec/issues) with tag `emitter:client:python`.

0 commit comments

Comments
 (0)