typings & worksheet range (#745) enhancements

Author: vgrem

examples/onedrive/excel/read_worksheet.py renamed to examples/onedrive/excel/list_worksheets.py

@@ -0,0 +1,20 @@
+"""
+Gets the range object specified by the address or name.
+
+https://learn.microsoft.com/en-us/graph/api/worksheet-range?view=graph-rest-1.0
+"""
+
+import sys
+
+from office365.graph_client import GraphClient
+from tests.graph_case import acquire_token_by_username_password
+
+client = GraphClient(acquire_token_by_username_password)
+drive_item = client.me.drive.root.get_by_path("Financial Sample.xlsx")
+worksheets = drive_item.workbook.worksheets.get().execute_query()
+if len(worksheets) == 0:
+    sys.exit("No worksheets found")
+
+# worksheet_range = worksheets["Sheet1"].range().execute_query()
+worksheet_range = worksheets["Sheet1"].range(address="A2:P10").execute_query()
+print(worksheet_range)

examples/onedrive/excel/read_range.py

@@ -0,0 +1,18 @@
+"""
+Demonstrates how to apply filtering to list collection
+
+In the provided example only the user defined lists are getting returned
+"""
+
+from office365.sharepoint.client_context import ClientContext
+from tests import test_client_credentials, test_team_site_url
+
+ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
+result = (
+    ctx.web.lists.get_by_title("Site Pages")
+    .items.filter("ID eq 135 AND RequestType eq 'Standard'")
+    .get()
+    .execute_query()
+)
+for item in result:
+    print(item.properties)

examples/sharepoint/listitems/filter.py

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

generator/import_metadata.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.identities.userflows.language_configuration import (
     UserFlowLanguageConfiguration,
 )
@@ -20,6 +22,7 @@ class B2XIdentityUserFlow(IdentityUserFlow):
 
     @property
     def languages(self):
+        # type: () -> EntityCollection[UserFlowLanguageConfiguration]
         """The languages supported for customization within the user flow. Language customization is enabled by default
         in self-service sign-up user flow. You cannot create custom languages in self-service sign-up user flows.
         """
@@ -34,9 +37,8 @@ def languages(self):
 
     @property
     def user_attribute_assignments(self):
-        """
-        The user attribute assignments included in the user flow.
-        """
+        # type: () -> IdentityUserFlowAttributeAssignmentCollection
+        """The user attribute assignments included in the user flow."""
         return self.properties.get(
             "userAttributeAssignments",
             IdentityUserFlowAttributeAssignmentCollection(
@@ -47,11 +49,10 @@ def user_attribute_assignments(self):
 
     @property
     def user_flow_type(self):
+        # type: () -> Optional[str]
         """
         The type of user flow. For self-service sign-up user flows,
         the value can only be signUpOrSignIn and cannot be modified after creation.
-
-        :rtype: str or None
         """
         return self.properties.get("userFlowType", None)
 

generator/metadata/MicrosoftGraph.xml

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.identities.userflows.language_page import UserFlowLanguagePage
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
@@ -11,19 +13,19 @@ class UserFlowLanguageConfiguration(Entity):
     User flows for Azure Active Directory support defining the language and strings shown to users
     as they go through the journeys you configure with your user flows."""
 
+    def __str__(self):
+        return self.display_name or self.entity_type_name
+
     @property
     def display_name(self):
-        """
-        The language name to display.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The language name to display."""
         return self.properties.get("displayName", None)
 
     @property
     def default_pages(self):
-        """
-        Collection of pages with the default content to display in a user flow for a specified language.
-        """
+        # type: () -> EntityCollection[UserFlowLanguagePage]
+        """Collection of pages with the default content to display in a user flow for a specified language."""
         return self.properties.get(
             "defaultPages",
             EntityCollection(
@@ -35,6 +37,7 @@ def default_pages(self):
 
     @property
     def overrides_pages(self):
+        # type: () -> EntityCollection[UserFlowLanguagePage]
         """Collection of pages with the default content to display in a user flow for a specified language."""
         return self.properties.get(
             "overridesPages",

office365/directory/identities/userflows/b2x/user_flow.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.directory.licenses.service_plan_info import ServicePlanInfo
 from office365.entity import Entity
 from office365.runtime.client_value_collection import ClientValueCollection
@@ -17,18 +19,17 @@ def service_plans(self):
 
     @property
     def sku_id(self):
+        # type: () -> Optional[str]
         """
         Unique identifier (GUID) for the service SKU. Equal to the skuId property on the related SubscribedSku object.
-        Read-only
-        :rtype: str or None
         """
         return self.properties.get("skuId", None)
 
     @property
     def sku_part_number(self):
+        # type: () -> Optional[str]
         """
         Unique SKU display name. Equal to the skuPartNumber on the related SubscribedSku object;
         for example: "AAD_Premium". Read-only
-        :rtype: str or None
         """
         return self.properties.get("skuPartNumber", None)

office365/directory/identities/userflows/language_configuration.py

@@ -4,12 +4,14 @@
 from office365.entity_collection import EntityCollection
 from office365.onedrive.workbooks.charts.chart import WorkbookChart
 from office365.onedrive.workbooks.names.named_item import WorkbookNamedItem
+from office365.onedrive.workbooks.ranges.range import WorkbookRange
 from office365.onedrive.workbooks.tables.collection import WorkbookTableCollection
 from office365.onedrive.workbooks.tables.pivot_table import WorkbookPivotTable
 from office365.onedrive.workbooks.worksheets.protection import (
     WorkbookWorksheetProtection,
 )
 from office365.runtime.paths.resource_path import ResourcePath
+from office365.runtime.queries.function import FunctionQuery
 
 
 class WorkbookWorksheet(Entity):
@@ -18,10 +20,22 @@ class WorkbookWorksheet(Entity):
     """
 
     def __repr__(self):
-        return self.name
+        return self.name or self.entity_type_name
 
     def __str__(self):
-        return self.name
+        return self.name or self.entity_type_name
+
+    def range(self, address=None):
+        """Gets the range object specified by the address or name."""
+        return_type = WorkbookRange(
+            self.context, ResourcePath("range", self.resource_path)
+        )
+        params = {"address": address}
+        qry = FunctionQuery(
+            self, "range", method_params=params, return_type=return_type
+        )
+        self.context.add_query(qry)
+        return return_type
 
     @property
     def charts(self):

office365/directory/licenses/details.py

@@ -112,26 +112,22 @@ def ical_uid(self):
 
     @property
     def importance(self):
-        """
-        The importance of the event. The possible values are: low, normal, high.
-        :rtype: str
-        """
+        # type: () -> Optional[str]
+        """The importance of the event. The possible values are: low, normal, high."""
         return self.properties.get("importance", None)
 
     @property
     def is_all_day(self):
+        # type: () -> Optional[bool]
         """
         Set to true if the event lasts all day. If true, regardless of whether it's a single-day or multi-day event,
         start and end time must be set to midnight and be in the same time zone.
-        :rtype: bool or None
         """
         return self.properties.get("isAllDay", None)
 
     @property
     def start(self):
-        """
-        The date, time, and time zone that the event starts. By default, the start time is in UTC.
-        """
+        """The date, time, and time zone that the event starts. By default, the start time is in UTC."""
         return self.properties.get("start", DateTimeTimeZone())
 
     @start.setter
@@ -145,9 +141,7 @@ def start(self, value):
 
     @property
     def end(self):
-        """
-        The date, time, and time zone that the event starts. By default, the start time is in UTC.
-        """
+        """The date, time, and time zone that the event starts. By default, the start time is in UTC."""
         return self.properties.get("end", DateTimeTimeZone())
 
     @end.setter
@@ -187,40 +181,30 @@ def multi_value_extended_properties(self):
 
     @property
     def body(self):
-        """
-        The body of the message associated with the event. It can be in HTML or text format.
-        """
+        """The body of the message associated with the event. It can be in HTML or text format."""
         return self.properties.get("body", ItemBody())
 
     @body.setter
     def body(self, value):
-        """
-        Sets The body of the message associated with the event. It can be in HTML or text format.
-        """
+        """Sets The body of the message associated with the event. It can be in HTML or text format."""
         self.set_property("body", ItemBody(value, "HTML"))
 
     @property
     def body_preview(self):
-        """
-        The preview of the message associated with the event. It is in text format.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The preview of the message associated with the event. It is in text format."""
         return self.properties.get("bodyPreview", None)
 
     @property
     def subject(self):
         # type: () -> Optional[str]
-        """
-        The text of the event's subject line.
-        """
+        """The text of the event's subject line."""
         return self.properties.get("subject", None)
 
     @subject.setter
     def subject(self, value):
-        """
-        Sets The text of the event's subject line.
-        :type: str or None
-        """
+        # type: (str) -> None
+        """Sets The text of the event's subject line."""
         self.set_property("subject", value)
 
     @property

office365/onedrive/workbooks/worksheets/worksheet.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.runtime.paths.resource_path import ResourcePath
 from office365.sharepoint.entity import Entity
 
@@ -14,26 +16,20 @@ class Alert(Entity):
 
     @property
     def alert_frequency(self):
-        """
-        Gets the time interval for sending the alert.
-        :rtype: int
-        """
+        # type: () -> Optional[int]
+        """Gets the time interval for sending the alert."""
         return self.properties.get("AlertFrequency", None)
 
     @property
     def alert_template_name(self):
-        """
-        Gets the string representing the alert template name.
-        :rtype: int
-        """
+        # type: () -> Optional[int]
+        """Gets the string representing the alert template name."""
         return self.properties.get("AlertTemplateName", None)
 
     @property
     def always_notify(self):
-        """
-        Gets a Boolean value that causes daily and weekly alerts to trigger, even if there is no matching event.
-        :rtype: bool
-        """
+        # type: () -> Optional[bool]
+        """Gets a Boolean value that causes daily and weekly alerts to trigger, even if there is no matching event."""
         return self.properties.get("AlwaysNotify", None)
 
     @property

office365/outlook/calendar/events/event.py

@@ -4,7 +4,7 @@
 from office365.sharepoint.features.feature import Feature
 
 
-class FeatureCollection(EntityCollection):
+class FeatureCollection(EntityCollection[Feature]):
     """Represents a collection of Feature resources."""
 
     def __init__(self, context, resource_path=None, parent=None):
@@ -31,9 +31,7 @@ def _create_query():
             return ServiceOperationQuery(self, "Add", None, payload, None, return_type)
 
         def _create_if_not_activated(f):
-            """
-            :type f: Feature
-            """
+            # type: (Feature) -> None
             if not f.properties:
                 self.context.add_query(_create_query())
 

office365/sharepoint/alerts/alert.py

@@ -6,6 +6,9 @@
 class WebTemplate(Entity):
     """Specifies a site definition or a site template that is used to instantiate a site."""
 
+    def __str__(self):
+        return self.title or self.entity_type_name
+
     def __repr__(self):
         return self.name
 
@@ -68,9 +71,8 @@ def lcid(self):
 
     @property
     def name(self):
-        """Gets a value that specifies the display name of the list template.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets a value that specifies the display name of the list template."""
         return self.properties.get("Name", None)
 
     @property

office365/sharepoint/features/collection.py

@@ -2185,9 +2185,8 @@ def url(self):
 
     @property
     def quick_launch_enabled(self):
-        """Gets a value that specifies whether the Quick Launch area is enabled on the site.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Gets a value that specifies whether the Quick Launch area is enabled on the site."""
         return self.properties.get("QuickLaunchEnabled", None)
 
     @property