pyado 0.3.2__tar.gz → 0.3.3__tar.gz

{pyado-0.3.2 → pyado-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyado
-Version: 0.3.2
+Version: 0.3.3
 Summary: Typed, Pydantic-backed wrappers and Pythonic convenience methods for the Azure DevOps REST API
 Keywords: azure,devops,ado,api,pydantic,azure-devops
 Author: Fred Stober

{pyado-0.3.2 → pyado-0.3.3}/pyproject.toml

@@ -44,7 +44,7 @@ license = "MIT"
 name = "pyado"
 readme = "README.md"
 requires-python = ">=3.11"
-version = "0.3.2"
+version = "0.3.3"
 
 [project.urls]
 "Bug Tracker" = "https://github.com/fredstober/pyado/issues"

{pyado-0.3.2 → pyado-0.3.3}/src/pyado/__init__.py

@@ -142,6 +142,8 @@ __all__ = [
     "WorkItemRef",
     "WorkItemRelation",
     "WorkItemRelationType",
+    "WorkItemState",
+    "WorkItemType",
     "WorkItemsBatchRequest",
     "abandon_pr",
     "add_file",
@@ -198,13 +200,13 @@ __all__ = [
     "get_work_item",
     "get_work_item_api_call",
     "get_work_item_tags",
+    "iter_active_prs",
     "iter_approvals",
     "iter_build_artifacts",
     "iter_build_tags",
     "iter_build_work_item_ids",
     "iter_builds",
     "iter_commit_diff",
-    "iter_open_prs",
     "iter_pending_approvals",
     "iter_pipeline_definitions",
     "iter_pipeline_runs",
@@ -348,13 +350,13 @@ from pyado.high import (
     get_work_item_tags as get_work_item_tags,
 )
 from pyado.high import (
-    iter_build_work_item_ids as iter_build_work_item_ids,
+    iter_active_prs as iter_active_prs,
 )
 from pyado.high import (
-    iter_commit_diff as iter_commit_diff,
+    iter_build_work_item_ids as iter_build_work_item_ids,
 )
 from pyado.high import (
-    iter_open_prs as iter_open_prs,
+    iter_commit_diff as iter_commit_diff,
 )
 from pyado.high import (
     iter_pending_approvals as iter_pending_approvals,
@@ -821,6 +823,12 @@ from pyado.raw import (
 from pyado.raw import (
     WorkItemsBatchRequest as WorkItemsBatchRequest,
 )
+from pyado.raw import (
+    WorkItemState as WorkItemState,
+)
+from pyado.raw import (
+    WorkItemType as WorkItemType,
+)
 from pyado.raw import (
     add_team_iteration as add_team_iteration,
 )

{pyado-0.3.2 → pyado-0.3.3}/src/pyado/high/__init__.py

@@ -55,9 +55,9 @@ __all__ = [
     "get_last_commit_touching_file",
     "get_pr_labels",
     "get_work_item_tags",
+    "iter_active_prs",
     "iter_build_work_item_ids",
     "iter_commit_diff",
-    "iter_open_prs",
     "iter_pending_approvals",
     "iter_pr_work_item_ids",
     "iter_work_item_details",
@@ -163,7 +163,7 @@ from pyado.high.pull_request import (
     get_pr_labels as get_pr_labels,
 )
 from pyado.high.pull_request import (
-    iter_open_prs as iter_open_prs,
+    iter_active_prs as iter_active_prs,
 )
 from pyado.high.pull_request import (
     iter_pr_work_item_ids as iter_pr_work_item_ids,

{pyado-0.3.2 → pyado-0.3.3}/src/pyado/high/pull_request.py

@@ -53,7 +53,7 @@ __all__ = [
     "create_pr",
     "create_pr_thread",
     "get_pr_labels",
-    "iter_open_prs",
+    "iter_active_prs",
     "iter_pr_work_item_ids",
     "link_pr_work_item",
     "reply_to_pr_thread",
@@ -62,7 +62,7 @@ __all__ = [
 ]
 
 
-def iter_open_prs(
+def iter_active_prs(
     project_api_call: ApiCall,
     *,
     expand: str | None = None,

{pyado-0.3.2 → pyado-0.3.3}/src/pyado/high/work_item.py

@@ -120,15 +120,15 @@ class WorkItemLink:
 
     Artifact links (builds, commits, pull requests) use the ArtifactLink
     relation type with a ``vstfs://`` URL constructed from the supplied IDs.
-    Work item links (parent, child, related, etc.) require the target work
-    item's ``url`` field (available as ``WorkItemInfo.url``).
+    Work item links (parent, child, related, etc.) accept the target work
+    item's ID and project-level API call; the URL is constructed internally.
 
     Examples::
 
         # At creation time
         create_work_item(api, fields, relations=[
             WorkItemLink.build(build_id),
-            WorkItemLink.parent(str(parent_wi.url)),
+            WorkItemLink.parent(project_api, parent_wi_id),
         ])
 
         # On an existing work item
@@ -156,9 +156,13 @@ class WorkItemLink:
     @staticmethod
     def _wi_link(
         rel_type: WorkItemRelationType,
-        work_item_url: str,
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
         comment: str | None,
     ) -> WorkItemRelation:
+        work_item_url = get_work_item_api_call(
+            project_api_call, work_item_id
+        ).url.unicode_string()
         attributes: dict[str, Any] | None = (
             {"comment": comment} if comment is not None else None
         )
@@ -237,108 +241,165 @@ class WorkItemLink:
     # --- Work item links ---
 
     @staticmethod
-    def related(work_item_url: str, *, comment: str | None = None) -> WorkItemRelation:
+    def related(
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
+    ) -> WorkItemRelation:
         """Return a Related link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.RELATED, work_item_url, comment
+            WorkItemRelationType.RELATED, project_api_call, work_item_id, comment
         )
 
     @staticmethod
-    def parent(work_item_url: str, *, comment: str | None = None) -> WorkItemRelation:
+    def parent(
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
+    ) -> WorkItemRelation:
         """Return a Parent (Hierarchy-Reverse) link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.PARENT, work_item_url, comment
+            WorkItemRelationType.PARENT, project_api_call, work_item_id, comment
         )
 
     @staticmethod
-    def child(work_item_url: str, *, comment: str | None = None) -> WorkItemRelation:
+    def child(
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
+    ) -> WorkItemRelation:
         """Return a Child (Hierarchy-Forward) link to another work item."""
-        return WorkItemLink._wi_link(WorkItemRelationType.CHILD, work_item_url, comment)
+        return WorkItemLink._wi_link(
+            WorkItemRelationType.CHILD, project_api_call, work_item_id, comment
+        )
 
     @staticmethod
     def duplicate(
-        work_item_url: str, *, comment: str | None = None
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
     ) -> WorkItemRelation:
         """Return a Duplicate-Forward link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.DUPLICATE, work_item_url, comment
+            WorkItemRelationType.DUPLICATE, project_api_call, work_item_id, comment
         )
 
     @staticmethod
     def duplicate_of(
-        work_item_url: str, *, comment: str | None = None
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
     ) -> WorkItemRelation:
         """Return a Duplicate-Reverse link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.DUPLICATE_OF, work_item_url, comment
+            WorkItemRelationType.DUPLICATE_OF,
+            project_api_call,
+            work_item_id,
+            comment,
         )
 
     @staticmethod
     def successor(
-        work_item_url: str, *, comment: str | None = None
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
     ) -> WorkItemRelation:
         """Return a Dependency-Forward (successor) link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.SUCCESSOR, work_item_url, comment
+            WorkItemRelationType.SUCCESSOR, project_api_call, work_item_id, comment
         )
 
     @staticmethod
     def predecessor(
-        work_item_url: str, *, comment: str | None = None
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
     ) -> WorkItemRelation:
         """Return a Dependency-Reverse (predecessor) link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.PREDECESSOR, work_item_url, comment
+            WorkItemRelationType.PREDECESSOR, project_api_call, work_item_id, comment
         )
 
     @staticmethod
     def tested_by(
-        work_item_url: str, *, comment: str | None = None
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
     ) -> WorkItemRelation:
         """Return a TestedBy-Forward link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.TESTED_BY, work_item_url, comment
+            WorkItemRelationType.TESTED_BY, project_api_call, work_item_id, comment
         )
 
     @staticmethod
-    def tests(work_item_url: str, *, comment: str | None = None) -> WorkItemRelation:
+    def tests(
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
+    ) -> WorkItemRelation:
         """Return a TestedBy-Reverse (tests) link to another work item."""
-        return WorkItemLink._wi_link(WorkItemRelationType.TESTS, work_item_url, comment)
+        return WorkItemLink._wi_link(
+            WorkItemRelationType.TESTS, project_api_call, work_item_id, comment
+        )
 
     @staticmethod
     def test_case(
-        work_item_url: str, *, comment: str | None = None
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
     ) -> WorkItemRelation:
-        """Return a SharedParameterReferencedBy-Forward link."""
+        """Return a TestCase-Forward link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.TEST_CASE, work_item_url, comment
+            WorkItemRelationType.TEST_CASE, project_api_call, work_item_id, comment
         )
 
     @staticmethod
     def shared_parameter_referenced_by(
-        work_item_url: str, *, comment: str | None = None
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
     ) -> WorkItemRelation:
         """Return a SharedParameterReferencedBy-Reverse link."""
         return WorkItemLink._wi_link(
             WorkItemRelationType.SHARED_PARAMETER_REFERENCED_BY,
-            work_item_url,
+            project_api_call,
+            work_item_id,
             comment,
         )
 
     @staticmethod
-    def affects(work_item_url: str, *, comment: str | None = None) -> WorkItemRelation:
+    def affects(
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
+    ) -> WorkItemRelation:
         """Return an Affects-Forward link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.AFFECTS, work_item_url, comment
+            WorkItemRelationType.AFFECTS, project_api_call, work_item_id, comment
         )
 
     @staticmethod
     def affected_by(
-        work_item_url: str, *, comment: str | None = None
+        project_api_call: ApiCall,
+        work_item_id: WorkItemId,
+        *,
+        comment: str | None = None,
     ) -> WorkItemRelation:
         """Return an Affects-Reverse (affected by) link to another work item."""
         return WorkItemLink._wi_link(
-            WorkItemRelationType.AFFECTED_BY, work_item_url, comment
+            WorkItemRelationType.AFFECTED_BY, project_api_call, work_item_id, comment
         )
 
     # --- Other links ---

{pyado-0.3.2 → pyado-0.3.3}/src/pyado/raw/__init__.py

@@ -139,6 +139,8 @@ __all__ = [
     "WorkItemRef",
     "WorkItemRelation",
     "WorkItemRelationType",
+    "WorkItemState",
+    "WorkItemType",
     "WorkItemsBatchRequest",
     "add_team_iteration",
     "create_classification_node",
@@ -836,6 +838,12 @@ from pyado.raw.work_item import (
 from pyado.raw.work_item import (
     WorkItemsBatchRequest as WorkItemsBatchRequest,
 )
+from pyado.raw.work_item import (
+    WorkItemState as WorkItemState,
+)
+from pyado.raw.work_item import (
+    WorkItemType as WorkItemType,
+)
 from pyado.raw.work_item import (
     add_team_iteration as add_team_iteration,
 )

{pyado-0.3.2 → pyado-0.3.3}/src/pyado/raw/work_item.py

@@ -33,6 +33,8 @@ __all__ = [
     "WorkItemRef",
     "WorkItemRelation",
     "WorkItemRelationType",
+    "WorkItemState",
+    "WorkItemType",
     "WorkItemsBatchRequest",
     "add_team_iteration",
     "create_classification_node",
@@ -93,6 +95,9 @@ class WorkItemFieldName(StrEnum):
     HYPERLINK_COUNT = "System.HyperLinkCount"
     EXTERNAL_LINK_COUNT = "System.ExternalLinkCount"
     RELATED_LINK_COUNT = "System.RelatedLinkCount"
+    # RemoteLinkCount tracks links to external work items (GitHub, etc.);
+    # available on Azure DevOps Services only.
+    REMOTE_LINK_COUNT = "System.RemoteLinkCount"
     TAGS = "System.Tags"
     BOARD_COLUMN = "System.BoardColumn"
     BOARD_COLUMN_DONE = "System.BoardColumnDone"
@@ -105,28 +110,137 @@ class WorkItemFieldName(StrEnum):
     BUSINESS_VALUE = "Microsoft.VSTS.Common.BusinessValue"
     TIME_CRITICALITY = "Microsoft.VSTS.Common.TimeCriticality"
     RISK = "Microsoft.VSTS.Common.Risk"
-    EFFORT = "Microsoft.VSTS.Common.Effort"
     ACTIVITY = "Microsoft.VSTS.Common.Activity"
+    # Discipline is the CMMI equivalent of Activity (Agile/Scrum).
+    DISCIPLINE = "Microsoft.VSTS.Common.Discipline"
     STACK_RANK = "Microsoft.VSTS.Common.StackRank"
     BACKLOG_PRIORITY = "Microsoft.VSTS.Common.BacklogPriority"
     CLOSED_DATE = "Microsoft.VSTS.Common.ClosedDate"
     CLOSED_BY = "Microsoft.VSTS.Common.ClosedBy"
+    ACTIVATED_BY = "Microsoft.VSTS.Common.ActivatedBy"
+    ACTIVATED_DATE = "Microsoft.VSTS.Common.ActivatedDate"
     RESOLVED_DATE = "Microsoft.VSTS.Common.ResolvedDate"
     RESOLVED_BY = "Microsoft.VSTS.Common.ResolvedBy"
     RESOLVED_REASON = "Microsoft.VSTS.Common.ResolvedReason"
     ACCEPTANCE_CRITERIA = "Microsoft.VSTS.Common.AcceptanceCriteria"
     STATE_CHANGE_DATE = "Microsoft.VSTS.Common.StateChangeDate"
+    # Triage is CMMI-only (Pending / More Info / Info Received / Triaged).
+    TRIAGE = "Microsoft.VSTS.Common.Triage"
+    # Resolution describes how a Scrum Impediment was resolved.
+    RESOLUTION = "Microsoft.VSTS.Common.Resolution"
     # --- Microsoft.VSTS.Scheduling fields ---
     REMAINING_WORK = "Microsoft.VSTS.Scheduling.RemainingWork"
     COMPLETED_WORK = "Microsoft.VSTS.Scheduling.CompletedWork"
     ORIGINAL_ESTIMATE = "Microsoft.VSTS.Scheduling.OriginalEstimate"
+    # Effort, StoryPoints, and Size are process-specific names for the same
+    # planning concept (all map to "Effort" in ProcessConfiguration).
+    # Scrum uses EFFORT; Agile uses STORY_POINTS; CMMI uses SIZE.
+    EFFORT = "Microsoft.VSTS.Scheduling.Effort"
     STORY_POINTS = "Microsoft.VSTS.Scheduling.StoryPoints"
+    SIZE = "Microsoft.VSTS.Scheduling.Size"
     START_DATE = "Microsoft.VSTS.Scheduling.StartDate"
     FINISH_DATE = "Microsoft.VSTS.Scheduling.FinishDate"
     TARGET_DATE = "Microsoft.VSTS.Scheduling.TargetDate"
     # --- Microsoft.VSTS.Build fields ---
     INTEGRATION_BUILD = "Microsoft.VSTS.Build.IntegrationBuild"
     FOUND_IN = "Microsoft.VSTS.Build.FoundIn"
+    # --- Microsoft.VSTS.TCM fields ---
+    REPRO_STEPS = "Microsoft.VSTS.TCM.ReproSteps"
+    # SystemInfo captures the OS/browser environment recorded at repro time
+    # (Bug work items, all process templates).
+    SYSTEM_INFO = "Microsoft.VSTS.TCM.SystemInfo"
+    # AutomationStatus tracks whether a test case is automated
+    # (Automated / Not Automated / Planned).
+    AUTOMATION_STATUS = "Microsoft.VSTS.TCM.AutomationStatus"
+    # --- Microsoft.VSTS.CMMI fields ---
+    # Note: despite the CMMI namespace, BLOCKED is also used by Scrum Tasks
+    # (same reference name across both process templates).
+    BLOCKED = "Microsoft.VSTS.CMMI.Blocked"
+    # Committed and Escalate are CMMI-only.
+    COMMITTED = "Microsoft.VSTS.CMMI.Committed"
+    ESCALATE = "Microsoft.VSTS.CMMI.Escalate"
+
+
+class WorkItemState(StrEnum):
+    """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"
+    """
+
+    # --- Agile (Epic, Feature, User Story, Bug, Task, Issue) ---
+    NEW = "New"  # Agile, Scrum
+    ACTIVE = "Active"  # Agile, CMMI
+    RESOLVED = "Resolved"  # Agile, CMMI
+    CLOSED = "Closed"  # Agile, CMMI
+    REMOVED = "Removed"  # Agile, Scrum
+
+    # --- Scrum (Product Backlog Item, Bug) ---
+    APPROVED = "Approved"
+    COMMITTED = "Committed"
+
+    # --- Scrum / Basic (Task, Epic, Feature) ---
+    TO_DO = "To Do"
+    IN_PROGRESS = "In Progress"
+    DONE = "Done"
+
+    # --- Basic only ---
+    DOING = "Doing"
+
+    # --- CMMI (Requirement, Change Request, Bug, Task, Issue, Risk, Review) ---
+    PROPOSED = "Proposed"
+
+
+class WorkItemType(StrEnum):
+    """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",
+        })
+    """
+
+    # --- Agile / Scrum / CMMI shared ---
+    EPIC = "Epic"
+    FEATURE = "Feature"
+    BUG = "Bug"
+    TASK = "Task"
+    TEST_CASE = "Test Case"
+    TEST_PLAN = "Test Plan"
+    TEST_SUITE = "Test Suite"
+    # --- Agile ---
+    USER_STORY = "User Story"
+    ISSUE = "Issue"
+    # --- Scrum ---
+    PRODUCT_BACKLOG_ITEM = "Product Backlog Item"
+    IMPEDIMENT = "Impediment"
+    # --- CMMI ---
+    REQUIREMENT = "Requirement"
+    CHANGE_REQUEST = "Change Request"
+    REVIEW = "Review"
+    RISK = "Risk"
 
 
 class WorkItemRelationType(StrEnum):