typings enhancements & examples update

examples/sharepoint/files/download_large.py

@@ -11,7 +11,7 @@ def print_download_progress(offset):
 
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
-file_url = "Shared Documents/big_buck_bunny.mp4"
+file_url = "Shared Documents/archive/big_buck_bunny.mp4"
 source_file = ctx.web.get_file_by_server_relative_path(file_url)
 local_file_name = os.path.join(tempfile.mkdtemp(), os.path.basename(file_url))
 with open(local_file_name, "wb") as local_file:

office365/booking/business/business.py

@@ -57,9 +57,8 @@ def address(self):
 
     @property
     def business_hours(self):
-        """
-        The hours of operation for the business.
-        """
+        # type: () -> ClientValueCollection[BookingWorkHours]
+        """The hours of operation for the business."""
         return self.properties.get(
             "businessHours", ClientValueCollection(BookingWorkHours)
         )
@@ -74,6 +73,7 @@ def display_name(self):
 
     @property
     def appointments(self):
+        # type: () -> EntityCollection[BookingAppointment]
         """All the appointments of this business. Read-only. Nullable."""
         return self.properties.get(
             "appointments",
@@ -86,6 +86,7 @@ def appointments(self):
 
     @property
     def calendar_view(self):
+        # type: () -> EntityCollection[BookingAppointment]
         """The set of appointments of this business in a specified date range. Read-only. Nullable."""
         return self.properties.get(
             "calendarView",
@@ -98,6 +99,7 @@ def calendar_view(self):
 
     @property
     def customers(self):
+        # type: () -> EntityCollection[BookingCustomerBase]
         """All the customers of this business. Read-only. Nullable."""
         return self.properties.get(
             "customers",

office365/onenote/notebooks/collection.py

@@ -18,7 +18,6 @@ def add(self, display_name):
 
         :param str display_name: Name for the notebook. Notebook names must be unique. The name cannot contain more
             than 128 characters or contain the following characters: ?*/:<>|'"
-        :rtype: Notebook
         """
         return super(NotebookCollection, self).add(displayName=display_name)
 

office365/outlook/calendar/events/event.py

@@ -1,6 +1,5 @@
 from typing import Optional
 
-from office365.delta_collection import DeltaCollection
 from office365.directory.extensions.extended_property import (
     MultiValueLegacyExtendedProperty,
     SingleValueLegacyExtendedProperty,
@@ -9,7 +8,6 @@
 from office365.entity_collection import EntityCollection
 from office365.outlook.calendar.attendees.attendee import Attendee
 from office365.outlook.calendar.dateTimeTimeZone import DateTimeTimeZone
-from office365.outlook.calendar.email_address import EmailAddress
 from office365.outlook.item import OutlookItem
 from office365.outlook.mail.attachments.collection import AttachmentCollection
 from office365.outlook.mail.item_body import ItemBody
@@ -74,45 +72,41 @@ def decline(self, proposed_new_time=None, send_response=True, comment=None):
         return self
 
     def dismiss_reminder(self):
-        """
-        Dismiss a reminder that has been triggered for an event in a user calendar.
-        """
+        """Dismiss a reminder that has been triggered for an event in a user calendar."""
         qry = ServiceOperationQuery(self, "dismissReminder")
         self.context.add_query(qry)
         return self
 
     @property
     def allow_new_time_proposals(self):
+        # type: () -> Optional[bool]
         """
         true if the meeting organizer allows invitees to propose a new time when responding; otherwise, false.
         Optional. Default is true.
-        :rtype: bool or None
         """
         return self.properties.get("allowNewTimeProposals", None)
 
     @property
     def has_attachments(self):
-        """
-        Set to true if the event has attachments.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Set to true if the event has attachments."""
         return self.properties.get("hasAttachments", None)
 
     @property
     def hide_attendees(self):
+        # type: () -> Optional[bool]
         """
         When set to true, each attendee only sees themselves in the meeting request and meeting Tracking list.
         Default is false.
-        :rtype: bool or None
         """
         return self.properties.get("hideAttendees", None)
 
     @property
     def ical_uid(self):
+        # type: () -> Optional[str]
         """
         A unique identifier for an event across calendars. This ID is different for each occurrence in a recurring
-        series. Read-only.
-        :rtype: str or None
+        series.
         """
         return self.properties.get("iCalUId", None)
 
@@ -167,6 +161,7 @@ def end(self, value):
 
     @property
     def single_value_extended_properties(self):
+        # type: () -> EntityCollection[SingleValueLegacyExtendedProperty]
         """The collection of single-value extended properties defined for the event."""
         return self.properties.get(
             "singleValueExtendedProperties",
@@ -179,6 +174,7 @@ def single_value_extended_properties(self):
 
     @property
     def multi_value_extended_properties(self):
+        # type: () -> EntityCollection[MultiValueLegacyExtendedProperty]
         """The collection of multi-value extended properties defined for the event."""
         return self.properties.get(
             "multiValueExtendedProperties",
@@ -229,22 +225,19 @@ def subject(self, value):
 
     @property
     def location(self):
-        """
-        The location of the event.
-        """
+        """The location of the event."""
         return self.properties.get("location", Location())
 
     @property
     def web_link(self):
+        # type: () -> Optional[str]
         """
         The URL to open the event in Outlook on the web.
 
         Outlook on the web opens the event in the browser if you are signed in to your mailbox. Otherwise, Outlook
         on the web prompts you to sign in.
 
         This URL cannot be accessed from within an iFrame.
-
-        :rtype: str or None
         """
         return self.properties.get("webLink", None)
 
@@ -275,6 +268,7 @@ def attachments(self):
 
     @property
     def extensions(self):
+        # type: () -> EntityCollection[Extension]
         """The collection of open extensions defined for the event. Nullable."""
         return self.properties.get(
             "extensions",

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 @@ def plans(self):
 
     @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/runtime/client_object.py

@@ -172,12 +172,12 @@ def set_property(self, name, value, persist_changes=True):
         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)

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
+from typing import TYPE_CHECKING, Any, AnyStr, Callable, List, Optional
 
 import requests
 from typing_extensions import Self
@@ -121,7 +121,7 @@ def _prepare_request(request):
         return self
 
     def before_execute(self, action, once=True, *args, **kwargs):
-        # type: (Callable[[RequestOptions, Any, Any], None], bool, Any, Any) -> Self
+        # type: (Callable[[RequestOptions, ...], None], bool, Optional[Any], Optional[Any]) -> Self
         """
         Attach an event handler which is triggered before request is submitted to server
         :param (office365.runtime.http.request_options.RequestOptions, any) -> None action:

office365/sharepoint/files/file.py

@@ -665,8 +665,6 @@ def _construct_request(request):
                 request.stream = True
                 request.method = HttpMethod.Get
 
-            self.context.before_execute(_construct_request)
-
             def _process_response(response):
                 # type: (requests.Response) -> None
                 response.raise_for_status()
@@ -677,8 +675,9 @@ def _process_response(response):
                         chunk_downloaded(bytes_read)
                     file_object.write(chunk)
 
-            self.context.after_execute(_process_response)
-            self.context.add_query(qry)
+            self.context.add_query(qry).before_execute(
+                _construct_request
+            ).after_execute(_process_response)
 
         if use_path:
             self.ensure_property("ServerRelativePath", _download_as_stream)

office365/teams/members/aad_user_conversation.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.teams.members.conversation import ConversationMember
 
@@ -7,10 +9,8 @@ class AadUserConversationMember(ConversationMember):
 
     @property
     def user_id(self):
-        """
-        The guid of the user.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The guid of the user."""
         return self.properties.get("userId", None)
 
     @property