Azure DevOps Python API Client

7.1.0b4 · active · verified Thu Apr 09

The `azure-devops` library provides a Pythonic wrapper around the Azure DevOps REST APIs, enabling programmatic interaction with Azure DevOps Services and Azure DevOps Server. It allows developers to automate tasks, manage resources like work items, repositories, pipelines, and more. The library has a frequent release cadence, often releasing beta versions to align with the latest Azure DevOps API versions, currently focusing on 7.x APIs.

Warnings

breaking The library closely tracks Azure DevOps REST API versions. Upgrading to a new major library version (e.g., from 6.x to 7.x) may introduce breaking changes in API client method signatures, return types, or data shapes, requiring code adjustments to align with the new underlying REST API version.
Fix: Review the GitHub releases and official Azure DevOps REST API documentation for the target API version. Regenerate client code if you are maintaining a fork, or adapt your calls to match the updated client methods and data models.
gotcha When using Personal Access Tokens (PATs) with `BasicAuthentication`, ensure the username is an empty string and the PAT is passed as the password. Issues can arise if PATs are not correctly formatted or if underlying HTTP clients in redirects strip authentication headers, leading to 401/403 errors.
Fix: Always pass `BasicAuthentication('', personal_access_token)`. If encountering 401/403 errors on redirects, investigate the underlying HTTP client behavior or consider alternative authentication methods like those provided by `azure-identity`.
gotcha The library might encounter deserialization errors (e.g., incorrect type casting from `int` to `float` or unexpected JSON structures) when processing API responses, especially with new or evolving API endpoints or specific data fields.
Fix: Ensure your library version is up-to-date. If issues persist, inspect the raw JSON response from the Azure DevOps API (e.g., via `requests` directly) and the library's client code for the specific API to identify discrepancies. Report issues to the maintainers if it's a library bug.
gotcha Running against Azure DevOps Server (on-premises) might lead to compatibility issues if the client library utilizes preview API versions (e.g., `7.1-preview.1`) that are not yet supported by your specific server installation, potentially causing unexpected errors or missing functionality.
Fix: Check the API versions supported by your Azure DevOps Server instance. If necessary, use an older `azure-devops` client library version or explicitly set the `api-version` parameter in your API calls to a version compatible with your server.
gotcha Certain functionalities (e.g., working with Excel files for migration, advanced work item field manipulation) may require additional, implicitly optional dependencies (e.g., `openpyxl`). A `ModuleNotFoundError` or `ImportError` typically indicates a missing optional package for your specific use case.
Fix: Identify the missing module from the error message and install it explicitly (e.g., `pip install openpyxl`). Consult relevant documentation or examples for the feature you are trying to use to determine necessary optional dependencies.

Install

pip install azure-devops Install latest stable/beta

Imports

Connection
```
from azure.devops.connection import Connection
```
The primary Connection class resides in the 'connection' submodule.
BasicAuthentication
```
from msrest.authentication import BasicAuthentication
```
BasicAuthentication is provided by the 'msrest' library, a core dependency, not directly from 'azure.devops'.

Quickstart

This quickstart demonstrates how to connect to an Azure DevOps organization using a Personal Access Token (PAT) and retrieve a list of projects. It is recommended to store sensitive information like PATs in environment variables for security.

import os
from azure.devops.connection import Connection
from msrest.authentication import BasicAuthentication
import pprint

# Retrieve organization URL and Personal Access Token from environment variables
organization_url = os.environ.get('AZURE_DEVOPS_ORG_URL', 'https://dev.azure.com/YOUR_ORGANIZATION')
personal_access_token = os.environ.get('AZURE_DEVOPS_PAT', 'YOUR_PERSONAL_ACCESS_TOKEN')

if not organization_url or organization_url == 'https://dev.azure.com/YOUR_ORGANIZATION':
    print("Please set the AZURE_DEVOPS_ORG_URL environment variable or update the placeholder.")
    exit(1)

if not personal_access_token or personal_access_token == 'YOUR_PERSONAL_ACCESS_TOKEN':
    print("Please set the AZURE_DEVOPS_PAT environment variable or update the placeholder.")
    exit(1)

# Create a connection to the organization
credentials = BasicAuthentication('', personal_access_token)
connection = Connection(base_url=organization_url, creds=credentials)

# Get a client (the 'core' client provides access to projects, teams, etc.)
core_client = connection.clients.get_core_client()

try:
    # Get the first page of projects
    get_projects_response = core_client.get_projects()
    print("Successfully connected to Azure DevOps. Projects:")
    index = 0
    while get_projects_response is not None:
        for project in get_projects_response.value:
            pprint.pprint(f"[{index}] {project.name}")
            index += 1
        if get_projects_response.continuation_token:
            get_projects_response = core_client.get_projects(continuation_token=get_projects_response.continuation_token)
        else:
            get_projects_response = None
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →