typings enhancements & examples update

examples/sharepoint/files/get_checked_out.py

@@ -0,0 +1,19 @@
+"""
+Retrieves collection of checked-out files in a document library
+"""
+import sys
+
+from office365.sharepoint.client_context import ClientContext
+from tests import test_client_credentials, test_site_url
+
+ctx = ClientContext(test_site_url).with_credentials(test_client_credentials)
+doc_lib = ctx.web.default_document_library()
+
+files = doc_lib.items.top(1).get().execute_query()
+if len(files) < 1:
+    sys.exit("No files were found")
+
+
+items = doc_lib.get_checked_out_files().execute_query()
+if len(items) == 0:
+    sys.exit("No files were checked out")

generator/import_metadata.py

@@ -21,13 +21,13 @@ def export_to_file(path, content):
     "--endpoint",
     dest="endpoint",
     help="Import metadata endpoint",
-    default="microsoftgraph",
+    default="sharepoint",
 )
 parser.add_argument(
     "-p",
     "--path",
     dest="path",
-    default="./metadata/MicrosoftGraph.xml",
+    default="./metadata/SharePoint.xml",
     help="Import metadata endpoint",
 )
 

office365/directory/extensions/extended_property.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.entity import Entity
 from office365.runtime.types.collections import StringCollection
 
@@ -7,10 +9,8 @@ class SingleValueLegacyExtendedProperty(Entity):
 
     @property
     def value(self):
-        """
-        A property value.
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """A property value."""
         return self.properties.get("value", None)
 
 

office365/directory/identities/providers/base.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.entity import Entity
 
 
@@ -7,11 +9,11 @@ class IdentityProviderBase(Entity):
     an Azure AD B2C tenant.
     """
 
+    def __str__(self):
+        return self.display_name or self.entity_type_name
+
     @property
     def display_name(self):
-        """
-        The display name for the identity provider.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The display name for the identity provider."""
         return self.properties.get("displayName", None)

office365/directory/identities/providers/social_identity.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.identities.providers.base import IdentityProviderBase
 
 
@@ -9,27 +11,27 @@ class SocialIdentityProvider(IdentityProviderBase):
 
     @property
     def client_id(self):
+        # type: () -> Optional[str]
         """
         The client identifier for the application obtained when registering the application with the identity provider.
-        :rtype: str or None
         """
         return self.properties.get("clientId", None)
 
     @property
     def client_secret(self):
+        # type: () -> Optional[str]
         """
         The client secret for the application that is obtained when the application is registered
         with the identity provider. This is write-only. A read operation returns ****.
-        :rtype: str or None
         """
         return self.properties.get("clientSecret", None)
 
     @property
     def identity_provider_type(self):
+        # type: () -> Optional[str]
         """
         For a B2B scenario, possible values: Google, Facebook.
         For a B2C scenario, possible values: Microsoft, Google, Amazon, LinkedIn, Facebook, GitHub, Twitter, Weibo,
         QQ, WeChat.
-        :rtype: str or None
         """
         return self.properties.get("identityProviderType", None)

office365/runtime/client_runtime_context.py

@@ -1,6 +1,6 @@
 import abc
 from time import sleep
-from typing import TYPE_CHECKING, Any, AnyStr, Callable, List, Optional
+from typing import TYPE_CHECKING, Any, AnyStr, Callable, List
 
 import requests
 from typing_extensions import Self

office365/sharepoint/client_context.py

@@ -81,7 +81,7 @@ def with_client_certificate(
         thumbprint,
         cert_path=None,
         private_key=None,
-        scopes=None
+        scopes=None,
     ):
         # type: (str, str, str, Optional[str], Optional[str], Optional[List[str]]) -> Self
         """
@@ -136,7 +136,12 @@ def with_access_token(self, token_func):
         return self
 
     def with_user_credentials(
-        self, username, password, allow_ntlm=False, browser_mode=False, environment='commercial'
+        self,
+        username,
+        password,
+        allow_ntlm=False,
+        browser_mode=False,
+        environment="commercial",
     ):
         # type: (str, str, bool, bool, Optional[str]) -> Self
         """
@@ -152,11 +157,13 @@ def with_user_credentials(
             UserCredential(username, password),
             allow_ntlm=allow_ntlm,
             browser_mode=browser_mode,
-            environment=environment
+            environment=environment,
         )
         return self
 
-    def with_client_credentials(self, client_id, client_secret, environment='commercial'):
+    def with_client_credentials(
+        self, client_id, client_secret, environment="commercial"
+    ):
         # type: (str, str, Optional[str]) -> Self
         """
         Initializes a client to acquire a token via client credentials (SharePoint App-Only)
@@ -170,20 +177,21 @@ def with_client_credentials(self, client_id, client_secret, environment='commerc
             defaults to 'commercial'.
         """
         self.authentication_context.with_credentials(
-            ClientCredential(client_id, client_secret),
-            environment=environment
+            ClientCredential(client_id, client_secret), environment=environment
         )
         return self
 
-    def with_credentials(self, credentials, environment='commercial'):
+    def with_credentials(self, credentials, environment="commercial"):
         # type: (UserCredential|ClientCredential, Optional[str]) -> Self
         """
         Initializes a client to acquire a token via user or client credentials
         :type credentials: UserCredential or ClientCredential
         :param str environment: The Office 365 Cloud Environment endpoint used for authentication
             defaults to 'commercial'.
         """
-        self.authentication_context.with_credentials(credentials, environment=environment)
+        self.authentication_context.with_credentials(
+            credentials, environment=environment
+        )
         return self
 
     def execute_batch(self, items_per_batch=100, success_callback=None):
@@ -204,9 +212,7 @@ def execute_batch(self, items_per_batch=100, success_callback=None):
         return self
 
     def pending_request(self):
-        """
-        Provides access to underlying request instance
-        """
+        """Provides access to underlying request instance"""
         if self._pending_request is None:
             self._pending_request = ODataRequest(JsonLightFormat())
             self._pending_request.beforeExecute += self._authenticate_request
@@ -220,9 +226,7 @@ def _ensure_form_digest(self, request):
         request.set_header("X-RequestDigest", self._ctx_web_info.FormDigestValue)
 
     def _get_context_web_information(self):
-        """
-        Returns an ContextWebInformation object that specifies metadata about the site
-        """
+        """Returns an ContextWebInformation object that specifies metadata about the site"""
         client = ODataRequest(JsonLightFormat())
         client.beforeExecute += self._authenticate_request
         for e in self.pending_request().beforeExecute:
@@ -278,9 +282,7 @@ def _authenticate_request(self, request):
 
     def _build_modification_query(self, request):
         # type: (RequestOptions) -> None
-        """
-        Constructs SharePoint specific modification OData request
-        """
+        """Constructs SharePoint specific modification OData request"""
         if request.method == HttpMethod.Post:
             self._ensure_form_digest(request)
         # set custom SharePoint control headers
@@ -366,9 +368,7 @@ def _after_site_created(result):
 
     @property
     def context_info(self):
-        """
-        Returns an ContextWebInformation object that specifies metadata about the site
-        """
+        """Returns an ContextWebInformation object that specifies metadata about the site"""
         if self._ctx_web_info is None:
             self._ctx_web_info = ContextWebInformation()
         return self._ctx_web_info

office365/sharepoint/files/checked_out_file.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.runtime.paths.v3.entity import EntityPath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
@@ -16,9 +18,8 @@ def takeover_checkout(self):
 
     @property
     def checked_out_by_id(self):
-        """Returns the user ID of the account used to check out the file.
-        :rtype: int or None
-        """
+        # type: () -> Optional[int]
+        """Returns the user ID of the account used to check out the file."""
         return self.properties.get("CheckedOutById", None)
 
     @property