Merge pull request #52 from itk-dev-rpa/release/2.3.0

Release/2.3.0

Author: ghbm-itk

.github/workflows/Linting.yml

@@ -1,6 +1,6 @@
 name: Linting
 
-on: [push]
+on: [push, pull_request]
 
 jobs:
   build:
@@ -29,4 +29,4 @@ jobs:
 
     - name: Analyzing the code with flake8
       run: |
-        flake8 --extend-ignore=E501,E251 $(git ls-files '*.py')
+        flake8 --extend-ignore=E501,E251 $(git ls-files '*.py')

.gitignore

@@ -160,3 +160,9 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# Ruff config file
+ruff.toml
+
+# Pre-commit YAML file
+.pre-commit-config.yaml

changelog.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2024-07-03
+
+### Added
+
+- Function for getting cases based on CVR from KMD Nova.
+- Tests for getting cases based on CVR from KMD Nova.
+- Module for accessing site and file endpoints in Microsoft Graph.
+
+### Changed
+
+- Unexpected format on caseworker in Nova cases results in None.
+- Minor refactoring to move common HTTP request wrappers for Microsoft Graph into their own file.
+
 ## [2.2.0] - 2024-05-08
 
 ### Added
@@ -101,7 +114,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Initial release
 
-[Unreleased] https://github.com/itk-dev-rpa/ITK-dev-shared-components/compare/2.2.0...HEAD
+[Unreleased] https://github.com/itk-dev-rpa/ITK-dev-shared-components/compare/2.3.0...HEAD
+[2.3.0] https://github.com/itk-dev-rpa/ITK-dev-shared-components/releases/tag/2.3.0
 [2.2.0] https://github.com/itk-dev-rpa/ITK-dev-shared-components/releases/tag/2.2.0
 [2.1.1] https://github.com/itk-dev-rpa/ITK-dev-shared-components/releases/tag/2.1.1
 [2.1.0] https://github.com/itk-dev-rpa/ITK-dev-shared-components/releases/tag/2.1.0

itk_dev_shared_components/graph/common.py

@@ -0,0 +1,54 @@
+"""This module contains common functions like HTTP request wrappers which are used across other modules."""
+
+from typing import Any
+
+import requests
+
+from itk_dev_shared_components.graph.authentication import GraphAccess
+
+
+def get_request(endpoint: str, graph_access: GraphAccess) -> requests.models.Response:
+    """Sends a get request to the given Graph endpoint using the GraphAccess
+    and returns the json object of the response.
+
+    Args:
+        endpoint: The URL of the Graph endpoint.
+        graph_access: The GraphAccess object used to authenticate.
+
+    Returns:
+        Response: The response object of the GET request.
+
+    Raises:
+        HTTPError: Any errors raised while performing GET request.
+    """
+    token = graph_access.get_access_token()
+    headers = {"Authorization": f"Bearer {token}"}
+
+    response = requests.get(endpoint, headers=headers, timeout=30)
+    response.raise_for_status()
+
+    return response
+
+
+def put_request(endpoint: str, graph_access: GraphAccess, data: Any) -> requests.models.Response:
+    """Sends a put request to the given Graph endpoint using the GraphAccess
+    and returns the json object of the response.
+
+    Args:
+        endpoint: The URL of the Graph endpoint.
+        data: The data to send in the request.
+        graph_access: The GraphAccess object used to authenticate.
+
+    Returns:
+        Response: The response object of the PUT request.
+
+    Raises:
+        HTTPError: Any errors raised while performing PUT request.
+    """
+    token = graph_access.get_access_token()
+    headers = {"Authorization": f"Bearer {token}"}
+
+    response = requests.put(endpoint, headers=headers, data=data, timeout=30)
+    response.raise_for_status()
+
+    return response

itk_dev_shared_components/graph/file.py

@@ -0,0 +1,54 @@
+"""This module is responsible for accessing files using the Microsoft Graph API."""
+
+from dataclasses import dataclass, field
+
+from itk_dev_shared_components.graph.authentication import GraphAccess
+from itk_dev_shared_components.graph.common import get_request
+
+
+@dataclass
+class DriveItem:
+    """A class representing a DriveItem."""
+
+    id: str = field(repr=False)
+    name: str
+    web_url: str
+    last_modified: str
+
+
+def get_drive_item(graph_access: GraphAccess, site_id: str, drive_item_path: str) -> str:
+    """Given a site id and a drive_item_path, gets the corresponding DriveItem
+
+    You need to authorize against Graph to get the GraphAccess before using this function
+    see the graph.authentication module.
+
+    See https://learn.microsoft.com/en-us/graph/api/driveitem-get for further documentation
+
+    Args:
+        graph_access: The GraphAccess object used to authenticate.
+        site_id: The id of the site in SharePoint.
+        drive_item_path: The path to the DriveItem in SharePoint.
+    """
+    endpoint = f"https://graph.microsoft.com/v1.0/sites/{site_id}/drive/root:/{drive_item_path}"
+    response = get_request(endpoint, graph_access)
+    raw_response = response.json()
+
+    return _unpack_drive_item_response(raw_response)
+
+
+def _unpack_drive_item_response(drive_item_raw: dict[str, str]) -> DriveItem:
+    """Unpack a json HTTP response and create a DriveItem object.
+
+    Args:
+        drive_item_raw: The json dictionary created by response.json().
+
+    Returns:
+        DriveItem: A DriveItem object.
+    """
+
+    return DriveItem(
+        id=drive_item_raw["id"],
+        name=drive_item_raw["name"],
+        web_url=drive_item_raw["webUrl"],
+        last_modified=drive_item_raw["lastModifiedDateTime"],
+    )

itk_dev_shared_components/graph/mail.py

@@ -7,6 +7,7 @@
 from bs4 import BeautifulSoup
 
 from itk_dev_shared_components.graph.authentication import GraphAccess
+from itk_dev_shared_components.graph.common import get_request
 
 
 @dataclass
@@ -67,7 +68,7 @@ def get_emails_from_folder(user: str, folder_path: str, graph_access: GraphAcces
 
     endpoint = f"https://graph.microsoft.com/v1.0/users/{user}/mailFolders/{folder_id}/messages?$top=1000"
 
-    response = _get_request(endpoint, graph_access)
+    response = get_request(endpoint, graph_access)
     emails_raw = response.json()['value']
 
     return _unpack_email_response(user, emails_raw)
@@ -84,7 +85,7 @@ def get_email_as_mime(email: Email, graph_access: GraphAccess) -> io.BytesIO:
         io.BytesIO: A file-like object of the MIME file.
     """
     endpoint = f"https://graph.microsoft.com/v1.0/users/{email.user}/messages/{email.id}/$value"
-    response = _get_request(endpoint, graph_access)
+    response = get_request(endpoint, graph_access)
     data = response.content
     return io.BytesIO(data)
 
@@ -113,15 +114,15 @@ def get_folder_id_from_path(user: str, folder_path: str, graph_access: GraphAcce
 
     # Get main folder
     endpoint = f"https://graph.microsoft.com/v1.0/users/{user}/mailFolders"
-    response = _get_request(endpoint, graph_access).json()
+    response = get_request(endpoint, graph_access).json()
     folder_id = _find_folder(response, main_folder)
     if folder_id is None:
         raise ValueError(f"Top level folder '{main_folder}' was not found for user '{user}'.")
 
     # Get child folders
     for child_folder in child_folders:
         endpoint = f"https://graph.microsoft.com/v1.0/users/{user}/mailFolders/{folder_id}/childFolders"
-        response = _get_request(endpoint, graph_access).json()
+        response = get_request(endpoint, graph_access).json()
         folder_id = _find_folder(response, child_folder)
         if folder_id is None:
             raise ValueError(f"Child folder '{child_folder}' not found under '{main_folder}' for user '{user}'.")
@@ -141,7 +142,7 @@ def list_email_attachments(email: Email, graph_access: GraphAccess) -> tuple[Att
         tuple[Attachment]: A tuple of Attachment objects describing the attachments.
     """
     endpoint = f"https://graph.microsoft.com/v1.0/users/{email.user}/messages/{email.id}/attachments?$select=name,size,id"
-    response = _get_request(endpoint, graph_access).json()
+    response = get_request(endpoint, graph_access).json()
 
     attachments = []
     for att in response['value']:
@@ -162,7 +163,7 @@ def get_attachment_data(attachment: Attachment, graph_access: GraphAccess) -> io
     """
     email = attachment.email
     endpoint = f"https://graph.microsoft.com/v1.0/users/{email.user}/messages/{email.id}/attachments/{attachment.id}/$value"
-    response = _get_request(endpoint, graph_access)
+    response = get_request(endpoint, graph_access)
     data_bytes = response.content
     return io.BytesIO(data_bytes)
 
@@ -287,31 +288,3 @@ def _unpack_email_response(user: str, emails_raw: list[dict[str, str]]) -> tuple
         )
 
     return tuple(emails)
-
-
-def _get_request(endpoint: str, graph_access: GraphAccess) -> requests.models.Response:
-    """Sends a get request to the given Graph endpoint using the GraphAccess
-    and returns the json object of the response.
-
-    Args:
-        endpoint: The URL of the Graph endpoint.
-        graph_access: The GraphAccess object used to authenticate.
-        timeout: Timeout in seconds of the HTTP request. Defaults to 10.
-
-    Returns:
-        Response: The response object of the GET request.
-
-    Raises:
-        HTTPError: Any errors raised while performing GET request.
-    """
-    token = graph_access.get_access_token()
-    headers = {'Authorization': f"Bearer {token}"}
-
-    response = requests.get(
-        endpoint,
-        headers=headers,
-        timeout=30
-    )
-    response.raise_for_status()
-
-    return response

itk_dev_shared_components/graph/site.py

@@ -0,0 +1,104 @@
+"""This module is responsible for accessing sites using the Microsoft Graph API."""
+
+from dataclasses import dataclass, field
+
+from itk_dev_shared_components.graph.authentication import GraphAccess
+from itk_dev_shared_components.graph.common import get_request, put_request
+
+
+@dataclass
+class Site:
+    """A class representing a Site."""
+
+    id: str = field(repr=False)
+    name: str
+    display_name: str
+    description: str
+    web_url: str
+    created: str
+    last_modified: str
+
+
+def get_site(graph_access: GraphAccess, site_path: str) -> Site:
+    """Retrieve properties and relationships for a site resource.
+    A site resource represents a team site in SharePoint.
+
+    You need to authorize against Graph to get the GraphAccess before using this function
+    see the graph.authentication module.
+
+    See https://learn.microsoft.com/en-us/graph/api/site-get?view=graph-rest-1.0
+    for a list of possible site_paths to pass as argument.
+
+    Args:
+        graph_access: The GraphAccess object used to authenticate.
+        site_path: The path to the team site in SharePoint.
+
+    returns:
+        A Site object
+    """
+    endpoint = f"https://graph.microsoft.com/v1.0/sites/{site_path}"
+    response = get_request(endpoint, graph_access)
+
+    return _unpack_site_response(response.json())
+
+
+def download_file_contents(graph_access: GraphAccess, site_id: str, drive_item_id: str) -> bytes:
+    """Given a site_id, a drive_item_id, and a download destination, downloads a single file from a site resource
+
+    You need to authorize against Graph to get the GraphAccess before using this function
+    see the graph.authentication module.
+
+    See https://learn.microsoft.com/en-us/graph/api/driveitem-get-content for further documentation
+
+    Args:
+        graph_access: The GraphAccess object used to authenticate.
+        site_id: The id of the site in SharePoint.
+        drive_item_id: The id of the DriveItem in SharePoint.
+
+    returns:
+        bytes containing the contents of the file
+    """
+    endpoint = f"https://graph.microsoft.com/v1.0/sites/{site_id}/drive/items/{drive_item_id}/content"
+    response = get_request(endpoint, graph_access)
+    return response.content
+
+
+def upload_file_contents(graph_access: GraphAccess, site_id: str, drive_item_path: str, file_contents: bytes):
+    """Given a site_id, a drive_item_path, and file_contents as bytes, uploads a single file to a site
+
+    You need to authorize against Graph to get the GraphAccess before using this function
+    see the graph.authentication module.
+
+    See https://learn.microsoft.com/en-us/graph/api/driveitem-put-content for further documentation
+
+    Args:
+        graph_access: The GraphAccess object used to authenticate.
+        site_id: The id of the site in SharePoint.
+        drive_item_path: The path to upload the file contents to.
+        file_contents: A bytes object containing the file's contents.
+
+    """
+
+    endpoint = f"https://graph.microsoft.com/v1.0/sites/{site_id}/drive/root:/{drive_item_path}:/content"
+    put_request(endpoint, graph_access, file_contents)
+
+
+def _unpack_site_response(site_raw: dict[str, str]) -> Site:
+    """Unpack a json HTTP response and create a Site object.
+
+    Args:
+        site_raw: The json dictionary created by response.json().
+
+    Returns:
+        Site: A Site object.
+    """
+
+    return Site(
+        id=site_raw["id"],
+        name=site_raw["name"],
+        display_name=site_raw["displayName"],
+        description=site_raw["description"],
+        web_url=site_raw["webUrl"],
+        created=site_raw["createdDateTime"],
+        last_modified=site_raw["lastModifiedDateTime"],
+    )