Reference ¶

update_user_access_level(user_id, access_level)¶

Update the access level for an existing user entitlement.

Parameters:

user_id (UUID) – UUID of the user whose access level should be updated.
access_level (AccessLevel) – New access level to apply.

Returns:

Updated UserEntitlement.

Return type:

UserEntitlement

Process¶

OOP wrapper for Azure DevOps work process resources.

class pyado.oop.core.process.Process(org, info)¶

An ADO work process template at organisation scope.

Wraps a single ADO work process, giving access to all mutation operations — work item type CRUD, state CRUD, field add/update/remove, rule CRUD, and behavior CRUD.

Instances are obtained from Organization.iter_processes(), Organization.list_processes(), Organization.get_process(), or Organization.create_process().

Parameters:

org (Organization)
info (ProcessDetail)

_org¶: The Organisation this process belongs to.

_id¶: Process template UUID (always known).

_info¶: Cached process data; None after refresh().

add_work_item_type_field(work_item_type_ref, request)¶

Add a field to a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
request (ProcessWorkItemTypeFieldAddRequest) – Add request specifying field reference name and options.

Returns:

ProcessWorkItemField describing the field as it was added.

Return type:

create_behavior(request)¶

Create a behavior in this process.

Parameters:: request (ProcessBehaviorCreateRequest) – Create request specifying name and optional color.
Returns:: ProcessBehaviorInfo for the newly created behavior.
Return type:: ProcessBehaviorInfo

create_work_item_type(request)¶

Create a work item type in this process.

Parameters:: request (ProcessWorkItemTypeCreateRequest) – Create request specifying name and optional fields.
Returns:: ProcessWITInfo for the newly created work item type.
Return type:: ProcessWITInfo

create_work_item_type_rule(work_item_type_ref, request)¶

Create a rule on a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
request (ProcessWorkItemTypeRuleCreateRequest) – Create request specifying conditions and actions.

Returns:

ProcessWorkItemRule for the newly created rule.

Return type:

create_work_item_type_state(work_item_type_ref, request)¶

Create a state on a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
request (ProcessWorkItemTypeStateCreateRequest) – Create request for the new state.

Returns:

ProcessWorkItemState for the newly created state.

Return type:

delete()¶

Delete this process template from the organisation.

Return type:: None

delete_behavior(behavior_ref)¶

Delete a behavior from this process.

Parameters:: behavior_ref (str) – Reference name of the behavior to delete.
Return type:: None

delete_work_item_type(work_item_type_ref)¶

Delete a work item type from this process.

Parameters:: work_item_type_ref (str) – Reference name of the work item type to delete.
Return type:: None

delete_work_item_type_rule(work_item_type_ref, rule_id)¶

Delete a rule from a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
rule_id (str) – ID of the rule to delete.

Return type:

None

delete_work_item_type_state(work_item_type_ref, state_id)¶

Delete a state from a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
state_id (str) – ID of the state to delete.

Return type:

None

property description: str¶: Process template description.

property id: UUID¶: Process template UUID — always known, no API call.

property info: ProcessDetail¶

Full process data as returned by the API.

Fetched lazily by re-querying the API if refresh() was called since the last access.

property name: str¶: Process template display name.

property org: Organization¶: Organisation this process belongs to — zero-cost.

refresh()¶

Discard cached process data.

The next access to info re-fetches from the API.

Return type:: None

remove_work_item_type_field(work_item_type_ref, field_ref)¶

Remove a field from a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
field_ref (str) – Reference name of the field to remove.

Return type:

None

update(request)¶

Update this process template.

Parameters:: request (ProcessUpdateRequest) – Update request with fields to change.
Return type:: None

update_behavior(behavior_ref, request)¶

Update a behavior in this process.

Parameters:

behavior_ref (str) – Reference name of the behavior to update.
request (ProcessBehaviorUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessBehaviorInfo.

Return type:

ProcessBehaviorInfo

update_work_item_type(work_item_type_ref, request)¶

Update a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
request (ProcessWorkItemTypeUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessWITInfo.

Return type:

ProcessWITInfo

update_work_item_type_field(work_item_type_ref, field_ref, request)¶

Update a field on a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
field_ref (str) – Reference name of the field to update.
request (ProcessWorkItemTypeFieldUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessWorkItemField.

Return type:

update_work_item_type_rule(work_item_type_ref, rule_id, request)¶

Update a rule on a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
rule_id (str) – ID of the rule to update.
request (ProcessWorkItemTypeRuleUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessWorkItemRule.

Return type:

update_work_item_type_state(work_item_type_ref, state_id, request)¶

Update a state on a work item type in this process.

Parameters:

work_item_type_ref (str) – Reference name of the work item type.
state_id (str) – ID of the state to update.
request (ProcessWorkItemTypeStateUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessWorkItemState.

Return type:

Project¶

OOP wrapper for Azure DevOps project resources.

class pyado.oop.project.Project(service, name, info=None)¶

An Azure DevOps project resource.

ADO concept: a project is the namespace within an organisation that contains all other resources — repositories, pipelines, builds, work items, variable groups, teams, iteration/area hierarchies, etc. ADO REST endpoints use the form {org}/{project}/_apis/…. The project is identified by a stable UUID (ProjectId) but is always addressed by name in the URL. Raw endpoint: GET _apis/projects/{nameOrId} (docs: core/Projects).

Why it exists: Project is the central hub of the OOP layer. It owns the project-level ApiCall (the URL prefix shared by every sub-resource) and exposes five section objects that group related operations: repos, boards, pipelines, search, and settings.

Instances are normally obtained from Organization.get_project() or Organization.iter_projects().

Project info is loaded lazily — the first access to info or id triggers a GET /projects/{name} call if info was not supplied at construction time. Call refresh() to discard cached info and force a fresh fetch on next access.

Parameters:

service (AzureDevOpsService)
name (str)
info (ProjectInfo | None)

_service¶: The owning AzureDevOpsService (cache and auth holder).

_name¶: Project name (always known at construction).

_api_call¶: Project-level API call built at construction; never changes.

_info¶: Cached project data; None until first lazy fetch.

property api_call: ApiCall¶: Project-level API call for direct use with pyado.raw functions.

property boards: ProjectBoards¶: The Boards section — work items, iterations, areas, teams.

get_dashboard(dashboard_id, team=None)¶

Return a specific dashboard by ID.

Parameters:

dashboard_id (UUID) – UUID of the dashboard.
team (Team | None) – Team to look up the dashboard under. When None, the project’s default team is used.

Returns:

Dashboard wrapping the requested dashboard.

Return type:

Dashboard

get_default_team()¶

Return the default team for this project.

Uses the defaultTeam field from the project info when available; falls back to "{project_name} Team" if not.

Returns:: Team wrapping the project’s default team.
Return type:: Team

get_process_info()¶

Return process detail for this project’s work process template.

Fetches the project capabilities to resolve the template type ID, then queries all process sub-resources (work item types, states, rules, fields, behaviors, and project fields).

Returns:: ProcessDetail with all sub-resources populated.
Raises:: ValueError – If the project capabilities are not available.
Return type:: ProcessDetail

property id: UUID¶: Project UUID (lazy-fetched if info was not supplied at construction).

property info: ProjectInfo¶: Project data — lazy-fetched on first access if not given at construction.

iter_dashboards(team=None)¶

Iterate over all dashboards in this project.

When team is given, only that team’s dashboards are returned. When team is None, dashboards from all teams are yielded.

Parameters:: team (Team | None) – Optional team to restrict the search to.
Yields:: Dashboard for each matching dashboard.
Return type:: Iterator[Dashboard]

iter_teams()¶

Iterate over all teams in this project.

Yields:: Team for each team in the project.
Return type:: Iterator[Team]

iter_wikis()¶

Iterate over all wikis in this project.

Yields:: Wiki for each wiki in the project.
Return type:: Iterator[Wiki]

list_dashboards(team=None)¶

Return dashboards in this project as a list.

Parameters:: team (Team | None) – Optional team to restrict the search to.
Returns:: List of Dashboard objects.
Return type:: list[Dashboard]

list_teams()¶

Return all teams in this project as a list.

Return type:: list[Team]

list_wikis()¶

Return all wikis in this project as a list.

Return type:: list[Wiki]

property name: str¶: Project name — always known, no API call.

property org: Organization¶: Organisation this project belongs to — zero-cost.

property pipelines: ProjectPipelines¶: The Pipelines section — builds, runs, approvals, environments, agents.

refresh()¶

Discard cached project info and stale child-scope cache entries.

The next access to info or id re-fetches from the API. All Repository and Pipeline objects cached under this project are also removed from the service cache so they are recreated fresh on next access.

Return type:: None

property repos: ProjectRepos¶: The Repos section — repositories, pull requests, branches, tags.

property search: ProjectSearch¶: Project-scoped search (code, work items, wiki, packages).

property settings: ProjectSettings¶: The Settings section — project-level configuration.

Settings¶

Azure DevOps project settings OOP layer.

class pyado.oop.settings.ProjectSettings(project)¶

The Settings section of a project.

Accessed via project.settings. Exposes project-level configuration, branch policies, process template information, and metadata operations.

Parameters:: project (Project)

_project¶: The owning Project.

create_policy_configuration(request)¶

Create a new branch policy configuration in this project.

Parameters:: request (PolicyConfigurationRequest) – Request specifying the type, settings, and blocking flag.
Returns:: PolicyConfiguration wrapping the newly created configuration.
Return type:: PolicyConfiguration

get_policy_configuration(config_id)¶

Return a specific branch policy configuration by numeric ID.

Parameters:: config_id (int) – PolicyConfigurationId of the policy configuration.
Returns:: PolicyConfiguration wrapping the requested configuration.
Return type:: PolicyConfiguration

get_policy_type(type_id)¶

Return a specific policy type by UUID.

Parameters:: type_id (UUID) – UUID of the policy type.
Returns:: The matching PolicyType.
Return type:: PolicyType

get_process_info()¶

Return the process template for this project.

Fetches the project with capabilities to discover the template type ID, then collects all process sub-resources.

Returns:: ProcessDetail with all sub-resources populated.
Raises:: ValueError – If the project capabilities are not available.
Return type:: ProcessDetail

get_project_info()¶

Return the raw project information record.

Returns:: ProjectInfo for this project.
Return type:: ProjectInfo

iter_policy_configurations()¶

Iterate over all branch policy configurations in this project.

Yields:: PolicyConfiguration for each configured policy.
Return type:: Iterator[PolicyConfiguration]

iter_policy_types()¶

Iterate over all available policy types in this project.

Yields:: PolicyType for each available policy type.
Return type:: Iterator[PolicyType]

list_policy_configurations()¶

Return all branch policy configurations as a list.

Return type:: list[PolicyConfiguration]

list_policy_types()¶

Return all available policy types in this project as a list.

Return type:: list[PolicyType]

class pyado.oop.settings.ServiceEndpoint(project, info)¶

An ADO service connection.

Wraps a single ADO service endpoint (service connection). Instances are obtained from ProjectPipelines.iter_service_endpoints().

Parameters:

project (Project)
info (ServiceEndpointInfo)

_project¶: The Project this service endpoint belongs to.

_id¶: Service endpoint UUID (always known).

_info¶: Cached service endpoint data; None after refresh().

property authorization_scheme: str | None¶: Authorization scheme (e.g. "Token", "UsernamePassword").

delete()¶

Delete this service endpoint from the current project.

Removes the endpoint from project. The deletion is permanent and cannot be undone via the API.

Return type:: None

property id: UUID¶: Service endpoint UUID — always known, no API call.

property info: ServiceEndpointInfo¶

Full service endpoint data as returned by the API.

Fetched lazily by re-querying the endpoint list if refresh() was called since the last access.

Raises:: KeyError – If no service endpoint with this ID is found in the project.

property is_ready: bool¶: Whether the service endpoint is ready for use.

property is_shared: bool¶: Whether the service endpoint is shared across projects.

property name: str¶: Service endpoint name.

property org: Organization¶: Organisation this service endpoint belongs to — zero-cost.

property project: Project¶: Project this service endpoint belongs to — zero-cost.

refresh()¶

Discard cached service endpoint info.

The next access to info re-fetches from the endpoint list.

Return type:: None

share(project_references)¶

Share this service endpoint with additional projects.

Parameters:: project_references (list[ServiceEndpointProjectReference]) – Project references describing each project to share the endpoint with and the name to use in each project.
Return type:: None

property type: str¶: Service endpoint type (e.g. "github", "azurerm").

update(request)¶

Update this service endpoint.

Sends a PUT to the organisation-scoped endpoint and refreshes the cached info with the API response.

Parameters:: request (ServiceEndpointUpdateRequest) – Update request. The id field must match this endpoint’s id.
Return type:: None

property url: str¶: Service endpoint target URL.

Service Endpoint¶

OOP wrapper for Azure DevOps service connection (endpoint) resources.

class pyado.oop.settings.service_endpoint.ServiceEndpoint(project, info)¶

An ADO service connection.

Wraps a single ADO service endpoint (service connection). Instances are obtained from ProjectPipelines.iter_service_endpoints().

Parameters:

project (Project)
info (ServiceEndpointInfo)

_project¶: The Project this service endpoint belongs to.

_id¶: Service endpoint UUID (always known).

_info¶: Cached service endpoint data; None after refresh().

property authorization_scheme: str | None¶: Authorization scheme (e.g. "Token", "UsernamePassword").

delete()¶

Delete this service endpoint from the current project.

Removes the endpoint from project. The deletion is permanent and cannot be undone via the API.

Return type:: None

property id: UUID¶: Service endpoint UUID — always known, no API call.

property info: ServiceEndpointInfo¶

Full service endpoint data as returned by the API.

Fetched lazily by re-querying the endpoint list if refresh() was called since the last access.

Raises:: KeyError – If no service endpoint with this ID is found in the project.

property is_ready: bool¶: Whether the service endpoint is ready for use.

property is_shared: bool¶: Whether the service endpoint is shared across projects.

property name: str¶: Service endpoint name.

property org: Organization¶: Organisation this service endpoint belongs to — zero-cost.

property project: Project¶: Project this service endpoint belongs to — zero-cost.

refresh()¶

Discard cached service endpoint info.

The next access to info re-fetches from the endpoint list.

Return type:: None

share(project_references)¶

Share this service endpoint with additional projects.

Parameters:: project_references (list[ServiceEndpointProjectReference]) – Project references describing each project to share the endpoint with and the name to use in each project.
Return type:: None

property type: str¶: Service endpoint type (e.g. "github", "azurerm").

update(request)¶

Update this service endpoint.

Sends a PUT to the organisation-scoped endpoint and refreshes the cached info with the API response.

Parameters:: request (ServiceEndpointUpdateRequest) – Update request. The id field must match this endpoint’s id.
Return type:: None

property url: str¶: Service endpoint target URL.

Search¶

OOP search wrappers for the Azure DevOps Search API.

class pyado.oop.core.search.OrganizationSearch(service)¶

Org-wide search via the Azure DevOps Search API.

ADO concept: the ADO Search API (almsearch.dev.azure.com/{org}/_apis/search/) allows full-text search across code, work items, wiki pages, and packages at the organisation level. Results can be filtered to specific projects via filters.

Why it exists: bundles the service reference and constructs the org-scoped search API call automatically so callers don’t need to manage the different hostname.

Instances are obtained from organization.search or service.org.search.

Parameters:: service (AzureDevOpsService)

_service¶: The AzureDevOpsService that owns this search scope.

search_code(request)¶

Search for code across the organisation.

Parameters:: request (CodeSearchRequest) – Search request parameters (text, filters, paging, etc.).
Yields:: CodeSearchResult for each matching code file.
Return type:: Iterator[CodeSearchResult]

search_packages(request)¶

Search for packages across the organisation.

Parameters:: request (SearchRequest) – Search request parameters.
Yields:: PackageSearchResult for each matching package.
Return type:: Iterator[PackageSearchResult]

search_wiki(request)¶

Search for wiki pages across the organisation.

Parameters:: request (SearchRequest) – Search request parameters.
Yields:: WikiSearchResult for each matching wiki page.
Return type:: Iterator[WikiSearchResult]

search_work_items(request)¶

Search for work items across the organisation.

Parameters:: request (SearchRequest) – Search request parameters.
Yields:: WorkItemSearchResult for each matching work item.
Return type:: Iterator[WorkItemSearchResult]

class pyado.oop.core.search.ProjectSearch(project)¶

Project-scoped search via the Azure DevOps Search API.

ADO concept: the ADO Search API supports project-scoped search at almsearch.dev.azure.com/{org}/{project}/_apis/search/. Results are automatically restricted to the owning project.

Why it exists: bundles the project reference and constructs the project-scoped search API call automatically.

Instances are obtained from project.search.

Parameters:: project (Project)

_project¶: The Project that owns this search scope.

search_code(request)¶

Search for code within this project.

Parameters:: request (CodeSearchRequest) – Search request parameters.
Yields:: CodeSearchResult for each matching code file.
Return type:: Iterator[CodeSearchResult]

search_packages(request)¶

Search for packages within this project.

Parameters:: request (SearchRequest) – Search request parameters.
Yields:: PackageSearchResult for each matching package.
Return type:: Iterator[PackageSearchResult]

search_wiki(request)¶

Search for wiki pages within this project.

Parameters:: request (SearchRequest) – Search request parameters.
Yields:: WikiSearchResult for each matching wiki page.
Return type:: Iterator[WikiSearchResult]

search_work_items(request)¶

Search for work items within this project.

Parameters:: request (SearchRequest) – Search request parameters.
Yields:: WorkItemSearchResult for each matching work item.
Return type:: Iterator[WorkItemSearchResult]

Repos¶

Repos section of the Azure DevOps OOP layer.

Exposes ProjectRepos — the project.repos section object — plus re-exports of all resource classes in this sub-package.

class pyado.oop.repos.AddFile(ado_path, content)¶

A file-add change for use in a push commit.

Creates a new file at the given repository path. The file must not already exist on the target branch; use EditFile to update an existing file.

Content can be supplied as a string (UTF-8 text), bytes (stored as Base64), or a local Path whose contents are read eagerly on construction. Binary paths are stored as Base64; text paths are stored as raw text.

Parameters:

ado_path (str)
content (str | bytes | Path)

_ado_path¶: Repository-root-relative destination path.

_new_content¶: Resolved content model ready for the push payload.

to_git_change()¶

Return the equivalent GitPushChange model.

Return type:: GitPushChange

class pyado.oop.repos.Branch(repo, ref)¶

A git branch in an Azure DevOps repository.

Wraps a GitRef for a refs/heads/… ref and exposes branch-specific convenience methods. Instances are obtained from ProjectRepos.iter_branches() or Repository.iter_branches().

Parameters:

repo (Repository)
ref (GitRef)

_repo¶: The Repository this branch belongs to.

_ref¶: The underlying GitRef data.

property commit_id: str¶: Current HEAD commit SHA of the branch.

delete()¶

Delete this branch from the repository.

Uses the stored commit SHA as the optimistic-concurrency guard.

Return type:: None

property full_name: str¶: Full ref name (e.g. "refs/heads/main").

get_commit()¶

Return the HEAD commit of this branch.

Returns:: Commit at the tip of this branch.
Return type:: Commit

property name: str¶: Short branch name (refs/heads/ prefix stripped).

property ref: GitRef¶: Underlying GitRef data.

property repo: Repository¶: Repository this branch belongs to — zero-cost.

class pyado.oop.repos.Commit(repo, info)¶

An Azure DevOps git commit.

Wraps a GitCommitRef and exposes its data as properties. Instances are obtained from Repository.get_commit() or Repository.iter_commits().

Parameters:

repo (Repository)
info (GitCommitRef)

_repo¶: The Repository this commit belongs to.

_info¶: The commit data returned from the API.

property author_date: datetime | None¶: UTC datetime the commit was authored, or None.

property author_email: str | None¶: Email of the commit author, or None if not in the API response.

property author_name: str | None¶: Name of the commit author, or None if not present in the API response.

property committer_date: datetime | None¶: UTC datetime the commit was applied, or None.

property committer_email: str | None¶: Email of the committer, or None if not present in the API response.

property committer_name: str | None¶: Name of the committer, or None if not present in the API response.

get_file(path)¶

Return the content of a file at this commit.

Parameters:: path (str) – Absolute file path within the repository (e.g. "/src/foo.py").
Returns:: File content as a UTF-8 string, or "" if the file is absent.
Return type:: str

get_pull_request()¶

Return the first active PR whose source branch contains this commit.

Delegates to Repository.get_pr_for_commit().

Returns:: PullRequest for the first active PR containing this commit, or None if no such PR exists.
Return type:: PullRequest | None

property info: GitCommitRef¶: Commit data captured at construction time.

iter_changes()¶

Iterate over files changed by this commit.

Uses the first parent commit as the diff base. Yields nothing for root commits (no parents).

Yields:: GitCommitChange for each changed file.
Return type:: Iterator[GitCommitChange]

list_changes()¶

Return all file changes in this commit as a list.

Return type:: list[GitCommitChange]

list_statuses()¶

Return the CI statuses attached to this commit.

Statuses are populated when the commit was fetched via an endpoint that includes status data. Call Repository.get_commit() (which uses get_commit_by_id) to ensure statuses are included.

Returns:: List of GitStatus objects; empty when none are present.
Return type:: list[GitStatus]

property message: str | None¶

Commit message; may be truncated for long messages.

Check comment_truncated on info to detect truncation.

property org: Organization¶: Organisation this commit belongs to — zero-cost.

property project: Project¶: Project this commit belongs to — zero-cost.

refresh(search_criteria=None)¶

Discard cached commit info.

The next access to info re-fetches from the API.

Parameters:: search_criteria (GitCommitSearchCriteria | None) – Optional search criteria to use on the next fetch. When provided, replaces any previously stored criteria; when None, previously stored criteria are preserved.
Return type:: None

property repo: Repository¶: Repository this commit belongs to — zero-cost.

property sha: str¶: Commit SHA (40-character hex string).

class pyado.oop.repos.DeleteFile(ado_path)¶

A file-delete change for use in a push commit.

Removes an existing file from the repository. The file must exist on the target branch.

Parameters:: ado_path (str)

_ado_path¶: Repository-root-relative path of the file to delete.

to_git_change()¶

Return the equivalent GitPushChange model.

Return type:: GitPushChange

class pyado.oop.repos.EditFile(ado_path, content)¶

A file-edit change for use in a push commit.

Replaces the full content of an existing file. The file must already exist on the target branch; use AddFile to create a new file.

Content can be supplied as a string (UTF-8 text), bytes (stored as Base64), or a local Path whose contents are read eagerly on construction.

Parameters:

ado_path (str)
content (str | bytes | Path)

_ado_path¶: Repository-root-relative path of the file to update.

_new_content¶: Resolved content model ready for the push payload.

to_git_change()¶

Return the equivalent GitPushChange model.

Return type:: GitPushChange

class pyado.oop.repos.PolicyConfiguration(project, info)¶

An ADO branch policy configuration.

Also exported from pyado directly as pyado.PolicyConfiguration. The underlying raw Pydantic model is pyado.PolicyConfigurationInfo.

Wraps a single branch policy configuration and exposes read, update, and delete operations. Instances are obtained from ProjectSettings.iter_policy_configurations() or ProjectSettings.get_policy_configuration().

Parameters:

project (Project)
info (PolicyConfigurationInfo)

_project¶: The Project this policy configuration belongs to.

_id¶: Numeric configuration ID (always known).

_info¶: Cached policy configuration data; None after refresh().

property api_call: ApiCall¶: Policy-configuration-level API call for use with raw functions.

property created_by: PolicyCreatedBy | None¶: Identity reference of the creator.

delete()¶

Delete this policy configuration from the project.

Return type:: None

property id: int¶: Numeric policy configuration ID — always known, no API call.

property info: PolicyConfigurationInfo¶

Full policy configuration data as returned by the API.

Fetched lazily from the API if refresh() was called since the last access.

property is_blocking: bool¶: Whether this policy blocks completion when violated.

property is_enabled: bool¶: Whether this policy configuration is enabled.

property org: Organization¶: Organisation this configuration belongs to — zero-cost.

property project: Project¶: Project this configuration belongs to — zero-cost.

refresh()¶

Discard cached policy configuration info.

The next access to info re-fetches from the API.

Return type:: None

property revision: int | None¶: Policy configuration revision number.

property type: PolicyType¶: Policy type definition.

update(request)¶

Update this policy configuration with new settings.

Parameters:: request (PolicyConfigurationRequest) – Updated settings for the policy configuration.
Return type:: None

class pyado.oop.repos.ProjectRepos(project)¶

The Repos section of a project.

Accessed via project.repos. Exposes all repository and pull-request operations that belong to the ADO Repos section.

Parameters:: project (Project)

_project¶: The owning Project.

get_pull_request(pr_id, repo_id=None)¶

Return a PR wrapper by ID.

When repo_id is provided, the PR is fetched directly from the repository-scoped endpoint (one API call). When omitted, a project-wide search is performed instead.

Parameters:

pr_id (int) – Numeric pull request ID.
repo_id (UUID | None) – Optional repository UUID. When supplied, the direct lookup path is used; when omitted the project-wide searchCriteria.pullRequestId search is used.

Returns:

PullRequest wrapping the matched PR.

Raises:

KeyError – If no PR with pr_id exists in this project.

Return type:

PullRequest

get_repository(name)¶

Return a wrapper for a repository by name.

Parameters:: name (str) – Repository name (case-sensitive).
Returns:: Repository wrapping the matched repository.
Raises:: KeyError – If no repository with the given name is found.
Return type:: Repository

get_repository_by_id(repo_id)¶

Return a wrapper for a repository by UUID.

Parameters:: repo_id (UUID) – Repository UUID.
Returns:: Repository wrapping the matched repository.
Raises:: KeyError – If no repository with the given ID is found.
Return type:: Repository

iter_active_prs(*, expand=None)¶

Iterate over all active pull requests in the project.

Convenience shortcut for iter_pull_requests(status=PullRequestStatus.ACTIVE).

Parameters:: expand (str | None) – Optional $expand value (e.g. "labels", "reviewers").
Yields:: PullRequest for each active PR, in API-returned order.
Return type:: Iterator[PullRequest]

iter_branches(repo_name)¶

Iterate over branches in a named repository.

Parameters:: repo_name (str) – Repository name (case-sensitive).
Yields:: Branch for each branch.
Return type:: Iterator[Branch]

iter_git_tags(repo_name)¶

Iterate over git tags in a named repository.

Parameters:: repo_name (str) – Repository name (case-sensitive).
Yields:: Tag for each tag.
Return type:: Iterator[Tag]

iter_pull_requests(status=None, *, criteria=None, expand=None)¶

Iterate over pull requests across all repositories in the project.

Parameters:

status (PullRequestStatus | None) – Filter by PR lifecycle status. When None (default), all PRs are returned regardless of status. Ignored when criteria is provided.
criteria (PullRequestSearchCriteria | None) – Full search criteria; overrides status when provided.
expand (str | None) – Optional $expand value (e.g. "labels", "reviewers").

Yields:

PullRequest for each matching PR, in API-returned order.

Return type:

Iterator[PullRequest]

iter_repositories()¶

Iterate over all repositories in the project.

Each yielded Repository is cached in the service so that repeated access returns the same instance.

Yields:: Repository for each repository in the project.
Return type:: Iterator[Repository]

list_active_prs(*, expand=None)¶

Return all active pull requests in the project as a list.

Parameters:: expand (str | None)
Return type:: list[PullRequest]

list_branches(repo_name)¶

Return all branches in a named repository as a list.

Parameters:: repo_name (str)
Return type:: list[Branch]

list_git_tags(repo_name)¶

Return all git tags in a named repository as a list.

Parameters:: repo_name (str)
Return type:: list[Tag]

list_pull_requests(status=None, *, criteria=None, expand=None)¶

Return all pull requests in the project as a list.

Parameters:

status (PullRequestStatus | None)
criteria (PullRequestSearchCriteria | None)
expand (str | None)

Return type:

list[PullRequest]

list_repositories()¶

Return all repositories in the project as a list.

Return type:: list[Repository]

class pyado.oop.repos.PullRequest(repo, pr_api_call, info, expand=None)¶

An Azure DevOps pull request resource.

Wraps a single ADO pull request and exposes its operations as instance methods. Instances are obtained from Repository.get_pull_request(), Repository.iter_pull_requests(), or Repository.create_pull_request().

Pull requests are not cached — each factory call returns a fresh instance. Call refresh() to re-fetch the info from the API at any time.

The info attribute holds either a PullRequestListItem (when obtained via a list endpoint) or a PullRequestResponse (when freshly created), reflecting the data available at construction time.

Parameters:

repo (Repository)
pr_api_call (ApiCall)
info (PullRequestListItem | PullRequestResponse)
expand (str | None)

_repo¶: The Repository this pull request belongs to.

_api_call¶: PR-level API call used by all operations.

_info¶: PR data; type depends on how the instance was constructed.

abandon()¶

Abandon the pull request.

Return type:: None

add_reviewer(reviewer_id, *, is_required=False, is_reapprove=False)¶

Add or update a reviewer on the pull request.

Parameters:

reviewer_id (str) – Identity (object) ID of the reviewer.
is_required (bool) – When True the reviewer is marked as required.
is_reapprove (bool) – When True, the approval is processed even if the vote has not changed.

Return type:

None

add_tag(name)¶

Add a tag to the pull request.

Parameters:: name (str) – Tag name to add.
Return type:: None

Note

The ADO tag endpoints return no body, so this method returns None. Call get_tags() afterwards if you need the updated tag list.

add_thread(content, *, file_path=None, line=None, status=PullRequestThreadStatus.ACTIVE)¶

Create a new review thread on the pull request.

Parameters:

content (str) – Text content of the first comment.
file_path (str | None) – File path to anchor the thread to, or None for a PR-level thread.
line (int | None) – Line number within the file; only meaningful when file_path is set.
status (PullRequestThreadStatus) – Initial thread status (default: "active").

Returns:

The created PullRequestThreadResponse.

Return type:

PullRequestThreadCommentResponse

add_work_item_ref(wi_id)¶

Add a single work item to the pull request’s work item refs.

Reads the current work item refs, adds wi_id if not already present, and writes the updated list back. The operation is idempotent — if wi_id is already linked, no PATCH is made.

This wraps iter_work_item_ids() and set_work_item_refs(): two API calls (one GET, one PATCH) when the item is not yet linked; one API call (GET only) when it is already present.

Parameters:: wi_id (int) – Numeric ID of the work item to add.
Return type:: None

property api_call: ApiCall¶: PR-level API call for direct use with pyado.raw functions.

complete(last_merge_source_commit, *, completion_options=None)¶

Complete (merge) the pull request.

Parameters:

last_merge_source_commit (str) – Current HEAD SHA of the source branch. Used by ADO as an optimistic-concurrency guard; obtain it from pr.info.last_merge_source_commit.commit_id after a refresh().
completion_options (PullRequestCompletionOptions | None) – Merge strategy and post-completion options. Defaults to squash merge with source-branch deletion.

Return type:

None

property created_by: str | None¶

Display name of the user who created the PR, or None.

For the full identity (id, unique name), use pr.info.created_by.

property description: str | None¶: Pull request description body, or None if not set.

disable_auto_complete()¶

Disable auto-complete on the pull request.

Clears the auto-complete setter so the PR will no longer be merged automatically when policies pass. Has no effect if auto-complete was not set. ADO requires an all-zeros GUID to unset auto-complete.

Return type:: None

enable_auto_complete(identity_id=None, *, completion_options=None)¶

Enable auto-complete on the pull request.

When auto-complete is set, ADO will automatically complete (merge) the PR once all required reviewers have approved and all policies pass.

Parameters:

identity_id (str | None) – Object ID of the identity to record as the auto-complete setter. When None (the default), the authenticated user’s identity is resolved via get_connection_data and used automatically.
completion_options (PullRequestCompletionOptions | None) – Merge strategy and post-completion options. When None, ADO retains the existing options.

Return type:

None

get_iteration_changes(iteration_id)¶

Return the file changes introduced by a specific PR iteration.

Parameters:: iteration_id (int) – The 1-based iteration number. Obtain it from iter_iterations().
Returns:: List of PullRequestIterationChange entries for the iteration.
Return type:: list[PullRequestIterationChange]

get_thread(thread_id)¶

Return a single review thread by ID.

Parameters:: thread_id (int) – Numeric ID of the thread to fetch. Obtain it from iter_threads().
Returns:: PullRequestThreadResponse for the requested thread.
Return type:: PullRequestThreadResponse

property id: int¶: Numeric pull request ID.

property info: PullRequestListItem | PullRequestResponse¶: PR data captured at construction time (or last refresh).

iter_commits()¶

Iterate over commits included in the pull request.

Yields:: Commit for each commit reachable from the PR.
Return type:: Iterator[Commit]

iter_files_changed()¶

Iterate over files changed in this pull request.

Fetches the latest iteration (one API call) and then returns its changes, which represent the full diff from the merge base to the current source branch HEAD. This is the equivalent of the “Files” tab in the ADO pull request UI.

Yields:: PullRequestIterationChange for each changed file.
Return type:: Iterator[PullRequestIterationChange]

iter_iterations()¶

Iterate over the push iterations of this pull request.

Each iteration corresponds to a force-push or new commit push to the source branch. Use get_iteration_changes() to retrieve the file-level diff introduced by a specific iteration.

Yields:: PullRequestIterationRecord for each iteration, oldest first.
Return type:: Iterator[PullRequestIterationRecord]

iter_statuses()¶

Iterate over status checks posted on this pull request.

Yields:: PullRequestStatusInfo for each status item, in API-returned order.
Return type:: Iterator[PullRequestStatusInfo]

iter_tag_details()¶

Iterate over full tag objects for all tags set on the pull request.

Use this instead of iter_tags() when you need the tag ID, URL, or active status, not just the name string.

Yields:: PullRequestLabel for each tag set on the pull request.
Return type:: Iterator[PullRequestLabel]

iter_tags()¶

Iterate over the tag names set on the pull request.

Yields:: Tag name strings; nothing when no tags are set.
Return type:: Iterator[str]

iter_threads()¶

Iterate over all review threads on the pull request.

Yields:: PullRequestThreadResponse for each thread.
Return type:: Iterator[PullRequestThreadResponse]

iter_work_item_ids()¶

Iterate over work item IDs linked to the pull request.

Yields:: Integer work item IDs associated with the PR.
Return type:: Iterator[int]

iter_work_items()¶

Iterate over work items linked to the pull request.

Convenience wrapper that resolves the linked IDs via iter_work_item_ids() and then fetches the work item details in a single batch call.

Yields:: WorkItem for each linked work item.
Return type:: Iterator[WorkItem]

link_work_item(work_item, *, comment=None)¶

Link this pull request to a work item via an ArtifactLink relation.

Adds the PR as an ArtifactLink relation on the work item so that the association appears in both the PR timeline and the work item links.

Parameters:

work_item (WorkItem) – The WorkItem to link to this pull request.
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

list_commits()¶

Return all commits in this pull request as a list.

Return type:: list[Commit]

list_files_changed()¶

Return all files changed in this pull request as a list.

Return type:: list[PullRequestIterationChange]

list_iterations()¶

Return all iterations for this pull request as a list.

Return type:: list[PullRequestIterationRecord]

list_reviewers()¶

Return all reviewers on the pull request.

Returns:: List of PullRequestReviewer entries.
Return type:: list[PullRequestReviewer]

list_statuses()¶

Return all status checks on this pull request as a list.

Return type:: list[PullRequestStatusInfo]

list_tag_details()¶

Return full tag objects for all tags set on the pull request.

Return type:: list[PullRequestLabel]

list_tags()¶

Return all tag names set on this pull request as a list.

Return type:: list[str]

list_threads()¶

Return all review threads on this pull request as a list.

Return type:: list[PullRequestThreadResponse]

list_work_item_ids()¶

Return all linked work item IDs as a list.

Return type:: list[int]

list_work_items()¶

Return all linked work items as a list.

Return type:: list[WorkItem]

property org: Organization¶: Organisation this pull request belongs to — zero-cost.

property project: Project¶: Project this pull request belongs to — zero-cost.

refresh(expand=None)¶

Discard cached pull request info.

The next access to info re-fetches from the API.

Parameters:: expand (str | None) – $expand value to use on the next fetch. When None (default), re-uses the expand value from construction or the last explicit refresh call. When provided, updates the stored expand so subsequent bare refresh() calls use it.
Return type:: None

remove_reviewer(reviewer_id)¶

Remove a reviewer from the pull request.

Parameters:: reviewer_id (str) – Identity (object) ID of the reviewer.
Return type:: None

remove_tag(name)¶

Remove a tag from the pull request.

Parameters:: name (str) – Tag name to remove.
Return type:: None

Note

The ADO tag endpoints return no body, so this method returns None. Call get_tags() afterwards if you need the updated tag list.

reply_to_thread(thread_id, content, *, parent_comment_id=1)¶

Add a reply to an existing review thread.

Parameters:

thread_id (int) – ID of the thread to reply to.
content (str) – Text content of the reply.
parent_comment_id (int) – ID of the comment being replied to (default: 1, the thread’s first comment).

Returns:

The created PullRequestThreadCommentResponse.

Return type:

property repo: Repository¶: Repository this pull request belongs to — zero-cost.

set_status(state, context_name, *, description=None, iteration_id=1, target_url=None, genre=None)¶

Post a status check result on the pull request.

Parameters:

state (PullRequestStatusState) – Status state to report.
context_name (str) – Unique name for the status context (e.g. the CI check name).
description (str | None) – Optional human-readable description.
iteration_id (int) – PR iteration the status applies to (default: 1).
target_url (str | None) – Optional URL to link to for details.
genre (str | None) – Optional genre grouping for the context.

Return type:

None

set_work_item_refs(work_item_ids)¶

Set the work items visible on the pull request page.

Replaces the PR’s workItemRefs list so the given work items appear in the ADO pull request UI. To also add the reverse link on the work item side, call link_work_item() for each item.

Parameters:: work_item_ids (list[int]) – Numeric IDs of the work items to associate.
Return type:: None

property source_branch: str | None¶: Source ref name (e.g. "refs/heads/feature/my-branch").

property status: PullRequestStatus | None¶: Pull request lifecycle status (e.g. "active", "completed").

sync_tags(desired)¶

Synchronise the PR tags to match desired.

Adds missing tags and removes extras so the final set matches desired exactly. When the object was constructed or last refreshed with an expand that includes "labels", the tags cached in _info are used and the GET /labels call is skipped entirely.

Parameters:: desired (set[str]) – The exact set of tag names the PR should have after the call.
Return type:: None

property target_branch: str | None¶: Target ref name (e.g. "refs/heads/main").

property title: str | None¶: Pull request title.

update(*, title=None, description=None, status=None, is_draft=None)¶

Update pull request metadata.

Only non-None arguments are sent to ADO.

Parameters:

title (str | None) – New PR title.
description (str | None) – New PR description.
status (PullRequestStatus | None) – New PR status ("active", "abandoned", or "completed").
is_draft (bool | None) – Set or clear the draft flag.

Return type:

None

update_thread_status(thread_id, status)¶

Update the status of an existing review thread.

Parameters:

thread_id (int) – Numeric ID of the thread to update. Obtain it from iter_threads().
status (PullRequestThreadStatus) – New status for the thread (e.g. PullRequestThreadStatus.FIXED).

Returns:

Updated PullRequestThreadResponse reflecting the new status.

Return type:

vote(reviewer_id, vote, *, is_reapprove=False)¶

Cast a reviewer vote on the pull request.

Parameters:

reviewer_id (str) – Identity ID of the reviewer casting the vote.
vote (PullRequestVote) – Vote value to submit.
is_reapprove (bool) – When True, the approval is processed even if the vote has not changed.

Return type:

None

class pyado.oop.repos.RenameFile(old_ado_path, new_ado_path)¶

A file-rename change for use in a push commit.

Moves a file to a new path without altering its content. Both the source and destination paths must be valid on the target branch.

Parameters:

old_ado_path (str)
new_ado_path (str)

_old_ado_path¶: Current repository-root-relative path.

_new_ado_path¶: Desired repository-root-relative path after rename.

to_git_change()¶

Return the equivalent GitPushChange model.

Return type:: GitPushChange

class pyado.oop.repos.Repository(project, repository_api_call, info, service)¶

An Azure DevOps Git repository resource.

Wraps a single ADO repository and exposes its operations as instance methods. Instances are obtained from ProjectRepos.iter_repositories() or ProjectRepos.get_repository().

Repositories are cached in the service — the same instance is returned on repeated access. Call refresh() to re-fetch the info from the API.

Parameters:

project (Project)
repository_api_call (ApiCall)
info (RepositoryInfo)
service (AzureDevOpsService)

_project¶: The Project this repository belongs to.

_service¶: The owning AzureDevOpsService (for org-level API calls).

_api_call¶: Repository-level API call used by all git operations.

_info¶: The repository data returned from the API at construction time.

property api_call: ApiCall¶: Repository-level API call for direct use with pyado.raw functions.

check_branch_exists(name)¶

Return True if the branch exists in this repository.

Parameters:: name (str) – Short branch name (e.g. "main") or full ref (e.g. "refs/heads/main").
Returns:: True if the branch exists, False otherwise.
Return type:: bool

check_file_exists_by_branch(path, branch=None)¶

Return True if a file exists at the tip of a branch.

Thin boolean wrapper over get_item_by_branch(). Fetches metadata only (no file content), so this is cheap.

Parameters:

path (str) – Absolute file path within the repository.
branch (str | None) – Short branch name or full ref. None → repository default branch.

Returns:

True if the file exists, False otherwise.

Return type:

bool

check_file_exists_by_commit(path, commit)¶

Return True if a file exists at a specific commit.

Thin boolean wrapper over get_item_by_commit(). Fully immutable — the result will not change for the same commit SHA.

Parameters:

path (str) – Absolute file path within the repository.
commit (str) – Commit SHA to resolve the file at.

Returns:

True if the file exists, False otherwise.

Return type:

bool

check_file_exists_by_ref(path, ref)¶

Return True if a file exists at an arbitrary ref.

Thin boolean wrapper over get_item_by_ref().

Parameters:

path (str) – Absolute file path within the repository.
ref (str) – Arbitrary full git ref string.

Returns:

True if the file exists, False otherwise.

Return type:

bool

check_file_exists_by_tag(path, tag)¶

Return True if a file exists at a tagged version.

Thin boolean wrapper over get_item_by_tag(). Note that lightweight tags are mutable; see get_item_by_tag().

Parameters:

path (str) – Absolute file path within the repository.
tag (str) – Short tag name or full ref.

Returns:

True if the file exists, False otherwise.

Return type:

bool

check_merge_feasible(source, target, *, timeout=10.0, poll_interval=0.5)¶

Return True if source can be merged into target without conflicts.

Queues a merge via ADO and polls until the operation reaches a terminal status or timeout seconds elapse. Returns True for COMPLETED, False for CONFLICTS or FAILURE.

Parameters:

source (str) – Commit SHA of the source branch tip.
target (str) – Commit SHA of the target branch tip.
timeout (float) – Maximum number of seconds to wait for ADO to complete the merge check. Defaults to 10 s.
poll_interval (float) – Seconds between poll attempts. Defaults to 0.5 s.

Returns:

True if the merge can be applied cleanly, False if it cannot.

Raises:

AzureDevOpsNotFoundError – If either commit SHA is not found by ADO (INVALID_REFS status).
TimeoutError – If the operation is still QUEUED after timeout seconds.

Return type:

bool

commit(branch, message, changes, current_commit=None)¶

Push a single commit to an existing branch.

When current_commit is supplied it is used directly as the optimistic-concurrency guard (zero extra API calls). When omitted, the branch’s current HEAD SHA is fetched automatically via GET /refs (one extra call).

Parameters:

branch (str | None) – Short branch name (e.g. "main"). None → repository default branch.
message (str) – Commit message.
changes (list[AddFile | EditFile | DeleteFile | RenameFile]) – One or more file changes to include in the commit. Use AddFile, EditFile, DeleteFile, or RenameFile.
current_commit (str | None) – Current HEAD SHA of the branch used for the optimistic-concurrency check. None → fetched automatically.

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

Example:

repo.commit("main", "Update config", [
    EditFile("/config.json", "{}"),
    DeleteFile("/old_config.json"),
])

commit_file_delete(branch, path, message)¶

Delete a file from a branch in a single commit.

Parameters:

branch (str) – Short branch name (e.g. "main").
path (str) – Absolute file path within the repository (e.g. "/config.json").
message (str) – Commit message.

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

commit_file_rename(branch, old_path, new_path, message)¶

Rename (move) a file on a branch in a single commit.

Parameters:

branch (str) – Short branch name (e.g. "main").
old_path (str) – Current absolute file path within the repository.
new_path (str) – New absolute file path within the repository.
message (str) – Commit message.

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

commit_file_upsert(branch, path, content, message, current_commit=None)¶

Create or update a single file on a branch in one commit.

Detects whether the file already exists (using check_file_exists_by_branch()) and applies an EditFile change if it does, or an AddFile change if it does not. Unlike the _by_branch read methods, branch here accepts None which also resolves to the repository’s default branch — consistent with the read API.

Note: unlike the _by_branch read methods, writing always targets a specific branch; there is no tag or commit variant because git objects are immutable after creation.

current_commit supports optimistic concurrency: supply the HEAD SHA you observed to ensure ADO rejects the push if a concurrent write landed in the meantime; omit to let commit() fetch the current HEAD automatically.

Parameters:

branch (str | None) – Target branch name. None → repository default branch.
path (str) – Absolute file path within the repository.
content (str) – New UTF-8 text content for the file.
message (str) – Commit message.
current_commit (str | None) – Current HEAD SHA for optimistic-concurrency. None → fetched automatically.

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

create_annotated_tag(name, message, commit_sha)¶

Create an annotated tag in this repository.

An annotated tag is a full git object (not just a lightweight ref pointer) and carries a message and tagger identity. Use create_git_tag() for lightweight tags.

Parameters:

name (str) – Tag name without refs/tags/ prefix (e.g. "v1.0").
message (str) – Annotation message for the tag.
commit_sha (str) – Commit SHA the tag should point at.

Returns:

AnnotatedTagInfo describing the newly created annotated tag.

Return type:

create_branch(name, from_commit)¶

Create a new branch pointing at an existing commit.

Parameters:

name (str) – Short branch name (e.g. "feature/my-branch"). A refs/heads/ prefix is added automatically if absent.
from_commit (str) – Commit SHA the new branch should point at.

Return type:

None

create_git_tag(name, commit_id)¶

Create a lightweight tag pointing at an existing commit.

Parameters:

name (str) – Short tag name (e.g. "v1.0"). A refs/tags/ prefix is added automatically if absent.
commit_id (str) – Commit SHA the tag should point at.

Return type:

None

create_pull_request(title, source_branch, target_branch, *, description=None, completion_options=None)¶

Create a new pull request in this repository.

Parameters:

title (str) – Title of the pull request.
source_branch (str) – Source branch name (e.g. "feature/my-branch" or full "refs/heads/feature/my-branch").
target_branch (str) – Target branch name (e.g. "main").
description (str | None) – Optional PR description.
completion_options (PullRequestCompletionOptions | None) – Merge and post-completion behaviour; defaults to squash merge with source-branch deletion.

Returns:

PullRequest wrapping the newly created PR.

Return type:

PullRequest

property default_branch: str | None¶: Default branch name (e.g. "refs/heads/main"), or None if unset.

delete_branch(name, current_commit=None)¶

Delete a branch from the repository.

When current_commit is supplied it is used directly as the optimistic-concurrency guard (zero extra API calls). When omitted, the current HEAD SHA is fetched automatically via get_branch_head() (one extra GET /refs call).

Parameters:

name (str) – Short branch name or full refs/heads/… name.
current_commit (str | None) – Current HEAD SHA of the branch. None → fetched automatically.

Return type:

None

delete_git_tag(name, commit_id)¶

Delete a git tag from the repository.

Parameters:

name (str) – Short tag name (e.g. "v1.0"). A refs/tags/ prefix is added automatically if absent.
commit_id (str) – Current object ID of the tag (optimistic-concurrency check).

Return type:

None

get_branch_head(name)¶

Return the current HEAD commit SHA of a branch.

Parameters:: name (str) – Short branch name (e.g. "main") or full ref (e.g. "refs/heads/main").
Returns:: Commit SHA string at the tip of the branch.
Raises:: AzureDevOpsNotFoundError – If the branch does not exist.
Return type:: str

get_cherry_pick_status(cherry_pick_id)¶

Return the current status of a queued cherry-pick operation.

Parameters:: cherry_pick_id (int) – The operation ID from start_cherry_pick().
Returns:: GitCherryPickResponse with the current status.
Return type:: GitCherryPickResponse

get_commit(sha)¶

Return a wrapper for a specific commit.

Parameters:: sha (str) – Commit SHA string.
Returns:: Commit wrapping the requested commit.
Return type:: Commit

get_default_branch_commit()¶

Return the HEAD commit of the default branch.

Convenience shortcut that avoids a separate iter_refs() call followed by get_commit().

Returns:: Commit at the tip of the default branch.
Raises:: AzureDevOpsNotFoundError – If the repository has no default branch configured, or if the default branch ref is not found (e.g. empty repository).
Return type:: Commit

get_file_by_branch(path, branch=None)¶

Return the content of a file from the tip of a branch.

Use when latest content is acceptable and mutability is not a concern. branch defaults to None, which resolves to the repository’s default branch (self.info.default_branch). The result is mutable and may differ between calls as the branch advances.

Parameters:

path (str) – Absolute file path within the repository (e.g. /foo.py).
branch (str | None) – Short branch name or full ref (e.g. "main" or "refs/heads/main"). None → repository default branch.

Returns:

File content as a UTF-8 string, or "" if the file is absent.

Return type:

str

get_file_by_commit(path, commit)¶

Return the content of a file at a specific commit.

Fully immutable. Use for reproducible references, audit trails, diffing, or any context where the result must not change.

Parameters:

path (str) – Absolute file path within the repository.
commit (str) – Commit SHA to resolve the file at.

Returns:

File content as a UTF-8 string, or "" if the file is absent.

Return type:

str

get_file_bytes_by_branch(path, branch=None)¶

Return the raw bytes of a file from the tip of a branch.

Use when latest content is acceptable and the file may contain non-UTF-8 data (e.g. images, compiled artefacts). branch defaults to None, which resolves to the repository’s default branch. The result is mutable and may differ between calls.

Parameters:

path (str) – Absolute file path within the repository (e.g. /img.png).
branch (str | None) – Short branch name or full ref. None → repository default branch.

Returns:

Raw file bytes, or None if the file does not exist.

Return type:

bytes | None

get_file_bytes_by_commit(path, commit)¶

Return the raw bytes of a file at a specific commit.

Fully immutable. Use when the file may contain non-UTF-8 data and the result must not change across calls.

Parameters:

path (str) – Absolute file path within the repository.
commit (str) – Commit SHA to resolve the file at.

Returns:

Raw file bytes, or None if the file does not exist.

Return type:

bytes | None

get_item_by_branch(path, branch=None)¶

Return metadata for a single file at the tip of a branch, or None.

Fetches metadata only (no file content), so this is cheap enough to use for existence checks. branch defaults to None, which resolves to the repository’s default branch. The result is mutable and may differ between calls as the branch advances.

Parameters:

path (str) – Absolute file path within the repository.
branch (str | None) – Short branch name or full ref. None → repository default branch.

Returns:

GitItem for the file, or None if it does not exist.

Return type:

GitItem | None

get_item_by_commit(path, commit)¶

Return metadata for a single file at a specific commit, or None.

Fully immutable. Use for reproducible references, audit trails, diffing, or any context where the result must not change.

Parameters:

path (str) – Absolute file path within the repository.
commit (str) – Commit SHA to resolve the file at.

Returns:

GitItem for the file, or None if it does not exist.

Return type:

GitItem | None

get_item_by_ref(path, ref)¶

Return metadata for a single file at an arbitrary ref, or None.

Escape hatch for refs outside the typed categories (e.g. pull-request merge refs "refs/pull/{id}/merge"). The ref is resolved to a commit SHA via the refs API before fetching the item.

Parameters:

path (str) – Absolute file path within the repository.
ref (str) – Arbitrary full git ref string (e.g. "refs/pull/42/merge").

Returns:

GitItem for the file, or None if the file does not exist at the ref.

Raises:

AzureDevOpsNotFoundError – If the ref cannot be resolved.

Return type:

GitItem | None

get_item_by_tag(path, tag)¶

Return metadata for a single file at a tagged version, or None.

Resolves to the tagged object. Note that lightweight tags are mutable (can be deleted and re-created pointing elsewhere); callers requiring true immutability should resolve the tag to a commit SHA first and use get_item_by_commit().

Parameters:

path (str) – Absolute file path within the repository.
tag (str) – Short tag name (e.g. "v1.0") or full ref (e.g. "refs/tags/v1.0"); the refs/tags/ prefix is stripped automatically.

Returns:

GitItem for the file, or None if it does not exist.

Return type:

GitItem | None

get_last_commit_touching_file(path, before_commit)¶

Return the most recent commit that touched a file at or before a commit.

Falls back to returning before_commit when no matching commit is found (e.g. the file did not exist at that point).

Parameters:

path (str) – Absolute file path within the repository (e.g. "/src/foo.py").
before_commit (str) – The commit SHA to search at or before.

Returns:

Commit SHA of the most recent touching commit, or before_commit.

Return type:

str

get_merge_status(merge_operation_id)¶

Return the current status of a queued merge operation.

Parameters:: merge_operation_id (int) – The operation ID from start_merge().
Returns:: GitMergeResponse with the current status.
Return type:: GitMergeResponse

get_pr_for_branch(source_branch)¶

Return the first active PR for the given source branch, or None.

Parameters:: source_branch (str) – Short branch name or full ref. A refs/heads/ prefix is added automatically when absent.
Returns:: PullRequest for the first active PR from that source branch, or None if none exists.
Return type:: PullRequest | None

get_pr_for_commit(sha)¶

Return the first active PR whose source branch contains sha, or None.

Uses searchCriteria.sourceVersion to restrict the search to PRs that include the given commit.

Parameters:: sha (str) – Commit SHA string to search for.
Returns:: PullRequest for the first active PR whose source version matches sha, or None if no such PR exists.
Return type:: PullRequest | None

get_pull_request(pull_request_id)¶

Return a wrapper for a specific pull request.

Parameters:: pull_request_id (int) – Numeric ID of the pull request.
Returns:: PullRequest wrapping the requested PR.
Return type:: PullRequest

get_revert_status(revert_id)¶

Return the current status of a queued revert operation.

Parameters:: revert_id (int) – The operation ID from start_revert().
Returns:: GitRevertResponse with the current status.
Return type:: GitRevertResponse

get_statistics(branch)¶

Return ahead/behind commit counts for a branch.

Parameters:: branch (str) – Branch name (e.g. "main" or "refs/heads/main").
Returns:: BranchStatistics with ahead/behind counts and the branch HEAD commit.
Return type:: BranchStatistics

property id: UUID¶: Repository UUID.

property info: RepositoryInfo¶: Repository data captured at construction time (or last refresh).

iter_branches()¶

Iterate over all branches (refs/heads/…) in the repository.

Convenience wrapper over iter_refs() that pre-applies the heads/ name filter so callers do not need to know the ADO ref filter format.

Yields:: Branch for each branch.
Return type:: Iterator[Branch]

iter_commit_diff(base_commit, target_commit)¶

Iterate over file changes between two commits.

Paginates automatically when the API returns partial results. Folder entries are excluded.

Parameters:

base_commit (str) – The older (base) commit SHA.
target_commit (str) – The newer (target) commit SHA.

Yields:

GitCommitChange for each changed file.

Return type:

Iterator[GitCommitChange]

iter_commits(*, item_path=None, top=None, branch=None)¶

Iterate over commits in the repository.

Parameters:

item_path (str | None) – When set, only commits that touched this file path are returned (e.g. "/src/foo.py").
top (int | None) – Maximum number of commits to return; None means no limit.
branch (str | None) – When set, only commits reachable from this branch are returned. Accepts a short name ("main") or a full ref ("refs/heads/main"); the refs/heads/ prefix is stripped automatically.

Yields:

Commit for each matching commit.

Return type:

Iterator[Commit]

iter_commits_by_commit(commit, *, item_path=None, top=None)¶

Iterate over commits reachable from a specific commit.

Fully immutable. Use for reproducible references, audit trails, or any context where the commit list must not change.

Parameters:

commit (str) – Commit SHA to search from.
item_path (str | None) – When set, only commits that touched this file path are returned.
top (int | None) – Maximum number of commits to return; None means no limit.

Yields:

Commit for each matching commit.

Return type:

Iterator[Commit]

iter_commits_by_tag(tag, *, item_path=None, top=None)¶

Iterate over commits reachable from a tagged version.

Parameters:

tag (str) – Short tag name (e.g. "v1.0") or full ref (e.g. "refs/tags/v1.0"); the refs/tags/ prefix is stripped automatically.
item_path (str | None) – When set, only commits that touched this file path are returned.
top (int | None) – Maximum number of commits to return; None means no limit.

Yields:

Commit for each matching commit.

Return type:

Iterator[Commit]

iter_git_tags()¶

Iterate over all git tags in the repository.

Yields:: Tag for each tag.
Return type:: Iterator[Tag]

iter_items(scope_path='/', *, branch=None, recursion_level=RecursionLevel.ONE_LEVEL)¶

Iterate over files and folders at scope_path.

Parameters:

scope_path (str) – Directory path to list (default: root "/").
branch (str | None) – Short branch name or full ref. When None, the repository default branch is used.
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Yields:

GitItem for each file or folder entry.

Return type:

Iterator[GitItem]

iter_items_by_commit(scope_path='/', *, commit, recursion_level=RecursionLevel.ONE_LEVEL)¶

Iterate over files and folders at scope_path at a specific commit.

Fully immutable. Use for reproducible references, audit trails, or any context where the listing must not change between calls.

Parameters:

scope_path (str) – Directory path to list (default: root "/").
commit (str) – Commit SHA to resolve the listing at.
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Yields:

GitItem for each file or folder entry.

Return type:

Iterator[GitItem]

iter_items_by_ref(scope_path='/', *, ref, recursion_level=RecursionLevel.ONE_LEVEL)¶

Iterate over files and folders at scope_path at an arbitrary ref.

Escape hatch for refs outside the typed categories (e.g. pull-request merge refs "refs/pull/{id}/merge"). The ref is resolved to a commit SHA via the refs API before fetching items, which ensures the ADO items endpoint can handle all ref types (branch, PR merge, etc.).

Parameters:

scope_path (str) – Directory path to list (default: root "/").
ref (str) – Arbitrary full git ref string (e.g. "refs/pull/42/merge").
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Yields:

GitItem for each file or folder entry.

Raises:

AzureDevOpsNotFoundError – If the ref cannot be resolved.

Return type:

Iterator[GitItem]

iter_items_by_tag(scope_path='/', *, tag, recursion_level=RecursionLevel.ONE_LEVEL)¶

Iterate over files and folders at scope_path at a tagged version.

Resolves to the tagged object. Note that lightweight tags are mutable (can be deleted and re-created pointing elsewhere); callers that require true immutability should resolve the tag to a commit SHA and use iter_items_by_commit() instead.

Parameters:

scope_path (str) – Directory path to list (default: root "/").
tag (str) – Short tag name (e.g. "v1.0") or full ref (e.g. "refs/tags/v1.0"); the refs/tags/ prefix is stripped automatically.
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Yields:

GitItem for each file or folder entry.

Return type:

Iterator[GitItem]

iter_pull_requests(status=None, *, criteria=None, expand=None)¶

Iterate over pull requests in this repository.

Parameters:

status (PullRequestStatus | None) – Filter by PR lifecycle status. When None (default), all PRs are returned regardless of status. Ignored when criteria is provided.
criteria (PullRequestSearchCriteria | None) – Full search criteria; repository_id is always overridden to this repository’s ID. Use this to apply date-range filters (min_time/max_time) or other PullRequestSearchCriteria fields.
expand (str | None) – Optional $expand value (e.g. "labels", "reviewers").

Yields:

PullRequest for each matching PR, in API-returned order.

Return type:

Iterator[PullRequest]

iter_refs(name_filter=None, name_contains=None)¶

Iterate over git refs in the repository.

Parameters:

name_filter (str | None) – Prefix filter for ref names (ADO strips refs/ before matching, e.g. "heads/main").
name_contains (str | None) – Substring filter for ref names.

Yields:

GitRef for each matching ref.

Return type:

Iterator[GitRef]

list_acl()¶

Return the access control lists for this repository.

The ACL endpoint is organisation-scoped; this method handles the required org-level API call internally.

Returns:: List of AccessControlList objects for this repository.
Return type:: list[AccessControlList]

list_branches()¶

Return all branches in this repository as a list.

Return type:: list[Branch]

list_commit_diff(base_commit, target_commit)¶

Return all file changes between two commits as a list.

Parameters:

base_commit (str)
target_commit (str)

Return type:

list[GitCommitChange]

list_commits(*, item_path=None, top=None, branch=None)¶

Return all commits matching the given criteria as a list.

Parameters:

item_path (str | None)
top (int | None)
branch (str | None)

Return type:

list[Commit]

list_commits_by_commit(commit, *, item_path=None, top=None)¶

Return commits reachable from a specific commit as a list.

Parameters:

commit (str)
item_path (str | None)
top (int | None)

Return type:

list[Commit]

list_commits_by_tag(tag, *, item_path=None, top=None)¶

Return commits reachable from a tagged version as a list.

Parameters:

tag (str)
item_path (str | None)
top (int | None)

Return type:

list[Commit]

list_git_tags()¶

Return all git tags in this repository as a list.

Return type:: list[Tag]

list_items(scope_path='/', *, branch=None, recursion_level=RecursionLevel.ONE_LEVEL)¶

Return all items at scope_path as a list.

Parameters:

scope_path (str) – Directory path to list (default: root "/").
branch (str | None) – Short branch name or full ref. When None, the repository default branch is used.
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Returns:

List of GitItem for each file or folder entry.

Return type:

list[GitItem]

list_items_by_commit(scope_path='/', *, commit, recursion_level=RecursionLevel.ONE_LEVEL)¶

Return items at scope_path at a specific commit as a list.

Parameters:

scope_path (str)
commit (str)
recursion_level (RecursionLevel)

Return type:

list[GitItem]

list_items_by_ref(scope_path='/', *, ref, recursion_level=RecursionLevel.ONE_LEVEL)¶

Return items at scope_path at an arbitrary ref as a list.

Parameters:

scope_path (str)
ref (str)
recursion_level (RecursionLevel)

Return type:

list[GitItem]

list_items_by_tag(scope_path='/', *, tag, recursion_level=RecursionLevel.ONE_LEVEL)¶

Return items at scope_path at a tagged version as a list.

Parameters:

scope_path (str)
tag (str)
recursion_level (RecursionLevel)

Return type:

list[GitItem]

list_pull_requests(status=None, *, criteria=None, expand=None)¶

Return all pull requests in this repository as a list.

Parameters:

status (PullRequestStatus | None)
criteria (PullRequestSearchCriteria | None)
expand (str | None)

Return type:

list[PullRequest]

list_refs(name_filter=None, name_contains=None)¶

Return all refs matching the filter as a list.

Parameters:

name_filter (str | None)
name_contains (str | None)

Return type:

list[GitRef]

make_ref_update(branch)¶

Return a ref-update entry for a branch, fetching its current SHA.

Convenience wrapper around create_ref_update() that supplies the repository API call automatically. Use this when building a push manually via push_commits().

Parameters:: branch (str) – Short branch name (e.g. "main"). A refs/heads/ prefix is added automatically if absent.
Returns:: GitPushRefUpdate with the branch’s current commit SHA as old_object_id.
Return type:: GitPushRefUpdate

property name: str¶: Repository name.

property org: Organization¶: Organisation this repository belongs to — zero-cost.

property project: Project¶: Project this repository belongs to — zero-cost.

push_commits(ref_updates, commits)¶

Push one or more commits to the repository.

Parameters:

ref_updates (list[GitPushRefUpdate]) – One entry per branch being updated. Use ZERO_SHA as old_object_id for new branches. Build entries with make_ref_update().
commits (list[GitPushCommit]) – Commits to include in the push. Build entries with make_commit().

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

refresh()¶

Discard cached repository info.

The next access to info re-fetches from the API.

Return type:: None

start_cherry_pick(onto, cherry_pick_ref)¶

Queue a cherry-pick and return immediately.

ADO cherry-picks asynchronously. The response status is typically GitCherryPickStatus.QUEUED on return. Poll with get_cherry_pick_status() to check for completion.

Parameters:

onto (str) – Target branch name (e.g. "main" or "refs/heads/main"). The refs/heads/ prefix is added automatically when absent.
cherry_pick_ref (str) – Name of the new branch ADO will create containing the cherry-picked commit (short name or full ref).

Returns:

GitCherryPickResponse with the initial operation status.

Return type:

start_merge(source, target, *, comment=None)¶

Queue a merge of two commits and return immediately.

ADO processes merges asynchronously. The response status is typically GitMergeStatus.QUEUED on return. Poll with get_merge_status() or use check_merge_feasible() to wait for the result.

Parameters:

source (str) – Commit SHA of the source (feature) branch tip.
target (str) – Commit SHA of the target (base) branch tip.
comment (str | None) – Optional merge commit message.

Returns:

GitMergeResponse with the initial operation status.

Return type:

start_revert(onto, revert_ref)¶

Queue a revert and return immediately.

ADO reverts asynchronously. The response status is typically GitRevertStatus.QUEUED on return. Poll with get_revert_status() to check for completion.

Parameters:

onto (str) – Target branch name (e.g. "main" or "refs/heads/main"). The refs/heads/ prefix is added automatically when absent.
revert_ref (str) – Name of the new branch ADO will create containing the revert commit (short name or full ref).

Returns:

GitRevertResponse with the initial operation status.

Return type:

property web_url: Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=['https'], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)]¶: Web URL of the repository in the ADO portal.

class pyado.oop.repos.Tag(repo, ref)¶

A git tag in an Azure DevOps repository.

Wraps a GitRef for a refs/tags/… ref and exposes tag-specific convenience methods. Instances are obtained from Repository.iter_git_tags() or ProjectRepos.iter_git_tags().

Parameters:

repo (Repository)
ref (GitRef)

_repo¶: The Repository this tag belongs to.

_ref¶: The underlying GitRef data.

property commit_id: str¶: Commit SHA the tag points at.

delete()¶

Delete this tag from the repository.

Uses the stored commit SHA as the optimistic-concurrency guard.

Return type:: None

property full_name: str¶: Full ref name (e.g. "refs/tags/v1.0").

get_annotated_info()¶

Return the annotated tag metadata, or None for lightweight tags.

Fetches the tag object from ADO to retrieve the tagger identity, timestamp, and annotation message. Lightweight tags point directly to a commit rather than to a tag object; ADO returns 404 for them, so this method returns None in that case.

Returns:: AnnotatedTagInfo with tagger, message, and tagged-object details, or None if this is a lightweight tag.
Return type:: AnnotatedTagInfo | None

get_commit()¶

Return the commit this tag points at.

For lightweight tags the objectId in the ref is already the commit SHA. For annotated tags it is the tag-object SHA; in that case the method fetches the annotated tag to dereference it to the actual commit.

Returns:: Commit the tag targets.
Raises:: AzureDevOpsNotFoundError – If the commit or annotated tag object cannot be resolved.
Return type:: Commit

property name: str¶: Short tag name (refs/tags/ prefix stripped).

property ref: GitRef¶: Underlying GitRef data.

property repo: Repository¶: Repository this tag belongs to — zero-cost.

Repository¶

OOP wrapper for Azure DevOps repository resources.

class pyado.oop.repos.repository.Repository(project, repository_api_call, info, service)

An Azure DevOps Git repository resource.

Wraps a single ADO repository and exposes its operations as instance methods. Instances are obtained from ProjectRepos.iter_repositories() or ProjectRepos.get_repository().

Repositories are cached in the service — the same instance is returned on repeated access. Call refresh() to re-fetch the info from the API.

Parameters:

project (Project)
repository_api_call (ApiCall)
info (RepositoryInfo)
service (AzureDevOpsService)

_project: The Project this repository belongs to.

_service: The owning AzureDevOpsService (for org-level API calls).

_api_call: Repository-level API call used by all git operations.

_info: The repository data returned from the API at construction time.

property api_call: ApiCall: Repository-level API call for direct use with pyado.raw functions.

check_branch_exists(name)

Return True if the branch exists in this repository.

Parameters:: name (str) – Short branch name (e.g. "main") or full ref (e.g. "refs/heads/main").
Returns:: True if the branch exists, False otherwise.
Return type:: bool

check_file_exists_by_branch(path, branch=None)

Return True if a file exists at the tip of a branch.

Thin boolean wrapper over get_item_by_branch(). Fetches metadata only (no file content), so this is cheap.

Parameters:

path (str) – Absolute file path within the repository.
branch (str | None) – Short branch name or full ref. None → repository default branch.

Returns:

True if the file exists, False otherwise.

Return type:

bool

check_file_exists_by_commit(path, commit)

Return True if a file exists at a specific commit.

Thin boolean wrapper over get_item_by_commit(). Fully immutable — the result will not change for the same commit SHA.

Parameters:

path (str) – Absolute file path within the repository.
commit (str) – Commit SHA to resolve the file at.

Returns:

True if the file exists, False otherwise.

Return type:

bool

check_file_exists_by_ref(path, ref)

Return True if a file exists at an arbitrary ref.

Thin boolean wrapper over get_item_by_ref().

Parameters:

path (str) – Absolute file path within the repository.
ref (str) – Arbitrary full git ref string.

Returns:

True if the file exists, False otherwise.

Return type:

bool

check_file_exists_by_tag(path, tag)

Return True if a file exists at a tagged version.

Thin boolean wrapper over get_item_by_tag(). Note that lightweight tags are mutable; see get_item_by_tag().

Parameters:

path (str) – Absolute file path within the repository.
tag (str) – Short tag name or full ref.

Returns:

True if the file exists, False otherwise.

Return type:

bool

check_merge_feasible(source, target, *, timeout=10.0, poll_interval=0.5)

Return True if source can be merged into target without conflicts.

Queues a merge via ADO and polls until the operation reaches a terminal status or timeout seconds elapse. Returns True for COMPLETED, False for CONFLICTS or FAILURE.

Parameters:

source (str) – Commit SHA of the source branch tip.
target (str) – Commit SHA of the target branch tip.
timeout (float) – Maximum number of seconds to wait for ADO to complete the merge check. Defaults to 10 s.
poll_interval (float) – Seconds between poll attempts. Defaults to 0.5 s.

Returns:

True if the merge can be applied cleanly, False if it cannot.

Raises:

AzureDevOpsNotFoundError – If either commit SHA is not found by ADO (INVALID_REFS status).
TimeoutError – If the operation is still QUEUED after timeout seconds.

Return type:

bool

commit(branch, message, changes, current_commit=None)

Push a single commit to an existing branch.

Parameters:

branch (str | None) – Short branch name (e.g. "main"). None → repository default branch.
message (str) – Commit message.
changes (list[AddFile | EditFile | DeleteFile | RenameFile]) – One or more file changes to include in the commit. Use AddFile, EditFile, DeleteFile, or RenameFile.
current_commit (str | None) – Current HEAD SHA of the branch used for the optimistic-concurrency check. None → fetched automatically.

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

Example:

repo.commit("main", "Update config", [
    EditFile("/config.json", "{}"),
    DeleteFile("/old_config.json"),
])

commit_file_delete(branch, path, message)

Delete a file from a branch in a single commit.

Parameters:

branch (str) – Short branch name (e.g. "main").
path (str) – Absolute file path within the repository (e.g. "/config.json").
message (str) – Commit message.

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

commit_file_rename(branch, old_path, new_path, message)

Rename (move) a file on a branch in a single commit.

Parameters:

branch (str) – Short branch name (e.g. "main").
old_path (str) – Current absolute file path within the repository.
new_path (str) – New absolute file path within the repository.
message (str) – Commit message.

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

commit_file_upsert(branch, path, content, message, current_commit=None)

Create or update a single file on a branch in one commit.

Note: unlike the _by_branch read methods, writing always targets a specific branch; there is no tag or commit variant because git objects are immutable after creation.

Parameters:

branch (str | None) – Target branch name. None → repository default branch.
path (str) – Absolute file path within the repository.
content (str) – New UTF-8 text content for the file.
message (str) – Commit message.
current_commit (str | None) – Current HEAD SHA for optimistic-concurrency. None → fetched automatically.

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

create_annotated_tag(name, message, commit_sha)

Create an annotated tag in this repository.

An annotated tag is a full git object (not just a lightweight ref pointer) and carries a message and tagger identity. Use create_git_tag() for lightweight tags.

Parameters:

name (str) – Tag name without refs/tags/ prefix (e.g. "v1.0").
message (str) – Annotation message for the tag.
commit_sha (str) – Commit SHA the tag should point at.

Returns:

AnnotatedTagInfo describing the newly created annotated tag.

Return type:

create_branch(name, from_commit)

Create a new branch pointing at an existing commit.

Parameters:

name (str) – Short branch name (e.g. "feature/my-branch"). A refs/heads/ prefix is added automatically if absent.
from_commit (str) – Commit SHA the new branch should point at.

Return type:

None

create_git_tag(name, commit_id)

Create a lightweight tag pointing at an existing commit.

Parameters:

name (str) – Short tag name (e.g. "v1.0"). A refs/tags/ prefix is added automatically if absent.
commit_id (str) – Commit SHA the tag should point at.

Return type:

None

create_pull_request(title, source_branch, target_branch, *, description=None, completion_options=None)

Create a new pull request in this repository.

Parameters:

title (str) – Title of the pull request.
source_branch (str) – Source branch name (e.g. "feature/my-branch" or full "refs/heads/feature/my-branch").
target_branch (str) – Target branch name (e.g. "main").
description (str | None) – Optional PR description.
completion_options (PullRequestCompletionOptions | None) – Merge and post-completion behaviour; defaults to squash merge with source-branch deletion.

Returns:

PullRequest wrapping the newly created PR.

Return type:

PullRequest

property default_branch: str | None: Default branch name (e.g. "refs/heads/main"), or None if unset.

delete_branch(name, current_commit=None)

Delete a branch from the repository.

Parameters:

name (str) – Short branch name or full refs/heads/… name.
current_commit (str | None) – Current HEAD SHA of the branch. None → fetched automatically.

Return type:

None

delete_git_tag(name, commit_id)

Delete a git tag from the repository.

Parameters:

name (str) – Short tag name (e.g. "v1.0"). A refs/tags/ prefix is added automatically if absent.
commit_id (str) – Current object ID of the tag (optimistic-concurrency check).

Return type:

None

get_branch_head(name)

Return the current HEAD commit SHA of a branch.

Parameters:: name (str) – Short branch name (e.g. "main") or full ref (e.g. "refs/heads/main").
Returns:: Commit SHA string at the tip of the branch.
Raises:: AzureDevOpsNotFoundError – If the branch does not exist.
Return type:: str

get_cherry_pick_status(cherry_pick_id)

Return the current status of a queued cherry-pick operation.

Parameters:: cherry_pick_id (int) – The operation ID from start_cherry_pick().
Returns:: GitCherryPickResponse with the current status.
Return type:: GitCherryPickResponse

get_commit(sha)

Return a wrapper for a specific commit.

Parameters:: sha (str) – Commit SHA string.
Returns:: Commit wrapping the requested commit.
Return type:: Commit

get_default_branch_commit()

Return the HEAD commit of the default branch.

Convenience shortcut that avoids a separate iter_refs() call followed by get_commit().

Returns:: Commit at the tip of the default branch.
Raises:: AzureDevOpsNotFoundError – If the repository has no default branch configured, or if the default branch ref is not found (e.g. empty repository).
Return type:: Commit

get_file_by_branch(path, branch=None)

Return the content of a file from the tip of a branch.

Parameters:

path (str) – Absolute file path within the repository (e.g. /foo.py).
branch (str | None) – Short branch name or full ref (e.g. "main" or "refs/heads/main"). None → repository default branch.

Returns:

File content as a UTF-8 string, or "" if the file is absent.

Return type:

str

get_file_by_commit(path, commit)

Return the content of a file at a specific commit.

Fully immutable. Use for reproducible references, audit trails, diffing, or any context where the result must not change.

Parameters:

path (str) – Absolute file path within the repository.
commit (str) – Commit SHA to resolve the file at.

Returns:

File content as a UTF-8 string, or "" if the file is absent.

Return type:

str

get_file_bytes_by_branch(path, branch=None)

Return the raw bytes of a file from the tip of a branch.

Parameters:

path (str) – Absolute file path within the repository (e.g. /img.png).
branch (str | None) – Short branch name or full ref. None → repository default branch.

Returns:

Raw file bytes, or None if the file does not exist.

Return type:

bytes | None

get_file_bytes_by_commit(path, commit)

Return the raw bytes of a file at a specific commit.

Fully immutable. Use when the file may contain non-UTF-8 data and the result must not change across calls.

Parameters:

path (str) – Absolute file path within the repository.
commit (str) – Commit SHA to resolve the file at.

Returns:

Raw file bytes, or None if the file does not exist.

Return type:

bytes | None

get_item_by_branch(path, branch=None)

Return metadata for a single file at the tip of a branch, or None.

Parameters:

path (str) – Absolute file path within the repository.
branch (str | None) – Short branch name or full ref. None → repository default branch.

Returns:

GitItem for the file, or None if it does not exist.

Return type:

GitItem | None

get_item_by_commit(path, commit)

Return metadata for a single file at a specific commit, or None.

Fully immutable. Use for reproducible references, audit trails, diffing, or any context where the result must not change.

Parameters:

path (str) – Absolute file path within the repository.
commit (str) – Commit SHA to resolve the file at.

Returns:

GitItem for the file, or None if it does not exist.

Return type:

GitItem | None

get_item_by_ref(path, ref)

Return metadata for a single file at an arbitrary ref, or None.

Escape hatch for refs outside the typed categories (e.g. pull-request merge refs "refs/pull/{id}/merge"). The ref is resolved to a commit SHA via the refs API before fetching the item.

Parameters:

path (str) – Absolute file path within the repository.
ref (str) – Arbitrary full git ref string (e.g. "refs/pull/42/merge").

Returns:

GitItem for the file, or None if the file does not exist at the ref.

Raises:

AzureDevOpsNotFoundError – If the ref cannot be resolved.

Return type:

GitItem | None

get_item_by_tag(path, tag)

Return metadata for a single file at a tagged version, or None.

Parameters:

path (str) – Absolute file path within the repository.
tag (str) – Short tag name (e.g. "v1.0") or full ref (e.g. "refs/tags/v1.0"); the refs/tags/ prefix is stripped automatically.

Returns:

GitItem for the file, or None if it does not exist.

Return type:

GitItem | None

get_last_commit_touching_file(path, before_commit)

Return the most recent commit that touched a file at or before a commit.

Falls back to returning before_commit when no matching commit is found (e.g. the file did not exist at that point).

Parameters:

path (str) – Absolute file path within the repository (e.g. "/src/foo.py").
before_commit (str) – The commit SHA to search at or before.

Returns:

Commit SHA of the most recent touching commit, or before_commit.

Return type:

str

get_merge_status(merge_operation_id)

Return the current status of a queued merge operation.

Parameters:: merge_operation_id (int) – The operation ID from start_merge().
Returns:: GitMergeResponse with the current status.
Return type:: GitMergeResponse

get_pr_for_branch(source_branch)

Return the first active PR for the given source branch, or None.

Parameters:: source_branch (str) – Short branch name or full ref. A refs/heads/ prefix is added automatically when absent.
Returns:: PullRequest for the first active PR from that source branch, or None if none exists.
Return type:: PullRequest | None

get_pr_for_commit(sha)

Return the first active PR whose source branch contains sha, or None.

Uses searchCriteria.sourceVersion to restrict the search to PRs that include the given commit.

Parameters:: sha (str) – Commit SHA string to search for.
Returns:: PullRequest for the first active PR whose source version matches sha, or None if no such PR exists.
Return type:: PullRequest | None

get_pull_request(pull_request_id)

Return a wrapper for a specific pull request.

Parameters:: pull_request_id (int) – Numeric ID of the pull request.
Returns:: PullRequest wrapping the requested PR.
Return type:: PullRequest

get_revert_status(revert_id)

Return the current status of a queued revert operation.

Parameters:: revert_id (int) – The operation ID from start_revert().
Returns:: GitRevertResponse with the current status.
Return type:: GitRevertResponse

get_statistics(branch)

Return ahead/behind commit counts for a branch.

Parameters:: branch (str) – Branch name (e.g. "main" or "refs/heads/main").
Returns:: BranchStatistics with ahead/behind counts and the branch HEAD commit.
Return type:: BranchStatistics

property id: UUID: Repository UUID.

property info: RepositoryInfo: Repository data captured at construction time (or last refresh).

iter_branches()

Iterate over all branches (refs/heads/…) in the repository.

Convenience wrapper over iter_refs() that pre-applies the heads/ name filter so callers do not need to know the ADO ref filter format.

Yields:: Branch for each branch.
Return type:: Iterator[Branch]

iter_commit_diff(base_commit, target_commit)

Iterate over file changes between two commits.

Paginates automatically when the API returns partial results. Folder entries are excluded.

Parameters:

base_commit (str) – The older (base) commit SHA.
target_commit (str) – The newer (target) commit SHA.

Yields:

GitCommitChange for each changed file.

Return type:

Iterator[GitCommitChange]

iter_commits(*, item_path=None, top=None, branch=None)

Iterate over commits in the repository.

Parameters:

item_path (str | None) – When set, only commits that touched this file path are returned (e.g. "/src/foo.py").
top (int | None) – Maximum number of commits to return; None means no limit.
branch (str | None) – When set, only commits reachable from this branch are returned. Accepts a short name ("main") or a full ref ("refs/heads/main"); the refs/heads/ prefix is stripped automatically.

Yields:

Commit for each matching commit.

Return type:

Iterator[Commit]

iter_commits_by_commit(commit, *, item_path=None, top=None)

Iterate over commits reachable from a specific commit.

Fully immutable. Use for reproducible references, audit trails, or any context where the commit list must not change.

Parameters:

commit (str) – Commit SHA to search from.
item_path (str | None) – When set, only commits that touched this file path are returned.
top (int | None) – Maximum number of commits to return; None means no limit.

Yields:

Commit for each matching commit.

Return type:

Iterator[Commit]

iter_commits_by_tag(tag, *, item_path=None, top=None)

Iterate over commits reachable from a tagged version.

Parameters:

tag (str) – Short tag name (e.g. "v1.0") or full ref (e.g. "refs/tags/v1.0"); the refs/tags/ prefix is stripped automatically.
item_path (str | None) – When set, only commits that touched this file path are returned.
top (int | None) – Maximum number of commits to return; None means no limit.

Yields:

Commit for each matching commit.

Return type:

Iterator[Commit]

iter_git_tags()

Iterate over all git tags in the repository.

Yields:: Tag for each tag.
Return type:: Iterator[Tag]

iter_items(scope_path='/', *, branch=None, recursion_level=RecursionLevel.ONE_LEVEL)

Iterate over files and folders at scope_path.

Parameters:

scope_path (str) – Directory path to list (default: root "/").
branch (str | None) – Short branch name or full ref. When None, the repository default branch is used.
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Yields:

GitItem for each file or folder entry.

Return type:

Iterator[GitItem]

iter_items_by_commit(scope_path='/', *, commit, recursion_level=RecursionLevel.ONE_LEVEL)

Iterate over files and folders at scope_path at a specific commit.

Fully immutable. Use for reproducible references, audit trails, or any context where the listing must not change between calls.

Parameters:

scope_path (str) – Directory path to list (default: root "/").
commit (str) – Commit SHA to resolve the listing at.
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Yields:

GitItem for each file or folder entry.

Return type:

Iterator[GitItem]

iter_items_by_ref(scope_path='/', *, ref, recursion_level=RecursionLevel.ONE_LEVEL)

Iterate over files and folders at scope_path at an arbitrary ref.

Parameters:

scope_path (str) – Directory path to list (default: root "/").
ref (str) – Arbitrary full git ref string (e.g. "refs/pull/42/merge").
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Yields:

GitItem for each file or folder entry.

Raises:

AzureDevOpsNotFoundError – If the ref cannot be resolved.

Return type:

Iterator[GitItem]

iter_items_by_tag(scope_path='/', *, tag, recursion_level=RecursionLevel.ONE_LEVEL)

Iterate over files and folders at scope_path at a tagged version.

Parameters:

scope_path (str) – Directory path to list (default: root "/").
tag (str) – Short tag name (e.g. "v1.0") or full ref (e.g. "refs/tags/v1.0"); the refs/tags/ prefix is stripped automatically.
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Yields:

GitItem for each file or folder entry.

Return type:

Iterator[GitItem]

iter_pull_requests(status=None, *, criteria=None, expand=None)

Iterate over pull requests in this repository.

Parameters:

status (PullRequestStatus | None) – Filter by PR lifecycle status. When None (default), all PRs are returned regardless of status. Ignored when criteria is provided.
criteria (PullRequestSearchCriteria | None) – Full search criteria; repository_id is always overridden to this repository’s ID. Use this to apply date-range filters (min_time/max_time) or other PullRequestSearchCriteria fields.
expand (str | None) – Optional $expand value (e.g. "labels", "reviewers").

Yields:

PullRequest for each matching PR, in API-returned order.

Return type:

Iterator[PullRequest]

iter_refs(name_filter=None, name_contains=None)

Iterate over git refs in the repository.

Parameters:

name_filter (str | None) – Prefix filter for ref names (ADO strips refs/ before matching, e.g. "heads/main").
name_contains (str | None) – Substring filter for ref names.

Yields:

GitRef for each matching ref.

Return type:

Iterator[GitRef]

list_acl()

Return the access control lists for this repository.

The ACL endpoint is organisation-scoped; this method handles the required org-level API call internally.

Returns:: List of AccessControlList objects for this repository.
Return type:: list[AccessControlList]

list_branches()

Return all branches in this repository as a list.

Return type:: list[Branch]

list_commit_diff(base_commit, target_commit)

Return all file changes between two commits as a list.

Parameters:

base_commit (str)
target_commit (str)

Return type:

list[GitCommitChange]

list_commits(*, item_path=None, top=None, branch=None)

Return all commits matching the given criteria as a list.

Parameters:

item_path (str | None)
top (int | None)
branch (str | None)

Return type:

list[Commit]

list_commits_by_commit(commit, *, item_path=None, top=None)

Return commits reachable from a specific commit as a list.

Parameters:

commit (str)
item_path (str | None)
top (int | None)

Return type:

list[Commit]

list_commits_by_tag(tag, *, item_path=None, top=None)

Return commits reachable from a tagged version as a list.

Parameters:

tag (str)
item_path (str | None)
top (int | None)

Return type:

list[Commit]

list_git_tags()

Return all git tags in this repository as a list.

Return type:: list[Tag]

list_items(scope_path='/', *, branch=None, recursion_level=RecursionLevel.ONE_LEVEL)

Return all items at scope_path as a list.

Parameters:

scope_path (str) – Directory path to list (default: root "/").
branch (str | None) – Short branch name or full ref. When None, the repository default branch is used.
recursion_level (RecursionLevel) – Depth of recursion (default: one level).

Returns:

List of GitItem for each file or folder entry.

Return type:

list[GitItem]

list_items_by_commit(scope_path='/', *, commit, recursion_level=RecursionLevel.ONE_LEVEL)

Return items at scope_path at a specific commit as a list.

Parameters:

scope_path (str)
commit (str)
recursion_level (RecursionLevel)

Return type:

list[GitItem]

list_items_by_ref(scope_path='/', *, ref, recursion_level=RecursionLevel.ONE_LEVEL)

Return items at scope_path at an arbitrary ref as a list.

Parameters:

scope_path (str)
ref (str)
recursion_level (RecursionLevel)

Return type:

list[GitItem]

list_items_by_tag(scope_path='/', *, tag, recursion_level=RecursionLevel.ONE_LEVEL)

Return items at scope_path at a tagged version as a list.

Parameters:

scope_path (str)
tag (str)
recursion_level (RecursionLevel)

Return type:

list[GitItem]

list_pull_requests(status=None, *, criteria=None, expand=None)

Return all pull requests in this repository as a list.

Parameters:

status (PullRequestStatus | None)
criteria (PullRequestSearchCriteria | None)
expand (str | None)

Return type:

list[PullRequest]

list_refs(name_filter=None, name_contains=None)

Return all refs matching the filter as a list.

Parameters:

name_filter (str | None)
name_contains (str | None)

Return type:

list[GitRef]

make_ref_update(branch)

Return a ref-update entry for a branch, fetching its current SHA.

Convenience wrapper around create_ref_update() that supplies the repository API call automatically. Use this when building a push manually via push_commits().

Parameters:: branch (str) – Short branch name (e.g. "main"). A refs/heads/ prefix is added automatically if absent.
Returns:: GitPushRefUpdate with the branch’s current commit SHA as old_object_id.
Return type:: GitPushRefUpdate

property name: str: Repository name.

property org: Organization: Organisation this repository belongs to — zero-cost.

property project: Project: Project this repository belongs to — zero-cost.

push_commits(ref_updates, commits)

Push one or more commits to the repository.

Parameters:

ref_updates (list[GitPushRefUpdate]) – One entry per branch being updated. Use ZERO_SHA as old_object_id for new branches. Build entries with make_ref_update().
commits (list[GitPushCommit]) – Commits to include in the push. Build entries with make_commit().

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

refresh()

Discard cached repository info.

The next access to info re-fetches from the API.

Return type:: None

start_cherry_pick(onto, cherry_pick_ref)

Queue a cherry-pick and return immediately.

ADO cherry-picks asynchronously. The response status is typically GitCherryPickStatus.QUEUED on return. Poll with get_cherry_pick_status() to check for completion.

Parameters:

onto (str) – Target branch name (e.g. "main" or "refs/heads/main"). The refs/heads/ prefix is added automatically when absent.
cherry_pick_ref (str) – Name of the new branch ADO will create containing the cherry-picked commit (short name or full ref).

Returns:

GitCherryPickResponse with the initial operation status.

Return type:

start_merge(source, target, *, comment=None)

Queue a merge of two commits and return immediately.

ADO processes merges asynchronously. The response status is typically GitMergeStatus.QUEUED on return. Poll with get_merge_status() or use check_merge_feasible() to wait for the result.

Parameters:

source (str) – Commit SHA of the source (feature) branch tip.
target (str) – Commit SHA of the target (base) branch tip.
comment (str | None) – Optional merge commit message.

Returns:

GitMergeResponse with the initial operation status.

Return type:

start_revert(onto, revert_ref)

Queue a revert and return immediately.

ADO reverts asynchronously. The response status is typically GitRevertStatus.QUEUED on return. Poll with get_revert_status() to check for completion.

Parameters:

onto (str) – Target branch name (e.g. "main" or "refs/heads/main"). The refs/heads/ prefix is added automatically when absent.
revert_ref (str) – Name of the new branch ADO will create containing the revert commit (short name or full ref).

Returns:

GitRevertResponse with the initial operation status.

Return type:

property web_url: Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=['https'], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)]: Web URL of the repository in the ADO portal.

Pull Request¶

OOP wrapper for Azure DevOps pull request resources.

class pyado.oop.repos.pull_request.PullRequest(repo, pr_api_call, info, expand=None)

An Azure DevOps pull request resource.

Pull requests are not cached — each factory call returns a fresh instance. Call refresh() to re-fetch the info from the API at any time.

The info attribute holds either a PullRequestListItem (when obtained via a list endpoint) or a PullRequestResponse (when freshly created), reflecting the data available at construction time.

Parameters:

repo (Repository)
pr_api_call (ApiCall)
info (PullRequestListItem | PullRequestResponse)
expand (str | None)

_repo: The Repository this pull request belongs to.

_api_call: PR-level API call used by all operations.

_info: PR data; type depends on how the instance was constructed.

abandon()

Abandon the pull request.

Return type:: None

add_reviewer(reviewer_id, *, is_required=False, is_reapprove=False)

Add or update a reviewer on the pull request.

Parameters:

reviewer_id (str) – Identity (object) ID of the reviewer.
is_required (bool) – When True the reviewer is marked as required.
is_reapprove (bool) – When True, the approval is processed even if the vote has not changed.

Return type:

None

add_tag(name)

Add a tag to the pull request.

Parameters:: name (str) – Tag name to add.
Return type:: None

Note

The ADO tag endpoints return no body, so this method returns None. Call get_tags() afterwards if you need the updated tag list.

add_thread(content, *, file_path=None, line=None, status=PullRequestThreadStatus.ACTIVE)

Create a new review thread on the pull request.

Parameters:

content (str) – Text content of the first comment.
file_path (str | None) – File path to anchor the thread to, or None for a PR-level thread.
line (int | None) – Line number within the file; only meaningful when file_path is set.
status (PullRequestThreadStatus) – Initial thread status (default: "active").

Returns:

The created PullRequestThreadResponse.

Return type:

PullRequestThreadCommentResponse

add_work_item_ref(wi_id)

Add a single work item to the pull request’s work item refs.

Reads the current work item refs, adds wi_id if not already present, and writes the updated list back. The operation is idempotent — if wi_id is already linked, no PATCH is made.

This wraps iter_work_item_ids() and set_work_item_refs(): two API calls (one GET, one PATCH) when the item is not yet linked; one API call (GET only) when it is already present.

Parameters:: wi_id (int) – Numeric ID of the work item to add.
Return type:: None

property api_call: ApiCall: PR-level API call for direct use with pyado.raw functions.

complete(last_merge_source_commit, *, completion_options=None)

Complete (merge) the pull request.

Parameters:

last_merge_source_commit (str) – Current HEAD SHA of the source branch. Used by ADO as an optimistic-concurrency guard; obtain it from pr.info.last_merge_source_commit.commit_id after a refresh().
completion_options (PullRequestCompletionOptions | None) – Merge strategy and post-completion options. Defaults to squash merge with source-branch deletion.

Return type:

None

property created_by: str | None

Display name of the user who created the PR, or None.

For the full identity (id, unique name), use pr.info.created_by.

property description: str | None: Pull request description body, or None if not set.

disable_auto_complete()

Disable auto-complete on the pull request.

Clears the auto-complete setter so the PR will no longer be merged automatically when policies pass. Has no effect if auto-complete was not set. ADO requires an all-zeros GUID to unset auto-complete.

Return type:: None

enable_auto_complete(identity_id=None, *, completion_options=None)

Enable auto-complete on the pull request.

When auto-complete is set, ADO will automatically complete (merge) the PR once all required reviewers have approved and all policies pass.

Parameters:

identity_id (str | None) – Object ID of the identity to record as the auto-complete setter. When None (the default), the authenticated user’s identity is resolved via get_connection_data and used automatically.
completion_options (PullRequestCompletionOptions | None) – Merge strategy and post-completion options. When None, ADO retains the existing options.

Return type:

None

get_iteration_changes(iteration_id)

Return the file changes introduced by a specific PR iteration.

Parameters:: iteration_id (int) – The 1-based iteration number. Obtain it from iter_iterations().
Returns:: List of PullRequestIterationChange entries for the iteration.
Return type:: list[PullRequestIterationChange]

get_thread(thread_id)

Return a single review thread by ID.

Parameters:: thread_id (int) – Numeric ID of the thread to fetch. Obtain it from iter_threads().
Returns:: PullRequestThreadResponse for the requested thread.
Return type:: PullRequestThreadResponse

property id: int: Numeric pull request ID.

property info: PullRequestListItem | PullRequestResponse: PR data captured at construction time (or last refresh).

iter_commits()

Iterate over commits included in the pull request.

Yields:: Commit for each commit reachable from the PR.
Return type:: Iterator[Commit]

iter_files_changed()

Iterate over files changed in this pull request.

Yields:: PullRequestIterationChange for each changed file.
Return type:: Iterator[PullRequestIterationChange]

iter_iterations()

Iterate over the push iterations of this pull request.

Each iteration corresponds to a force-push or new commit push to the source branch. Use get_iteration_changes() to retrieve the file-level diff introduced by a specific iteration.

Yields:: PullRequestIterationRecord for each iteration, oldest first.
Return type:: Iterator[PullRequestIterationRecord]

iter_statuses()

Iterate over status checks posted on this pull request.

Yields:: PullRequestStatusInfo for each status item, in API-returned order.
Return type:: Iterator[PullRequestStatusInfo]

iter_tag_details()

Iterate over full tag objects for all tags set on the pull request.

Use this instead of iter_tags() when you need the tag ID, URL, or active status, not just the name string.

Yields:: PullRequestLabel for each tag set on the pull request.
Return type:: Iterator[PullRequestLabel]

iter_tags()

Iterate over the tag names set on the pull request.

Yields:: Tag name strings; nothing when no tags are set.
Return type:: Iterator[str]

iter_threads()

Iterate over all review threads on the pull request.

Yields:: PullRequestThreadResponse for each thread.
Return type:: Iterator[PullRequestThreadResponse]

iter_work_item_ids()

Iterate over work item IDs linked to the pull request.

Yields:: Integer work item IDs associated with the PR.
Return type:: Iterator[int]

iter_work_items()

Iterate over work items linked to the pull request.

Convenience wrapper that resolves the linked IDs via iter_work_item_ids() and then fetches the work item details in a single batch call.

Yields:: WorkItem for each linked work item.
Return type:: Iterator[WorkItem]

link_work_item(work_item, *, comment=None)

Link this pull request to a work item via an ArtifactLink relation.

Adds the PR as an ArtifactLink relation on the work item so that the association appears in both the PR timeline and the work item links.

Parameters:

work_item (WorkItem) – The WorkItem to link to this pull request.
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

list_commits()

Return all commits in this pull request as a list.

Return type:: list[Commit]

list_files_changed()

Return all files changed in this pull request as a list.

Return type:: list[PullRequestIterationChange]

list_iterations()

Return all iterations for this pull request as a list.

Return type:: list[PullRequestIterationRecord]

list_reviewers()

Return all reviewers on the pull request.

Returns:: List of PullRequestReviewer entries.
Return type:: list[PullRequestReviewer]

list_statuses()

Return all status checks on this pull request as a list.

Return type:: list[PullRequestStatusInfo]

list_tag_details()

Return full tag objects for all tags set on the pull request.

Return type:: list[PullRequestLabel]

list_tags()

Return all tag names set on this pull request as a list.

Return type:: list[str]

list_threads()

Return all review threads on this pull request as a list.

Return type:: list[PullRequestThreadResponse]

list_work_item_ids()

Return all linked work item IDs as a list.

Return type:: list[int]

list_work_items()

Return all linked work items as a list.

Return type:: list[WorkItem]

property org: Organization: Organisation this pull request belongs to — zero-cost.

property project: Project: Project this pull request belongs to — zero-cost.

refresh(expand=None)

Discard cached pull request info.

The next access to info re-fetches from the API.

Parameters:: expand (str | None) – $expand value to use on the next fetch. When None (default), re-uses the expand value from construction or the last explicit refresh call. When provided, updates the stored expand so subsequent bare refresh() calls use it.
Return type:: None

remove_reviewer(reviewer_id)

Remove a reviewer from the pull request.

Parameters:: reviewer_id (str) – Identity (object) ID of the reviewer.
Return type:: None

remove_tag(name)

Remove a tag from the pull request.

Parameters:: name (str) – Tag name to remove.
Return type:: None

Note

The ADO tag endpoints return no body, so this method returns None. Call get_tags() afterwards if you need the updated tag list.

reply_to_thread(thread_id, content, *, parent_comment_id=1)

Add a reply to an existing review thread.

Parameters:

thread_id (int) – ID of the thread to reply to.
content (str) – Text content of the reply.
parent_comment_id (int) – ID of the comment being replied to (default: 1, the thread’s first comment).

Returns:

The created PullRequestThreadCommentResponse.

Return type:

property repo: Repository: Repository this pull request belongs to — zero-cost.

set_status(state, context_name, *, description=None, iteration_id=1, target_url=None, genre=None)

Post a status check result on the pull request.

Parameters:

state (PullRequestStatusState) – Status state to report.
context_name (str) – Unique name for the status context (e.g. the CI check name).
description (str | None) – Optional human-readable description.
iteration_id (int) – PR iteration the status applies to (default: 1).
target_url (str | None) – Optional URL to link to for details.
genre (str | None) – Optional genre grouping for the context.

Return type:

None

set_work_item_refs(work_item_ids)

Set the work items visible on the pull request page.

Replaces the PR’s workItemRefs list so the given work items appear in the ADO pull request UI. To also add the reverse link on the work item side, call link_work_item() for each item.

Parameters:: work_item_ids (list[int]) – Numeric IDs of the work items to associate.
Return type:: None

property source_branch: str | None: Source ref name (e.g. "refs/heads/feature/my-branch").

property status: PullRequestStatus | None: Pull request lifecycle status (e.g. "active", "completed").

sync_tags(desired)

Synchronise the PR tags to match desired.

Parameters:: desired (set[str]) – The exact set of tag names the PR should have after the call.
Return type:: None

property target_branch: str | None: Target ref name (e.g. "refs/heads/main").

property title: str | None: Pull request title.

update(*, title=None, description=None, status=None, is_draft=None)

Update pull request metadata.

Only non-None arguments are sent to ADO.

Parameters:

title (str | None) – New PR title.
description (str | None) – New PR description.
status (PullRequestStatus | None) – New PR status ("active", "abandoned", or "completed").
is_draft (bool | None) – Set or clear the draft flag.

Return type:

None

update_thread_status(thread_id, status)

Update the status of an existing review thread.

Parameters:

thread_id (int) – Numeric ID of the thread to update. Obtain it from iter_threads().
status (PullRequestThreadStatus) – New status for the thread (e.g. PullRequestThreadStatus.FIXED).

Returns:

Updated PullRequestThreadResponse reflecting the new status.

Return type:

vote(reviewer_id, vote, *, is_reapprove=False)

Cast a reviewer vote on the pull request.

Parameters:

reviewer_id (str) – Identity ID of the reviewer casting the vote.
vote (PullRequestVote) – Vote value to submit.
is_reapprove (bool) – When True, the approval is processed even if the vote has not changed.

Return type:

None

Branch¶

OOP wrapper for an Azure DevOps git branch.

class pyado.oop.repos.branch.Branch(repo, ref)¶

A git branch in an Azure DevOps repository.

Wraps a GitRef for a refs/heads/… ref and exposes branch-specific convenience methods. Instances are obtained from ProjectRepos.iter_branches() or Repository.iter_branches().

Parameters:

repo (Repository)
ref (GitRef)

_repo¶: The Repository this branch belongs to.

_ref¶: The underlying GitRef data.

property commit_id: str¶: Current HEAD commit SHA of the branch.

delete()¶

Delete this branch from the repository.

Uses the stored commit SHA as the optimistic-concurrency guard.

Return type:: None

property full_name: str¶: Full ref name (e.g. "refs/heads/main").

get_commit()¶

Return the HEAD commit of this branch.

Returns:: Commit at the tip of this branch.
Return type:: Commit

property name: str¶: Short branch name (refs/heads/ prefix stripped).

property ref: GitRef¶: Underlying GitRef data.

property repo: Repository¶: Repository this branch belongs to — zero-cost.

Tag¶

OOP wrapper for an Azure DevOps git tag.

class pyado.oop.repos.tag.Tag(repo, ref)¶

A git tag in an Azure DevOps repository.

Wraps a GitRef for a refs/tags/… ref and exposes tag-specific convenience methods. Instances are obtained from Repository.iter_git_tags() or ProjectRepos.iter_git_tags().

Parameters:

repo (Repository)
ref (GitRef)

_repo¶: The Repository this tag belongs to.

_ref¶: The underlying GitRef data.

property commit_id: str¶: Commit SHA the tag points at.

delete()¶

Delete this tag from the repository.

Uses the stored commit SHA as the optimistic-concurrency guard.

Return type:: None

property full_name: str¶: Full ref name (e.g. "refs/tags/v1.0").

get_annotated_info()¶

Return the annotated tag metadata, or None for lightweight tags.

Returns:: AnnotatedTagInfo with tagger, message, and tagged-object details, or None if this is a lightweight tag.
Return type:: AnnotatedTagInfo | None

get_commit()¶

Return the commit this tag points at.

Returns:: Commit the tag targets.
Raises:: AzureDevOpsNotFoundError – If the commit or annotated tag object cannot be resolved.
Return type:: Commit

property name: str¶: Short tag name (refs/tags/ prefix stripped).

property ref: GitRef¶: Underlying GitRef data.

property repo: Repository¶: Repository this tag belongs to — zero-cost.

Commit¶

OOP wrapper for Azure DevOps git commit resources.

class pyado.oop.repos.commit.Commit(repo, info)

An Azure DevOps git commit.

Wraps a GitCommitRef and exposes its data as properties. Instances are obtained from Repository.get_commit() or Repository.iter_commits().

Parameters:

repo (Repository)
info (GitCommitRef)

_repo: The Repository this commit belongs to.

_info: The commit data returned from the API.

property author_date: datetime | None: UTC datetime the commit was authored, or None.

property author_email: str | None: Email of the commit author, or None if not in the API response.

property author_name: str | None: Name of the commit author, or None if not present in the API response.

property committer_date: datetime | None: UTC datetime the commit was applied, or None.

property committer_email: str | None: Email of the committer, or None if not present in the API response.

property committer_name: str | None: Name of the committer, or None if not present in the API response.

get_file(path)

Return the content of a file at this commit.

Parameters:: path (str) – Absolute file path within the repository (e.g. "/src/foo.py").
Returns:: File content as a UTF-8 string, or "" if the file is absent.
Return type:: str

get_pull_request()

Return the first active PR whose source branch contains this commit.

Delegates to Repository.get_pr_for_commit().

Returns:: PullRequest for the first active PR containing this commit, or None if no such PR exists.
Return type:: PullRequest | None

property info: GitCommitRef: Commit data captured at construction time.

iter_changes()

Iterate over files changed by this commit.

Uses the first parent commit as the diff base. Yields nothing for root commits (no parents).

Yields:: GitCommitChange for each changed file.
Return type:: Iterator[GitCommitChange]

list_changes()

Return all file changes in this commit as a list.

Return type:: list[GitCommitChange]

list_statuses()

Return the CI statuses attached to this commit.

Statuses are populated when the commit was fetched via an endpoint that includes status data. Call Repository.get_commit() (which uses get_commit_by_id) to ensure statuses are included.

Returns:: List of GitStatus objects; empty when none are present.
Return type:: list[GitStatus]

property message: str | None

Commit message; may be truncated for long messages.

Check comment_truncated on info to detect truncation.

property org: Organization: Organisation this commit belongs to — zero-cost.

property project: Project: Project this commit belongs to — zero-cost.

refresh(search_criteria=None)

Discard cached commit info.

The next access to info re-fetches from the API.

Parameters:: search_criteria (GitCommitSearchCriteria | None) – Optional search criteria to use on the next fetch. When provided, replaces any previously stored criteria; when None, previously stored criteria are preserved.
Return type:: None

property repo: Repository: Repository this commit belongs to — zero-cost.

property sha: str: Commit SHA (40-character hex string).

File Changes¶

OOP objects for file changes within a git push commit.

class pyado.oop.repos.file_change.AddFile(ado_path, content)¶

A file-add change for use in a push commit.

Creates a new file at the given repository path. The file must not already exist on the target branch; use EditFile to update an existing file.

Parameters:

ado_path (str)
content (str | bytes | Path)

_ado_path¶: Repository-root-relative destination path.

_new_content¶: Resolved content model ready for the push payload.

to_git_change()¶

Return the equivalent GitPushChange model.

Return type:: GitPushChange

class pyado.oop.repos.file_change.DeleteFile(ado_path)¶

A file-delete change for use in a push commit.

Removes an existing file from the repository. The file must exist on the target branch.

Parameters:: ado_path (str)

_ado_path¶: Repository-root-relative path of the file to delete.

to_git_change()¶

Return the equivalent GitPushChange model.

Return type:: GitPushChange

class pyado.oop.repos.file_change.EditFile(ado_path, content)¶

A file-edit change for use in a push commit.

Replaces the full content of an existing file. The file must already exist on the target branch; use AddFile to create a new file.

Content can be supplied as a string (UTF-8 text), bytes (stored as Base64), or a local Path whose contents are read eagerly on construction.

Parameters:

ado_path (str)
content (str | bytes | Path)

_ado_path¶: Repository-root-relative path of the file to update.

_new_content¶: Resolved content model ready for the push payload.

to_git_change()¶

Return the equivalent GitPushChange model.

Return type:: GitPushChange

class pyado.oop.repos.file_change.RenameFile(old_ado_path, new_ado_path)¶

A file-rename change for use in a push commit.

Moves a file to a new path without altering its content. Both the source and destination paths must be valid on the target branch.

Parameters:

old_ado_path (str)
new_ado_path (str)

_old_ado_path¶: Current repository-root-relative path.

_new_ado_path¶: Desired repository-root-relative path after rename.

to_git_change()¶

Return the equivalent GitPushChange model.

Return type:: GitPushChange

Policy Configuration¶

OOP wrapper for Azure DevOps branch policy configuration resources.

class pyado.oop.repos.policy.PolicyConfiguration(project, info)¶

An ADO branch policy configuration.

Also exported from pyado directly as pyado.PolicyConfiguration. The underlying raw Pydantic model is pyado.PolicyConfigurationInfo.

Parameters:

project (Project)
info (PolicyConfigurationInfo)

_project¶: The Project this policy configuration belongs to.

_id¶: Numeric configuration ID (always known).

_info¶: Cached policy configuration data; None after refresh().

property api_call: ApiCall¶: Policy-configuration-level API call for use with raw functions.

property created_by: PolicyCreatedBy | None¶: Identity reference of the creator.

delete()¶

Delete this policy configuration from the project.

Return type:: None

property id: int¶: Numeric policy configuration ID — always known, no API call.

property info: PolicyConfigurationInfo¶

Full policy configuration data as returned by the API.

Fetched lazily from the API if refresh() was called since the last access.

property is_blocking: bool¶: Whether this policy blocks completion when violated.

property is_enabled: bool¶: Whether this policy configuration is enabled.

property org: Organization¶: Organisation this configuration belongs to — zero-cost.

property project: Project¶: Project this configuration belongs to — zero-cost.

refresh()¶

Discard cached policy configuration info.

The next access to info re-fetches from the API.

Return type:: None

property revision: int | None¶: Policy configuration revision number.

property type: PolicyType¶: Policy type definition.

update(request)¶

Update this policy configuration with new settings.

Parameters:: request (PolicyConfigurationRequest) – Updated settings for the policy configuration.
Return type:: None

Policy Types¶

Typed OOP policy models for Azure DevOps branch policy configurations.

Each class wraps a specific policy type with strongly-typed fields and provides round-trip conversion to and from the raw PolicyConfigurationRequest / PolicyConfigurationInfo models.

Policy scope types¶

Two scope variants reflect the two ways ADO applies policies:

RepoPolicyScope — repository-level policies (repositoryId only; no branch filtering). Used by GitRepositoryPolicy, ReservedNamesPolicy, PathLengthPolicy, FileSizeRestrictionPolicy, FileNamePolicy, SearchBranchesPolicy, and CommitAuthorEmailPolicy.
PolicyScope — branch-level policies (repositoryId + refName + matchKind). Used by the remaining seven policy classes.

Typical usage:

import pyado

# Branch-level policy
branch_scope = pyado.PolicyScope.for_default_branch(repo_id)
policy = pyado.MinimumReviewersPolicy(
    scope=[branch_scope],
    minimum_approver_count=2,
    creator_vote_counts=False,
    allow_downvotes=False,
    reset_on_source_push=True,
    require_vote_on_last_iteration=False,
    reset_rejections_on_source_push=False,
    block_last_pusher_vote=False,
)
project.settings.create_policy_configuration(policy.to_request())

# Repository-level policy
repo_scope = pyado.RepoPolicyScope(repository_id=repo_id)
size_policy = pyado.FileSizeRestrictionPolicy(
    scope=[repo_scope],
    maximum_git_blob_size_in_bytes=10_485_760,
    use_uncompressed_size=False,
)
project.settings.create_policy_configuration(size_policy.to_request())

class pyado.oop.repos.policy_types.BasePolicyModel(*, isEnabled=True, isBlocking=True)¶

Base class for typed OOP policy models.

Subclasses declare a POLICY_TYPE_ID class variable and the policy-specific fields. The three conversion methods are implemented here and require no overriding in concrete subclasses.

Parameters:

isEnabled (bool)
isBlocking (bool)

classmethod from_info(info)¶

Construct this policy model from a raw PolicyConfigurationInfo.

Parameters:: info (PolicyConfigurationInfo) – A PolicyConfigurationInfo returned by the ADO policy endpoint.
Returns:: A fully populated instance of this policy model.
Return type:: Self

classmethod from_request(request)¶

Construct this policy model from a raw PolicyConfigurationRequest.

Parameters:: request (PolicyConfigurationRequest) – A PolicyConfigurationRequest previously built by to_request() or constructed manually.
Returns:: A fully populated instance of this policy model.
Return type:: Self

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_request()¶

Serialise this model to a raw PolicyConfigurationRequest.

The is_enabled and is_blocking fields are lifted to the top level of the request; all remaining fields are serialised as the settings dict in camelCase.

Returns:: A PolicyConfigurationRequest ready to pass to post_policy_configuration() or put_policy_configuration().
Return type:: PolicyConfigurationRequest

class pyado.oop.repos.policy_types.BuildPolicy(*, isEnabled=True, isBlocking=True, scope, buildDefinitionId, queueOnSourceUpdateOnly, manualQueueOnly, validDuration, displayName=None, filenamePatterns=None)¶

Typed policy model for ‘Build’ policy.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[PolicyScope])
buildDefinitionId (int)
queueOnSourceUpdateOnly (bool)
manualQueueOnly (bool)
validDuration (float)
displayName (str | None)
filenamePatterns (list[str] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.CommentRequirementsPolicy(*, isEnabled=True, isBlocking=True, scope)¶

Typed policy model for ‘Comment requirements’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[PolicyScope])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.CommitAuthorEmailPolicy(*, isEnabled=True, isBlocking=True, scope, authorEmailPatterns=None)¶

Typed policy model for ‘Commit author email validation’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[RepoPolicyScope])
authorEmailPatterns (list[str] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.FileNamePolicy(*, isEnabled=True, isBlocking=True, scope, filenamePatterns=None)¶

Typed policy model for ‘File name restriction’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[RepoPolicyScope])
filenamePatterns (list[str] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.FileSizeRestrictionPolicy(*, isEnabled=True, isBlocking=True, scope, maximumGitBlobSizeInBytes, useUncompressedSize)¶

Typed policy model for ‘File size restriction’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[RepoPolicyScope])
maximumGitBlobSizeInBytes (int)
useUncompressedSize (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.GitRepositoryPolicy(*, isEnabled=True, isBlocking=True, scope, enforceConsistentCase=None, rejectDotGit=None, optimizedByDefault=None, breadcrumbDays=None, allowedForkTargets=None, gvfsOnly=None, gvfsExemptUsers=None, gvfsAllowedVersionRanges=None, detectRenameFalsePositivesByDefault=None, strictVoteMode=None, inheritPullRequestCreationMode=None, repoPullRequestAsDraftByDefault=None, repoPullRequestAutoCompleteByDefault=None)¶

Typed policy model for ‘Git repository settings’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[RepoPolicyScope])
enforceConsistentCase (bool | None)
rejectDotGit (bool | None)
optimizedByDefault (bool | None)
breadcrumbDays (int | None)
allowedForkTargets (int | None)
gvfsOnly (bool | None)
gvfsExemptUsers (Any | None)
gvfsAllowedVersionRanges (Any | None)
detectRenameFalsePositivesByDefault (bool | None)
strictVoteMode (bool | None)
inheritPullRequestCreationMode (bool | None)
repoPullRequestAsDraftByDefault (bool | None)
repoPullRequestAutoCompleteByDefault (bool | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.MergeStrategyPolicy(*, isEnabled=True, isBlocking=True, scope, allowNoFastForward=None, allowSquash=None, allowRebase=None, allowRebaseMerge=None)¶

Typed policy model for ‘Require a merge strategy’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[PolicyScope])
allowNoFastForward (bool | None)
allowSquash (bool | None)
allowRebase (bool | None)
allowRebaseMerge (bool | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.MinimumReviewersPolicy(*, isEnabled=True, isBlocking=True, scope, minimumApproverCount, creatorVoteCounts, allowDownvotes, resetOnSourcePush, requireVoteOnLastIteration, resetRejectionsOnSourcePush, blockLastPusherVote, requireVoteOnEachIteration=None)¶

Typed policy model for ‘Minimum number of reviewers’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[PolicyScope])
minimumApproverCount (int)
creatorVoteCounts (bool)
allowDownvotes (bool)
resetOnSourcePush (bool)
requireVoteOnLastIteration (bool)
resetRejectionsOnSourcePush (bool)
blockLastPusherVote (bool)
requireVoteOnEachIteration (bool | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.PathLengthPolicy(*, isEnabled=True, isBlocking=True, scope, maxPathLength)¶

Typed policy model for ‘Path Length restriction’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[RepoPolicyScope])
maxPathLength (int)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.RepoPolicyScope(*, repositoryId=None)¶

Repository scope for policies that apply at repository (not branch) level.

Repository-level policies (e.g. file-size restriction, reserved-names) target a whole repository, not a specific branch. Pass None as repository_id to apply the policy to every repository in the project.

Parameters:: repositoryId (UUID | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.RequiredReviewersPolicy(*, isEnabled=True, isBlocking=True, scope, requiredReviewerIds, minimumApproverCount, creatorVoteCounts, message=None, filenamePatterns=None)¶

Typed policy model for ‘Required reviewers’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[PolicyScope])
requiredReviewerIds (list[UUID])
minimumApproverCount (int)
creatorVoteCounts (bool)
message (str | None)
filenamePatterns (list[str] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.ReservedNamesPolicy(*, isEnabled=True, isBlocking=True, scope)¶

Typed policy model for ‘Reserved names restriction’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[RepoPolicyScope])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.SearchBranchesPolicy(*, isEnabled=True, isBlocking=True, scope, searchBranches)¶

Typed policy model for ‘Search branches’ policy.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[RepoPolicyScope])
searchBranches (list[str])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.StatusPolicy(*, isEnabled=True, isBlocking=True, scope, statusName, statusGenre, authorId, invalidateOnSourceUpdate, defaultDisplayName, policyApplicability=None, filenamePatterns=None)¶

Typed policy model for ‘Status’ policy.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[PolicyScope])
statusName (str)
statusGenre (StatusGenre)
authorId (UUID)
invalidateOnSourceUpdate (bool)
defaultDisplayName (str)
policyApplicability (Any | None)
filenamePatterns (list[str] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.oop.repos.policy_types.WorkItemLinkingPolicy(*, isEnabled=True, isBlocking=True, scope)¶

Typed policy model for ‘Work item linking’.

Parameters:

isEnabled (bool)
isBlocking (bool)
scope (list[PolicyScope])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Overview¶

Overview section of the Azure DevOps OOP layer.

Exposes Dashboard and Wiki — resource wrappers for ADO dashboards and wikis.

class pyado.oop.overview.Dashboard(team, info)¶

An ADO team dashboard.

Wraps a single ADO team dashboard and exposes its properties and widgets. Instances are obtained from Team.iter_dashboards(), Team.get_dashboard(), Project.iter_dashboards(), or Project.get_dashboard().

Parameters:

team (Team)
info (DashboardInfo)

_team¶: The Team this dashboard belongs to.

_id¶: Dashboard UUID (always known).

_info¶: Cached dashboard data; None after refresh().

property api_call: ApiCall¶: Dashboard-level API call for direct use with pyado.raw functions.

property id: UUID¶: Dashboard UUID — always known, no API call.

property info: DashboardInfo¶

Full dashboard data as returned by the API.

Fetched lazily from the API if refresh() was called since the last access.

property name: str¶: Dashboard name.

property org: Organization¶: Organisation this dashboard belongs to — zero-cost.

property project: Project¶: Project this dashboard belongs to — zero-cost.

refresh()¶

Discard cached dashboard info.

The next access to info re-fetches from the API.

Return type:: None

property team: Team¶: Team this dashboard belongs to — zero-cost.

property widgets: list[WidgetInfo]¶: Widget list — populated only after a full detail fetch.

class pyado.oop.overview.Wiki(project, info)¶

An ADO project wiki.

Wraps a single ADO wiki and exposes its pages. Instances are obtained from Project.iter_wikis() or Project.list_wikis().

Parameters:

project (Project)
info (WikiInfo)

_project¶: The Project this wiki belongs to.

_info¶: Wiki metadata returned by the API.

delete_page(path, *, version)¶

Delete a wiki page by path.

Parameters:

path (str) – Page path relative to the wiki root.
version (int) – Current ETag version of the page.

Returns:

WikiPageDetail of the deleted page.

Return type:

get_page(path, *, include_content=True)¶

Fetch a single wiki page by path.

Parameters:

path (str) – Page path relative to the wiki root (e.g. "/README").
include_content (bool) – Whether to include the page content in the response. Defaults to True.

Returns:

WikiPageDetail for the requested page.

Return type:

property id: UUID¶: Wiki UUID.

property info: WikiInfo¶: Full wiki data as returned by the API.

iter_pages(*, recursion_level=2)¶

Iterate over root pages for this wiki.

Parameters:: recursion_level (int) – How many levels of child pages to include. Defaults to 2.
Yields:: WikiPage objects at the root level, each with nested sub_pages up to the requested depth.
Return type:: Iterator[WikiPage]

list_page_attachments(page_id)¶

Return all attachments for a wiki page.

Parameters:: page_id (int) – Numeric ID of the wiki page.
Returns:: List of WikiPageAttachment objects for the page.
Return type:: list[WikiPageAttachment]

list_pages(*, recursion_level=2)¶

Return the root page tree for this wiki.

Parameters:: recursion_level (int) – How many levels of child pages to include. Defaults to 2.
Returns:: List of WikiPage objects at the root level, each with nested sub_pages up to the requested depth.
Return type:: list[WikiPage]

property name: str¶: Wiki name.

property org: Organization¶: Organisation this wiki belongs to — zero-cost.

property project: Project¶: Project this wiki belongs to — zero-cost.

put_page(path, content, *, version=None)¶

Create or update a wiki page.

Parameters:

path (str) – Page path relative to the wiki root.
content (str) – New Markdown content for the page.
version (int | None) – Current ETag version of the page. Omit when creating a new page.

Returns:

WikiPageDetail reflecting the created or updated page.

Return type:

property type: WikiType | None¶: Wiki type (projectWiki or codeWiki).

Dashboard¶

OOP wrapper for Azure DevOps team dashboard resources.

class pyado.oop.overview.dashboard.Dashboard(team, info)¶

An ADO team dashboard.

Parameters:

team (Team)
info (DashboardInfo)

_team¶: The Team this dashboard belongs to.

_id¶: Dashboard UUID (always known).

_info¶: Cached dashboard data; None after refresh().

property api_call: ApiCall¶: Dashboard-level API call for direct use with pyado.raw functions.

property id: UUID¶: Dashboard UUID — always known, no API call.

property info: DashboardInfo¶

Full dashboard data as returned by the API.

Fetched lazily from the API if refresh() was called since the last access.

property name: str¶: Dashboard name.

property org: Organization¶: Organisation this dashboard belongs to — zero-cost.

property project: Project¶: Project this dashboard belongs to — zero-cost.

refresh()¶

Discard cached dashboard info.

The next access to info re-fetches from the API.

Return type:: None

property team: Team¶: Team this dashboard belongs to — zero-cost.

property widgets: list[WidgetInfo]¶: Widget list — populated only after a full detail fetch.

Wiki¶

OOP wrapper for Azure DevOps project wiki resources.

class pyado.oop.overview.wiki.Wiki(project, info)¶

An ADO project wiki.

Wraps a single ADO wiki and exposes its pages. Instances are obtained from Project.iter_wikis() or Project.list_wikis().

Parameters:

project (Project)
info (WikiInfo)

_project¶: The Project this wiki belongs to.

_info¶: Wiki metadata returned by the API.

delete_page(path, *, version)¶

Delete a wiki page by path.

Parameters:

path (str) – Page path relative to the wiki root.
version (int) – Current ETag version of the page.

Returns:

WikiPageDetail of the deleted page.

Return type:

get_page(path, *, include_content=True)¶

Fetch a single wiki page by path.

Parameters:

path (str) – Page path relative to the wiki root (e.g. "/README").
include_content (bool) – Whether to include the page content in the response. Defaults to True.

Returns:

WikiPageDetail for the requested page.

Return type:

property id: UUID¶: Wiki UUID.

property info: WikiInfo¶: Full wiki data as returned by the API.

iter_pages(*, recursion_level=2)¶

Iterate over root pages for this wiki.

Parameters:: recursion_level (int) – How many levels of child pages to include. Defaults to 2.
Yields:: WikiPage objects at the root level, each with nested sub_pages up to the requested depth.
Return type:: Iterator[WikiPage]

list_page_attachments(page_id)¶

Return all attachments for a wiki page.

Parameters:: page_id (int) – Numeric ID of the wiki page.
Returns:: List of WikiPageAttachment objects for the page.
Return type:: list[WikiPageAttachment]

list_pages(*, recursion_level=2)¶

Return the root page tree for this wiki.

Parameters:: recursion_level (int) – How many levels of child pages to include. Defaults to 2.
Returns:: List of WikiPage objects at the root level, each with nested sub_pages up to the requested depth.
Return type:: list[WikiPage]

property name: str¶: Wiki name.

property org: Organization¶: Organisation this wiki belongs to — zero-cost.

property project: Project¶: Project this wiki belongs to — zero-cost.

put_page(path, content, *, version=None)¶

Create or update a wiki page.

Parameters:

path (str) – Page path relative to the wiki root.
content (str) – New Markdown content for the page.
version (int | None) – Current ETag version of the page. Omit when creating a new page.

Returns:

WikiPageDetail reflecting the created or updated page.

Return type:

property type: WikiType | None¶: Wiki type (projectWiki or codeWiki).

Boards¶

Boards section of the Azure DevOps OOP layer.

Exposes ProjectBoards — the project.boards section object — plus re-exports of all resource classes in this sub-package.

class pyado.oop.boards.Area(project, info)¶

An Azure DevOps area classification node.

Wraps a single area node and exposes its properties. Instances are obtained from ProjectBoards.get_area_node().

Unlike iteration nodes, area nodes carry no date attributes. Child nodes are returned as Area instances wrapping the children list embedded in the API response (no extra API call is made). To fetch children at a specific depth, call ProjectBoards.get_area_node() with a higher depth argument.

Parameters:

project (Project)
info (ClassificationNode)

_project¶: The Project this area belongs to.

_info¶: The ClassificationNode data for this node.

property children: list[Area]¶

Child area nodes embedded in the API response.

Returns an empty list when either no children are present or the response was fetched at depth 0. Call ProjectBoards.get_area_node() with a higher depth to populate children.

create_child(name)¶

Create a child area node under this node.

Parameters:: name (str) – Name of the new child area node.
Returns:: Area wrapping the newly created child area node.
Return type:: Area

delete()¶

Delete this area node.

Return type:: None

property id: int¶: Numeric node ID.

property info: ClassificationNode¶: Raw node data captured at construction time.

property name: str¶: Node name (e.g. "Team A").

property org: Organization¶: Organisation this area belongs to — zero-cost.

property path: str | None¶: Full path as returned by the API (e.g. "\\\\Proj\\\\Team A").

property project: Project¶: Project this area belongs to — zero-cost.

refresh()¶

Discard cached area node info.

The next access to info re-fetches from the API.

Return type:: None

update(name)¶

Rename this area node.

Parameters:: name (str) – New name for the area node.
Return type:: None

class pyado.oop.boards.Iteration(project, info)¶

An Azure DevOps iteration classification node.

Wraps a single iteration node and exposes its properties and patch operation. Instances are obtained from ProjectBoards.get_iteration_node().

Iteration nodes may carry start and finish dates. Child nodes are returned as Iteration instances wrapping the children list embedded in the API response (no extra API call is made). To fetch children at a specific depth, call ProjectBoards.get_iteration_node() with a higher depth argument.

Parameters:

project (Project)
info (ClassificationNode)

_project¶: The Project this iteration belongs to.

_info¶: The ClassificationNode data for this node.

add_to_team(team)¶

Assign this iteration node to a team.

Parameters:: team (Team) – The Team to assign this iteration to.
Raises:: ValueError – If the iteration node has no identifier (UUID).
Return type:: None

property children: list[Iteration]¶

Child iteration nodes embedded in the API response.

Returns an empty list when either no children are present or the response was fetched at depth 0. Call ProjectBoards.get_iteration_node() with a higher depth to populate children.

create_child(name)¶

Create a child iteration node under this node.

Parameters:: name (str) – Name of the new child iteration node.
Returns:: Iteration wrapping the newly created child iteration node.
Return type:: Iteration

delete()¶

Delete this iteration node.

Return type:: None

property finish_date: date | None¶: Iteration finish (end) date, or None if not set.

property id: int¶: Numeric node ID.

property info: ClassificationNode¶: Raw node data captured at construction time.

property name: str¶: Node name (e.g. "Sprint 1").

property org: Organization¶: Organisation this iteration belongs to — zero-cost.

property path: str | None¶: Full path as returned by the API (e.g. "\\\\Proj\\\\Sprint 1").

property project: Project¶: Project this iteration belongs to — zero-cost.

refresh()¶

Discard cached iteration node info.

The next access to info re-fetches from the API.

Return type:: None

property start_date: date | None¶: Iteration start date, or None if not set.

update(*, name=None, start_date=None, finish_date=None)¶

Update the name and/or dates of this iteration node.

Parameters:

name (str | None) – New name for the iteration node, or None to leave unchanged.
start_date (date | None) – New start date, or None to leave unchanged.
finish_date (date | None) – New finish (end) date, or None to leave unchanged.

Return type:

None

class pyado.oop.boards.ProjectBoards(project)¶

The Boards section of a project.

Accessed via project.boards. Exposes all work-item, iteration, area, team, and query operations that belong to the ADO Boards section.

Parameters:: project (Project)

_project¶: The owning Project.

add_team_iteration(team_name, iteration_id)¶

Assign an existing iteration node to a team.

Parameters:

team_name (str) – Name of the team within this project.
iteration_id (UUID) – UUID of the iteration classification node to assign.

Return type:

None

create_area(name, parent_path=None)¶

Create a new area node under a parent path.

Parameters:

name (str) – Name of the new area node.
parent_path (str | None) – Path of the parent node within the area tree, or None to create at the root.

Returns:

Area wrapping the newly created area node.

Return type:

Area

create_iteration(name, parent_path=None, *, start_date=None, finish_date=None)¶

Create a new iteration node under a parent path.

Parameters:

name (str) – Name of the new iteration node.
parent_path (str | None) – Path of the parent node within the iteration tree, or None to create at the root.
start_date (date | None) – Optional start date for the iteration.
finish_date (date | None) – Optional end date for the iteration.

Returns:

Iteration wrapping the newly created iteration node.

Return type:

Iteration

create_work_item(ticket_type, fields, relations=None, *, multiline_fields_format=None)¶

Create a new work item in the project.

Parameters:

ticket_type (str) – ADO work item type name (e.g. "Task", "Bug", "User Story").
fields (dict[str, Any]) – Mapping of field reference names to values. "System.WorkItemType" must not appear in fields; it is set automatically from ticket_type.
relations (list[WorkItemRelation] | None) – Optional list of work item relations to add.
multiline_fields_format (dict[str, TextFormat] | None) – Optional per-field format override ("html" or "markdown").

Returns:

WorkItem wrapping the newly created work item.

Raises:

ValueError – If fields contains "System.WorkItemType".

Return type:

WorkItem

get_area_node(path=None, *, depth=1)¶

Return the area classification node tree for the project.

Parameters:

path (str | None) – Path within the area tree (e.g. "Team A"), or None for the root.
depth (int) – Number of child levels to fetch below the node (default: 1).

Returns:

Area wrapping the requested node, with children populated to depth levels.

Return type:

Area

get_iteration_node(path=None, *, depth=1)¶

Return the iteration classification node tree for the project.

Parameters:

path (str | None) – Path within the iteration tree (e.g. "Sprint 1"), or None for the root.
depth (int) – Number of child levels to fetch below the node (default: 1).

Returns:

Iteration wrapping the requested node, with children populated to depth levels.

Return type:

Iteration

get_query_folder(folder_id, *, depth=1, expand=WorkItemQueryExpand.ALL)¶

Return a specific query folder by ID.

Parameters:

folder_id (str) – UUID of the query folder.
depth (int) – Number of folder levels to expand (default: 1).
expand (WorkItemQueryExpand) – Which fields to include in the response.

Returns:

WorkItemQuery representing the requested folder.

Return type:

WorkItemQuery

get_query_tree(*, depth=2, expand=WorkItemQueryExpand.ALL)¶

Return the root-level query folders for the project.

ADO exposes two root folders — “My Queries” and “Shared Queries”. Use get_query_folder() with a folder’s id to drill into a specific folder.

Parameters:

depth (int) – Number of folder levels to expand below the root folders (default: 2).
expand (WorkItemQueryExpand) – Which fields to include in the response.

Returns:

List of WorkItemQuery objects, one per root folder.

Return type:

list[WorkItemQuery]

get_team(name)¶

Return a specific team by name.

Parameters:: name (str) – Team name (case-sensitive).
Returns:: Team wrapping the requested team.
Return type:: Team

get_team_by_id(team_id)¶

Return a specific team by ID.

Parameters:: team_id (str) – Team ID.
Returns:: Team wrapping the requested team.
Return type:: Team

get_work_item(work_item_id)¶

Return a wrapper for a specific work item.

Parameters:: work_item_id (int) – Numeric ID of the work item.
Returns:: WorkItem wrapping the requested work item.
Return type:: WorkItem

get_work_item_type(name)¶

Return a specific work item type by display name.

Parameters:: name (str) – Work item type display name (e.g. "Bug").
Returns:: WorkItemType wrapping the requested work item type.
Raises:: KeyError – If no work item type with the given name exists.
Return type:: WorkItemType

iter_team_sprint_iterations(team_name, *, timeframe_filter=None)¶

Iterate over sprint iterations for a team.

Parameters:

team_name (str) – Name of the team within this project.
timeframe_filter (SprintIterationTimeframe | None) – When provided, restricts results to a specific timeframe. ADO only supports SprintIterationTimeframe.CURRENT.

Yields:

SprintIterationInfo for each sprint iteration.

Return type:

Iterator[SprintIterationInfo]

iter_teams()¶

Iterate over all teams in this project.

Yields:: Team for each team in the project.
Return type:: Iterator[Team]

iter_work_item_type_categories()¶

Iterate over work item type category definitions in this project.

Yields:: WorkItemTypeCategoryInfo for each category.
Return type:: Iterator[WorkItemTypeCategoryInfo]

iter_work_item_types()¶

Iterate over all work item type definitions in this project.

Yields:: WorkItemType for each work item type definition.
Return type:: Iterator[WorkItemType]

iter_work_items(query)¶

Iterate over work items matching a WIQL query.

Parameters:: query (str) – WIQL query string. The SELECT list determines which fields are returned; use SELECT [System.Id] as a minimum.
Yields:: WorkItem for each work item returned by the query.
Return type:: Iterator[WorkItem]

iter_work_items_by_ids(ids, *, expand=WorkItemExpand.RELATIONS)¶

Iterate over multiple work items by ID using a single API call.

Prefer this over repeated get_work_item() calls when you already have a list of IDs.

Parameters:

ids (list[int]) – List of numeric work item IDs to fetch.
expand (WorkItemExpand | None) – Expand mode controlling which extra data ADO includes (default: WorkItemExpand.RELATIONS). Pass None to fetch fields only.

Yields:

WorkItem for each ID, in the same order as ids.

Return type:

Iterator[WorkItem]

list_team_field_values(team_name)¶

Return the area-path field configuration for a team.

Parameters:: team_name (str) – Name of the team within this project.
Returns:: List of TeamFieldValue entries describing the team’s allowed area paths.
Return type:: list[TeamFieldValue]

list_team_sprint_iterations(team_name, *, timeframe_filter=None)¶

Return sprint iterations for a team as a list.

Parameters:

team_name (str)
timeframe_filter (SprintIterationTimeframe | None)

Return type:

list[SprintIterationInfo]

list_teams()¶

Return all teams in the project as a list.

Return type:: list[Team]

list_work_item_type_categories()¶

Return all work item type category definitions as a list.

Return type:: list[WorkItemTypeCategoryInfo]

list_work_item_types()¶

Return all work item type definitions in this project as a list.

Return type:: list[WorkItemType]

list_work_items(query)¶

Return all work items matching a WIQL query as a list.

Parameters:: query (str)
Return type:: list[WorkItem]

list_work_items_by_ids(ids, *, expand=WorkItemExpand.RELATIONS)¶

Fetch multiple work items by ID in a single API call.

Prefer this over repeated get_work_item() calls when you already have a list of IDs (e.g. from iter_work_item_ids()).

Parameters:

ids (list[int]) – List of numeric work item IDs to fetch.
expand (WorkItemExpand | None) – Expand mode controlling which extra data ADO includes (default: WorkItemExpand.RELATIONS). Pass None to fetch fields only.

Returns:

List of WorkItem objects, in the same order as ids.

Return type:

list[WorkItem]

class pyado.oop.boards.Team(project, info, service)¶

An Azure DevOps team within a project.

Wraps a single ADO team and exposes its properties. Instances are obtained from Project.iter_teams() or Project.get_team().

The api_call property returns a team-level call suitable for raw functions such as get_team_field_values() and post_team_iteration().

Parameters:

project (Project)
info (TeamInfo)
service (AzureDevOpsService)

_project¶: The Project this team belongs to.

_info¶: TeamInfo data returned by the API.

add_iteration(iteration_id)¶

Assign an existing iteration node to this team.

Parameters:: iteration_id (UUID) – UUID of the iteration classification node to assign.
Return type:: None

property api_call: ApiCall¶

Team-level API call for use with raw teamsettings functions.

ADO team-scoped endpoints use the URL form {org}/{project}/{team}/_apis/..., so the team name must sit before /_apis, not after it.

get_dashboard(dashboard_id)¶

Return a specific dashboard by ID.

Parameters:: dashboard_id (UUID) – UUID of the dashboard.
Returns:: Dashboard wrapping the requested dashboard.
Return type:: Dashboard

property id: str¶: Team UUID string.

property info: TeamInfo¶: Full team data as returned by the API.

iter_dashboards()¶

Iterate over all dashboards for this team.

Yields:: Dashboard for each dashboard belonging to this team.
Return type:: Iterator[Dashboard]

iter_members()¶

Iterate over all members of this team.

Yields:: TeamMember for each team member.
Return type:: Iterator[TeamMember]

iter_sprint_iterations(*, timeframe_filter=None)¶

Iterate over sprint iterations for this team.

Parameters:: timeframe_filter (SprintIterationTimeframe | None) – When provided, restricts results to a specific timeframe. ADO only supports SprintIterationTimeframe.CURRENT.
Yields:: SprintIterationInfo for each sprint iteration.
Return type:: Iterator[SprintIterationInfo]

list_dashboards()¶

Return all dashboards for this team as a list.

Return type:: list[Dashboard]

list_field_values()¶

Return the area-path field configuration for this team.

Returns:: List of TeamFieldValue entries describing the team’s allowed area paths.
Return type:: list[TeamFieldValue]

list_members()¶

Return all members of this team as a list.

Return type:: list[TeamMember]

list_sprint_iterations(*, timeframe_filter=None)¶

Return all sprint iterations for this team as a list.

Parameters:: timeframe_filter (SprintIterationTimeframe | None)
Return type:: list[SprintIterationInfo]

property name: str¶: Team name.

property org: Organization¶: Organisation this team belongs to — zero-cost.

property project: Project¶: Project this team belongs to — zero-cost.

refresh()¶

Discard cached team info.

The next access to info re-fetches from the API.

Return type:: None

remove_iteration(iteration_id)¶

Remove an iteration from this team’s sprint backlog.

Parameters:: iteration_id (UUID) – UUID of the iteration classification node to remove.
Return type:: None

class pyado.oop.boards.WorkItem(project, work_item_api_call, info, expand=None)¶

An Azure DevOps work item resource.

Wraps a single ADO work item and exposes its operations as instance methods. Instances are obtained from ProjectBoards.get_work_item(), ProjectBoards.iter_work_items(), or ProjectBoards.create_work_item().

Work items are not cached — each factory call returns a fresh instance with the current API state. Call refresh() to re-fetch the info from the API at any time.

Parameters:

project (Project)
work_item_api_call (ApiCall)
info (WorkItemInfo)
expand (WorkItemExpand | None)

_project¶: The Project this work item belongs to.

_api_call¶: Work-item-level API call used by all operations.

_info¶: The work item data returned from the API at construction time.

add_attachment(filename, content)¶

Upload a file and attach it to the work item.

Parameters:

filename (str) – Name of the file as it will appear in ADO.
content (bytes) – Raw bytes of the file to upload.

Returns:

WorkItemAttachmentRef with the ID and URL of the uploaded file.

Return type:

WorkItemAttachmentRef

add_comment(text, *, comment_format=TextFormat.HTML)¶

Add a comment to the work item.

Parameters:

text (str) – Comment body text (HTML or Markdown depending on format).
comment_format (TextFormat) – Format of the comment body — "html" (default) or "markdown".

Returns:

The created WorkItemComment.

Return type:

add_link(other, link_type, *, comment=None)¶

Link this work item to another with the specified relation type.

Covers all work-item-to-work-item relation types (parent, child, related, successor, predecessor, duplicate, etc.). For artifact links (PRs, builds, commits) use the dedicated helpers instead.

Parameters:

other (WorkItem) – Target WorkItem to link to.
link_type (WorkItemRelationType) – Relation type to create (e.g. WorkItemRelationType.PARENT).
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

add_tag(tag)¶

Add a tag to the work item.

If the tag is already present the work item is not modified.

Parameters:: tag (str) – Tag name to add.
Return type:: None

property api_call: ApiCall¶: Work-item-level API call for direct use with pyado.raw functions.

property area_path: str | None¶: Value of the System.AreaPath field, or None if absent.

property assigned_to: Any¶: Value of the System.AssignedTo field (identity dict), or None.

create_child(work_item_type, title, extra_fields=None, *, multiline_fields_format=None)¶

Create a new work item and link it as a child of this one.

Creates a new work item of work_item_type, sets title (and any extra_fields), then adds a parent link from the new item back to self.

Parameters:

work_item_type (str) – Work item type name (e.g. "Task").
title (str) – Title for the new work item.
extra_fields (dict[str, Any] | None) – Additional fields to set on the new work item.
multiline_fields_format (dict[str, TextFormat] | None) – Optional per-field format override forwarded to ProjectBoards.create_work_item().

Returns:

The newly created child WorkItem.

Return type:

WorkItem

delete()¶

Soft-delete this work item.

The item can be restored from the ADO Recycle Bin within 30 days.

Return type:: None

download_attachment(ref)¶

Download the raw bytes of an uploaded attachment.

Parameters:: ref (WorkItemAttachmentRef) – The WorkItemAttachmentRef returned by add_attachment() or iter_attachments().
Returns:: Raw file bytes.
Return type:: bytes

get_field(field)¶

Return the current value of a work item field.

Parameters:: field (str) – Field reference name, e.g. "System.Title".
Returns:: The field value, or None if the field is absent.
Return type:: Any

get_parent()¶

Return the parent work item, or None if none exists.

Returns:: WorkItem for the parent, or None if this work item has no parent relation.
Return type:: WorkItem | None

get_parent_id()¶

Return the ID of the parent work item without making API calls.

Parses the relation URLs from the already-fetched work item data. Requires the info to have been fetched with expand=WorkItemExpand.RELATIONS (the default for ProjectBoards.get_work_item()).

Returns:: Numeric parent work item ID, or None if this work item has no parent relation.
Return type:: int | None

property id: int¶: Numeric work item ID.

property info: WorkItemInfo¶: Work item data captured at construction time (or last refresh).

iter_artifact_links()¶

Iterate over artifact link relations (PRs, builds, commits).

Convenience filter around iter_relations() for WorkItemRelationType.ARTIFACT_LINK.

Yields:: WorkItemRelation for each artifact link.
Return type:: Iterator[WorkItemRelation]

iter_attachments()¶

Iterate over attached-file relations as attachment references.

Convenience filter around iter_relations() for WorkItemRelationType.ATTACHED_FILE. The attachment ID is extracted from each relation URL so the result can be passed directly to download_attachment().

Yields:: WorkItemAttachmentRef for each attached file.
Return type:: Iterator[WorkItemAttachmentRef]

iter_children()¶

Iterate over direct child work items.

Convenience wrapper around iter_linked_work_items() filtered to WorkItemRelationType.CHILD. Requires the info to have been fetched with expand=WorkItemExpand.RELATIONS (the default).

Yields:: WorkItem for each child.
Return type:: Iterator[WorkItem]

iter_comments()¶

Iterate over comments on the work item.

Yields:: WorkItemComment for each comment, in API-returned order.
Return type:: Iterator[WorkItemComment]

iter_linked_work_items(rel_type=None)¶

Iterate over work items linked to this one.

Only work-item-to-work-item relations are returned. Artifact links (PRs, commits, builds) are skipped automatically. Ensure the info was fetched with expand=WorkItemExpand.RELATIONS (the default for ProjectBoards.get_work_item()).

Parameters:: rel_type (WorkItemRelationType | None) – When provided, only relations of this type are yielded (e.g. WorkItemRelationType.CHILD). When None, all WI-to-WI relation types are returned.
Yields:: WorkItem for each linked work item.
Return type:: Iterator[WorkItem]

iter_relations(rel_type=None)¶

Iterate over all relations on this work item.

Returns every relation regardless of type — work item links, artifact links (PRs, builds, commits), attached files, and hyperlinks. Filter by rel_type to narrow the result.

Requires the info to have been fetched with expand=WorkItemExpand.RELATIONS (the default for ProjectBoards.get_work_item()).

Parameters:: rel_type (WorkItemRelationType | None) – When provided, only relations of this type are yielded. When None, all relation types are returned.
Yields:: WorkItemRelation for each matching relation.
Return type:: Iterator[WorkItemRelation]

iter_revisions()¶

Iterate over all historical revisions of this work item, oldest first.

Each revision is a full snapshot of the work item at that point in time. Useful for audit trails and change tracking.

Yields:: WorkItemInfo for each revision, oldest first.
Return type:: Iterator[WorkItemInfo]

iter_tags()¶

Iterate over the tags currently set on the work item.

Yields:: Tag name strings; nothing when no tags are set.
Return type:: Iterator[str]

property iteration_path: str | None¶: Value of the System.IterationPath field, or None if absent.

link_build(build, *, comment=None)¶

Link this work item to a build via an ArtifactLink relation.

Parameters:

build (Build) – The Build to link.
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

link_commit(repo, commit_id, *, comment=None)¶

Link this work item to a git commit via an ArtifactLink relation.

Parameters:

repo (Repository) – The Repository the commit belongs to.
commit_id (str) – Commit SHA string.
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

link_pull_request(pr, *, comment=None)¶

Link this work item to a pull request via an ArtifactLink relation.

Parameters:

pr (PullRequest) – The PullRequest to link.
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

list_artifact_links()¶

Return all artifact link relations as a list.

Return type:: list[WorkItemRelation]

list_attachments()¶

Return all attached-file relations as a list.

Return type:: list[WorkItemAttachmentRef]

list_child_ids()¶

Return the IDs of direct child work items without making API calls.

Parses the relation URLs from the already-fetched work item data. Requires the info to have been fetched with expand=WorkItemExpand.RELATIONS (the default for ProjectBoards.get_work_item()).

Returns:: List of numeric child work item IDs.
Return type:: list[int]

list_children()¶

Return all child work items as a list.

Return type:: list[WorkItem]

list_comments()¶

Return all comments on this work item as a list.

Return type:: list[WorkItemComment]

list_linked_work_items(rel_type=None)¶

Return all linked work items as a list.

Parameters:: rel_type (WorkItemRelationType | None)
Return type:: list[WorkItem]

list_relations(rel_type=None)¶

Return all relations on this work item as a list.

Parameters:: rel_type (WorkItemRelationType | None)
Return type:: list[WorkItemRelation]

list_revisions()¶

Return all historical revisions of this work item as a list.

Return type:: list[WorkItemInfo]

list_tags()¶

Return all tags on this work item as a list.

Return type:: list[str]

move(*, iteration_path=None, area_path=None)¶

Move this work item to a different iteration and/or area path.

Parameters:

iteration_path (str | None) – New iteration path (e.g. "MyProject\\Sprint 2"), or None to leave unchanged.
area_path (str | None) – New area path (e.g. "MyProject\\Team A"), or None to leave unchanged.

Return type:

None

property org: Organization¶: Organisation this work item belongs to — zero-cost.

property project: Project¶: Project this work item belongs to — zero-cost.

refresh(expand=None)¶

Discard cached work item info.

The next access to info re-fetches from the API.

Parameters:: expand (WorkItemExpand | None) – Expand mode to use on the next fetch. When None (default), re-uses the expand value from construction or the last explicit refresh call. When provided, updates the stored expand so subsequent bare refresh() calls use it.
Return type:: None

remove_comment(comment_id)¶

Delete a comment from this work item.

Parameters:: comment_id (int) – Numeric ID of the comment to delete. Obtain it from iter_comments().
Return type:: None

remove_link(relation)¶

Remove a specific relation from this work item.

Scans the current info.relations list for a matching entry by rel type and url, then removes it via a JSON Patch remove operation.

Parameters:: relation (WorkItemRelation) – The WorkItemRelation to remove. Must be one of the relations returned by iter_relations().
Raises:: ValueError – If the relation is not found on the work item.
Return type:: None

remove_tag(tag)¶

Remove a tag from the work item.

If the tag is not present the work item is not modified.

Parameters:: tag (str) – Tag name to remove.
Return type:: None

remove_work_item_links(other)¶

Remove all relations between this work item and other.

Iterates over all relations on this work item and removes every entry whose URL refers to other. Snapshots the matching relations before the loop so that the index passed to each remove_link() call is always correct.

Parameters:: other (WorkItem) – The work item whose links to this one should all be removed.
Return type:: None

restore()¶

Restore this work item from the Recycle Bin.

Reverses a delete() call. The item is live again after this returns. refresh() is called automatically so subsequent accesses to info reflect the restored state.

Return type:: None

property state: str | None¶: Value of the System.State field, or None if absent.

sync_tags(desired)¶

Synchronise work item tags to match desired exactly.

Adds missing tags and removes extras so the final set matches desired exactly. Does nothing when the current tags already match.

Parameters:: desired (set[str]) – The exact set of tag names the work item should have after the call.
Return type:: None

property title: str | None¶: Value of the System.Title field, or None if absent.

property type: str | None¶: Value of the System.WorkItemType field, or None if absent.

update(fields, *, multiline_fields_format=None)¶

Update work item fields.

Parameters:

fields (dict[str, Any]) – Mapping of field reference names to new values.
multiline_fields_format (dict[str, TextFormat] | None) – Optional per-field format override ("html" or "markdown").

Return type:

None

update_comment(comment_id, text)¶

Update the text of an existing comment.

Parameters:

comment_id (int) – Numeric ID of the comment to update. Obtain it from iter_comments().
text (str) – New comment body text.

Returns:

The updated WorkItemComment.

Return type:

class pyado.oop.boards.WorkItemType(project, info)¶

Metadata about an ADO work item type.

This class is exported from pyado.oop only — not from pyado directly, where pyado.WorkItemType refers to the raw model alias.

Instances are obtained from ProjectBoards.iter_work_item_types() or ProjectBoards.get_work_item_type().

Parameters:

project (Project)
info (WorkItemTypeInfo)

_project¶: The Project this work item type belongs to.

_info¶: Work item type metadata.

property color: str | None¶: Hex color code for this work item type.

property description: str¶: Work item type description.

property icon: WorkItemTypeIcon | None¶: Icon descriptor for this work item type.

property info: WorkItemTypeInfo¶: Full work item type data as returned by the API.

iter_fields()¶

Iterate over field definitions for this work item type.

Yields:: WorkItemFieldInfo for each field.
Return type:: Iterator[WorkItemFieldInfo]

iter_states()¶

Iterate over state definitions for this work item type.

Yields:: WorkItemStateInfo for each state.
Return type:: Iterator[WorkItemStateInfo]

list_fields()¶

Return all field definitions for this work item type as a list.

Return type:: list[WorkItemFieldInfo]

list_states()¶

Return all state definitions for this work item type as a list.

Return type:: list[WorkItemStateInfo]

property name: str¶: Work item type display name (e.g. "Bug").

property org: Organization¶: Organisation this work item type belongs to — zero-cost.

property project: Project¶: Project this work item type belongs to — zero-cost.

property reference_name: str¶

Fully-qualified reference name.

Example: "Microsoft.VSTS.WorkItemTypes.Bug".

Work Item¶

OOP wrapper for Azure DevOps work item resources.

class pyado.oop.boards.work_item.WorkItem(project, work_item_api_call, info, expand=None)

An Azure DevOps work item resource.

Work items are not cached — each factory call returns a fresh instance with the current API state. Call refresh() to re-fetch the info from the API at any time.

Parameters:

project (Project)
work_item_api_call (ApiCall)
info (WorkItemInfo)
expand (WorkItemExpand | None)

_project: The Project this work item belongs to.

_api_call: Work-item-level API call used by all operations.

_info: The work item data returned from the API at construction time.

add_attachment(filename, content)

Upload a file and attach it to the work item.

Parameters:

filename (str) – Name of the file as it will appear in ADO.
content (bytes) – Raw bytes of the file to upload.

Returns:

WorkItemAttachmentRef with the ID and URL of the uploaded file.

Return type:

WorkItemAttachmentRef

add_comment(text, *, comment_format=TextFormat.HTML)

Add a comment to the work item.

Parameters:

text (str) – Comment body text (HTML or Markdown depending on format).
comment_format (TextFormat) – Format of the comment body — "html" (default) or "markdown".

Returns:

The created WorkItemComment.

Return type:

add_link(other, link_type, *, comment=None)

Link this work item to another with the specified relation type.

Covers all work-item-to-work-item relation types (parent, child, related, successor, predecessor, duplicate, etc.). For artifact links (PRs, builds, commits) use the dedicated helpers instead.

Parameters:

other (WorkItem) – Target WorkItem to link to.
link_type (WorkItemRelationType) – Relation type to create (e.g. WorkItemRelationType.PARENT).
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

add_tag(tag)

Add a tag to the work item.

If the tag is already present the work item is not modified.

Parameters:: tag (str) – Tag name to add.
Return type:: None

property api_call: ApiCall: Work-item-level API call for direct use with pyado.raw functions.

property area_path: str | None: Value of the System.AreaPath field, or None if absent.

property assigned_to: Any: Value of the System.AssignedTo field (identity dict), or None.

create_child(work_item_type, title, extra_fields=None, *, multiline_fields_format=None)

Create a new work item and link it as a child of this one.

Creates a new work item of work_item_type, sets title (and any extra_fields), then adds a parent link from the new item back to self.

Parameters:

work_item_type (str) – Work item type name (e.g. "Task").
title (str) – Title for the new work item.
extra_fields (dict[str, Any] | None) – Additional fields to set on the new work item.
multiline_fields_format (dict[str, TextFormat] | None) – Optional per-field format override forwarded to ProjectBoards.create_work_item().

Returns:

The newly created child WorkItem.

Return type:

WorkItem

delete()

Soft-delete this work item.

The item can be restored from the ADO Recycle Bin within 30 days.

Return type:: None

download_attachment(ref)

Download the raw bytes of an uploaded attachment.

Parameters:: ref (WorkItemAttachmentRef) – The WorkItemAttachmentRef returned by add_attachment() or iter_attachments().
Returns:: Raw file bytes.
Return type:: bytes

get_field(field)

Return the current value of a work item field.

Parameters:: field (str) – Field reference name, e.g. "System.Title".
Returns:: The field value, or None if the field is absent.
Return type:: Any

get_parent()

Return the parent work item, or None if none exists.

Returns:: WorkItem for the parent, or None if this work item has no parent relation.
Return type:: WorkItem | None

get_parent_id()

Return the ID of the parent work item without making API calls.

Parses the relation URLs from the already-fetched work item data. Requires the info to have been fetched with expand=WorkItemExpand.RELATIONS (the default for ProjectBoards.get_work_item()).

Returns:: Numeric parent work item ID, or None if this work item has no parent relation.
Return type:: int | None

property id: int: Numeric work item ID.

property info: WorkItemInfo: Work item data captured at construction time (or last refresh).

iter_artifact_links()

Iterate over artifact link relations (PRs, builds, commits).

Convenience filter around iter_relations() for WorkItemRelationType.ARTIFACT_LINK.

Yields:: WorkItemRelation for each artifact link.
Return type:: Iterator[WorkItemRelation]

iter_attachments()

Iterate over attached-file relations as attachment references.

Yields:: WorkItemAttachmentRef for each attached file.
Return type:: Iterator[WorkItemAttachmentRef]

iter_children()

Iterate over direct child work items.

Convenience wrapper around iter_linked_work_items() filtered to WorkItemRelationType.CHILD. Requires the info to have been fetched with expand=WorkItemExpand.RELATIONS (the default).

Yields:: WorkItem for each child.
Return type:: Iterator[WorkItem]

iter_comments()

Iterate over comments on the work item.

Yields:: WorkItemComment for each comment, in API-returned order.
Return type:: Iterator[WorkItemComment]

iter_linked_work_items(rel_type=None)

Iterate over work items linked to this one.

Parameters:: rel_type (WorkItemRelationType | None) – When provided, only relations of this type are yielded (e.g. WorkItemRelationType.CHILD). When None, all WI-to-WI relation types are returned.
Yields:: WorkItem for each linked work item.
Return type:: Iterator[WorkItem]

iter_relations(rel_type=None)

Iterate over all relations on this work item.

Returns every relation regardless of type — work item links, artifact links (PRs, builds, commits), attached files, and hyperlinks. Filter by rel_type to narrow the result.

Requires the info to have been fetched with expand=WorkItemExpand.RELATIONS (the default for ProjectBoards.get_work_item()).

Parameters:: rel_type (WorkItemRelationType | None) – When provided, only relations of this type are yielded. When None, all relation types are returned.
Yields:: WorkItemRelation for each matching relation.
Return type:: Iterator[WorkItemRelation]

iter_revisions()

Iterate over all historical revisions of this work item, oldest first.

Each revision is a full snapshot of the work item at that point in time. Useful for audit trails and change tracking.

Yields:: WorkItemInfo for each revision, oldest first.
Return type:: Iterator[WorkItemInfo]

iter_tags()

Iterate over the tags currently set on the work item.

Yields:: Tag name strings; nothing when no tags are set.
Return type:: Iterator[str]

property iteration_path: str | None: Value of the System.IterationPath field, or None if absent.

link_build(build, *, comment=None)

Link this work item to a build via an ArtifactLink relation.

Parameters:

build (Build) – The Build to link.
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

link_commit(repo, commit_id, *, comment=None)

Link this work item to a git commit via an ArtifactLink relation.

Parameters:

repo (Repository) – The Repository the commit belongs to.
commit_id (str) – Commit SHA string.
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

link_pull_request(pr, *, comment=None)

Link this work item to a pull request via an ArtifactLink relation.

Parameters:

pr (PullRequest) – The PullRequest to link.
comment (str | None) – Optional comment to attach to the relation.

Return type:

None

list_artifact_links()

Return all artifact link relations as a list.

Return type:: list[WorkItemRelation]

list_attachments()

Return all attached-file relations as a list.

Return type:: list[WorkItemAttachmentRef]

list_child_ids()

Return the IDs of direct child work items without making API calls.

Parses the relation URLs from the already-fetched work item data. Requires the info to have been fetched with expand=WorkItemExpand.RELATIONS (the default for ProjectBoards.get_work_item()).

Returns:: List of numeric child work item IDs.
Return type:: list[int]

list_children()

Return all child work items as a list.

Return type:: list[WorkItem]

list_comments()

Return all comments on this work item as a list.

Return type:: list[WorkItemComment]

list_linked_work_items(rel_type=None)

Return all linked work items as a list.

Parameters:: rel_type (WorkItemRelationType | None)
Return type:: list[WorkItem]

list_relations(rel_type=None)

Return all relations on this work item as a list.

Parameters:: rel_type (WorkItemRelationType | None)
Return type:: list[WorkItemRelation]

list_revisions()

Return all historical revisions of this work item as a list.

Return type:: list[WorkItemInfo]

list_tags()

Return all tags on this work item as a list.

Return type:: list[str]

move(*, iteration_path=None, area_path=None)

Move this work item to a different iteration and/or area path.

Parameters:

iteration_path (str | None) – New iteration path (e.g. "MyProject\\Sprint 2"), or None to leave unchanged.
area_path (str | None) – New area path (e.g. "MyProject\\Team A"), or None to leave unchanged.

Return type:

None

property org: Organization: Organisation this work item belongs to — zero-cost.

property project: Project: Project this work item belongs to — zero-cost.

refresh(expand=None)

Discard cached work item info.

The next access to info re-fetches from the API.

Parameters:: expand (WorkItemExpand | None) – Expand mode to use on the next fetch. When None (default), re-uses the expand value from construction or the last explicit refresh call. When provided, updates the stored expand so subsequent bare refresh() calls use it.
Return type:: None

remove_comment(comment_id)

Delete a comment from this work item.

Parameters:: comment_id (int) – Numeric ID of the comment to delete. Obtain it from iter_comments().
Return type:: None

remove_link(relation)

Remove a specific relation from this work item.

Scans the current info.relations list for a matching entry by rel type and url, then removes it via a JSON Patch remove operation.

Parameters:: relation (WorkItemRelation) – The WorkItemRelation to remove. Must be one of the relations returned by iter_relations().
Raises:: ValueError – If the relation is not found on the work item.
Return type:: None

remove_tag(tag)

Remove a tag from the work item.

If the tag is not present the work item is not modified.

Parameters:: tag (str) – Tag name to remove.
Return type:: None

remove_work_item_links(other)

Remove all relations between this work item and other.

Parameters:: other (WorkItem) – The work item whose links to this one should all be removed.
Return type:: None

restore()

Restore this work item from the Recycle Bin.

Reverses a delete() call. The item is live again after this returns. refresh() is called automatically so subsequent accesses to info reflect the restored state.

Return type:: None

property state: str | None: Value of the System.State field, or None if absent.

sync_tags(desired)

Synchronise work item tags to match desired exactly.

Adds missing tags and removes extras so the final set matches desired exactly. Does nothing when the current tags already match.

Parameters:: desired (set[str]) – The exact set of tag names the work item should have after the call.
Return type:: None

property title: str | None: Value of the System.Title field, or None if absent.

property type: str | None: Value of the System.WorkItemType field, or None if absent.

update(fields, *, multiline_fields_format=None)

Update work item fields.

Parameters:

fields (dict[str, Any]) – Mapping of field reference names to new values.
multiline_fields_format (dict[str, TextFormat] | None) – Optional per-field format override ("html" or "markdown").

Return type:

None

update_comment(comment_id, text)

Update the text of an existing comment.

Parameters:

comment_id (int) – Numeric ID of the comment to update. Obtain it from iter_comments().
text (str) – New comment body text.

Returns:

The updated WorkItemComment.

Return type:

PipelineResourcePermissions

Iteration¶

OOP wrapper for Azure DevOps iteration classification nodes.

class pyado.oop.boards.iteration.Iteration(project, info)¶

An Azure DevOps iteration classification node.

Wraps a single iteration node and exposes its properties and patch operation. Instances are obtained from ProjectBoards.get_iteration_node().

Parameters:

project (Project)
info (ClassificationNode)

_project¶: The Project this iteration belongs to.

_info¶: The ClassificationNode data for this node.

add_to_team(team)¶

Assign this iteration node to a team.

Parameters:: team (Team) – The Team to assign this iteration to.
Raises:: ValueError – If the iteration node has no identifier (UUID).
Return type:: None

property children: list[Iteration]¶

Child iteration nodes embedded in the API response.

Returns an empty list when either no children are present or the response was fetched at depth 0. Call ProjectBoards.get_iteration_node() with a higher depth to populate children.

create_child(name)¶

Create a child iteration node under this node.

Parameters:: name (str) – Name of the new child iteration node.
Returns:: Iteration wrapping the newly created child iteration node.
Return type:: Iteration

delete()¶

Delete this iteration node.

Return type:: None

property finish_date: date | None¶: Iteration finish (end) date, or None if not set.

property id: int¶: Numeric node ID.

property info: ClassificationNode¶: Raw node data captured at construction time.

property name: str¶: Node name (e.g. "Sprint 1").

property org: Organization¶: Organisation this iteration belongs to — zero-cost.

property path: str | None¶: Full path as returned by the API (e.g. "\\\\Proj\\\\Sprint 1").

property project: Project¶: Project this iteration belongs to — zero-cost.

refresh()¶

Discard cached iteration node info.

The next access to info re-fetches from the API.

Return type:: None

property start_date: date | None¶: Iteration start date, or None if not set.

update(*, name=None, start_date=None, finish_date=None)¶

Update the name and/or dates of this iteration node.

Parameters:

name (str | None) – New name for the iteration node, or None to leave unchanged.
start_date (date | None) – New start date, or None to leave unchanged.
finish_date (date | None) – New finish (end) date, or None to leave unchanged.

Return type:

None

Area¶

OOP wrapper for Azure DevOps area classification nodes.

class pyado.oop.boards.area.Area(project, info)¶

An Azure DevOps area classification node.

Wraps a single area node and exposes its properties. Instances are obtained from ProjectBoards.get_area_node().

Parameters:

project (Project)
info (ClassificationNode)

_project¶: The Project this area belongs to.

_info¶: The ClassificationNode data for this node.

property children: list[Area]¶

Child area nodes embedded in the API response.

Returns an empty list when either no children are present or the response was fetched at depth 0. Call ProjectBoards.get_area_node() with a higher depth to populate children.

create_child(name)¶

Create a child area node under this node.

Parameters:: name (str) – Name of the new child area node.
Returns:: Area wrapping the newly created child area node.
Return type:: Area

delete()¶

Delete this area node.

Return type:: None

property id: int¶: Numeric node ID.

property info: ClassificationNode¶: Raw node data captured at construction time.

property name: str¶: Node name (e.g. "Team A").

property org: Organization¶: Organisation this area belongs to — zero-cost.

property path: str | None¶: Full path as returned by the API (e.g. "\\\\Proj\\\\Team A").

property project: Project¶: Project this area belongs to — zero-cost.

refresh()¶

Discard cached area node info.

The next access to info re-fetches from the API.

Return type:: None

update(name)¶

Rename this area node.

Parameters:: name (str) – New name for the area node.
Return type:: None

Work Item Type¶

OOP wrapper for Azure DevOps work item type metadata resources.

class pyado.oop.boards.work_item_type.WorkItemType(project, info)¶

Metadata about an ADO work item type.

This class is exported from pyado.oop only — not from pyado directly, where pyado.WorkItemType refers to the raw model alias.

Instances are obtained from ProjectBoards.iter_work_item_types() or ProjectBoards.get_work_item_type().

Parameters:

project (Project)
info (WorkItemTypeInfo)

_project¶: The Project this work item type belongs to.

_info¶: Work item type metadata.

property color: str | None¶: Hex color code for this work item type.

property description: str¶: Work item type description.

property icon: WorkItemTypeIcon | None¶: Icon descriptor for this work item type.

property info: WorkItemTypeInfo¶: Full work item type data as returned by the API.

iter_fields()¶

Iterate over field definitions for this work item type.

Yields:: WorkItemFieldInfo for each field.
Return type:: Iterator[WorkItemFieldInfo]

iter_states()¶

Iterate over state definitions for this work item type.

Yields:: WorkItemStateInfo for each state.
Return type:: Iterator[WorkItemStateInfo]

list_fields()¶

Return all field definitions for this work item type as a list.

Return type:: list[WorkItemFieldInfo]

list_states()¶

Return all state definitions for this work item type as a list.

Return type:: list[WorkItemStateInfo]

property name: str¶: Work item type display name (e.g. "Bug").

property org: Organization¶: Organisation this work item type belongs to — zero-cost.

property project: Project¶: Project this work item type belongs to — zero-cost.

property reference_name: str¶

Fully-qualified reference name.

Example: "Microsoft.VSTS.WorkItemTypes.Bug".

Pipelines¶

Pipelines section of the Azure DevOps OOP layer.

Exposes ProjectPipelines — the project.pipelines section object — and PipelineLibrary — the project.pipelines.library section object — plus re-exports of all resource classes in this sub-package.

class pyado.oop.pipelines.Agent(pool, info)¶

An agent within an agent pool.

ADO concept: an agent is a compute instance registered to an agent pool. It runs pipeline jobs dispatched by the pool scheduler. Agents are exposed at distributedtask/pools/{poolId}/agents/{agentId}.

Why it exists: wraps AgentInfo and holds a back-reference to the owning AgentPool for upward navigation.

Instances are obtained from AgentPool.iter_agents().

Parameters:

pool (AgentPool)
info (AgentInfo)

_pool¶: The AgentPool this agent belongs to.

_info¶: Agent data returned from the API.

property id: int¶: Numeric agent ID.

property info: AgentInfo¶: Raw agent data.

property name: str¶: Agent name.

property pool: AgentPool¶: AgentPool this agent belongs to — zero-cost.

property status: str | None¶: Current agent status string (e.g. "online", "offline").

class pyado.oop.pipelines.AgentPool(org, pool_api_call, info)¶

An Azure DevOps agent pool.

ADO concept: an agent pool is an org-level collection of agents (distributedtask/pools/{poolId}). Both Microsoft-hosted (isHosted=True) and self-hosted pools are represented by this class.

Why it exists: bundles pool info and the pool-level API call so that iter_agents() works without the caller constructing URLs manually.

Instances are obtained from Organization.iter_agent_pools() or Organization.get_agent_pool().

Parameters:

org (Organization)
pool_api_call (ApiCall)
info (AgentPoolInfo)

_org¶: The Organisation this pool belongs to.

_pool_api_call¶: Pool-level ADO API call.

_info¶: Cached pool data.

property id: int¶: Numeric pool ID.

property info: AgentPoolInfo¶: Pool data captured at construction time.

property is_hosted: bool¶: True for Microsoft-hosted pools, False for self-hosted.

iter_agents()¶

Iterate over all agents registered in this pool.

Yields:: Agent for each agent in the pool.
Return type:: Iterator[Agent]

list_agents()¶

Return all agents in this pool as a list.

Return type:: list[Agent]

property name: str¶: Pool name (e.g. "Default", "Azure Pipelines").

property org: Organization¶: Organisation this pool belongs to — zero-cost.

refresh()¶

Discard cached pool info.

The next access to info re-fetches from the API.

Return type:: None

class pyado.oop.pipelines.AgentQueue(project, info)¶

A project-scoped agent queue.

ADO concept: an agent queue is the project-facing view of an agent pool (distributedtask/queues/{queueId}). Pipelines reference queues (not pools directly) via the pool key in YAML or the classic pipeline GUI. Each queue is associated with exactly one pool.

Why it exists: wraps AgentQueueInfo and holds a back-reference to the owning Project.

Instances are obtained from ProjectPipelines.iter_agent_queues() or ProjectPipelines.get_agent_queue().

Parameters:

project (Project)
info (AgentQueueInfo)

_project¶: The Project this queue belongs to.

_info¶: Queue data returned from the API.

property id: int¶: Numeric queue ID.

property info: AgentQueueInfo¶: Raw queue data.

property name: str¶: Queue name (e.g. "Default").

property org: Organization¶: Organisation this queue belongs to — zero-cost.

property pool_id: int | None¶: ID of the agent pool backing this queue, or None if not available.

property project: Project¶: Project this queue belongs to — zero-cost.

class pyado.oop.pipelines.Build(project, build_api_call, info, service)¶

An Azure DevOps build resource.

ADO concept: a build (also called a pipeline run) is a single execution of a pipeline definition. It is exposed by two separate ADO APIs:

Build API — build/builds/{buildId} (docs: build/Builds). Older, richer surface: artifacts, logs, tags, work-item associations, timeline, cancel, queue.
Pipelines v2 API — pipelines/{id}/runs/{runId} (docs: pipelines/Runs). Newer, cleaner surface: finalYaml, templateParameters. The numeric run id is identical to the build id.

Build uses the Build API surface. When you need the Pipelines v2 view of the same run, use pipeline_run.

Why it exists: the raw build/builds endpoint returns a BuildDetails dict of scalars. Build adds: lazy-loaded caching (one HTTP call per refresh), It also carries the back-reference to project and pipeline so navigation is always zero-cost.

Unlike projects and pipelines, builds are not cached — each factory call returns a fresh instance with the current API state.

Wraps a single ADO build and exposes its operations as instance methods. Instances are obtained from ProjectPipelines.get_build(), ProjectPipelines.iter_builds(), or ProjectPipelines.start_build().

Unlike projects and pipelines, builds are not cached — each factory call returns a fresh instance with the current API state.

Parameters:

project (Project)
build_api_call (ApiCall)
info (BuildDetails)
service (AzureDevOpsService)

_project¶: The Project this build belongs to.

_service¶: The owning AzureDevOpsService (for cache access).

_api_call¶: Build-level API call used by all operations.

_info¶: The build data returned from the API at construction time.

add_tag(tag)¶

Add a tag to the build.

Parameters:: tag (str) – Tag name to add.
Return type:: None

property api_call: ApiCall¶: Build-level API call for direct use with pyado.raw functions.

cancel()¶

Request cancellation of this running build.

Updates the wrapper’s cached info to reflect the cancelling state. Read info after the call to inspect the cancelling state without a separate refresh() call.

Returns:: self with status "cancelling"; transitions to "completed" once the agent acknowledges.
Return type:: Build

cancel_run()¶

Cancel this build via the Pipelines v2 API.

Delegates to cancel_pipeline_run(), which uses the Build API to request cancellation and then re-fetches the run via the Pipelines API. Use cancel() instead when you only need a BuildDetails response.

Returns:: PipelineRunInfo reflecting the cancelling/canceled state.
Return type:: PipelineRunInfo

download_artifact(artifact)¶

Download the bytes of a build artifact.

Parameters:: artifact (BuildArtifact) – A BuildArtifact obtained from iter_artifacts().
Returns:: Raw artifact bytes, or None if no download URL is available.
Return type:: bytes | None

find_task(predicate)¶

Return the first timeline record for which predicate returns True.

Fetches all timeline records in one API call, then returns the first record for which predicate returns True, or None if no record matches.

Parameters:: predicate (Callable[[BuildRecordInfo], bool]) – A callable that accepts a BuildRecordInfo and returns True when it is the desired record.
Returns:: The first matching BuildRecordInfo, or None if no record satisfies predicate.
Return type:: BuildRecordInfo | None

property finish_time: datetime | None¶: UTC datetime when the build finished, or None if not yet complete.

get_all_log_text(*, separator='\n')¶

Fetch and concatenate the text of every build log.

Makes one API call to list all log IDs, then one call per log to fetch the text. Logs are joined with separator.

Parameters:: separator (str) – String inserted between consecutive log texts (default: "\n").
Returns:: All log content as a single string.
Return type:: str

get_log_text(log_id)¶

Fetch the plain-text content of a build log.

Parameters:: log_id (int) – Numeric log ID from a BuildLogInfo record. Obtain it via BuildTask.log, BuildJob.log, or BuildStage.log.
Returns:: Log content as a decoded UTF-8 string.
Return type:: str

property id: int¶: Numeric build ID.

property info: BuildDetails¶: Build data captured at construction time (or last refresh).

iter_approvals(state=None)¶

Iterate over environment approvals for this build.

Scoped to this build’s run ID, so only approvals that belong to this specific run are returned.

Parameters:: state (PipelineApprovalStatus | None) – Optional status filter (e.g. PipelineApprovalStatus.PENDING). When None, approvals in all states are returned.
Yields:: PipelineApproval for each matching approval on this build.
Return type:: Iterator[PipelineApproval]

iter_artifacts()¶

Iterate over artifacts published by the build.

Yields:: BuildArtifact for each artifact associated with the build.
Return type:: Iterator[BuildArtifact]

iter_logs()¶

Iterate over all log entries for this build.

Yields:: BuildLogInfo for each log container associated with the build.
Return type:: Iterator[BuildLogInfo]

iter_tags()¶

Iterate over the tags set on the build.

Yields:: Tag name strings.
Return type:: Iterator[str]

iter_timeline_records()¶

Iterate over the timeline records (stages, jobs, tasks) of the build.

Yields:: BuildRecordInfo for each timeline entry.
Return type:: Iterator[BuildRecordInfo]

iter_work_item_ids()¶

Iterate over work item IDs associated with the build.

Yields:: Integer work item IDs linked to this build.
Return type:: Iterator[int]

iter_work_item_ids_between(older_build, *, top=None)¶

Iterate over work item IDs in the range (older_build, this build].

Returns work items associated with any build between older_build (exclusive) and this build (inclusive). Useful for generating a changelog between two consecutive pipeline runs.

Parameters:

older_build (Build) – The earlier build that marks the exclusive lower bound of the range.
top (int | None) – Optional cap on the number of work items returned.

Yields:

Integer work item IDs in the range.

Return type:

Iterator[int]

iter_work_items()¶

Iterate over work items associated with the build.

Convenience wrapper that resolves the linked IDs via iter_work_item_ids() and then fetches the work item details in a single batch call.

Yields:: WorkItem for each linked work item.
Return type:: Iterator[WorkItem]

iter_work_items_between(older_build, *, top=None)¶

Iterate over work items in the range (older_build, this build].

Fetches the work item IDs via iter_work_items_between_builds(), then resolves them in a single batch call.

Parameters:

older_build (Build) – The earlier build that marks the exclusive lower bound of the range.
top (int | None) – Optional cap on the number of work items returned.

Yields:

WorkItem for each work item in the build range.

Return type:

Iterator[WorkItem]

list_approvals(state=None)¶

Return environment approvals for this build as a list.

Parameters:: state (PipelineApprovalStatus | None)
Return type:: list[PipelineApproval]

list_artifacts()¶

Return all artifacts for this build as a list.

Return type:: list[BuildArtifact]

list_logs()¶

Return all log entries for this build as a list.

Return type:: list[BuildLogInfo]

list_tags()¶

Return all tags for this build as a list.

Return type:: list[str]

list_timeline_records()¶

Return all timeline records for this build as a list.

Return type:: list[BuildRecordInfo]

list_work_item_ids()¶

Return all work item IDs for this build as a list.

Return type:: list[int]

list_work_item_ids_between(older_build, *, top=None)¶

Return all work item IDs between two builds as a list.

Parameters:

older_build (Build)
top (int | None)

Return type:

list[int]

list_work_items()¶

Return all work items for this build as a list.

Return type:: list[WorkItem]

list_work_items_between(older_build, *, top=None)¶

Return all work items between two builds as a list.

Parameters:

older_build (Build)
top (int | None)

Return type:

list[WorkItem]

property number: str¶: Build number string (e.g. "20240101.1").

property org: Organization¶: Organisation this build belongs to — zero-cost.

property pipeline: Pipeline¶

Pipeline definition that produced this build — zero-cost.

The Pipeline object is looked up from (or inserted into) the service cache using the definition id and name embedded in the build info. No API call is made unless Pipeline.info is accessed.

property pipeline_run: PipelineRun¶

The Pipelines v2 view of this build run.

Fetches the run via the Pipelines v2 API and returns a PipelineRun bound to this build’s owning pipeline.

Returns:: PipelineRun for this build.

property project: Project¶: Project this build belongs to — zero-cost.

property queue_time: datetime | None¶: UTC datetime when the build was queued, or None if not available.

refresh(expand=None)¶

Discard cached build info.

The next access to info re-fetches from the API.

Parameters:: expand (BuildExpand | None) – Optional $expand value to use on the next fetch. When provided, replaces any previously stored expand value; when None, previously stored expand is preserved.
Return type:: None

remove_tag(tag)¶

Remove a tag from the build.

Parameters:: tag (str) – Tag name to remove.
Return type:: None

property requested_by: str¶: Display name of the identity that queued the build.

property requested_for: str | None¶

Display name of the identity the build was requested for, or None.

For CI builds this is usually the commit author; for manually-queued builds it may differ from requested_by.

property result: BuildResult | None¶

Build outcome once completed (e.g. "succeeded", "failed").

None while the build is still running.

retry()¶

Queue a new build run using the same definition and source branch.

Returns:: A new Build object for the queued build run.
Return type:: Build

property source_branch: str¶: Source branch used for this build (e.g. "refs/heads/main").

property source_version: str¶: Commit SHA that triggered this build.

property start_time: datetime | None¶: UTC datetime when the build started, or None if not yet started.

property status: BuildStatus¶: Current build status.

update(status)¶

Update the status of this build.

Parameters:: status (BuildStatus) – New build status to set (e.g. BuildStatus.CANCELLING).
Return type:: None

class pyado.oop.pipelines.Environment(project, env_api_call, info)¶

An Azure DevOps pipeline environment.

ADO concept: a pipeline environment is a named deployment target (e.g. "production", "staging") managed at distributedtask/environments/{id}. Environments support approval gates, deployment history, and resource targets (Kubernetes, virtual machines).

Why it exists: bundles the environment ID and info together so callers can inspect properties and iterate deployment history without managing raw API calls.

Instances are obtained from ProjectPipelines.iter_environments() or ProjectPipelines.get_environment().

Parameters:

project (Project)
env_api_call (ApiCall)
info (EnvironmentInfo)

_project¶: The Project this environment belongs to.

_api_call¶: Environment-level ADO API call.

_info¶: Cached environment data.

property api_call: ApiCall¶: Environment-level API call for direct use with pyado.raw functions.

property description: str¶: Environment description.

property id: int¶: Numeric environment ID.

property info: EnvironmentInfo¶: Environment data captured at construction time.

iter_checks()¶

Iterate over all check configurations for this environment.

Yields:: EnvironmentCheckInfo for each check configuration.
Return type:: Iterator[EnvironmentCheckInfo]

iter_deployments(*, top=None)¶

Iterate over deployment records for this environment.

Parameters:: top (int | None) – Maximum number of records to return. When None, the API default is used.
Yields:: EnvironmentDeploymentRecord for each deployment.
Return type:: Iterator[EnvironmentDeploymentRecord]

list_checks()¶

Return all check configurations for this environment as a list.

Return type:: list[EnvironmentCheckInfo]

list_deployments(*, top=None)¶

Return deployment records for this environment as a list.

Parameters:: top (int | None)
Return type:: list[EnvironmentDeploymentRecord]

property name: str¶: Environment name (e.g. "production").

property org: Organization¶: Organisation this environment belongs to — zero-cost.

property project: Project¶: Project this environment belongs to — zero-cost.

refresh()¶

Discard cached environment info.

The next access to info re-fetches from the API.

Return type:: None

class pyado.oop.pipelines.Pipeline(project, pipeline_id, name, info=None)¶

An Azure DevOps pipeline resource (Pipelines v2).

ADO concept: a pipeline is the definition of a CI/CD process, stored as a YAML file in a repository (or as a classic GUI definition). It is exposed by two APIs:

Pipelines v2 API — pipelines/{id} (docs: pipelines/Pipelines). This class uses this surface.
Build API — build/definitions/{id} — older surface with more fields (triggers, retention, variables), represented as PipelineDefinitionInfo.

The numeric id is the same in both APIs.

Why it exists: Pipeline is the factory for PipelineRun objects and owns resource-permission management (authorize_resource()). Caching through the service guarantees that build.pipeline is other_build.pipeline when both were produced by the same definition — even if the two Build objects were obtained from different call paths. The id and name are always known (embedded in BuildDetails), so a Pipeline wrapper is available with zero API calls as soon as a Build is fetched; the full info is loaded lazily on first access.

Wraps a single ADO pipeline and exposes its operations as instance methods. Instances are obtained from ProjectPipelines.get_pipeline(), ProjectPipelines.iter_pipelines(), or as a zero-cost back-reference via Build.pipeline.

The id and name are always known at construction. The full info payload is loaded lazily and cached; call refresh() to discard it so the next access re-fetches from the API.

Parameters:

project (Project)
pipeline_id (int)
name (str)
info (PipelineInfo | None)

_project¶: The Project this pipeline belongs to.

_id¶: Numeric pipeline ID.

_name¶: Pipeline name.

_info¶: Cached pipeline data; None until first lazy fetch.

property api_call: ApiCall¶

Project-level API call for direct use with pyado.raw functions.

ADO pipelines are project-scoped, so the pipeline-level API call is the same as the owning project’s API call.

authorize_resource(resource_type, resource_id, *, authorized=True)¶

Authorize (or de-authorize) a resource for this pipeline.

Note: ADO pipeline permission grants are additive — this call can never remove an authorization that was granted by another pipeline or via the portal. Read the current permissions from ADO before deciding to call this method.

Parameters:

resource_type (PipelineResourceType) – The type of resource to authorize.
resource_id (str) – String ID of the resource.
authorized (bool) – True to grant access (default); False to revoke.

Returns:

PipelineResourcePermissions reflecting the updated state.

Return type:

cancel_run(run_id)¶

Request cancellation of an in-progress pipeline run.

Parameters:: run_id (int) – Numeric ID of the run to cancel (same as the build ID for Pipelines v2 runs).
Returns:: PipelineRunInfo with state "canceling"; transitions to "completed" with result "canceled" once the agent acknowledges.
Return type:: PipelineRunInfo

get_latest_run()¶

Return the most recent pipeline run, or None if none exist.

Returns:: PipelineRun for the newest run, or None.
Return type:: PipelineRun | None

get_run(run_id)¶

Return a wrapper for a single pipeline run.

Parameters:: run_id (int) – Numeric ID of the pipeline run.
Returns:: PipelineRun wrapping the requested run.
Return type:: PipelineRun

property id: int¶: Numeric pipeline ID — always known, no API call.

property info: PipelineInfo¶: Full pipeline data (lazy-fetched on first access if not supplied).

iter_builds(*, status_filter=None, branch_name=None, top=None)¶

Iterate over builds for this pipeline via the Build API.

Provides richer filtering than iter_runs() (status, branch, top). Delegates to iter_builds() with this pipeline’s definition ID pre-filled.

Parameters:

status_filter (BuildStatus | None) – Filter by build status (e.g. BuildStatus.COMPLETED).
branch_name (str | None) – Filter by source branch ref name (e.g. "refs/heads/main").
top (int | None) – Maximum number of builds to return.

Yields:

Build for each matching build.

Return type:

Iterator[Build]

iter_runs(*, top=None)¶

Iterate over all runs of the pipeline.

Parameters:: top (int | None) – Maximum number of runs to return. When None the API default is used.
Yields:: PipelineRun for each run, in API-returned order (newest first).
Return type:: Iterator[PipelineRun]

list_builds(*, status_filter=None, branch_name=None, top=None)¶

Return all builds for this pipeline as a list.

Parameters:

status_filter (BuildStatus | None)
branch_name (str | None)
top (int | None)

Return type:

list[Build]

list_runs(*, top=None)¶

Return all runs for this pipeline as a list.

Parameters:: top (int | None)
Return type:: list[PipelineRun]

property name: str¶: Pipeline name — always known, no API call.

property org: Organization¶: Organisation this pipeline belongs to — zero-cost.

property project: Project¶: Project this pipeline belongs to — zero-cost.

refresh()¶

Discard cached pipeline info.

The next access to info re-fetches from the API.

Return type:: None

start_run(*, resources=None, variables=None, template_parameters=None, stages_to_skip=None)¶

Trigger a new run of the pipeline.

Parameters:

resources (dict[str, Any] | None) – Optional pipeline resources override dict.
variables (dict[str, VariableInfo] | None) – Optional pipeline variable overrides dict.
template_parameters (dict[str, str] | None) – Optional template parameter overrides.
stages_to_skip (list[str] | None) – List of stage names to skip during the run.

Returns:

PipelineRun wrapping the newly triggered run.

Return type:

PipelineRun

class pyado.oop.pipelines.PipelineLibrary(project)¶

The library sub-section of a project’s Pipelines section.

Accessed via project.pipelines.library. Exposes variable group and secure file operations that belong to the ADO Pipeline Library.

Parameters:: project (Project)

_project¶: The owning Project.

create_variable_group(name, variables, *, description=None, var_group_type='Vsts', provider_data=None)¶

Create a new variable group in the project.

Parameters:

name (str) – Name for the new variable group.
variables (dict[str, VariableInfo]) – Mapping of variable names to VariableInfo values.
description (str | None) – Optional description for the variable group.
var_group_type (str) – Variable group type (default: "Vsts").
provider_data (Any) – Optional provider-specific configuration object (e.g. key vault config).

Returns:

VariableGroup wrapping the newly created variable group.

Return type:

VariableGroup

get_secure_file(name)¶

Return a secure file by name.

Parameters:: name (str) – Secure file name (case-sensitive).
Returns:: SecureFile wrapping the requested secure file.
Raises:: KeyError – If no secure file with the given name exists.
Return type:: SecureFile

get_variable_group(name)¶

Return a variable group by name.

Parameters:: name (str) – Variable group name (case-sensitive).
Returns:: VariableGroup wrapping the requested variable group.
Raises:: KeyError – If no variable group with the given name exists.
Return type:: VariableGroup

get_variable_group_by_id(variable_group_id)¶

Return a variable group by numeric ID.

Parameters:: variable_group_id (int) – Numeric variable group ID.
Returns:: VariableGroup wrapping the requested variable group.
Return type:: VariableGroup

iter_secure_files()¶

Iterate over all secure files in the project.

Yields:: SecureFile for each secure file in the project.
Return type:: Iterator[SecureFile]

iter_variable_groups()¶

Iterate over all variable groups in the project.

Yields:: VariableGroup for each variable group in the project.
Return type:: Iterator[VariableGroup]

list_secure_files()¶

Return all secure files in the project as a list.

Return type:: list[SecureFile]

list_variable_groups()¶

Return all variable groups in the project as a list.

Return type:: list[VariableGroup]

class pyado.oop.pipelines.PipelineRun(pipeline, info)¶

A single Pipelines v2 run.

ADO concept: a pipeline run is a single execution of a pipeline, as exposed by the newer Pipelines v2 API at pipelines/{pipelineId}/runs/{runId} (docs: pipelines/Runs). The numeric runId is identical to the Build API’s buildId — the same execution is accessible via both surfaces.

Why it exists as a separate class from Build: the Pipelines v2 API exposes data that the Build API does not: finalYaml (the compiled YAML after template expansion), templateParameters, and a cleaner state/result enum pair (PipelineRunState + PipelineRunResult). It is also the natural companion to Pipeline — obtaining a run through pipeline.iter_runs() returns a PipelineRun, while navigating via project.pipelines.iter_builds() returns a Build.

ADO constraint: the Pipelines v2 API has no cancel endpoint. Cancellation is routed through the Build API (PATCH build/builds/{id} with {status: "cancelling"}); pyado does this automatically in cancel().

Wraps a PipelineRunInfo and holds a back-reference to the owning Pipeline. Instances are obtained from Pipeline.iter_runs(), Pipeline.get_run(), or Pipeline.start_run().

Parameters:

pipeline (Pipeline)
info (PipelineRunInfo)

_pipeline¶: The Pipeline this run belongs to.

_info¶: Run data returned from the API at construction time.

property api_call: ApiCall¶

Project-level API call for direct use with pyado.raw pipeline functions.

ADO’s Pipelines REST API has no run-scoped base URL — every run endpoint is project-scoped ({org}/{project}/_apis/pipelines/…), with pipelineId and runId passed as additional path segments by the raw functions themselves. Returning the project-level call is therefore correct and consistent with the raw layer.

cancel()¶

Request cancellation of this in-progress run.

Updates the wrapper’s cached info to reflect the cancelling state.

Returns:: self with state "canceling"; transitions to "completed" with result "canceled" once the agent acknowledges.
Return type:: PipelineRun

property id: int¶: Numeric run ID.

property info: PipelineRunInfo¶: Run data captured at construction time.

iter_approvals(state=None)¶

Iterate over environment approvals for this run.

Scoped to this run’s ID, so only approvals that belong to this specific run are returned.

Parameters:: state (PipelineApprovalStatus | None) – Optional status filter (e.g. PipelineApprovalStatus.PENDING). When None, approvals in all states are returned.
Yields:: PipelineApproval for each matching approval on this run.
Return type:: Iterator[PipelineApproval]

list_approvals(state=None)¶

Return environment approvals for this run as a list.

Parameters:: state (PipelineApprovalStatus | None)
Return type:: list[PipelineApproval]

property org: Organization¶: Organisation this run belongs to — zero-cost.

property pipeline: Pipeline¶: Pipeline this run belongs to — zero-cost.

property project: Project¶: Project this run belongs to — zero-cost.

refresh()¶

Discard cached run info.

The next access to info re-fetches from the API.

Return type:: None

property result: PipelineRunResult | None¶

Run result once completed (e.g. "succeeded", "failed").

None while the run is still in progress.

property status: PipelineRunState¶: Current run state (e.g. "inProgress", "completed").

class pyado.oop.pipelines.ProjectPipelines(project)¶

The Pipelines section of a project.

Accessed via project.pipelines. Exposes all pipeline, build, approval, environment, agent queue, and library operations that belong to the ADO Pipelines section.

Parameters:: project (Project)

_project¶: The owning Project.

approve(approval_id, *, comment='')¶

Approve a pending pipeline environment approval.

Parameters:

approval_id (str) – UUID string of the approval to approve.
comment (str) – Optional comment to attach to the approval.

Return type:

None

create_service_endpoint(request)¶

Create a new service connection in the project.

Parameters:: request (ServiceEndpointCreateRequest) – Create request specifying the name, type, URL, authorization, and project references.
Returns:: ServiceEndpoint wrapping the newly created connection.
Return type:: ServiceEndpoint

create_task_group(request)¶

Create a new task group in the project.

Parameters:: request (TaskGroupCreateRequest) – Create request specifying the name and tasks.
Returns:: TaskGroup wrapping the newly created task group.
Return type:: TaskGroup

create_variable_group(name, variables, *, description=None, var_group_type='Vsts', provider_data=None)¶

Create a new variable group in the project.

Delegates to PipelineLibrary.create_variable_group().

Parameters:

name (str) – Name for the new variable group.
variables (dict[str, VariableInfo]) – Mapping of variable names to VariableInfo values.
description (str | None) – Optional description for the variable group.
var_group_type (str) – Variable group type (default: "Vsts").
provider_data (Any) – Optional provider data (e.g. key vault config).

Returns:

VariableGroup wrapping the newly created variable group.

Return type:

VariableGroup

get_agent_queue(name)¶

Return an agent queue by name.

Parameters:: name (str) – Agent queue name (case-sensitive).
Returns:: AgentQueue wrapping the requested queue.
Raises:: KeyError – If no agent queue with the given name exists.
Return type:: AgentQueue

get_agent_queue_by_id(queue_id)¶

Return an agent queue by numeric ID.

Parameters:: queue_id (int) – Numeric agent queue ID.
Returns:: AgentQueue wrapping the requested queue.
Return type:: AgentQueue

get_build(build_id)¶

Return a build by numeric ID.

Parameters:: build_id (int) – Numeric build ID.
Returns:: Build wrapping the requested build.
Return type:: Build

get_build_details(build_id, *, expand=None)¶

Return raw BuildDetails for a build ID.

Parameters:

build_id (int) – Numeric build ID.
expand (BuildExpand | None) – Optional expand mode.

Returns:

BuildDetails from the API.

Return type:

PipelineResourcePermissions

get_build_with_expand(build_id, expand)¶

Return a build with a specific expand mode.

Parameters:

build_id (int) – Numeric build ID.
expand (BuildExpand) – $expand value to include extra data in the response.

Returns:

Build wrapping the requested build with expanded info.

Return type:

Build

get_environment(name)¶

Return a pipeline environment by name.

Parameters:: name (str) – Environment name (case-sensitive).
Returns:: Environment wrapping the requested environment.
Raises:: KeyError – If no environment with the given name exists.
Return type:: Environment

get_environment_by_id(environment_id)¶

Return a pipeline environment by numeric ID.

Parameters:: environment_id (int) – Numeric environment ID.
Returns:: Environment wrapping the requested environment.
Return type:: Environment

get_latest_build(pipeline_id, *, branch_name=None)¶

Return the most recent build for a pipeline, or None.

Parameters:

pipeline_id (int) – The ID of the pipeline to look up builds for.
branch_name (str | None) – Optional branch filter.

Returns:

The most recent Build, or None if no builds exist.

Return type:

Build | None

get_pipeline(name)¶

Return a pipeline by name.

Parameters:: name (str) – Pipeline name (case-sensitive).
Returns:: Pipeline wrapping the requested pipeline.
Raises:: KeyError – If no pipeline with the given name exists.
Return type:: Pipeline

get_pipeline_by_id(pipeline_id)¶

Return a pipeline by numeric ID.

The result is stored in (or retrieved from) the service cache so that build.pipeline and project.pipelines.get_pipeline_by_id return the same object for the same pipeline.

Parameters:: pipeline_id (int) – Numeric pipeline ID.
Returns:: Pipeline wrapping the requested pipeline.
Return type:: Pipeline

get_run(pipeline_id, run_id)¶

Return a specific pipeline run by ID.

Parameters:

pipeline_id (int) – The ID of the pipeline the run belongs to.
run_id (int) – Numeric run ID.

Returns:

PipelineRun wrapping the requested run.

Return type:

PipelineRun

get_service_endpoint(name)¶

Return a service connection by name.

Parameters:: name (str) – Service connection name (case-sensitive).
Returns:: ServiceEndpoint wrapping the requested connection.
Raises:: KeyError – If no service connection with the given name exists.
Return type:: ServiceEndpoint

get_service_endpoint_by_id(endpoint_id)¶

Return a service connection by UUID.

Parameters:: endpoint_id (UUID) – UUID of the service connection.
Returns:: ServiceEndpoint wrapping the requested connection.
Return type:: ServiceEndpoint

get_task_group(name)¶

Return a task group by name.

Parameters:: name (str) – Task group name (case-sensitive).
Returns:: TaskGroup wrapping the requested task group.
Raises:: KeyError – If no task group with the given name exists.
Return type:: TaskGroup

get_task_group_by_id(task_group_id)¶

Return a task group by UUID.

Parameters:: task_group_id (UUID) – UUID of the task group.
Returns:: TaskGroup wrapping the requested task group.
Return type:: TaskGroup

get_variable_group(name)¶

Return a variable group by name.

Delegates to PipelineLibrary.get_variable_group().

Parameters:: name (str) – Variable group name (case-sensitive).
Returns:: VariableGroup wrapping the requested variable group.
Return type:: VariableGroup

get_variable_group_by_id(variable_group_id)¶

Return a variable group by numeric ID.

Delegates to PipelineLibrary.get_variable_group_by_id().

Parameters:: variable_group_id (int) – Numeric variable group ID.
Returns:: VariableGroup wrapping the requested variable group.
Return type:: VariableGroup

iter_agent_queues()¶

Iterate over all agent queues in the project.

Yields:: AgentQueue for each agent queue in the project.
Return type:: Iterator[AgentQueue]

iter_approvals(state=None)¶

Iterate over pipeline environment approvals in the project.

Parameters:: state (PipelineApprovalStatus | None) – Optional status filter. When None, approvals in all states are returned.
Yields:: PipelineApproval for each matching approval.
Return type:: Iterator[PipelineApproval]

iter_builds(*, definition_id=None, status_filter=None, branch_name=None, top=None)¶

Iterate over builds in the project.

Parameters:

definition_id (int | None) – Filter by pipeline definition ID.
status_filter (BuildStatus | None) – Filter by build status (e.g. BuildStatus.COMPLETED).
branch_name (str | None) – Filter by source branch ref name (e.g. "refs/heads/main").
top (int | None) – Maximum number of builds to return.

Yields:

Build for each matching build.

Return type:

Iterator[Build]

iter_environments()¶

Iterate over all pipeline environments in the project.

Yields:: Environment for each environment in the project.
Return type:: Iterator[Environment]

iter_pipeline_definitions(*, name_filter=None)¶

Iterate over pipeline definitions (Build API) in the project.

Returns richer definition metadata than iter_pipelines() (which uses the Pipelines v2 API). Use this when you need fields such as the YAML file path or the queue/pool reference.

Parameters:: name_filter (str | None) – Optional name substring filter passed to the API.
Yields:: PipelineDefinitionInfo for each matching definition.
Return type:: Iterator[PipelineDefinitionInfo]

iter_pipelines()¶

Iterate over all pipeline definitions in the project.

Yields:: Pipeline for each pipeline definition.
Return type:: Iterator[Pipeline]

iter_runs(pipeline_id, *, top=None)¶

Iterate over all runs of a specific pipeline.

Parameters:

pipeline_id (int) – The ID of the pipeline to iterate runs for.
top (int | None) – Maximum number of runs to return.

Yields:

PipelineRun for each run, in API-returned order (newest first).

Return type:

Iterator[PipelineRun]

iter_service_endpoints()¶

Iterate over all service connections in the project.

Yields:: ServiceEndpoint for each service connection.
Return type:: Iterator[ServiceEndpoint]

iter_task_groups()¶

Iterate over all task groups in the project.

Yields:: TaskGroup for each task group in the project.
Return type:: Iterator[TaskGroup]

iter_variable_groups()¶

Iterate over all variable groups in the project.

Delegates to PipelineLibrary.iter_variable_groups().

Yields:: VariableGroup for each variable group in the project.
Return type:: Iterator[VariableGroup]

property library: PipelineLibrary¶: The Pipeline Library sub-section (variable groups, secure files).

list_agent_queues()¶

Return all agent queues in the project as a list.

Return type:: list[AgentQueue]

list_approvals(state=None)¶

Return pipeline environment approvals as a list.

Parameters:: state (PipelineApprovalStatus | None)
Return type:: list[PipelineApproval]

list_builds(*, definition_id=None, status_filter=None, branch_name=None, top=None)¶

Return builds in the project as a list.

Parameters:

definition_id (int | None)
status_filter (BuildStatus | None)
branch_name (str | None)
top (int | None)

Return type:

list[Build]

list_environments()¶

Return all pipeline environments in the project as a list.

Return type:: list[Environment]

list_pipeline_definitions(*, name_filter=None)¶

Return pipeline definitions in the project as a list.

Parameters:: name_filter (str | None)
Return type:: list[PipelineDefinitionInfo]

list_pipelines()¶

Return all pipeline definitions in the project as a list.

Return type:: list[Pipeline]

list_runs(pipeline_id, *, top=None)¶

Return all runs of a specific pipeline as a list.

Parameters:

pipeline_id (int) – The ID of the pipeline to list runs for.
top (int | None) – Maximum number of runs to return.

Returns:

List of PipelineRun, in API-returned order (newest first).

Return type:

list[PipelineRun]

list_service_endpoints()¶

Return all service connections in the project as a list.

Return type:: list[ServiceEndpoint]

list_task_groups()¶

Return all task groups in the project as a list.

Return type:: list[TaskGroup]

list_variable_groups()¶

Return all variable groups in the project as a list.

Returns:: List of VariableGroup objects.
Return type:: list[VariableGroup]

reject(approval_id, *, comment='')¶

Reject a pending pipeline environment approval.

Parameters:

approval_id (str) – UUID string of the approval to reject.
comment (str) – Optional comment to attach to the rejection.

Return type:

None

start_build(pipeline_id, *, source_branch=None, source_version=None, parameters=None)¶

Queue a new build run for a pipeline.

Parameters:

pipeline_id (int) – The ID of the pipeline to run.
source_branch (str | None) – Source branch to build (e.g. "refs/heads/main"). Uses the definition default when omitted.
source_version (str | None) – Commit SHA to build. Uses the branch HEAD when omitted.
parameters (dict[str, str] | None) – Optional key/value pairs passed to the pipeline as template parameters.

Returns:

Build for the newly queued build run.

Return type:

Build

class pyado.oop.pipelines.SecureFile(project, secure_file_api_call, info)¶

An Azure DevOps secure file resource.

ADO concept: a secure file is an encrypted file stored in the pipeline library (distributedtask/securefiles/{id}). Common uses include signing certificates, provisioning profiles, and SSH keys. Secure files can be referenced in pipelines via the DownloadSecureFile task.

Why it exists: bundles the secure file ID and info together so callers can inspect properties and delete the file without managing raw API calls.

Instances are obtained from PipelineLibrary.iter_secure_files() or PipelineLibrary.get_secure_file().

Parameters:

project (Project)
secure_file_api_call (ApiCall)
info (SecureFileInfo)

_project¶: The Project this secure file belongs to.

_api_call¶: Secure-file-level ADO API call.

_info¶: Cached secure file data.

property api_call: ApiCall¶: Secure-file-level API call for direct use with pyado.raw functions.

delete()¶

Delete this secure file from the project.

The deletion is permanent and cannot be undone via the API.

Return type:: None

property id: UUID¶: UUID of the secure file.

property info: SecureFileInfo¶: Secure file data captured at construction time.

property name: str¶: Secure file name.

property org: Organization¶: Organisation this secure file belongs to — zero-cost.

property project: Project¶: Project this secure file belongs to — zero-cost.

refresh()¶

Discard cached secure file info.

The next access to info re-fetches from the API.

Return type:: None

class pyado.oop.pipelines.ServiceEndpoint(project, info)¶

An ADO service connection.

Wraps a single ADO service endpoint (service connection). Instances are obtained from ProjectPipelines.iter_service_endpoints().

Parameters:

project (Project)
info (ServiceEndpointInfo)

_project¶: The Project this service endpoint belongs to.

_id¶: Service endpoint UUID (always known).

_info¶: Cached service endpoint data; None after refresh().

property authorization_scheme: str | None¶: Authorization scheme (e.g. "Token", "UsernamePassword").

delete()¶

Delete this service endpoint from the current project.

Removes the endpoint from project. The deletion is permanent and cannot be undone via the API.

Return type:: None

property id: UUID¶: Service endpoint UUID — always known, no API call.

property info: ServiceEndpointInfo¶

Full service endpoint data as returned by the API.

Fetched lazily by re-querying the endpoint list if refresh() was called since the last access.

Raises:: KeyError – If no service endpoint with this ID is found in the project.

property is_ready: bool¶: Whether the service endpoint is ready for use.

property is_shared: bool¶: Whether the service endpoint is shared across projects.

property name: str¶: Service endpoint name.

property org: Organization¶: Organisation this service endpoint belongs to — zero-cost.

property project: Project¶: Project this service endpoint belongs to — zero-cost.

refresh()¶

Discard cached service endpoint info.

The next access to info re-fetches from the endpoint list.

Return type:: None

share(project_references)¶

Share this service endpoint with additional projects.

Parameters:: project_references (list[ServiceEndpointProjectReference]) – Project references describing each project to share the endpoint with and the name to use in each project.
Return type:: None

property type: str¶: Service endpoint type (e.g. "github", "azurerm").

update(request)¶

Update this service endpoint.

Sends a PUT to the organisation-scoped endpoint and refreshes the cached info with the API response.

Parameters:: request (ServiceEndpointUpdateRequest) – Update request. The id field must match this endpoint’s id.
Return type:: None

property url: str¶: Service endpoint target URL.

class pyado.oop.pipelines.TaskGroup(project, info)¶

An ADO task group.

Wraps a single ADO task group in a project. Instances are obtained from ProjectPipelines.iter_task_groups().

Parameters:

project (Project)
info (TaskGroupInfo)

_project¶: The Project this task group belongs to.

_id¶: Task group UUID (always known).

_info¶: Cached task group data; None after refresh().

property category: str | None¶: Task group category.

delete()¶

Delete this task group from the project.

Return type:: None

property description: str | None¶: Task group description.

property id: UUID¶: Task group UUID — always known, no API call.

property info: TaskGroupInfo¶

Full task group data as returned by the API.

Fetched lazily by re-querying the API if refresh() was called since the last access.

property name: str¶: Task group name.

property org: Organization¶: Organisation this task group belongs to — zero-cost.

property project: Project¶: Project this task group belongs to — zero-cost.

refresh()¶

Discard cached task group info.

The next access to info re-fetches from the API.

Return type:: None

update(request)¶

Update this task group.

Parameters:: request (TaskGroupUpdateRequest) – Update request. The id field must match this task group’s id.
Return type:: None

class pyado.oop.pipelines.VariableGroup(project, variable_group_api_call, info)¶

An Azure DevOps variable group resource.

ADO concept: a variable group is a named, project-scoped store of key-value pairs managed at distributedtask/variablegroups/{variableGroupId} (docs: distributedtask/variablegroups). Each entry is a VariableInfo with a string value and an optional isSecret flag. When isSecret is True ADO stores the value encrypted and returns null on subsequent GETs — the value is write-only. A variable group may be backed by Azure Key Vault (type='AzureKeyVault') instead of the native ADO store (type='Vsts'); in that case providerData carries the Key Vault configuration. Pipeline permission grants for variable groups are additive — the API can never remove a grant made by another pipeline or via the portal.

Why it exists: the ADO variable-group PUT endpoint has two quirks that VariableGroup hides from callers:

Full-replace semantics — every PUT must carry the complete set of variables, not just the changed ones. set_variable() and delete_variable() fetch the current state, apply the targeted change, then write back the full set.
Mandatory project references — the PUT body must contain at least one entry in variableGroupProjectReferences even though the GET response often omits the field (returns null). _project_refs() synthesises a minimal entry from the owning Project when the GET response is silent.

Wraps a single ADO variable group and exposes its operations as instance methods. Instances are obtained from ProjectPipelines.library.iter_variable_groups() or ProjectPipelines.library.get_variable_group().

Variable groups are not cached — each factory call returns a fresh instance.

Parameters:

project (Project)
variable_group_api_call (ApiCall)
info (VariableGroupInfo)

_project¶: The Project this variable group belongs to.

_api_call¶: Variable-group-level API call used by all operations.

_info¶: The variable group data returned from the API at construction time.

property api_call: ApiCall¶: Variable-group-level API call for direct use with pyado.raw functions.

delete()¶

Delete this variable group from the project.

The deletion is permanent and cannot be undone via the API.

Return type:: None

property id: int¶: Numeric variable group ID.

property info: VariableGroupInfo¶: Variable group data captured at construction time.

property name: str¶: Variable group name.

property org: Organization¶: Organisation this variable group belongs to — zero-cost.

property project: Project¶: Project this variable group belongs to — zero-cost.

refresh()¶

Discard cached variable group info.

The next access to info re-fetches from the API.

Return type:: None

set_variable(var_name, value, *, is_secret=False)¶

Set or update a single variable in the group.

Fetches all current variables, merges the update, then writes back.

Parameters:

var_name (str) – Name of the variable to set.
value (str) – New value for the variable.
is_secret (bool) – When True the variable is marked as secret.

Return type:

None

unset_variable(var_name)¶

Remove a variable from the group.

Parameters:: var_name (str) – Name of the variable to remove.
Raises:: KeyError – If the variable does not exist in the group.
Return type:: None

update(variables, *, name=None, description=None, var_group_type=None, provider_data=None)¶

Replace the variable group’s variables (and optionally its metadata).

Parameters:

variables (dict[str, VariableInfo]) – New variable mapping to apply. Replaces the existing set entirely.
name (str | None) – New name for the variable group. Defaults to the current name if not supplied.
description (str | None) – Updated description, or None to leave unchanged.
var_group_type (str | None) – Optional type string (e.g. "Vsts", "AzureKeyVault").
provider_data (Any) – Optional provider-specific configuration object (e.g. key vault settings).

Return type:

None

property variables: dict[str, VariableInfo]¶: Current variable mapping (name → VariableInfo).

Build¶

OOP wrapper for Azure DevOps build resources.

class pyado.oop.pipelines.build.Build(project, build_api_call, info, service)

An Azure DevOps build resource.

ADO concept: a build (also called a pipeline run) is a single execution of a pipeline definition. It is exposed by two separate ADO APIs:

Build API — build/builds/{buildId} (docs: build/Builds). Older, richer surface: artifacts, logs, tags, work-item associations, timeline, cancel, queue.
Pipelines v2 API — pipelines/{id}/runs/{runId} (docs: pipelines/Runs). Newer, cleaner surface: finalYaml, templateParameters. The numeric run id is identical to the build id.

Build uses the Build API surface. When you need the Pipelines v2 view of the same run, use pipeline_run.

Unlike projects and pipelines, builds are not cached — each factory call returns a fresh instance with the current API state.

Parameters:

project (Project)
build_api_call (ApiCall)
info (BuildDetails)
service (AzureDevOpsService)

_project: The Project this build belongs to.

_service: The owning AzureDevOpsService (for cache access).

_api_call: Build-level API call used by all operations.

_info: The build data returned from the API at construction time.

add_tag(tag)

Add a tag to the build.

Parameters:: tag (str) – Tag name to add.
Return type:: None

property api_call: ApiCall: Build-level API call for direct use with pyado.raw functions.

cancel()

Request cancellation of this running build.

Updates the wrapper’s cached info to reflect the cancelling state. Read info after the call to inspect the cancelling state without a separate refresh() call.

Returns:: self with status "cancelling"; transitions to "completed" once the agent acknowledges.
Return type:: Build

cancel_run()

Cancel this build via the Pipelines v2 API.

Returns:: PipelineRunInfo reflecting the cancelling/canceled state.
Return type:: PipelineRunInfo

download_artifact(artifact)

Download the bytes of a build artifact.

Parameters:: artifact (BuildArtifact) – A BuildArtifact obtained from iter_artifacts().
Returns:: Raw artifact bytes, or None if no download URL is available.
Return type:: bytes | None

find_task(predicate)

Return the first timeline record for which predicate returns True.

Fetches all timeline records in one API call, then returns the first record for which predicate returns True, or None if no record matches.

Parameters:: predicate (Callable[[BuildRecordInfo], bool]) – A callable that accepts a BuildRecordInfo and returns True when it is the desired record.
Returns:: The first matching BuildRecordInfo, or None if no record satisfies predicate.
Return type:: BuildRecordInfo | None

property finish_time: datetime | None: UTC datetime when the build finished, or None if not yet complete.

get_all_log_text(*, separator='\n')

Fetch and concatenate the text of every build log.

Makes one API call to list all log IDs, then one call per log to fetch the text. Logs are joined with separator.

Parameters:: separator (str) – String inserted between consecutive log texts (default: "\n").
Returns:: All log content as a single string.
Return type:: str

get_log_text(log_id)

Fetch the plain-text content of a build log.

Parameters:: log_id (int) – Numeric log ID from a BuildLogInfo record. Obtain it via BuildTask.log, BuildJob.log, or BuildStage.log.
Returns:: Log content as a decoded UTF-8 string.
Return type:: str

property id: int: Numeric build ID.

property info: BuildDetails: Build data captured at construction time (or last refresh).

iter_approvals(state=None)

Iterate over environment approvals for this build.

Scoped to this build’s run ID, so only approvals that belong to this specific run are returned.

Parameters:: state (PipelineApprovalStatus | None) – Optional status filter (e.g. PipelineApprovalStatus.PENDING). When None, approvals in all states are returned.
Yields:: PipelineApproval for each matching approval on this build.
Return type:: Iterator[PipelineApproval]

iter_artifacts()

Iterate over artifacts published by the build.

Yields:: BuildArtifact for each artifact associated with the build.
Return type:: Iterator[BuildArtifact]

iter_logs()

Iterate over all log entries for this build.

Yields:: BuildLogInfo for each log container associated with the build.
Return type:: Iterator[BuildLogInfo]

iter_tags()

Iterate over the tags set on the build.

Yields:: Tag name strings.
Return type:: Iterator[str]

iter_timeline_records()

Iterate over the timeline records (stages, jobs, tasks) of the build.

Yields:: BuildRecordInfo for each timeline entry.
Return type:: Iterator[BuildRecordInfo]

iter_work_item_ids()

Iterate over work item IDs associated with the build.

Yields:: Integer work item IDs linked to this build.
Return type:: Iterator[int]

iter_work_item_ids_between(older_build, *, top=None)

Iterate over work item IDs in the range (older_build, this build].

Returns work items associated with any build between older_build (exclusive) and this build (inclusive). Useful for generating a changelog between two consecutive pipeline runs.

Parameters:

older_build (Build) – The earlier build that marks the exclusive lower bound of the range.
top (int | None) – Optional cap on the number of work items returned.

Yields:

Integer work item IDs in the range.

Return type:

Iterator[int]

iter_work_items()

Iterate over work items associated with the build.

Convenience wrapper that resolves the linked IDs via iter_work_item_ids() and then fetches the work item details in a single batch call.

Yields:: WorkItem for each linked work item.
Return type:: Iterator[WorkItem]

iter_work_items_between(older_build, *, top=None)

Iterate over work items in the range (older_build, this build].

Fetches the work item IDs via iter_work_items_between_builds(), then resolves them in a single batch call.

Parameters:

older_build (Build) – The earlier build that marks the exclusive lower bound of the range.
top (int | None) – Optional cap on the number of work items returned.

Yields:

WorkItem for each work item in the build range.

Return type:

Iterator[WorkItem]

list_approvals(state=None)

Return environment approvals for this build as a list.

Parameters:: state (PipelineApprovalStatus | None)
Return type:: list[PipelineApproval]

list_artifacts()

Return all artifacts for this build as a list.

Return type:: list[BuildArtifact]

list_logs()

Return all log entries for this build as a list.

Return type:: list[BuildLogInfo]

list_tags()

Return all tags for this build as a list.

Return type:: list[str]

list_timeline_records()

Return all timeline records for this build as a list.

Return type:: list[BuildRecordInfo]

list_work_item_ids()

Return all work item IDs for this build as a list.

Return type:: list[int]

list_work_item_ids_between(older_build, *, top=None)

Return all work item IDs between two builds as a list.

Parameters:

older_build (Build)
top (int | None)

Return type:

list[int]

list_work_items()

Return all work items for this build as a list.

Return type:: list[WorkItem]

list_work_items_between(older_build, *, top=None)

Return all work items between two builds as a list.

Parameters:

older_build (Build)
top (int | None)

Return type:

list[WorkItem]

property number: str: Build number string (e.g. "20240101.1").

property org: Organization: Organisation this build belongs to — zero-cost.

property pipeline: Pipeline

Pipeline definition that produced this build — zero-cost.

The Pipeline object is looked up from (or inserted into) the service cache using the definition id and name embedded in the build info. No API call is made unless Pipeline.info is accessed.

property pipeline_run: PipelineRun

The Pipelines v2 view of this build run.

Fetches the run via the Pipelines v2 API and returns a PipelineRun bound to this build’s owning pipeline.

Returns:: PipelineRun for this build.

property project: Project: Project this build belongs to — zero-cost.

property queue_time: datetime | None: UTC datetime when the build was queued, or None if not available.

refresh(expand=None)

Discard cached build info.

The next access to info re-fetches from the API.

Parameters:: expand (BuildExpand | None) – Optional $expand value to use on the next fetch. When provided, replaces any previously stored expand value; when None, previously stored expand is preserved.
Return type:: None

remove_tag(tag)

Remove a tag from the build.

Parameters:: tag (str) – Tag name to remove.
Return type:: None

property requested_by: str: Display name of the identity that queued the build.

property requested_for: str | None

Display name of the identity the build was requested for, or None.

For CI builds this is usually the commit author; for manually-queued builds it may differ from requested_by.

property result: BuildResult | None

Build outcome once completed (e.g. "succeeded", "failed").

None while the build is still running.

retry()

Queue a new build run using the same definition and source branch.

Returns:: A new Build object for the queued build run.
Return type:: Build

property source_branch: str: Source branch used for this build (e.g. "refs/heads/main").

property source_version: str: Commit SHA that triggered this build.

property start_time: datetime | None: UTC datetime when the build started, or None if not yet started.

property status: BuildStatus: Current build status.

update(status)

Update the status of this build.

Parameters:: status (BuildStatus) – New build status to set (e.g. BuildStatus.CANCELLING).
Return type:: None

Pipeline¶

OOP wrapper for Azure DevOps pipeline resources.

class pyado.oop.pipelines.pipeline.Pipeline(project, pipeline_id, name, info=None)¶

An Azure DevOps pipeline resource (Pipelines v2).

ADO concept: a pipeline is the definition of a CI/CD process, stored as a YAML file in a repository (or as a classic GUI definition). It is exposed by two APIs:

Pipelines v2 API — pipelines/{id} (docs: pipelines/Pipelines). This class uses this surface.
Build API — build/definitions/{id} — older surface with more fields (triggers, retention, variables), represented as PipelineDefinitionInfo.

The numeric id is the same in both APIs.

The id and name are always known at construction. The full info payload is loaded lazily and cached; call refresh() to discard it so the next access re-fetches from the API.

Parameters:

project (Project)
pipeline_id (int)
name (str)
info (PipelineInfo | None)

_project¶: The Project this pipeline belongs to.

_id¶: Numeric pipeline ID.

_name¶: Pipeline name.

_info¶: Cached pipeline data; None until first lazy fetch.

property api_call: ApiCall¶

Project-level API call for direct use with pyado.raw functions.

ADO pipelines are project-scoped, so the pipeline-level API call is the same as the owning project’s API call.

authorize_resource(resource_type, resource_id, *, authorized=True)¶

Authorize (or de-authorize) a resource for this pipeline.

Parameters:

resource_type (PipelineResourceType) – The type of resource to authorize.
resource_id (str) – String ID of the resource.
authorized (bool) – True to grant access (default); False to revoke.

Returns:

PipelineResourcePermissions reflecting the updated state.

Return type:

cancel_run(run_id)¶

Request cancellation of an in-progress pipeline run.

Parameters:: run_id (int) – Numeric ID of the run to cancel (same as the build ID for Pipelines v2 runs).
Returns:: PipelineRunInfo with state "canceling"; transitions to "completed" with result "canceled" once the agent acknowledges.
Return type:: PipelineRunInfo

get_latest_run()¶

Return the most recent pipeline run, or None if none exist.

Returns:: PipelineRun for the newest run, or None.
Return type:: PipelineRun | None

get_run(run_id)¶

Return a wrapper for a single pipeline run.

Parameters:: run_id (int) – Numeric ID of the pipeline run.
Returns:: PipelineRun wrapping the requested run.
Return type:: PipelineRun

property id: int¶: Numeric pipeline ID — always known, no API call.

property info: PipelineInfo¶: Full pipeline data (lazy-fetched on first access if not supplied).

iter_builds(*, status_filter=None, branch_name=None, top=None)¶

Iterate over builds for this pipeline via the Build API.

Provides richer filtering than iter_runs() (status, branch, top). Delegates to iter_builds() with this pipeline’s definition ID pre-filled.

Parameters:

status_filter (BuildStatus | None) – Filter by build status (e.g. BuildStatus.COMPLETED).
branch_name (str | None) – Filter by source branch ref name (e.g. "refs/heads/main").
top (int | None) – Maximum number of builds to return.

Yields:

Build for each matching build.

Return type:

Iterator[Build]

iter_runs(*, top=None)¶

Iterate over all runs of the pipeline.

Parameters:: top (int | None) – Maximum number of runs to return. When None the API default is used.
Yields:: PipelineRun for each run, in API-returned order (newest first).
Return type:: Iterator[PipelineRun]

list_builds(*, status_filter=None, branch_name=None, top=None)¶

Return all builds for this pipeline as a list.

Parameters:

status_filter (BuildStatus | None)
branch_name (str | None)
top (int | None)

Return type:

list[Build]

list_runs(*, top=None)¶

Return all runs for this pipeline as a list.

Parameters:: top (int | None)
Return type:: list[PipelineRun]

property name: str¶: Pipeline name — always known, no API call.

property org: Organization¶: Organisation this pipeline belongs to — zero-cost.

property project: Project¶: Project this pipeline belongs to — zero-cost.

refresh()¶

Discard cached pipeline info.

The next access to info re-fetches from the API.

Return type:: None

start_run(*, resources=None, variables=None, template_parameters=None, stages_to_skip=None)¶

Trigger a new run of the pipeline.

Parameters:

resources (dict[str, Any] | None) – Optional pipeline resources override dict.
variables (dict[str, VariableInfo] | None) – Optional pipeline variable overrides dict.
template_parameters (dict[str, str] | None) – Optional template parameter overrides.
stages_to_skip (list[str] | None) – List of stage names to skip during the run.

Returns:

PipelineRun wrapping the newly triggered run.

Return type:

PipelineRun

class pyado.oop.pipelines.pipeline.PipelineRun(pipeline, info)¶

A single Pipelines v2 run.

Wraps a PipelineRunInfo and holds a back-reference to the owning Pipeline. Instances are obtained from Pipeline.iter_runs(), Pipeline.get_run(), or Pipeline.start_run().

Parameters:

pipeline (Pipeline)
info (PipelineRunInfo)

_pipeline¶: The Pipeline this run belongs to.

_info¶: Run data returned from the API at construction time.

property api_call: ApiCall¶

Project-level API call for direct use with pyado.raw pipeline functions.

cancel()¶

Request cancellation of this in-progress run.

Updates the wrapper’s cached info to reflect the cancelling state.

Returns:: self with state "canceling"; transitions to "completed" with result "canceled" once the agent acknowledges.
Return type:: PipelineRun

property id: int¶: Numeric run ID.

property info: PipelineRunInfo¶: Run data captured at construction time.

iter_approvals(state=None)¶

Iterate over environment approvals for this run.

Scoped to this run’s ID, so only approvals that belong to this specific run are returned.

Parameters:: state (PipelineApprovalStatus | None) – Optional status filter (e.g. PipelineApprovalStatus.PENDING). When None, approvals in all states are returned.
Yields:: PipelineApproval for each matching approval on this run.
Return type:: Iterator[PipelineApproval]

list_approvals(state=None)¶

Return environment approvals for this run as a list.

Parameters:: state (PipelineApprovalStatus | None)
Return type:: list[PipelineApproval]

property org: Organization¶: Organisation this run belongs to — zero-cost.

property pipeline: Pipeline¶: Pipeline this run belongs to — zero-cost.

property project: Project¶: Project this run belongs to — zero-cost.

refresh()¶

Discard cached run info.

The next access to info re-fetches from the API.

Return type:: None

property result: PipelineRunResult | None¶

Run result once completed (e.g. "succeeded", "failed").

None while the run is still in progress.

property status: PipelineRunState¶: Current run state (e.g. "inProgress", "completed").

Environment¶

OOP wrapper for Azure DevOps pipeline environment resources.

class pyado.oop.pipelines.environment.Environment(project, env_api_call, info)¶

An Azure DevOps pipeline environment.

Why it exists: bundles the environment ID and info together so callers can inspect properties and iterate deployment history without managing raw API calls.

Instances are obtained from ProjectPipelines.iter_environments() or ProjectPipelines.get_environment().

Parameters:

project (Project)
env_api_call (ApiCall)
info (EnvironmentInfo)

_project¶: The Project this environment belongs to.

_api_call¶: Environment-level ADO API call.

_info¶: Cached environment data.

property api_call: ApiCall¶: Environment-level API call for direct use with pyado.raw functions.

property description: str¶: Environment description.

property id: int¶: Numeric environment ID.

property info: EnvironmentInfo¶: Environment data captured at construction time.

iter_checks()¶

Iterate over all check configurations for this environment.

Yields:: EnvironmentCheckInfo for each check configuration.
Return type:: Iterator[EnvironmentCheckInfo]

iter_deployments(*, top=None)¶

Iterate over deployment records for this environment.

Parameters:: top (int | None) – Maximum number of records to return. When None, the API default is used.
Yields:: EnvironmentDeploymentRecord for each deployment.
Return type:: Iterator[EnvironmentDeploymentRecord]

list_checks()¶

Return all check configurations for this environment as a list.

Return type:: list[EnvironmentCheckInfo]

list_deployments(*, top=None)¶

Return deployment records for this environment as a list.

Parameters:: top (int | None)
Return type:: list[EnvironmentDeploymentRecord]

property name: str¶: Environment name (e.g. "production").

property org: Organization¶: Organisation this environment belongs to — zero-cost.

property project: Project¶: Project this environment belongs to — zero-cost.

refresh()¶

Discard cached environment info.

The next access to info re-fetches from the API.

Return type:: None

Agent¶

OOP wrappers for Azure DevOps agent pool and queue resources.

class pyado.oop.pipelines.agent.Agent(pool, info)¶

An agent within an agent pool.

Why it exists: wraps AgentInfo and holds a back-reference to the owning AgentPool for upward navigation.

Instances are obtained from AgentPool.iter_agents().

Parameters:

pool (AgentPool)
info (AgentInfo)

_pool¶: The AgentPool this agent belongs to.

_info¶: Agent data returned from the API.

property id: int¶: Numeric agent ID.

property info: AgentInfo¶: Raw agent data.

property name: str¶: Agent name.

property pool: AgentPool¶: AgentPool this agent belongs to — zero-cost.

property status: str | None¶: Current agent status string (e.g. "online", "offline").

class pyado.oop.pipelines.agent.AgentPool(org, pool_api_call, info)¶

An Azure DevOps agent pool.

ADO concept: an agent pool is an org-level collection of agents (distributedtask/pools/{poolId}). Both Microsoft-hosted (isHosted=True) and self-hosted pools are represented by this class.

Why it exists: bundles pool info and the pool-level API call so that iter_agents() works without the caller constructing URLs manually.

Instances are obtained from Organization.iter_agent_pools() or Organization.get_agent_pool().

Parameters:

org (Organization)
pool_api_call (ApiCall)
info (AgentPoolInfo)

_org¶: The Organisation this pool belongs to.

_pool_api_call¶: Pool-level ADO API call.

_info¶: Cached pool data.

property id: int¶: Numeric pool ID.

property info: AgentPoolInfo¶: Pool data captured at construction time.

property is_hosted: bool¶: True for Microsoft-hosted pools, False for self-hosted.

iter_agents()¶

Iterate over all agents registered in this pool.

Yields:: Agent for each agent in the pool.
Return type:: Iterator[Agent]

list_agents()¶

Return all agents in this pool as a list.

Return type:: list[Agent]

property name: str¶: Pool name (e.g. "Default", "Azure Pipelines").

property org: Organization¶: Organisation this pool belongs to — zero-cost.

refresh()¶

Discard cached pool info.

The next access to info re-fetches from the API.

Return type:: None

class pyado.oop.pipelines.agent.AgentQueue(project, info)¶

A project-scoped agent queue.

Why it exists: wraps AgentQueueInfo and holds a back-reference to the owning Project.

Instances are obtained from ProjectPipelines.iter_agent_queues() or ProjectPipelines.get_agent_queue().

Parameters:

project (Project)
info (AgentQueueInfo)

_project¶: The Project this queue belongs to.

_info¶: Queue data returned from the API.

property id: int¶: Numeric queue ID.

property info: AgentQueueInfo¶: Raw queue data.

property name: str¶: Queue name (e.g. "Default").

property org: Organization¶: Organisation this queue belongs to — zero-cost.

property pool_id: int | None¶: ID of the agent pool backing this queue, or None if not available.

property project: Project¶: Project this queue belongs to — zero-cost.

Variable Group¶

OOP wrapper for Azure DevOps variable group resources.

class pyado.oop.pipelines.variable_group.VariableGroup(project, variable_group_api_call, info)¶

An Azure DevOps variable group resource.

Why it exists: the ADO variable-group PUT endpoint has two quirks that VariableGroup hides from callers:

Full-replace semantics — every PUT must carry the complete set of variables, not just the changed ones. set_variable() and delete_variable() fetch the current state, apply the targeted change, then write back the full set.
Mandatory project references — the PUT body must contain at least one entry in variableGroupProjectReferences even though the GET response often omits the field (returns null). _project_refs() synthesises a minimal entry from the owning Project when the GET response is silent.

Variable groups are not cached — each factory call returns a fresh instance.

Parameters:

project (Project)
variable_group_api_call (ApiCall)
info (VariableGroupInfo)

_project¶: The Project this variable group belongs to.

_api_call¶: Variable-group-level API call used by all operations.

_info¶: The variable group data returned from the API at construction time.

property api_call: ApiCall¶: Variable-group-level API call for direct use with pyado.raw functions.

delete()¶

Delete this variable group from the project.

The deletion is permanent and cannot be undone via the API.

Return type:: None

property id: int¶: Numeric variable group ID.

property info: VariableGroupInfo¶: Variable group data captured at construction time.

property name: str¶: Variable group name.

property org: Organization¶: Organisation this variable group belongs to — zero-cost.

property project: Project¶: Project this variable group belongs to — zero-cost.

refresh()¶

Discard cached variable group info.

The next access to info re-fetches from the API.

Return type:: None

set_variable(var_name, value, *, is_secret=False)¶

Set or update a single variable in the group.

Fetches all current variables, merges the update, then writes back.

Parameters:

var_name (str) – Name of the variable to set.
value (str) – New value for the variable.
is_secret (bool) – When True the variable is marked as secret.

Return type:

None

unset_variable(var_name)¶

Remove a variable from the group.

Parameters:: var_name (str) – Name of the variable to remove.
Raises:: KeyError – If the variable does not exist in the group.
Return type:: None

update(variables, *, name=None, description=None, var_group_type=None, provider_data=None)¶

Replace the variable group’s variables (and optionally its metadata).

Parameters:

variables (dict[str, VariableInfo]) – New variable mapping to apply. Replaces the existing set entirely.
name (str | None) – New name for the variable group. Defaults to the current name if not supplied.
description (str | None) – Updated description, or None to leave unchanged.
var_group_type (str | None) – Optional type string (e.g. "Vsts", "AzureKeyVault").
provider_data (Any) – Optional provider-specific configuration object (e.g. key vault settings).

Return type:

None

property variables: dict[str, VariableInfo]¶: Current variable mapping (name → VariableInfo).

Secure File¶

OOP wrapper for Azure DevOps secure file resources.

class pyado.oop.pipelines.secure_file.SecureFile(project, secure_file_api_call, info)¶

An Azure DevOps secure file resource.

Why it exists: bundles the secure file ID and info together so callers can inspect properties and delete the file without managing raw API calls.

Instances are obtained from PipelineLibrary.iter_secure_files() or PipelineLibrary.get_secure_file().

Parameters:

project (Project)
secure_file_api_call (ApiCall)
info (SecureFileInfo)

_project¶: The Project this secure file belongs to.

_api_call¶: Secure-file-level ADO API call.

_info¶: Cached secure file data.

property api_call: ApiCall¶: Secure-file-level API call for direct use with pyado.raw functions.

delete()¶

Delete this secure file from the project.

The deletion is permanent and cannot be undone via the API.

Return type:: None

property id: UUID¶: UUID of the secure file.

property info: SecureFileInfo¶: Secure file data captured at construction time.

property name: str¶: Secure file name.

property org: Organization¶: Organisation this secure file belongs to — zero-cost.

property project: Project¶: Project this secure file belongs to — zero-cost.

refresh()¶

Discard cached secure file info.

The next access to info re-fetches from the API.

Return type:: None

Task Group¶

OOP wrapper for Azure DevOps task group resources.

class pyado.oop.pipelines.task_group.TaskGroup(project, info)¶

An ADO task group.

Wraps a single ADO task group in a project. Instances are obtained from ProjectPipelines.iter_task_groups().

Parameters:

project (Project)
info (TaskGroupInfo)

_project¶: The Project this task group belongs to.

_id¶: Task group UUID (always known).

_info¶: Cached task group data; None after refresh().

property category: str | None¶: Task group category.

delete()¶

Delete this task group from the project.

Return type:: None

property description: str | None¶: Task group description.

property id: UUID¶: Task group UUID — always known, no API call.

property info: TaskGroupInfo¶

Full task group data as returned by the API.

Fetched lazily by re-querying the API if refresh() was called since the last access.

property name: str¶: Task group name.

property org: Organization¶: Organisation this task group belongs to — zero-cost.

property project: Project¶: Project this task group belongs to — zero-cost.

refresh()¶

Discard cached task group info.

The next access to info re-fetches from the API.

Return type:: None

update(request)¶

Update this task group.

Parameters:: request (TaskGroupUpdateRequest) – Update request. The id field must match this task group’s id.
Return type:: None

Raw API¶

Core¶

HTTP client infrastructure and shared primitive types for pyado.raw submodules.

pyado.raw._core.AccessToken¶: alias of str

pyado.raw._core.AdoUrl¶

Validated HTTPS URL accepted by ADO API calls (max 2048 characters).

alias of Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=[‘https’], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)]

class pyado.raw._core.ApiCall(*, session=<factory>, parameters={}, timeout=10, url)¶

Class to call Azure DevOps APIs.

Pass a session from get_session() to authenticate requests. When no session is provided a plain unauthenticated session is used.

Parameters:

session (Session)
parameters (dict[str, int | str | bool])
timeout (Annotated[int, Gt(gt=0)])
url (Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=['https'], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)])

build_call(*args, parameters=None, version=None)¶

Build API call from arguments.

Returns:

A new ApiCall with the appended path and merged parameters.

Parameters:

args (str | int | UUID)
parameters (dict[str, int | str | bool] | None)
version (str | None)

Return type:

delete(*args, parameters=None, version=None, extra_headers=None)¶

Helper function to interact with the Azure DevOps API via DELETE.

Returns:

The parsed API response.

Parameters:

args (str | int | UUID)
parameters (dict[str, int | str | bool] | None)
version (str | None)
extra_headers (dict[str, str] | None)

Return type:

Any

get(*args, parameters=None, version=None)¶

Helper function to interact with the Azure DevOps API via GET.

Returns:

The parsed API response.

Parameters:

args (str | int | UUID)
parameters (dict[str, int | str | bool] | None)
version (str | None)

Return type:

Any

get_raw(*args, parameters=None, version=None)¶

Helper function to interact with the Azure DevOps API via GET.

Returns:

The raw bytes content of the response.

Parameters:

args (str | int | UUID)
parameters (dict[str, int | str | bool] | None)
version (str | None)

Return type:

Any

model_config = {'arbitrary_types_allowed': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

patch(*args, parameters=None, version=None, json=None)¶

Helper function to interact with the Azure DevOps API via PATCH.

Returns:

The parsed API response.

Parameters:

args (str | int | UUID)
parameters (dict[str, int | str | bool] | None)
version (str | None)
json (Any)

Return type:

Any

post(*args, parameters=None, version=None, json=None, data=None)¶

Helper function to interact with the Azure DevOps API via POST.

Returns:

The parsed API response.

Parameters:

args (str | int | UUID)
parameters (dict[str, int | str | bool] | None)
version (str | None)
json (Any)
data (Any)

Return type:

Any

put(*args, parameters=None, version=None, json=None, data=None, extra_headers=None)¶

Helper function to interact with the Azure DevOps API via PUT.

Returns:

The parsed API response.

Parameters:

args (str | int | UUID)
parameters (dict[str, int | str | bool] | None)
version (str | None)
json (Any)
data (Any)
extra_headers (dict[str, str] | None)

Return type:

Any

exception pyado.raw._core.AzureDevOpsAuthError(status_code, message)¶

HTTP 401 or 403 from the Azure DevOps API (authentication/authorisation).

Parameters:

status_code (int)
message (str)

Return type:

None

exception pyado.raw._core.AzureDevOpsBadRequestError(status_code, message)¶

HTTP 400 from the Azure DevOps API (malformed or invalid request).

Parameters:

status_code (int)
message (str)

Return type:

None

exception pyado.raw._core.AzureDevOpsConflictError(status_code, message)¶

HTTP 409 from the Azure DevOps API (conflict with current state).

Parameters:

status_code (int)
message (str)

Return type:

None

exception pyado.raw._core.AzureDevOpsError¶: Base class for all Azure DevOps errors raised by pyado.

exception pyado.raw._core.AzureDevOpsHttpError(status_code, message)¶

An HTTP error response from the Azure DevOps REST API.

Parameters:

status_code (int)
message (str)

Return type:

None

status_code¶: The HTTP status code returned by the API.

message¶: The error message extracted from the response body.

exception pyado.raw._core.AzureDevOpsNotFoundError(status_code, message)¶

HTTP 404 from the Azure DevOps API (resource not found).

Parameters:

status_code (int)
message (str)

Return type:

None

class pyado.raw._core.HtmlTextFilter¶

Filter HTML error pages for useful text.

handle_data(data)¶

Add data if the tag context is correct.

Parameters:: data (str)
Return type:: None

handle_endtag(tag)¶

Remove tags from the stack.

Raises:: ValueError – If the closing tag does not match the open tag.
Parameters:: tag (str)
Return type:: None

handle_starttag(tag, attrs)¶

Add tags to the stack.

Parameters:

tag (str)
attrs (list[tuple[str, str | None]])

Return type:

None

class pyado.raw._core.JsonPatchAdd(*, op='add', path, value)¶

Type to store JSON patch information to add data.

Parameters:

op (Literal['add'])
path (str)
value (Any)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw._core.JsonPatchRemove(*, op='remove', path)¶

Type to store JSON patch information to remove data.

Parameters:

op (Literal['remove'])
path (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw._core.get_session(pat=None, bearer_token=None, azure_credentials=None)¶

Return a new session configured via _setup_session().

Parameters:

pat (str | None) – ADO personal access token. Falls back to AZURE_DEVOPS_EXT_PAT.
bearer_token (str | None) – Pre-acquired OAuth bearer token string.
azure_credentials (TokenCredential | None) – Any azure-identity TokenCredential. A bearer token is acquired immediately using the ADO resource scope.

Returns:

A new requests.Session configured with the supplied credentials.

Return type:

Session

Profile¶

Azure DevOps user profile API wrappers.

class pyado.raw.core.profile.ConnectionData(*, authenticatedUser)¶

Response from GET /_apis/connectionData.

Parameters:: authenticatedUser (ConnectionDataIdentity)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.profile.ConnectionDataIdentity(*, id, providerDisplayName)¶

Minimal identity record returned inside the connectionData response.

Parameters:

id (str)
providerDisplayName (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.profile.UserProfile(*, id, displayName, emailAddress, publicAlias)¶

Type to store Azure DevOps user profile details.

Parameters:

id (str)
displayName (str)
emailAddress (str)
publicAlias (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.core.profile.get_connection_data(org_api_call)¶

Return connection data for the organisation including the authenticated user.

The result’s authenticated_user field contains the current user’s identity GUID and display name.

Parameters:: org_api_call (ApiCall) – Organisation-level ADO API call (e.g. ApiCall(access_token=…, url="https://dev.azure.com/myorg")). Must not include a project path segment.
Returns:: ConnectionData for the organisation and authenticated user.
Return type:: ConnectionData

pyado.raw.core.profile.get_my_profile(profile_api_call)¶

Return the profile of the currently authenticated user.

The profile_api_call must point at the user profile base URL (https://app.vssps.visualstudio.com/_apis), not the project API.

Parameters:: profile_api_call (ApiCall) – API call targeting app.vssps.visualstudio.com/_apis.
Returns:: UserProfile for the authenticated user.
Return type:: UserProfile

pyado.raw.core.profile.get_profile_api_call(session)¶

Construct the API call for the user profile endpoint.

The profile API lives on a different host from the rest of ADO (app.vssps.visualstudio.com), so it cannot be built from a project-level ApiCall.

Parameters:: session (Session) – Authenticated requests.Session (from get_session() or get_bearer_session()).
Returns:: ApiCall targeting https://app.vssps.visualstudio.com/_apis.
Return type:: ApiCall

Project¶

Azure DevOps project API wrappers.

pyado.raw.core.project.ProjectId¶: alias of UUID

class pyado.raw.core.project.ProjectInfo(*, id, name, description=None, url=None, state, revision, visibility, lastUpdateTime, defaultTeam=None, capabilities=None)¶

Type to store project details.

Parameters:

id (UUID)
name (str)
description (str | None)
url (Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=['https'], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)] | None)
state (ProjectState)
revision (int)
visibility (ProjectVisibility)
lastUpdateTime (datetime)
defaultTeam (_ProjectDefaultTeam | None)
capabilities (_ProjectCapabilities | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.core.project.ProjectName¶: alias of str

class pyado.raw.core.project.ProjectState(value)¶: Possible lifecycle states of an ADO project.

class pyado.raw.core.project.ProjectVisibility(value)¶: Visibility settings for an ADO project.

pyado.raw.core.project.get_project(org_api_call, name, *, include_capabilities=False)¶

Return details for a single project by name or UUID string.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
name (str) – Project name (case-sensitive) or UUID string.
include_capabilities (bool) – When True, the response includes the project’s process template and version control capabilities (default: False).

Returns:

ProjectInfo for the requested project.

Return type:

ProjectInfo

pyado.raw.core.project.iter_projects(base_api_call)¶

Iterate over all projects in the ADO organisation.

Parameters:: base_api_call (ApiCall) – Organisation-level ADO API call (URL must point at the org root or /_apis).
Yields:: ProjectInfo for each project.
Return type:: Iterator[ProjectInfo]

Identity¶

Azure DevOps vssps identity and graph-group API wrappers.

All endpoints in this module live on https://vssps.dev.azure.com/{org}/. Using the relative-path form /{org}/ returns 404 HTML responses — this module always constructs the full absolute base URL.

class pyado.raw.core.identity.AccessLevel(*, licensingSource=None, accountLicenseType=None, msdnLicenseType=None, licenseDisplayName=None, status=None, statusMessage=None, assignmentSource=None)¶

License / access-level information for a user entitlement.

Parameters:

licensingSource (str | None)
accountLicenseType (str | None)
msdnLicenseType (str | None)
licenseDisplayName (str | None)
status (str | None)
statusMessage (str | None)
assignmentSource (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.identity.GraphGroup(*, displayName, descriptor, principalName, description=None, origin=None, originId=None, mailAddress=None, subjectKind)¶

A graph group record returned by the vssps graph/groups endpoint.

Parameters:

displayName (str)
descriptor (str)
principalName (str)
description (str | None)
origin (str | None)
originId (str | None)
mailAddress (str | None)
subjectKind (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.identity.GraphMembership(*, containerDescriptor, memberDescriptor)¶

A graph membership record linking a member to a container group.

Parameters:

containerDescriptor (str)
memberDescriptor (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.identity.GraphUser(*, descriptor, displayName, subjectKind, principalName=None, mailAddress=None, origin=None, originId=None, isDeletedInOrigin=False)¶

A graph user record returned by the vssps graph/users endpoint.

Parameters:

descriptor (str)
displayName (str)
subjectKind (str)
principalName (str | None)
mailAddress (str | None)
origin (str | None)
originId (str | None)
isDeletedInOrigin (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.identity.IdentityInfo(*, id, providerDisplayName, subjectDescriptor=None, isActive=True, isContainer=False)¶

An identity record returned by the vssps identities endpoint.

Parameters:

id (str)
providerDisplayName (str)
subjectDescriptor (str | None)
isActive (bool)
isContainer (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.identity.UserEntitlement(*, id, user, accessLevel=None)¶

A user entitlement record pairing a graph user with an access level.

Parameters:

id (UUID)
user (GraphUser)
accessLevel (AccessLevel | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.identity.UserEntitlementCreateRequest(*, user, accessLevel)¶

Request body for creating a new user entitlement.

Parameters:

user (GraphUser)
accessLevel (AccessLevel)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.core.identity.delete_graph_membership(vssps_call, subject_descriptor, container_descriptor)¶

Remove a user (or group) from a group.

Parameters:

vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call()).
subject_descriptor (str) – Descriptor of the member to remove.
container_descriptor (str) – Descriptor of the group to remove the member from.

Return type:

None

pyado.raw.core.identity.get_graph_user(vssps_call, descriptor)¶

Return a single graph user by subject descriptor.

Parameters:

vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call()).
descriptor (str) – Subject descriptor of the user to retrieve.

Returns:

GraphUser for the requested descriptor.

Return type:

GraphUser

pyado.raw.core.identity.get_identities(vssps_call, descriptors)¶

Look up one or more identities by subject descriptor.

Parameters:

vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call()).
descriptors (list[str]) – List of subject descriptor strings to resolve.

Returns:

List of IdentityInfo objects for the requested descriptors.

Return type:

list[IdentityInfo]

pyado.raw.core.identity.get_vssps_api_call(session, org_name)¶

Construct an API call targeting the vssps service for an organisation.

The vssps service requires the full absolute URL https://vssps.dev.azure.com/{org}. Relative paths to the vssps service return 404 HTML responses.

Parameters:

session (Session) – Authenticated requests.Session (from get_session() or get_bearer_session()).
org_name (str) – Azure DevOps organisation name (the {org} slug from https://dev.azure.com/{org}).

Returns:

ApiCall targeting https://vssps.dev.azure.com/{org_name}.

Return type:

pyado.raw.core.identity.iter_graph_groups(vssps_call)¶

Iterate over all graph groups in the organisation.

Parameters:: vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call()).
Yields:: GraphGroup for each group in the organisation.
Return type:: Iterator[GraphGroup]

pyado.raw.core.identity.iter_graph_users(vssps_call)¶

Iterate over all graph users in the organisation.

Parameters:: vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call()).
Yields:: GraphUser for each user in the organisation.
Return type:: Iterator[GraphUser]

pyado.raw.core.identity.iter_user_entitlements(vssps_call)¶

Iterate over all user entitlements in the organisation.

Parameters:: vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call()).
Yields:: UserEntitlement for each user in the organisation.
Return type:: Iterator[UserEntitlement]

pyado.raw.core.identity.list_graph_memberships(vssps_call, descriptor)¶

Return the member descriptors of a group (direction=Down).

Parameters:

vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call).
descriptor (str) – Subject descriptor of the container group.

Returns:

Sorted list of member subject descriptors.

Return type:

list[str]

pyado.raw.core.identity.list_graph_users(vssps_call)¶

Return all graph users as a list.

Parameters:: vssps_call (ApiCall)
Return type:: list[GraphUser]

pyado.raw.core.identity.list_user_entitlements(vssps_call)¶

Return all user entitlements as a list.

Parameters:: vssps_call (ApiCall)
Return type:: list[UserEntitlement]

pyado.raw.core.identity.patch_user_entitlement(vssps_call, user_id, access_level)¶

Update the access level for an existing user entitlement.

Parameters:

vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call()).
user_id (UUID) – UUID of the user whose access level should be updated.
access_level (AccessLevel) – New access level to apply.

Returns:

Updated UserEntitlement.

Return type:

UserEntitlement

pyado.raw.core.identity.post_user_entitlement(vssps_call, request)¶

Add a user to the organisation with an access level.

Parameters:

vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call()).
request (UserEntitlementCreateRequest) – Create request specifying the user and desired access level.

Returns:

UserEntitlement for the newly added user.

Return type:

UserEntitlement

pyado.raw.core.identity.put_graph_membership(vssps_call, subject_descriptor, container_descriptor)¶

Add a user (or group) to a group.

Parameters:

vssps_call (ApiCall) – vssps-scoped API call (from get_vssps_api_call()).
subject_descriptor (str) – Descriptor of the member to add.
container_descriptor (str) – Descriptor of the group to add the member to.

Returns:

GraphMembership describing the new membership link.

Return type:

GraphMembership

Dashboard¶

Azure DevOps dashboard API wrappers.

pyado.raw.overview.dashboard.DashboardId¶: alias of UUID

class pyado.raw.overview.dashboard.DashboardInfo(*, id, name, description='', etag=None, widgets=<factory>)¶

Minimal representation of an ADO team dashboard.

Parameters:

id (UUID)
name (str)
description (str)
etag (str | None)
widgets (list[WidgetInfo])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.overview.dashboard.WidgetId¶: UUID identifier for a dashboard widget.

class pyado.raw.overview.dashboard.WidgetInfo(*, id, name, typeId='', position=None, size=None)¶

A widget on an ADO dashboard.

Parameters:

id (UUID)
name (str)
typeId (str)
position (_WidgetPosition | None)
size (_WidgetSize | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.overview.dashboard.get_dashboard(dashboard_api_call)¶

Return the detail for a single dashboard, including its widgets.

Parameters:: dashboard_api_call (ApiCall) – Dashboard-level ADO API call (from get_dashboard_api_call).
Returns:: DashboardInfo with the full widget list populated.
Return type:: DashboardInfo

pyado.raw.overview.dashboard.get_dashboard_api_call(team_api_call, dashboard_id)¶

Build a dashboard-scoped API call.

Parameters:

team_api_call (ApiCall) – Team-level ADO API call (from make_team_api_call).
dashboard_id (UUID) – UUID of the dashboard.

Returns:

An ApiCall pointing at the dashboard resource.

Return type:

NotificationSubscription

pyado.raw.overview.dashboard.iter_dashboards(team_api_call)¶

Iterate over all dashboards for a team.

Parameters:: team_api_call (ApiCall) – Team-level ADO API call (from make_team_api_call).
Yields:: DashboardInfo for each dashboard (without widgets — widgets are only present in the detail response, see get_dashboard).
Return type:: Iterator[DashboardInfo]

pyado.raw.overview.dashboard.list_dashboards(team_api_call)¶

Return all dashboards for a team as a list.

Parameters:: team_api_call (ApiCall)
Return type:: list[DashboardInfo]

Notification¶

Azure DevOps notification subscription API wrappers.

class pyado.raw.settings.notification.NotificationSubscription(*, id, description='', filter=<factory>, subscriber=<factory>, channel=<factory>, scope=<factory>, status=None, url=None, flags=None, permissions=None, adminSettings=<factory>, diagnostics=<factory>, extendedProperties=<factory>, userSettings=<factory>)¶

A single ADO notification subscription.

Parameters:

id (str)
description (str)
filter (dict[str, Any])
subscriber (dict[str, Any])
channel (dict[str, Any])
scope (dict[str, Any])
status (str | None)
url (str | None)
flags (str | None)
permissions (str | None)
adminSettings (dict[str, Any])
diagnostics (dict[str, Any])
extendedProperties (dict[str, Any])
userSettings (dict[str, Any])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.settings.notification.delete_notification_subscription(org_api_call, subscription_id)¶

Delete a notification subscription.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
subscription_id (str) – Subscription identifier (GUID or numeric string).

Return type:

None

pyado.raw.settings.notification.get_notification_subscription(org_api_call, subscription_id)¶

Fetch a single notification subscription by ID.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
subscription_id (str) – Subscription identifier (GUID or numeric string).

Returns:

NotificationSubscription parsed from the API response.

Return type:

pyado.raw.settings.notification.iter_notification_subscriptions(org_api_call)¶

Iterate over all notification subscriptions in the organisation.

The endpoint is org-scoped; filter to a specific project client-side by inspecting subscription.scope.

Parameters:: org_api_call (ApiCall) – Organisation-level ADO API call.
Yields:: NotificationSubscription for each subscription.
Return type:: Iterator[NotificationSubscription]

pyado.raw.settings.notification.list_notification_subscriptions(org_api_call)¶

Return all notification subscriptions in the organisation as a list.

Parameters:: org_api_call (ApiCall)
Return type:: list[NotificationSubscription]

pyado.raw.settings.notification.patch_notification_subscription(org_api_call, subscription_id, body)¶

Update an existing notification subscription via PATCH.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
subscription_id (str) – Subscription identifier (GUID or numeric string).
body (dict[str, Any]) – Partial subscription payload with fields to update.

Returns:

Updated NotificationSubscription parsed from the API response.

Return type:

NotificationSubscription

pyado.raw.settings.notification.post_notification_subscription(org_api_call, body)¶

Create a new notification subscription.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
body (dict[str, Any]) – Subscription creation payload (description, filter, channel, subscriber, scope, etc.).

Returns:

NotificationSubscription for the newly created subscription.

Return type:

NotificationSubscription

Policy¶

Azure DevOps branch policy configuration and types API wrappers.

pyado.raw.repos.policy.PolicyConfigurationId¶: alias of int

class pyado.raw.repos.policy.PolicyConfigurationInfo(*, id, type, isEnabled, isBlocking, settings, isDeleted=False, isEnterpriseManaged=False, revision=None, url=None, createdBy=None, createdDate=None)¶

A single ADO branch policy configuration.

The settings field is a catch-all dict because the schema varies by policy type and is too wide to enumerate strictly.

Parameters:

id (int)
type (PolicyType)
isEnabled (bool)
isBlocking (bool)
settings (dict[str, Any])
isDeleted (bool)
isEnterpriseManaged (bool)
revision (int | None)
url (str | None)
createdBy (PolicyCreatedBy | None)
createdDate (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.policy.PolicyConfigurationRequest(*, isEnabled, isBlocking, type, settings)¶

Request body for creating or updating a policy configuration.

Parameters:

isEnabled (bool)
isBlocking (bool)
type (PolicyTypeIdRef)
settings (dict[str, Any])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.policy.PolicyCreatedBy(*, id, displayName)¶

Identity reference embedded in a policy configuration.

Parameters:

id (UUID)
displayName (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.policy.PolicyScope(*, repositoryId=None, refName=None, matchKind=None)¶

Repository or branch scope entry for a policy configuration.

A policy’s settings["scope"] is a list of these objects. Each entry restricts the policy to a specific repository and, optionally, a subset of branches. Use the factory class methods to build the most common variants.

Serialize with model_dump(by_alias=True, exclude_none=True) unless you need to express an explicit null repository_id (meaning “all repositories in the project”), in which case omit exclude_none.

Parameters:

repositoryId (UUID | None)
refName (str | None)
matchKind (PolicyScopeMatchKind | None)

classmethod for_all_branches(repository_id)¶

Create a scope that targets every branch in a repository.

Uses a prefix match on "refs/heads/" so that all branches, including those created after the policy is applied, are covered.

Parameters:: repository_id (UUID) – RepositoryId of the target repository.
Returns:: PolicyScope targeting all branches.
Return type:: PolicyScope

classmethod for_branch(repository_id, ref_name, match_kind=PolicyScopeMatchKind.EXACT)¶

Create a scope that targets a specific branch (or prefix) in a repository.

Parameters:

repository_id (UUID) – RepositoryId of the target repository.
ref_name (str) – Full ref name, e.g. "refs/heads/main".
match_kind (PolicyScopeMatchKind) – How ref_name is matched; defaults to PolicyScopeMatchKind.EXACT.

Returns:

PolicyScope targeting the specified branch.

Return type:

PolicyScope

classmethod for_default_branch(repository_id)¶

Create a scope that targets the default branch of a repository.

Parameters:: repository_id (UUID) – RepositoryId of the target repository.
Returns:: PolicyScope targeting the default branch (matchKind=DefaultBranch).
Return type:: PolicyScope

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.policy.PolicyScopeMatchKind(value)¶

How a policy scope’s ref_name is matched against branch names.

EXACT matches a single named branch. PREFIX matches all branches whose ref begins with ref_name (typically "refs/heads/" to cover every branch in the repository). DEFAULT_BRANCH matches the current default branch regardless of its name; ref_name is ignored in this case.

class pyado.raw.repos.policy.PolicyType(*, id, displayName, url=None, description=None)¶

Policy type, returned by the types API and embedded in configurations.

Parameters:

id (UUID)
displayName (str)
url (str | None)
description (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.policy.PolicyTypeId¶: alias of UUID

class pyado.raw.repos.policy.PolicyTypeIdRef(*, id)¶

Minimal policy type reference used in write requests.

Parameters:: id (UUID)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.policy.delete_policy_configuration(policy_configuration_api_call)¶

Delete a policy configuration.

Parameters:: policy_configuration_api_call (ApiCall) – Configuration-level ADO API call (from get_policy_configuration_api_call).
Return type:: None

pyado.raw.repos.policy.get_policy_configuration(policy_configuration_api_call)¶

Return a single policy configuration by ID.

Parameters:: policy_configuration_api_call (ApiCall) – Configuration-level ADO API call (from get_policy_configuration_api_call).
Returns:: The matching PolicyConfigurationInfo.
Return type:: PolicyConfigurationInfo

pyado.raw.repos.policy.get_policy_configuration_api_call(project_api_call, config_id)¶

Build a policy-configuration-scoped API call.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
config_id (int) – Numeric ID of the policy configuration.

Returns:

An ApiCall pointing at the policy configuration resource.

Return type:

PolicyConfigurationInfo

pyado.raw.repos.policy.get_policy_type(project_api_call, type_id)¶

Return a single policy type by ID.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
type_id (UUID) – UUID of the policy type.

Returns:

The matching PolicyType.

Return type:

PolicyType

pyado.raw.repos.policy.iter_policy_configurations(project_api_call)¶

Iterate over all policy configurations in a project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: PolicyConfigurationInfo for each configured policy.
Return type:: Iterator[PolicyConfigurationInfo]

pyado.raw.repos.policy.iter_policy_types(project_api_call)¶

Iterate over all available policy types in a project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: PolicyType for each available policy type.
Return type:: Iterator[PolicyType]

pyado.raw.repos.policy.list_policy_configurations(project_api_call)¶

Return all policy configurations in a project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[PolicyConfigurationInfo]

pyado.raw.repos.policy.list_policy_types(project_api_call)¶

Return all available policy types in a project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[PolicyType]

pyado.raw.repos.policy.post_policy_configuration(project_api_call, request)¶

Create a new policy configuration in a project.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
request (PolicyConfigurationRequest) – Request specifying the type, settings, and blocking flag.

Returns:

The newly created PolicyConfigurationInfo.

Return type:

pyado.raw.repos.policy.put_policy_configuration(policy_configuration_api_call, request)¶

Update an existing policy configuration.

Parameters:

policy_configuration_api_call (ApiCall) – Configuration-level ADO API call (from get_policy_configuration_api_call).
request (PolicyConfigurationRequest) – Updated settings for the policy configuration.

Returns:

The updated PolicyConfigurationInfo.

Return type:

PolicyConfigurationInfo

Process¶

Azure DevOps work process API wrappers.

class pyado.raw.core.process.ProcessBehaviorCreateRequest(*, name, referenceName=None, color=None, description=None)¶

Request body for creating a behavior in a process.

Parameters:

name (str)
referenceName (str | None)
color (str | None)
description (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessBehaviorField(*, name=None, referenceName=None, defaultValue=None)¶

A field reference on a process behavior.

Parameters:

name (str | None)
referenceName (str | None)
defaultValue (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessBehaviorInfo(*, referenceName, name, color=None, description='', rank=None, fields=<factory>)¶

A behavior (portfolio backlog level) defined in a process.

Parameters:

referenceName (str)
name (str)
color (str | None)
description (str)
rank (int | None)
fields (list[ProcessBehaviorField])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessBehaviorUpdateRequest(*, name=None, color=None, description=None)¶

Request body for updating a behavior in a process.

Parameters:

name (str | None)
color (str | None)
description (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessCreateRequest(*, name, parentProcessTypeId, description=None, referenceName=None)¶

Request body for creating an inherited process template.

Parameters:

name (str)
parentProcessTypeId (UUID)
description (str | None)
referenceName (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessDetail(*, typeId, name, description='', referenceName=None, parentProcessTypeId=None, isEnabled=True, customizationType=None, isDefault=False, workItemTypes=<factory>, behaviors=<factory>, projectFields=<factory>)¶

Composite process detail gathered from all process sub-resources.

Parameters:

typeId (UUID)
name (str)
description (str)
referenceName (str | None)
parentProcessTypeId (str | None)
isEnabled (bool)
customizationType (ProcessType | None)
isDefault (bool)
workItemTypes (list[ProcessWITInfo])
behaviors (list[ProcessBehaviorInfo])
projectFields (list[ProjectFieldInfo])

type_id¶

Process template UUID.

Type:: uuid.UUID

name¶

Human-readable process name.

Type:: str

description¶

Optional process description.

Type:: str

reference_name¶

Unique reference name for the process.

Type:: str | None

parent_process_type_id¶

UUID of the parent (system) process this was derived from; None for system processes.

Type:: str | None

is_enabled¶

Whether the process is enabled in the organisation.

Type:: bool

customization_type¶

Customisation origin (e.g. "system" or "inherited").

Type:: pyado.raw.core.process.ProcessType | None

is_default¶

Whether this is the default process for the org.

Type:: bool

work_item_types¶

WIT definitions with states, rules, and fields.

Type:: list[pyado.raw.core.process.ProcessWITInfo]

behaviors¶

Portfolio backlog behaviors in this process.

Type:: list[pyado.raw.core.process.ProcessBehaviorInfo]

project_fields¶

All field definitions registered in the project.

Type:: list[pyado.raw.core.process.ProjectFieldInfo]

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.core.process.ProcessId¶: alias of UUID

class pyado.raw.core.process.ProcessType(value)¶

The origin type of an ADO work process template.

SYSTEM processes are the built-in templates shipped by Microsoft (Agile, Scrum, CMMI, Basic). INHERITED processes are copies derived from a system process that can be customised per organisation.

class pyado.raw.core.process.ProcessUpdateRequest(*, name=None, description=None, isDefault=None, isEnabled=None)¶

Request body for updating a process template.

Parameters:

name (str | None)
description (str | None)
isDefault (bool | None)
isEnabled (bool | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWITInfo(*, referenceName, name, description='', color=None, icon=None, isDisabled=False, states=<factory>, rules=<factory>, fields=<factory>)¶

A work item type as returned by the process API.

Parameters:

referenceName (str)
name (str)
description (str)
color (str | None)
icon (str | None)
isDisabled (bool)
states (list[ProcessWorkItemState])
rules (list[ProcessWorkItemRule])
fields (list[ProcessWorkItemField])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemField(*, name=None, referenceName=None, fieldType=None, isRequired=False, isReadOnly=False, defaultValue=None, helpText=None, allowedValues=None)¶

A field entry on a work item type in a process.

Parameters:

name (str | None)
referenceName (str | None)
fieldType (WorkItemFieldType | None)
isRequired (bool)
isReadOnly (bool)
defaultValue (str | None)
helpText (str | None)
allowedValues (list[str] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemRule(*, id=None, name=None, isSystem=False, isDisabled=False, conditions=<factory>, actions=<factory>)¶

A workflow rule on a work item type in a process.

Parameters:

id (str | None)
name (str | None)
isSystem (bool)
isDisabled (bool)
conditions (list[ProcessWorkItemTypeRuleCondition])
actions (list[ProcessWorkItemTypeRuleAction])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemState(*, name, stateCategory=None, id=None, color=None, url=None)¶

A work item type state as returned by the process states API.

Parameters:

name (str)
stateCategory (WorkItemStateCategory | None)
id (str | None)
color (str | None)
url (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemTypeCreateRequest(*, name, referenceName=None, description=None, color=None, icon=None)¶

Request body for creating a work item type in a process.

Parameters:

name (str)
referenceName (str | None)
description (str | None)
color (str | None)
icon (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemTypeFieldAddRequest(*, referenceName, defaultValue=None, isRequired=False, isReadOnly=False, allowedValues=<factory>)¶

Request body for adding a field to a work item type in a process.

Parameters:

referenceName (str)
defaultValue (str | None)
isRequired (bool)
isReadOnly (bool)
allowedValues (list[str])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemTypeFieldUpdateRequest(*, defaultValue=None, isRequired=None, isReadOnly=None, allowedValues=None)¶

Request body for updating a field on a work item type in a process.

Parameters:

defaultValue (str | None)
isRequired (bool | None)
isReadOnly (bool | None)
allowedValues (list[str] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemTypeRuleAction(*, actionType=None, targetField=None, value=None)¶

An action clause in a work item type rule.

Parameters:

actionType (str | None)
targetField (str | None)
value (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemTypeRuleCondition(*, conditionType=None, field=None, value=None)¶

A condition clause in a work item type rule.

Parameters:

conditionType (str | None)
field (str | None)
value (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemTypeRuleCreateRequest(*, name, conditions=<factory>, actions=<factory>, isDisabled=False)¶

Request body for creating a rule on a work item type.

Parameters:

name (str)
conditions (list[ProcessWorkItemTypeRuleCondition])
actions (list[ProcessWorkItemTypeRuleAction])
isDisabled (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.core.process.ProcessWorkItemTypeRuleId¶: alias of str

class pyado.raw.core.process.ProcessWorkItemTypeRuleUpdateRequest(*, name=None, conditions=None, actions=None, isDisabled=None)¶

Request body for updating a rule on a work item type.

Parameters:

name (str | None)
conditions (list[ProcessWorkItemTypeRuleCondition] | None)
actions (list[ProcessWorkItemTypeRuleAction] | None)
isDisabled (bool | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemTypeStateCreateRequest(*, name, color, stateCategory=None, order=None)¶

Request body for creating a state on a work item type.

Parameters:

name (str)
color (str)
stateCategory (WorkItemStateCategory | None)
order (int | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.core.process.ProcessWorkItemTypeStateId¶: alias of str

class pyado.raw.core.process.ProcessWorkItemTypeStateUpdateRequest(*, name=None, color=None, stateCategory=None, order=None)¶

Request body for updating a state on a work item type.

Parameters:

name (str | None)
color (str | None)
stateCategory (WorkItemStateCategory | None)
order (int | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProcessWorkItemTypeUpdateRequest(*, name=None, description=None, color=None, icon=None, isDisabled=None)¶

Request body for updating a work item type in a process.

Parameters:

name (str | None)
description (str | None)
color (str | None)
icon (str | None)
isDisabled (bool | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.process.ProjectFieldInfo(*, name, referenceName, fieldType=None, readOnly=False, canSortBy=False, isQueryable=False, isIdentity=False)¶

A field definition at project scope.

Parameters:

name (str)
referenceName (str)
fieldType (WorkItemFieldType | None)
readOnly (bool)
canSortBy (bool)
isQueryable (bool)
isIdentity (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.core.process.delete_behavior(org_api_call, process_id, behavior_ref)¶

Delete a behavior from a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
behavior_ref (str) – Reference name of the behavior to delete.

Return type:

None

pyado.raw.core.process.delete_process(org_api_call, process_id)¶

Delete a process template from the organisation.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template to delete.

Return type:

None

pyado.raw.core.process.delete_work_item_type(org_api_call, process_id, work_item_type_ref)¶

Delete a work item type from a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type to delete.

Return type:

None

pyado.raw.core.process.delete_work_item_type_field(org_api_call, process_id, work_item_type_ref, field_ref)¶

Remove a field from a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type.
field_ref (str) – Reference name of the field to remove.

Return type:

None

pyado.raw.core.process.delete_work_item_type_rule(org_api_call, process_id, work_item_type_ref, rule_id)¶

Delete a rule from a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type.
rule_id (str) – ID of the rule to delete.

Return type:

None

pyado.raw.core.process.delete_work_item_type_state(org_api_call, process_id, work_item_type_ref, state_id)¶

Delete a state from a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type.
state_id (str) – ID of the state to delete.

Return type:

None

pyado.raw.core.process.get_process(org_api_call, process_id)¶

Fetch a single process template by ID without sub-resources.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.

Returns:

ProcessDetail for the requested process (WIT lists are empty).

Return type:

pyado.raw.core.process.get_process_info(org_api_call, project_api_call, template_type_id)¶

Gather composite process information for a project.

Calls five ADO endpoints in sequence:

GET /_apis/work/processes/{templateTypeId} — process detail
GET /_apis/work/processes/{id}/workitemtypes — WITs in process
Per WIT: states, rules, and fields
GET /_apis/work/processes/{id}/behaviors
GET /{project}/_apis/wit/fields — all project fields

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
project_api_call (ApiCall) – Project-level ADO API call.
template_type_id (UUID) – UUID of the process template (available via ProjectInfo.capabilities.process_template.template_type_id).

Returns:

ProcessDetail with all sub-resources populated.

Return type:

pyado.raw.core.process.iter_processes(org_api_call)¶

Iterate over all work process templates in the organisation.

Parameters:: org_api_call (ApiCall) – Organisation-level ADO API call.
Yields:: ProcessDetail for each process template (WIT lists are empty).
Return type:: Iterator[ProcessDetail]

pyado.raw.core.process.list_processes(org_api_call)¶

Return all work process templates in the organisation as a list.

Parameters:: org_api_call (ApiCall) – Organisation-level ADO API call.
Returns:: List of ProcessDetail for each process template.
Return type:: list[ProcessDetail]

pyado.raw.core.process.patch_behavior(org_api_call, process_id, behavior_ref, request)¶

Update a behavior in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
behavior_ref (str) – Reference name of the behavior to update (e.g. "System.RequirementBacklogBehavior").
request (ProcessBehaviorUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessBehaviorInfo.

Return type:

ProcessBehaviorInfo

pyado.raw.core.process.patch_process(org_api_call, process_id, request)¶

Update an existing process template.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template to update.
request (ProcessUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessDetail.

Return type:

pyado.raw.core.process.patch_work_item_type(org_api_call, process_id, work_item_type_ref, request)¶

Update a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type (e.g. "Custom.MyType").
request (ProcessWorkItemTypeUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessWITInfo.

Return type:

ProcessWITInfo

pyado.raw.core.process.patch_work_item_type_field(org_api_call, process_id, work_item_type_ref, field_ref, request)¶

Update a field on a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type.
field_ref (str) – Reference name of the field to update (e.g. "System.Title").
request (ProcessWorkItemTypeFieldUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessWorkItemField.

Return type:

pyado.raw.core.process.patch_work_item_type_rule(org_api_call, process_id, work_item_type_ref, rule_id, request)¶

Update a rule on a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type.
rule_id (str) – ID of the rule to update.
request (ProcessWorkItemTypeRuleUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessWorkItemRule.

Return type:

pyado.raw.core.process.patch_work_item_type_state(org_api_call, process_id, work_item_type_ref, state_id, request)¶

Update a state on a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type.
state_id (str) – ID of the state to update.
request (ProcessWorkItemTypeStateUpdateRequest) – Update request with fields to change.

Returns:

Updated ProcessWorkItemState.

Return type:

pyado.raw.core.process.post_behavior(org_api_call, process_id, request)¶

Create a behavior in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
request (ProcessBehaviorCreateRequest) – Create request specifying name and optional color.

Returns:

ProcessBehaviorInfo for the newly created behavior.

Return type:

ProcessBehaviorInfo

pyado.raw.core.process.post_process(org_api_call, request)¶

Create a new inherited process template.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
request (ProcessCreateRequest) – Create request specifying name and parent process.

Returns:

ProcessDetail for the newly created process.

Return type:

pyado.raw.core.process.post_work_item_type(org_api_call, process_id, request)¶

Create a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
request (ProcessWorkItemTypeCreateRequest) – Create request for the new work item type.

Returns:

ProcessWITInfo for the newly created work item type.

Return type:

ProcessWITInfo

pyado.raw.core.process.post_work_item_type_field(org_api_call, process_id, work_item_type_ref, request)¶

Add a field to a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type.
request (ProcessWorkItemTypeFieldAddRequest) – Add request specifying the field reference name and options.

Returns:

ProcessWorkItemField describing the field as it was added.

Return type:

pyado.raw.core.process.post_work_item_type_rule(org_api_call, process_id, work_item_type_ref, request)¶

Create a rule on a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type.
request (ProcessWorkItemTypeRuleCreateRequest) – Create request specifying conditions and actions.

Returns:

ProcessWorkItemRule for the newly created rule.

Return type:

pyado.raw.core.process.post_work_item_type_state(org_api_call, process_id, work_item_type_ref, request)¶

Create a state on a work item type in a process.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
process_id (UUID) – UUID of the process template.
work_item_type_ref (str) – Reference name of the work item type.
request (ProcessWorkItemTypeStateCreateRequest) – Create request for the new state.

Returns:

ProcessWorkItemState for the newly created state.

Return type:

Search¶

Azure DevOps Search API wrappers (almsearch.dev.azure.com).

class pyado.raw.core.search.CodeSearchRequest(*, searchText, skip=0, top=25, filters=None, order_by=None, includeFacets=False, includeSnippet=False)¶

Request body for the ADO code search API.

Extends SearchRequest with include_snippet, which controls whether matched code snippets are included in results.

Parameters:

searchText (str)
skip (int)
top (int)
filters (dict[str, list[str]] | None)
order_by (list[SearchSortOption] | None)
includeFacets (bool)
includeSnippet (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.CodeSearchResponse(*, count=0, results=<factory>)¶

Response from the code search API.

Parameters:

count (int)
results (list[CodeSearchResult])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.CodeSearchResult(*, fileName='', path='', project=<factory>, repository=<factory>, versions=<factory>, matches=<factory>, contentId='')¶

A single result from the code search API.

Parameters:

fileName (str)
path (str)
project (_SearchProjectRef)
repository (_SearchRepositoryRef)
versions (list[_SearchVersion])
matches (dict[str, Any])
contentId (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.PackageSearchResponse(*, count=0, results=<factory>)¶

Response from the package search API.

Parameters:

count (int)
results (list[PackageSearchResult])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.PackageSearchResult(*, name='', description='', views=<factory>, versions=<factory>, feeds=<factory>, protocolType='')¶

A single result from the package search API.

Parameters:

name (str)
description (str)
views (list[_PackageView])
versions (list[_PackageVersion])
feeds (list[_PackageFeed])
protocolType (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.SearchFacetResult(*, name, id, resultCount=0)¶

A single facet bucket in a search response.

Parameters:

name (str)
id (str)
resultCount (int)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.SearchRequest(*, searchText, skip=0, top=25, filters=None, order_by=None, includeFacets=False)¶

Shared request body for all ADO search APIs.

All four search endpoints (code, work item, wiki, package) accept this schema. Pass a SearchRequest directly to the work-item, wiki, and package search functions; use CodeSearchRequest for code search, which adds the include_snippet flag.

Parameters:

searchText (str)
skip (int)
top (int)
filters (dict[str, list[str]] | None)
order_by (list[SearchSortOption] | None)
includeFacets (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.SearchResponse(*, count=0, results=<factory>)¶

Shared response shape for all ADO search APIs.

Parameters:

count (int)
results (list[_ResultT])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.SearchSortOption(*, field, sortOrder='ASC')¶

Sort option for search requests.

Parameters:

field (str)
sortOrder (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.WikiSearchResponse(*, count=0, results=<factory>)¶

Response from the wiki search API.

Parameters:

count (int)
results (list[WikiSearchResult])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.WikiSearchResult(*, fileName='', path='', project=<factory>, wiki=<factory>, hits=<factory>, collection=<factory>)¶

A single result from the wiki search API.

Parameters:

fileName (str)
path (str)
project (_SearchProjectRef)
wiki (_SearchWikiRef)
hits (list[_SearchHit])
collection (_SearchCollectionRef)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.WorkItemSearchResponse(*, count=0, results=<factory>)¶

Response from the work item search API.

Parameters:

count (int)
results (list[WorkItemSearchResult])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.core.search.WorkItemSearchResult(*, fields=<factory>, hits=<factory>, url=None)¶

A single result from the work item search API.

Parameters:

fields (dict[str, str])
hits (list[_SearchHit])
url (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.core.search.get_search_api_call(session, org_name)¶

Build the org-scoped search API call (almsearch.dev.azure.com).

Parameters:

session (Session) – Authenticated requests.Session (from get_session() or get_bearer_session()).
org_name (str) – Organisation name (e.g. "myorg").

Returns:

ApiCall pointing at the org-level search endpoint.

Return type:

pyado.raw.core.search.post_code_search(search_api_call, request)¶

Search for code across the organisation or project.

Parameters:

search_api_call (ApiCall) – Org-scoped or project-scoped search API call (from get_search_api_call or service.make_search_project_api_call).
request (CodeSearchRequest) – Search request parameters.

Yields:

CodeSearchResult for each matching code file.

Return type:

Iterator[CodeSearchResult]

pyado.raw.core.search.post_package_search(search_api_call, request)¶

Search for packages across the organisation or project.

Parameters:

search_api_call (ApiCall) – Org-scoped or project-scoped search API call (from get_search_api_call or service.make_search_project_api_call).
request (SearchRequest) – Search request parameters.

Yields:

PackageSearchResult for each matching package.

Return type:

Iterator[PackageSearchResult]

pyado.raw.core.search.post_wiki_search(search_api_call, request)¶

Search for wiki pages across the organisation or project.

Parameters:

search_api_call (ApiCall) – Org-scoped or project-scoped search API call (from get_search_api_call or service.make_search_project_api_call).
request (SearchRequest) – Search request parameters.

Yields:

WikiSearchResult for each matching wiki page.

Return type:

Iterator[WikiSearchResult]

pyado.raw.core.search.post_work_item_search(search_api_call, request)¶

Search for work items across the organisation or project.

Parameters:

search_api_call (ApiCall) – Org-scoped or project-scoped search API call (from get_search_api_call or service.make_search_project_api_call).
request (SearchRequest) – Search request parameters.

Yields:

WorkItemSearchResult for each matching work item.

Return type:

Iterator[WorkItemSearchResult]

Hook¶

Azure DevOps service hooks subscription and publisher API wrappers.

pyado.raw.settings.hook.HookConsumerId¶: String identifier for a service-hooks consumer (e.g. "webHooks").

pyado.raw.settings.hook.HookPublisherId¶: String identifier for a service-hooks publisher (e.g. "tfs").

class pyado.raw.settings.hook.HookPublisherInfo(*, id, name, description=None)¶

Minimal representation of an ADO service-hooks publisher.

Parameters:

id (str)
name (str)
description (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.settings.hook.HookSubscriptionCreateRequest(*, publisherId, eventType, resourceVersion, consumerId, consumerActionId, publisherInputs=<factory>, consumerInputs=<factory>)¶

Request body for creating a service-hooks subscription.

Parameters:

publisherId (str)
eventType (str)
resourceVersion (str)
consumerId (str)
consumerActionId (str)
publisherInputs (dict[str, Any])
consumerInputs (dict[str, Any])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.settings.hook.HookSubscriptionId¶: UUID identifier for a service-hooks subscription.

class pyado.raw.settings.hook.HookSubscriptionInfo(*, id, status=None, publisherId, eventType, consumerId, consumerActionId, resourceVersion=None, actionDescription=None, publisherInputs=<factory>, consumerInputs=<factory>, createdDate=None, modifiedDate=None)¶

Minimal representation of an ADO service-hooks subscription.

Parameters:

id (UUID)
status (HookSubscriptionStatus | None)
publisherId (str)
eventType (str)
consumerId (str)
consumerActionId (str)
resourceVersion (str | None)
actionDescription (str | None)
publisherInputs (dict[str, Any])
consumerInputs (dict[str, Any])
createdDate (datetime | None)
modifiedDate (datetime | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.settings.hook.HookSubscriptionStatus(value)¶: Lifecycle status of a service-hooks subscription.

class pyado.raw.settings.hook.HookSubscriptionUpdateRequest(*, id, publisherId, eventType, resourceVersion, consumerId, consumerActionId, publisherInputs=<factory>, consumerInputs=<factory>)¶

Request body for updating a service-hooks subscription.

Parameters:

id (UUID)
publisherId (str)
eventType (str)
resourceVersion (str)
consumerId (str)
consumerActionId (str)
publisherInputs (dict[str, Any])
consumerInputs (dict[str, Any])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.settings.hook.delete_hook_subscription(org_api_call, subscription_id)¶

Delete a service-hooks subscription.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
subscription_id (UUID) – UUID of the subscription to delete.

Return type:

None

pyado.raw.settings.hook.get_hook_subscription(org_api_call, subscription_id)¶

Fetch a single service-hooks subscription by ID.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
subscription_id (UUID) – UUID of the subscription.

Returns:

HookSubscriptionInfo for the requested subscription.

Return type:

pyado.raw.settings.hook.iter_hook_publishers(org_api_call)¶

Iterate over all service-hooks publishers in the organisation.

Parameters:: org_api_call (ApiCall) – Organisation-level ADO API call.
Yields:: HookPublisherInfo for each publisher.
Return type:: Iterator[HookPublisherInfo]

pyado.raw.settings.hook.iter_hook_subscriptions(org_api_call)¶

Iterate over all service-hooks subscriptions in the organisation.

Parameters:: org_api_call (ApiCall) – Organisation-level ADO API call.
Yields:: HookSubscriptionInfo for each subscription.
Return type:: Iterator[HookSubscriptionInfo]

pyado.raw.settings.hook.list_hook_publishers(org_api_call)¶

Return all service-hooks publishers in the organisation as a list.

Parameters:: org_api_call (ApiCall)
Return type:: list[HookPublisherInfo]

pyado.raw.settings.hook.list_hook_subscriptions(org_api_call)¶

Return all service-hooks subscriptions in the organisation as a list.

Parameters:: org_api_call (ApiCall)
Return type:: list[HookSubscriptionInfo]

pyado.raw.settings.hook.post_hook_subscription(org_api_call, request)¶

Create a new service-hooks subscription.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
request (HookSubscriptionCreateRequest) – Create request specifying the publisher, event type, consumer, and consumer action.

Returns:

HookSubscriptionInfo for the newly created subscription.

Return type:

pyado.raw.settings.hook.put_hook_subscription(org_api_call, subscription_id, request)¶

Update an existing service-hooks subscription.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
subscription_id (UUID) – UUID of the subscription to update.
request (HookSubscriptionUpdateRequest) – Update request. The id field must match subscription_id.

Returns:

Updated HookSubscriptionInfo parsed from the API response.

Return type:

Service Endpoint¶

Azure DevOps service endpoint API wrappers.

class pyado.raw.settings.service_endpoint.ServiceEndpointAuthorization(*, scheme, parameters=<factory>)¶

Authorization block for a service endpoint create or update request.

Parameters:

scheme (str)
parameters (dict[str, Any])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.settings.service_endpoint.ServiceEndpointCreateRequest(*, name, type, url, authorization, serviceEndpointProjectReferences, description=None, isShared=False, data=None)¶

Request body for creating a service endpoint.

Parameters:

name (str)
type (str)
url (str)
authorization (ServiceEndpointAuthorization)
serviceEndpointProjectReferences (list[ServiceEndpointProjectReference])
description (str | None)
isShared (bool)
data (dict[str, Any] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.settings.service_endpoint.ServiceEndpointId¶: UUID identifier for a service endpoint (service connection).

class pyado.raw.settings.service_endpoint.ServiceEndpointInfo(*, id, name, type, url, isShared=False, isReady=False, owner=None, description=None, authorizationScheme=None)¶

Minimal representation of an ADO service endpoint.

Parameters:

id (UUID)
name (str)
type (str)
url (str)
isShared (bool)
isReady (bool)
owner (str | None)
description (str | None)
authorizationScheme (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.settings.service_endpoint.ServiceEndpointProjectReference(*, projectReference, name, description=None)¶

A project reference entry within a service endpoint’s project references list.

Parameters:

projectReference (_SeProjectRef)
name (str)
description (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.settings.service_endpoint.ServiceEndpointUpdateRequest(*, id, name, type, url, authorization, serviceEndpointProjectReferences, description=None, isShared=False, data=None)¶

Request body for updating a service endpoint.

Parameters:

id (UUID)
name (str)
type (str)
url (str)
authorization (ServiceEndpointAuthorization)
serviceEndpointProjectReferences (list[ServiceEndpointProjectReference])
description (str | None)
isShared (bool)
data (dict[str, Any] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.settings.service_endpoint.delete_service_endpoint(project_api_call, endpoint_id, project_ids)¶

Delete a service endpoint from one or more projects.

The DELETE endpoint is project-scoped and requires the projectIds query parameter listing every project the endpoint should be removed from.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
endpoint_id (UUID) – UUID of the service endpoint to delete.
project_ids (list[str]) – List of project UUIDs to remove the endpoint from.

Return type:

None

pyado.raw.settings.service_endpoint.get_service_endpoint(project_api_call, endpoint_id)¶

Fetch a single service endpoint by ID.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
endpoint_id (UUID) – UUID of the service endpoint.

Returns:

ServiceEndpointInfo for the requested endpoint.

Return type:

ServiceEndpointInfo

pyado.raw.settings.service_endpoint.iter_service_endpoints(project_api_call)¶

Iterate over all service endpoints in a project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: ServiceEndpointInfo for each service endpoint.
Return type:: Iterator[ServiceEndpointInfo]

pyado.raw.settings.service_endpoint.list_service_endpoints(project_api_call)¶

Return all service endpoints in a project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[ServiceEndpointInfo]

pyado.raw.settings.service_endpoint.patch_service_endpoint_share(org_api_call, endpoint_id, project_references)¶

Share a service endpoint with additional projects.

Sends a PATCH to the organisation-scoped endpoint, appending the given project references to the endpoint’s sharing list.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
endpoint_id (UUID) – UUID of the service endpoint to share.
project_references (list[ServiceEndpointProjectReference]) – Project references describing each project to share the endpoint with and the name to use in each project.

Return type:

None

pyado.raw.settings.service_endpoint.post_service_endpoint(org_api_call, request)¶

Create a new service endpoint.

The endpoint is created at organisation scope and shared with the projects listed in request.service_endpoint_project_references.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
request (ServiceEndpointCreateRequest) – Create request specifying the name, type, URL, authorization, and project references.

Returns:

ServiceEndpointInfo for the newly created endpoint.

Return type:

ServiceEndpointInfo

pyado.raw.settings.service_endpoint.put_service_endpoint(org_api_call, endpoint_id, request)¶

Update an existing service endpoint.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
endpoint_id (UUID) – UUID of the service endpoint to update.
request (ServiceEndpointUpdateRequest) – Update request. The id field must match endpoint_id.

Returns:

Updated ServiceEndpointInfo parsed from the API response.

Return type:

ServiceEndpointInfo

Wiki¶

Azure DevOps wiki API wrappers.

pyado.raw.overview.wiki.WikiId¶: alias of UUID

class pyado.raw.overview.wiki.WikiInfo(*, id, name, type=None, projectId=None, repositoryId=None, mappedPath=None)¶

Minimal representation of an ADO wiki.

Parameters:

id (UUID)
name (str)
type (WikiType | None)
projectId (str | None)
repositoryId (str | None)
mappedPath (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.overview.wiki.WikiPage(*, id=None, path=None, order=None, isParentPage=False, subPages=<factory>)¶

A page in an ADO wiki.

Parameters:

id (int | None)
path (str | None)
order (int | None)
isParentPage (bool)
subPages (list[WikiPage])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.overview.wiki.WikiPageAttachment(*, name)¶

An attachment reference for a wiki page.

Parameters:: name (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.overview.wiki.WikiPageDetail(*, id=None, path=None, order=None, isParentPage=False, subPages=<factory>, content=None, gitItemPath=None, remoteUrl=None)¶

A wiki page returned by the get-page or put-page endpoint.

Extends WikiPage with fields that are only present when fetching or mutating a single page (rather than listing a tree).

Parameters:

id (int | None)
path (str | None)
order (int | None)
isParentPage (bool)
subPages (list[WikiPage])
content (str | None)
gitItemPath (str | None)
remoteUrl (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.overview.wiki.WikiPageId¶: Numeric identifier for a wiki page.

pyado.raw.overview.wiki.WikiPageVersion¶: Integer version (ETag) for a wiki page, used for conflict detection.

class pyado.raw.overview.wiki.WikiType(value)¶

Type discriminator for an ADO wiki.

PROJECT_WIKI is the built-in wiki created automatically for a project. CODE_WIKI is a wiki backed by a Git repository.

pyado.raw.overview.wiki.delete_wiki_page(project_api_call, wiki_id, path, *, version)¶

Delete a wiki page by path.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
wiki_id (UUID) – UUID of the wiki.
path (str) – Page path (e.g. "/Overview").
version (int) – Page version (ETag) for conflict detection.

Returns:

WikiPageDetail for the deleted page.

Return type:

pyado.raw.overview.wiki.get_wiki_page(project_api_call, wiki_id, path, *, include_content=True)¶

Fetch a single wiki page by path.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
wiki_id (UUID) – UUID of the wiki.
path (str) – Page path (e.g. "/Overview").
include_content (bool) – Whether to include page markdown content. Defaults to True.

Returns:

WikiPageDetail for the requested page.

Return type:

pyado.raw.overview.wiki.get_wiki_page_attachments(project_api_call, wiki_id, page_id)¶

Return all attachments for a wiki page.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
wiki_id (UUID) – UUID of the wiki.
page_id (int) – Numeric identifier of the wiki page.

Returns:

List of WikiPageAttachment objects for the page.

Return type:

list[WikiPageAttachment]

pyado.raw.overview.wiki.get_wiki_pages(project_api_call, wiki_id, *, recursion_level=2)¶

Return the root page tree for a wiki.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
wiki_id (UUID) – UUID of the wiki.
recursion_level (int) – How many levels of child pages to include. Defaults to 2.

Returns:

List of WikiPage objects at the root level, each with nested sub_pages up to the requested recursion depth.

Return type:

list[WikiPage]

pyado.raw.overview.wiki.iter_wikis(project_api_call)¶

Iterate over all wikis in a project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: WikiInfo for each wiki in the project.
Return type:: Iterator[WikiInfo]

pyado.raw.overview.wiki.list_wikis(project_api_call)¶

Return all wikis in a project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[WikiInfo]

pyado.raw.overview.wiki.put_wiki_page(project_api_call, wiki_id, path, content, *, version=None)¶

Create or update a wiki page.

Pass version (the integer ETag obtained from a prior get_wiki_page() call) when updating an existing page; omit it when creating a new page.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
wiki_id (UUID) – UUID of the wiki.
path (str) – Page path (e.g. "/Overview").
content (str) – Markdown content for the page.
version (int | None) – Page version for conflict detection. Required when updating an existing page; omit for new pages.

Returns:

WikiPageDetail for the created or updated page.

Return type:

Repos¶

Git¶

Azure DevOps Git repository, commit, ref, diff, and push API wrappers.

class pyado.raw.repos.git.AccessControlEntry(*, descriptor, allow, deny)¶

A single access control entry granting or denying permissions.

Parameters:

descriptor (str)
allow (int)
deny (int)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.AccessControlList(*, token, inheritanceDeny=0, entries=<factory>)¶

An access control list for a git security token.

Parameters:

token (str)
inheritanceDeny (int)
entries (dict[str, AccessControlEntry])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.AnnotatedTagInfo(*, objectId='', name='', message='', taggedObject=None, tagId=None, url=None)¶

An ADO annotated git tag (stored object in the object database).

Parameters:

objectId (str)
name (str)
message (str)
taggedObject (_AnnotatedTagObject | None)
tagId (str | None)
url (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.AnnotatedTagRequest(*, name, message, taggedObject)¶

Request body for creating an annotated tag via the ADO git API.

Parameters:

name (str)
message (str)
taggedObject (_AnnotatedTagObject)

classmethod from_commit(name, commit_id, message)¶

Construct an annotated tag request targeting a commit.

Parameters:

name (str) – Tag name (without refs/tags/ prefix).
commit_id (str) – Commit SHA the tag should point at.
message (str) – Annotation message for the tag.

Returns:

AnnotatedTagRequest ready to pass to post_annotated_tag.

Return type:

AnnotatedTagRequest

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.git.BranchName¶: alias of str

class pyado.raw.repos.git.BranchStatistics(*, name, aheadCount, behindCount, commit=None)¶

Ahead/behind commit counts for a branch relative to its base version.

Parameters:

name (str)
aheadCount (int)
behindCount (int)
commit (GitCommitRef | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.git.ChangeTypeList¶

Field type for changeType in ADO response models. ADO may return composite flags like "edit, rename" as a single string; the BeforeValidator splits that into list[GitChangeFlag].

alias of Annotated[list[GitChangeFlag], BeforeValidator(func=_parse_change_type, json_schema_input_type=PydanticUndefined)]

class pyado.raw.repos.git.CommitDiffPage(*, changes=<factory>, allChangesIncluded=True)¶

One page of results from the diffs/commits endpoint.

Parameters:

changes (list[GitCommitChange])
allChangesIncluded (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.git.CommitId¶: alias of str

pyado.raw.repos.git.GIT_SECURITY_NAMESPACE_ID = '2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87'¶: Security namespace GUID for git repositories. Used with GET /_apis/accesscontrollists/{GIT_SECURITY_NAMESPACE_ID}.

class pyado.raw.repos.git.GitChangeFlag(value)¶

All ADO GitChangeType flag values as returned in diff and PR responses.

ADO models this as a bit-flags enum and may return composite values such as "delete, sourceRename" when a file is both removed and renamed. ChangeTypeList uses this enum after splitting the string.

class pyado.raw.repos.git.GitChangeType(value)¶

Change type values accepted in push-commit requests.

Only these four operations are valid when constructing a GitPushChange to send to ADO. For parsing response fields use ChangeTypeList which handles the full ADO flags set.

class pyado.raw.repos.git.GitCommitChange(*, changeType, item)¶

A single change entry in a commit diff.

Parameters:

changeType (Annotated[list[GitChangeFlag], BeforeValidator(func=~pyado.raw.repos.git._parse_change_type, json_schema_input_type=PydanticUndefined)])
item (GitCommitChangeItem)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitCommitChangeItem(*, path, isFolder=False)¶

The item (file or folder) affected by a single commit change.

Parameters:

path (str)
isFolder (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitCommitRef(*, commitId, comment=None, commentTruncated=False, author=None, committer=None, parents=<factory>, url=None, changeCounts=None, statuses=<factory>, workItems=<factory>)¶

A minimal git commit reference.

Parameters:

commitId (str)
comment (str | None)
commentTruncated (bool)
author (_GitUserDate | None)
committer (_GitUserDate | None)
parents (list[str])
url (str | None)
changeCounts (dict[str, int] | None)
statuses (list[GitStatus])
workItems (list[WorkItemRef])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitCommitSearchCriteria(*, itemPath=None, itemVersion=None, itemVersionType=None, top=None)¶

Search criteria for listing commits in a repository.

All fields are optional; only non-None values are forwarded as searchCriteria.* query parameters.

Parameters:

itemPath (str | None)
itemVersion (str | None)
itemVersionType (VersionDescriptorType | None)
top (int | None)

item_path¶

Filter to commits that touched this file path.

Type:: str | None

item_version¶

Version string for the item version filter.

Type:: str | None

item_version_type¶

Version type (e.g. "commit").

Type:: pyado.raw.repos.git.VersionDescriptorType | None

top¶

Maximum number of commits to return.

Type:: int | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitItem(*, objectId, gitObjectType, path, url=None, isFolder=False, isSymLink=False, commitId=None)¶

A single file or folder entry returned by the items endpoint.

Parameters:

objectId (str)
gitObjectType (GitObjectType)
path (str)
url (str | None)
isFolder (bool)
isSymLink (bool)
commitId (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitObjectType(value)¶: Git object types returned in repository item metadata.

class pyado.raw.repos.git.GitPushChange(*, changeType, item, newContent=None, sourceServerItem=None)¶

A single file change within a push commit.

Parameters:

changeType (GitChangeType)
item (GitPushChangeItem)
newContent (GitPushNewContent | None)
sourceServerItem (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitPushChangeItem(*, path)¶

An item path within a push change.

Parameters:: path (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitPushCommit(*, comment, changes)¶

A commit payload within a push request.

Parameters:

comment (str)
changes (list[GitPushChange])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitPushContentType(value)¶: Content encoding for new file content in a git push.

class pyado.raw.repos.git.GitPushNewContent(*, content, contentType=GitPushContentType.RAWTEXT)¶

New file content within a push change.

Parameters:

content (str)
contentType (GitPushContentType)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitPushRefUpdate(*, name, oldObjectId)¶

A ref update entry within a push request.

Each entry tells ADO which branch (or tag) to advance and from which commit it is currently expected to point. A single push can carry multiple entries, allowing several refs to be updated atomically in one API call — mirroring native Git push semantics (e.g. git push origin main feature/foo).

Parameters:

name (str)
oldObjectId (str)

name¶

Full ref name, e.g. "refs/heads/main".

Type:: str

old_object_id¶

The commit SHA the ref currently points to. ADO uses this as an optimistic-concurrency guard: the push is rejected if the ref has moved since you read it. Use ZERO_SHA when pushing to a ref that does not yet exist (creating a new branch).

Type:: str

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitPushRequest(*, refUpdates, commits)¶

Request body for POST .../pushes.

A push bundles two things together:

ref_updates — which branch/tag pointers to move. More than one entry is allowed; all updates land atomically in a single push event.
commits — the new commit objects to create. The same commit(s) are applied to every ref listed in ref_updates.

Parameters:

refUpdates (list[GitPushRefUpdate])
commits (list[GitPushCommit])

ref_updates¶

One entry per ref being updated. See GitPushRefUpdate for details.

Type:: list[pyado.raw.repos.git.GitPushRefUpdate]

commits¶

Ordered list of commits to include in the push. Each commit carries one or more GitPushChange file changes.

Type:: list[pyado.raw.repos.git.GitPushCommit]

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitPushResult(*, pushId, commits)¶

The result of a successful push operation.

Parameters:

pushId (int)
commits (list[GitCommitRef])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitRef(*, name, objectId)¶

A git ref (branch or tag) entry returned by the refs endpoint.

Parameters:

name (str)
objectId (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitRefFilter(*, nameFilter=None, nameContains=None)¶

Filter criteria for listing git refs.

All fields are optional; only non-None values are forwarded as query parameters.

Parameters:

nameFilter (str | None)
nameContains (str | None)

name_filter¶

Prefix filter applied by ADO, e.g. "heads/main" to match exactly refs/heads/main (ADO strips the refs/ prefix before matching).

Type:: str | None

name_contains¶

Substring filter applied to the full ref name.

Type:: str | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.git.GitRefName¶: alias of str

class pyado.raw.repos.git.GitRefUpdate(*, name, newObjectId, oldObjectId)¶

A ref update operation for creating, updating, or deleting a branch or tag.

Parameters:

name (str)
newObjectId (str)
oldObjectId (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitStatus(*, id=None, state, description=None, context=None, creationDate=None, updatedDate=None, targetUrl=None)¶

A status entry attached to a git commit.

Parameters:

id (int | None)
state (GitStatusState)
description (str | None)
context (PullRequestStatusContext | None)
creationDate (datetime | None)
updatedDate (datetime | None)
targetUrl (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.GitStatusState(value)¶: Possible state values for a git commit or pull request status.

class pyado.raw.repos.git.PullRequestStatusContext(*, name, genre=None)¶

The context identifier for a git or pull request status.

Parameters:

name (str)
genre (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.git.RecursionLevel(value)¶: Recursion depth for repository items listing.

pyado.raw.repos.git.RepositoryId¶: alias of UUID

class pyado.raw.repos.git.RepositoryInfo(*, id, name, project, defaultBranch=None, size, remoteUrl, sshUrl, webUrl, isDisabled, isInMaintenance, isFork=False, url=None, parentRepository=None)¶

Type to store repository details.

Parameters:

id (UUID)
name (str)
project (ProjectInfo)
defaultBranch (str | None)
size (Annotated[int, Ge(ge=0)])
remoteUrl (Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=['https'], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)])
sshUrl (str)
webUrl (Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=['https'], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)])
isDisabled (bool)
isInMaintenance (bool)
isFork (bool)
url (Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=['https'], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)] | None)
parentRepository (_GitRepositoryRef | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.git.RepositoryName¶: alias of str

pyado.raw.repos.git.SshUrl¶: alias of str

pyado.raw.repos.git.TagName¶: alias of str

class pyado.raw.repos.git.VersionDescriptorType(value)¶: Version type for item-version descriptors in git API queries.

pyado.raw.repos.git.ZERO_SHA: str = '0000000000000000000000000000000000000000'¶: Null commit SHA used to represent a non-existent ref (e.g. deleting a branch).

pyado.raw.repos.git.delete_git_tag(repository_api_call, name, commit_id)¶

Remove a git tag from the repository.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
name (str) – Short tag name (e.g. "v1.0"). A refs/tags/ prefix is added automatically if absent.
commit_id (str) – Current object ID of the tag (used for the optimistic- concurrency check).

Return type:

None

pyado.raw.repos.git.get_annotated_tag(repository_api_call, object_id)¶

Fetch an annotated tag by its object ID.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
object_id (str) – SHA of the annotated tag object, as returned in GitRef.object_id for annotated tags.

Returns:

AnnotatedTagInfo describing the annotated tag, including the tagged_object field that holds the actual commit SHA.

Return type:

pyado.raw.repos.git.get_commit_by_id(repository_api_call, commit_id, *, search_criteria=None)¶

Return a single commit by its SHA.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
commit_id (str) – Commit SHA string.
search_criteria (GitCommitSearchCriteria | None) – Optional search criteria model; only non-None fields are forwarded as searchCriteria.* query parameters.

Returns:

GitCommitRef for the requested commit.

Return type:

GitCommitRef

pyado.raw.repos.git.get_commit_diff_page(repository_api_call, base_commit, target_commit, *, skip=0, top=100)¶

Fetch one page of file changes between two commits.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
base_commit (str) – The base (older) commit SHA.
target_commit (str) – The target (newer) commit SHA.
skip (int) – Number of results to skip (for pagination).
top (int) – Maximum number of results to return per page.

Returns:

CommitDiffPage containing the changes and a flag indicating whether all changes were returned.

Return type:

CommitDiffPage

pyado.raw.repos.git.get_git_acl(org_api_call, project_id, repo_id=None)¶

Return the access control lists for a git repository or project.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call (must NOT include a project path segment, e.g. ApiCall(access_token=…, url="https://dev.azure.com/myorg")). The ACL endpoint is org-scoped, not project-scoped.
project_id (UUID) – Project UUID.
repo_id (UUID | None) – Repository UUID, or None to query all repositories in the project.

Returns:

List of AccessControlList objects for the requested token scope.

Return type:

list[AccessControlList]

pyado.raw.repos.git.get_repository_api_call(project_api_call, repository_id)¶

Get repository API call.

Returns:

An ApiCall pointing at the repository resource for the given ID.

Parameters:

project_api_call (ApiCall)
repository_id (UUID)

Return type:

pyado.raw.repos.git.get_repository_commits(repository_api_call, search_criteria=None)¶

Search commits in a repository.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
search_criteria (GitCommitSearchCriteria | None) – Optional search criteria model; only non-None fields are forwarded as searchCriteria.* query parameters.

Returns:

List of GitCommitRef objects matching the search criteria.

Return type:

list[GitCommitRef]

pyado.raw.repos.git.get_repository_info(repository_api_call)¶

Return details for a single repository.

Parameters:: repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
Returns:: RepositoryInfo for the repository.
Return type:: RepositoryInfo

pyado.raw.repos.git.get_repository_item(repository_api_call, path, version_descriptor_version, version_descriptor_type)¶

Return item metadata for a single file, or None if it does not exist.

Fetches only metadata (object ID, path, type) — no file content. This makes it cheap enough to use for existence checks.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
path (str) – Absolute file path within the repository.
version_descriptor_version (str) – Version string whose meaning is determined by version_descriptor_type.
version_descriptor_type (VersionDescriptorType) – Selects how version_descriptor_version is interpreted. Use COMMIT for an immutable, reproducible reference (audit trails, diffing); use BRANCH when the latest content is acceptable and mutability is not a concern; use TAG when resolving by tag name (note: lightweight tags are mutable — callers requiring true immutability should resolve the tag to a commit SHA first and use COMMIT).

Returns:

GitItem for the file, or None if it does not exist at that version.

Return type:

GitItem | None

pyado.raw.repos.git.get_repository_item_bytes(repository_api_call, path, version_descriptor_version, version_descriptor_type)¶

Fetch the raw bytes of a repository item.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
path (str) – Absolute file path within the repository.
version_descriptor_version (str) – The version string (commit SHA or branch name) passed as versionDescriptor.version.
version_descriptor_type (VersionDescriptorType) – The version type passed as versionDescriptor.versionType.

Returns:

Raw bytes of the file, or None if the item does not exist.

Return type:

bytes | None

pyado.raw.repos.git.get_repository_statistics(repository_api_call, branch)¶

Return ahead/behind statistics for a branch.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
branch (str) – Branch name (e.g. "main" or "refs/heads/main").

Returns:

BranchStatistics with ahead/behind counts and the branch HEAD commit.

Return type:

BranchStatistics

pyado.raw.repos.git.iter_refs(repository_api_call, ref_filter=None)¶

Iterate over git refs in a repository.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
ref_filter (GitRefFilter | None) – Optional filter model; only non-None fields are forwarded as query parameters.

Yields:

GitRef for each matching ref.

Return type:

Iterator[GitRef]

pyado.raw.repos.git.iter_repository_details(project_api_call)¶

Iterate over the repositories of the project.

Yields:: RepositoryInfo objects for each repository in the project.
Parameters:: project_api_call (ApiCall)
Return type:: Iterator[RepositoryInfo]

pyado.raw.repos.git.iter_repository_items(repository_api_call, scope_path='/', *, branch=None, recursion_level=RecursionLevel.ONE_LEVEL, version=None, version_type=None)¶

Iterate over items at scope_path in the repository.

Exactly one of branch or (version, version_type) should be supplied; when neither is provided the repository default branch is used by ADO.

Parameters:

repository_api_call (ApiCall) – Repository-level API call.
scope_path (str) – Directory path to list (default: root "/").
branch (str | None) – Short branch name or full ref; the refs/heads/ prefix is stripped automatically. When None and version is also None, the repository default branch is used.
recursion_level (RecursionLevel) – Depth of recursion (default: one level).
version (str | None) – Version string (commit SHA, branch name, tag name, etc.). Used together with version_type; ignored when branch is set.
version_type (VersionDescriptorType | None) – How to interpret version. Required when version is provided.

Yields:

GitItem for each file or folder entry.

Return type:

Iterator[GitItem]

pyado.raw.repos.git.iter_tags(repository_api_call)¶

Iterate over all git tags in the repository.

Parameters:: repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
Yields:: GitRef for each tag.
Return type:: Iterator[GitRef]

pyado.raw.repos.git.list_refs(repository_api_call, ref_filter=None)¶

Return all refs matching the filter as a list.

Parameters:

repository_api_call (ApiCall)
ref_filter (GitRefFilter | None)

Return type:

list[GitRef]

pyado.raw.repos.git.list_repository_details(project_api_call)¶

Return all repositories in the project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[RepositoryInfo]

pyado.raw.repos.git.list_repository_items(repository_api_call, scope_path='/', *, branch=None, recursion_level=RecursionLevel.ONE_LEVEL, version=None, version_type=None)¶

Return items at scope_path as a list.

Parameters:

repository_api_call (ApiCall)
scope_path (str)
branch (str | None)
recursion_level (RecursionLevel)
version (str | None)
version_type (VersionDescriptorType | None)

Return type:

list[GitItem]

pyado.raw.repos.git.list_tags(repository_api_call)¶

Return all tags in the repository as a list.

Parameters:: repository_api_call (ApiCall)
Return type:: list[GitRef]

pyado.raw.repos.git.make_git_acl_token(project_id, repo_id=None, branch=None)¶

Build a git ACL token for use with the security accesscontrollists API.

Token formats:

All repositories in a project: repoV2/{project_id}
Specific repository: repoV2/{project_id}/{repo_id}
Specific branch: repoV2/{project_id}/{repo_id}/refs/heads/{encoded}

Branch names are encoded with / → ^3 as required by ADO.

Parameters:

project_id (UUID) – Project UUID.
repo_id (UUID | None) – Repository UUID, or None for a project-scoped token.
branch (str | None) – Branch name (e.g. "main" or "refs/heads/main"), or None. The refs/heads/ prefix is stripped before encoding when present.

Returns:

ACL token string.

Return type:

str

pyado.raw.repos.git.make_ref_update(branch, old_commit)¶

Return a ref-update entry for a branch.

A refs/heads/ prefix is added automatically when absent. Pass ZERO_SHA as old_commit when pushing to a branch that does not yet exist.

Parameters:

branch (str) – Branch name (e.g. "main" or "refs/heads/main").
old_commit (str) – Current HEAD SHA of the branch.

Return type:

GitPushRefUpdate

pyado.raw.repos.git.post_annotated_tag(repository_api_call, request)¶

Create an annotated tag in a repository.

An annotated tag is a full git object (not just a lightweight ref pointer) and can carry a message and tagger identity. Use create_tag() for lightweight tags.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
request (AnnotatedTagRequest) – Annotated tag request specifying the name, target commit, and annotation message.

Returns:

AnnotatedTagInfo describing the newly created annotated tag.

Return type:

pyado.raw.repos.git.post_git_tag(repository_api_call, name, commit_id)¶

Create a lightweight tag pointing at an existing commit.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
name (str) – Short tag name (e.g. "v1.0"). A refs/tags/ prefix is added automatically if absent.
commit_id (str) – Commit SHA the tag should point at.

Return type:

None

pyado.raw.repos.git.post_push(repository_api_call, request)¶

Push one or more commits to a repository.

Maps directly to POST .../pushes in the Azure DevOps Git REST API.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
request (GitPushRequest) – Push request specifying the ref updates and commits.

Returns:

GitPushResult containing the new push ID and commit references.

Return type:

pyado.raw.repos.git.post_repository_refs(repository_api_call, ref_updates)¶

Apply one or more ref updates (create, update, or delete branches/tags).

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
ref_updates (list[GitRefUpdate]) – List of ref updates, each specifying a name and old/new object IDs.

Return type:

None

Pull Request¶

Azure DevOps pull request API wrappers.

pyado.raw.repos.pull_request.CommentId¶: Numeric identifier for a comment within a pull request thread.

class pyado.raw.repos.pull_request.CommitIdRef(*, commitId)¶

Minimal commit reference for use in PR request bodies.

Serialises to {"commitId": "<sha>"} as required by the ADO PATCH PR endpoint’s lastMergeSourceCommit field.

Parameters:: commitId (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.GitCherryPickRequest(*, onto, cherryPickRef, generatedRefName=None)¶

Request body for creating a git cherry-pick operation.

Parameters:

onto (str)
cherryPickRef (str)
generatedRefName (str | None)

onto¶

Target branch ref name (e.g. "refs/heads/main") to cherry-pick onto.

Type:: str

cherry_pick_ref¶

Name of the new branch to create with the cherry-picked commit applied.

Type:: str

generated_ref_name¶

Optional name for the generated ref; if omitted ADO generates one.

Type:: str | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.GitCherryPickResponse(*, cherryPickId=None, status, onto=None, cherryPickRef=None)¶

Response from the git cherry-pick endpoint.

Parameters:

cherryPickId (int | None)
status (GitCherryPickStatus)
onto (str | None)
cherryPickRef (str | None)

cherry_pick_id¶

Unique identifier for this cherry-pick operation.

Type:: int | None

status¶

Current state of the cherry-pick.

Type:: pyado.raw.repos.pull_request.GitCherryPickStatus

onto¶

The target branch ref name.

Type:: str | None

cherry_pick_ref¶

The new branch created by the cherry-pick.

Type:: str | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.GitCherryPickStatus(value)¶: Possible completion states of a git cherry-pick operation.

class pyado.raw.repos.pull_request.GitForkRef(*, name, objectId, repository)¶

Source ref information for a PR created from a fork.

Parameters:

name (str)
objectId (str)
repository (RepositoryRef)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.GitMergeRequest(*, comment=None, parents)¶

Request body for creating a git merge operation.

Parameters:

comment (str | None)
parents (list[str])

comment¶

Optional merge commit message.

Type:: str | None

parents¶

List of commit SHAs to merge (must have exactly two entries).

Type:: list[str]

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.GitMergeResponse(*, mergeOperationId=None, status, mergeCommitId=None)¶

Response from the git merge endpoint.

Parameters:

mergeOperationId (int | None)
status (GitMergeStatus)
mergeCommitId (str | None)

merge_operation_id¶

Unique identifier for this merge operation.

Type:: int | None

status¶

Current state of the merge (e.g. completed, conflicts).

Type:: pyado.raw.repos.pull_request.GitMergeStatus

merge_commit_id¶

The resulting merge commit SHA once the merge completes, or None if the merge has not yet finished.

Type:: str | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.GitMergeStatus(value)¶: Possible completion states of a git merge operation.

class pyado.raw.repos.pull_request.GitRevertRequest(*, onto, revertRef, generatedRefName=None)¶

Request body for creating a git revert operation.

Parameters:

onto (str)
revertRef (str)
generatedRefName (str | None)

onto¶

Target branch ref name (e.g. "refs/heads/main") to revert onto.

Type:: str

revert_ref¶

Name of the new branch to create with the revert commit applied.

Type:: str

generated_ref_name¶

Optional name for the generated ref.

Type:: str | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.GitRevertResponse(*, revertId=None, status, onto=None, revertRef=None)¶

Response from the git revert endpoint.

Parameters:

revertId (int | None)
status (GitRevertStatus)
onto (str | None)
revertRef (str | None)

revert_id¶

Unique identifier for this revert operation.

Type:: int | None

status¶

Current state of the revert.

Type:: pyado.raw.repos.pull_request.GitRevertStatus

onto¶

The target branch ref name.

Type:: str | None

revert_ref¶

The new branch created by the revert.

Type:: str | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.GitRevertStatus(value)¶: Possible completion states of a git revert operation.

class pyado.raw.repos.pull_request.IdentityIdRef(*, id)¶

Minimal identity reference for use in PR request bodies (id only).

Serialises to {"id": "<uuid>"} as required by ADO endpoints such as autoCompleteSetBy.

Parameters:: id (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestCompletionOptions(*, squashMerge=True, deleteSourceBranch=True, mergeStrategy=None, mergeCommitMessage=None, transitionWorkItems=False)¶

Options applied when a pull request is completed.

Parameters:

squashMerge (bool)
deleteSourceBranch (bool)
mergeStrategy (PullRequestMergeStrategy | None)
mergeCommitMessage (str | None)
transitionWorkItems (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestCreateRequest(*, title, sourceRefName, targetRefName, completionOptions, description=None, workItemRefs=None)¶

Request body for creating a new pull request.

Parameters:

title (str)
sourceRefName (str)
targetRefName (str)
completionOptions (PullRequestCompletionOptions)
description (str | None)
workItemRefs (list[WorkItemRef] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.pull_request.PullRequestId¶: alias of int

pyado.raw.repos.pull_request.PullRequestIteration¶: alias of int

class pyado.raw.repos.pull_request.PullRequestIterationChange(*, changeType, item)¶

A single file change entry from a PR iteration changes response.

Parameters:

changeType (Annotated[list[GitChangeFlag], BeforeValidator(func=~pyado.raw.repos.git._parse_change_type, json_schema_input_type=PydanticUndefined)])
item (PullRequestIterationChangeItem)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestIterationChangeItem(*, path=None, url=None)¶

A file-level item in a PR iteration change entry.

Parameters:

path (str | None)
url (AnyUrl | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestIterationContext(*, firstComparingIteration, secondComparingIteration)¶

The pair of PR iterations being compared when a thread was created.

Parameters:

firstComparingIteration (int)
secondComparingIteration (int)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestIterationRecord(*, id, createdDate=None, sourceRefCommit=None, targetRefCommit=None)¶

A single iteration (push) of a pull request.

Parameters:

id (int)
createdDate (datetime | None)
sourceRefCommit (GitCommitRef | None)
targetRefCommit (GitCommitRef | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestLabel(*, id=None, name, active=True, url=None)¶

A label (tag) associated with a pull request.

Parameters:

id (str | None)
name (str)
active (bool)
url (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.pull_request.PullRequestLabelId¶: String identifier for a pull request label.

class pyado.raw.repos.pull_request.PullRequestListItem(*, pullRequestId, repository, title=None, description=None, sourceRefName=None, targetRefName=None, createdBy=None, creationDate=None, status=None, isDraft=False, mergeStatus=None, reviewers=<factory>, labels=<factory>, closedDate=None, autoCompleteSetBy=None, mergeFailureType=None, mergeFailureMessage=None, hasMultipleMergeBases=False, url=None, mergeId=None, lastMergeSourceCommit=None, lastMergeTargetCommit=None, lastMergeCommit=None, supportsIterations=False)¶

A pull request entry as returned by the project-level PR list endpoint.

Parameters:

pullRequestId (int)
repository (RepositoryRef)
title (str | None)
description (str | None)
sourceRefName (str | None)
targetRefName (str | None)
createdBy (_IdentityRef | None)
creationDate (datetime | None)
status (PullRequestStatus | None)
isDraft (bool)
mergeStatus (PullRequestMergeStatus | None)
reviewers (list[PullRequestReviewer])
labels (list[PullRequestLabel])
closedDate (datetime | None)
autoCompleteSetBy (_IdentityRef | None)
mergeFailureType (PullRequestMergeFailureType | None)
mergeFailureMessage (str | None)
hasMultipleMergeBases (bool)
url (str | None)
mergeId (str | None)
lastMergeSourceCommit (GitCommitRef | None)
lastMergeTargetCommit (GitCommitRef | None)
lastMergeCommit (GitCommitRef | None)
supportsIterations (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestMergeFailureType(value)¶: Reason a pull request merge failed.

class pyado.raw.repos.pull_request.PullRequestMergeStatus(value)¶: Current merge status of a pull request.

class pyado.raw.repos.pull_request.PullRequestMergeStrategy(value)¶: Merge strategies available when completing a pull request.

class pyado.raw.repos.pull_request.PullRequestResponse(*, pullRequestId, repository, status, url, title, sourceRefName, targetRefName, isDraft=False, createdBy=None, creationDate=None, closedDate=None, closedBy=None, reviewers=<factory>, mergeStatus=None, mergeId=None, lastMergeSourceCommit=None, lastMergeTargetCommit=None, lastMergeCommit=None, autoCompleteSetBy=None, completionOptions=None, labels=<factory>, description=None, artifactId=None, supportsIterations=False, forkSource=None, mergeFailureType=None, mergeFailureMessage=None, hasMultipleMergeBases=False)¶

Full pull request resource, as returned by the ADO Git pull-requests API.

ADO uses a single PullRequestResponse schema for the responses of all three operations: POST (create), GET (get details), and PATCH (update). This class models that shared schema.

Reference: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/ pull-requests

Parameters:

pullRequestId (int)
repository (RepositoryRef)
status (PullRequestStatus)
url (str)
title (str)
sourceRefName (str)
targetRefName (str)
isDraft (bool)
createdBy (_IdentityRef | None)
creationDate (datetime | None)
closedDate (datetime | None)
closedBy (_IdentityRef | None)
reviewers (list[PullRequestReviewer])
mergeStatus (PullRequestMergeStatus | None)
mergeId (str | None)
lastMergeSourceCommit (GitCommitRef | None)
lastMergeTargetCommit (GitCommitRef | None)
lastMergeCommit (GitCommitRef | None)
autoCompleteSetBy (_IdentityRef | None)
completionOptions (PullRequestCompletionOptions | None)
labels (list[PullRequestLabel])
description (str | None)
artifactId (str | None)
supportsIterations (bool)
forkSource (GitForkRef | None)
mergeFailureType (PullRequestMergeFailureType | None)
mergeFailureMessage (str | None)
hasMultipleMergeBases (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestReviewer(*, id, displayName, vote=PullRequestVote.NO_VOTE, isRequired=False, hasDeclined=False, isFlagged=False)¶

A reviewer entry on a pull request.

Parameters:

id (str)
displayName (str)
vote (PullRequestVote)
isRequired (bool)
hasDeclined (bool)
isFlagged (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestReviewerRequest(*, vote=PullRequestVote.NO_VOTE, isRequired=False, isReapprove=False)¶

Request body for adding or updating a reviewer on a pull request.

Parameters:

vote (PullRequestVote)
isRequired (bool)
isReapprove (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestReviewerVoteRequest(*, vote, isReapprove=False)¶

Request body for setting a reviewer’s vote on a pull request.

Parameters:

vote (PullRequestVote)
isReapprove (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestSearchCriteria(*, status=None, creatorId=None, reviewerId=None, sourceRefName=None, targetRefName=None, repositoryId=None, pullRequestId=None, sourceVersion=None, minTime=None, maxTime=None)¶

Search criteria for listing pull requests.

All fields are optional; only non-None values are forwarded as searchCriteria.* query parameters.

Parameters:

status (PullRequestStatus | None)
creatorId (str | None)
reviewerId (str | None)
sourceRefName (str | None)
targetRefName (str | None)
repositoryId (str | None)
pullRequestId (int | None)
sourceVersion (str | None)
minTime (datetime | None)
maxTime (datetime | None)

status¶

Filter by PR lifecycle state.

Type:: pyado.raw.repos.pull_request.PullRequestStatus | None

creator_id¶

Filter by the identity UUID of the PR creator.

Type:: str | None

reviewer_id¶

Filter by the identity UUID of a reviewer.

Type:: str | None

source_ref_name¶

Filter by source branch ref name.

Type:: str | None

target_ref_name¶

Filter by target branch ref name.

Type:: str | None

repository_id¶

Filter by repository UUID.

Type:: str | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestStatus(value)¶: Lifecycle state of a pull request.

pyado.raw.repos.pull_request.PullRequestStatusId¶: Numeric identifier for a pull request status check entry.

class pyado.raw.repos.pull_request.PullRequestStatusInfo(*, id=None, state, context, description=None, targetUrl=None, iterationId=None)¶

A status item as returned by the PR statuses GET endpoint.

Parameters:

id (int | None)
state (PullRequestStatusState)
context (PullRequestStatusContext)
description (str | None)
targetUrl (AnyUrl | None)
iterationId (int | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestStatusRequest(*, context, description=None, iterationId, state, targetUrl=None)¶

Request body for posting a status item on a pull request.

Parameters:

context (PullRequestStatusContext)
description (str | None)
iterationId (int)
state (PullRequestStatusState)
targetUrl (AnyUrl | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestStatusState(value)¶: Possible state values for a PR status check.

class pyado.raw.repos.pull_request.PullRequestThreadCommentRequest(*, commentType, content, parentCommentId)¶

Type for storing a pull request comment.

Parameters:

commentType (PullRequestThreadCommentType)
content (str)
parentCommentId (int)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestThreadCommentResponse(*, id=None, content=None, commentType=None, parentCommentId, author=None, publishedDate=None, lastUpdatedDate=None, lastContentUpdatedDate=None, isDeleted=False)¶

A single comment within a PR review thread.

Parameters:

id (int | None)
content (str | None)
commentType (PullRequestThreadCommentType | None)
parentCommentId (int)
author (_IdentityRef | None)
publishedDate (datetime | None)
lastUpdatedDate (datetime | None)
lastContentUpdatedDate (datetime | None)
isDeleted (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestThreadCommentType(value)¶: ADO comment type values for PR thread comments.

class pyado.raw.repos.pull_request.PullRequestThreadContext(*, filePath, leftFileStart=None, leftFileEnd=None, rightFileStart=None, rightFileEnd=None)¶

File location context for a PR review thread.

Parameters:

filePath (str)
leftFileStart (PullRequestThreadPosition | None)
leftFileEnd (PullRequestThreadPosition | None)
rightFileStart (PullRequestThreadPosition | None)
rightFileEnd (PullRequestThreadPosition | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestThreadHistoryContext(*, changeTrackingId=None, iterationContext=None)¶

Extended PR-specific context for a review thread (iteration tracking).

Parameters:

changeTrackingId (int | None)
iterationContext (PullRequestIterationContext | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestThreadPosition(*, line, offset)¶

A position (line and offset) within a file in a PR thread context.

Parameters:

line (int)
offset (int)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestThreadRequest(*, comments, status, threadContext=None)¶

Request body for creating a new review thread on a pull request.

Parameters:

comments (list[PullRequestThreadCommentRequest])
status (PullRequestThreadStatus)
threadContext (PullRequestThreadContext | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestThreadResponse(*, id=None, status=None, comments=<factory>, threadContext=None, pullRequestThreadContext=None, publishedDate=None, lastUpdatedDate=None, isDeleted=False, properties=None)¶

A review thread on a pull request.

Parameters:

id (int | None)
status (PullRequestThreadStatus | None)
comments (list[PullRequestThreadCommentResponse])
threadContext (PullRequestThreadContext | None)
pullRequestThreadContext (PullRequestThreadHistoryContext | None)
publishedDate (datetime | None)
lastUpdatedDate (datetime | None)
isDeleted (bool)
properties (dict[str, Any] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestThreadStatus(value)¶: Possible status values for a PR review thread.

class pyado.raw.repos.pull_request.PullRequestUpdateRequest(*, title=None, description=None, status=None, isDraft=None, completionOptions=None, lastMergeSourceCommit=None, workItemRefs=None, autoCompleteSetBy=None)¶

Request body for patching a pull request.

All fields are optional; only non-None values are sent to ADO.

Parameters:

title (str | None)
description (str | None)
status (PullRequestStatus | None)
isDraft (bool | None)
completionOptions (PullRequestCompletionOptions | None)
lastMergeSourceCommit (CommitIdRef | None)
workItemRefs (list[WorkItemRef] | None)
autoCompleteSetBy (IdentityIdRef | None)

title¶

New PR title.

Type:: str | None

description¶

New PR description.

Type:: str | None

status¶

Transition the PR to this status.

Type:: pyado.raw.repos.pull_request.PullRequestStatus | None

is_draft¶

Set or clear the draft flag.

Type:: bool | None

completion_options¶

Merge strategy and post-completion options, used when completing (merging) a PR.

Type:: pyado.raw.repos.pull_request.PullRequestCompletionOptions | None

last_merge_source_commit¶

Commit ID of the source branch tip at the time of the request, used for optimistic concurrency on complete.

Type:: pyado.raw.repos.pull_request.CommitIdRef | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.repos.pull_request.PullRequestVote(value)¶: Reviewer vote values for a pull request.

class pyado.raw.repos.pull_request.RepositoryRef(*, id, name=None)¶

Minimal repository reference as returned in PR list responses.

Parameters:

id (UUID)
name (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.repos.pull_request.ThreadId¶: Numeric identifier for a pull request review thread.

pyado.raw.repos.pull_request.delete_pull_request_label(pr_api_call, label_name)¶

Remove a label from a pull request.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
label_name (str) – Name of the label to remove.

Return type:

None

pyado.raw.repos.pull_request.delete_pull_request_reviewer(pr_api_call, reviewer_id)¶

Remove a reviewer from a pull request.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
reviewer_id (str) – Identity (object) ID of the reviewer to remove.

Return type:

None

pyado.raw.repos.pull_request.get_git_cherry_pick(repository_api_call, cherry_pick_id)¶

Return the current status of a git cherry-pick operation.

Use this to poll a previously queued cherry-pick (from post_git_cherry_pick) until its status transitions away from GitCherryPickStatus.QUEUED.

Reference:: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/cherry-picks/get

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
cherry_pick_id (int) – The cherry-pick operation ID returned by post_git_cherry_pick.

Returns:

GitCherryPickResponse with the current operation status.

Return type:

pyado.raw.repos.pull_request.get_git_merge(repository_api_call, merge_operation_id)¶

Return the current status of a git merge operation.

Use this to poll a previously queued merge (from post_git_merge) until its status transitions away from GitMergeStatus.QUEUED.

Reference:: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/merges/get

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
merge_operation_id (int) – The merge operation ID returned by post_git_merge.

Returns:

GitMergeResponse with the current operation status and, once complete, the resulting merge commit ID.

Return type:

pyado.raw.repos.pull_request.get_git_revert(repository_api_call, revert_id)¶

Return the current status of a git revert operation.

Use this to poll a previously queued revert (from post_git_revert) until its status transitions away from GitRevertStatus.QUEUED.

Reference:: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/reverts/get

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
revert_id (int) – The revert operation ID returned by post_git_revert.

Returns:

GitRevertResponse with the current operation status.

Return type:

pyado.raw.repos.pull_request.get_pull_request_api_call(project_api_call, repository_id, pr_id)¶

Get pull request API call.

Returns:

An ApiCall pointing at the pull request resource.

Parameters:

project_api_call (ApiCall)
repository_id (UUID)
pr_id (int)

Return type:

pyado.raw.repos.pull_request.get_pull_request_details(pr_api_call, *, expand=None)¶

Return the full details of a single pull request.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
expand (str | None) – Optional $expand value (e.g. "labels", "reviewers"). When provided, the corresponding data is inlined in the response.

Returns:

PullRequestResponse populated with the current PR state.

Return type:

PullRequestResponse

pyado.raw.repos.pull_request.get_pull_request_iteration_changes(pr_api_call, iteration_id)¶

Return the file changes introduced by a specific PR iteration.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
iteration_id (int) – The iteration number to query.

Returns:

List of PullRequestIterationChange from the changeEntries key of the API response.

Return type:

list[PullRequestIterationChange]

pyado.raw.repos.pull_request.get_pull_request_labels_details(pr_api_call)¶

Return all labels currently set on a pull request.

Parameters:: pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
Returns:: List of PullRequestLabel objects.
Return type:: list[PullRequestLabel]

pyado.raw.repos.pull_request.get_pull_request_reviewers(pr_api_call)¶

Return all reviewers on a pull request.

Parameters:: pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
Returns:: List of PullRequestReviewer entries.
Return type:: list[PullRequestReviewer]

pyado.raw.repos.pull_request.get_pull_request_thread(pr_api_call, thread_id)¶

Return a single review thread by ID.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
thread_id (int) – Numeric ID of the thread to fetch.

Returns:

PullRequestThreadResponse for the requested thread.

Return type:

pyado.raw.repos.pull_request.iter_pull_request_commits(pr_api_call)¶

Iterate over commits included in a pull request.

Parameters:: pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
Yields:: GitCommitRef for each commit reachable from the pull request.
Return type:: Iterator[GitCommitRef]

pyado.raw.repos.pull_request.iter_pull_request_iterations(pr_api_call)¶

Iterate over the iterations (commit pushes) of a pull request.

Parameters:: pr_api_call (ApiCall) – PR-level ADO API call.
Yields:: PullRequestIterationRecord for each iteration.
Return type:: Iterator[PullRequestIterationRecord]

pyado.raw.repos.pull_request.iter_pull_request_statuses(pr_api_call)¶

Iterate over status checks posted on a pull request.

Parameters:: pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
Yields:: PullRequestStatusInfo for each status item on the PR.
Return type:: Iterator[PullRequestStatusInfo]

pyado.raw.repos.pull_request.iter_pull_request_threads(pr_api_call)¶

Iterate over all review threads on a pull request.

Note

Issues a single HTTP request — the ADO threads endpoint returns all threads in one response. The $iteration and $baseIteration query params control which diff context is included in each thread but do not act as pagination parameters.

Parameters:: pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
Yields:: PullRequestThreadResponse objects for each thread.
Return type:: Iterator[PullRequestThreadResponse]

pyado.raw.repos.pull_request.iter_pull_request_work_item_ids(pr_api_call)¶

Iterate over work items linked to a pull request.

Parameters:: pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
Yields:: WorkItemRef for each work item associated with the pull request.
Return type:: Iterator[WorkItemRef]

pyado.raw.repos.pull_request.iter_pull_requests(project_api_call, *, search_criteria=None, expand=None)¶

Iterate over pull requests in the project matching the given criteria.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
search_criteria (PullRequestSearchCriteria | None) – Optional search criteria model; only non-None fields are forwarded as searchCriteria.* query parameters.
expand (str | None) – Optional $expand value (e.g. "labels", "reviewers"). Multiple values can be combined with a comma.

Yields:

PullRequestListItem for each matching pull request.

Return type:

Iterator[PullRequestListItem]

pyado.raw.repos.pull_request.list_pull_request_commits(pr_api_call)¶

Return all commits for a pull request as a list.

Parameters:: pr_api_call (ApiCall)
Return type:: list[GitCommitRef]

pyado.raw.repos.pull_request.list_pull_request_iterations(pr_api_call)¶

Return all iterations for a pull request as a list.

Parameters:: pr_api_call (ApiCall)
Return type:: list[PullRequestIterationRecord]

pyado.raw.repos.pull_request.list_pull_request_statuses(pr_api_call)¶

Return all statuses for a pull request as a list.

Parameters:: pr_api_call (ApiCall)
Return type:: list[PullRequestStatusInfo]

pyado.raw.repos.pull_request.list_pull_request_threads(pr_api_call)¶

Return all review threads for a pull request as a list.

Parameters:: pr_api_call (ApiCall)
Return type:: list[PullRequestThreadResponse]

pyado.raw.repos.pull_request.list_pull_request_work_item_ids(pr_api_call)¶

Return all work item IDs linked to a pull request as a list.

Parameters:: pr_api_call (ApiCall)
Return type:: list[WorkItemRef]

pyado.raw.repos.pull_request.list_pull_requests(project_api_call, search_criteria=None, expand=None)¶

Return all pull requests matching the given criteria as a list.

Parameters:

project_api_call (ApiCall)
search_criteria (PullRequestSearchCriteria | None)
expand (str | None)

Return type:

list[PullRequestListItem]

pyado.raw.repos.pull_request.patch_pull_request(pr_api_call, update)¶

Update fields on a pull request.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call.
update (PullRequestUpdateRequest) – Fields to update; None values are omitted from the request.

Returns:

PullRequestResponse populated with the PR state after the update.

Return type:

PullRequestResponse

pyado.raw.repos.pull_request.patch_pull_request_thread(pr_api_call, thread_id, status)¶

Update the status of an existing PR review thread.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
thread_id (int) – Numeric ID of the thread to update.
status (PullRequestThreadStatus) – New thread status (e.g. PullRequestThreadStatus.FIXED).

Returns:

Updated PullRequestThreadResponse.

Return type:

pyado.raw.repos.pull_request.post_git_cherry_pick(repository_api_call, request)¶

Create a git cherry-pick operation.

ADO cherry-picks asynchronously — the returned status is typically GitCherryPickStatus.QUEUED immediately. Poll get_git_cherry_pick until the status transitions to COMPLETED or CONFLICTS/FAILED.

Reference:: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/cherry-picks/create

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
request (GitCherryPickRequest) – Cherry-pick request specifying the target branch and new branch name.

Returns:

GitCherryPickResponse with the initial operation status.

Return type:

pyado.raw.repos.pull_request.post_git_merge(repository_api_call, request)¶

Create a git merge operation to test whether two commits can be merged.

ADO merges asynchronously — the returned status is typically GitMergeStatus.QUEUED immediately after the call. Poll get_git_merge (or use post_git_merge with detect_renames=False) to retrieve the final result.

Reference:: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/merges/create

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
request (GitMergeRequest) – Merge request specifying the two parent commit SHAs and an optional merge commit message.

Returns:

GitMergeResponse with the initial operation status and, once complete, the resulting merge commit ID.

Return type:

pyado.raw.repos.pull_request.post_git_revert(repository_api_call, request)¶

Create a git revert operation.

ADO reverts asynchronously — the returned status is typically GitRevertStatus.QUEUED immediately. Poll get_git_revert until the status transitions to COMPLETED or CONFLICTS/FAILED.

Reference:: https://learn.microsoft.com/en-us/rest/api/azure/devops/git/reverts/create

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
request (GitRevertRequest) – Revert request specifying the target branch and new branch name.

Returns:

GitRevertResponse with the initial operation status.

Return type:

pyado.raw.repos.pull_request.post_pull_request(repository_api_call, request)¶

Create a new pull request.

Parameters:

repository_api_call (ApiCall) – Repository-level ADO API call (from get_repository_api_call).
request (PullRequestCreateRequest) – Pull request creation request specifying title, branches, and completion options.

Returns:

PullRequestResponse for the newly created pull request.

Return type:

PullRequestResponse

pyado.raw.repos.pull_request.post_pull_request_label(pr_api_call, label_name)¶

Add a label to a pull request.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
label_name (str) – Name of the label to add.

Return type:

None

pyado.raw.repos.pull_request.post_pull_request_new_thread(pr_api_call, request)¶

Create a new review thread on a pull request.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
request (PullRequestThreadRequest) – Thread creation request specifying comments, status, and optional file context.

Returns:

The created PullRequestThreadResponse.

Return type:

PullRequestThreadCommentResponse

pyado.raw.repos.pull_request.post_pull_request_status(pr_api_call, request)¶

Create a status item on the PR.

Reference: https://github.com/MicrosoftDocs/vsts-rest-api-specs/blob/master /specification/git/7.1/httpExamples/pullRequestStatuses/ POST_git_pullRequestStatuses_statusIterationInBody.json

Parameters:

pr_api_call (ApiCall)
request (PullRequestStatusRequest)

Return type:

None

pyado.raw.repos.pull_request.post_pull_request_thread_comment(pr_api_call, thread_id, comment)¶

Add a reply comment to an existing PR review thread.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call.
thread_id (int) – ID of the thread to reply to.
comment (PullRequestThreadCommentRequest) – The comment to post, including content, type, and parent ID.

Returns:

The created PullRequestThreadCommentResponse.

Return type:

pyado.raw.repos.pull_request.put_pull_request_reviewer(pr_api_call, reviewer_id, request)¶

Add or update a reviewer on a pull request.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call (from get_pull_request_api_call).
reviewer_id (str) – Identity (object) ID of the reviewer.
request (PullRequestReviewerRequest) – Reviewer request specifying vote, required flag, and reapprove flag.

Return type:

None

pyado.raw.repos.pull_request.put_pull_request_reviewer_vote(pr_api_call, reviewer_id, request)¶

Set a reviewer’s vote on a pull request.

Parameters:

pr_api_call (ApiCall) – PR-level ADO API call.
reviewer_id (str) – Identity ID of the reviewer.
request (PullRequestReviewerVoteRequest) – Vote request specifying the vote value and reapprove flag.

Return type:

None

Boards¶

Work Item¶

Azure DevOps work item, WIQL, sprint, and attachment API wrappers.

class pyado.raw.boards.work_item.ClassificationNode(*, id, identifier=None, name, path=None, structureType=None, hasChildren=None, attributes=None, children=None, url=None)¶

A classification node as returned by the ADO API.

The same schema is used for both iteration nodes (structureType == "iteration") and area nodes (structureType == "area"). The distinction matters for the attributes field:

Iterations may carry attributes.startDate / attributes.finishDate.
Areas never have attributes — the field will always be None.

Parameters:

id (int)
identifier (str | None)
name (str)
path (str | None)
structureType (ClassificationNodeType | None)
hasChildren (bool | None)
attributes (ClassificationNodeAttributes | None)
children (list[ClassificationNode] | None)
url (AnyUrl | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.ClassificationNodeAttributes(*, startDate=None, finishDate=None)¶

Date attributes of a classification node (sprint iteration).

Parameters:

startDate (str | None)
finishDate (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.boards.work_item.ClassificationNodeId¶: Numeric identifier for a classification node (area/iteration tree node).

class pyado.raw.boards.work_item.ClassificationNodePatchRequest(*, name=None, attributes=None)¶

Request body for patching a classification node (rename and/or date update).

Parameters:

name (str | None)
attributes (ClassificationNodeAttributes | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.ClassificationNodeRequest(*, name, attributes=None)¶

Request body for creating a classification node.

Parameters:

name (str)
attributes (ClassificationNodeAttributes | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.ClassificationNodeType(value)¶: Discriminates iteration nodes from area nodes in the classification tree.

class pyado.raw.boards.work_item.ClassificationNodeUrlType(value)¶

URL path segment used to select the classification node tree type.

Used as the node_type argument to get_classification_node, create_classification_node, and patch_classification_node.

class pyado.raw.boards.work_item.SprintIterationAttributes(*, startDate=None, finishDate=None, timeFrame)¶

Type to store sprint attribute information.

Parameters:

startDate (datetime | None)
finishDate (datetime | None)
timeFrame (SprintIterationTimeframe)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.boards.work_item.SprintIterationId¶: alias of UUID

class pyado.raw.boards.work_item.SprintIterationInfo(*, id, name, path, attributes, url=None)¶

Type to store sprint information.

Parameters:

id (UUID)
name (str)
path (str)
attributes (SprintIterationAttributes)
url (AnyUrl | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.boards.work_item.SprintIterationPath¶: alias of str

class pyado.raw.boards.work_item.SprintIterationTimeframe(value)¶

Relative timeframe values for filtering sprint iterations.

Only CURRENT is currently supported as a filter value by ADO. All three values appear in the timeFrame field of SprintIterationAttributes.

class pyado.raw.boards.work_item.TeamFieldValue(*, value, includeChildren)¶

A single team area-path field value.

Parameters:

value (str)
includeChildren (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.TextFormat(value)¶

Content format for multiline work item fields.

Pass as values in the multiline_fields_format argument to create_work_item / update_work_item to control how ADO renders the field’s content.

class pyado.raw.boards.work_item.WorkItemArtifactUrlPrefix(value)¶

vstfs:/// URL prefixes for work item artifact links.

Append /{artifact_id} to form a complete artifact URL: f"{WorkItemArtifactUrlPrefix.BUILD}/{build_id}".

pyado.raw.boards.work_item.WorkItemAttachmentId¶: String identifier for a work item attachment resource.

class pyado.raw.boards.work_item.WorkItemAttachmentRef(*, id, url)¶

A reference to a file attachment uploaded to ADO.

Parameters:

id (str)
url (AnyUrl)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemBatchRequest(*, ids, fields=None, expand=None)¶

Request body for fetching a batch of work items.

The ADO API accepts at most 200 IDs per call.

Parameters:

ids (list[int])
fields (list[str] | None)
expand (WorkItemExpand | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemComment(*, id, text, createdBy=None, modifiedBy=None, createdDate, modifiedDate, isDeleted=False, format=None)¶

A single comment on a work item.

Parameters:

id (int)
text (str)
createdBy (_IdentityRef | None)
modifiedBy (_IdentityRef | None)
createdDate (datetime)
modifiedDate (datetime)
isDeleted (bool)
format (TextFormat | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.boards.work_item.WorkItemCommentId¶: Numeric identifier for a work item comment.

class pyado.raw.boards.work_item.WorkItemExpand(value)¶: Expand options for work item fetch requests.

pyado.raw.boards.work_item.WorkItemField¶: alias of str

class pyado.raw.boards.work_item.WorkItemFieldInfo(*, name, referenceName, fieldType=None, readOnly=False, required=False, defaultValue=None)¶

A field definition associated with a work item type.

Parameters:

name (str)
referenceName (str)
fieldType (WorkItemFieldType | None)
readOnly (bool)
required (bool)
defaultValue (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemFieldName(value)¶

Well-known ADO work item field reference names.

Use these as keys when reading WorkItemInfo.fields or building fields dicts for create_work_item / update_work_item.

Example:

title = wi.fields[WorkItemFieldName.TITLE]
update_work_item(api, {WorkItemFieldName.STATE: "Active"})

class pyado.raw.boards.work_item.WorkItemFieldType(value)¶

Field type values returned by the WIT fields API.

These are the primitive storage types for work item fields as defined by Azure DevOps. They appear in WorkItemFieldInfo.field_type and ProjectFieldInfo.field_type.

pyado.raw.boards.work_item.WorkItemId¶: alias of int

class pyado.raw.boards.work_item.WorkItemInfo(*, id, rev=None, url=None, fields, relations=<factory>)¶

Type to store work item details.

Parameters:

id (int)
rev (int | None)
url (AnyUrl | None)
fields (dict[str, Any])
relations (list[WorkItemRelation])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemQuery(*, id, name, path=None, isFolder=False, hasChildren=False, children=<factory>, wiql=None, queryType=None)¶

A saved query or query folder returned by the WIT queries endpoint.

Parameters:

id (str)
name (str)
path (str | None)
isFolder (bool)
hasChildren (bool)
children (list[WorkItemQuery])
wiql (str | None)
queryType (WorkItemQueryType | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemQueryExpand(value)¶

Expand options for WIT query fetch requests.

These are OData $expand values used with GET wit/queries.

pyado.raw.boards.work_item.WorkItemQueryId¶: String identifier for a work item query or query folder.

class pyado.raw.boards.work_item.WorkItemQueryType(value)¶: The structural type of a WIT saved query.

class pyado.raw.boards.work_item.WorkItemRef(*, id, url=None)¶

A work item reference as returned by build and PR workitems endpoints.

Parameters:

id (int)
url (AnyUrl | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemRelation(*, rel, url, attributes=None)¶

Type to store work item relationships.

Parameters:

rel (str)
url (str)
attributes (dict[str, Any] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemRelationType(value)¶

Well-known work item relation type strings for WorkItemRelation.rel.

External artifact links (pull requests, builds, commits) use ARTIFACT_LINK with a vstfs:// URL built from WorkItemArtifactUrlPrefix.

class pyado.raw.boards.work_item.WorkItemState(value)¶

Well-known work item state values across the four built-in ADO processes.

States are process-template-specific and can be customised per project. This enum covers all states shipped with the Agile, Scrum, CMMI, and Basic templates. For projects with custom states, pass the state name as a plain string — the field accepts any str value regardless.

To define a project-specific state set that reuses standard values alongside custom ones, declare your own StrEnum and assign members from this class:

from enum import StrEnum
from pyado import WorkItemState

class AcmeState(StrEnum):
    NEW      = WorkItemState.NEW        # "New"
    ACTIVE   = WorkItemState.ACTIVE     # "Active"
    IN_SPRINT = "In Sprint"             # custom
    CLOSED   = WorkItemState.CLOSED     # "Closed"

class pyado.raw.boards.work_item.WorkItemStateCategory(value)¶

State category values for work item type states.

ADO groups work item states into five fixed categories regardless of the process template or custom state names. The category controls how the state appears in boards, backlogs, and analytics.

class pyado.raw.boards.work_item.WorkItemStateInfo(*, name, color=None, stateCategory=None, order=None)¶

A single state definition for a work item type.

Parameters:

name (str)
color (str | None)
stateCategory (WorkItemStateCategory | None)
order (int | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemTypeCategoryInfo(*, name, referenceName, defaultWorkItemType=None, workItemTypes=<factory>)¶

A work item type category (e.g. Requirements, Tasks).

Parameters:

name (str)
referenceName (str)
defaultWorkItemType (WorkItemTypeInfo | None)
workItemTypes (list[WorkItemTypeInfo])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemTypeIcon(*, id, url)¶

Icon descriptor for a work item type.

Parameters:

id (str)
url (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemTypeInfo(*, name, referenceName='', description='', color=None, icon=None, isDisabled=False)¶

Minimal representation of a work item type in a project process.

Parameters:

name (str)
referenceName (str)
description (str)
color (str | None)
icon (WorkItemTypeIcon | None)
isDisabled (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.boards.work_item.WorkItemTypeName(value)¶

Common ADO work item type names for use with System.WorkItemType.

These are the standard types shipped with the default Azure DevOps process templates (Agile, Scrum, CMMI). Custom process templates may define additional types not listed here; pass the type name as a plain string in those cases.

Example:

create_work_item(api, {
    WorkItemFieldName.WORK_ITEM_TYPE: WorkItemTypeName.BUG,
    WorkItemFieldName.TITLE: "Something is broken",
})

pyado.raw.boards.work_item.delete_classification_node(project_api_call, path, *, node_type)¶

Delete a classification node (iteration or area).

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
path (str | None) – Relative path of the node to delete (e.g. "Sprint 42"), or None for the root node.
node_type (ClassificationNodeUrlType) – Whether to delete from the iterations or areas tree.

Return type:

None

pyado.raw.boards.work_item.delete_team_iteration(team_api_call, iteration_id)¶

Remove an iteration from a team’s sprint backlog.

ADO: DELETE {team}/_apis/work/teamsettings/iterations/{iterationId}

Parameters:

team_api_call (ApiCall) – Team-scoped API call.
iteration_id (UUID) – UUID of the iteration to remove.

Return type:

None

pyado.raw.boards.work_item.delete_work_item(work_item_api_call)¶

Soft-delete a work item.

Parameters:: work_item_api_call (ApiCall) – Work-item-level ADO API call (from get_work_item_api_call).
Return type:: None

pyado.raw.boards.work_item.delete_work_item_comment(work_item_api_call, comment_id)¶

Delete a comment from a work item.

Parameters:

work_item_api_call (ApiCall) – Work-item-level ADO API call (from get_work_item_api_call).
comment_id (int) – Numeric ID of the comment to delete.

Return type:

None

pyado.raw.boards.work_item.get_classification_node(project_api_call, path=None, *, node_type, depth=1)¶

Return the classification node tree for a project.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
path (str | None) – Path within the tree (e.g. "Sprint 42" or "Team A"), or None for the root.
node_type (ClassificationNodeUrlType) – Whether to fetch from the iterations or areas tree.
depth (int) – Number of levels to fetch below the requested node (default: 1).

Returns:

ClassificationNode for the requested path.

Return type:

ClassificationNode

pyado.raw.boards.work_item.get_query_folder(project_api_call, folder_id, *, depth=1, expand=WorkItemQueryExpand.ALL)¶

Return the children of a specific WIT query folder by GUID.

Use this when you only need queries under a particular folder rather than fetching the entire tree.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
folder_id (str) – GUID of the query folder.
depth (int) – Number of levels to expand below the requested folder. 1 is sufficient when starting directly at a folder (you are already at the folder level).
expand (WorkItemQueryExpand) – OData $expand value; defaults to WorkItemQueryExpand.ALL.

Returns:

WorkItemQuery for the folder with its children populated.

Return type:

WorkItemQuery

pyado.raw.boards.work_item.get_query_tree(project_api_call, *, depth=2, expand=WorkItemQueryExpand.ALL)¶

Return the root-level WIT saved-query folders for a project.

ADO’s GET wit/queries endpoint returns a paged list of root folders (typically “My Queries” and “Shared Queries”). Use get_query_folder() to fetch a specific folder’s contents by GUID.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
depth (int) – Number of folder levels to expand below the root folders. 2 is sufficient for the standard Shared Queries structure (folder → queries). Avoid 3 or higher unless you know the project has nested sub-folders.
expand (WorkItemQueryExpand) – OData $expand value controlling which fields are populated. Defaults to WorkItemQueryExpand.ALL to include wiql and other query details.

Returns:

List of WorkItemQuery objects, one per root folder.

Return type:

list[WorkItemQuery]

Note

The depth parameter must be passed as $depth (with leading dollar sign) to be recognised by ADO. Using plain depth causes ADO to silently ignore it, returning folders with empty children even when hasChildren is true. This function always sends the correctly-spelled parameter.

pyado.raw.boards.work_item.get_team_field_values(team_api_call)¶

Return the team area-path field values configuration.

Parameters:: team_api_call (ApiCall) – Team-level ADO API call (URL includes the team segment).
Returns:: List of TeamFieldValue from the values key of the API response.
Return type:: list[TeamFieldValue]

pyado.raw.boards.work_item.get_work_item(work_item_api_call, *, expand=None)¶

Fetch a single work item by ID.

Parameters:

work_item_api_call (ApiCall) – Work-item-level ADO API call (from get_work_item_api_call).
expand (WorkItemExpand | None) – Optional expand mode; controls which extra data ADO includes in the response (e.g. WorkItemExpand.RELATIONS to include related work item links, WorkItemExpand.ALL for everything).

Returns:

WorkItemInfo for the work item.

Return type:

WorkItemInfo

pyado.raw.boards.work_item.get_work_item_api_call(project_api_call, work_item_id)¶

Get the API call for a specific work item.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
work_item_id (int) – Numeric ID of the work item.

Returns:

An ApiCall pointing at the work item resource for the given ID.

Return type:

pyado.raw.boards.work_item.get_work_item_attachment_bytes(project_api_call, attachment_id)¶

Download the raw bytes of an uploaded work item attachment.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
attachment_id (str) – The UUID string from WorkItemAttachmentRef.id.

Returns:

Raw attachment bytes.

Return type:

bytes

pyado.raw.boards.work_item.iter_sprint_iterations(team_api_call, timeframe_filter=None)¶

Iterate over the sprint iterations for a team.

Parameters:

team_api_call (ApiCall) – Team-level ADO API call (URL includes the team segment).
timeframe_filter (SprintIterationTimeframe | None) – When provided, filters by timeframe. Only SprintIterationTimeframe.CURRENT is supported by ADO.

Yields:

SprintIterationInfo objects for each iteration.

Return type:

Iterator[SprintIterationInfo]

pyado.raw.boards.work_item.iter_work_item_comments(work_item_api_call)¶

Iterate over comments on a work item.

Note

Uses cursor-based pagination via continuationToken — this is an intentional ADO WIT Comments endpoint design. The endpoint does not support the standard $skip/$top offset pagination used by other ADO endpoints.

Parameters:: work_item_api_call (ApiCall) – Work-item-level ADO API call (from get_work_item_api_call).
Yields:: WorkItemComment objects for each comment.
Return type:: Iterator[WorkItemComment]

pyado.raw.boards.work_item.iter_work_item_revisions(work_item_api_call)¶

Iterate over all historical revisions of a work item, oldest first.

Parameters:: work_item_api_call (ApiCall) – Work-item-level ADO API call (from get_work_item_api_call).
Yields:: WorkItemInfo snapshot for each revision, oldest first.
Return type:: Iterator[WorkItemInfo]

pyado.raw.boards.work_item.iter_work_item_type_categories(project_api_call)¶

Iterate over all work item type categories in a project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: WorkItemTypeCategoryInfo for each category.
Return type:: Iterator[WorkItemTypeCategoryInfo]

pyado.raw.boards.work_item.iter_work_item_type_fields(project_api_call, work_item_type)¶

Iterate over field definitions for a specific work item type.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
work_item_type (str) – Work item type reference name (e.g. "Bug").

Yields:

WorkItemFieldInfo for each field.

Return type:

Iterator[WorkItemFieldInfo]

pyado.raw.boards.work_item.iter_work_item_type_states(project_api_call, work_item_type)¶

Iterate over state definitions for a specific work item type.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
work_item_type (str) – Work item type reference name (e.g. "Bug").

Yields:

WorkItemStateInfo for each state.

Return type:

Iterator[WorkItemStateInfo]

pyado.raw.boards.work_item.iter_work_item_types(project_api_call)¶

Iterate over all work item types in a project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: WorkItemTypeInfo for each work item type.
Return type:: Iterator[WorkItemTypeInfo]

pyado.raw.boards.work_item.list_sprint_iterations(team_api_call, timeframe_filter=None)¶

Return all sprint iterations for a team as a list.

Parameters:

team_api_call (ApiCall)
timeframe_filter (SprintIterationTimeframe | None)

Return type:

list[SprintIterationInfo]

pyado.raw.boards.work_item.list_work_item_comments(work_item_api_call)¶

Return all comments on a work item as a list.

Parameters:: work_item_api_call (ApiCall)
Return type:: list[WorkItemComment]

pyado.raw.boards.work_item.list_work_item_revisions(work_item_api_call)¶

Return all revisions of a work item as a list.

Parameters:: work_item_api_call (ApiCall)
Return type:: list[WorkItemInfo]

pyado.raw.boards.work_item.list_work_item_type_categories(project_api_call)¶

Return all work item type categories in a project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[WorkItemTypeCategoryInfo]

pyado.raw.boards.work_item.list_work_item_type_fields(project_api_call, work_item_type)¶

Return the field definitions for a specific work item type as a list.

Parameters:

project_api_call (ApiCall)
work_item_type (str)

Return type:

list[WorkItemFieldInfo]

pyado.raw.boards.work_item.list_work_item_type_states(project_api_call, work_item_type)¶

Return the state definitions for a specific work item type as a list.

Parameters:

project_api_call (ApiCall)
work_item_type (str)

Return type:

list[WorkItemStateInfo]

pyado.raw.boards.work_item.list_work_item_types(project_api_call)¶

Return all work item types in a project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[WorkItemTypeInfo]

pyado.raw.boards.work_item.patch_classification_node(project_api_call, path, request, *, node_type)¶

Update a classification node (rename and/or change dates).

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
path (str | None) – Path of the node to update (e.g. "Sprint 42" or "Team A"), or None for the root node.
request (ClassificationNodePatchRequest) – Patch body carrying the optional new name and/or date attributes.
node_type (ClassificationNodeUrlType) – Whether to patch in the iterations or areas tree.

Returns:

Updated ClassificationNode from the ADO API.

Return type:

ClassificationNode

pyado.raw.boards.work_item.patch_recycle_bin_work_item(project_api_call, work_item_id)¶

Restore a soft-deleted work item from the Recycle Bin.

ADO: PATCH {project}/_apis/wit/recycleBin/{id}

Parameters:

project_api_call (ApiCall) – Project-level API call.
work_item_id (int) – Numeric ID of the work item to restore.

Return type:

None

pyado.raw.boards.work_item.patch_work_item(work_item_api_call, json_patches)¶

Update a work item via JSON Patch operations.

Parameters:

work_item_api_call (ApiCall) – Work-item-level ADO API call (from get_work_item_api_call).
json_patches (list[JsonPatchAdd | JsonPatchRemove]) – JSON Patch operations list describing the fields to update.

Returns:

Updated WorkItemInfo.

Return type:

WorkItemInfo

pyado.raw.boards.work_item.patch_work_item_comment(work_item_api_call, comment_id, text)¶

Update the text of an existing work item comment.

Parameters:

work_item_api_call (ApiCall) – Work-item-level ADO API call (from get_work_item_api_call).
comment_id (int) – Numeric ID of the comment to update.
text (str) – New comment body text.

Returns:

The updated WorkItemComment.

Return type:

pyado.raw.boards.work_item.post_classification_node(project_api_call, request, parent_path=None, *, node_type)¶

Create a classification node under a parent path.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
request (ClassificationNodeRequest) – Request body carrying the node name and optional date attributes.
parent_path (str | None) – Path of the parent node within the tree, or None to create at the root.
node_type (ClassificationNodeUrlType) – Whether to create in the iterations or areas tree.

Returns:

The newly created ClassificationNode.

Return type:

ClassificationNode

pyado.raw.boards.work_item.post_team_iteration(team_api_call, iteration_id)¶

Assign an existing iteration to a team.

Parameters:

team_api_call (ApiCall) – Team-level ADO API call (URL includes the team segment).
iteration_id (UUID) – UUID of the iteration to assign.

Return type:

None

pyado.raw.boards.work_item.post_wiql(project_api_call, query)¶

Execute a WIQL query and return work item references.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
query (str) – WIQL query string.

Returns:

List of WorkItemRef objects.

Return type:

list[WorkItemRef]

pyado.raw.boards.work_item.post_work_item(project_api_call, ticket_type, json_patches)¶

Create a new work item of the given type.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
ticket_type (str) – Work item type name (e.g. "Task", "Bug").
json_patches (list[JsonPatchAdd | JsonPatchRemove]) – JSON Patch operations list describing the fields and relations for the new work item.

Returns:

The created WorkItemInfo.

Return type:

WorkItemInfo

pyado.raw.boards.work_item.post_work_item_attachment_upload(project_api_call, filename, content)¶

Upload a file as a work item attachment.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
filename (str) – Name of the file as it will appear in ADO.
content (bytes) – Raw bytes of the file to upload.

Returns:

WorkItemAttachmentRef with the ID and URL of the uploaded attachment.

Return type:

WorkItemAttachmentRef

pyado.raw.boards.work_item.post_work_item_comment(work_item_api_call, text, *, comment_format=TextFormat.HTML)¶

Add a comment to a work item.

Parameters:

work_item_api_call (ApiCall) – Work-item-level ADO API call (from get_work_item_api_call).
text (str) – Comment text.
comment_format (TextFormat) – Content format (default: HTML). When MARKDOWN, ADO renders the markdown server-side.

Returns:

The created WorkItemComment.

Return type:

pyado.raw.boards.work_item.post_work_items_batch(project_api_call, request)¶

Fetch a batch of work items.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
request (WorkItemBatchRequest) – Batch request specifying IDs and optional field or expand settings.

Returns:

List of WorkItemInfo objects.

Return type:

list[WorkItemInfo]

Pipelines¶

Build¶

Azure DevOps Build API wrappers: builds, timelines, artifacts, pipeline defs.

class pyado.raw.pipelines.build.BuildArtifact(*, id, name, source=None, resource)¶

An artifact produced by a build.

Parameters:

id (int)
name (str)
source (str | None)
resource (BuildArtifactResource)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.build.BuildArtifactId¶: Numeric identifier for a build artifact.

class pyado.raw.pipelines.build.BuildArtifactResource(*, type, url, downloadUrl=None, data=None)¶

The downloadable resource backing a build artifact.

Parameters:

type (str)
url (str)
downloadUrl (str | None)
data (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.BuildAttemptInfo(*, attempt, timelineId, recordId)¶

Type to store build attempt details.

Parameters:

attempt (int)
timelineId (UUID)
recordId (UUID)

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.BuildDetails(*, id, buildNumber, status, result=None, queueTime=None, startTime=None, finishTime=None, lastChangedDate=None, sourceBranch, sourceVersion, definition, requestedBy, requestedFor=None, reason=None, priority=None, url=None, tags=<factory>, parameters=None, repository=None, project=None, triggerInfo=None, orchestrationPlan=None, logs=None, deleted=False, queuePosition=None, retainedByRelease=False)¶

Type to store top-level build (pipeline run) details.

Parameters:

id (int)
buildNumber (str)
status (BuildStatus)
result (BuildResult | None)
queueTime (datetime | None)
startTime (datetime | None)
finishTime (datetime | None)
lastChangedDate (datetime | None)
sourceBranch (str)
sourceVersion (str)
definition (_BuildDefinitionRef)
requestedBy (_IdentityRef)
requestedFor (_IdentityRef | None)
reason (BuildReason | None)
priority (BuildPriority | None)
url (str | None)
tags (list[str])
parameters (str | None)
repository (_BuildRepository | None)
project (ProjectInfo | None)
triggerInfo (dict[str, str] | None)
orchestrationPlan (_BuildOrchestrationPlan | None)
logs (BuildLogInfo | None)
deleted (bool)
queuePosition (int | None)
retainedByRelease (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.BuildExpand(value)¶: Expand options for build fetch requests.

pyado.raw.pipelines.build.BuildId¶: alias of int

class pyado.raw.pipelines.build.BuildIssue(*, category=None, data=None, message, type)¶

Type for build message issues.

Parameters:

category (str | None)
data (dict[str, str] | None)
message (str)
type (BuildIssueType)

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.BuildIssueType(value)¶: Severity types for a build issue.

pyado.raw.pipelines.build.BuildLogId¶: alias of int

class pyado.raw.pipelines.build.BuildLogInfo(*, id, type, url, lineCount=None, createdOn=None, lastChangedOn=None)¶

Type to store build log details.

Parameters:

id (int)
type (BuildLogType)
url (Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=['https'], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)])
lineCount (int | None)
createdOn (datetime | None)
lastChangedOn (datetime | None)

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.BuildLogType(value)¶: Log container types returned by the build log endpoint.

class pyado.raw.pipelines.build.BuildPriority(value)¶: Queue priority for a build run.

class pyado.raw.pipelines.build.BuildQueueRequest(*, definitionId, sourceBranch=None, sourceVersion=None, parameters=None)¶

Request body for queueing a new build run.

ADO requires parameters to be serialised as a JSON string rather than an object, which is handled automatically by the field serializer. ADO requires definition to be a nested object; definition_id is serialised automatically as {"definition": {"id": ...}}.

Parameters:

definitionId (int)
sourceBranch (str | None)
sourceVersion (str | None)
parameters (dict[str, str] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.BuildReason(value)¶: Why a build was triggered.

class pyado.raw.pipelines.build.BuildRecordInfo(*, attempt, changeId, currentOperation, details, errorCount=None, finishTime, id, identifier, issues=None, lastModified, log, name, order=None, refName, parentId, percentComplete, previousAttempts, queueId=None, result, resultCode, startTime, state, task, type, url, warningCount=None, workerName)¶

Type to store build task details.

Parameters:

attempt (int)
changeId (int | None)
currentOperation (str | None)
details (TimelineReference | None)
errorCount (int | None)
finishTime (datetime | None)
id (UUID)
identifier (str | None)
issues (list[BuildIssue] | None)
lastModified (datetime)
log (BuildLogInfo | None)
name (str)
order (int | None)
refName (str | None)
parentId (UUID | None)
percentComplete (int | None)
previousAttempts (list[BuildAttemptInfo])
queueId (int | None)
result (BuildRecordResult | None)
resultCode (str | None)
startTime (datetime | None)
state (BuildRecordState)
task (BuildRecordTypeInfo | None)
type (BuildRecordType)
url (AnyUrl | None)
warningCount (int | None)
workerName (str | None)

model_config = {'alias_generator': <function to_camel>, 'extra': 'ignore', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.BuildRecordResult(value)¶: Outcome values for a single timeline record within a build.

class pyado.raw.pipelines.build.BuildRecordState(value)¶: Lifecycle state values for a single timeline record within a build.

class pyado.raw.pipelines.build.BuildRecordType(value)¶: Timeline record types present in a build’s timeline.

class pyado.raw.pipelines.build.BuildRecordTypeInfo(*, id, name, version)¶

Type to store build task type details.

Parameters:

id (UUID)
name (str)
version (str)

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.BuildResult(value)¶: Possible outcome values for a completed build.

class pyado.raw.pipelines.build.BuildSearchCriteria(*, definitionId=None, statusFilter=None, branchName=None, top=None)¶

Search criteria for listing build runs.

All fields are optional; only non-None values are forwarded as query parameters to the builds list endpoint.

Parameters:

definitionId (int | None)
statusFilter (BuildStatus | None)
branchName (str | None)
top (int | None)

definition_id¶

Filter to a specific pipeline definition ID.

Type:: int | None

status_filter¶

Filter by build status.

Type:: pyado.raw.pipelines.build.BuildStatus | None

branch_name¶

Filter by source branch ref name.

Type:: str | None

top¶

Maximum number of results to return.

Type:: int | None

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.BuildStatus(value)¶: Possible build status values used to filter or inspect a build.

pyado.raw.pipelines.build.PipelineDefinitionId¶: Numeric identifier for a pipeline (build) definition.

class pyado.raw.pipelines.build.PipelineDefinitionInfo(*, id, name, path, queueStatus, revision, url=None, uri=None, type=None, quality=None, createdDate=None, authoredBy=None, project=None, queue=None, drafts=<factory>)¶

Type to store pipeline definition details.

Parameters:

id (int)
name (str)
path (str)
queueStatus (PipelineQueueStatus)
revision (int)
url (Annotated[HttpUrl, UrlConstraints(max_length=2048, allowed_schemes=['https'], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)] | None)
uri (str | None)
type (PipelineDefinitionType | None)
quality (PipelineDefinitionQuality | None)
createdDate (datetime | None)
authoredBy (_IdentityRef | None)
project (ProjectInfo | None)
queue (dict[str, object] | None)
drafts (list[dict[str, object]])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.build.PipelineDefinitionQuality(value)¶: Whether a pipeline definition is a draft or a published definition.

class pyado.raw.pipelines.build.PipelineDefinitionType(value)¶: Pipeline definition type.

class pyado.raw.pipelines.build.PipelineQueueStatus(value)¶: Whether new builds can be queued for a pipeline definition.

pyado.raw.pipelines.build.PlanId¶: alias of UUID

pyado.raw.pipelines.build.QueueId¶: alias of int

pyado.raw.pipelines.build.TaskId¶: alias of UUID

pyado.raw.pipelines.build.TimelineId¶: alias of UUID

class pyado.raw.pipelines.build.TimelineReference(*, changeId, id, url)¶

A reference to a sub-timeline within a build timeline record.

Parameters:

changeId (int)
id (UUID)
url (AnyUrl)

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.build.delete_build_tag(build_api_call, tag)¶

Remove a tag from a build.

Note

Returns the updated tag list (not None) — this is intentional ADO behaviour. The DELETE endpoint always returns the full list of remaining tags after the operation.

Parameters:

build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
tag (str) – The tag string to remove.

Returns:

Updated list of all remaining tags on the build.

Return type:

list[str]

pyado.raw.pipelines.build.get_build_api_call(project_api_call, build_id)¶

Get the API call for a specific build run.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
build_id (int) – Numeric ID of the build run.

Returns:

An ApiCall pointing at the build resource for the given build ID.

Return type:

pyado.raw.pipelines.build.get_build_artifact_bytes(build_api_call, artifact)¶

Download the bytes of a build artifact.

Uses the downloadUrl from artifact.resource. Returns None when the artifact has no download URL (e.g. pipeline artifacts that require a separate API call to locate).

Parameters:

build_api_call (ApiCall) – Build-level API call (for auth and timeout).
artifact (BuildArtifact) – BuildArtifact whose bytes to download.

Returns:

Raw artifact bytes, or None if no download URL is available.

Raises:

RuntimeError – If the HTTP response indicates an error.

Return type:

bytes | None

pyado.raw.pipelines.build.get_build_details(build_api_call, *, expand=None)¶

Return the top-level details of a build run.

Parameters:

build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
expand (BuildExpand | None) – Optional $expand value to request additional fields.

Returns:

BuildDetails for the build.

Return type:

pyado.raw.pipelines.build.get_build_log(build_api_call, log_id)¶

Return the plain-text content of a build log.

Parameters:

build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
log_id (int) – Numeric log ID from a BuildLogInfo record.

Returns:

Log content as a decoded UTF-8 string.

Return type:

str

pyado.raw.pipelines.build.iter_build_artifacts(build_api_call)¶

Iterate over artifacts produced by a build.

Note

Issues a single HTTP request — the ADO artifacts endpoint returns all artifacts in one response and does not support pagination parameters.

Parameters:: build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
Yields:: BuildArtifact for each artifact attached to the build.
Return type:: Iterator[BuildArtifact]

pyado.raw.pipelines.build.iter_build_logs(build_api_call)¶

Iterate over all log entries for a build.

Calls GET build/builds/{id}/logs, which returns metadata for every log container associated with the build.

Parameters:: build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
Yields:: BuildLogInfo for each log entry, in ADO-returned order.
Return type:: Iterator[BuildLogInfo]

pyado.raw.pipelines.build.iter_build_tags(build_api_call)¶

Iterate over tags attached to a build.

Note

Issues a single HTTP request — the ADO tags endpoint returns all tags in one response and does not support pagination parameters.

Parameters:: build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
Yields:: Each tag string associated with the build.
Return type:: Iterator[str]

pyado.raw.pipelines.build.iter_build_work_item_ids(build_api_call)¶

Iterate over work items linked to a build.

Parameters:: build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
Yields:: WorkItemRef for each work item associated with the build.
Return type:: Iterator[WorkItemRef]

pyado.raw.pipelines.build.iter_builds(project_api_call, *, search_criteria=None)¶

Iterate over build runs in the project.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
search_criteria (BuildSearchCriteria | None) – Optional search criteria model; only non-None fields are forwarded as query parameters.

Yields:

BuildDetails for each matching build run.

Return type:

Iterator[BuildDetails]

pyado.raw.pipelines.build.iter_pipeline_definitions(project_api_call, *, name_filter=None)¶

Iterate over pipeline definitions in the project.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
name_filter (str | None) – Optional name substring filter.

Yields:

PipelineDefinitionInfo for each matching definition.

Return type:

Iterator[PipelineDefinitionInfo]

pyado.raw.pipelines.build.iter_timeline_records(build_api_call)¶

Iterate over task records in the build timeline.

Note

Issues a single HTTP request — the ADO timeline endpoint returns a single Timeline object containing all records at once and does not support pagination parameters.

Reference: https://github.com/MicrosoftDocs/vsts-rest-api-specs/blob/master /specification/build/7.1/build.json#L2478

Parameters:: build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
Yields:: BuildRecordInfo objects for each record in the timeline.
Return type:: Iterator[BuildRecordInfo]

pyado.raw.pipelines.build.iter_work_items_between_builds(project_api_call, from_build_id, to_build_id, *, top=None)¶

Iterate over work items associated with builds in the range (from, to].

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
from_build_id (int) – The ID of the earlier build (exclusive lower bound).
to_build_id (int) – The ID of the later build (inclusive upper bound).
top (int | None) – Maximum number of work items to return.

Yields:

WorkItemRef for each work item in the build range.

Return type:

Iterator[WorkItemRef]

pyado.raw.pipelines.build.list_build_artifacts(build_api_call)¶

Return all artifacts for a build as a list.

Parameters:: build_api_call (ApiCall)
Return type:: list[BuildArtifact]

pyado.raw.pipelines.build.list_build_logs(build_api_call)¶

Return all log entries for a build as a list.

Parameters:: build_api_call (ApiCall)
Return type:: list[BuildLogInfo]

pyado.raw.pipelines.build.list_build_tags(build_api_call)¶

Return all tags for a build as a list.

Parameters:: build_api_call (ApiCall)
Return type:: list[str]

pyado.raw.pipelines.build.list_build_work_item_ids(build_api_call)¶

Return all work item IDs for a build as a list.

Parameters:: build_api_call (ApiCall)
Return type:: list[WorkItemRef]

pyado.raw.pipelines.build.list_builds(project_api_call, *, search_criteria=None)¶

Return all builds matching the given criteria as a list.

Parameters:

project_api_call (ApiCall)
search_criteria (BuildSearchCriteria | None)

Return type:

list[BuildDetails]

pyado.raw.pipelines.build.list_pipeline_definitions(project_api_call, *, name_filter=None)¶

Return all pipeline definitions as a list.

Parameters:

project_api_call (ApiCall)
name_filter (str | None)

Return type:

list[PipelineDefinitionInfo]

pyado.raw.pipelines.build.list_timeline_records(build_api_call)¶

Return all timeline records for a build as a list.

Parameters:: build_api_call (ApiCall)
Return type:: list[BuildRecordInfo]

pyado.raw.pipelines.build.list_work_items_between_builds(project_api_call, from_build_id, to_build_id, *, top=None)¶

Return all work items between two builds as a list.

Parameters:

project_api_call (ApiCall)
from_build_id (int)
to_build_id (int)
top (int | None)

Return type:

list[WorkItemRef]

pyado.raw.pipelines.build.patch_build(build_api_call, status)¶

Update the status of a build run.

Parameters:

build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
status (BuildStatus) – New build status to set (e.g. "cancelling").

Returns:

BuildDetails reflecting the updated build state.

Return type:

pyado.raw.pipelines.build.post_build(project_api_call, request)¶

Queue a new build run for a pipeline definition.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
request (BuildQueueRequest) – Build queue request specifying the definition and options.

Returns:

BuildDetails for the queued build run.

Return type:

pyado.raw.pipelines.build.post_build_tag(build_api_call, tag)¶

Add a tag to a build.

Parameters:

build_api_call (ApiCall) – Build-level ADO API call (from get_build_api_call).
tag (str) – The tag string to add.

Returns:

Updated list of all tags on the build.

Return type:

list[str]

Pipeline¶

Azure DevOps Pipelines REST API and distributed task wrappers.

Covers the newer /pipelines endpoints (pipeline runs, pipeline listing) as well as the distributed task plane (plans, timelines, job feeds, job events, and environment approvals).

pyado.raw.pipelines.pipeline.ApprovalId¶: String identifier for a pipeline approval gate.

class pyado.raw.pipelines.pipeline.JobEventName(value)¶: Event name sent to the job completion endpoint.

class pyado.raw.pipelines.pipeline.JobEventPayload(*, name, taskId, jobId, result)¶

Payload for the job event (task completed) endpoint.

Parameters:

name (JobEventName)
taskId (UUID)
jobId (UUID)
result (JobEventResult)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.pipeline.JobEventResult(value)¶: Outcome value reported with a job completion event.

class pyado.raw.pipelines.pipeline.JobFeedPayload(*, value, count)¶

Payload for the job feed (append timeline record feed) endpoint.

Parameters:

value (list[str])
count (int)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.pipeline.JobId¶: alias of UUID

class pyado.raw.pipelines.pipeline.PipelineApproval(*, id, status, steps=<factory>, instructions=None, blockedApprovers=<factory>, minRequiredApprovers=1, createdOn=None)¶

A pipeline environment approval request.

Parameters:

id (str)
status (PipelineApprovalStatus)
steps (list[PipelineApprovalStep])
instructions (str | None)
blockedApprovers (list[_IdentityRef])
minRequiredApprovers (int)
createdOn (datetime | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.pipeline.PipelineApprovalStatus(value)¶: Possible status values for a pipeline approval step.

class pyado.raw.pipelines.pipeline.PipelineApprovalStep(*, assignedApprover, status, actualApprover=None, comment=None)¶

A single step within a pipeline approval.

Parameters:

assignedApprover (_IdentityRef)
status (PipelineApprovalStatus)
actualApprover (_IdentityRef | None)
comment (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.pipeline.PipelineApprovalUpdateRequest(*, approvalId, status, comment='')¶

Request body item for patching a pipeline environment approval.

Parameters:

approvalId (str)
status (PipelineApprovalStatus)
comment (str)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.pipeline.PipelineId¶: alias of int

class pyado.raw.pipelines.pipeline.PipelineInfo(*, id, revision, name, folder, url)¶

A pipeline definition returned by the Pipelines REST API.

Parameters:

id (int)
revision (int)
name (str)
folder (str)
url (AnyUrl)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.pipeline.PipelinePermissionEntry(*, authorized, authorizedBy=None, authorizedOn=None, id=None)¶

Authorization state for a single pipeline or the all-pipelines wildcard.

Parameters:

authorized (bool)
authorizedBy (_IdentityRef | None)
authorizedOn (datetime | None)
id (int | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.pipeline.PipelineResourcePermissions(*, resource=None, allPipelines=None, pipelines=<factory>)¶

Resource-level permissions response from the pipelinepermissions endpoint.

Parameters:

resource (_PipelineResourceRef | None)
allPipelines (PipelinePermissionEntry | None)
pipelines (list[PipelinePermissionEntry])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.pipeline.PipelineResourceType(value)¶: Resource type values for the pipeline resource permissions endpoint.

pyado.raw.pipelines.pipeline.PipelineRunId¶: Numeric identifier for a pipeline run instance.

class pyado.raw.pipelines.pipeline.PipelineRunInfo(*, id, name, state, result=None, pipeline, createdDate, finishedDate=None, url, templateParameters=None, variables=None, finalYaml=None)¶

A pipeline run returned by the Pipelines REST API.

Parameters:

id (int)
name (str)
state (PipelineRunState)
result (PipelineRunResult | None)
pipeline (PipelineInfo)
createdDate (datetime)
finishedDate (datetime | None)
url (AnyUrl)
templateParameters (dict[str, str] | None)
variables (dict[str, VariableInfo] | None)
finalYaml (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.pipeline.PipelineRunRequest(*, resources=None, variables=None, templateParameters=None, stagesToSkip=None)¶

Request body for triggering a pipeline run.

Parameters:

resources (dict[str, Any] | None)
variables (dict[str, VariableInfo] | None)
templateParameters (dict[str, str] | None)
stagesToSkip (list[str] | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.pipeline.PipelineRunResult(value)¶: Possible outcome values for a completed pipeline run.

class pyado.raw.pipelines.pipeline.PipelineRunState(value)¶: Possible lifecycle states of a pipeline run.

class pyado.raw.pipelines.pipeline.TimelineRecordsUpdatePayload(*, count, value)¶

Payload for the update timeline records endpoint.

Parameters:

count (int)
value (list[BuildRecordInfo])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.pipeline.get_job_api_call(project_api_call, hub_name, plan_id, timeline_id, job_id)¶

Get job API call.

Returns:

An ApiCall pointing at the job record resource.

Parameters:

project_api_call (ApiCall)
hub_name (str)
plan_id (UUID)
timeline_id (UUID)
job_id (UUID)

Return type:

pyado.raw.pipelines.pipeline.get_log_api_call(project_api_call, hub_name, plan_id, log_id)¶

Get job log API call.

Returns:

An ApiCall pointing at the job log resource.

Parameters:

project_api_call (ApiCall)
hub_name (str)
plan_id (UUID)
log_id (int)

Return type:

pyado.raw.pipelines.pipeline.get_pipeline(project_api_call, pipeline_id, *, pipeline_version=None)¶

Fetch a single pipeline by ID.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
pipeline_id (int) – The numeric pipeline ID.
pipeline_version (int | None) – Optional specific revision to fetch.

Returns:

PipelineInfo for the requested pipeline.

Return type:

PipelineInfo

pyado.raw.pipelines.pipeline.get_pipeline_run(project_api_call, pipeline_id, run_id)¶

Fetch a single pipeline run by ID.

The run ID is identical to the build ID — the same entity is exposed via both the Pipelines API (/pipelines/{id}/runs/{runId}) and the Build API (/build/builds/{buildId}).

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
pipeline_id (int) – The numeric pipeline ID.
run_id (int) – The numeric run (build) ID.

Returns:

PipelineRunInfo for the requested run.

Return type:

PipelineRunInfo

pyado.raw.pipelines.pipeline.get_plan_api_call(project_api_call, hub_name, plan_id)¶

Get plan API call.

Returns:

An ApiCall pointing at the distributed task plan resource.

Parameters:

project_api_call (ApiCall)
hub_name (str)
plan_id (UUID)

Return type:

pyado.raw.pipelines.pipeline.get_timeline_api_call(project_api_call, hub_name, plan_id, timeline_id)¶

Get timeline API call.

Returns:

An ApiCall pointing at the timeline resource.

Parameters:

project_api_call (ApiCall)
hub_name (str)
plan_id (UUID)
timeline_id (UUID)

Return type:

PipelineResourcePermissions

pyado.raw.pipelines.pipeline.iter_approvals(project_api_call, state=None, pipeline_run_ids=None)¶

Iterate over pipeline approvals in the project.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
state (PipelineApprovalStatus | None) – Optional status filter. If None, all approvals are returned.
pipeline_run_ids (list[int] | None) – Optional list of pipeline run IDs (identical to build IDs for Pipelines v2 runs) to restrict results to approvals belonging to those runs.

Yields:

PipelineApproval for each matching approval.

Return type:

Iterator[PipelineApproval]

pyado.raw.pipelines.pipeline.iter_pipeline_runs(project_api_call, pipeline_id, *, top=None)¶

Iterate over runs for a pipeline.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
pipeline_id (int) – The numeric pipeline ID.
top (int | None) – Maximum number of runs to return. When None the API default is used.

Yields:

PipelineRunInfo for each run, newest first.

Return type:

Iterator[PipelineRunInfo]

pyado.raw.pipelines.pipeline.iter_pipelines(project_api_call, *, order_by=None)¶

Iterate over pipelines in the project using the Pipelines REST API.

This uses the newer /pipelines endpoint (distinct from the Build Definitions API at /build/definitions).

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
order_by (str | None) – Optional sort expression (e.g. "name asc").

Yields:

PipelineInfo for each pipeline.

Return type:

Iterator[PipelineInfo]

pyado.raw.pipelines.pipeline.list_approvals(project_api_call)¶

Return all pending approvals as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[PipelineApproval]

pyado.raw.pipelines.pipeline.list_pipeline_runs(project_api_call, pipeline_id, *, top=None)¶

Return all runs for a pipeline as a list.

Parameters:

project_api_call (ApiCall)
pipeline_id (int)
top (int | None)

Return type:

list[PipelineRunInfo]

pyado.raw.pipelines.pipeline.list_pipelines(project_api_call, order_by=None)¶

Return all pipelines as a list.

Parameters:

project_api_call (ApiCall)
order_by (str | None)

Return type:

list[PipelineInfo]

pyado.raw.pipelines.pipeline.patch_approvals(project_api_call, updates)¶

Patch one or more pipeline environment approvals.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
updates (list[PipelineApprovalUpdateRequest]) – List of approval updates to apply.

Return type:

None

pyado.raw.pipelines.pipeline.patch_pipeline_permission(project_api_call, resource_type, resource_id, pipeline_id, *, authorized)¶

Authorize or de-authorize a pipeline to use a protected resource.

Maps to PATCH /{project}/_apis/pipelines/pipelinepermissions/{type}/{id}.

Important — additive semantics: this endpoint only adds authorizations; it never removes existing ones. There is no bulk-replace endpoint. To remove a pipeline authorization you must use the ADO web UI or compare the current ADO state against your expected configuration and handle the delta manually.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
resource_type (PipelineResourceType) – The resource category (e.g. PipelineResourceType.VARIABLE_GROUP).
resource_id (str) – String identifier of the resource (numeric ID as a string for variable groups and queues; GUID string for environments).
pipeline_id (int) – Numeric pipeline ID to authorize.
authorized (bool) – True to grant access, False to revoke.

Returns:

PipelineResourcePermissions reflecting the updated state of the resource’s authorization list.

Return type:

pyado.raw.pipelines.pipeline.patch_timeline_records(timeline_api_call, payload)¶

Update the timeline records.

Parameters:

timeline_api_call (ApiCall)
payload (TimelineRecordsUpdatePayload)

Return type:

None

pyado.raw.pipelines.pipeline.post_job_event(plan_api_call, payload)¶

This notifies the pipeline that the task has completed.

Reference: https://github.com/MicrosoftDocs/vsts-rest-api-specs/blob/master /specification/distributedTask/7.1/httpExamples/events/ POST_distributedtask_PostEvent.json

Parameters:

plan_api_call (ApiCall)
payload (JobEventPayload)

Return type:

None

pyado.raw.pipelines.pipeline.post_job_feed(job_api_call, payload)¶

Sends messages to feed of the running task.

Reference: https://github.com/MicrosoftDocs/vsts-rest-api-specs/blob/master /specification/distributedTask/7.1/httpExamples/feed/ POST__distributedtask_AppendTimelineRecordFeed_.json

Parameters:

job_api_call (ApiCall)
payload (JobFeedPayload)

Return type:

None

pyado.raw.pipelines.pipeline.post_job_logs(log_api_call, message)¶

Sends messages to the log of the running task.

Reference: https://github.com/MicrosoftDocs/vsts-rest-api-specs/blob/master /specification/distributedTask/7.1/httpExamples/logs/ POST__distributedtask_AppendLogContent_.json

Parameters:

log_api_call (ApiCall)
message (str)

Return type:

None

pyado.raw.pipelines.pipeline.post_new_log(plan_api_call, path)¶

Create a new log entry in a distributed-task plan.

Step 1 of the three-step per-record log sequence: POST to the plan’s logs endpoint to obtain a new numeric log ID. Call patch_timeline_records() (step 2) to associate the log with a timeline record, then post_job_logs() (step 3) to append content.

Parameters:

plan_api_call (ApiCall) – Plan-level ADO API call (from get_plan_api_call).
path (str) – Path for the log container, conventionally "logs\\\\<record-uuid>".

Returns:

BuildLogInfo with the newly assigned numeric log ID and canonical URL.

Return type:

BuildLogInfo

Reference:: POST …/distributedtask/hubs/{hub}/plans/{plan_id}/logs

pyado.raw.pipelines.pipeline.post_pipeline_run(project_api_call, pipeline_id, request=None)¶

Trigger a new run of a pipeline.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
pipeline_id (int) – The numeric pipeline ID to trigger.
request (PipelineRunRequest | None) – Optional run parameters (variables, template parameters, stages to skip, etc.). Pass None to run with defaults.

Returns:

PipelineRunInfo describing the newly queued run.

Return type:

PipelineRunInfo

Task Group¶

Azure DevOps task group API wrappers.

class pyado.raw.pipelines.task_group.TaskGroupCreateRequest(*, name, tasks, description=None, category=None, comment=None, author=None, runsOn=<factory>)¶

Request body for creating a task group.

Parameters:

name (str)
tasks (list[dict[str, Any]])
description (str | None)
category (str | None)
comment (str | None)
author (str | None)
runsOn (list[str])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.task_group.TaskGroupId¶: UUID identifier for a task group.

class pyado.raw.pipelines.task_group.TaskGroupInfo(*, id, name, revision=None, description=None, category=None, comment=None, author=None, tasks=<factory>)¶

Minimal representation of an ADO task group.

Parameters:

id (UUID)
name (str)
revision (int | None)
description (str | None)
category (str | None)
comment (str | None)
author (str | None)
tasks (list[dict[str, Any]])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.task_group.TaskGroupUpdateRequest(*, id, name, tasks, revision=None, description=None, category=None, comment=None, author=None, runsOn=<factory>)¶

Request body for updating a task group.

Parameters:

id (UUID)
name (str)
tasks (list[dict[str, Any]])
revision (int | None)
description (str | None)
category (str | None)
comment (str | None)
author (str | None)
runsOn (list[str])

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.task_group.delete_task_group(project_api_call, task_group_id)¶

Delete a task group from a project.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
task_group_id (UUID) – UUID of the task group to delete.

Return type:

None

pyado.raw.pipelines.task_group.get_task_group(project_api_call, task_group_id)¶

Fetch a single task group by ID.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
task_group_id (UUID) – UUID of the task group.

Returns:

TaskGroupInfo for the requested task group.

Return type:

TaskGroupInfo

pyado.raw.pipelines.task_group.iter_task_groups(project_api_call)¶

Iterate over all task groups in a project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: TaskGroupInfo for each task group.
Return type:: Iterator[TaskGroupInfo]

pyado.raw.pipelines.task_group.list_task_groups(project_api_call)¶

Return all task groups in a project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[TaskGroupInfo]

pyado.raw.pipelines.task_group.post_task_group(project_api_call, request)¶

Create a new task group in a project.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
request (TaskGroupCreateRequest) – Create request specifying the name and tasks.

Returns:

TaskGroupInfo for the newly created task group.

Return type:

TaskGroupInfo

pyado.raw.pipelines.task_group.put_task_group(project_api_call, task_group_id, request)¶

Update an existing task group.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
task_group_id (UUID) – UUID of the task group to update.
request (TaskGroupUpdateRequest) – Update request. The id field must match task_group_id.

Returns:

Updated TaskGroupInfo parsed from the API response.

Return type:

TaskGroupInfo

Agent¶

Azure DevOps agent pool and queue API wrappers.

pyado.raw.pipelines.agent.AgentId¶: alias of int

class pyado.raw.pipelines.agent.AgentInfo(*, id, name, status=None, osDescription=None, version=None, createdOn=None)¶

Minimal representation of an agent within a pool.

Parameters:

id (int)
name (str)
status (str | None)
osDescription (str | None)
version (str | None)
createdOn (datetime | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.agent.AgentPoolId¶: alias of int

class pyado.raw.pipelines.agent.AgentPoolInfo(*, id, name, isHosted=False, poolType=None, size=0)¶

Minimal representation of an ADO agent pool.

Parameters:

id (int)
name (str)
isHosted (bool)
poolType (str | None)
size (int)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.agent.AgentPoolRef(*, id, name, isHosted=False)¶

Pool reference embedded in an agent queue response.

Parameters:

id (int)
name (str)
isHosted (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.agent.AgentQueueId¶: alias of int

class pyado.raw.pipelines.agent.AgentQueueInfo(*, id, name, pool=None)¶

Minimal representation of a project-scoped agent queue.

Parameters:

id (int)
name (str)
pool (AgentPoolRef | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.agent.get_agent_pool(org_api_call, pool_id)¶

Return a single agent pool by ID.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
pool_id (int) – Numeric agent pool ID.

Returns:

AgentPoolInfo for the requested pool.

Return type:

AgentPoolInfo

pyado.raw.pipelines.agent.get_agent_pool_api_call(org_api_call, pool_id)¶

Build an agent-pool-scoped API call.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
pool_id (int) – Numeric agent pool ID.

Returns:

An ApiCall pointing at the agent pool resource.

Return type:

pyado.raw.pipelines.agent.get_agent_queue(project_api_call, queue_id)¶

Return a single agent queue by ID.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
queue_id (int) – Numeric agent queue ID.

Returns:

AgentQueueInfo for the requested queue.

Return type:

AgentQueueInfo

pyado.raw.pipelines.agent.iter_agent_pools(org_api_call)¶

Iterate over all agent pools in the organisation.

Parameters:: org_api_call (ApiCall) – Organisation-level ADO API call.
Yields:: AgentPoolInfo for each agent pool.
Return type:: Iterator[AgentPoolInfo]

pyado.raw.pipelines.agent.iter_agent_queues(project_api_call)¶

Iterate over all agent queues in a project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: AgentQueueInfo for each agent queue.
Return type:: Iterator[AgentQueueInfo]

pyado.raw.pipelines.agent.iter_agents(pool_api_call)¶

Iterate over all agents in a pool.

Parameters:: pool_api_call (ApiCall) – Agent-pool-level ADO API call (from get_agent_pool_api_call).
Yields:: AgentInfo for each agent in the pool.
Return type:: Iterator[AgentInfo]

pyado.raw.pipelines.agent.list_agent_pools(org_api_call)¶

Return all agent pools in the organisation as a list.

Parameters:: org_api_call (ApiCall)
Return type:: list[AgentPoolInfo]

pyado.raw.pipelines.agent.list_agent_queues(project_api_call)¶

Return all agent queues in the project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[AgentQueueInfo]

pyado.raw.pipelines.agent.list_agents(pool_api_call)¶

Return all agents in a pool as a list.

Parameters:: pool_api_call (ApiCall)
Return type:: list[AgentInfo]

Environment¶

Azure DevOps distributed task environment API wrappers.

class pyado.raw.pipelines.environment.ApprovalCheckSettings(*, approvers=<factory>, instructions='', requesterCannotBeApprover=False, requiredApproverCount=1, allowApproversToApproveTheirOwnRuns=False)¶

Settings for an Approval check on a pipeline environment.

Parameters:

approvers (list[_EnvironmentIdentityRef])
instructions (str)
requesterCannotBeApprover (bool)
requiredApproverCount (int)
allowApproversToApproveTheirOwnRuns (bool)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.environment.DeploymentRecordId¶: Numeric identifier for an environment deployment record.

pyado.raw.pipelines.environment.EnvironmentCheckId¶: Numeric identifier for an environment check configuration.

class pyado.raw.pipelines.environment.EnvironmentCheckInfo(*, id, type, settings=None, timeout=None, createdBy=None, createdOn=None)¶

A single check configuration on a pipeline environment.

Parameters:

id (int)
type (_CheckTypeRef)
settings (ApprovalCheckSettings | None)
timeout (int | None)
createdBy (_EnvironmentIdentityRef | None)
createdOn (datetime | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.environment.EnvironmentDeploymentRecord(*, id, definitionName='', startTime=None, finishTime=None, result=None, owner=None)¶

A single deployment record for a pipeline environment.

Parameters:

id (int)
definitionName (str)
startTime (datetime | None)
finishTime (datetime | None)
result (str | None)
owner (_DeploymentRecordOwner | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.environment.EnvironmentId¶: alias of int

class pyado.raw.pipelines.environment.EnvironmentInfo(*, id, name, description='', createdBy=None, createdOn=None, lastModifiedBy=None, lastModifiedOn=None, project=None)¶

Minimal representation of an ADO pipeline environment.

Parameters:

id (int)
name (str)
description (str)
createdBy (_EnvironmentIdentityRef | None)
createdOn (datetime | None)
lastModifiedBy (_EnvironmentIdentityRef | None)
lastModifiedOn (datetime | None)
project (_EnvironmentProjectRef | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.environment.get_environment(project_api_call, environment_id)¶

Return a single pipeline environment by ID.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
environment_id (int) – Numeric environment ID.

Returns:

EnvironmentInfo for the requested environment.

Return type:

EnvironmentInfo

pyado.raw.pipelines.environment.get_environment_api_call(project_api_call, environment_id)¶

Build an environment-scoped API call.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
environment_id (int) – Numeric environment ID.

Returns:

An ApiCall pointing at the environment resource.

Return type:

pyado.raw.pipelines.environment.iter_environment_checks(project_api_call, environment_id)¶

Iterate over all check configurations for a pipeline environment.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
environment_id (int) – Numeric environment ID.

Yields:

EnvironmentCheckInfo for each check configuration.

Return type:

Iterator[EnvironmentCheckInfo]

pyado.raw.pipelines.environment.iter_environment_deployments(env_api_call, *, top=None)¶

Iterate over deployment records for a pipeline environment.

Parameters:

env_api_call (ApiCall) – Environment-level ADO API call (from get_environment_api_call).
top (int | None) – Maximum number of records to return. When None, the API default is used.

Yields:

EnvironmentDeploymentRecord for each deployment.

Return type:

Iterator[EnvironmentDeploymentRecord]

pyado.raw.pipelines.environment.iter_environments(project_api_call)¶

Iterate over all pipeline environments in a project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: EnvironmentInfo for each environment in the project.
Return type:: Iterator[EnvironmentInfo]

pyado.raw.pipelines.environment.list_environment_checks(project_api_call, environment_id)¶

Return all check configurations for a pipeline environment as a list.

Parameters:

project_api_call (ApiCall)
environment_id (int)

Return type:

list[EnvironmentCheckInfo]

pyado.raw.pipelines.environment.list_environment_deployments(env_api_call, *, top=None)¶

Return all deployment records for a pipeline environment as a list.

Parameters:

env_api_call (ApiCall)
top (int | None)

Return type:

list[EnvironmentDeploymentRecord]

pyado.raw.pipelines.environment.list_environments(project_api_call)¶

Return all pipeline environments in a project as a list.

Parameters:: project_api_call (ApiCall)
Return type:: list[EnvironmentInfo]

Variable Group¶

Azure DevOps distributed task variable group API wrappers.

pyado.raw.pipelines.variable_group.UserId¶: alias of UUID

class pyado.raw.pipelines.variable_group.VariableGroupCreateRequest(*, name, variables, variableGroupProjectReferences, description=None, type='Vsts', providerData=None)¶

Request body for creating a variable group.

Parameters:

name (str)
variables (dict[str, VariableInfo])
variableGroupProjectReferences (list[VariableGroupProjectReference])
description (str | None)
type (str)
providerData (Any)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.variable_group.VariableGroupId¶: alias of int

class pyado.raw.pipelines.variable_group.VariableGroupInfo(*, createdBy, createdOn, description=None, id, isShared, modifiedBy, modifiedOn, name, type, variableGroupProjectReferences=None, variables)¶

Type to store variable group details.

Parameters:

createdBy (VariableGroupUserInfo)
createdOn (datetime)
description (str | None)
id (int)
isShared (bool)
modifiedBy (VariableGroupUserInfo)
modifiedOn (datetime)
name (str)
type (str)
variableGroupProjectReferences (list[VariableGroupProjectReference] | None)
variables (dict[str, VariableInfo])

model_config = {'alias_generator': <function to_camel>, 'extra': 'forbid', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.variable_group.VariableGroupProjectReference(*, description=None, name, projectReference)¶

A project reference entry within a variable group’s project references list.

Parameters:

description (str | None)
name (str)
projectReference (_VgProjectRef)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.variable_group.VariableGroupUpdateRequest(*, name, variables, variableGroupProjectReferences=None, description=None, type=None, providerData=None)¶

Request body for updating a variable group.

Parameters:

name (str)
variables (dict[str, VariableInfo])
variableGroupProjectReferences (list[VariableGroupProjectReference] | None)
description (str | None)
type (str | None)
providerData (Any)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.variable_group.VariableGroupUserInfo(*, displayName=None, id, uniqueName=None)¶

Type to store variable group user information.

Parameters:

displayName (str | None)
id (UUID)
uniqueName (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipelines.variable_group.VariableInfo(*, isSecret=False, value=None)¶

Type to store information about variables.

Parameters:

isSecret (bool)
value (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.variable_group.delete_variable_group(org_api_call, var_group_id, project_ids)¶

Delete a variable group.

The DELETE endpoint is organisation-scoped (not project-scoped) and requires one or more project UUIDs via the projectIds query parameter.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call.
var_group_id (int) – Numeric ID of the variable group to delete.
project_ids (list[str]) – List of project UUIDs the variable group is associated with.

Return type:

None

pyado.raw.pipelines.variable_group.get_variable_group_api_call(project_api_call, var_group_id)¶

Get the API call for a specific variable group.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
var_group_id (int) – Numeric ID of the variable group.

Returns:

An ApiCall pointing at the variable group resource for the given ID.

Return type:

pyado.raw.pipelines.variable_group.get_variable_group_details(variable_group_api_call)¶

Fetch the details of a single variable group by its API call.

Parameters:: variable_group_api_call (ApiCall) – Variable-group-level ADO API call (from get_variable_group_api_call).
Returns:: VariableGroupInfo for the requested variable group.
Return type:: VariableGroupInfo

pyado.raw.pipelines.variable_group.iter_variable_group_details(project_api_call)¶

Iterate over the variable groups of the project.

Parameters:: project_api_call (ApiCall) – Project-level ADO API call.
Yields:: VariableGroupInfo objects for each variable group in the project.
Return type:: Iterator[VariableGroupInfo]

pyado.raw.pipelines.variable_group.post_variable_group(project_api_call, request)¶

Create a new variable group in the project.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
request (VariableGroupCreateRequest) – Create request specifying the name, variables, project references, and optional metadata fields.

Returns:

VariableGroupInfo for the newly created variable group.

Return type:

VariableGroupInfo

pyado.raw.pipelines.variable_group.put_variable_group(variable_group_api_call, request)¶

Update a variable group.

Parameters:

variable_group_api_call (ApiCall) – Variable-group-level ADO API call (from get_variable_group_api_call).
request (VariableGroupUpdateRequest) – Update request specifying the name, variables, and optional metadata fields.

Returns:

Updated VariableGroupInfo parsed from the API response.

Return type:

VariableGroupInfo

Secure File¶

Azure DevOps distributed task secure file API wrappers.

pyado.raw.pipelines.secure_file.SecureFileId¶: alias of UUID

class pyado.raw.pipelines.secure_file.SecureFileInfo(*, id, name, createdOn=None, modifiedOn=None, createdBy=None, modifiedBy=None)¶

Minimal representation of an ADO secure file.

Parameters:

id (UUID)
name (str)
createdOn (datetime | None)
modifiedOn (datetime | None)
createdBy (str | None)
modifiedBy (str | None)

model_config = {'alias_generator': <function to_camel>, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipelines.secure_file.delete_secure_file(secure_file_api_call)¶

Delete a secure file.

Parameters:: secure_file_api_call (ApiCall) – Secure-file-level ADO API call (from get_secure_file_api_call).
Return type:: None

pyado.raw.pipelines.secure_file.get_secure_file(project_api_call, file_id)¶

Return a single secure file by ID.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
file_id (UUID) – UUID of the secure file.

Returns:

SecureFileInfo for the requested secure file.

Return type:

SecureFileInfo

pyado.raw.pipelines.secure_file.get_secure_file_api_call(project_api_call, file_id)¶

Build a secure-file-scoped API call.

Parameters:

project_api_call (ApiCall) – Project-level ADO API call.
file_id (UUID) – UUID of the secure file.

Returns:

An ApiCall pointing at the secure file resource.

Return type: