Refactor file session upload method in SharePoint API, typing improvements

Author: vgrem

examples/sharepoint/fields/get_from_web.py

@@ -1,5 +1,5 @@
 """
-This example retrieves all fields in a SharePoint site.
+This example demonstrates how to retrieve all fields in a SharePoint site.
 """
 from office365.sharepoint.client_context import ClientContext
 from tests import test_client_credentials, test_team_site_url

examples/sharepoint/files/delete.py

@@ -1,8 +1,10 @@
+"""
+Deletes a file from SharePoint site
+"""
 from office365.sharepoint.client_context import ClientContext
 from tests import test_team_site_url, test_user_credentials
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_user_credentials)
-
 file_url = "Shared Documents/SharePoint User Guide.docx"
 file = ctx.web.get_file_by_server_relative_url(file_url)
 file.delete_object().execute_query()

examples/sharepoint/files/download_recent.py

@@ -2,7 +2,6 @@
 import tempfile
 
 from office365.sharepoint.client_context import ClientContext
-from office365.sharepoint.listitems.listitem import ListItem
 from tests import test_site_url, test_user_credentials
 
 ctx = ClientContext(test_site_url).with_credentials(test_user_credentials)
@@ -16,7 +15,7 @@
     .get()
     .execute_query()
 )
-for item in recent_items:  # type: ListItem
+for item in recent_items:
     file_url = item.properties.get("FileRef")
     download_path = os.path.join(tempfile.mkdtemp(), os.path.basename(file_url))
     with open(download_path, "wb") as local_file:

examples/sharepoint/files/traverse.py examples/sharepoint/files/get_all_items.py

@@ -4,7 +4,7 @@
 from tests import test_client_credentials, test_team_site_url
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
-doc_lib = ctx.web.lists.get_by_title("Documents_Archive")
+doc_lib = ctx.web.default_document_library()
 items = (
     doc_lib.items.select(["FileSystemObjectType"])
     .expand(["File", "Folder"])

examples/sharepoint/files/get_checkout_type.py

@@ -0,0 +1,19 @@
+"""
+Retrieves file check out status
+
+https://support.microsoft.com/en-us/office/check-out-or-check-in-files-in-a-document-library-acce24cd-ab39-4fcf-9c4d-1ce3050dc602
+"""
+
+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)
+file_url = "SitePages/Home.aspx"
+file = ctx.web.get_file_by_server_relative_url(file_url).get().execute_query()
+
+if file.check_out_type == 0:
+    print("The file is checked out for editing on the server")
+elif file.check_out_type == 1:
+    print("The file is checked out for editing on the local computer.")
+else:
+    print("The file is not checked out.")

examples/sharepoint/files/get_content.py

@@ -1,12 +1,12 @@
 """
-Demonstrates how to download a file content (intended for a small files with a size less than 4 Mb)
+Demonstrates how to download a file content.
+Intended for a 'small' files (with a size less than 4 Mb)
 """
 
 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)
-file_url = "SitePages/Home.aspx"
 file = ctx.web.lists.get_by_title("Site Pages").root_folder.files.get_by_url(
     "Home.aspx"
 )

examples/sharepoint/files/get_extended_props.py

@@ -0,0 +1,16 @@
+"""
+Retrieves file extended properties (accessible via associated ListItem)
+"""
+
+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)
+file_url = "SitePages/Home.aspx"
+file_item = (
+    ctx.web.get_file_by_server_relative_url(file_url)
+    .listItemAllFields.get()
+    .execute_query()
+)
+for k, v in file_item.properties.items():
+    print("{0}: {1}".format(k, v))

examples/sharepoint/files/get_system_metadata.py

@@ -0,0 +1,20 @@
+"""
+Retrieves file system metadata
+"""
+
+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)
+file_url = "SitePages/Home.aspx"
+file = (
+    ctx.web.get_file_by_server_relative_url(file_url)
+    .expand(["ModifiedBy", "Author", "TimeCreated", "TimeLastModified"])
+    .get()
+    .execute_query()
+)
+
+print(file.author)
+print(file.modified_by)
+print(file.time_created)
+print(file.time_last_modified)

examples/sharepoint/files/get_version.py

@@ -3,7 +3,6 @@
 """
 
 from office365.sharepoint.client_context import ClientContext
-from office365.sharepoint.files.versions.version import FileVersion
 from tests import test_client_credentials, test_team_site_url
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
@@ -14,5 +13,5 @@
     .get()
     .execute_query()
 )
-for version in file_with_versions.versions:  # type: FileVersion
+for version in file_with_versions.versions:
     print(version.version_label)

examples/sharepoint/files/list.py

@@ -19,10 +19,8 @@ def enum_folder(parent_folder, fn):
 
 
 def print_file(f):
-    """
-    :type f: File
-    """
-    print(f.properties["ServerRelativeUrl"])
+    # type: (File) -> None
+    print(f.serverRelativeUrl)
 
 
 target_folder_url = "Shared Documents"

examples/sharepoint/files/upload_large.py

@@ -9,6 +9,7 @@
 
 
 def print_upload_progress(offset):
+    # type: (int) -> None
     file_size = os.path.getsize(local_path)
     print(
         "Uploaded '{0}' bytes from '{1}'...[{2}%]".format(

examples/sharepoint/folders/get_folder_files.py

@@ -1,5 +1,5 @@
 """
-Prints file names in a folder
+Gets files within a folder
 """
 from office365.sharepoint.client_context import ClientContext
 from tests import test_client_credentials, test_team_site_url

examples/sharepoint/folders/share_with_external_user.py

@@ -1,11 +1,9 @@
 """
-Share a Folder with External User
+Share a folder with a set of users
 """
 
-import json
-
 from office365.sharepoint.client_context import ClientContext
-from office365.sharepoint.sharing.role_type import RoleType
+from office365.sharepoint.sharing.role import Role
 from office365.sharepoint.sharing.user_role_assignment import UserRoleAssignment
 from tests import (
     test_client_credentials,
@@ -16,6 +14,7 @@
 ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
 folder_url = "Shared Documents/Archive"
 folder = ctx.web.get_folder_by_server_relative_path(folder_url)
-assignment = UserRoleAssignment(RoleType.Guest, test_user_principal_name_alt)
+assignment = UserRoleAssignment(Role.Edit, test_user_principal_name_alt)
 result = folder.update_document_sharing_info([assignment]).execute_query()
-print(json.dumps(result.value.to_json(), indent=4))
+for item in result.value:
+    print(item)

examples/sharepoint/hubsites/__init__.py

@@ -1,8 +1,10 @@
-import json
-
+"""
+Gets information about all hub sites that the current user can access.
+"""
 from office365.sharepoint.client_context import ClientContext
 from tests import test_team_site_url, test_user_credentials
 
 ctx = ClientContext(test_team_site_url).with_credentials(test_user_credentials)
 hub_sites = ctx.hub_sites.get().execute_query()
-print(json.dumps(hub_sites.to_json(), indent=4))
+for hub_site in hub_sites:
+    print(hub_site)

examples/sharepoint/hubsites/list_my.py

@@ -1,5 +1,5 @@
 """
-Delete a SharePoint list
+Deletes a SharePoint list
 """
 from office365.sharepoint.client_context import ClientContext
 from tests import test_client_credentials, test_team_site_url

examples/sharepoint/lists/delete.py

@@ -1,3 +1,6 @@
+"""
+Saves the list as a template in the list template gallery
+"""
 from office365.sharepoint.client_context import ClientContext
 from tests import test_client_credentials, test_team_site_url
 

examples/sharepoint/export/save_list_as_template.py examples/sharepoint/lists/save_as_template.py

@@ -0,0 +1,16 @@
+"""
+Revokes user access from web
+"""
+from office365.sharepoint.client_context import ClientContext
+from office365.sharepoint.sharing.role_type import RoleType
+from tests import (
+    test_client_credentials,
+    test_team_site_url,
+    test_user_principal_name_alt,
+)
+
+ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
+result = ctx.web.remove_role_assignment(
+    test_user_principal_name_alt, RoleType.Contributor
+).execute_query()
+print("Access has been revoked")

examples/sharepoint/permissions/revoke_from_web.py

@@ -1,5 +1,5 @@
 """
-
+Prints server settings
 """
 
 from office365.sharepoint.client_context import ClientContext
@@ -12,4 +12,4 @@
 installed_languages = ServerSettings.get_global_installed_languages(ctx, 15)
 ctx.execute_batch()
 print("Is SharePoint Online? : {0}".format(is_online.value))
-print("Installed languages amount : {0}".format(len(installed_languages.items)))
+print("Installed languages : {0}".format(installed_languages))

examples/sharepoint/print_server_settings.py

@@ -1,3 +1,6 @@
+"""
+
+"""
 from office365.sharepoint.client_context import ClientContext
 from tests import test_site_url, test_user_credentials
 

examples/sharepoint/search/search_documents.py

@@ -1,6 +1,5 @@
 """
 Search SharePoint sites the current user is member of
-
 """
 
 from office365.sharepoint.client_context import ClientContext

examples/sharepoint/search/search_sites.py

@@ -4,14 +4,14 @@
 
 
 class HostedAppsManager(Entity):
-    def get_by_id(self, _id):
+    def get_by_id(self, id_):
         """
         Gets an hosted app based on the Id.
 
-        :param str _id: The Id of the hosted app to get.
+        :param str id_: The Id of the hosted app to get.
         """
         return HostedApp(
-            self.context, ServiceOperationPath("GetById", [_id], self.resource_path)
+            self.context, ServiceOperationPath("GetById", [id_], self.resource_path)
         )
 
     @property

office365/sharepoint/clientsidecomponent/hostedapps/manager.py

@@ -20,4 +20,4 @@ def __init__(self, string_value=None):
         self.StringValue = string_value
 
     def __repr__(self):
-        return self.StringValue
+        return self.StringValue or self.entity_type_name

office365/sharepoint/contenttypes/content_type_id.py

@@ -14,6 +14,9 @@ class Field(Entity):
     def __init__(self, context, resource_path=None):
         super(Field, self).__init__(context, resource_path)
 
+    def __repr__(self):
+        return self.internal_name or self.id
+
     @staticmethod
     def resolve_field_type(type_id_or_name):
         from office365.sharepoint.fields.calculated import FieldCalculated

office365/sharepoint/fields/field.py

@@ -1,13 +1,13 @@
 import os
+import uuid
+from typing import IO, Callable
 
+from office365.runtime.client_result import ClientResult
 from office365.runtime.paths.service_operation import ServiceOperationPath
 from office365.runtime.queries.service_operation import ServiceOperationQuery
 from office365.sharepoint.entity_collection import EntityCollection
 from office365.sharepoint.files.creation_information import FileCreationInformation
 from office365.sharepoint.files.file import File
-from office365.sharepoint.internal.queries.upload_session import (
-    create_upload_session_query_ex,
-)
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 
 
@@ -35,21 +35,59 @@ def upload(self, path_or_file):
             return self.add(name, content, True)
 
     def create_upload_session(
-        self, path_or_file, chunk_size, chunk_uploaded=None, **kwargs
+        self, file, chunk_size, chunk_uploaded=None, file_name=None, **kwargs
     ):
+        # type: (IO|str, int, Callable[[int, ...], None], str, ...) -> File
         """Upload a file as multiple chunks
-
-        :param str or typing.IO path_or_file: path where file to upload resides or file handle
+        :param str or typing.IO file: path where file to upload resides or file handle
         :param int chunk_size: upload chunk size (in bytes)
         :param (long)->None or None chunk_uploaded: uploaded event
+        :param str file_name: custom file name
         :param kwargs: arguments to pass to chunk_uploaded function
         """
 
-        qry = create_upload_session_query_ex(
-            self, path_or_file, chunk_size, chunk_uploaded, **kwargs
-        )
-        self.context.add_query(qry)
-        return qry.return_type
+        auto_close = False
+        if not hasattr(file, "read"):
+            file = open(file, "rb")
+            auto_close = True
+
+        file_size = os.fstat(file.fileno()).st_size
+        file_name = file_name if file_name else os.path.basename(file.name)
+        upload_id = str(uuid.uuid4())
+
+        def _upload_session(return_type, return_file):
+            # type: (File|ClientResult, File) -> None
+            if return_file is None:
+                return_file = return_type
+
+            uploaded_bytes = file.tell()
+            if callable(chunk_uploaded):
+                chunk_uploaded(uploaded_bytes, **kwargs)
+
+            if uploaded_bytes == file_size:
+                if auto_close and not file.closed:
+                    file.close()
+                return
+
+            content = file.read(chunk_size)
+
+            if uploaded_bytes == 0:
+                return_file.start_upload(upload_id, content).after_execute(
+                    _upload_session, return_file
+                )
+            elif uploaded_bytes + len(content) < file_size:
+                return_file.continue_upload(
+                    upload_id, uploaded_bytes, content
+                ).after_execute(_upload_session, return_file)
+            else:
+                return_file.finish_upload(
+                    upload_id, uploaded_bytes, content
+                ).after_execute(_upload_session, return_file)
+
+        if file_size > chunk_size:
+            return self.add(file_name, None, True).after_execute(_upload_session, None)
+        else:
+            return self.add(file_name, file.read(), True)
 
     def add(self, url, content, overwrite=False):
         """
@@ -60,7 +98,7 @@ def add(self, url, content, overwrite=False):
             or absolute form. Its length MUST be equal to or greater than 1.
         :param bool overwrite: Specifies whether to overwrite an existing file with the same name and in the same
             location as the one being added.
-        :param str or bytes content: Specifies the binary content of the file to be added.
+        :param str or bytes or None content: Specifies the binary content of the file to be added.
         """
         return_type = File(self.context)
         self.add_child(return_type)