SharePoint API: file and list item versions improvements

Author: vgrem

examples/sharepoint/files/assign_file_permissions.py

@@ -9,7 +9,7 @@
 role_def = client.web.role_definitions.get_by_type(RoleType.Contributor)
 
 # get user by email
-user = client.web.siteUsers.get_by_email(test_user_principal_name_alt)
+user = client.web.site_users.get_by_email(test_user_principal_name_alt)
 
 # assign user with role to file
 target_file = client.web.get_file_by_server_relative_path(file_url)

examples/sharepoint/files/download_file_versions.py

@@ -0,0 +1,16 @@
+import os
+import tempfile
+
+from office365.sharepoint.client_context import ClientContext
+from office365.sharepoint.files.file_version import FileVersion
+from tests import test_team_site_url, test_client_credentials
+
+ctx = ClientContext(test_team_site_url).with_credentials(test_client_credentials)
+file_url = "/sites/team/Shared Documents/report #123.csv"
+file_versions = ctx.web.get_file_by_server_relative_path(file_url).versions.get().execute_query()
+for version in file_versions:  # type: FileVersion
+    download_path = os.path.join(tempfile.mkdtemp(), version.version_label + "_" + os.path.basename(file_url))
+    with open(download_path, "wb") as local_file:
+        file = version.download(local_file).execute_query()
+    print("[Ok] file version {0} has been downloaded into: {1}".format(version.url, download_path))
+

office365/sharepoint/files/file.py

@@ -295,7 +295,9 @@ def open_binary(ctx, server_relative_url):
         return response
 
     def download(self, file_object):
-        """Download a file content
+        """
+        Download a file content
+
         :type file_object: typing.IO
         """
 
@@ -393,10 +395,7 @@ def length(self):
 
         :rtype: int or None
         """
-        if self.is_property_available('Length'):
-            return int(self.properties["Length"])
-        else:
-            return None
+        return int(self.properties.get("Length", -1))
 
     @property
     def exists(self):
@@ -459,10 +458,8 @@ def time_last_modified(self):
     def minor_version(self):
         """
         Gets a value that specifies the minor version of the file.
-
-        :rtype: int or None
         """
-        return self.properties.get("MinorVersion", None)
+        return int(self.properties.get("MinorVersion", -1))
 
     @property
     def major_version(self):
@@ -471,7 +468,7 @@ def major_version(self):
 
         :rtype: int or None
         """
-        return self.properties.get("MajorVersion", None)
+        return int(self.properties.get("MajorVersion", -1))
 
     @property
     def unique_id(self):
@@ -482,17 +479,25 @@ def unique_id(self):
         """
         return self.properties.get("UniqueId", None)
 
+    def get_property(self, name, default_value=None):
+        if default_value is None:
+            property_mapping = {
+                "LockedByUser": self.locked_by_user,
+                "ModifiedBy": self.modified_by
+            }
+            default_value = property_mapping.get(name, None)
+        return super(File, self).get_property(name, default_value)
+
     def set_property(self, name, value, persist_changes=True):
         super(File, self).set_property(name, value, persist_changes)
         # fallback: create a new resource path
         if self._resource_path is None:
             if name == "ServerRelativeUrl":
-                self._resource_path = ResourcePathServiceOperation(
-                    "GetFileByServerRelativeUrl", [value], ResourcePath("Web"))
+                self._resource_path = ResourcePathServiceOperation("GetFileByServerRelativeUrl", [value],
+                                                                   ResourcePath("Web"))
             elif name == "ServerRelativePath":
                 self._resource_path = ResourcePathServiceOperation("getFolderByServerRelativePath", [value],
                                                                    ResourcePath("Web"))
             elif name == "UniqueId":
-                self._resource_path = ResourcePathServiceOperation(
-                    "GetFileById", [value], ResourcePath("Web"))
+                self._resource_path = ResourcePathServiceOperation("GetFileById", [value], ResourcePath("Web"))
         return self

office365/sharepoint/files/file_version.py

@@ -1,10 +1,56 @@
+from office365.runtime.client_result import ClientResult
+from office365.runtime.queries.service_operation_query import ServiceOperationQuery
+from office365.runtime.resource_path import ResourcePath
 from office365.runtime.resource_path_service_operation import ResourcePathServiceOperation
 from office365.sharepoint.base_entity import BaseEntity
 
 
 class FileVersion(BaseEntity):
     """Represents a version of a File object."""
 
+    def download(self, file_object):
+        """Downloads the file version as a stream and save into a file.
+
+        :type file_object: typing.IO
+        """
+        def _file_version_loaded():
+            result = self.open_binary_stream()
+
+            def _process_response(response):
+                """
+                :type response: requests.Response
+                """
+                response.raise_for_status()
+                file_object.write(result.value)
+            self.context.after_execute(_process_response)
+        self.ensure_property("ID", _file_version_loaded)
+        return self
+
+    def open_binary_stream(self):
+        """Opens the file as a stream."""
+        return_stream = ClientResult(self.context)
+        qry = ServiceOperationQuery(self, "OpenBinaryStream", None, None, None, return_stream)
+        self.context.add_query(qry)
+        return return_stream
+
+    def open_binary_stream_with_options(self, open_options):
+        """Opens the file as a stream."""
+        return_stream = ClientResult(self.context)
+        qry = ServiceOperationQuery(self, "OpenBinaryStreamWithOptions", [open_options], None, None, return_stream)
+        self.context.add_query(qry)
+        return return_stream
+
+    @property
+    def created_by(self):
+        """Gets the user that created the file version."""
+        from office365.sharepoint.principal.user import User
+        return self.properties.get("CreatedBy", User(self.context, ResourcePath("CreatedBy", self.resource_path)))
+
+    @property
+    def id(self):
+        """Gets a file version identifier"""
+        return int(self.properties.get("ID", -1))
+
     @property
     def url(self):
         """Gets a value that specifies the relative URL of the file version based on the URL for the site or subsite."""
@@ -25,11 +71,18 @@ def checkin_comment(self):
         """Gets a value that specifies the check-in comment."""
         return self.properties.get("CheckInComment", None)
 
+    def get_property(self, name, default_value=None):
+        if default_value is None:
+            property_mapping = {
+                "CreatedBy": self.created_by,
+            }
+            default_value = property_mapping.get(name, None)
+        return super(FileVersion, self).get_property(name, default_value)
+
     def set_property(self, name, value, persist_changes=True):
         super(FileVersion, self).set_property(name, value, persist_changes)
         if self._resource_path is None:
             if name == "ID":
                 self._resource_path = ResourcePathServiceOperation(
-                    "GetById",
-                    [value],
-                    self._parent_collection.resource_path)
+                    "GetById", [value], self._parent_collection.resource_path)
+        return self

office365/sharepoint/files/file_version_collection.py

@@ -1,3 +1,5 @@
+from office365.runtime.queries.service_operation_query import ServiceOperationQuery
+from office365.runtime.resource_path_service_operation import ResourcePathServiceOperation
 from office365.sharepoint.base_entity_collection import BaseEntityCollection
 from office365.sharepoint.files.file_version import FileVersion
 
@@ -6,3 +8,62 @@ class FileVersionCollection(BaseEntityCollection):
     """Represents a collection of FileVersion."""
     def __init__(self, context, resource_path=None):
         super(FileVersionCollection, self).__init__(context, FileVersion, resource_path)
+
+    def get_by_id(self, version_id):
+        """Gets the file version with the specified ID."""
+        return FileVersion(self.context, ResourcePathServiceOperation("getById", [version_id], self.resource_path))
+
+    def delete_all(self):
+        """Deletes all the file version objects in the collection."""
+        qry = ServiceOperationQuery(self, "DeleteAll")
+        self.context.add_query(qry)
+        return self
+
+    def delete_by_id(self, vid):
+        """Removes the file version object with the specified integer ID from the collection.
+
+        :param int vid: The file version to remove.
+        """
+        qry = ServiceOperationQuery(self, "DeleteByID", {"vid": vid})
+        self.context.add_query(qry)
+        return self
+
+    def delete_by_label(self, label):
+        """
+        Deletes the file version object with the specified version label.
+
+        :param str label: The file version to remove.
+        """
+        qry = ServiceOperationQuery(self, "DeleteByLabel", {"versionlabel": label})
+        self.context.add_query(qry)
+        return self
+
+    def recycle_by_id(self, vid):
+        """
+        Recycles a file version objects in the collection by version identifier.
+
+        :param int vid: The file version to remove.
+        """
+        qry = ServiceOperationQuery(self, "RecycleByID", {"vid": vid})
+        self.context.add_query(qry)
+        return self
+
+    def recycle_by_label(self, label):
+        """
+        Recycles the file version object with the specified version label.
+
+        :param str label: The file version to remove.
+        """
+        qry = ServiceOperationQuery(self, "RecycleByLabel", {"versionlabel": label})
+        self.context.add_query(qry)
+        return self
+
+    def restore_by_label(self, label):
+        """
+        Restores the file version object that has the specified version label.
+
+        :param str label: The file version to remove.
+        """
+        qry = ServiceOperationQuery(self, "RestoreByLabel", {"versionlabel": label})
+        self.context.add_query(qry)
+        return self

office365/sharepoint/internal/download_file.py

@@ -13,11 +13,15 @@ def create_download_file_query(source_file, file_object):
 
     def _process_response(response):
         """
-        :type response: RequestOptions
+        :type response: requests.Response
         """
+        response.raise_for_status()
         file_object.write(response.content)
 
     def _construct_download_query(request):
+        """
+        :type request: office365.runtime.http.request_options.RequestOptions
+        """
         request.method = HttpMethod.Get
         source_file.context.after_execute(_process_response)
 

office365/sharepoint/listitems/list_item_version.py

@@ -1,5 +1,66 @@
+from office365.runtime.resource_path import ResourcePath
+from office365.runtime.resource_path_service_operation import ResourcePathServiceOperation
 from office365.sharepoint.base_entity import BaseEntity
 
 
 class ListItemVersion(BaseEntity):
-    pass
+    """Represents a version of a list item."""
+
+    @property
+    def version_id(self):
+        """Gets the ID of the version."""
+        return int(self.properties.get("VersionId", -1))
+
+    @property
+    def version_label(self):
+        """Gets the version number of the item version."""
+        return self.properties.get("VersionLabel")
+
+    @property
+    def is_current_version(self):
+        """Gets a value that specifies whether the file version is the current version.
+
+        :rtype: bool
+        """
+        return self.properties.get("IsCurrentVersion", None)
+
+    @property
+    def created(self):
+        """Gets the creation date and time for the item version."""
+        return self.properties.get("Created", None)
+
+    @property
+    def created_by(self):
+        """Gets the user that created the item version."""
+        from office365.sharepoint.principal.user import User
+        return self.properties.get("CreatedBy", User(self.context, ResourcePath("CreatedBy", self.resource_path)))
+
+    @property
+    def fields(self):
+        """Gets the collection of fields that are used in the list that contains the item version."""
+        from office365.sharepoint.fields.field_collection import FieldCollection
+        return self.properties.get("Fields", FieldCollection(self.context, ResourcePath("Fields", self.resource_path)))
+
+    @property
+    def file_version(self):
+        from office365.sharepoint.files.file_version import FileVersion
+        return self.properties.get("FileVersion",
+                                   FileVersion(self.context, ResourcePath("FileVersion", self.resource_path)))
+
+    def get_property(self, name, default_value=None):
+        if default_value is None:
+            property_mapping = {
+                "CreatedBy": self.created_by,
+                "FileVersion": self.file_version
+            }
+            default_value = property_mapping.get(name, None)
+        return super(ListItemVersion, self).get_property(name, default_value)
+
+    def set_property(self, name, value, persist_changes=True):
+        if self._resource_path is None:
+            if name == "VersionId":
+                self._resource_path = ResourcePathServiceOperation(
+                    "GetById", [value], self._parent_collection.resource_path)
+        return super(ListItemVersion, self).set_property(name, value, persist_changes)
+
+