Office365-REST-Python-Client 2.6.1__py3-none-any.whl → 2.6.2__py3-none-any.whl

office365/reports/root.py

@@ -89,7 +89,9 @@ class ReportRoot(Entity):
             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, "getEmailActivityUserDetail", period)
+        qry = create_report_query(
+            self, "getEmailActivityUserDetail", period, return_stream=True
+        )
         self.context.add_query(qry)
         return qry.return_type
 
@@ -105,18 +107,61 @@ class ReportRoot(Entity):
         self.context.add_query(qry)
         return qry.return_type
 
+    def get_email_app_usage_user_counts(self, period):
+        """
+        Get the count of unique users that connected to Exchange Online using any 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, "getEmailAppUsageUserCounts", period, True)
+        self.context.add_query(qry)
+        return qry.return_type
+
+    ###
+    def get_email_app_usage_user_detail(self, period):
+        """
+        Get details about which activities users performed on the various email apps.
+
+        :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, "getEmailAppUsageUserDetail", period, True)
+        self.context.add_query(qry)
+        return qry.return_type
+
+    def get_mailbox_usage_storage(self, period):
+        """
+        Get the amount of storage used in your organization.
+
+        :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, "getMailboxUsageStorage", period, True)
+        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,
         PowerPoint, OneNote, and Teams) in your organization.
         """
-        return_type = ClientResult(self.context, str())
+        return_type = ClientResult(self.context, bytes())
         qry = FunctionQuery(
             self, "getM365AppUserCounts", {"period": period}, return_type
         )
         self.context.add_query(qry)
         return return_type
 
+    def get_office365_activation_counts(self):
+        """Get the count of Microsoft 365 activations on desktops and devices."""
+        qry = create_report_query(self, "getOffice365ActivationCounts")
+        self.context.add_query(qry)
+        return qry.return_type
+
     def get_office365_activations_user_counts(self):
         """Get the count of Microsoft 365 activations on desktops and devices."""
         qry = create_report_query(self, "getOffice365ActivationsUserCounts")
@@ -283,6 +328,20 @@ class ReportRoot(Entity):
         self.context.add_query(qry)
         return qry.return_type
 
+    def get_teams_team_counts(self, period):
+        """
+        Get the number of teams of a particular type in an instance of Microsoft Teams.
+
+        :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, "getTeamsTeamCounts", period, return_stream=True
+        )
+        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

@@ -1,5 +1,6 @@
 import json
 import sys
+from datetime import datetime, timedelta, timezone
 from typing import Any, Callable
 
 from typing_extensions import Required, Self, TypedDict
@@ -46,6 +47,7 @@ class AuthenticationContext(object):
         self._environment = environment
         self._allow_ntlm = allow_ntlm
         self._browser_mode = browser_mode
+        self._token_expires = datetime.max
 
     def with_client_certificate(
         self,
@@ -178,8 +180,15 @@ class AuthenticationContext(object):
         """
 
         def _authenticate(request):
-            if self._cached_token is None:
+
+            request_time = datetime.now(timezone.utc)
+
+            if self._cached_token is None or request_time > self._token_expires:
                 self._cached_token = token_func()
+                if hasattr(self._cached_token, "expiresIn"):
+                    self._token_expires = request_time + timedelta(
+                        seconds=self._cached_token.expiresIn
+                    )
             request.set_header(
                 "Authorization", _get_authorization_header(self._cached_token)
             )

office365/runtime/auth/sts_profile.py

@@ -30,7 +30,9 @@ class STSProfile(object):
     @property
     def signin_page_url(self):
         site_info = urlparse(self._site_url)
-        return "{0}://{1}/_forms/default.aspx?wa=wsignin1.0".format(site_info.scheme, site_info.netloc)
+        return "{0}://{1}/_forms/default.aspx?wa=wsignin1.0".format(
+            site_info.scheme, site_info.netloc
+        )
 
     @property
     def user_realm_service_url(self):

office365/runtime/client_object.py

@@ -86,7 +86,7 @@ class ClientObject(Generic[T]):
     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)
+        self.context.before_query_execute(action)
         return self
 
     def after_execute(self, action, execute_first=False, include_response=False):

office365/runtime/client_object_collection.py

@@ -81,14 +81,12 @@ class ClientObjectCollection(ClientObject, Generic[T]):
 
     def __iter__(self):
         # type: () -> Iterator[T]
-        for item in self._data:
-            yield item
+        yield from self._data
         if self._paged_mode:
             while self.has_next:
                 self._get_next().execute_query()
                 next_items = self._data[self._current_pos :]
-                for next_item in next_items:
-                    yield next_item
+                yield from next_items
 
     def __len__(self):
         # type: () -> int
@@ -234,7 +232,7 @@ class ClientObjectCollection(ClientObject, Generic[T]):
     @property
     def has_next(self):
         # type: () -> bool
-        """"""
+        """Determines whether the collection contains a next page of data."""
         return self._next_request_url is not None
 
     @property

office365/runtime/client_result.py

@@ -28,10 +28,10 @@ class ClientResult(Generic[T]):
         self._context.before_query_execute(action)
         return self
 
-    def after_execute(self, action, execute_first=False):
-        # type: (Callable[[Self], None], bool) -> Self
+    def after_execute(self, action, execute_first=False, include_response=False):
+        # type: (Callable[[Self], None], bool, bool) -> Self
         """Attach an event handler which is triggered after query is submitted to server"""
-        self._context.after_query_execute(action, execute_first)
+        self._context.after_query_execute(action, execute_first, include_response)
         return self
 
     def set_property(self, key, value, persist_changes=False):

office365/runtime/client_runtime_context.py

@@ -96,7 +96,7 @@ class ClientRuntimeContext(object):
         :param bool once: Flag which determines whether action is executed once or multiple times
         """
         if len(self._queries) == 0:
-            return
+            return self
         query = self._queries[-1]
 
         def _prepare_request(request):
@@ -130,7 +130,7 @@ class ClientRuntimeContext(object):
         # type: (Callable[[T|Response], None], bool, bool) -> Self
         """Attach an event handler which is triggered after query is submitted to server"""
         if len(self._queries) == 0:
-            return
+            return self
         query = self._queries[-1]
 
         def _process_response(resp):

office365/runtime/odata/json_format.py

@@ -4,10 +4,9 @@ from abc import ABCMeta
 class ODataJsonFormat(object):
     """OData JSON format"""
 
-    def __init__(self, metadata_level=None, etag=None):
-        # type: (str, str) -> None
+    def __init__(self, metadata_level=None):
+        # type: (str) -> None
         self.metadata_level = metadata_level
-        self.etag = etag
 
     __metaclass__ = ABCMeta
 
@@ -23,6 +22,18 @@ class ODataJsonFormat(object):
     def collection_next(self):
         raise NotImplementedError
 
+    @property
+    def collection_delta(self):
+        raise NotImplementedError
+
+    @property
+    def etag(self):
+        raise NotImplementedError
+
+    @property
+    def value_tag(self):
+        raise NotImplementedError
+
     @property
     def media_type(self):
         # type: () -> str

office365/runtime/odata/request.py

@@ -99,7 +99,7 @@ class ODataRequest(ClientRequest):
             elif isinstance(json, dict):
                 for name, value in json.items():
                     if isinstance(json_format, JsonLightFormat):
-                        is_valid = name != "__metadata" and not (
+                        is_valid = name != json_format.metadata_type and not (
                             isinstance(value, dict) and "__deferred" in value
                         )
                     else:
@@ -155,5 +155,3 @@ class ODataRequest(ClientRequest):
         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/json_light_format.py

@@ -25,10 +25,28 @@ class JsonLightFormat(ODataJsonFormat):
         """Property name for a reference to the next page of results"""
         return "__next"
 
+    @property
+    def collection_delta(self):
+        """Property name for a reference to the next page of results"""
+        return "__delta"
+
     @property
     def metadata_type(self):
         return "__metadata"
 
+    @property
+    def deferred_type(self):
+        return "__deferred"
+
+    @property
+    def value_tag(self):
+        return "__value"
+
+    @property
+    def etag(self):
+        """The entity tag that represents the version of the object."""
+        return "__etag"
+
     @property
     def media_type(self):
         return "application/json;odata={0}".format(self.metadata_level)

office365/runtime/odata/v4/json_format.py

@@ -14,16 +14,35 @@ class V4JsonFormat(ODataJsonFormat):
 
     @property
     def metadata_type(self):
+        """The OData entity type in Microsoft Graph that describes the represented object."""
         return "@odata.type"
 
+    @property
+    def value_tag(self):
+        """The OData entity type in Microsoft Graph that describes the represented object."""
+        return "@odata.value"
+
     @property
     def collection(self):
         return "value"
 
     @property
     def collection_next(self):
+        """
+        Property name for a reference to the next page of results
+        """
         return "@odata.nextLink"
 
+    @property
+    def collection_delta(self):
+        """ """
+        return "@odata.deltaLink"
+
+    @property
+    def etag(self):
+        """The entity tag that represents the version of the object."""
+        return "@odata.etag"
+
     @property
     def media_type(self):
         return "application/json;odata.metadata={0};odata.streaming={1};IEEE754Compatible={2}".format(

office365/runtime/queries/client_query.py

@@ -1,4 +1,15 @@
-class ClientQuery(object):
+from typing import TYPE_CHECKING, AnyStr, Dict, Generic, Optional, TypeVar, Union
+
+if TYPE_CHECKING:
+    from office365.runtime.client_object import ClientObject
+    from office365.runtime.client_result import ClientResult
+    from office365.runtime.client_runtime_context import ClientRuntimeContext
+    from office365.runtime.client_value import ClientValue
+
+T = TypeVar("T", bound=Union["ClientObject", "ClientResult"])
+
+
+class ClientQuery(Generic[T]):
     """Client query"""
 
     def __init__(
@@ -9,15 +20,9 @@ class ClientQuery(object):
         parameters_name=None,
         return_type=None,
     ):
+        # type: (ClientRuntimeContext, Optional[ClientObject], Optional[ClientObject|ClientValue|Dict|AnyStr], Optional[str], Optional[T]) -> None
         """
         Generic query
-
-        :type context: office365.runtime.client_runtime_context.ClientRuntimeContext
-        :type binding_type: office365.runtime.client_object.ClientObject or None
-        :type parameters_type: office365.runtime.client_object.ClientObject or ClientValue or dict or bytes or None
-        :type parameters_name: str or None
-        :type return_type: office365.runtime.client_object.ClientObject
-            or office365.runtime.client_result.ClientResult or None
         """
         self._context = context
         self._binding_type = binding_type

office365/runtime/queries/create_entity.py

@@ -1,13 +1,15 @@
-from typing import Dict
+from typing import TYPE_CHECKING, Dict
 
-from office365.runtime.client_object import ClientObject
 from office365.runtime.client_value import ClientValue
-from office365.runtime.queries.client_query import ClientQuery
+from office365.runtime.queries.client_query import ClientQuery, T
 
+if TYPE_CHECKING:
+    from office365.runtime.client_object import ClientObject
 
-class CreateEntityQuery(ClientQuery):
+
+class CreateEntityQuery(ClientQuery[T]):
     def __init__(self, parent_entity, parameters, return_type=None):
-        # type: (ClientObject, ClientObject|ClientValue|Dict, ClientObject) -> None
+        # type: (ClientObject, ClientObject|ClientValue|Dict, T) -> None
         """Create entity query"""
         super(CreateEntityQuery, self).__init__(
             parent_entity.context, parent_entity, parameters, None, return_type

office365/runtime/queries/delete_entity.py

@@ -1,11 +1,15 @@
+from typing import TYPE_CHECKING
+
 from office365.runtime.queries.client_query import ClientQuery
 
+if TYPE_CHECKING:
+    from office365.runtime.client_object import ClientObject
+
 
 class DeleteEntityQuery(ClientQuery):
     def __init__(self, delete_type):
+        # type: (ClientObject) -> None
         """
         Delete entity query
-
-        :type delete_type: office365.runtime.client_object.ClientObject
         """
         super(DeleteEntityQuery, self).__init__(delete_type.context, delete_type)

office365/runtime/queries/function.py

@@ -1,17 +1,16 @@
 from office365.runtime.client_object import ClientObject
-from office365.runtime.client_result import ClientResult
 from office365.runtime.client_value import ClientValue
 from office365.runtime.paths.service_operation import ServiceOperationPath
-from office365.runtime.queries.client_query import ClientQuery
+from office365.runtime.queries.client_query import ClientQuery, T
 
 
-class FunctionQuery(ClientQuery):
+class FunctionQuery(ClientQuery[T]):
     """Function query"""
 
     def __init__(
         self, binding_type, method_name=None, method_params=None, return_type=None
     ):
-        # type: (ClientObject, str, list|dict|ClientValue, ClientObject|ClientResult) -> None
+        # type: (ClientObject, str, list|dict|ClientValue, T) -> None
         """Function query"""
         super(FunctionQuery, self).__init__(
             binding_type.context, binding_type, None, None, return_type

office365/runtime/queries/read_entity.py

@@ -1,14 +1,12 @@
 from office365.runtime.odata.query_options import QueryOptions
-from office365.runtime.queries.client_query import ClientQuery
+from office365.runtime.queries.client_query import ClientQuery, T
 
 
-class ReadEntityQuery(ClientQuery):
+class ReadEntityQuery(ClientQuery[T]):
     def __init__(self, return_type, properties_to_include=None):
+        # type: (T, list[str]) -> None
         """
         Read client object query
-
-        :type properties_to_include: list[str] or None
-        :type return_type: office365.runtime.client_object.ClientObject
         """
         super(ReadEntityQuery, self).__init__(
             return_type.context, return_type, None, None, return_type

office365/runtime/queries/service_operation.py

@@ -1,8 +1,8 @@
 from office365.runtime.paths.service_operation import ServiceOperationPath
-from office365.runtime.queries.client_query import ClientQuery
+from office365.runtime.queries.client_query import ClientQuery, T
 
 
-class ServiceOperationQuery(ClientQuery):
+class ServiceOperationQuery(ClientQuery[T]):
     """ "Service operation query"""
 
     def __init__(
@@ -15,11 +15,6 @@ class ServiceOperationQuery(ClientQuery):
         return_type=None,
         is_static=False,
     ):
-        """
-
-        :type method_params: list or dict or office365.runtime.client_value.ClientValue or None
-        :type method_name: str or None
-        """
         super(ServiceOperationQuery, self).__init__(
             binding_type.context,
             binding_type,

office365/search/answer.py

@@ -1,9 +1,44 @@
+from datetime import datetime
+from typing import Optional
+
 from office365.entity import Entity
+from office365.search.identity_set import IdentitySet
 
 
 class SearchAnswer(Entity):
     """Represents the base type for other search answers."""
 
+    @property
+    def description(self):
+        # type: () -> Optional[str]
+        """The search answer description that is shown on the search results page."""
+        return self.properties.get("description", None)
+
+    @property
+    def display_name(self):
+        # type: () -> Optional[str]
+        """The search answer name that is displayed in search results."""
+        return self.properties.get("displayName", None)
+
+    @property
+    def last_modified_by(self):
+        # type: () -> IdentitySet
+        """Details of the user who created or last modified the search answer."""
+        return self.properties.get("lastModifiedBy", IdentitySet())
+
+    @property
+    def last_modified_datetime(self):
+        # type: () -> Optional[datetime]
+        """Date and time when the search answer was created or last edited."""
+        return self.properties.get("lastModifiedDateTime", datetime.min)
+
+    @property
+    def web_url(self):
+        # type: () -> Optional[str]
+        """The URL link for the search answer. When users select this search answer from the search results,
+        they are directed to the specified URL."""
+        return self.properties.get("webUrl", None)
+
     @property
     def entity_type_name(self):
         return "microsoft.graph.search.searchAnswer"

office365/search/bookmarks/bookmark.py

@@ -0,0 +1,7 @@
+from office365.search.answer import SearchAnswer
+
+
+class Bookmark(SearchAnswer):
+    """Represents a bookmark that is an administrative answer in Microsoft Search results for common search queries
+    in an organization. A bookmark has many properties that allow administrators to make common resources more
+    accessible in their organization."""

office365/search/entity.py

@@ -7,9 +7,11 @@ from office365.runtime.client_value_collection import ClientValueCollection
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.paths.v4.entity import EntityPath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
-from office365.search.acronym import Acronym
+from office365.search.acronyms.acronym import Acronym
+from office365.search.bookmarks.bookmark import Bookmark
 from office365.search.entity_type import EntityType
 from office365.search.hit import SearchHit
+from office365.search.qnas.qna import Qna
 from office365.search.query import SearchQuery
 from office365.search.request import SearchRequest
 from office365.search.response import SearchResponse
@@ -28,8 +30,9 @@ class SearchEntity(Entity):
         page_from=None,
         size=None,
         enable_top_results=None,
+        region=None,
     ):
-        # type: (str, Optional[List[str]], Optional[int], Optional[int], Optional[bool]) -> ClientResult[ClientValueCollection[SearchResponse]]
+        # type: (str, Optional[List[str]], Optional[int], Optional[int], Optional[bool], Optional[str]) -> ClientResult[ClientValueCollection[SearchResponse]]
         """
         Runs the query specified in the request body. Search results are provided in the response.
 
@@ -39,6 +42,8 @@ class SearchEntity(Entity):
         :param int page_from: Specifies the offset for the search results. Offset 0 returns the very first result.
         :param int size: The size of the page to be retrieved. The maximum value is 500. Optional.
         :param bool enable_top_results: This triggers hybrid sort for messages
+        :param str region: The geographic location for the search. Required for searches that use application
+             permissions. For details, see Get the region value.
         """
         search_request = SearchRequest(
             query=SearchQuery(query_string),
@@ -46,6 +51,7 @@ class SearchEntity(Entity):
             page_from=page_from,
             size=size,
             enable_top_results=enable_top_results,
+            region=region,
         )
 
         def _patch_hit(search_hit):
@@ -106,6 +112,54 @@ class SearchEntity(Entity):
             size=size,
         )
 
+    def query_list_items(self, query_string, page_from=None, size=None, region=None):
+        """Searches list items. Alias to query method
+
+        :param str query_string: Contains the query terms.
+        :param int page_from: Specifies the offset for the search results. Offset 0 returns the very first result.
+        :param int size: The size of the page to be retrieved. The maximum value is 500.
+        :param str region: The geographic location for the search. Required for searches that use application
+        """
+        return self.query(
+            query_string,
+            entity_types=[EntityType.listItem],
+            page_from=page_from,
+            size=size,
+            region=region,
+        )
+
+    def query_peoples(self, query_string, page_from=None, size=None, region=None):
+        """Searches peoples. Alias to query method
+
+        :param str query_string: Contains the query terms.
+        :param int page_from: Specifies the offset for the search results. Offset 0 returns the very first result.
+        :param int size: The size of the page to be retrieved. The maximum value is 500.
+        :param str region: The geographic location for the search. Required for searches that use application
+        """
+        return self.query(
+            query_string,
+            entity_types=[EntityType.person],
+            page_from=page_from,
+            size=size,
+            region=region,
+        )
+
+    def query_sites(self, query_string, page_from=None, size=None, region=None):
+        """Searches sites. Alias to query method
+
+        :param str query_string: Contains the query terms.
+        :param int page_from: Specifies the offset for the search results. Offset 0 returns the very first result.
+        :param int size: The size of the page to be retrieved. The maximum value is 500.
+        :param str region: The geographic location for the search. Required for searches that use application
+        """
+        return self.query(
+            query_string,
+            entity_types=[EntityType.site],
+            page_from=page_from,
+            size=size,
+            region=region,
+        )
+
     @property
     def acronyms(self):
         """Administrative answer in Microsoft Search results to define common acronyms in an organization."""
@@ -117,3 +171,28 @@ class SearchEntity(Entity):
                 ResourcePath("acronyms", self.resource_path),
             ),
         )
+
+    @property
+    def bookmarks(self):
+        """Administrative answer in Microsoft Search results for common search queries in an organization."""
+        return self.properties.get(
+            "bookmarks",
+            EntityCollection(
+                self.context,
+                Bookmark,
+                ResourcePath("bookmarks", self.resource_path),
+            ),
+        )
+
+    @property
+    def qnas(self):
+        """Administrative answer in Microsoft Search results that provide answers for specific search keywords in
+        an organization."""
+        return self.properties.get(
+            "qnas",
+            EntityCollection(
+                self.context,
+                Qna,
+                ResourcePath("qnas", self.resource_path),
+            ),
+        )

office365/search/entity_type.py

@@ -7,6 +7,8 @@ from office365.onedrive.lists.list import List
 from office365.onedrive.sites.site import Site
 from office365.outlook.calendar.events.event import Event
 from office365.outlook.mail.messages.message import Message
+from office365.outlook.person import Person
+from office365.search.external.item import ExternalItem
 
 
 class EntityType:
@@ -20,7 +22,8 @@ class EntityType:
         "message": Message,
         "drive": Drive,
         "driveItem": DriveItem,
-        # "externalItem": ExternalItem
+        "externalItem": ExternalItem,
+        "person": Person,
     }
 
     def __init__(self):
@@ -47,3 +50,5 @@ class EntityType:
     driveItem = "driveItem"
 
     externalItem = "externalItem"
+
+    person = "person"