Skip to content

Commit 526285d

Browse files
authored
[docs] add new backcompat serialization methods to migration guide (#41895)
1 parent 28bb627 commit 526285d

File tree

1 file changed

+50
-0
lines changed

1 file changed

+50
-0
lines changed

doc/dev/mgmt/hybrid_model_migration.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,18 @@ print(json_model["myName"]) # Now returns camelCase key (matches REST API)
6060
- Replace `keep_readonly=True` with `exclude_readonly=False`
6161
- Update code expecting `snake_case` keys to use `camelCase` keys (consistent with REST API)
6262

63+
**Backcompat option:**
64+
If you need `snake_case` keys and can't easily update your code:
65+
66+
```python
67+
# Requires azure-core >= 1.35.0
68+
from azure.core.serialization import as_attribute_dict
69+
70+
# Returns snake_case keys like the old models
71+
json_model = as_attribute_dict(model, exclude_readonly=False)
72+
print(json_model["my_name"]) # snake_case key preserved
73+
```
74+
6375
### Model Hierarchy Reflects REST API Structure
6476

6577
**What changed**: Hybrid model generation preserves the actual REST API hierarchy instead of artificially flattening it.
@@ -99,6 +111,18 @@ print(model["properties"]["properties"]["name"]) # ✅ Mirrors actual API struc
99111
- Example: `obj.level1_level2_property``obj.level1.level2.property`
100112
- This new structure will match your REST API documentation exactly
101113

114+
**Backcompat option:**
115+
For complex flattened property access where direct migration is difficult:
116+
117+
```python
118+
# Requires azure-core >= 1.35.0
119+
from azure.core.serialization import as_attribute_dict
120+
121+
# Handles flattened properties automatically
122+
model_dict = as_attribute_dict(model)
123+
print(model_dict["properties_properties_name"]) # Works with flattened names
124+
```
125+
102126
### Additional Properties Handling
103127

104128
**What changed**: Hybrid models inherently support additional properties through dictionary-like behavior, eliminating the need for a separate additional_properties parameter.
@@ -236,6 +260,32 @@ model = Model(name="example", value=42) # Still works as before
236260
- Verify the output format matches your expectations
237261
- Check that `camelCase` keys are handled correctly
238262

263+
**Backcompat option:**
264+
If you need the exact same serialization format as the old `serialize()` method:
265+
266+
```python
267+
# Requires azure-core >= 1.35.0
268+
from azure.core.serialization import as_attribute_dict
269+
270+
# Returns the same format as old serialize() method with snake_case keys
271+
serialized_dict = as_attribute_dict(model, exclude_readonly=False)
272+
# For old serialize(keep_readonly=False) behavior:
273+
serialized_dict = as_attribute_dict(model, exclude_readonly=True)
274+
```
275+
276+
---
277+
278+
## Additional Helper Methods
279+
280+
For edge cases and generic code that works with models, Azure Core (version 1.35.0 or later) provides these utility methods in `azure.core.serialization`:
281+
282+
- **`is_generated_model(obj)`**: Check if an object is an SDK-generated model
283+
- **`attribute_list(model)`**: Get list of model attribute names (excluding additional properties)
284+
285+
These are useful for writing generic code that needs to detect or introspect SDK models. These methods work with both the old and new hybrid models.
286+
287+
---
288+
239289
## Why These Changes?
240290

241291
Our hybrid models prioritize consistency with the underlying REST API:

0 commit comments

Comments
 (0)