Common issues about Python SDK

This doc clarify some common misunderstandings about Python SDK.

How to update an existing resource with create_or_update/begin_create_or_update

An operation named create_or_update/begin_create_or_update of Python SDK usually matches PUT. To update a filed of existing resource, users must do like:

    ...
    # get all fileds of existing resource
    agent_pool = client.agent_pools.get(
        resource_group_name="rg1",
        resource_name="clustername1",
        agent_pool_name="agentpool1",
    )
 
    agent_pool.max_count = 10
    agent_pool.min_count = 1
    # change any filed that you want
    #...
 
    response = client.agent_pools.begin_create_or_update(
        resource_group_name="rg1",
        resource_name="clustername1",
        agent_pool_name="agentpool1",
        parameters=agent_pool,
    ).result()

Users may have confusion: why can't I set the filed directly but have to get the existing resource filed? Here is guideline about PUT:

So the question becomes: Why does PUT has such strange limitations when update existing resource? To explain the question, let us assume special scenarios:

• User A want to delete a field X, so A set the filed X with None and think: Now that I set X with None, service shall delete X
• User B want to update a field Y, so B only set the filed Y and think: Now that I don't set X and it shall be None, service shall keep X same as before

Why is there such ambiguity? It is caused by the meaning of None(in other language, it may be named null/undefined/...). None has two kinds of different meaning in nature: delete it or keep it same as before. To eliminate the ambiguity, PUT adopts meaning that delete it so if users want to update existing resource, they have to get all the filed of the resource and update specific feild.

Different ways to set body parameter of an operation

Usually, operation has a body parameter corresponding to http request body. For Python SDK users, there are 2 ways to set the body parameter.

from azure.identity import DefaultAzureCredential
from azure.mgmt.network import NetworkManagementClient

client = NetworkManagementClient(credential=DefaultAzureCredential(), subscription_id="subid")

# 1: with json-like object
response = client.public_ip_addresses.begin_create_or_update(
    resource_group_name="rg1",
    public_ip_address_name="test-ip",
    parameters={"location": "eastus", "properties": {"dnsSettings": {"domainNameLabel": "dnslbl"}}},
).result()
print(response.as_dict())

# 2: With native model
from azure.mgmt.network.models import PublicIPAddress, PublicIPAddressDnsSettings
parameters = PublicIPAddress(location="eastus", dns_settings=PublicIPAddressDnsSettings(domain_name_label="dnslbl"))
response = client.public_ip_addresses.begin_create_or_update(
    resource_group_name="rg1",
    public_ip_address_name="test-ip",
    parameters=parameters,
).result()
print(response.as_dict())

In model, the signature name is snake-case like domain_name_label; in json-like object, the name is camel-case like domainNameLabel

Debug guide

This guide is to help Python SDK users to get the process about how SDK call REST api.

(1) Copy the following code in your .py file

import sys
import logging

logging.basicConfig(level=logging.DEBUG,
                    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
                    stream=sys.stdout)

(2) set logging_enable=True when calling operation:

client.operation_group.operation(..., logging_enable=True)

(3) Run your .py you could find the log info in screen. It is convenient to get the process about how SDK call REST api:

Build private package with PR

This part will show how to build private package(e.g. azure-mgmt-devcenter) locally with a PR:

1. Install dependencies

PS D:\dev\azure-sdk-for-python> pip install wheel

2. pull the target branch Github shows the branch with azure-sdk:t2-devcenter-2024-04-03-14415, which contains remote repo name azure-sdk and branch name t2-devcenter-2024-04-03-14415

PS D:\dev\azure-sdk-for-python> git remote add azure-sdk https://github.com/azure-sdk/azure-sdk-for-python.git
PS D:\dev\azure-sdk-for-python> git fetch azure-sdk t2-devcenter-2024-04-03-14415
PS D:\dev\azure-sdk-for-python> git checkout t2-devcenter-2024-04-03-14415

3. Step into target package folder where setup.py is

Run and get .whl

PS D:\dev\azure-sdk-for-python\sdk\devcenter\azure-mgmt-devcenter> python setup.py bdist_wheel

Run and get .zip

PS D:\dev\azure-sdk-for-python\sdk\devcenter\azure-mgmt-devcenter> python setup.py sdist --format=zip

Then you can get the private package at dist folder: