typings enhancements & examples update

examples/onedrive/columns/list_site.py

@@ -4,9 +4,11 @@
 https://learn.microsoft.com/en-us/graph/api/site-list-columns?view=graph-rest-1.0
 """
 from office365.graph_client import GraphClient
-from tests.graph_case import acquire_token_by_username_password
+from tests import test_client_id, test_password, test_tenant, test_username
 
-client = GraphClient(acquire_token_by_username_password)
+client = GraphClient.with_username_and_password(
+    test_tenant, test_client_id, test_username, test_password
+)
 columns = client.sites.root.columns.get().execute_query()
 for column in columns:
     print(column)

examples/outlook/messages/download.py

@@ -15,8 +15,7 @@
 messages = client.me.messages.select(["id", "subject"]).top(1).get().execute_query()
 with tempfile.TemporaryDirectory() as local_path:
     for message in messages:
-        with open(
-            os.path.join(local_path, message.subject + ".eml"), "wb"
-        ) as local_file:
-            message.download(local_file).execute_query()
-        print("Message downloaded into {0}".format(local_file.name))
+        with open(os.path.join(local_path, message.subject + ".eml"), "wb") as f:
+            message.download(f).execute_query()
+
+        print("Message downloaded into {0}".format(f.name))

examples/sharepoint/sharing/share_folder.py

@@ -1,3 +1,6 @@
+"""
+Demonstrates how to create and get a tokenized sharing link for a Folder
+"""
 from office365.sharepoint.client_context import ClientContext
 from office365.sharepoint.sharing.links.kind import SharingLinkKind
 from tests import test_team_site_url, test_user_credentials

office365/onedrive/workbooks/comments/comment.py

@@ -1,3 +1,5 @@
+from typing import AnyStr, Optional
+
 from office365.entity import Entity
 from office365.entity_collection import EntityCollection
 from office365.onedrive.workbooks.comments.reply import WorkbookCommentReply
@@ -9,20 +11,19 @@ class WorkbookComment(Entity):
 
     @property
     def content(self):
-        """The content of comment.
-        :rtype: str or None
-        """
+        # type: () -> Optional[AnyStr]
+        """The content of comment."""
         return self.properties.get("content", None)
 
     @property
     def content_type(self):
-        """Indicates the type for the comment.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Indicates the type for the comment."""
         return self.properties.get("contentType", None)
 
     @property
     def replies(self):
+        # type: () -> EntityCollection[WorkbookCommentReply]
         """"""
         return self.properties.get(
             "replies",

office365/outlook/mail/attachments/file.py

@@ -1,3 +1,5 @@
+from typing import AnyStr, Optional
+
 from office365.outlook.mail.attachments.attachment import Attachment
 
 
@@ -6,32 +8,23 @@ class FileAttachment(Attachment):
 
     @property
     def content_id(self):
-        """
-        The ID of the attachment in the Exchange store.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """The ID of the attachment in the Exchange store."""
         return self.properties.get("contentId", None)
 
     @property
     def content_location(self):
-        """
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """ """
         return self.properties.get("content_location", None)
 
     @property
     def content_bytes(self):
-        """
-        The base64-encoded contents of the file.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[AnyStr]
+        """The base64-encoded contents of the file."""
         return self.properties.get("contentBytes", None)
 
     @content_bytes.setter
     def content_bytes(self, value):
-        """
-        Sets the base64-encoded contents of the file.
-        """
+        """Sets the base64-encoded contents of the file."""
         self.set_property("contentBytes", value)

office365/runtime/odata/request.py

@@ -1,5 +1,5 @@
 import copy
-from typing import Any, Optional
+from typing import Any, Iterator, Optional, Tuple
 
 import requests
 
@@ -79,7 +79,7 @@ def map_json(self, json, return_type, json_format=None):
                 return_type.set_property(k, v, False)
 
     def _next_property(self, json, json_format):
-        # type: (Any, ODataJsonFormat) -> None
+        # type: (Any, ODataJsonFormat) -> Iterator[Tuple[str, Any]]
         if isinstance(json_format, JsonLightFormat):
             json = json.get(json_format.security, json)
             json = json.get(json_format.function, json)

office365/runtime/odata/v3/batch_request.py

@@ -1,8 +1,10 @@
 import json
 import re
 from email.message import Message
+from typing import Iterator, Tuple
 
 import requests
+from requests import Response
 from requests.structures import CaseInsensitiveDict
 
 from office365.runtime.compat import (
@@ -12,16 +14,14 @@
 from office365.runtime.http.http_method import HttpMethod
 from office365.runtime.http.request_options import RequestOptions
 from office365.runtime.odata.request import ODataRequest
-from office365.runtime.queries.batch import create_boundary
+from office365.runtime.queries.batch import BatchQuery, create_boundary
+from office365.runtime.queries.client_query import ClientQuery
 
 
 class ODataBatchV3Request(ODataRequest):
     def build_request(self, query):
-        """
-        Construct a OData v3 Batch request
-
-        :type query: office365.runtime.queries.batch.BatchQuery
-        """
+        # type: (BatchQuery) -> RequestOptions
+        """Construct a OData v3 Batch request"""
         request = RequestOptions(query.url)
         request.method = HttpMethod.Post
         media_type = "multipart/mixed"
@@ -33,17 +33,14 @@ def build_request(self, query):
         return request
 
     def process_response(self, response, query):
-        """
-        Parses an HTTP response.
-
-        :type response: requests.Response
-        :type query: office365.runtime.queries.batch.BatchQuery
-        """
+        # type: (Response, BatchQuery) -> None
+        """Parses an HTTP response."""
         for sub_qry, sub_resp in self._extract_response(response, query):
             sub_resp.raise_for_status()
             super(ODataBatchV3Request, self).process_response(sub_resp, sub_qry)
 
     def _extract_response(self, response, query):
+        # type: (requests.Response, BatchQuery) -> Iterator[Tuple[ClientQuery, Response]]
         """Parses a multipart/mixed response body from the position defined by the context.
 
         :type response: requests.Response
@@ -102,9 +99,7 @@ def _normalize_headers(headers_raw):
         return CaseInsensitiveDict(headers)
 
     def _deserialize_response(self, raw_response):
-        """
-        :type raw_response: Message
-        """
+        # type: (Message) -> Response
         response = raw_response.get_payload(decode=True)
         lines = list(filter(None, response.decode("utf-8").split("\r\n")))
         response_status_regex = "^HTTP/1\\.\\d (\\d{3}) (.*)$"
@@ -123,10 +118,9 @@ def _deserialize_response(self, raw_response):
 
     @staticmethod
     def _serialize_request(request):
+        # type: (RequestOptions) -> Message
         """Serializes a part of a batch request to a string. A part can be either a GET request or
-            a change set grouping several CUD (create, update, delete) requests.
-
-        :type request: RequestOptions
+        a change set grouping several CUD (create, update, delete) requests.
         """
         eol = "\r\n"
         method = request.method

office365/runtime/queries/batch.py

@@ -1,5 +1,7 @@
 import uuid
+from typing import List
 
+from office365.runtime.client_runtime_context import ClientRuntimeContext
 from office365.runtime.queries.client_query import ClientQuery
 from office365.runtime.queries.read_entity import ReadEntityQuery
 
@@ -20,21 +22,15 @@ class BatchQuery(ClientQuery):
     """Client query collection"""
 
     def __init__(self, context, queries=None):
-        """
-
-        :type context: office365.runtime.client_runtime_context.ClientRuntimeContext
-        :type queries: list[ClientQuery]
-        """
+        # type: (ClientRuntimeContext, List[ClientQuery]) -> None
         super(BatchQuery, self).__init__(context)
         self._current_boundary = create_boundary("batch_")
         if queries is None:
             queries = []
         self._queries = queries
 
     def add(self, query):
-        """
-        :type query: ClientQuery
-        """
+        # type: (ClientQuery) -> None
         self._queries.append(query)
 
     @property
@@ -51,9 +47,7 @@ def change_sets(self):
 
     @property
     def queries(self):
-        """
-        :rtype: list[ClientQuery]
-        """
+        # type: () -> List[ClientQuery]
         return self._queries
 
     @property

office365/runtime/queries/function.py

@@ -1,3 +1,6 @@
+from office365.runtime.client_object import ClientObject
+from office365.runtime.client_result import ClientResult
+from office365.runtime.client_value import ClientValue
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.runtime.queries.client_query import ClientQuery
 
@@ -8,12 +11,8 @@ class FunctionQuery(ClientQuery):
     def __init__(
         self, binding_type, method_name=None, method_params=None, return_type=None
     ):
-        """
-        Function query
-
-        :type method_params: list or dict or office365.runtime.client_value.ClientValue or None
-        :type method_name: str or None
-        """
+        # type: (ClientObject, str, list|dict|ClientValue, ClientObject|ClientResult) -> None
+        """Function query"""
         super(FunctionQuery, self).__init__(
             binding_type.context, binding_type, None, None, return_type
         )

office365/sharepoint/webs/theme_info.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.runtime.client_result import ClientResult
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.sharepoint.entity import Entity
@@ -23,14 +25,12 @@ def get_theme_font_by_name(self, name, lcid):
 
     @property
     def accessible_description(self):
-        """Specifies the accessible description for this theme.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Specifies the accessible description for this theme."""
         return self.properties.get("AccessibleDescription", None)
 
     @property
     def theme_background_image_uri(self):
-        """Specifies the URI of the background image for this theme.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Specifies the URI of the background image for this theme."""
         return self.properties.get("ThemeBackgroundImageUri", None)