Reference ¶

Example:

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

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_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

create_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

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

delete_branch(name, current_commit)¶

Delete a branch from the repository.

Parameters:

name (str) – Short branch name or full refs/heads/… name.
current_commit (str) – Current HEAD SHA of the branch (used for the optimistic-concurrency check).

Return type:

None

delete_file(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:

delete_tag(name, commit_id)¶

Delete a 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_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]

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:

ValueError – If the repository has no default branch configured.
KeyError – If the default branch ref is not found in the repository (e.g. empty repository).

Return type:

Commit

get_file_at_branch(path, branch)¶

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) – Short branch name (e.g. "main").

Returns:

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

Return type:

str

get_file_at_commit(path, commit)¶

Return the content of a file at a specific commit.

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_at_branch(path, branch)¶

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

Use this instead of get_file_at_branch() when the file may contain non-UTF-8 data (e.g. images, compiled artefacts).

Parameters:

path (str) – Absolute file path within the repository (e.g. /img.png).
branch (str) – Short branch name (e.g. "main").

Returns:

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

Return type:

bytes | None

get_file_bytes_at_commit(path, commit)¶

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

Use this instead of get_file_at_commit() when the file may contain non-UTF-8 data (e.g. images, compiled artefacts).

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_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_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_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:: GitRef for each branch.
Return type:: Iterator[GitRef]

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_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_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]

iter_tags()¶

Iterate over all git tags in the repository.

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

list_branches()¶

Return all branches in this repository as a list.

Return type:: list[GitRef]

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_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_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]

list_tags()¶

Return all tags in this repository as a list.

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

rename_file(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:

property web_url: Annotated[HttpUrl, UrlConstraints(max_length=256, 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.pull_request.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

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 PrIterationChange entries for the iteration.
Return type:: list[PrIterationChange]

get_reviewers()¶

Return all reviewers on the pull request.

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

get_tag_details()¶

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

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

Returns:: List of PullRequestLabel objects; empty when no tags are set.
Return type:: list[PullRequestLabel]

get_tags()¶

Return the names of all tags set on the pull request.

Returns:: List of tag name strings; empty when no tags are set.
Return type:: list[str]

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:: PrIterationChange for each changed file.
Return type:: Iterator[PrIterationChange]

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_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[PrIterationChange]

list_iterations()¶

Return all iterations for this pull request as a list.

Return type:: list[PullRequestIterationRecord]

list_statuses()¶

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

Return type:: list[PullRequestStatusInfo]

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

Work Item¶

OOP wrapper for Azure DevOps work item resources.

class pyado.oop.work_item.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 Project.get_work_item(), Project.iter_work_items(), or Project.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.
Returns:: Updated list of tag name strings.
Return type:: list[str]

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 Project.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

delete_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

get_attachment_bytes(ref)¶

Download the raw bytes of an uploaded attachment.

Parameters:: ref (WorkItemAttachmentRef) – The WorkItemAttachmentRef returned by add_attachment().
Returns:: Raw file bytes.
Return type:: bytes

get_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 Project.get_work_item()).

Returns:: List of numeric child work item IDs.
Return type:: list[int]

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

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.

Convenience filter around iter_relations() for WorkItemRelationType.ATTACHED_FILE.

Yields:: WorkItemRelation for each attached file.
Return type:: Iterator[WorkItemRelation]

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 Project.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 Project.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[WorkItemRelation]

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_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.
Returns:: Updated list of tag name strings.
Return type:: list[str]

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:

PipelineResourcePermissions

Build¶

OOP wrapper for Azure DevOps build resources.

class pyado.oop.build.Build(project, build_api_call, info, service)¶

An Azure DevOps build resource.

Wraps a single ADO build and exposes its operations as instance methods. Instances are obtained from Project.get_build(), Project.iter_builds(), or Project.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.
Returns:: Updated list of all tag name strings on the build after the operation. ADO returns the full tag list; this is a direct pass-through.
Return type:: list[str]

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.

Return type:: None

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_active_build_task(*, hub_name, plan_id, timeline_id, job_id, task_instance_id)¶

Return an ActiveBuildTask for a running pipeline task.

This factory is intended for external systems acting as a serverless ADO task (e.g. an AWS Lambda polling ADO for work). Pass the distributed-task runtime variables that ADO injects as pipeline environment variables.

Parameters:

hub_name (str) – Distributed-task hub name (e.g. "build").
plan_id (UUID) – Value of $(system.planId) / SYSTEM_PLANID.
timeline_id (UUID) – Value of $(system.timelineId) / SYSTEM_TIMELINEID.
job_id (UUID) – Value of $(system.jobId) / SYSTEM_JOBID.
task_instance_id (UUID) – Value of the task instance UUID (AGENT_TASKINSTANCEID).

Returns:

ActiveBuildTask bound to this build and the given task.

Return type:

ActiveBuildTask

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_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_stages()¶

Iterate over the stages of the build.

Fetches all timeline records in a single API call, then yields a BuildStage for each Stage-type record. Navigate into jobs and tasks via BuildStage.iter_jobs() and BuildJob.iter_tasks() — no additional API calls are made.

Yields:: BuildStage for each stage in the build timeline.
Return type:: Iterator[BuildStage]

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_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_stages()¶

Return all stages for this build as a list.

Return type:: list[BuildStage]

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 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.
Returns:: Updated list of all tag name strings on the build after the operation. ADO returns the full tag list; this is a direct pass-through.
Return type:: list[str]

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.build.BuildJob(record, all_records, stage, phase)¶

A job within a build stage.

Wraps one Job-type timeline record and provides access to its child tasks. Instances are obtained from BuildStage.iter_jobs() or BuildPhase.iter_jobs().

Parameters:

record (BuildRecordInfo)
all_records (list[BuildRecordInfo])
stage (BuildStage)
phase (BuildPhase | None)

_record¶: The raw timeline record for this job.

_all_records¶: All timeline records from the same build (used to find child tasks without additional API calls).

_stage¶: The parent BuildStage.

_phase¶: The parent BuildPhase, or None for classic pipelines where jobs are direct children of the stage.

property error_count: int¶: Number of errors logged by this job.

property finish_time: datetime | None¶: When the job finished, or None if not yet finished.

get_log_text()¶

Fetch the plain-text log content for this job.

Returns None when no log is associated with this job.

Returns:: Log text, or None if no log is available.
Return type:: str | None

property id: UUID¶: Unique record ID for this job.

property info: BuildRecordInfo¶: Raw timeline record for direct inspection or raw-layer use.

property issues: list[BuildIssue]¶: List of issues (errors/warnings) reported by this job.

iter_tasks()¶

Iterate over the task steps within this job.

Yields:: BuildTask for each Task-type record whose parent is this job.
Return type:: Iterator[BuildTask]

list_tasks()¶

Return all task steps within this job as a list.

Return type:: list[BuildTask]

property log: BuildLogInfo | None¶: Log reference for this job, or None if unavailable.

property name: str¶: Display name of the job.

property phase: BuildPhase | None¶

Parent BuildPhase — zero-cost.

None for jobs that are direct children of a stage (classic pipelines). Non-None for jobs nested under a Phase in YAML pipelines.

property result: BuildRecordResult | None¶: Outcome once the job has completed, or None if still running.

property stage: BuildStage¶: Parent BuildStage — zero-cost.

property start_time: datetime | None¶: When the job started, or None if not yet started.

property state: BuildRecordState¶: Lifecycle state (pending, inProgress, completed).

property warning_count: int¶: Number of warnings logged by this job.

property worker_name: str | None¶: Name of the agent that ran this job, or None if unavailable.

class pyado.oop.build.BuildPhase(record, all_records, stage)¶

A phase within a build stage (YAML pipelines only).

In YAML pipelines a Phase record sits between a Stage and its Job records. Classic pipelines do not emit Phase records — in that case BuildStage.iter_phases() yields nothing and BuildStage.iter_jobs() returns the jobs directly.

Instances are obtained from BuildStage.iter_phases().

Parameters:

record (BuildRecordInfo)
all_records (list[BuildRecordInfo])
stage (BuildStage)

_record¶: The raw timeline record for this phase.

_all_records¶: All timeline records from the same build.

_stage¶: The parent BuildStage.

property error_count: int¶: Number of errors logged by this phase.

property finish_time: datetime | None¶: When the phase finished, or None if not yet finished.

property id: UUID¶: Unique record ID for this phase.

property info: BuildRecordInfo¶: Raw timeline record for direct inspection or raw-layer use.

property issues: list[BuildIssue]¶: List of issues (errors/warnings) reported by this phase.

iter_jobs()¶

Iterate over the jobs within this phase.

Yields:: BuildJob for each Job-type record whose parent is this phase.
Return type:: Iterator[BuildJob]

list_jobs()¶

Return all jobs within this phase as a list.

Return type:: list[BuildJob]

property log: BuildLogInfo | None¶: Log reference for this phase, or None if unavailable.

property name: str¶: Display name of the phase.

property result: BuildRecordResult | None¶: Outcome once the phase has completed, or None if still running.

property stage: BuildStage¶: Parent BuildStage — zero-cost.

property start_time: datetime | None¶: When the phase started, or None if not yet started.

property state: BuildRecordState¶: Lifecycle state (pending, inProgress, completed).

property warning_count: int¶: Number of warnings logged by this phase.

class pyado.oop.build.BuildStage(record, all_records, build)¶

A stage within a build timeline.

Wraps one Stage-type timeline record and provides access to its child jobs. In YAML pipelines an optional Phase record may sit between the stage and its jobs; iter_jobs() handles this transparently. Instances are obtained from Build.iter_stages().

Parameters:

record (BuildRecordInfo)
all_records (list[BuildRecordInfo])
build (Build)

_record¶: The raw timeline record for this stage.

_all_records¶: All timeline records from the same build.

_build¶: The owning Build.

property build: Build¶: Owning Build — zero-cost.

property error_count: int¶: Number of errors logged by this stage.

property finish_time: datetime | None¶: When the stage finished, or None if not yet finished.

get_log_text()¶

Fetch the plain-text log content for this stage.

Returns None when no log is associated with this stage.

Returns:: Log text, or None if no log is available.
Return type:: str | None

property id: UUID¶: Unique record ID for this stage.

property info: BuildRecordInfo¶: Raw timeline record for direct inspection or raw-layer use.

property issues: list[BuildIssue]¶: List of issues (errors/warnings) reported by this stage.

iter_jobs()¶

Iterate over all jobs within this stage.

Includes jobs that are direct children of the stage (classic pipelines) as well as jobs nested under a Phase (YAML pipelines). Use iter_phases() followed by BuildPhase.iter_jobs() if you need to distinguish which phase a job belongs to.

Yields:: BuildJob for each Job-type record belonging to this stage.
Return type:: Iterator[BuildJob]

iter_phases()¶

Iterate over the phases within this stage (YAML pipelines only).

Classic pipelines do not have Phase records; this method yields nothing for them. Use iter_jobs() to iterate jobs regardless of whether phases are present.

Yields:: BuildPhase for each Phase-type record under this stage.
Return type:: Iterator[BuildPhase]

list_jobs()¶

Return all jobs within this stage as a list.

Return type:: list[BuildJob]

list_phases()¶

Return all phases within this stage as a list.

Return type:: list[BuildPhase]

property log: BuildLogInfo | None¶: Log reference for this stage, or None if unavailable.

property name: str¶: Display name of the stage.

property result: BuildRecordResult | None¶: Outcome once the stage has completed, or None if still running.

property start_time: datetime | None¶: When the stage started, or None if not yet started.

property state: BuildRecordState¶: Lifecycle state (pending, inProgress, completed).

property warning_count: int¶: Number of warnings logged by this stage.

class pyado.oop.build.BuildTask(record=None, *, job=None)¶

A single task step within a build job.

Wraps one Task-type timeline record. Instances are obtained from BuildJob.iter_tasks().

The job back-reference is always non-None for tasks obtained from BuildJob.iter_tasks(). The ActiveBuildTask subclass starts with job=None and provides get_job() instead.

Parameters:

record (BuildRecordInfo | None)
job (BuildJob | None)

_record¶: The raw timeline record for this task (None until _resolve() is called by a subclass).

_job¶: The parent BuildJob, or None for ActiveBuildTask.

property error_count: int¶: Number of errors logged by this task.

property finish_time: datetime | None¶: When the task finished, or None if not yet finished.

get_log_text()¶

Fetch the plain-text log content for this task.

Returns None when no log is associated with this task (i.e. log is None). Requires job to be set; tasks obtained from BuildJob.iter_tasks() always satisfy this.

Returns:: Log text, or None if no log is available.
Return type:: str | None

property id: UUID¶: Unique record ID for this task.

property info: BuildRecordInfo¶: Raw timeline record for direct inspection or raw-layer use.

property issues: list[BuildIssue]¶: List of issues (errors/warnings) reported by this task.

property job: BuildJob | None¶

Parent BuildJob — zero-cost.

Always non-None for tasks obtained from BuildJob.iter_tasks(). None for ActiveBuildTask instances (use get_job() instead).

property log: BuildLogInfo | None¶: Log reference for this task, or None if unavailable.

property name: str¶: Display name of the task.

property result: BuildRecordResult | None¶: Outcome once the task has completed, or None if still running.

property start_time: datetime | None¶: When the task started, or None if not yet started.

property state: BuildRecordState¶: Lifecycle state (pending, inProgress, completed).

property warning_count: int¶: Number of warnings logged by this task.

Pipeline¶

OOP wrapper for Azure DevOps pipeline resources.

class pyado.oop.pipeline.Pipeline(project, pipeline_id, name, info=None)¶

An Azure DevOps pipeline resource (Pipelines v2).

Wraps a single ADO pipeline and exposes its operations as instance methods. Instances are obtained from Project.get_pipeline(), Project.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, Any] | 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.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.

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 (rather than a raw info object) so that callers can chain further method calls on the same wrapper. This differs from Build.cancel(), which returns BuildDetails for the classic Build API — the two methods target different ADO endpoints and the return-type difference is intentional.

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.

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").

Variable Group¶

OOP wrapper for Azure DevOps variable group resources.

class pyado.oop.variable_group.VariableGroup(project, variable_group_api_call, info)¶

An Azure DevOps variable group resource.

Wraps a single ADO variable group and exposes its operations as instance methods. Instances are obtained from Project.iter_variable_groups() or Project.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

delete_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

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

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).

Team¶

OOP wrapper for Azure DevOps team resources.

class pyado.oop.team.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 add_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_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]

property id: str¶: Team UUID string.

property info: TeamInfo¶: Full team data as returned by the API.

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_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

Iteration¶

OOP wrapper for Azure DevOps iteration classification nodes.

class pyado.oop.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 Project.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 Project.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 Project.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.area.Area(project, info)¶

An Azure DevOps area classification node.

Wraps a single area node and exposes its properties. Instances are obtained from Project.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 Project.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 Project.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

Commit¶

OOP wrapper for Azure DevOps git commit resources.

class pyado.oop.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

get_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 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]

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.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.

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.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.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.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

Build Timeline¶

OOP wrappers for build timeline stages, jobs, and tasks.

class pyado.oop.build_timeline.BuildJob(record, all_records, stage, phase)¶

A job within a build stage.

Wraps one Job-type timeline record and provides access to its child tasks. Instances are obtained from BuildStage.iter_jobs() or BuildPhase.iter_jobs().

Parameters:

record (BuildRecordInfo)
all_records (list[BuildRecordInfo])
stage (BuildStage)
phase (BuildPhase | None)

_record¶: The raw timeline record for this job.

_all_records¶: All timeline records from the same build (used to find child tasks without additional API calls).

_stage¶: The parent BuildStage.

_phase¶: The parent BuildPhase, or None for classic pipelines where jobs are direct children of the stage.

property error_count: int¶: Number of errors logged by this job.

property finish_time: datetime | None¶: When the job finished, or None if not yet finished.

get_log_text()¶

Fetch the plain-text log content for this job.

Returns None when no log is associated with this job.

Returns:: Log text, or None if no log is available.
Return type:: str | None

property id: UUID¶: Unique record ID for this job.

property info: BuildRecordInfo¶: Raw timeline record for direct inspection or raw-layer use.

property issues: list[BuildIssue]¶: List of issues (errors/warnings) reported by this job.

iter_tasks()¶

Iterate over the task steps within this job.

Yields:: BuildTask for each Task-type record whose parent is this job.
Return type:: Iterator[BuildTask]

list_tasks()¶

Return all task steps within this job as a list.

Return type:: list[BuildTask]

property log: BuildLogInfo | None¶: Log reference for this job, or None if unavailable.

property name: str¶: Display name of the job.

property phase: BuildPhase | None¶

Parent BuildPhase — zero-cost.

None for jobs that are direct children of a stage (classic pipelines). Non-None for jobs nested under a Phase in YAML pipelines.

property result: BuildRecordResult | None¶: Outcome once the job has completed, or None if still running.

property stage: BuildStage¶: Parent BuildStage — zero-cost.

property start_time: datetime | None¶: When the job started, or None if not yet started.

property state: BuildRecordState¶: Lifecycle state (pending, inProgress, completed).

property warning_count: int¶: Number of warnings logged by this job.

property worker_name: str | None¶: Name of the agent that ran this job, or None if unavailable.

class pyado.oop.build_timeline.BuildPhase(record, all_records, stage)¶

A phase within a build stage (YAML pipelines only).

Instances are obtained from BuildStage.iter_phases().

Parameters:

record (BuildRecordInfo)
all_records (list[BuildRecordInfo])
stage (BuildStage)

_record¶: The raw timeline record for this phase.

_all_records¶: All timeline records from the same build.

_stage¶: The parent BuildStage.

property error_count: int¶: Number of errors logged by this phase.

property finish_time: datetime | None¶: When the phase finished, or None if not yet finished.

property id: UUID¶: Unique record ID for this phase.

property info: BuildRecordInfo¶: Raw timeline record for direct inspection or raw-layer use.

property issues: list[BuildIssue]¶: List of issues (errors/warnings) reported by this phase.

iter_jobs()¶

Iterate over the jobs within this phase.

Yields:: BuildJob for each Job-type record whose parent is this phase.
Return type:: Iterator[BuildJob]

list_jobs()¶

Return all jobs within this phase as a list.

Return type:: list[BuildJob]

property log: BuildLogInfo | None¶: Log reference for this phase, or None if unavailable.

property name: str¶: Display name of the phase.

property result: BuildRecordResult | None¶: Outcome once the phase has completed, or None if still running.

property stage: BuildStage¶: Parent BuildStage — zero-cost.

property start_time: datetime | None¶: When the phase started, or None if not yet started.

property state: BuildRecordState¶: Lifecycle state (pending, inProgress, completed).

property warning_count: int¶: Number of warnings logged by this phase.

class pyado.oop.build_timeline.BuildStage(record, all_records, build)¶

A stage within a build timeline.

Parameters:

record (BuildRecordInfo)
all_records (list[BuildRecordInfo])
build (Build)

_record¶: The raw timeline record for this stage.

_all_records¶: All timeline records from the same build.

_build¶: The owning Build.

property build: Build¶: Owning Build — zero-cost.

property error_count: int¶: Number of errors logged by this stage.

property finish_time: datetime | None¶: When the stage finished, or None if not yet finished.

get_log_text()¶

Fetch the plain-text log content for this stage.

Returns None when no log is associated with this stage.

Returns:: Log text, or None if no log is available.
Return type:: str | None

property id: UUID¶: Unique record ID for this stage.

property info: BuildRecordInfo¶: Raw timeline record for direct inspection or raw-layer use.

property issues: list[BuildIssue]¶: List of issues (errors/warnings) reported by this stage.

iter_jobs()¶

Iterate over all jobs within this stage.

Yields:: BuildJob for each Job-type record belonging to this stage.
Return type:: Iterator[BuildJob]

iter_phases()¶

Iterate over the phases within this stage (YAML pipelines only).

Classic pipelines do not have Phase records; this method yields nothing for them. Use iter_jobs() to iterate jobs regardless of whether phases are present.

Yields:: BuildPhase for each Phase-type record under this stage.
Return type:: Iterator[BuildPhase]

list_jobs()¶

Return all jobs within this stage as a list.

Return type:: list[BuildJob]

list_phases()¶

Return all phases within this stage as a list.

Return type:: list[BuildPhase]

property log: BuildLogInfo | None¶: Log reference for this stage, or None if unavailable.

property name: str¶: Display name of the stage.

property result: BuildRecordResult | None¶: Outcome once the stage has completed, or None if still running.

property start_time: datetime | None¶: When the stage started, or None if not yet started.

property state: BuildRecordState¶: Lifecycle state (pending, inProgress, completed).

property warning_count: int¶: Number of warnings logged by this stage.

class pyado.oop.build_timeline.BuildTask(record=None, *, job=None)¶

A single task step within a build job.

Wraps one Task-type timeline record. Instances are obtained from BuildJob.iter_tasks().

The job back-reference is always non-None for tasks obtained from BuildJob.iter_tasks(). The ActiveBuildTask subclass starts with job=None and provides get_job() instead.

Parameters:

record (BuildRecordInfo | None)
job (BuildJob | None)

_record¶: The raw timeline record for this task (None until _resolve() is called by a subclass).

_job¶: The parent BuildJob, or None for ActiveBuildTask.

property error_count: int¶: Number of errors logged by this task.

property finish_time: datetime | None¶: When the task finished, or None if not yet finished.

get_log_text()¶

Fetch the plain-text log content for this task.

Returns None when no log is associated with this task (i.e. log is None). Requires job to be set; tasks obtained from BuildJob.iter_tasks() always satisfy this.

Returns:: Log text, or None if no log is available.
Return type:: str | None

property id: UUID¶: Unique record ID for this task.

property info: BuildRecordInfo¶: Raw timeline record for direct inspection or raw-layer use.

property issues: list[BuildIssue]¶: List of issues (errors/warnings) reported by this task.

property job: BuildJob | None¶

Parent BuildJob — zero-cost.

Always non-None for tasks obtained from BuildJob.iter_tasks(). None for ActiveBuildTask instances (use get_job() instead).

property log: BuildLogInfo | None¶: Log reference for this task, or None if unavailable.

property name: str¶: Display name of the task.

property result: BuildRecordResult | None¶: Outcome once the task has completed, or None if still running.

property start_time: datetime | None¶: When the task started, or None if not yet started.

property state: BuildRecordState¶: Lifecycle state (pending, inProgress, completed).

property warning_count: int¶: Number of warnings logged by this task.

Active Build Task¶

OOP wrapper for an active (running) Azure DevOps pipeline task.

class pyado.oop.active_build_task.ActiveBuildTask(build, *, hub_name, plan_id, timeline_id, job_id, task_instance_id)¶

An active (running) task within an Azure DevOps pipeline.

Used by external systems acting as a serverless ADO task — for example an AWS Lambda function that polls an ADO pipeline for work. Inherits all read properties from BuildTask (loaded lazily on first access). Exposes the write operations (feed messages, log entries, timeline issue updates, task completion) that require the distributed-task runtime variables only available during pipeline execution.

Instances are obtained from Build.get_active_build_task().

The build timeline record is loaded lazily: the first access to any inherited property (e.g. .name, .state) triggers one API call to fetch the timeline records. Call refresh() to discard the cached record and re-fetch on the next access.

send_feed and send_log use the 7.1-preview.1 API (preview). add_issues uses the stable 7.1 API.

Parameters:

build (Build)
hub_name (str)
plan_id (UUID)
timeline_id (UUID)
job_id (UUID)
task_instance_id (UUID)

_build¶: The Build this task belongs to.

_hub_name¶: Distributed-task hub name (e.g. "build").

_plan_id¶: The orchestration plan UUID.

_timeline_id¶: The timeline UUID.

_job_id¶: The job UUID.

_task_instance_id¶: UUID identifying this task instance.

_log_id¶: Lazily resolved task log ID.

add_issues(issues)¶

Append issues to this task’s timeline record.

Uses the stable 7.1 distributed-task API. Fetches the current record, merges in the new issues, then patches the timeline.

Parameters:: issues (list[BuildIssue]) – Issues to append to the task’s timeline record.
Return type:: None

property build: Build¶: Owning Build — zero-cost.

complete(*, succeeded)¶

Signal task completion to the pipeline.

Parameters:: succeeded (bool) – When True, reports success; otherwise reports failure.
Return type:: None

get_job()¶

Find and return the parent BuildJob for this task.

Fetches the build timeline (one API call via Build.iter_stages()) and returns the BuildJob whose ID matches the job ID supplied at construction. The returned BuildJob has its full parent chain populated (job.stage, job.stage.build, etc.).

Returns:: BuildJob for the job that owns this task.
Raises:: ValueError – If the job is not found in the build timeline.
Return type:: BuildJob

get_record()¶

Fetch the timeline record for this task (always fresh).

Fetches all timeline records for the build (one API call) and returns the Task-type record whose ID matches _task_instance_id. The result is cached by _resolve(); call refresh() to invalidate the cache.

Returns:: BuildRecordInfo for this task.
Raises:: ValueError – If no matching task record is found.
Return type:: BuildRecordInfo

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

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

refresh()¶

Discard the cached timeline record and log ID.

The next access to any inherited property (e.g. .name, .state) will re-fetch the timeline records from the API.

Return type:: None

send_feed(messages)¶

Send messages to the task’s live feed.

Uses the 7.1-preview.1 distributed-task API.

Parameters:: messages (list[str]) – Log lines to append to the feed.
Return type:: None

send_log(message)¶

Append a message to the task’s persistent log.

Uses the 7.1-preview.1 distributed-task API. The log ID is resolved lazily on first call and then cached; call refresh() to clear the cache.

Parameters:: message (str) – Text to append to the task log.
Return type:: None

send_message(messages)¶

Send messages to both the task feed and the task log.

Uses the 7.1-preview.1 distributed-task API for both operations. All messages are joined with newlines into a single log entry.

Breaking change: previously each message was sent as a separate log entry; now all messages are combined into one post_job_logs call.

Parameters:: messages (list[str]) – Log lines to append to both feed and persistent log.
Return type:: None

Raw API¶

Core¶

HTTP client infrastructure and shared primitive types for pyado.raw submodules.

pyado.raw._core.ADOUrl¶

Validated HTTPS URL accepted by ADO API calls (max 256 characters).

alias of Annotated[HttpUrl, UrlConstraints(max_length=256, allowed_schemes=[‘https’], host_required=None, default_host=None, default_port=None, default_path=None, preserve_empty_path=None)]

pyado.raw._core.AccessToken¶: alias of str

class pyado.raw._core.ApiCall(*, access_token, parameters={}, session=None, timeout=10, url)¶

Class to call Azure DevOps APIs.

Parameters:

access_token (str)
parameters (dict[str, int | str | bool])
session (Session | None)
timeout (Annotated[int, Gt(gt=0)])
url (Annotated[HttpUrl, UrlConstraints(max_length=256, 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)¶

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)

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)¶

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)

Return type:

Any

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 = {}¶: 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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw._core.get_session(access_token)¶

Return the cached session for the given access token.

Callers may use this to inject a custom SSL adapter (e.g. a truststore adapter) into the session before the first API call is made.

Parameters:: access_token (str) – ADO personal access token or OAuth token.
Returns:: The requests.Session that pyado uses for all calls with this token.
Return type:: Session

Build¶

Azure DevOps Build API wrappers: builds, timelines, artifacts, pipeline defs.

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.build.BuildAttemptInfo(*, attempt, timelineId, recordId)¶

Type to store build attempt details.

Parameters:

attempt (int)
timelineId (UUID)
recordId (UUID)

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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=[], 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 (str | None)
priority (str | 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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.build.BuildExpand(value)¶: Expand options for build fetch requests.

pyado.raw.build.BuildId¶: alias of int

class pyado.raw.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 = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.build.BuildIssueType(value)¶: Severity types for a build issue.

pyado.raw.build.BuildLogId¶: alias of int

class pyado.raw.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=256, 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 = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.build.BuildLogType(value)¶: Log container types returned by the build log endpoint.

class pyado.raw.build.BuildQueueRequest(*, definition_id, source_branch=None, source_version=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:

definition_id (int)
source_branch (str | None)
source_version (str | None)
parameters (dict[str, str] | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 (Any)
details (Any)
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 = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.build.BuildRecordResult(value)¶: Outcome values for a single timeline record within a build.

class pyado.raw.build.BuildRecordState(value)¶: Lifecycle state values for a single timeline record within a build.

class pyado.raw.build.BuildRecordType(value)¶: Timeline record types present in a build’s timeline.

class pyado.raw.build.BuildRecordTypeInfo(*, id, name, version)¶

Type to store build task type details.

Parameters:

id (UUID)
name (str)
version (str)

model_config = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.build.BuildResult(value)¶: Possible outcome values for a completed build.

class pyado.raw.build.BuildSearchCriteria(*, definition_id=None, status_filter=None, branch_name=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:

definition_id (int | None)
status_filter (BuildStatus | None)
branch_name (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.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.build.BuildStatus(value)¶: Possible build status values used to filter or inspect a build.

class pyado.raw.build.PipelineDefinitionInfo(*, id, name, path, queueStatus, revision)¶

Type to store pipeline definition details.

Parameters:

id (int)
name (str)
path (str)
queueStatus (str)
revision (int)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.build.PlanId¶: alias of UUID

pyado.raw.build.QueueId¶: alias of int

pyado.raw.build.TaskId¶: alias of UUID

pyado.raw.build.TimelineId¶: alias of UUID

pyado.raw.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.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.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.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:

BuildDetails

pyado.raw.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.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.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.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.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.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.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.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.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.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:

BuildDetails

pyado.raw.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:

BuildDetails

pyado.raw.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]

Git¶

Azure DevOps Git repository, commit, ref, diff, and push API wrappers.

class pyado.raw.git.AccessControlEntry(*, descriptor, allow, deny)¶

A single access control entry granting or denying permissions.

Parameters:

descriptor (str)
allow (int)
deny (int)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.AccessControlList(*, token, inheritanceDeny=0, entries={})¶

An access control list for a git security token.

Parameters:

token (str)
inheritanceDeny (int)
entries (dict[str, AccessControlEntry])

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.git.BranchName¶: alias of str

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.CommitDiffPage(*, changes=[], allChangesIncluded=True)¶

One page of results from the diffs/commits endpoint.

Parameters:

changes (list[GitCommitChange])
allChangesIncluded (bool)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.git.CommitId¶: alias of str

pyado.raw.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.git.GitChangeType(value)¶: Operation type for a single file change (push, diff, or PR iteration).

class pyado.raw.git.GitCommitChange(*, changeType, item)¶

A single change entry in a commit diff.

Parameters:

changeType (str)
item (GitCommitChangeItem)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitCommitChangeItem(*, path, isFolder=False)¶

The item (file or folder) affected by a single commit change.

Parameters:

path (str)
isFolder (bool)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitCommitRef(*, commitId, comment=None, commentTruncated=False, author=None, committer=None, parents=[], url=None, changeCounts=None, statuses=[], work_items=[])¶

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])
work_items (list[WorkItemRef])

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitCommitSearchCriteria(*, item_path=None, item_version=None, item_version_type=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:

item_path (str | None)
item_version (str | None)
item_version_type (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.git.VersionDescriptorType | None

top¶

Maximum number of commits to return.

Type:: int | None

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 (str)
path (str)
url (str | None)
isFolder (bool)
isSymLink (bool)
commitId (str | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitPushChange(*, change_type, item, new_content=None, source_server_item=None)¶

A single file change within a push commit.

Parameters:

change_type (GitChangeType)
item (GitPushChangeItem)
new_content (GitPushNewContent | None)
source_server_item (str | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitPushChangeItem(*, path)¶

An item path within a push change.

Parameters:: path (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitPushCommit(*, comment, changes)¶

A commit payload within a push request.

Parameters:

comment (str)
changes (list[GitPushChange])

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitPushContentType(value)¶: Content encoding for new file content in a git push.

class pyado.raw.git.GitPushNewContent(*, content, content_type=GitPushContentType.RAWTEXT)¶

New file content within a push change.

Parameters:

content (str)
content_type (GitPushContentType)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitPushRefUpdate(*, name, old_object_id)¶

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)
old_object_id (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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitPushRequest(*, ref_updates, 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:

ref_updates (list[GitPushRefUpdate])
commits (list[GitPushCommit])

ref_updates¶

One entry per ref being updated. See GitPushRefUpdate for details.

Type:: list[pyado.raw.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.git.GitPushCommit]

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitPushResult(*, pushId, commits)¶

The result of a successful push operation.

Parameters:

pushId (int)
commits (list[GitCommitRef])

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitRef(*, name, objectId)¶

A git ref (branch or tag) entry returned by the refs endpoint.

Parameters:

name (str)
objectId (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitRefFilter(*, name_filter=None, name_contains=None)¶

Filter criteria for listing git refs.

All fields are optional; only non-None values are forwarded as query parameters.

Parameters:

name_filter (str | None)
name_contains (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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitRefUpdate(*, name, new_object_id, old_object_id)¶

A ref update operation for creating, updating, or deleting a branch or tag.

Parameters:

name (str)
new_object_id (str)
old_object_id (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.GitStatusState(value)¶: Possible state values for a git commit or pull request status.

class pyado.raw.git.PullRequestStatusContext(*, name, genre=None)¶

The context identifier for a git or pull request status.

Parameters:

name (str)
genre (str | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.git.RecursionLevel(value)¶: Recursion depth for repository items listing.

pyado.raw.git.RepositoryId¶: alias of UUID

class pyado.raw.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=256, 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=256, 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=256, 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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.git.RepositoryName¶: alias of str

pyado.raw.git.SshUrl¶: alias of str

class pyado.raw.git.VersionDescriptorType(value)¶: Version type for item-version descriptors in git API queries.

pyado.raw.git.ZERO_SHA: str = '0000000000000000000000000000000000000000'¶: Null commit SHA used to represent a non-existent ref (e.g. deleting a branch).

pyado.raw.git.create_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.git.delete_tag(repository_api_call, name, commit_id)¶

Delete a 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.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.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.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.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.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.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.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.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.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.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.git.iter_repository_items(repository_api_call, scope_path='/', *, branch=None, recursion_level=RecursionLevel.ONE_LEVEL)¶

Iterate over items at scope_path in the repository.

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, 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]

pyado.raw.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.git.list_repository_items(repository_api_call, scope_path='/', *, branch=None, recursion_level=RecursionLevel.ONE_LEVEL)¶

Return items at scope_path as a list.

Parameters:

repository_api_call (ApiCall)
scope_path (str)
branch (str | None)
recursion_level (RecursionLevel)

Return type:

list[GitItem]

pyado.raw.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.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.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.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

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.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.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.identity.get_vssps_api_call(access_token, 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:

access_token (str) – ADO personal access token or OAuth token.
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.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]

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).

class pyado.raw.pipeline.JobEventName(value)¶: Event name sent to the job completion endpoint.

class pyado.raw.pipeline.JobEventPayload(*, name, task_id, job_id, result)¶

Payload for the job event (task completed) endpoint.

Parameters:

name (JobEventName)
task_id (UUID)
job_id (UUID)
result (JobEventResult)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipeline.JobEventResult(value)¶: Outcome value reported with a job completion event.

class pyado.raw.pipeline.JobFeedPayload(*, value, count)¶

Payload for the job feed (append timeline record feed) endpoint.

Parameters:

value (list[str])
count (int)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipeline.JobId¶: alias of UUID

class pyado.raw.pipeline.PipelineApproval(*, id, status, steps=[], instructions=None, blockedApprovers=[], 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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipeline.PipelineApprovalStatus(value)¶: Possible status values for a pipeline approval step.

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipeline.PipelineApprovalUpdateRequest(*, approval_id, status, comment='')¶

Request body item for patching a pipeline environment approval.

Parameters:

approval_id (str)
status (PipelineApprovalStatus)
comment (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pipeline.PipelineId¶: alias of int

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipeline.PipelineResourcePermissions(*, resource=None, allPipelines=None, pipelines=[])¶

Resource-level permissions response from the pipelinepermissions endpoint.

Parameters:

resource (PipelinePermissionEntry | None)
allPipelines (PipelinePermissionEntry | None)
pipelines (list[PipelinePermissionEntry])

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipeline.PipelineResourceType(value)¶: Resource type values for the pipeline resource permissions endpoint.

class pyado.raw.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, Any] | None)
variables (dict[str, VariableInfo] | None)
finalYaml (str | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipeline.PipelineRunRequest(*, resources=None, variables=None, template_parameters=None, stages_to_skip=None)¶

Request body for triggering a pipeline run.

Parameters:

resources (dict[str, Any] | None)
variables (dict[str, Any] | None)
template_parameters (dict[str, str] | None)
stages_to_skip (list[str] | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pipeline.PipelineRunResult(value)¶: Possible outcome values for a completed pipeline run.

class pyado.raw.pipeline.PipelineRunState(value)¶: Possible lifecycle states of a pipeline run.

class pyado.raw.pipeline.TimelineRecordsUpdatePayload(*, count, value)¶

Payload for the update timeline records endpoint.

Parameters:

count (int)
value (list[BuildRecordInfo])

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.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.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.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.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.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.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.pipeline.iter_approvals(project_api_call, state=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.

Yields:

PipelineApproval for each matching approval.

Return type:

Iterator[PipelineApproval]

pyado.raw.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.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.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.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.pipeline.patch_timeline_records(timeline_api_call, payload)¶

Update the timeline records.

Parameters:

timeline_api_call (ApiCall)
payload (TimelineRecordsUpdatePayload)

Return type:

None

pyado.raw.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.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.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.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

Profile¶

Azure DevOps user profile API wrappers.

class pyado.raw.profile.ConnectionData(*, authenticatedUser)¶

Response from GET /_apis/connectionData.

Parameters:: authenticatedUser (ConnectionDataIdentity)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.profile.ConnectionDataIdentity(*, id, providerDisplayName)¶

Minimal identity record returned inside the connectionData response.

Parameters:

id (str)
providerDisplayName (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.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.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.profile.get_profile_api_call(access_token)¶

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:: access_token (str) – ADO personal access token or OAuth token.
Returns:: ApiCall targeting https://app.vssps.visualstudio.com/_apis.
Return type:: ApiCall

Project¶

Azure DevOps project API wrappers.

pyado.raw.project.ProjectId¶: alias of UUID

class pyado.raw.project.ProjectInfo(*, id, name, description=None, state, revision, visibility, lastUpdateTime)¶

Type to store project details.

Parameters:

id (UUID)
name (str)
description (str | None)
state (ProjectState)
revision (int)
visibility (ProjectVisibility)
lastUpdateTime (datetime)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.project.ProjectName¶: alias of str

class pyado.raw.project.ProjectState(value)¶: Possible lifecycle states of an ADO project.

class pyado.raw.project.ProjectVisibility(value)¶: Visibility settings for an ADO project.

pyado.raw.project.get_project(org_api_call, name)¶

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.

Returns:

ProjectInfo for the requested project.

Return type:

ProjectInfo

pyado.raw.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]

Pull Request¶

Azure DevOps pull request API wrappers.

class pyado.raw.pull_request.CommitIdRef(*, commit_id)¶

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:: commit_id (str)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PrIterationChange(*, changeType, item)¶

A single file change entry from a PR iteration changes response.

Parameters:

changeType (GitChangeType)
item (PrIterationChangeItem)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PrIterationChangeItem(*, path=None, url=None)¶

A file-level item in a PR iteration change entry.

Parameters:

path (str | None)
url (AnyUrl | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {'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.pull_request.PullRequestCreateRequest(*, title, source_ref_name, target_ref_name, completion_options, description=None, work_item_refs=None)¶

Request body for creating a new pull request.

Parameters:

title (str)
source_ref_name (str)
target_ref_name (str)
completion_options (PullRequestCompletionOptions)
description (str | None)
work_item_refs (list[WorkItemRef] | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.pull_request.PullRequestId¶: alias of int

pyado.raw.pull_request.PullRequestIteration¶: alias of int

class pyado.raw.pull_request.PullRequestIterationContext(*, firstComparingIteration, secondComparingIteration)¶

The pair of PR iterations being compared when a thread was created.

Parameters:

firstComparingIteration (int)
secondComparingIteration (int)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestListItem(*, pullRequestId, repository, title=None, description=None, sourceRefName=None, targetRefName=None, createdBy=None, creationDate=None, status=None, isDraft=False, mergeStatus=None, reviewers=[], labels=[], 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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestMergeFailureType(value)¶: Reason a pull request merge failed.

class pyado.raw.pull_request.PullRequestMergeStatus(value)¶: Current merge status of a pull request.

class pyado.raw.pull_request.PullRequestMergeStrategy(value)¶: Merge strategies available when completing a pull request.

class pyado.raw.pull_request.PullRequestResponse(*, pullRequestId, repository, status, url, title, sourceRefName, targetRefName, isDraft=False, createdBy=None, creationDate=None, closedDate=None, closedBy=None, reviewers=[], mergeStatus=None, mergeId=None, lastMergeSourceCommit=None, lastMergeTargetCommit=None, lastMergeCommit=None, autoCompleteSetBy=None, completionOptions=None, labels=[], 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 (str | 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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestReviewer(*, id, displayName, vote=0, isRequired=False, hasDeclined=False, isFlagged=False)¶

A reviewer entry on a pull request.

Parameters:

id (str)
displayName (str)
vote (int)
isRequired (bool)
hasDeclined (bool)
isFlagged (bool)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestReviewerRequest(*, vote=PullRequestVote.NO_VOTE, is_required=False, is_reapprove=False)¶

Request body for adding or updating a reviewer on a pull request.

Parameters:

vote (PullRequestVote)
is_required (bool)
is_reapprove (bool)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestReviewerVoteRequest(*, vote, is_reapprove=False)¶

Request body for setting a reviewer’s vote on a pull request.

Parameters:

vote (PullRequestVote)
is_reapprove (bool)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestSearchCriteria(*, status=None, creator_id=None, reviewer_id=None, source_ref_name=None, target_ref_name=None, repository_id=None, pull_request_id=None, source_version=None, min_time=None, max_time=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)
creator_id (str | None)
reviewer_id (str | None)
source_ref_name (str | None)
target_ref_name (str | None)
repository_id (str | None)
pull_request_id (int | None)
source_version (str | None)
min_time (datetime | None)
max_time (datetime | None)

status¶

Filter by PR lifecycle state.

Type:: pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestStatus(value)¶: Lifecycle state of a pull request.

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestStatusRequest(*, context, description=None, iteration_id, state, target_url=None)¶

Request body for posting a status item on a pull request.

Parameters:

context (PullRequestStatusContext)
description (str | None)
iteration_id (int)
state (PullRequestStatusState)
target_url (AnyUrl | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestStatusState(value)¶: Possible state values for a PR status check.

class pyado.raw.pull_request.PullRequestThreadCommentRequest(*, comment_type, content, parent_comment_id)¶

Type for storing a pull request comment.

Parameters:

comment_type (PullRequestThreadCommentType)
content (str)
parent_comment_id (int)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 (str | None)
parentCommentId (int)
author (_IdentityRef | None)
publishedDate (datetime | None)
lastUpdatedDate (datetime | None)
lastContentUpdatedDate (datetime | None)
isDeleted (bool)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestThreadCommentType(value)¶: ADO comment type values used when creating thread comments.

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestThreadRequest(*, comments, status, thread_context=None)¶

Request body for creating a new review thread on a pull request.

Parameters:

comments (list[PullRequestThreadCommentRequest])
status (PullRequestThreadStatus)
thread_context (PullRequestThreadContext | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestThreadResponse(*, id=None, status=None, comments=[], 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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestThreadStatus(value)¶: Possible status values for a PR review thread.

class pyado.raw.pull_request.PullRequestUpdateRequest(*, title=None, description=None, status=None, is_draft=None, completion_options=None, last_merge_source_commit=None, work_item_refs=None, auto_complete_set_by=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)
is_draft (bool | None)
completion_options (PullRequestCompletionOptions | None)
last_merge_source_commit (CommitIdRef | None)
work_item_refs (list[WorkItemRef] | None)
auto_complete_set_by (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.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.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.pull_request.CommitIdRef | None

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.pull_request.PullRequestVote(value)¶: Reviewer vote values for a pull request.

class pyado.raw.pull_request.RepositoryRef(*, id, name=None)¶

Minimal repository reference as returned in PR list responses.

Parameters:

id (UUID)
name (str | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.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.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.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.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.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 PrIterationChange from the changeEntries key of the API response.

Return type:

list[PrIterationChange]

pyado.raw.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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

Team¶

Azure DevOps Teams API wrappers.

class pyado.raw.team.TeamInfo(*, id, name, description=None, url=None)¶

An Azure DevOps team within a project.

Parameters:

id (str)
name (str)
description (str | None)
url (str | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.team.TeamMember(*, identity, isTeamAdmin=False)¶

A single member of an Azure DevOps team.

Parameters:

identity (_IdentityRef)
isTeamAdmin (bool)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.team.get_team(org_api_call, project_name, team_name_or_id)¶

Return a specific team by name or ID.

See iter_teams() for an explanation of why an organisation-level ApiCall is required rather than a project-scoped one.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call (from AzureDevOpsService.api_call).
project_name (str) – Name of the project.
team_name_or_id (str) – Team name or UUID string.

Returns:

TeamInfo for the requested team.

Return type:

TeamInfo

pyado.raw.team.iter_team_members(org_api_call, project_id, team_id)¶

Iterate over all members of a team.

The ADO team-members endpoint is GET {org}/_apis/projects/{project}/teams/{team}/members. An organisation-level ApiCall is required because the project and team identifiers both sit under /_apis/.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call (from AzureDevOpsService.api_call).
project_id (str) – Project name or UUID string.
team_id (str) – Team name or UUID string.

Yields:

TeamMember for each member of the team.

Return type:

Iterator[TeamMember]

pyado.raw.team.iter_teams(org_api_call, project_name)¶

Iterate over all teams in a project.

The ADO teams endpoint is GET {org}/_apis/projects/{project}/teams. The project identifier sits under /_apis/, so a project-scoped ApiCall (whose base URL is {org}/{project}/_apis) cannot be used here — it would produce the wrong path {org}/{project}/_apis/teams. An organisation-level ApiCall is required so that project_name can be appended after /_apis/projects/.

Parameters:

org_api_call (ApiCall) – Organisation-level ADO API call (from AzureDevOpsService.api_call).
project_name (str) – Name of the project.

Yields:

TeamInfo for each team in the project.

Return type:

Iterator[TeamInfo]

Variable Group¶

Azure DevOps distributed task variable group API wrappers.

pyado.raw.variable_group.UserId¶: alias of UUID

class pyado.raw.variable_group.VariableGroupCreateRequest(*, name, variables, variable_group_project_references, description=None, type='Vsts', provider_data=None)¶

Request body for creating a variable group.

Parameters:

name (str)
variables (dict[str, VariableInfo])
variable_group_project_references (list[VariableGroupProjectReference])
description (str | None)
type (str)
provider_data (Any)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.variable_group.VariableGroupId¶: alias of int

class pyado.raw.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 = {'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.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.variable_group.VariableGroupUpdateRequest(*, name, variables, variable_group_project_references=None, description=None, type=None, provider_data=None)¶

Request body for updating a variable group.

Parameters:

name (str)
variables (dict[str, VariableInfo])
variable_group_project_references (list[VariableGroupProjectReference] | None)
description (str | None)
type (str | None)
provider_data (Any)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {'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.variable_group.VariableInfo(*, isSecret=False, value=None)¶

Type to store information about variables.

Parameters:

isSecret (bool)
value (str | None)

model_config = {'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.variable_group.delete_variable_group(variable_group_api_call)¶

Delete a variable group.

Parameters:: variable_group_api_call (ApiCall) – Variable-group-level ADO API call (from get_variable_group_api_call).
Return type:: None

pyado.raw.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.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.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.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.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

Work Item¶

Azure DevOps work item, WIQL, sprint, and attachment API wrappers.

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.work_item.ClassificationNodeAttributes(*, startDate=None, finishDate=None)¶

Date attributes of a classification node (sprint iteration).

Parameters:

startDate (str | None)
finishDate (str | None)

model_config = {'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.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.work_item.ClassificationNodeRequest(*, name, attributes=None)¶

Request body for creating a classification node.

Parameters:

name (str)
attributes (ClassificationNodeAttributes | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.work_item.ClassificationNodeType(value)¶: Discriminates iteration nodes from area nodes in the classification tree.

class pyado.raw.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.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.work_item.SprintIterationId¶: alias of UUID

class pyado.raw.work_item.SprintIterationInfo(*, id, name, path, attributes)¶

Type to store sprint information.

Parameters:

id (UUID)
name (str)
path (str)
attributes (SprintIterationAttributes)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.work_item.SprintIterationPath¶: alias of str

class pyado.raw.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.work_item.TeamFieldValue(*, value, includeChildren)¶

A single team area-path field value.

Parameters:

value (str)
includeChildren (bool)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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.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}".

class pyado.raw.work_item.WorkItemAttachmentRef(*, id, url)¶

A reference to a file attachment uploaded to ADO.

Parameters:

id (str)
url (AnyUrl)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 (str | None)

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.work_item.WorkItemExpand(value)¶: Expand options for work item fetch requests.

pyado.raw.work_item.WorkItemField¶: alias of str

class pyado.raw.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"})

pyado.raw.work_item.WorkItemId¶: alias of int

class pyado.raw.work_item.WorkItemInfo(*, id, rev=None, url=None, fields, relations=[])¶

Type to store work item details.

Parameters:

id (int)
rev (int | None)
url (AnyUrl | None)
fields (dict[str, Any])
relations (list[WorkItemRelation])

model_config = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.work_item.WorkItemQuery(*, id, name, path=None, isFolder=False, hasChildren=False, children=[], 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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.work_item.WorkItemQueryExpand(value)¶

Expand options for WIT query fetch requests.

These are OData $expand values used with GET wit/queries.

class pyado.raw.work_item.WorkItemQueryType(value)¶: The structural type of a WIT saved query.

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class pyado.raw.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.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.work_item.WorkItemType(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: WorkItemType.BUG,
    WorkItemFieldName.TITLE: "Something is broken",
})

class pyado.raw.work_item.WorkItemsBatchRequest(*, 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 = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

pyado.raw.work_item.add_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.work_item.create_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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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: