Office365-REST-Python-Client 2.5.4__py3-none-any.whl → 2.5.6__py3-none-any.whl

office365/outlook/calendar/place.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.entity import Entity
 from office365.outlook.mail.physical_address import PhysicalAddress
 
@@ -8,9 +10,8 @@ class Place(Entity):
 
     @property
     def display_name(self):
-        """The name associated with the place.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The name associated with the place."""
         return self.properties.get("displayName", None)
 
     @property
@@ -20,5 +21,6 @@ class Place(Entity):
 
     @property
     def phone(self):
+        # type: () -> Optional[str]
         """The phone number of the place."""
         return self.properties.get("phone", None)

office365/outlook/mail/attachments/collection.py

@@ -4,7 +4,10 @@ import requests
 
 from office365.entity_collection import EntityCollection
 from office365.outlook.mail.attachments.attachment import Attachment
+from office365.runtime.client_result import ClientResult
 from office365.runtime.compat import parse_query_string
+from office365.runtime.http.request_options import RequestOptions
+from office365.runtime.odata.v4.upload_session import UploadSession
 from office365.runtime.odata.v4.upload_session_request import UploadSessionRequest
 from office365.runtime.queries.upload_session import UploadSessionQuery
 
@@ -60,13 +63,15 @@ class AttachmentCollection(EntityCollection[Attachment]):
             self, {"AttachmentItem": AttachmentItem.create_file(source_path)}
         )
 
-        def _start_upload():
+        def _start_upload(result):
+            # type: (ClientResult[UploadSession]) -> None
             with open(source_path, "rb") as local_file:
                 session_request = UploadSessionRequest(
                     local_file, chunk_size, chunk_uploaded
                 )
 
                 def _construct_request(request):
+                    # type: (RequestOptions) -> None
                     auth_token = parse_query_string(request.url, "authtoken")
                     request.set_header("Authorization", "Bearer {0}".format(auth_token))
 

office365/outlook/mail/attachments/file.py

@@ -1,3 +1,5 @@
+from typing import AnyStr, Optional
+
 from office365.outlook.mail.attachments.attachment import Attachment
 
 
@@ -6,32 +8,23 @@ class FileAttachment(Attachment):
 
     @property
     def content_id(self):
-        """
-        The ID of the attachment in the Exchange store.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The ID of the attachment in the Exchange store."""
         return self.properties.get("contentId", None)
 
     @property
     def content_location(self):
-        """
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """ """
         return self.properties.get("content_location", None)
 
     @property
     def content_bytes(self):
-        """
-        The base64-encoded contents of the file.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[AnyStr]
+        """The base64-encoded contents of the file."""
         return self.properties.get("contentBytes", None)
 
     @content_bytes.setter
     def content_bytes(self, value):
-        """
-        Sets the base64-encoded contents of the file.
-        """
+        """Sets the base64-encoded contents of the file."""
         self.set_property("contentBytes", value)

office365/outlook/mail/messages/message.py

@@ -103,7 +103,7 @@ class Message(OutlookItem):
         if a file that's smaller than 3 MB, then add_file_attachment method is utilized
 
         :param str file_path:
-        :param ()->None chunk_uploaded: Upload action
+        :param (int)->None chunk_uploaded: Upload action
         """
         max_upload_chunk = 1000000 * 3
         file_size = os.stat(file_path).st_size

office365/planner/user.py

@@ -10,9 +10,7 @@ class PlannerUser(Entity):
 
     @property
     def plans(self):
-        """
-        Returns the plannerTasks assigned to the user.
-        """
+        """Returns the plannerTasks assigned to the user."""
         from office365.planner.plans.collection import PlannerPlanCollection
 
         return self.properties.get(
@@ -24,10 +22,8 @@ class PlannerUser(Entity):
 
     @property
     def tasks(self):
-        """Read-only. Nullable. Returns the plannerTasks assigned to the user.
-
-        :rtype: EntityCollection
-        """
+        # type: () -> EntityCollection[PlannerTask]
+        """Returns the plannerTasks assigned to the user."""
         return self.properties.get(
             "tasks",
             EntityCollection(

office365/reports/root.py

@@ -72,6 +72,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 +97,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 +175,19 @@ 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_sharepoint_activity_pages(self, period):
         """
         Get the number of unique pages visited by users.
@@ -203,6 +225,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/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
@@ -34,7 +35,7 @@ class ClientObject(Generic[T]):
         self._entity_type_name = None
         self._resource_path = resource_path
 
-    def clear(self):
+    def clear_state(self):
         # type: () -> Self
         """Resets client object's state."""
         self._properties = {
@@ -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)
 
@@ -172,12 +172,12 @@ class ClientObject(Generic[T]):
         return self
 
     def ensure_property(self, name, action, *args, **kwargs):
-        # type: (str, Callable[[], None], Any, Any) -> Self
+        # type: (str, Callable[..., None], Optional[Any], Optional[Any]) -> Self
         """Ensures if property is loaded"""
         return self.ensure_properties([name], action, *args, **kwargs)
 
     def ensure_properties(self, names, action, *args, **kwargs):
-        # type: (List[str], Callable[[Any, Any], None], Any, Any) -> Self
+        # type: (List[str], Callable[..., None], Any, Any) -> Self
         """Ensure if list of properties are retrieved from the server"""
         if self.property_ref_name is not None and self.property_ref_name not in names:
             names.append(self.property_ref_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
 
@@ -25,7 +25,7 @@ class ClientObjectCollection(ClientObject, Generic[T]):
         self._next_request_url = None
         self._parent = parent
 
-    def clear(self):
+    def clear_state(self):
         """Clears client object collection"""
         if not self._paged_mode:
             self._data = []
@@ -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
@@ -33,9 +34,7 @@ class ClientRuntimeContext(object):
 
     def build_request(self, query):
         # type: (ClientQuery) -> RequestOptions
-        """
-        Builds a request
-        """
+        """Builds a request"""
         self._current_query = query
         request = self.pending_request().build_request(query)
         self.pending_request().beforeExecute.notify(request)
@@ -81,25 +80,15 @@ 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, *args, **kwargs):
-        # type: (Callable[[RequestOptions, Any, Any], None], bool, Any, Any) -> Self
+    def before_query_execute(self, action, once=True):
+        # type: (Callable[[RequestOptions], None], bool) -> Self
         """
         Attach an event handler which is triggered before query is submitted to server
 
@@ -115,13 +104,13 @@ class ClientRuntimeContext(object):
             if self.current_query.id == query.id:
                 if once:
                     self.pending_request().beforeExecute -= _prepare_request
-                action(request, *args, **kwargs)
+                action(request)
 
         self.pending_request().beforeExecute += _prepare_request
         return self
 
-    def before_execute(self, action, once=True, *args, **kwargs):
-        # type: (Callable[[RequestOptions, Any, Any], None], bool, Any, Any) -> Self
+    def before_execute(self, action, once=True):
+        # type: (Callable[[RequestOptions], None], bool) -> Self
         """
         Attach an event handler which is triggered before request is submitted to server
         :param (office365.runtime.http.request_options.RequestOptions, any) -> None action:
@@ -132,48 +121,47 @@ class ClientRuntimeContext(object):
             # type: (RequestOptions) -> None
             if once:
                 self.pending_request().beforeExecute -= _process_request
-            action(request, *args, **kwargs)
+            action(request)
 
         self.pending_request().beforeExecute += _process_request
         return self
 
-    def after_query_execute(self, action, *args, **kwargs):
-        # type: (Callable[[Any, Any], 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, *args, **kwargs):
-        # type: (Callable[[requests.Response, Any, Any], None], bool, Any, Any) -> Self
+    def after_execute(self, action, once=True):
+        # 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, *args, **kwargs)
+            action(response)
 
         self.pending_request().afterExecute += _process_response
         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

@@ -24,15 +24,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

@@ -1,5 +1,5 @@
 import copy
-from typing import Any, Optional
+from typing import Any, Iterator, Optional, Tuple
 
 import requests
 
@@ -54,7 +54,7 @@ class ODataRequest(ClientRequest):
             return
 
         if isinstance(return_type, ClientObject):
-            return_type.clear()
+            return_type.clear_state()
 
         if (
             response.headers.get("Content-Type", "").lower().split(";")[0]
@@ -79,7 +79,7 @@ class ODataRequest(ClientRequest):
                 return_type.set_property(k, v, False)
 
     def _next_property(self, json, json_format):
-        # type: (Any, ODataJsonFormat) -> None
+        # type: (Any, ODataJsonFormat) -> Iterator[Tuple[str, Any]]
         if isinstance(json_format, JsonLightFormat):
             json = json.get(json_format.security, json)
             json = json.get(json_format.function, json)