The Azure SDK for Python is composed of many independent libraries, which are listed on thePython SDK package index.

All the libraries share certain common characteristics and usage patterns, such as installation and the use of inline JSON for object arguments.

Set up your local development environment

If you haven't already, you can set up an environment where you can run this code. Here are some options:

• Configure a Python virtual environment usingvenv or your tool of choice. To start using the virtual environment, be sure to activate it. To install python, seeInstall Python.

  • Bash
  • PowerShell

  #!/bin/bash# Create a virtual environmentpython -m venv .venv# Activate the virtual environmentsource .venv/Scripts/activate # only required for Windows (Git Bash)

• Use aconda environment. To install Conda, seeInstall Miniconda.

• Use aDev Container inVisual Studio Code orGitHub Codespaces.

Library installation

Choose the installation method that corresponds to your Python environment management tool, either pip or conda.

REM Install the management library for Azure Storagepip install azure-mgmt-storage

REM Install the client library for Azure Blob Storagepip install azure-storage-blob

REM Install the azure identity library for Azure authenticationpip install azure-identity

# Install the Azure management library packageconda install azure-mgmt

# Install the client library for Azure Storageconda install azure-storage

REM Install the azure identity library for Azure authenticationpip install azure-identity

Asynchronous operations

Asynchronous libraries

Many client and management libraries provide async versions (.aio). Theasyncio library has been available since Python 3.4, and the async/await keywords were introduced in Python 3.5. The async versions of the libraries are intended to be used with Python 3.5 and later.

Examples of Azure Python SDK libraries with async versions include:azure.storage.blob.aio,azure.servicebus.aio,azure.mgmt.keyvault.aio, andazure.mgmt.compute.aio.

These libraries need an async transport such asaiohttp to work. Theazure-core library provides an async transport,AioHttpTransport, which is used by the async libraries, so you may not need to installaiohttp separately.

The following code shows how create a python file thath demonstrates how to create a client for the async version of the Azure Blob Storage library:

credential = DefaultAzureCredential()async def run():    async with BlobClient(        storage_url,        container_name="blob-container-01",        blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",        credential=credential,    ) as blob_client:        # Open a local file and upload its contents to Blob Storage        with open("./sample-source.txt", "rb") as data:            await blob_client.upload_blob(data)            print(f"Uploaded sample-source.txt to {blob_client.url}")        # Close credential        await credential.close()asyncio.run(run())

The full example is on GitHub atuse_blob_auth_async.py. For the synchronous version of this code, seeExample: Upload a blob.

Long running operations

Some management operations that you invoke (such asComputeManagementClient.virtual_machines.begin_create_or_update andWebAppsClient.web_apps.begin_create_or_update) return a poller for long running operations,LROPoller[<type>], where<type> is specific to the operation in question.

TheLROPoller return type means that the operation is asynchronous. Accordingly, you must call that poller'sresult method to wait for the operation to finish and obtain its result.

The following code, taken fromExample: Create and deploy a web app, shows an example of using the poller to wait for a result:

# Step 3: With the plan in place, provision the web app itself, which is the process that can host# whatever code we want to deploy to it.poller = app_service_client.web_apps.begin_create_or_update(RESOURCE_GROUP_NAME,    WEB_APP_NAME,    {        "location": LOCATION,        "server_farm_id": plan_result.id,        "site_config": {            "linux_fx_version": "python|3.8"        }    })web_app_result = poller.result()

In this case, the return value ofbegin_create_or_update is of typeAzureOperationPoller[Site], which means that the return value ofpoller.result() is a Site object.

Exceptions

In general, the Azure libraries raise exceptions when operations fail to perform as intended, including failed HTTP requests to the Azure REST API. For app code, you can usetry...except blocks around library operations.

For more information on the type of exceptions that may be raised, see the documentation for the operation in question.

Logging

The most recent Azure libraries use the Python standardlogging library to generate log output. You can set the logging level for individual libraries, groups of libraries, or all libraries. Once you register a logging stream handler, you can then enable logging for a specific client object or a specific operation. For more information, seeLogging in the Azure libraries.

Proxy configuration

To specify a proxy, you can use environment variables or optional arguments. For more information, seeHow to configure proxies.

Optional arguments for client objects and methods

In the library reference documentation, you often see a**kwargs or**operation_config argument in the signature of a client object constructor or a specific operation method. These placeholders indicate that the object or method in question may support other named arguments. Typically, the reference documentation indicates the specific arguments you can use. There are also some general arguments that are often supported as described in the following sections.

Arguments for libraries based on azure.core

These arguments apply to those libraries listed onPython - New Libraries. For example, here are a subset of the keyword arguments forazure-core. For a complete list, see the GitHub README forazure-core.

Individual libraries aren't obligated to support any of these arguments, so always consult the reference documentation for each library for exact details. Also, each library may support other arguments. For example, for blob storage specific keyword arguments, see the GitHub README forazure-storage-blob.

Inline JSON pattern for object arguments

Many operations within the Azure libraries allow you to express object arguments either as discrete objects or as inline JSON.

For example, suppose you have aResourceManagementClient object through which you create a resource group with itscreate_or_update method. The second argument to this method is of typeResourceGroup.

To call thecreate_or_update method, you can create a discrete instance ofResourceGroup directly with its required arguments (location in this case):

# Provision the resource group.rg_result = resource_client.resource_groups.create_or_update(    "PythonSDKExample-rg",    ResourceGroup(location="centralus"))

Alternately, you can pass the same parameters as inline JSON:

# Provision the resource group.rg_result = resource_client.resource_groups.create_or_update(    "PythonAzureExample-rg", {"location": "centralus"})

When you use inline JSON, the Azure libraries automatically convert the inline JSON to the appropriate object type for the argument in question.

Objects can also have nested object arguments, in which case you can also use nested JSON.

For example, suppose you have an instance of theKeyVaultManagementClient object, and are calling itscreate_or_update. In this case, the third argument is of typeVaultCreateOrUpdateParameters, which itself contains an argument of typeVaultProperties.VaultProperties, in turn, contains object arguments of typeSku andlist[AccessPolicyEntry]. ASku contains aSkuName object, and eachAccessPolicyEntry contains aPermissions object.

To callbegin_create_or_update with embedded objects, you use code like the following (assumingtenant_id,object_id, andLOCATION are already defined). You can also create the necessary objects before the function call.

# Provision a Key Vault using inline parameterspoller = keyvault_client.vaults.begin_create_or_update(    RESOURCE_GROUP_NAME,    KEY_VAULT_NAME_A,    VaultCreateOrUpdateParameters(        location = LOCATION,        properties = VaultProperties(            tenant_id = tenant_id,            sku = Sku(                name="standard",                family="A"            ),                        access_policies = [                AccessPolicyEntry(                    tenant_id = tenant_id,                    object_id = object_id,                    permissions = Permissions(                        keys = ['all'],                        secrets = ['all']                    )                )            ]        )    ))key_vault1 = poller.result()

The same call using inline JSON appears as follows:

# Provision a Key Vault using inline JSONpoller = keyvault_client.vaults.begin_create_or_update(    RESOURCE_GROUP_NAME,    KEY_VAULT_NAME_B,    {        'location': LOCATION,        'properties': {            'sku': {                'name': 'standard',                'family': 'A'            },            'tenant_id': tenant_id,            'access_policies': [{                'tenant_id': tenant_id,                'object_id': object_id,                                'permissions': {                    'keys': ['all'],                    'secrets': ['all']                }            }]        }    })key_vault2 = poller.result()

Because both forms are equivalent, you can choose whichever you prefer and even intermix them. (The full code for these examples can be found onGitHub.)

If your JSON isn't formed properly, you typically get the error, "DeserializationError: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute 'get'". A common cause of this error is that you're providing a single string for a property when the library expects a nested JSON object. For example, using'sku': 'standard' in the previous example generates this error because thesku parameter is aSku object that expects inline object JSON, in this case{'name': 'standard'}, which maps to the expectedSkuName type.

Next steps

Now that you understand the common patterns for using the Azure libraries for Python, see the following standalone examples to explore specific management and client library scenarios. You can try these examples in any order as they're not sequential or interdependent.

• Example: Create a resource group

• Example: Use Azure Storage

• Example: Create a web app and deploy code

• Example: Create and query a database

• Example: Create a virtual machine

• Use Azure Managed Disks with virtual machines

• Complete a short survey about the Azure SDK for Python