ado-source-core

ado-source-core

Read-only Azure DevOps API client and Pydantic models. OSS library (MIT-licensed) shared by:

• ado-scanner — standalone discovery CLI
• Shyftport engines that need to read from Azure DevOps

This library is read-only. It does not perform any writes against Azure DevOps. Migration-side writes live in proprietary code outside this package.

Install

pip install ado-source-core

Quickstart

import asyncio
from ado_source_core import ADOClient, PATAuth

async def main():
    auth = PATAuth(token="your-pat")
    async with ADOClient(organization="myorg", auth=auth) as client:
        async for repo in client.list_repositories(project="MyProject"):
            print(repo.name, repo.default_branch)

asyncio.run(main())

Cloud vs Server

ado-source-core ships two adapters:

• AzureDevOpsCloudAdapter — for Azure DevOps Services (dev.azure.com/{org}). REST API pinned to 7.1.
• AzureDevOpsServerAdapter — for self-hosted Azure DevOps Server (the on-prem product, formerly TFS). The REST api-version is auto-discovered when the client connects (await client.connect() or implicitly via async with ADOServerClient(...)) by probing /_apis/connectionData with candidate iteration as a fallback. Construction itself performs no network I/O.

Supported Server versions

TFS 2018 (REST 4.x) and earlier are out of scope for v0.3.0. Server deployments with PATs disabled at the org-policy level (or NTLM-only deployments behind enterprise SSO) are not supported — PAT support is a hard prerequisite. NTLM/Negotiate auth is a v0.4.0 candidate.

Server quickstart

import asyncio
from ado_source_core import (
    ADOServerClient, AzureDevOpsServerAdapter, PATAuth,
    UnsupportedOnAzureDevOpsServerError,
)

async def main():
    auth = PATAuth(token="your-server-pat")
    async with ADOServerClient(
        base_url="https://devops.example.com:8080/tfs",
        collection="DefaultCollection",
        auth=auth,
    ) as client:
        adapter = AzureDevOpsServerAdapter(client=client)
        caps = await adapter.get_capabilities()
        print(f"Resolved api-version: {caps.api_version}")
        print(f"Notes: {caps.notes}")

        # Always-available calls work the same as on cloud:
        for project in await adapter.list_projects():
            print(project["name"])

        # Optional calls gate on capability flags:
        if caps.supports_graph_api:
            for user in await adapter.list_users():
                print(user.username)
        else:
            print("Graph extension not installed; user listing unavailable.")

        # Capabilities that don't exist on Server raise:
        try:
            await adapter.list_user_entitlements()
        except UnsupportedOnAzureDevOpsServerError as exc:
            print(f"Skipped {exc.capability}: {exc.remediation}")

asyncio.run(main())

Capability matrix

Comprehensive flag-by-flag state across both adapters:

When a probe-resolvable capability is False, the corresponding adapter methods raise UnsupportedOnAzureDevOpsServerError with capability, api_version, and remediation fields populated for downstream discovery reports.

Status

Alpha. Stable enough for ado-scanner consumption; API may change before v1.0.

License

MIT.