devopsdriver 0.1.32__tar.gz → 0.1.35__tar.gz

{devopsdriver-0.1.32 → devopsdriver-0.1.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: devopsdriver
-Version: 0.1.32
+Version: 0.1.35
 Summary: DevOps tools
 Author-email: Marc Page <marcallenpage@gmail.com>
 License: This is free and unencumbered software released into the public domain.
@@ -43,13 +43,20 @@ Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Utilities
 Classifier: Topic :: Software Development
-Requires-Python: >=3.12
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: PyYAML==6.0.1
+Requires-Dist: keyring==25.0.0
+Requires-Dist: setuptools==69.0.2
+Requires-Dist: azure-devops==7.1.0b4
 
 ![status sheild](https://img.shields.io/static/v1?label=status&message=starting...&color=inactive&style=plastic)
+[![status sheild](https://img.shields.io/static/v1?label=released&message=v0.1.35&color=active&style=plastic)](https://pypi.org/project/devopsdriver/0.1.35/)
 [![GitHub](https://img.shields.io/github/license/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver?tab=Unlicense-1-ov-file#readme)
+[![GitHub contributors](https://img.shields.io/github/contributors/marcpage/devops-driver?style=flat)](https://github.com/marcpage/devops-driver/graphs/contributors)
+[![PR's Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)
+
 [![commit sheild](https://img.shields.io/github/last-commit/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver/commits)
 [![activity sheild](https://img.shields.io/github/commit-activity/m/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver/commits)
 [![GitHub top language](https://img.shields.io/github/languages/top/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver)
@@ -59,8 +66,6 @@ Requires-Dist: PyYAML==6.0.1
 [![status sheild](https://img.shields.io/static/v1?label=test+coverage&message=99%&color=active&style=plastic)](https://github.com/marcpage/devops-driver/blob/main/Makefile#L4)
 [![issues sheild](https://img.shields.io/github/issues-raw/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver/issues)
 [![GitHub pull requests](https://img.shields.io/github/issues-pr/marcpage/devops-driver?style=flat)](https://github.com/marcpage/devops-driver/pulls)
-[![GitHub contributors](https://img.shields.io/github/contributors/marcpage/devops-driver?style=flat)](https://github.com/marcpage/devops-driver/graphs/contributors)
-[![PR's Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)
 
 [![follow sheild](https://img.shields.io/github/followers/marcpage?label=Follow&style=social)](https://github.com/marcpage?tab=followers)
 [![watch sheild](https://img.shields.io/github/watchers/marcpage/devops-driver?label=Watch&style=social)](https://github.com/marcpage/devops-driver/watchers)
@@ -68,3 +73,4 @@ Requires-Dist: PyYAML==6.0.1
 # devops-driver
 
 Devops-driver is a set of tools to help streamline developer's experience. It is a collection of tools to help gain insights into various processes.
+

{devopsdriver-0.1.32 → devopsdriver-0.1.35}/README.md

@@ -1,5 +1,9 @@
 ![status sheild](https://img.shields.io/static/v1?label=status&message=starting...&color=inactive&style=plastic)
+[![status sheild](https://img.shields.io/static/v1?label=released&message=v0.1.35&color=active&style=plastic)](https://pypi.org/project/devopsdriver/0.1.35/)
 [![GitHub](https://img.shields.io/github/license/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver?tab=Unlicense-1-ov-file#readme)
+[![GitHub contributors](https://img.shields.io/github/contributors/marcpage/devops-driver?style=flat)](https://github.com/marcpage/devops-driver/graphs/contributors)
+[![PR's Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)
+
 [![commit sheild](https://img.shields.io/github/last-commit/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver/commits)
 [![activity sheild](https://img.shields.io/github/commit-activity/m/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver/commits)
 [![GitHub top language](https://img.shields.io/github/languages/top/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver)
@@ -9,8 +13,6 @@
 [![status sheild](https://img.shields.io/static/v1?label=test+coverage&message=99%&color=active&style=plastic)](https://github.com/marcpage/devops-driver/blob/main/Makefile#L4)
 [![issues sheild](https://img.shields.io/github/issues-raw/marcpage/devops-driver?style=plastic)](https://github.com/marcpage/devops-driver/issues)
 [![GitHub pull requests](https://img.shields.io/github/issues-pr/marcpage/devops-driver?style=flat)](https://github.com/marcpage/devops-driver/pulls)
-[![GitHub contributors](https://img.shields.io/github/contributors/marcpage/devops-driver?style=flat)](https://github.com/marcpage/devops-driver/graphs/contributors)
-[![PR's Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat)](http://makeapullrequest.com)
 
 [![follow sheild](https://img.shields.io/github/followers/marcpage?label=Follow&style=social)](https://github.com/marcpage?tab=followers)
 [![watch sheild](https://img.shields.io/github/watchers/marcpage/devops-driver?label=Watch&style=social)](https://github.com/marcpage/devops-driver/watchers)
@@ -18,3 +20,4 @@
 # devops-driver
 
 Devops-driver is a set of tools to help streamline developer's experience. It is a collection of tools to help gain insights into various processes.
+

{devopsdriver-0.1.32 → devopsdriver-0.1.35}/devopsdriver/__init__.py

@@ -1,5 +1,7 @@
 """ DevOps tools """
 
-__version__ = "0.1.32"
+from .azure import Azure
+
+__version__ = "0.1.35"
 __author__ = "Marc Page"
 __credits__ = ""

devopsdriver-0.1.35/devopsdriver/azure/__init__.py

@@ -0,0 +1,10 @@
+""" initialize azure module """
+
+# re export symbols for easier use
+from .clients import Azure
+
+from .workitem import WorkItem
+from .workitem.wiql import Wiql, Value, Field
+from .workitem.wiql import Ascending, Descending, And, Or
+from .workitem.wiql import Equal, NotEqual, LessThanOrEqual, GreaterThanOrEqual
+from .workitem.wiql import IsEmpty, IsNotEmpty, LessThan, GreaterThan

devopsdriver-0.1.35/devopsdriver/azure/clients.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+
+
+""" Establish a connection to Azure Devops 
+
+API Documented here:
+https://github.com/microsoft/azure-devops-python-api
+"""
+
+from azure.devops.connection import Connection as AzureConnection
+from msrest.authentication import BasicAuthentication as MSBasicAuthentication
+
+from devopsdriver.settings import Settings
+from devopsdriver.azure.workitem.client import Client as WIClient
+
+CONNECTION = AzureConnection
+AUTHENTICATION = MSBasicAuthentication
+
+
+class Azure:  # pylint: disable=too-few-public-methods
+    """A connection to Azure clients"""
+
+    SUPPORTED_CLIENTS = {"workitem", "pipeline"}
+
+    def __init__(
+        self, settings: Settings = None, token: str = None, url: str = None, **clients
+    ):
+        unsupported_clients = set(clients) - Azure.SUPPORTED_CLIENTS
+        assert not unsupported_clients, f"{unsupported_clients} not supported"
+        settings = (
+            Settings(__file__).key("secrets")
+            if settings is None and token is None and url is None
+            else settings
+        )
+        assert (token or "azure.token" in settings) and (
+            url or "azure.url" in settings
+        ), "azure.token and azure.url not found in:\n" + "\n".join(
+            settings.search_files
+        )
+        url = settings["azure.url"] if url is None else url
+        token = settings["azure.token"] if token is None else token
+        self.connection = CONNECTION(base_url=url, creds=AUTHENTICATION("", token))
+        client_calls = {
+            "workitem": self.connection.clients_v7_1.get_work_item_tracking_client
+        }
+        self.workitem = WIClient(Azure.__client("workitem", clients, client_calls))
+
+    @staticmethod
+    def __client(name: str, clients: dict, calls: dict) -> any:
+        if clients and not clients.get(name, False):
+            return None
+
+        return calls[name]()

devopsdriver-0.1.35/devopsdriver/azure/workitem/__init__.py

@@ -0,0 +1,4 @@
+""" init workitem module """
+
+# Re-export symbols to make things make sense
+from .workitem import WorkItem

devopsdriver-0.1.35/devopsdriver/azure/workitem/client.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+
+""" Azure WorkItem Client """
+
+from azure.devops.v7_1.work_item_tracking.models import Wiql as AzureWiql
+from azure.devops.v7_1.work_item_tracking.models import WorkItem as AzureWorkItem
+from azure.devops.v7_1.work_item_tracking.models import TeamContext
+from azure.devops.v7_1.work_item_tracking.models import WorkItemQueryResult
+from devopsdriver.azure.workitem import WorkItem
+from devopsdriver.azure.workitem.wiql import Wiql
+
+
+class Client:
+    """Wraps work item client"""
+
+    def __init__(self, client):
+        self.client = client
+
+    def query(
+        self,
+        wiql: Wiql | str,
+        team_context: TeamContext = None,
+        time_precision: bool = None,
+        top: int = None,
+    ) -> WorkItemQueryResult:
+        """Perform a wiql query
+
+        Args:
+            wiql (Wiql | str): The query
+            team_context (TeamContext, optional): context object. Defaults to None.
+            time_precision (bool, optional): True for precision time. Defaults to None.
+            top (int, optional): Count of items to get. Defaults to None.
+
+        Returns:
+            WorkItemQueryResult: The results
+        """
+        return self.client.query_by_wiql(
+            AzureWiql(query=str(wiql)),
+            team_context=team_context,
+            time_precision=time_precision,
+            top=top,
+        )
+
+    def history(  # pylint: disable=too-many-arguments
+        self,
+        wi_id: int,
+        project: str = None,
+        top: int = None,
+        skip: int = None,
+        expand: str = None,
+    ) -> list[AzureWorkItem]:
+        """Simple wrapper around get_revisions"""
+        return self.client.get_revisions(wi_id, project, top, skip, expand)
+
+    def find_ids(self, wiql: Wiql | str, top: int = None) -> list[int]:
+        """Given a query, find the work item ids
+
+        Args:
+            wiql (Wiql | str): The query
+            top (int, optional): The number of results to return. Defaults to None.
+
+        Returns:
+            list: List of item ids
+        """
+        if isinstance(wiql, Wiql):
+            wiql.select("Id")
+
+        found = self.query(wiql, top=top)
+        # top-level items: as_of, columns, query_results_type, query_type, work_items
+        # work_items fields: id, url
+        # query_results_type: workItem
+        # query_type: flat
+        # columns: list of name, reference_name, url
+        return [i.id for i in found.work_items]
+
+    def find(self, wiql: Wiql | str, top: int = None) -> list[list[WorkItem]]:
+        """Gets the full history of items found in a WIQL search
+
+        Args:
+            wiql (Wiql | str): The query
+            top (int, optional): The number of work items to return. Defaults to None.
+
+        Returns:
+            list[list[WorkItem]]: List of work items, each is a history of work items
+        """
+        return [
+            [WorkItem(e) for e in self.history(i)] for i in self.find_ids(wiql, top)
+        ]

devopsdriver-0.1.35/devopsdriver/azure/workitem/wiql.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+
+""" Builds a WIQL query
+https://learn.microsoft.com/en-us/azure/devops/boards/queries/wiql-syntax?view=azure-devops
+
+SELECT
+    [System.Id],
+    [System.AssignedTo],
+    [System.State],
+    [System.Title],
+    [System.Tags]
+FROM workitems
+WHERE
+    [System.TeamProject] = 'Design Agile'
+    AND [System.WorkItemType] = 'User Story'
+    AND [System.State] = 'Active'
+ORDER BY [System.ChangedDate] DESC
+ASOF '02-11-2020'
+"""
+
+
+from datetime import datetime, date
+
+
+class Field:  # pylint: disable=too-few-public-methods
+    """column name"""
+
+    SYSTEM = {
+        "Id",
+        "AssignTo",
+        "State",
+        "Title",
+        "Tags",
+        "TeamProject",
+        "WorkItemType",
+        "ChangedDate",
+        "CreatedDate",
+    }
+    COMMON = {"Priority"}
+
+    def __init__(self, value: str):
+        self.value = value
+
+    def __str__(self) -> str:
+        if self.value in Field.SYSTEM:
+            prefix = "System."
+
+        elif self.value in Field.COMMON:
+            prefix = "Microsoft.VSTS.Common."
+
+        else:
+            prefix = ""
+
+        return f"[{prefix}{self.value}]"
+
+
+class OrderBy:  # pylint: disable=too-few-public-methods
+    """Order by field"""
+
+    def __init__(self, field: Field | str, order: str = "DESC"):
+        self.field = field if isinstance(field, Field) else Field(field)
+        self.order = order
+
+    def __str__(self) -> str:
+        return f"{self.field} {self.order}"
+
+
+class Ascending(OrderBy):  # pylint: disable=too-few-public-methods
+    """Order by field ascending"""
+
+    def __init__(self, field: Field | str):
+        super().__init__(field, "ASC")
+
+
+class Descending(OrderBy):  # pylint: disable=too-few-public-methods
+    """Order by field descending"""
+
+    def __init__(self, field: Field | str):
+        super().__init__(field, "DESC")
+
+
+class Value:  # pylint: disable=too-few-public-methods
+    """A constant value"""
+
+    def __init__(self, value: date | datetime | int | float | str):
+        self.value = value
+
+    def __str__(self) -> str:
+        if isinstance(self.value, datetime):
+            return self.value.strftime("%Y-%m-%d %H:%M:%S")
+
+        if isinstance(self.value, date):
+            return self.value.strftime("%Y-%m-%d")
+
+        if isinstance(self.value, int):
+            return str(self.value)
+
+        if isinstance(self.value, float):
+            return f"{self.value:0.3f}"
+
+        if isinstance(self.value, str):
+            return f'"{self.value}"'  # TODO: escape value  # pylint: disable=fixme
+
+        raise AssertionError("Unknown type")
+
+
+class IsEmpty:  # pylint: disable=too-few-public-methods
+    """Compare a field to a value"""
+
+    def __init__(self, field: Field | str):
+        self.field = field if isinstance(field, Field) else Field(field)
+
+    def __str__(self) -> str:
+        return f"{str(self.field)} IS EMPTY"
+
+
+class IsNotEmpty:  # pylint: disable=too-few-public-methods
+    """Compare a field to a value"""
+
+    def __init__(self, field: Field | str):
+        self.field = field if isinstance(field, Field) else Field(field)
+
+    def __str__(self) -> str:
+        return f"{str(self.field)} IS NOT EMPTY"
+
+
+class Compare:  # pylint: disable=too-few-public-methods
+    """Compare a field to a value"""
+
+    def __init__(
+        self,
+        field: Field | str,
+        value: Value | str | date | datetime | int | float,
+        operator: str,
+    ):
+        self.left = field if isinstance(field, Field) else Field(field)
+        self.right = value if isinstance(value, Value) else Value(value)
+        self.operator = operator
+
+    def __str__(self) -> str:
+        return f"{str(self.left)} {self.operator} {str(self.right)}"
+
+
+class Equal(Compare):  # pylint: disable=too-few-public-methods
+    """checks for equality"""
+
+    def __init__(
+        self, field: Field | str, value: Value | str | date | datetime | int | float
+    ):
+        super().__init__(field, value, "=")
+
+
+class NotEqual(Compare):  # pylint: disable=too-few-public-methods
+    """checks for equality"""
+
+    def __init__(
+        self, field: Field | str, value: Value | str | date | datetime | int | float
+    ):
+        super().__init__(field, value, "<>")
+
+
+class LessThan(Compare):  # pylint: disable=too-few-public-methods
+    """checks for lass than"""
+
+    def __init__(
+        self, field: Field | str, value: Value | str | date | datetime | int | float
+    ):
+        super().__init__(field, value, "<")
+
+
+class GreaterThan(Compare):  # pylint: disable=too-few-public-methods
+    """checks for greater than"""
+
+    def __init__(
+        self, field: Field | str, value: Value | str | date | datetime | int | float
+    ):
+        super().__init__(field, value, ">")
+
+
+class LessThanOrEqual(Compare):  # pylint: disable=too-few-public-methods
+    """checks for less than or equal"""
+
+    def __init__(
+        self, field: Field | str, value: Value | str | date | datetime | int | float
+    ):
+        super().__init__(field, value, "<=")
+
+
+class GreaterThanOrEqual(Compare):  # pylint: disable=too-few-public-methods
+    """checks for greater than or equal"""
+
+    def __init__(
+        self, field: Field | str, value: Value | str | date | datetime | int | float
+    ):
+        super().__init__(field, value, ">=")
+
+
+class Expression:  # pylint: disable=too-few-public-methods
+    """Join several compares"""
+
+    def __init__(self, operator: str, *compares: list[Compare]):
+        self.operator = operator
+        self.expressions = compares
+
+    def __str__(self) -> str:
+        return f" {self.operator} ".join(str(e) for e in self.expressions)
+
+
+class And(Expression):  # pylint: disable=too-few-public-methods
+    """Join compares via AND"""
+
+    def __init__(self, *compares: list[Compare | Expression]):
+        super().__init__("AND", *compares)
+
+
+class Or(Expression):  # pylint: disable=too-few-public-methods
+    """join compares via OR"""
+
+    def __init__(self, *compares: list[Compare | Expression]):
+        super().__init__("OR", *compares)
+
+
+class Wiql:
+    """Build a WIQL query"""
+
+    def __init__(self):
+        self.selected = [Field("Id")]
+        self.search = None
+        self.order = []
+        self.snapshot = None
+
+    def select(self, *fields: list[Field | str]):
+        """The fields to select
+
+        Returns:
+            Builder: Returns self for chaining
+        """
+        self.selected = [f if isinstance(f, Field) else Field(f) for f in fields]
+        return self
+
+    def where(self, expression: Compare | And | Or):
+        """Search criteria
+
+        Args:
+            expression (Expression|Compare): An expression of what to search for.
+
+        Returns:
+            Builder: self for chaining calls
+        """
+        self.search = expression
+        return self
+
+    def order_by(self, *orders):
+        """Set the fields to order the results by
+
+        Returns:
+            Builder: Returns self for chaining
+        """
+        self.order = orders
+        return self
+
+    def asof(self, stamp: Value | date | datetime | str):
+        """Set the view of the data
+
+        Args:
+            stamp (Value): The date or datetime in a Value
+
+        Returns:
+            Builder: self for chainingd
+        """
+        assert isinstance(stamp, (Value, date, datetime, str)), stamp
+        self.snapshot = stamp if isinstance(stamp, (Value, str)) else Value(stamp)
+        return self
+
+    def __str__(self) -> str:
+        select = ", ".join(str(s) for s in self.selected)
+        where = f" WHERE {self.search}" if self.search else ""
+        order = (
+            f" ORDER BY {', '.join(str(o) for o in self.order)}" if self.order else ""
+        )
+        asof = f" ASOF {str(self.snapshot)}" if self.snapshot else ""
+        return f"SELECT {select} FROM workitems{where}{order}{asof}"

devopsdriver-0.1.35/devopsdriver/azure/workitem/workitem.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+
+""" An Azure Devops WorkItem """
+
+from typing import Any
+from azure.devops.v7_1.work_item_tracking.models import WorkItem as AzureWorkItem
+
+
+class WorkItem:  # pylint: disable=too-few-public-methods
+    """Azure WorkItem"""
+
+    def __init__(self, work_item: AzureWorkItem):
+        self.raw = work_item
+
+    @staticmethod
+    def __matches_field(name: str, field: str) -> bool:
+        name = name.lower()
+        field = field.lower()
+
+        if name == field:
+            return True
+
+        if name == field.replace(".", "_"):
+            return True
+
+        if name == field.split(".")[-1]:
+            return True
+
+        return False
+
+    @staticmethod
+    def _parse_field(name: str, data: dict) -> any:
+        assert name and data
+        found = [f for f in data if WorkItem.__matches_field(name, f)]
+
+        if len(found) == 1:
+            return (
+                WorkItem._Dict(data[found[0]])
+                if isinstance(data[found[0]], dict)
+                else data[found[0]]
+            )
+
+        if "fields" in data:
+            return WorkItem._parse_field(name, data["fields"])
+
+        raise AttributeError(f"'WorkItem' object has no attribute '{name}'")
+
+    class _Dict(dict):
+        def __getattr__(self, name: str) -> Any:
+            return WorkItem._parse_field(name, self)
+
+    def __getattr__(self, name: str) -> Any:
+        return WorkItem._parse_field(name, self.raw.as_dict())