devopsdriver 0.1.37__tar.gz → 0.1.40__tar.gz

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: devopsdriver
-Version: 0.1.37
+Version: 0.1.40
 Summary: DevOps tools
 Author-email: Marc Page <marcallenpage@gmail.com>
 License: This is free and unencumbered software released into the public domain.
@@ -32,7 +32,7 @@ Project-URL: Homepage, https://github.com/marcpage/devops-driver
 Project-URL: Documentation, https://github.com/marcpage/devops-driver
 Project-URL: Repository, https://github.com/marcpage/devops-driver.git
 Project-URL: Issues, https://github.com/marcpage/devops-driver/issues
-Project-URL: Changelog, https://github.com/marcpage/devops-driver
+Project-URL: Changelog, https://github.com/marcpage/devops-driver/releases
 Keywords: azure,devops,jira,confluence,email,pipelines,tools
 Classifier: Development Status :: 1 - Planning
 Classifier: Environment :: Console
@@ -51,9 +51,16 @@ Requires-Dist: keyring==25.0.0
 Requires-Dist: setuptools==69.0.2
 Requires-Dist: azure-devops==7.1.0b4
 Requires-Dist: Mako==1.3.2
+Provides-Extra: dev
+Requires-Dist: black>=24.3.0; extra == "dev"
+Requires-Dist: pylint>=3.1.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=8.1.1; extra == "test"
+Requires-Dist: coverage>=7.4.4; extra == "test"
+Provides-Extra: doc
 
 ![status sheild](https://img.shields.io/static/v1?label=status&message=beta&color=blue&style=plastic)
-[![status sheild](https://img.shields.io/static/v1?label=released&message=v0.1.37&color=active&style=plastic)](https://pypi.org/project/devopsdriver/0.1.37/)
+[![status sheild](https://img.shields.io/static/v1?label=released&message=v0.1.40&color=active&style=plastic)](https://pypi.org/project/devopsdriver/0.1.40/)
 [![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)
@@ -84,7 +91,16 @@ OS:
 
 Devops-driver is a collection of tools to help streamline developer's experience and gain insights into various processes.
 
-## Access to secrets
+## Tools
+
+devopsdriver is a toolbox that helps to quickly put together reports. Some of the items in the toolbox are:
+
+- **Settings**: store data, constants, settings, keys, tokens, etc. both in and out of the repository
+- **send_email**: send emails over SMTP (including SSL), using `Settings` to store credentials
+- **Template**: Simplify generating reports using `.mako` templates
+- **Azure.workitem**: Search for and inspect Azure DevOps work items
+
+## Example use-case
 
 To allow seamless work in both pipelines as well as in the development environment, the `Settings` object gives you access to common settings among multiple scripts, secrets, and configuration constants in a way the helps keep secrets out of the repository but runs just as well in the pipeline as your machine.
 
@@ -101,7 +117,6 @@ secrets:
 ```
 
 This file is in a global place (location varies by OS) and stores information that you may not want in your repository or is specific to development. 
-The `secrets` are extra sensative and are stored in the OS keychain.
 
 | Platform | Global Directory       |
 |----------|------------------------|
@@ -109,26 +124,28 @@ The `secrets` are extra sensative and are stored in the OS keychain.
 | Linux    | ~/.devopsdriver/       |
 | macOS    | ~/Library/Preferences/ |
 
+The `secrets` are extra sensative and are stored in the OS keychain.
+
 ### Set secrets in the keychain
 ```bash
 $ python3 -m venv .venv
 $ source .venv/bin/activate
 $ pip install devopsdriver
-$ python -m devopsdriver.settings --secrets
+$ settings --secrets
 secret: smtp.password  key: smtp/password
 smtp.password (smtp/password): ****
 secret: azure.token  key: azure/token
 smtp.password (azure/token): ****
-$ python -m devopsdriver.settings --secrets
+$ settings --secrets
 secret: azure.token  key: azure/token
 	Value set
 secret: smtp.password  key: smtp/password
 	Value set
 $
 ```
-The first call to `devopsdriver.settings` will look for every secret and check if they are already set in the keychain.
+The first call to `settings` will look for every secret and check if they are already set in the keychain.
 For any secret that has not been set in the keychain, you will be prompted to enter the password to store.
-The second call to `devopsdriver.settings` will verify that all the values have been set in the keychain.
+The second call to `settings` will verify that all the values have been set in the keychain.
 
 ### devopsdriver.yml
 ```yaml
@@ -174,6 +191,8 @@ These are values that you want to use in your script but have them here for easy
 </ul>
 ```
 
+This file is the template for the email body.
+
 ### new_stories.py
 ```python
 from datetime import date, timedelta

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/README.md

@@ -1,5 +1,5 @@
 ![status sheild](https://img.shields.io/static/v1?label=status&message=beta&color=blue&style=plastic)
-[![status sheild](https://img.shields.io/static/v1?label=released&message=v0.1.37&color=active&style=plastic)](https://pypi.org/project/devopsdriver/0.1.37/)
+[![status sheild](https://img.shields.io/static/v1?label=released&message=v0.1.40&color=active&style=plastic)](https://pypi.org/project/devopsdriver/0.1.40/)
 [![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)
@@ -30,7 +30,16 @@ OS:
 
 Devops-driver is a collection of tools to help streamline developer's experience and gain insights into various processes.
 
-## Access to secrets
+## Tools
+
+devopsdriver is a toolbox that helps to quickly put together reports. Some of the items in the toolbox are:
+
+- **Settings**: store data, constants, settings, keys, tokens, etc. both in and out of the repository
+- **send_email**: send emails over SMTP (including SSL), using `Settings` to store credentials
+- **Template**: Simplify generating reports using `.mako` templates
+- **Azure.workitem**: Search for and inspect Azure DevOps work items
+
+## Example use-case
 
 To allow seamless work in both pipelines as well as in the development environment, the `Settings` object gives you access to common settings among multiple scripts, secrets, and configuration constants in a way the helps keep secrets out of the repository but runs just as well in the pipeline as your machine.
 
@@ -47,7 +56,6 @@ secrets:
 ```
 
 This file is in a global place (location varies by OS) and stores information that you may not want in your repository or is specific to development. 
-The `secrets` are extra sensative and are stored in the OS keychain.
 
 | Platform | Global Directory       |
 |----------|------------------------|
@@ -55,26 +63,28 @@ The `secrets` are extra sensative and are stored in the OS keychain.
 | Linux    | ~/.devopsdriver/       |
 | macOS    | ~/Library/Preferences/ |
 
+The `secrets` are extra sensative and are stored in the OS keychain.
+
 ### Set secrets in the keychain
 ```bash
 $ python3 -m venv .venv
 $ source .venv/bin/activate
 $ pip install devopsdriver
-$ python -m devopsdriver.settings --secrets
+$ settings --secrets
 secret: smtp.password  key: smtp/password
 smtp.password (smtp/password): ****
 secret: azure.token  key: azure/token
 smtp.password (azure/token): ****
-$ python -m devopsdriver.settings --secrets
+$ settings --secrets
 secret: azure.token  key: azure/token
 	Value set
 secret: smtp.password  key: smtp/password
 	Value set
 $
 ```
-The first call to `devopsdriver.settings` will look for every secret and check if they are already set in the keychain.
+The first call to `settings` will look for every secret and check if they are already set in the keychain.
 For any secret that has not been set in the keychain, you will be prompted to enter the password to store.
-The second call to `devopsdriver.settings` will verify that all the values have been set in the keychain.
+The second call to `settings` will verify that all the values have been set in the keychain.
 
 ### devopsdriver.yml
 ```yaml
@@ -120,6 +130,8 @@ These are values that you want to use in your script but have them here for easy
 </ul>
 ```
 
+This file is the template for the email body.
+
 ### new_stories.py
 ```python
 from datetime import date, timedelta

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/devopsdriver/__init__.py

@@ -1,10 +1,11 @@
 """ DevOps tools """
 
-from .azdo import Azure
 from .settings import Settings
 from .sendmail import send_email
 from .template import Template
+from .azdo.clients import Azure
 
-__version__ = "0.1.37"
+
+__version__ = "0.1.40"
 __author__ = "Marc Page"
 __credits__ = ""

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/devopsdriver/azdo/__init__.py

@@ -2,8 +2,9 @@
 
 # re export symbols for easier use
 from .clients import Azure
+from .timestamp import Timestamp
 
-from .workitem import WorkItem
+from .workitem.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

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/devopsdriver/azdo/clients.py

@@ -7,12 +7,15 @@ 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.azdo.workitem.client import Client as WIClient
 
+
+# for testing
 CONNECTION = AzureConnection
 AUTHENTICATION = MSBasicAuthentication
 

devopsdriver-0.1.40/devopsdriver/azdo/timestamp.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+
+
+""" Tools that help when working with Azure """
+
+
+from datetime import datetime, timezone, timedelta
+from functools import total_ordering
+
+
+@total_ordering
+class Timestamp:
+    """An Azure timestamp"""
+
+    DATE_FORMAT = "%Y-%m-%dT%H:%M:%S"
+    US_PER_MS = 1000  # microseconds per millisecond
+    US_PER_SEC = 1000 * US_PER_MS  # microseconds per second
+
+    @staticmethod
+    def is_timestamp(value: any) -> bool:
+        """Determines if the value is a timestamp string
+
+        Args:
+            value (any): The value to check
+
+        Returns:
+            bool: True if the value is an Azure timestamp
+        """
+        if not isinstance(value, str):
+            return False
+
+        if not value.endswith("Z"):
+            return False
+
+        try:
+            Timestamp.__parse_string(value)
+            return True
+
+        except ValueError:
+            return False
+
+    @staticmethod
+    def now():
+        """Returns a timestamp representing now"""
+        return Timestamp(datetime.now(tz=timezone.utc))
+
+    def __init__(self, value: datetime | str | float | int):
+        if isinstance(value, datetime):
+            self.value = value
+
+        elif isinstance(value, str):
+            self.value = Timestamp.__parse_string(value)
+
+        elif isinstance(value, (int, float)):
+            self.value = datetime.fromtimestamp(value, tz=timezone.utc)
+
+    def __str__(self) -> str:
+        return self.to_string()
+
+    def __lt__(self, other) -> bool:
+        match Timestamp.__comparison_type(other):
+            case 1:
+                return self.value < other.value
+            case 2:
+                return self.value < other
+            case _:
+                return NotImplemented
+
+    def __eq__(self, other) -> bool:
+        match Timestamp.__comparison_type(other):
+            case 1:
+                return self.value == other.value
+            case 2:
+                return self.value == other
+            case _:
+                return NotImplemented
+
+    def __sub__(self, other):
+        match Timestamp.__comparison_type(other):
+            case 1:
+                return self.value - other.value
+            case 2 | 3:
+                return self.value - other
+            case _:
+                return NotImplemented
+
+    def __add__(self, other):
+        if Timestamp.__comparison_type(other) != 3:
+            return NotImplemented
+
+        return Timestamp(self.value + other)
+
+    def to_string(self) -> str:
+        """Returns the Azure formatted timestamp
+
+        Returns:
+            str: The correctly formatted string
+        """
+        milliseconds = f"{self.value.microsecond / Timestamp.US_PER_MS:03.0f}".rstrip(
+            "0"
+        )
+        return f"{self.value.strftime(Timestamp.DATE_FORMAT)}.{milliseconds}Z"
+
+    def to_timestamp(self) -> float:
+        """Converts to a number to use with time.time()
+
+        Returns:
+            float: The number of seconds since the epoch
+        """
+        return datetime.timestamp(self.value)
+
+    @staticmethod
+    def __parse_string(timestamp: str) -> datetime:
+        assert timestamp.endswith("Z"), timestamp
+        whole, fractional = timestamp.rsplit(".", 1)
+        result = datetime.strptime(whole, Timestamp.DATE_FORMAT)
+        fractional_seconds = float(f"0.{fractional[:-1].ljust(3, '0')}")
+        return result.replace(
+            microsecond=int(fractional_seconds * Timestamp.US_PER_SEC)
+        ).replace(tzinfo=timezone.utc)
+
+    @staticmethod
+    def __comparison_type(other) -> int:
+        if isinstance(other, timedelta):
+            return 3
+
+        if isinstance(other, datetime):
+            return 2
+
+        if hasattr(other, "value") and isinstance(other.value, datetime):
+            return 1
+
+        return 0

devopsdriver-0.1.40/devopsdriver/azdo/workitem/__init__.py

@@ -0,0 +1 @@
+""" init workitem module """

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/devopsdriver/azdo/workitem/client.py

@@ -1,12 +1,14 @@
 #!/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.azdo.workitem import WorkItem
+from devopsdriver.azdo.workitem.workitem import WorkItem
 from devopsdriver.azdo.workitem.wiql import Wiql
 
 

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/devopsdriver/azdo/workitem/wiql.py

@@ -1,5 +1,6 @@
 #!/usr/bin/env python3
 
+
 """ Builds a WIQL query
 https://learn.microsoft.com/en-us/azure/devops/boards/queries/wiql-syntax?view=azure-devops
 

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/devopsdriver/azdo/workitem/workitem.py

@@ -1,10 +1,15 @@
 #!/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
 
+from devopsdriver.azdo.timestamp import Timestamp
+
 
 class WorkItem:  # pylint: disable=too-few-public-methods
     """Azure WorkItem"""
@@ -43,11 +48,21 @@ class WorkItem:  # pylint: disable=too-few-public-methods
         if "fields" in data:
             return WorkItem._parse_field(name, data["fields"])
 
-        raise AttributeError(f"'WorkItem' object has no attribute '{name}'")
+        return None
 
     class _Dict(dict):
         def __getattr__(self, name: str) -> Any:
-            return WorkItem._parse_field(name, self)
+            value = WorkItem._parse_field(name, self)
+
+            if Timestamp.is_timestamp(value):
+                return Timestamp(value)
+
+            return value
 
     def __getattr__(self, name: str) -> Any:
-        return WorkItem._parse_field(name, self.raw.as_dict())
+        value = WorkItem._parse_field(name, self.raw.as_dict())
+
+        if Timestamp.is_timestamp(value):
+            return Timestamp(value)
+
+        return value

devopsdriver-0.1.40/devopsdriver/manage_settings.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+
+
+""" Module Doc """
+
+
+from os.path import dirname, join
+from sys import argv as sys_argv
+from getpass import getpass as os_getpass
+
+from keyring import set_password
+
+from .settings import Settings
+from .template import Template
+
+ARGV = sys_argv
+PRINT = print
+SET_PASSWORD = set_password
+GET_PASS = os_getpass
+
+
+def main() -> None:
+    """Get settings values"""
+    args = list(ARGV[1:])
+
+    if not args or "--help" in args or "-h" in args:
+        PRINT(
+            Template(
+                __file__, join(dirname(__file__), "templates"), extension=".txt.mako"
+            ).render()
+        )
+        return
+
+    settings = Settings(__file__, dirname(dirname(__file__))).key("secrets")
+
+    if "--secrets" in args:
+        args.remove("--secrets")
+
+        for secret, key in settings.secrets.items():
+            PRINT(f"secret: {secret}  key: {key}")
+
+            if not settings.has(secret):
+                value = GET_PASS(f"{secret} ({key}): ")
+
+                if value:
+                    SET_PASSWORD(*Settings.split_key(key), value)
+            else:
+                PRINT("\tValue set")
+
+    for arg in args:
+        PRINT(f"{settings.get(arg)}")
+
+
+if __name__ == "__main__":
+    main()

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/devopsdriver/sendmail.py

@@ -1,6 +1,9 @@
 #!/usr/bin/env python3
 
+
 """ Ability to send emails with embedded images """
+
+
 from smtplib import SMTP as OS_SMTP, SMTP_SSL as OS_SMTP_SSL
 from email.mime.multipart import MIMEMultipart as OS_MIMEMultipart
 from email.mime.text import MIMEText as OS_MIMEText
@@ -8,6 +11,7 @@ from email.mime.image import MIMEImage as OS_MIMEImage
 
 from devopsdriver.settings import Settings
 
+
 IMAGE_HEADERS = {".png": b"\x89PNG\r\n\x1a\n", ".jpg": b"\xff\xd8\xff"}
 
 # for testing

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/devopsdriver/settings.py

@@ -86,6 +86,8 @@ from getpass import getpass as os_getpass
 
 from yaml import safe_load
 from keyring import get_password, set_password
+from keyring.backends import fail
+
 
 # for testing
 ENVIRON = os_environ
@@ -266,7 +268,7 @@ class Settings:
         if key in self.secrets:
             value = GET_PASSWORD(*Settings.split_key(self.secrets[key]))
 
-            if value is not None:
+            if value is not None and not isinstance(value, fail.Keyring):
                 return True if check else value
 
         # Last check the files for settings
@@ -357,38 +359,3 @@ class Settings:
             Settings.__merge(settings, contents)
 
         return settings
-
-
-def main() -> None:
-    """Get settings values"""
-    args = list(ARGV[1:])
-
-    if not args or "--help" in args or "-h" in args:
-        PRINT("pass in settings to see if they are set and to what value")
-        PRINT("You can pass dotted names to get inner values, like smpt.server")
-        PRINT("You can pass --secrets to set keychain values that have not been set")
-        PRINT("You can also pass --help or -h to get this message")
-        return
-
-    settings = Settings(__file__, dirname(dirname(__file__))).key("secrets")
-
-    if "--secrets" in args:
-        args.remove("--secrets")
-
-        for secret, key in settings.secrets.items():
-            PRINT(f"secret: {secret}  key: {key}")
-
-            if not settings.has(secret):
-                value = GET_PASS(f"{secret} ({key}): ")
-
-                if value:
-                    SET_PASSWORD(*Settings.split_key(key), value)
-            else:
-                PRINT("\tValue set")
-
-    for arg in args:
-        PRINT(f"{settings.get(arg)}")
-
-
-if __name__ == "__main__":
-    main()

{devopsdriver-0.1.37 → devopsdriver-0.1.40}/devopsdriver/template.py

@@ -1,7 +1,9 @@
 #!/usr/bin/env python3
 
+
 """ Module Doc """
 
+
 from os.path import dirname, basename, splitext
 
 from mako.lookup import TemplateLookup

devopsdriver-0.1.40/devopsdriver/templates/manage_settings.txt.mako

@@ -0,0 +1,14 @@
+Usage:
+
+  settings [-h | --help] 
+  settings --secrets
+  settings <value>...
+
+-h --help  Display this help information
+
+--secrets  Prompt for any secrets that have not been set in the keychain
+            For secrets that are set, confirms that the value is set
+
+<value>    A value to display the value for. For instance:
+                "smtp" will display all the smtp values (but not secrets in smtp, like password)
+                "smtp.server" will display just the smtp server