Office365-REST-Python-Client 2.5.5__py3-none-any.whl → 2.5.7__py3-none-any.whl

office365/planner/plans/plan.py

@@ -7,6 +7,7 @@ from office365.planner.buckets.bucket import PlannerBucket
 from office365.planner.plans.container import PlannerPlanContainer
 from office365.planner.plans.details import PlannerPlanDetails
 from office365.planner.tasks.task import PlannerTask
+from office365.runtime.http.request_options import RequestOptions
 from office365.runtime.paths.resource_path import ResourcePath
 
 
@@ -18,11 +19,20 @@ class PlannerPlan(Entity):
     """
 
     def __str__(self):
-        return self.title
+        return self.title or self.entity_type_name
 
     def __repr__(self):
         return self.id or self.entity_type_name
 
+    def delete_object(self):
+        def _construct_request(request):
+            # type: (RequestOptions) -> None
+            request.set_header("If-Match", self.properties.get("__etag"))
+
+        return (
+            super(PlannerPlan, self).delete_object().before_execute(_construct_request)
+        )
+
     @property
     def container(self):
         """Identity of the user, device, or application which created the plan."""

office365/reports/root.py

@@ -11,6 +11,17 @@ from office365.runtime.queries.function import FunctionQuery
 class ReportRoot(Entity):
     """Represents a container for Azure Active Directory (Azure AD) reporting resources."""
 
+    def device_configuration_device_activity(self):
+        """
+        Metadata for the device configuration device activity report
+        """
+        return_type = ClientResult(self.context, Report())
+        qry = FunctionQuery(
+            self, "deviceConfigurationDeviceActivity", None, return_type
+        )
+        self.context.add_query(qry)
+        return return_type
+
     def device_configuration_user_activity(self):
         """
         Metadata for the device configuration user activity report
@@ -20,6 +31,15 @@ class ReportRoot(Entity):
         self.context.add_query(qry)
         return return_type
 
+    def managed_device_enrollment_failure_details(self):
+        """ """
+        return_type = ClientResult(self.context, Report())
+        qry = FunctionQuery(
+            self, "managedDeviceEnrollmentFailureDetails", None, return_type
+        )
+        self.context.add_query(qry)
+        return return_type
+
     def managed_device_enrollment_top_failures(self, period=None):
         """
         Note: The Microsoft Graph API for Intune requires an active Intune license for the tenant.
@@ -72,6 +92,18 @@ class ReportRoot(Entity):
         self.context.add_query(qry)
         return qry.return_type
 
+    def get_email_app_usage_apps_user_counts(self, period):
+        """
+        Get the count of unique users per email app.
+
+        :param str period: Specifies the length of time over which the report is aggregated.
+            The supported values for {period_value} are: D7, D30, D90, and D180. These values follow the format
+            Dn where n represents the number of days over which the report is aggregated. Required.
+        """
+        qry = create_report_query(self, "getEmailAppUsageAppsUserCounts", period)
+        self.context.add_query(qry)
+        return qry.return_type
+
     def get_m365_app_user_counts(self, period=None):
         """
         Get a report that provides the trend in the number of active users for each app (Outlook, Word, Excel,
@@ -85,10 +117,7 @@ class ReportRoot(Entity):
         return return_type
 
     def get_office365_activations_user_counts(self):
-        """
-        Get the count of Microsoft 365 activations on desktops and devices.
-
-        """
+        """Get the count of Microsoft 365 activations on desktops and devices."""
         qry = create_report_query(self, "getOffice365ActivationsUserCounts")
         self.context.add_query(qry)
         return qry.return_type
@@ -166,6 +195,32 @@ class ReportRoot(Entity):
         self.context.add_query(qry)
         return qry.return_type
 
+    def get_mailbox_usage_mailbox_counts(self, period):
+        """
+        Get the total number of user mailboxes in your organization and how many are active each day of the reporting
+        period. A mailbox is considered active if the user sent or read any email.
+
+        :param str period: Specifies the length of time over which the report is aggregated.
+            The supported values for {period_value} are: D7, D30, D90, and D180. These values follow the format
+            Dn where n represents the number of days over which the report is aggregated. Required.
+        """
+        qry = create_report_query(self, "getMailboxUsageMailboxCounts", period)
+        self.context.add_query(qry)
+        return qry.return_type
+
+    def get_mailbox_usage_quota_status_mailbox_counts(self, period):
+        """
+
+        :param str period: Specifies the length of time over which the report is aggregated.
+            The supported values for {period_value} are: D7, D30, D90, and D180. These values follow the format
+            Dn where n represents the number of days over which the report is aggregated. Required.
+        """
+        qry = create_report_query(
+            self, "getMailboxUsageQuotaStatusMailboxCounts", period
+        )
+        self.context.add_query(qry)
+        return qry.return_type
+
     def get_sharepoint_activity_pages(self, period):
         """
         Get the number of unique pages visited by users.
@@ -203,6 +258,30 @@ class ReportRoot(Entity):
         self.context.add_query(qry)
         return qry.return_type
 
+    def get_sharepoint_site_usage_detail(self, period):
+        """
+        Get details about SharePoint site usage.
+
+        :param str period: Specifies the length of time over which the report is aggregated.
+            The supported values for {period_value} are: D7, D30, D90, and D180. These values follow the format
+            Dn where n represents the number of days over which the report is aggregated. Required.
+        """
+        qry = create_report_query(self, "getSharePointSiteUsageDetail", period)
+        self.context.add_query(qry)
+        return qry.return_type
+
+    def get_sharepoint_site_usage_site_counts(self, period):
+        """
+        Get the trend of total and active site count during the reporting period.
+
+        :param str period: Specifies the length of time over which the report is aggregated.
+            The supported values for {period_value} are: D7, D30, D90, and D180. These values follow the format
+            Dn where n represents the number of days over which the report is aggregated. Required.
+        """
+        qry = create_report_query(self, "getSharePointSiteUsageSiteCounts", period)
+        self.context.add_query(qry)
+        return qry.return_type
+
     @property
     def authentication_methods(self):
         """Container for navigation properties for Azure AD authentication methods resources."""

office365/runtime/auth/authentication_context.py

@@ -47,6 +47,7 @@ class AuthenticationContext(object):
         cert_path=None,
         private_key=None,
         scopes=None,
+        passphrase=None,
     ):
         """Initializes a client to acquire a token via certificate credentials
 
@@ -56,6 +57,7 @@ class AuthenticationContext(object):
         :param str or None cert_path: Path to A PEM encoded certificate private key.
         :param str or None private_key: A PEM encoded certificate private key.
         :param list[str] or None scopes:  Scopes requested to access a protected API (a resource)
+        :param str passphrase: Passphrase if the private_key is encrypted
         """
         if scopes is None:
             resource = get_absolute_url(self.url)
@@ -70,7 +72,11 @@ class AuthenticationContext(object):
 
         def _acquire_token():
             authority_url = "https://login.microsoftonline.com/{0}".format(tenant)
-            credentials = {"thumbprint": thumbprint, "private_key": private_key}
+            credentials = {
+                "thumbprint": thumbprint,
+                "private_key": private_key,
+                "passphrase": passphrase,
+            }
             import msal
 
             app = msal.ConfidentialClientApplication(
@@ -187,7 +193,11 @@ class AuthenticationContext(object):
                 browser_mode = kwargs.get("browser_mode", False)
                 environment = kwargs.get("environment")
                 provider = SamlTokenProvider(
-                    self.url, credentials.userName, credentials.password, browser_mode, environment
+                    self.url,
+                    credentials.userName,
+                    credentials.password,
+                    browser_mode,
+                    environment,
                 )
         else:
             raise ValueError("Unknown credential type")

office365/runtime/auth/providers/acs_token_provider.py

@@ -10,7 +10,7 @@ from office365.runtime.http.request_options import RequestOptions
 
 
 class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
-    def __init__(self, url, client_id, client_secret, environment='commercial'):
+    def __init__(self, url, client_id, client_secret, environment="commercial"):
         """
         Provider to acquire the access token from a Microsoft Azure Access Control Service (ACS)
 
@@ -65,7 +65,9 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
             self.SharePointPrincipal, target_host, target_realm
         )
         principal_id = self.get_formatted_principal(self._client_id, None, target_realm)
-        sts_url = self.get_security_token_service_url(target_realm, environment=self._environment)
+        sts_url = self.get_security_token_service_url(
+            target_realm, environment=self._environment
+        )
         oauth2_request = {
             "grant_type": "client_credentials",
             "client_id": principal_id,
@@ -105,13 +107,14 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
 
     @staticmethod
     def get_security_token_service_url(realm, environment):
+        # type: (str, str) -> str
         if environment == "GCCH":
-            return "https://login.microsoftonline.us/{0}/tokens/OAuth/2".format(
-                realm
-            )
+            return "https://login.microsoftonline.us/{0}/tokens/OAuth/2".format(realm)
         else:
-            return "https://accounts.accesscontrol.windows.net/{0}/tokens/OAuth/2".format(
-                realm
+            return (
+                "https://accounts.accesscontrol.windows.net/{0}/tokens/OAuth/2".format(
+                    realm
+                )
             )
 
     def _get_authorization_header(self):

office365/runtime/auth/sts_profile.py

@@ -6,7 +6,6 @@ from office365.runtime.compat import timezone, urlparse
 class STSProfile(object):
     def __init__(self, authority_url, environment):
         """
-
         :type authority_url: str
         """
         self.authorityUrl = authority_url

office365/runtime/client_object.py

@@ -7,6 +7,7 @@ from typing_extensions import Self
 
 from office365.runtime.client_runtime_context import ClientRuntimeContext
 from office365.runtime.client_value import ClientValue
+from office365.runtime.http.request_options import RequestOptions
 from office365.runtime.odata.json_format import ODataJsonFormat
 from office365.runtime.odata.query_options import QueryOptions
 from office365.runtime.odata.type import ODataType
@@ -73,12 +74,16 @@ class ClientObject(Generic[T]):
         )
         return self
 
-    def after_execute(self, action, *args, **kwargs):
-        # type: (Callable[[Self, Any, Any], None], Any, Any) -> Self
-        """
-        Attach an event handler to client object which gets triggered after query is submitted to server
-        """
-        self._context.after_query_execute(action, self, *args, **kwargs)
+    def before_execute(self, action):
+        # type: (Callable[[RequestOptions], None]) -> Self
+        """Attach an event handler to client object which gets triggered after query is submitted to server"""
+        self.context.before_execute(action)
+        return self
+
+    def after_execute(self, action, execute_first=False):
+        # type: (Callable[[Self], None], bool) -> Self
+        """Attach an event handler to client object which gets triggered after query is submitted to server"""
+        self.context.after_query_execute(action, execute_first)
         return self
 
     def get(self):
@@ -138,13 +143,8 @@ class ClientObject(Generic[T]):
         return self._properties.get(name, default_value)
 
     def set_property(self, name, value, persist_changes=True):
-        # type: (str, P_T, bool) -> Self
-        """Sets property value
-
-        :param str name: Property name
-        :param P_T value: Property value
-        :param bool persist_changes: Persist changes
-        """
+        # type: (str|int, P_T, bool) -> Self
+        """Sets property value"""
         if persist_changes:
             self._ser_property_names.append(name)
 
@@ -187,7 +187,11 @@ class ClientObject(Generic[T]):
             from office365.runtime.queries.read_entity import ReadEntityQuery
 
             qry = ReadEntityQuery(self, names_to_include)
-            self.context.add_query(qry).after_query_execute(action, *args, **kwargs)
+
+            def _after_loaded(return_type):
+                action(*args, **kwargs)
+
+            self.context.add_query(qry).after_query_execute(_after_loaded)
         else:
             action(*args, **kwargs)
         return self

office365/runtime/client_object_collection.py

@@ -1,4 +1,4 @@
-from typing import Any, Callable, Generic, Iterator, List, Optional, Type, TypeVar
+from typing import Callable, Generic, Iterator, List, Optional, Type, TypeVar
 
 from typing_extensions import Self
 
@@ -147,12 +147,6 @@ class ClientObjectCollection(ClientObject, Generic[T]):
             self.top(page_size)
         return self
 
-    def after_execute(self, action, *args, **kwargs):
-        # type: (Callable[[Self, Any, Any], None], Any, Any) -> Self
-        super(ClientObjectCollection, self).after_execute(action, *args, **kwargs)
-        self._page_loaded += action
-        return self
-
     def get(self):
         # type: () -> Self
 
@@ -160,39 +154,30 @@ class ClientObjectCollection(ClientObject, Generic[T]):
             # type: (Self) -> None
             self._page_loaded.notify(self)
 
-        self.context.load(self, after_loaded=_loaded)
+        self.context.load(self).after_query_execute(_loaded)
         return self
 
     def get_all(self, page_size=None, page_loaded=None):
         # type: (int, Callable[[Self], None]) -> Self
         """Gets all the items in a collection, regardless of the size."""
 
-        self.paged(page_size, page_loaded)
-
         def _page_loaded(col):
             # type: (Self) -> None
-            self._page_loaded.notify(col)
             if self.has_next:
-                self._get_next(after_loaded=_page_loaded)
+                self._get_next().after_execute(_page_loaded)
 
-        self.context.load(self, after_loaded=_page_loaded)
+        self.paged(page_size, page_loaded).get().after_execute(_page_loaded)
         return self
 
-    def _get_next(self, after_loaded=None):
-        # type: (Optional[EventHandler]) -> Self
-        """
-        Submit a request to retrieve next collection of items
-        :param (ClientObjectCollection) -> None after_loaded: Page loaded event
-        """
+    def _get_next(self):
+        # type: () -> Self
+        """Submit a request to retrieve next collection of items"""
 
         def _construct_request(request):
             # type: (RequestOptions) -> None
             request.url = self._next_request_url
 
-        self.context.load(
-            self, before_loaded=_construct_request, after_loaded=after_loaded
-        )
-        return self
+        return self.get().before_execute(_construct_request)
 
     def first(self, expression):
         # type: (str) -> T

office365/runtime/client_request_exception.py

@@ -32,9 +32,7 @@ class ClientRequestException(RequestException):
 
     @property
     def message(self):
-        """
-        :rtype: str
-        """
+        # type: () -> str
         if self.payload:
             error = self.payload.get("error")
             if error:

office365/runtime/client_result.py

@@ -1,8 +1,10 @@
 import copy
-from typing import TYPE_CHECKING, Any, Callable, Generic, Optional, TypeVar
+from typing import TYPE_CHECKING, Callable, Generic, Optional, TypeVar
 
 from typing_extensions import Self
 
+from office365.runtime.http.request_options import RequestOptions
+
 if TYPE_CHECKING:
     from office365.runtime.client_runtime_context import ClientRuntimeContext  # noqa
     from office365.runtime.client_value import ClientValue  # noqa
@@ -19,21 +21,16 @@ class ClientResult(Generic[T]):
         self._context = context
         self._value = copy.deepcopy(default_value)  # type: T
 
-    def before_execute(self, action, *args, **kwargs):
-        """
-        Attach an event handler which is triggered before query is submitted to server
-        :param (office365.runtime.http.request_options.RequestOptions) -> None action: Event handler
-        """
-        self._context.before_query_execute(action, *args, **kwargs)
+    def before_execute(self, action):
+        # type: (Callable[[RequestOptions], None]) -> Self
+        """Attach an event handler which is triggered before query is submitted to server"""
+        self._context.before_query_execute(action)
         return self
 
-    def after_execute(self, action, *args, **kwargs):
-        # type: (Callable[[Self], None], Any, Any) -> Self
-        """
-        Attach an event handler which is triggered after query is submitted to server
-        :param (ClientResult) -> None action: Event handler
-        """
-        self._context.after_query_execute(action, self, *args, **kwargs)
+    def after_execute(self, action, execute_first=False):
+        # type: (Callable[[Self], None], bool) -> Self
+        """Attach an event handler which is triggered after query is submitted to server"""
+        self._context.after_query_execute(action, execute_first)
         return self
 
     def set_property(self, key, value, persist_changes=False):

office365/runtime/client_runtime_context.py

@@ -1,8 +1,9 @@
 import abc
 from time import sleep
-from typing import TYPE_CHECKING, Any, AnyStr, Callable, List
+from typing import TYPE_CHECKING, AnyStr, Callable, List
 
 import requests
+from requests import Response
 from typing_extensions import Self
 
 from office365.runtime.client_request import ClientRequest
@@ -79,21 +80,11 @@ class ClientRuntimeContext(object):
         # type: () -> str
         pass
 
-    def load(
-        self,
-        client_object,
-        properties_to_retrieve=None,
-        before_loaded=None,
-        after_loaded=None,
-    ):
-        # type: (T, List[str], Callable[[RequestOptions], None], Callable[[T], None]) -> Self
+    def load(self, client_object, properties_to_retrieve=None):
+        # type: (T, List[str]) -> Self
         """Prepare retrieval query"""
         qry = ReadEntityQuery(client_object, properties_to_retrieve)
         self.add_query(qry)
-        if callable(before_loaded):
-            self.before_query_execute(before_loaded)
-        if callable(after_loaded):
-            self.after_query_execute(after_loaded, client_object)
         return self
 
     def before_query_execute(self, action, once=True):
@@ -135,34 +126,33 @@ class ClientRuntimeContext(object):
         self.pending_request().beforeExecute += _process_request
         return self
 
-    def after_query_execute(self, action, *args, **kwargs):
-        # type: (Callable[..., None], Any, Any) -> Self
+    def after_query_execute(self, action, execute_first=False):
+        # type: (Callable[[T], None], bool) -> Self
         """Attach an event handler which is triggered after query is submitted to server"""
         if len(self._queries) == 0:
             return
         query = self._queries[-1]
 
         def _process_response(resp):
-            # type: (requests.Response) -> None
+            # type: (Response) -> None
             resp.raise_for_status()
             if self.current_query.id == query.id:
                 self.pending_request().afterExecute -= _process_response
-                action(*args, **kwargs)
+                action(query.return_type)
 
         self.pending_request().afterExecute += _process_response
 
-        execute_first = kwargs.pop("execute_first", False)
         if execute_first and len(self._queries) > 1:
             self._queries.insert(0, self._queries.pop())
 
         return self
 
     def after_execute(self, action, once=True):
-        # type: (Callable[[requests.Response], None], bool) -> Self
+        # type: (Callable[[Response], None], bool) -> Self
         """Attach an event handler which is triggered after request is submitted to server"""
 
         def _process_response(response):
-            # type: (requests.Response) -> None
+            # type: (Response) -> None
             if once:
                 self.pending_request().afterExecute -= _process_response
             action(response)
@@ -171,7 +161,7 @@ class ClientRuntimeContext(object):
         return self
 
     def execute_request_direct(self, path):
-        # type: (str) -> requests.Response
+        # type: (str) -> Response
         full_url = "".join([self.service_root_url(), "/", path])
         request = RequestOptions(full_url)
         return self.pending_request().execute_request_direct(request)

office365/runtime/odata/json_format.py

@@ -4,9 +4,10 @@ from abc import ABCMeta
 class ODataJsonFormat(object):
     """OData JSON format"""
 
-    def __init__(self, metadata_level=None):
-        # type: (str) -> None
+    def __init__(self, metadata_level=None, etag=None):
+        # type: (str, str) -> None
         self.metadata_level = metadata_level
+        self.etag = etag
 
     __metaclass__ = ABCMeta
 
@@ -24,15 +25,12 @@ class ODataJsonFormat(object):
 
     @property
     def media_type(self):
-        """
-        Gets media type
-        :rtype: str
-        """
+        # type: () -> str
+        """Gets media type"""
         raise NotImplementedError
 
     @property
     def include_control_information(self):
-        """Determines whether control information that is represented as annotations should be included in payload
-        :rtype: bool
-        """
+        # type: () -> bool
+        """Determines whether control information that is represented as annotations should be included in payload"""
         raise NotImplementedError

office365/runtime/odata/request.py

@@ -25,7 +25,7 @@ class ODataRequest(ClientRequest):
         """Creates OData request"""
         super(ODataRequest, self).__init__()
         self._default_json_format = json_format
-        self.beforeExecute += self._ensure_json_format
+        self.beforeExecute += self._ensure_http_headers
 
     @property
     def json_format(self):
@@ -111,6 +111,8 @@ class ODataRequest(ClientRequest):
                                 k: v for k, v in self._next_property(value, json_format)
                             }
                         yield name, value
+                    elif name == "@odata.etag":
+                        yield "__etag", value
             else:
                 yield "__value", json
         elif json is not None:
@@ -142,8 +144,16 @@ class ODataRequest(ClientRequest):
             json = {query.parameters_name: json}
         return json
 
-    def _ensure_json_format(self, request):
+    def _ensure_http_headers(self, request):
         # type: (RequestOptions) -> None
+        """
+        Ensures that HTTP Header Fields are specified in the OData request, namely:
+           - The Content-Type header
+           - Accept request-header field
+           - The If-Match request-header field (optional)
+        """
         media_type = self.json_format.media_type
         request.ensure_header("Content-Type", media_type)
         request.ensure_header("Accept", media_type)
+        if self.json_format.etag is not None:
+            request.ensure_header("If-Match", self.json_format.etag)

office365/runtime/odata/v3/batch_request.py

@@ -1,7 +1,7 @@
 import json
 import re
 from email.message import Message
-from typing import Iterator, Tuple
+from typing import AnyStr, Iterator, List, Tuple
 
 import requests
 from requests import Response
@@ -40,12 +40,8 @@ class ODataBatchV3Request(ODataRequest):
             super(ODataBatchV3Request, self).process_response(sub_resp, sub_qry)
 
     def _extract_response(self, response, query):
-        # type: (requests.Response, BatchQuery) -> Iterator[Tuple[ClientQuery, Response]]
-        """Parses a multipart/mixed response body from the position defined by the context.
-
-        :type response: requests.Response
-        :type query: office365.runtime.queries.batch.BatchQuery
-        """
+        # type: (Response, BatchQuery) -> Iterator[Tuple[ClientQuery, Response]]
+        """Parses a multipart/mixed response body from the position defined by the context."""
         content_type = response.headers["Content-Type"].encode("ascii")
         http_body = b"Content-Type: " + content_type + b"\r\n\r\n" + response.content
 
@@ -59,11 +55,8 @@ class ODataBatchV3Request(ODataRequest):
                 yield qry, self._deserialize_response(raw_response)
 
     def _prepare_payload(self, query):
-        """
-        Serializes a batch request body.
-
-        :type query: office365.runtime.queries.batch.BatchQuery
-        """
+        # type: (BatchQuery) -> AnyStr
+        """Serializes a batch request body."""
         main_message = Message()
         main_message.add_header("Content-Type", "multipart/mixed")
         main_message.set_boundary(query.current_boundary)
@@ -89,9 +82,8 @@ class ODataBatchV3Request(ODataRequest):
 
     @staticmethod
     def _normalize_headers(headers_raw):
-        """
-        :type headers_raw: list[str]
-        """
+        # type: (List[str]) -> CaseInsensitiveDict
+        """ """
         headers = {}
         for header_line in headers_raw:
             k, v = header_line.split(":", 1)