type hints enhancements for ClientValueCollection (PEP 484) for Share…

…Point API

examples/outlook/events/delete.py

@@ -1,12 +1,11 @@
 """
-
+Deletes the event
 """
 
 from office365.graph_client import GraphClient
-from office365.outlook.calendar.events.event import Event
 from tests.graph_case import acquire_token_by_username_password
 
 client = GraphClient(acquire_token_by_username_password)
 event_id = "--event id goes here--"
-event_to_del = client.me.calendar.events[event_id]  # type: Event
+event_to_del = client.me.calendar.events[event_id]
 event_to_del.delete_object().execute_query()

examples/outlook/events/list.py

@@ -9,5 +9,5 @@
 
 client = GraphClient(acquire_token_by_username_password)
 events = client.me.calendar.events.get_all().select(["subject", "body"]).execute_query()
-for event in events:  # type: Event
+for event in events:
     print(event.subject)

examples/sharepoint/tenant/change_external_sharing.py

@@ -15,7 +15,6 @@
     test_client_id,
     test_team_site_url,
     test_tenant,
-    test_tenant_name,
 )
 
 cert_credentials = {

examples/sharepoint/tenant/get_all_sites.py

@@ -3,7 +3,6 @@
 """
 
 from office365.sharepoint.client_context import ClientContext
-from office365.sharepoint.tenant.administration.sites.properties import SiteProperties
 from tests import test_admin_credentials, test_admin_site_url
 
 admin_client = ClientContext(test_admin_site_url).with_credentials(
@@ -12,5 +11,7 @@
 result = admin_client.tenant.get_site_properties_from_sharepoint_by_filters(
     ""
 ).execute_query()
-for i, siteProps in enumerate(result):  # type: int, SiteProperties
+i = 0
+for siteProps in result:
     print("({0} of {1}) {2}".format(i, len(result), siteProps.url))
+    i += 1

office365/base_item.py

@@ -13,11 +13,13 @@ class BaseItem(Entity):
 
     @property
     def etag(self):
+        # type: () -> Optional[str]
         """ETag for the item."""
         return self.properties.get("eTag", None)
 
     @property
     def created_by(self):
+        # type: () -> IdentitySet
         """Identity of the user, device, or application which created the item."""
         return self.properties.get("createdBy", IdentitySet())
 
@@ -70,16 +72,14 @@ def name(self):
     def name(self, value):
         """
         Sets the name of the item.
-
-        :type value: str
         """
         self.set_property("name", value)
 
     @property
     def description(self):
+        # type: () -> Optional[str]
         """
         Provides a user-visible description of the item.
-        :rtype: str or None
         """
         return self.properties.get("description", None)
 
@@ -89,9 +89,9 @@ def description(self, value):
 
     @property
     def web_url(self):
+        # type: () -> Optional[str]
         """
         URL that displays the resource in the browser
-        :rtype: str or None
         """
         return self.properties.get("webUrl", None)
 

office365/booking/business/business.py

@@ -1,3 +1,6 @@
+from datetime import datetime
+from typing import List, Optional
+
 from office365.booking.appointment import BookingAppointment
 from office365.booking.custom_question import BookingCustomQuestion
 from office365.booking.customers.base import BookingCustomerBase
@@ -22,6 +25,7 @@ class BookingBusiness(Entity):
     def get_staff_availability(
         self, staff_ids=None, start_datetime=None, end_datetime=None
     ):
+        # type: (List[str], datetime, datetime) -> ClientResult[ClientValueCollection[StaffAvailabilityItem]]
         """
         Get the availability information of staff members of a Microsoft Bookings calendar.
         :param list[str] staff_ids: The list of staff IDs
@@ -30,7 +34,7 @@ def get_staff_availability(
         """
         return_type = ClientResult(
             self.context, ClientValueCollection(StaffAvailabilityItem)
-        )  # type: ClientResult[ClientValueCollection[StaffAvailabilityItem]]
+        )
         payload = {
             "staffIds": staff_ids,
             "startDateTime": start_datetime,
@@ -61,10 +65,10 @@ def business_hours(self):
         )
 
     def display_name(self):
+        # type: () -> Optional[str]
         """
         The name of the business, which interfaces with customers. This name appears at the top of the business
-            scheduling page.
-        :rtype: str or None
+        scheduling page.
         """
         return self.properties.get("displayName", None)
 

office365/directory/applications/service_principal.py

@@ -0,0 +1,9 @@
+from office365.entity import Entity
+
+
+class ApplicationServicePrincipal(Entity):
+    """
+    When an instance of an application from the Azure AD application gallery is added, application and servicePrincipal
+     objects are created in the directory. The applicationServicePrincipal represents the concatenation of the
+     application and servicePrincipal object.
+    """

office365/directory/users/user.py

@@ -370,6 +370,7 @@ def delete_object(self, permanent_delete=False):
         return self
 
     def revoke_signin_sessions(self):
+        # type: () -> ClientResult[bool]
         """
         Invalidates all the refresh tokens issued to applications for a user
         (as well as session cookies in a user's browser), by resetting the signInSessionsValidFromDateTime user

office365/onedrive/columns/definition_collection.py

@@ -1,5 +1,8 @@
+from typing import Optional
+
 from office365.entity_collection import EntityCollection
 from office365.onedrive.columns.definition import ColumnDefinition
+from office365.onedrive.lists.list import List
 from office365.runtime.queries.create_entity import CreateEntityQuery
 
 
@@ -15,7 +18,6 @@ def add_number(self, name, minimum=None, maximum=None):
         :param str name: The API-facing name of the column as it appears in the fields on a listItem
         :param float minimum: The minimum permitted value.
         :param float maximum: The maximum permitted value.
-        :rtype: ColumnDefinition
         """
         from office365.onedrive.columns.number import NumberColumn
 
@@ -28,7 +30,6 @@ def add_text(self, name, max_length=None, text_type=None):
         :param str name: The API-facing name of the column as it appears in the fields on a listItem
         :param int or None max_length: The maximum number of characters for the value.
         :param str or None text_type: The type of text being stored
-        :rtype: ColumnDefinition
         """
         from office365.onedrive.columns.text import TextColumn
 
@@ -53,13 +54,13 @@ def add_hyperlink_or_picture(self, name, is_picture=None):
         )
 
     def add_lookup(self, name, lookup_list, column_name=None):
+        # type: (str, List|str, Optional[str]) -> ColumnDefinition
         """
         Creates a lookup column
 
         :param str name: The API-facing name of the column as it appears in the fields on a listItem
         :param office365.onedrive.lists.list.List or str lookup_list: Lookup source list or identifier
         :param str column_name: The name of the lookup source column.
-        :rtype: ColumnDefinition
         """
         from office365.onedrive.columns.lookup import LookupColumn
         from office365.onedrive.lists.list import List

office365/onedrive/lists/list.py

@@ -43,6 +43,7 @@ def drive(self):
 
     @property
     def columns(self):
+        # type: () -> ColumnDefinitionCollection
         """The collection of columns under this site."""
         return self.properties.setdefault(
             "columns",
@@ -53,6 +54,7 @@ def columns(self):
 
     @property
     def content_types(self):
+        # type: () -> ContentTypeCollection
         """The collection of content types under this site."""
         return self.properties.get(
             "contentTypes",
@@ -63,6 +65,7 @@ def content_types(self):
 
     @property
     def items(self):
+        # type: () -> EntityCollection[ListItem]
         """All items contained in the list."""
         return self.properties.get(
             "items",
@@ -73,6 +76,7 @@ def items(self):
 
     @property
     def operations(self):
+        # type: () -> EntityCollection[RichLongRunningOperation]
         """The collection of long-running operations on the list."""
         return self.properties.get(
             "operations",
@@ -85,6 +89,7 @@ def operations(self):
 
     @property
     def subscriptions(self):
+        # type: () -> EntityCollection[Subscription]
         """The set of subscriptions on the list."""
         return self.properties.get(
             "subscriptions",

office365/onedrive/workbooks/tables/columns/collection.py

@@ -4,7 +4,7 @@
 from office365.runtime.queries.function import FunctionQuery
 
 
-class WorkbookTableColumnCollection(EntityCollection):
+class WorkbookTableColumnCollection(EntityCollection[WorkbookTableColumn]):
     def __init__(self, context, resource_path=None):
         super(WorkbookTableColumnCollection, self).__init__(
             context, WorkbookTableColumn, resource_path

office365/outlook/calendar/calendar.py

@@ -170,6 +170,7 @@ def owner(self):
 
     @property
     def events(self):
+        # type: () -> EventCollection
         """The events in the calendar. Navigation property. Read-only."""
         return self.properties.get(
             "events",

office365/outlook/calendar/events/collection.py

@@ -1,3 +1,8 @@
+import datetime
+from typing import List
+
+from typing_extensions import Self
+
 from office365.delta_collection import DeltaCollection
 from office365.outlook.calendar.attendees.attendee import Attendee
 from office365.outlook.calendar.dateTimeTimeZone import DateTimeTimeZone
@@ -7,13 +12,14 @@
 from office365.runtime.client_value_collection import ClientValueCollection
 
 
-class EventCollection(DeltaCollection):
+class EventCollection(DeltaCollection[Event]):
     def __init__(self, context, resource_path=None):
         super(EventCollection, self).__init__(context, Event, resource_path)
 
     def add(
         self, subject=None, body=None, start=None, end=None, attendees=None, **kwargs
     ):
+        # type: (str, str|ItemBody, datetime.datetime, datetime.datetime, List[str], ...) -> Event
         """
         Create an event in the user's default calendar or specified calendar.
 
@@ -28,7 +34,6 @@ def add(
         :param datetime.datetime end: The date, time, and time zone that the event ends.
             By default, the end time is in UTC.
         :param list[str] attendees: The collection of attendees for the event.
-        :rtype: Event
         """
 
         if body is not None:

office365/outlook/calendar/events/event.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.delta_collection import DeltaCollection
 from office365.directory.extensions.extended_property import (
     MultiValueLegacyExtendedProperty,
@@ -211,9 +213,9 @@ def body_preview(self):
 
     @property
     def subject(self):
+        # type: () -> Optional[str]
         """
         The text of the event's subject line.
-        :rtype: str or None
         """
         return self.properties.get("subject", None)
 

office365/runtime/client_result.py

@@ -5,8 +5,7 @@
 
 if TYPE_CHECKING:
     from office365.runtime.client_runtime_context import ClientRuntimeContext
-
-from office365.runtime.client_value import ClientValue
+    from office365.runtime.client_value import ClientValue
 
 T = TypeVar("T")
 

office365/runtime/client_value_collection.py

@@ -1,9 +1,10 @@
 import uuid
-from typing import Any, Dict, Generic, Iterator, List, Optional, TypeVar
+from typing import Any, Dict, Generic, Iterator, List, Optional, Type, TypeVar
 
 from typing_extensions import Self
 
 from office365.runtime.client_value import ClientValue
+from office365.runtime.odata.json_format import ODataJsonFormat
 from office365.runtime.odata.type import ODataType
 from office365.runtime.odata.v3.json_light_format import JsonLightFormat
 
@@ -12,7 +13,7 @@
 
 class ClientValueCollection(ClientValue, Generic[T]):
     def __init__(self, item_type, initial_values=None):
-        # type: (T, Optional[List | Dict]) -> None
+        # type: (Type[T], Optional[List | Dict]) -> None
         super(ClientValueCollection, self).__init__()
         if initial_values is None:
             initial_values = []
@@ -42,9 +43,9 @@ def __str__(self):
         return ",".join(self._data)
 
     def to_json(self, json_format=None):
+        # type: (ODataJsonFormat) -> dict
         """
         Serializes a client value's collection
-        :type json_format: office365.runtime.odata.json_format.ODataJsonFormat or None
         """
         json = [v for v in self]
         for i, v in enumerate(json):
@@ -63,7 +64,7 @@ def to_json(self, json_format=None):
         return json
 
     def create_typed_value(self, initial_value=None):
-        # type: (Optional[Any]) -> T
+        # type: (Optional[T]) -> 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: