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

office365/onedrive/workbooks/worksheets/worksheet.py

@@ -20,8 +20,12 @@ class WorkbookWorksheet(Entity):
     def __repr__(self):
         return self.name
 
+    def __str__(self):
+        return self.name
+
     @property
     def charts(self):
+        # type: () -> EntityCollection[WorkbookChart]
         """Returns collection of charts that are part of the worksheet"""
         return self.properties.get(
             "charts",
@@ -33,9 +37,7 @@ class WorkbookWorksheet(Entity):
     @property
     def name(self):
         # type: () -> Optional[str]
-        """
-        The display name of the worksheet.
-        """
+        """The display name of the worksheet."""
         return self.properties.get("name", None)
 
     @property

office365/onenote/pages/collection.py

@@ -1,3 +1,5 @@
+from typing import IO
+
 from office365.entity_collection import EntityCollection
 from office365.onenote.internal.multipart_page_query import OneNotePageCreateQuery
 from office365.onenote.pages.page import OnenotePage
@@ -10,12 +12,11 @@ class OnenotePageCollection(EntityCollection[OnenotePage]):
         super(OnenotePageCollection, self).__init__(context, OnenotePage, resource_path)
 
     def add(self, presentation_file, attachment_files=None):
+        # type: (IO, dict) -> OnenotePage
         """
         Create a new OneNote page.
-
         :param typing.IO presentation_file: Presentation file
         :param dict or None attachment_files: Attachment files
-        :rtype: OnenotePage
         """
         qry = OneNotePageCreateQuery(self, presentation_file, attachment_files)
         self.context.add_query(qry)

office365/onenote/resources/resource.py

@@ -1,3 +1,5 @@
+from typing import AnyStr, Optional
+
 from office365.onenote.entity_base_model import OnenoteEntityBaseModel
 from office365.runtime.client_result import ClientResult
 from office365.runtime.queries.function import FunctionQuery
@@ -7,6 +9,7 @@ class OnenoteResource(OnenoteEntityBaseModel):
     """An image or other file resource on a OneNote page."""
 
     def get_content(self):
+        # type: () -> ClientResult[AnyStr]
         """Retrieve the binary data of a file or image resource object."""
         return_type = ClientResult(self.context)
         qry = FunctionQuery(self, "content", None, return_type)
@@ -15,8 +18,6 @@ class OnenoteResource(OnenoteEntityBaseModel):
 
     @property
     def content_url(self):
-        """The URL for downloading the content
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The URL for downloading the content"""
         return self.properties.get("contentUrl", None)

office365/onenote/sectiongroups/section_group.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.entity_collection import EntityCollection
 from office365.onenote.entity_hierarchy_model import OnenoteEntityHierarchyModel
 from office365.onenote.notebooks.notebook import Notebook
@@ -10,22 +12,21 @@ class SectionGroup(OnenoteEntityHierarchyModel):
 
     @property
     def section_groups_url(self):
-        """The URL for the sectionGroups navigation property, which returns all the section groups in the section group.
-
-        :rtype: str or None
+        # type: () -> Optional[str]
+        """
+        The URL for the sectionGroups navigation property, which returns all the section groups in the section group.
         """
         return self.properties.get("sectionGroupsUrl", None)
 
     @property
     def sections_url(self):
-        """The URL for the sections navigation property, which returns all the sections in the section group.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The URL for the sections navigation property, which returns all the sections in the section group."""
         return self.properties.get("sectionsUrl", None)
 
     @property
     def parent_notebook(self):
+        # type: () -> Notebook
         """The notebook that contains the section group. Read-only."""
         return self.properties.get(
             "parentNotebook",
@@ -34,6 +35,7 @@ class SectionGroup(OnenoteEntityHierarchyModel):
 
     @property
     def sections(self):
+        # type: () -> EntityCollection[OnenoteSection]
         """The sections in the section group. Read-only. Nullable."""
         return self.properties.get(
             "sections",
@@ -46,6 +48,7 @@ class SectionGroup(OnenoteEntityHierarchyModel):
 
     @property
     def section_groups(self):
+        # type: () -> EntityCollection[SectionGroup]
         """Retrieve a list of onenoteSection objects from the specified notebook."""
         return self.properties.get(
             "sectionGroups",

office365/outlook/calendar/calendar.py

@@ -28,7 +28,7 @@ class Calendar(Entity):
     """
 
     def __repr__(self):
-        return self.name
+        return self.name or self.id or self.entity_type_name
 
     def allowed_calendar_sharing_roles(self, user):
         """

office365/outlook/calendar/schedule/information.py

@@ -17,7 +17,6 @@ class ScheduleInformation(ClientValue):
         working_hours=WorkingHours(),
     ):
         """
-
         :param WorkingHours working_hours: The days of the week and hours in a specific time zone that the user works.
              These are set as part of the user's mailboxSettings.
         :param str error: Error information from attempting to get the availability of the user, distribution list,

office365/outlook/contacts/contact.py

@@ -45,25 +45,19 @@ class Contact(OutlookItem):
     @manager.setter
     def manager(self, value):
         # type: (str) -> None
-        """
-        Sets name of the contact's manager.
-        """
+        """Sets name of the contact's manager."""
         self.set_property("manager", value)
 
     @property
     def mobile_phone(self):
         # type: () -> Optional[str]
-        """
-        The contact's mobile phone number.
-        """
+        """The contact's mobile phone number."""
         return self.properties.get("mobilePhone", None)
 
     @mobile_phone.setter
     def mobile_phone(self, value):
         # type: (str) -> None
-        """
-        Sets contact's mobile phone number.
-        """
+        """Sets contact's mobile phone number."""
         self.set_property("mobilePhone", value)
 
     @property

office365/outlook/contacts/folder.py

@@ -24,6 +24,7 @@ class ContactFolder(Entity):
 
     @property
     def child_folders(self):
+        # type: () -> EntityCollection["ContactFolder"]
         """The collection of child folders in the folder. Navigation property. Read-only. Nullable."""
         return self.properties.get(
             "childFolders",
@@ -36,6 +37,7 @@ class ContactFolder(Entity):
 
     @property
     def multi_value_extended_properties(self):
+        # type: () -> EntityCollection[MultiValueLegacyExtendedProperty]
         """The collection of multi-value extended properties defined for the Contact folder."""
         return self.properties.get(
             "multiValueExtendedProperties",
@@ -48,6 +50,7 @@ class ContactFolder(Entity):
 
     @property
     def single_value_extended_properties(self):
+        # type: () -> EntityCollection[SingleValueLegacyExtendedProperty]
         """The collection of single-value extended properties defined for the Contact folder."""
         return self.properties.get(
             "singleValueExtendedProperties",

office365/outlook/item.py

@@ -1,4 +1,5 @@
 import datetime
+from typing import Optional
 
 from office365.entity import Entity
 from office365.runtime.types.collections import StringCollection
@@ -7,18 +8,16 @@ from office365.runtime.types.collections import StringCollection
 class OutlookItem(Entity):
     @property
     def change_key(self):
+        # type: () -> Optional[str]
         """
         Identifies the version of the item. Every time the item is changed, changeKey changes as well.
         This allows Exchange to apply changes to the correct version of the object.
-        :rtype: str
         """
         return self.properties.get("ChangeKey", None)
 
     @property
     def categories(self):
-        """
-        The categories associated with the item
-        """
+        """The categories associated with the item"""
         return self.properties.get("categories", StringCollection())
 
     @property

office365/outlook/mail/messages/message.py

@@ -174,17 +174,30 @@ class Message(OutlookItem):
         self.context.add_query(qry)
         return self
 
-    def move(self, destination_id):
+    def move(self, destination):
         """
         Move a message to another folder within the specified user's mailbox.
         This creates a new copy of the message in the destination folder and removes the original message.
 
-        :param str destination_id: The destination folder ID, or a well-known folder name.
+        :param str or MailFolder destination: The destination folder ID, or a well-known folder name.
             For a list of supported well-known folder names, see mailFolder resource type.
         """
-        payload = {"DestinationId": destination_id}
-        qry = ServiceOperationQuery(self, "move", None, payload, None, None)
-        self.context.add_query(qry)
+        from office365.outlook.mail.folders.folder import MailFolder
+
+        def _move(destination_id):
+            # type: (str) -> None
+            payload = {"DestinationId": destination_id}
+            qry = ServiceOperationQuery(self, "move", None, payload, None, None)
+            self.context.add_query(qry)
+
+        if isinstance(destination, MailFolder):
+
+            def _loaded():
+                _move(destination.id)
+
+            destination.ensure_property("id", _loaded)
+        else:
+            _move(destination)
         return self
 
     def forward(self, to_recipients, comment=""):
@@ -205,13 +218,12 @@ class Message(OutlookItem):
 
     @property
     def has_attachments(self):
+        # type: () -> Optional[bool]
         """
         Indicates whether the message has attachments. This property doesn't include inline attachments,
         so if a message contains only inline attachments, this property is false. To verify the existence
         of inline attachments, parse the body property to look for a src attribute,
         such as <IMG src="cid:image001.jpg@01D26CD8.6C05F070">.
-
-        :rtype: bool or None
         """
         return self.properties.get("hasAttachments", None)
 
@@ -229,6 +241,7 @@ class Message(OutlookItem):
 
     @property
     def extensions(self):
+        # type: () -> EntityCollection[Extension]
         """The collection of open extensions defined for the message. Nullable."""
         return self.properties.get(
             "extensions",
@@ -253,24 +266,19 @@ class Message(OutlookItem):
     @property
     def body_preview(self):
         # type: () -> Optional[str]
-        """
-        The first 255 characters of the message body. It is in text format."""
+        """The first 255 characters of the message body. It is in text format."""
         return self.properties.get("bodyPreview", None)
 
     @property
     def conversation_id(self):
         # type: () -> Optional[str]
-        """
-        The ID of the conversation the email belongs to.
-        """
+        """The ID of the conversation the email belongs to."""
         return self.properties.get("conversationId", None)
 
     @property
     def conversation_index(self):
         # type: () -> Optional[str]
-        """
-        Indicates the position of the message within the conversation.
-        """
+        """Indicates the position of the message within the conversation."""
         return self.properties.get("conversationIndex", None)
 
     @property
@@ -292,9 +300,7 @@ class Message(OutlookItem):
     @property
     def importance(self):
         # type: () -> Optional[str]
-        """
-        The importance of the message.
-        """
+        """The importance of the message."""
         return self.properties.get("importance", None)
 
     @property
@@ -308,6 +314,7 @@ class Message(OutlookItem):
 
     @property
     def internet_message_headers(self):
+        # type: () -> ClientValueCollection[InternetMessageHeader]
         """
         A collection of message headers defined by RFC5322. The set includes message headers indicating the network
         path taken by a message from the sender to the recipient. It can also contain custom message headers that

office365/outlook/mail/recipient.py

@@ -5,10 +5,12 @@ from office365.runtime.client_value import ClientValue
 class Recipient(ClientValue):
     """Represents information about a user in the sending or receiving end of an event, message or group post."""
 
-    def __init__(self, email_address=EmailAddress()):
+    def __init__(self, email_address=None):
         """
         :param EmailAddress email_address: The recipient's email address.
         """
+        if email_address is None:
+            email_address = EmailAddress()
         super(Recipient, self).__init__()
         self.emailAddress = email_address
 

office365/runtime/auth/authentication_context.py

@@ -1,8 +1,8 @@
 import json
 import sys
-from typing import Any, Callable, TypedDict
+from typing import Any, Callable
 
-from typing_extensions import Required
+from typing_extensions import Required, TypedDict
 
 from office365.runtime.auth.client_credential import ClientCredential
 from office365.runtime.auth.providers.acs_token_provider import ACSTokenProvider
@@ -173,8 +173,9 @@ class AuthenticationContext(object):
         :param UserCredential or ClientCredential credentials:
         """
         if isinstance(credentials, ClientCredential):
+            environment = kwargs.get("environment")
             provider = ACSTokenProvider(
-                self.url, credentials.clientId, credentials.clientSecret
+                self.url, credentials.clientId, credentials.clientSecret, environment
             )
         elif isinstance(credentials, UserCredential):
             allow_ntlm = kwargs.get("allow_ntlm", False)
@@ -184,8 +185,9 @@ class AuthenticationContext(object):
                 provider = NtlmProvider(credentials.userName, credentials.password)
             else:
                 browser_mode = kwargs.get("browser_mode", False)
+                environment = kwargs.get("environment")
                 provider = SamlTokenProvider(
-                    self.url, credentials.userName, credentials.password, browser_mode
+                    self.url, credentials.userName, credentials.password, browser_mode, environment
                 )
         else:
             raise ValueError("Unknown credential type")

office365/runtime/auth/providers/acs_token_provider.py

@@ -1,19 +1,24 @@
+from typing import Optional
+
 import requests
 
 import office365.logger
 from office365.runtime.auth.authentication_provider import AuthenticationProvider
 from office365.runtime.auth.token_response import TokenResponse
 from office365.runtime.compat import urlparse
+from office365.runtime.http.request_options import RequestOptions
 
 
 class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
-    def __init__(self, url, client_id, client_secret):
+    def __init__(self, url, client_id, client_secret, environment='commercial'):
         """
         Provider to acquire the access token from a Microsoft Azure Access Control Service (ACS)
 
         :param str client_id: The OAuth client id of the calling application.
         :param str client_secret: Secret string that the application uses to prove its identity when requesting a token
         :param str url: SharePoint web or site url
+        :param str environment: The Office 365 Cloud Environment endpoint used for authentication
+            defaults to 'commercial'.
         """
         self.url = url
         self.redirect_url = None
@@ -22,11 +27,10 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         self._client_id = client_id
         self._client_secret = client_secret
         self._cached_token = None
+        self._environment = environment
 
     def authenticate_request(self, request):
-        """
-        :type request: office365.runtime.http.request_options.RequestOptions
-        """
+        # type: (RequestOptions) -> None
         self.ensure_app_only_access_token()
         request.set_header("Authorization", self._get_authorization_header())
 
@@ -36,9 +40,7 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         return self._cached_token and self._cached_token.is_valid
 
     def get_app_only_access_token(self):
-        """
-        Retrieves an app-only access token from ACS
-        """
+        """Retrieves an app-only access token from ACS"""
         try:
             realm = self._get_realm_from_target_url()
             url_info = urlparse(self.url)
@@ -63,7 +65,7 @@ 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)
+        sts_url = self.get_security_token_service_url(target_realm, environment=self._environment)
         oauth2_request = {
             "grant_type": "client_credentials",
             "client_id": principal_id,
@@ -86,9 +88,7 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
 
     @staticmethod
     def process_realm_response(response):
-        """
-        :type response: requests.Response
-        """
+        # type: (requests.Response) -> Optional[str]
         header_key = "WWW-Authenticate"
         if header_key in response.headers:
             auth_values = response.headers[header_key].split(",")
@@ -98,15 +98,21 @@ class ACSTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
 
     @staticmethod
     def get_formatted_principal(principal_name, host_name, realm):
+        # type: (str, Optional[str], str) -> str
         if host_name:
             return "{0}/{1}@{2}".format(principal_name, host_name, realm)
         return "{0}@{1}".format(principal_name, realm)
 
     @staticmethod
-    def get_security_token_service_url(realm):
-        return "https://accounts.accesscontrol.windows.net/{0}/tokens/OAuth/2".format(
-            realm
-        )
+    def get_security_token_service_url(realm, environment):
+        if environment == "GCCH":
+            return "https://login.microsoftonline.us/{0}/tokens/OAuth/2".format(
+                realm
+            )
+        else:
+            return "https://accounts.accesscontrol.windows.net/{0}/tokens/OAuth/2".format(
+                realm
+            )
 
     def _get_authorization_header(self):
         return "Bearer {0}".format(self._cached_token.accessToken)

office365/runtime/auth/providers/saml_token_provider.py

@@ -40,7 +40,7 @@ def is_valid_auth_cookies(values):
 
 
 class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
-    def __init__(self, url, username, password, browser_mode):
+    def __init__(self, url, username, password, browser_mode, environment='commercial'):
         """
         SAML Security Token Service provider (claims-based authentication)
 
@@ -48,11 +48,14 @@ class SamlTokenProvider(AuthenticationProvider, office365.logger.LoggerContext):
         :param str username: Typically a UPN in the form of an email address
         :param str password: The password
         :param bool browser_mode:
+        :param str environment: The Office 365 Cloud Environment endpoint used for authentication.
+        By default, this will be set to commercial ('commercial', 'GCCH')
         """
         # Security Token Service info
-        self._sts_profile = STSProfile(resolve_base_url(url))
+        self._sts_profile = STSProfile(resolve_base_url(url), environment)
         # Obtain authentication cookies, using the browser mode
         self._browser_mode = browser_mode
+        self._environment = environment
         # Last occurred error
         self.error = ""
         self._username = username

office365/runtime/auth/sts_profile.py

@@ -4,13 +4,16 @@ from office365.runtime.compat import timezone, urlparse
 
 
 class STSProfile(object):
-    def __init__(self, authority_url):
+    def __init__(self, authority_url, environment):
         """
 
         :type authority_url: str
         """
         self.authorityUrl = authority_url
-        self.serviceUrl = "https://login.microsoftonline.com"
+        if environment == "GCCH":
+            self.serviceUrl = "https://login.microsoftonline.us"
+        else:
+            self.serviceUrl = "https://login.microsoftonline.com"
         self.securityTokenServicePath = "extSTS.srf"
         self.userRealmServicePath = "GetUserRealm.srf"
         self.tokenIssuer = "urn:federation:MicrosoftOnline"

office365/runtime/client_object.py

@@ -90,7 +90,6 @@ class ClientObject(Generic[T]):
     def is_property_available(self, name):
         # type: (str) -> bool
         """Returns a Boolean value that indicates whether the specified property has been retrieved or set.
-
         :param str name: A property name
         """
         if name in self.properties:
@@ -116,7 +115,7 @@ class ClientObject(Generic[T]):
 
     def remove_from_parent_collection(self):
         if self._parent_collection is None:
-            return
+            return self
         self._parent_collection.remove_child(self)
         return self
 
@@ -174,19 +173,12 @@ class ClientObject(Generic[T]):
 
     def ensure_property(self, name, action, *args, **kwargs):
         # type: (str, Callable[[], None], Any, Any) -> Self
-        """
-        Ensures if property is loaded
-
-        :type action: () -> None
-        :type name: str
-        """
+        """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
-        """
-        Ensure if list of properties are retrieved from the server
-        """
+        """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)