examples refactorings and type hints enhancements for ClientValue, Cl…

…ientResult and EventHandler

examples/sharepoint/folders/download.py

@@ -1,30 +1,28 @@
 """
-Demonstrates how to download folders content
+Demonstrates how to enumerate folder files and download file's content
 """
 import os
 import tempfile
 
 from office365.sharepoint.client_context import ClientContext
 from office365.sharepoint.files.file import File
+from office365.sharepoint.folders.folder import Folder
 from tests import test_client_credentials, test_team_site_url
 
 
 def print_progress(file):
+    # type: (File) -> None
     print("File {0} has been  downloaded".format(file.serverRelativeUrl))
 
 
 def download_files(source_folder, download_path):
-    """
-    Demonstrates how to enumerate folder files and download file's content
-    :type source_folder: Folder
-    :type download_path: str
-    """
+    # type: (Folder, str) -> None
 
     # 1. retrieve files collection (metadata) from library root folder
     files = source_folder.files.get().execute_query()
 
     # 2. start download process (per file)
-    for file in files:  # type: File
+    for file in files:
         print("Downloading file: {0} ...".format(file.properties["ServerRelativeUrl"]))
         download_file_name = os.path.join(download_path, file.name)
         with open(download_file_name, "wb") as local_file:

examples/sharepoint/folders/get_folder_files.py

@@ -1,10 +1,12 @@
+"""
+Prints file names in a folder
+"""
 from office365.sharepoint.client_context import ClientContext
-from office365.sharepoint.files.file import File
 from tests import test_client_credentials, test_team_site_url
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
 root_folder = ctx.web.default_document_library().root_folder
 ctx.load(root_folder, ["Files"])
 ctx.execute_query()
-for file in root_folder.files:  # type: File
+for file in root_folder.files:
     print(file.name)

examples/sharepoint/folders/list_folders.py

@@ -17,9 +17,7 @@ def enum_folder(parent_folder, action):
 
 
 def print_folder_stat(folder):
-    """
-    :type folder: Folder
-    """
+    # type: (Folder) -> None
     print(folder.serverRelativeUrl)
     print(folder.time_created)
 

examples/sharepoint/search/search_simple.py

@@ -9,5 +9,5 @@
 
 ctx = ClientContext(test_site_url).with_credentials(test_user_credentials)
 result = ctx.search.query("IsDocument:1", row_limit=10).execute_query()
-for i, row in enumerate(result.value.PrimaryQueryResult.RelevantResults.Table.Rows):
-    print("{0}: {1}".format(i + 1, row.Cells["Path"]))
+for row in result.value.PrimaryQueryResult.RelevantResults.Table.Rows:
+    print("{0}".format(row.Cells["Path"]))

examples/sharepoint/sharing/share_file_org.py

@@ -1,5 +1,3 @@
-import json
-
 from examples.sharepoint import upload_sample_file
 from office365.sharepoint.client_context import ClientContext
 from office365.sharepoint.sharing.links.kind import SharingLinkKind
@@ -8,4 +6,4 @@
 ctx = ClientContext(test_team_site_url).with_credentials(test_user_credentials)
 remote_file = upload_sample_file(ctx, "../../data/Financial Sample.xlsx")
 result = remote_file.share_link(SharingLinkKind.OrganizationView).execute_query()
-print(json.dumps(result.value.to_json(), indent=4))
+print("Shared link url: {0}".format(result.value.sharingLinkInfo))

examples/sharepoint/sharing/share_file_with_password.py

@@ -1,5 +1,5 @@
 """
-
+Share a file with a password
 """
 import json
 
@@ -14,5 +14,6 @@
 result = target_file.share_link(
     SharingLinkKind.Flexible, role=RoleType.Editor, password="password"
 ).execute_query()
-print(json.dumps(result.value.to_json(), indent=4))
-# print("Shared link url: {0}".format(result.value.sharingLinkInfo))
+
+# print(json.dumps(result.value.to_json(), indent=4))
+print("Shared link url: {0}".format(result.value.sharingLinkInfo))

examples/sharepoint/tenant/check_licenses.py

@@ -9,4 +9,4 @@
     test_admin_credentials
 )
 result = admin_client.tenant.check_tenant_intune_license().execute_query()
-print(result.value)
+print("Intune license: {0}".format("Yes" if result.value else "No"))

office365/runtime/client_value.py

@@ -1,5 +1,11 @@
+from typing import Any, Iterator, Tuple, TypeVar
+
+from typing_extensions import Self
+
 from office365.runtime.odata.v3.json_light_format import JsonLightFormat
 
+T = TypeVar("T", int, float, str, bool, "ClientValue")
+
 
 class ClientValue(object):
     """Represent complex type.
@@ -8,6 +14,7 @@ class ClientValue(object):
     """
 
     def set_property(self, k, v, persist_changes=True):
+        # type: (str, Any, bool) -> Self
         prop_type = getattr(self, k, None)
         if isinstance(prop_type, ClientValue) and v is not None:
             if isinstance(v, list):
@@ -26,9 +33,11 @@ def set_property(self, k, v, persist_changes=True):
         return self
 
     def get_property(self, k):
+        # type: (str) -> T
         return getattr(self, k)
 
     def __iter__(self):
+        # type: () -> Iterator[Tuple[str, T]]
         for n, v in vars(self).items():
             yield n, v
 

office365/runtime/client_value_collection.py

@@ -1,5 +1,5 @@
 import uuid
-from typing import Dict, Generic, Iterator, List, Optional, TypeVar
+from typing import Any, Dict, Generic, Iterator, List, Optional, TypeVar
 
 from typing_extensions import Self
 
@@ -63,7 +63,7 @@ def to_json(self, json_format=None):
         return json
 
     def create_typed_value(self, initial_value=None):
-        # type: (Optional[T]) -> T
+        # type: (Optional[Any]) -> T
         if initial_value is None:
             return uuid.uuid4() if self._item_type == uuid.UUID else self._item_type()
         elif self._item_type == uuid.UUID:
@@ -76,7 +76,7 @@ def create_typed_value(self, initial_value=None):
             return initial_value
 
     def set_property(self, index, value, persist_changes=False):
-        # type: (str | int, T, bool) -> Self
+        # type: (str | int, Any, bool) -> Self
         client_value = self.create_typed_value(value)
         self.add(client_value)
         return self

office365/runtime/types/event_handler.py

@@ -1,44 +1,49 @@
 import types
-from typing import Callable
+from typing import Callable, Iterator, TypeVar
 
-from typing_extensions import Self
+from typing_extensions import ParamSpec, Self
+
+P = ParamSpec("P")
+F = TypeVar("F", bound=Callable[..., None])
 
 
 class EventHandler:
     def __init__(self, once=False):
         # type: (bool) -> None
-        self._listeners = []
+        self._listeners = []  # type: list[F]
         self._once = once
 
     def __contains__(self, listener):
-        # type: (Callable[..., None]) -> bool
+        # type: (F) -> bool
         return listener in self._listeners
 
     def __iter__(self):
+        # type: () -> Iterator[F]
         return iter(self._listeners)
 
     def __iadd__(self, listener):
-        # type: (Callable[..., None]) -> Self
+        # type: (F) -> Self
         self._listeners.append(listener)
         return self
 
     def __isub__(self, listener):
-        # type: (Callable[..., None]) -> Self
+        # type: (F) -> Self
         self._listeners.remove(listener)
         return self
 
     def __len__(self):
         return len(self._listeners)
 
     def notify(self, *args, **kwargs):
+        # type: (P.args, P.kwargs) -> None
         for listener in self._listeners:
             if self._once:
                 self._listeners.remove(listener)
             listener(*args, **kwargs)
 
     @staticmethod
-    def is_builtin(listener):
-        # type: (Callable[..., None]) -> bool
+    def is_system(listener):
+        # type: (F) -> bool
         from office365.runtime.client_request import ClientRequest
         from office365.runtime.client_runtime_context import ClientRuntimeContext
 

office365/sharepoint/client_context.py

@@ -204,7 +204,7 @@ def _get_context_web_information(self):
         client = ODataRequest(JsonLightFormat())
         client.beforeExecute += self._authenticate_request
         for e in self.pending_request().beforeExecute:
-            if not EventHandler.is_builtin(e):
+            if not EventHandler.is_system(e):
                 client.beforeExecute += e
         request = RequestOptions("{0}/contextInfo".format(self.service_root_url()))
         request.method = HttpMethod.Post

office365/sharepoint/files/collection.py

@@ -11,7 +11,7 @@
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 
 
-class FileCollection(EntityCollection):
+class FileCollection(EntityCollection[File]):
     """Represents a collection of File resources."""
 
     def __init__(self, context, resource_path=None, parent=None):

office365/sharepoint/folders/collection.py

@@ -6,7 +6,7 @@
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 
 
-class FolderCollection(EntityCollection):
+class FolderCollection(EntityCollection[Folder]):
     """Represents a collection of Folder resources."""
 
     def __init__(self, context, resource_path=None, parent=None):

office365/sharepoint/listitems/listitem.py

@@ -4,12 +4,10 @@
 from office365.runtime.client_value_collection import ClientValueCollection
 from office365.runtime.paths.key import KeyPath
 from office365.runtime.paths.resource_path import ResourcePath
-from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.sharepoint.changes.collection import ChangeCollection
 from office365.sharepoint.changes.query import ChangeQuery
 from office365.sharepoint.comments.collection import CommentCollection
-from office365.sharepoint.entity_collection import EntityCollection
 from office365.sharepoint.fields.image_value import ImageFieldValue
 from office365.sharepoint.fields.lookup_value import FieldLookupValue
 from office365.sharepoint.fields.multi_lookup_value import FieldMultiLookupValue
@@ -65,7 +63,9 @@ def share_link(self, link_kind, expiration=None, role=None, password=None):
         :param str password: Optional password value to apply to the tokenized sharing link,
             if it can support password protection.
         """
-        return_type = ClientResult(self.context, ShareLinkResponse())
+        return_type = ClientResult(
+            self.context, ShareLinkResponse()
+        )  # type: ClientResult[ShareLinkResponse]
         request = ShareLinkRequest(
             settings=ShareLinkSettings(
                 link_kind=link_kind, expiration=expiration, role=role, password=password

office365/sharepoint/sharing/links/share_response.py

@@ -8,6 +8,9 @@ class ShareLinkResponse(ClientValue):
     """
 
     def __init__(self, sharing_link_info=SharingLinkInfo()):
+        """
+        :param SharingLinkInfo sharing_link_info:
+        """
         self.sharingLinkInfo = sharing_link_info
 
     @property

office365/sharepoint/tenant/administration/tenant.py

@@ -269,7 +269,7 @@ def check_tenant_intune_license(self):
         """
         Checks whether a tenant has the Intune license.
         """
-        return_type = ClientResult(self.context, bool())
+        return_type = ClientResult(self.context)  # type: ClientResult[bool]
         qry = ServiceOperationQuery(
             self, "CheckTenantIntuneLicense", None, None, None, return_type
         )