Office365-REST-Python-Client 2.5.1__py3-none-any.whl → 2.5.3__py3-none-any.whl

office365/sharepoint/files/file.py

@@ -1,5 +1,7 @@
 import datetime
-from typing import AnyStr
+from typing import TYPE_CHECKING, AnyStr
+
+import requests
 
 from office365.runtime.client_result import ClientResult
 from office365.runtime.http.http_method import HttpMethod
@@ -23,12 +25,16 @@ from office365.sharepoint.permissions.irm.file_settings import (
     InformationRightsManagementFileSettings,
 )
 from office365.sharepoint.principal.users.user import User
+from office365.sharepoint.sharing.links.share_response import ShareLinkResponse
 from office365.sharepoint.types.resource_path import ResourcePath as SPResPath
 from office365.sharepoint.utilities.upload_status import UploadStatus
 from office365.sharepoint.utilities.wopi_frame_action import SPWOPIFrameAction
 from office365.sharepoint.webparts.limited_manager import LimitedWebPartManager
 from office365.sharepoint.webparts.personalization_scope import PersonalizationScope
 
+if TYPE_CHECKING:
+    from typing import Optional
+
 
 class AbstractFile(Entity):
     def read(self):
@@ -52,11 +58,19 @@ class File(AbstractFile):
     """Represents a file in a SharePoint Web site that can be a Web Part Page, an item in a document library,
     or a file in a folder."""
 
+    def __repr__(self):
+        if self.server_relative_path:
+            return repr(self.server_relative_path)
+        else:
+            return self.serverRelativeUrl or self.unique_id or self.entity_type_name
+
+    def __str__(self):
+        return self.name or self.entity_type_name
+
     @staticmethod
     def from_url(abs_url):
         """
         Retrieves a File from absolute url
-
         :type abs_url: str
         """
         from office365.sharepoint.client_context import ClientContext
@@ -84,11 +98,12 @@ class File(AbstractFile):
         return return_type
 
     def create_anonymous_link_with_expiration(self, expiration, is_edit_link=False):
+        # type: (datetime.datetime, bool) -> ClientResult[str]
         """Creates and returns an anonymous link that can be used to access a document without needing to authenticate.
 
-        :param bool is_edit_link: If true, the link will allow the guest user edit privileges on the item.
+        :param is_edit_link: If true, the link will allow the guest user edit privileges on the item.
         string parameters
-        :param datetime.datetime expiration: A date/time string for which the format conforms to the ISO 8601:2004(E) complete
+        :param expiration: A date/time string for which the format conforms to the ISO 8601:2004(E) complete
         representation for calendar date and time of day, and which represents the time and date of expiry for the
         anonymous link. Both the minutes and hour value MUST be specified for the difference between the local and
         UTC time. Midnight is represented as 00:00:00.
@@ -151,18 +166,19 @@ class File(AbstractFile):
         return return_type
 
     def share_link(self, link_kind, expiration=None, role=None, password=None):
+        # type: (int, Optional[datetime.datetime], Optional[int], Optional[str]) -> ClientResult[ShareLinkResponse]
         """Creates a tokenized sharing link for a file based on the specified parameters and optionally
         sends an email to the people that are listed in the specified parameters.
 
-        :param int link_kind: The kind of the tokenized sharing link to be created/updated or retrieved.
-        :param datetime.datetime or None expiration: A date/time string for which the format conforms to the ISO 8601:2004(E)
+        :param link_kind: The kind of the tokenized sharing link to be created/updated or retrieved.
+        :param expiration: A date/time string for which the format conforms to the ISO 8601:2004(E)
             complete representation for calendar date and time of day and which represents the time and date of expiry
             for the tokenized sharing link. Both the minutes and hour value MUST be specified for the difference
             between the local and UTC time. Midnight is represented as 00:00:00. A null value indicates no expiry.
             This value is only applicable to tokenized sharing links that are anonymous access links.
-        :param int role: The role to be used for the tokenized sharing link. This is required for Flexible links
+        :param role: The role to be used for the tokenized sharing link. This is required for Flexible links
             and ignored for all other kinds.
-        :param str password: Optional password value to apply to the tokenized sharing link,
+        :param password: Optional password value to apply to the tokenized sharing link,
             if it can support password protection.
         """
         return self.listItemAllFields.share_link(link_kind, expiration, role, password)
@@ -238,21 +254,23 @@ class File(AbstractFile):
         self.context.add_query(qry)
         return self
 
-    def copyto(self, destination, overwrite=False):
+    def copyto(self, destination, overwrite=False, file_name=None):
+        # type: (Folder|str, bool, str) -> "File"
         """Copies the file to the destination URL.
 
         :param office365.sharepoint.folders.folder.Folder or str destination: Specifies the destination folder or
             folder server relative url where to copy a file.
         :param bool overwrite: Specifies whether a file with the same name is overwritten.
+        :param str file_name: A new file name
         """
         return_type = File(self.context)
         self.parent_collection.add_child(return_type)
 
         def _copyto(destination_folder):
-            """
-            :type destination_folder: Folder
-            """
-            file_path = "/".join([str(destination_folder.serverRelativeUrl), self.name])
+            # type: (Folder) -> None
+            file_path = "/".join(
+                [str(destination_folder.serverRelativeUrl), file_name or self.name]
+            )
             return_type.set_property("ServerRelativeUrl", file_path)
 
             params = {"strNewUrl": file_path, "boverwrite": overwrite}
@@ -263,14 +281,12 @@ class File(AbstractFile):
             if isinstance(destination, Folder):
                 destination.ensure_property("ServerRelativeUrl", _copyto, destination)
             else:
-                self.context.web.ensure_folder_path(destination).get().after_execute(
-                    _copyto
-                )
+                self.context.web.ensure_folder_path(destination).after_execute(_copyto)
 
-        self.ensure_property("ServerRelativeUrl", _source_file_resolved)
+        self.ensure_properties(["ServerRelativeUrl", "Name"], _source_file_resolved)
         return return_type
 
-    def copyto_using_path(self, destination, overwrite=False):
+    def copyto_using_path(self, destination, overwrite=False, file_name=None):
         """
         Copies the file to the destination path. Server MUST overwrite an existing file of the same name
         if overwrite is true.
@@ -278,17 +294,16 @@ class File(AbstractFile):
         :param bool overwrite: Specifies whether a file with the same name is overwritten.
         :param office365.sharepoint.folders.folder.Folder or str destination: Specifies the destination folder or
             folder server relative url where to copy a file.
+        :param str file_name: New file name
         """
 
         return_type = File(self.context)
         self.parent_collection.add_child(return_type)
 
         def _copyto_using_path(destination_folder):
-            """
-            :type destination_folder: Folder
-            """
+            # type: (Folder) -> None
             file_path = "/".join(
-                [str(destination_folder.server_relative_path), self.name]
+                [str(destination_folder.server_relative_path), file_name or self.name]
             )
             return_type.set_property("ServerRelativePath", file_path)
 
@@ -352,16 +367,19 @@ class File(AbstractFile):
         """
 
         def _update_file(return_type, new_file_url):
+            # type: (File, str) -> None
             return_type.set_property("ServerRelativePath", new_file_url)
 
         def _move_to_using_path(destination_folder):
+            # type: (Folder) -> None
             file_path = "/".join(
                 [str(destination_folder.server_relative_path), self.name]
             )
             params = {"DecodedUrl": file_path, "moveOperations": flag}
             qry = ServiceOperationQuery(self, "MoveToUsingPath", params)
-            self.context.add_query(qry)
-            self.context.after_query_execute(_update_file, self, file_path)
+            self.context.add_query(qry).after_query_execute(
+                _update_file, self, file_path
+            )
 
         def _source_file_resolved():
             if isinstance(destination, Folder):
@@ -378,7 +396,6 @@ class File(AbstractFile):
 
     def publish(self, comment):
         """Submits the file for content approval with the specified comment.
-
         :param str comment: Specifies the comment.
         """
         qry = ServiceOperationQuery(self, "Publish", {"comment": comment})
@@ -387,7 +404,6 @@ class File(AbstractFile):
 
     def unpublish(self, comment):
         """Removes the file from content approval or unpublishes a major version.
-
         :param str comment: Specifies the comment for UnPublish. Its length MUST be equal to or less than 1023.
         """
         qry = ServiceOperationQuery(self, "unpublish", {"comment": comment})
@@ -464,7 +480,6 @@ class File(AbstractFile):
 
     def get_upload_status(self, upload_id):
         """Gets the status of a chunk upload session.
-
         :param str upload_id:  The upload session ID.
         """
         payload = {
@@ -484,9 +499,9 @@ class File(AbstractFile):
         :param bytes stream:
         """
         return_type = File(self.context)
-        payload = {"uploadId": upload_id, "checksum": checksum, "stream": stream}
+        params = {"uploadId": upload_id, "checksum": checksum}
         qry = ServiceOperationQuery(
-            self, "UploadWithChecksum", None, payload, None, return_type
+            self, "UploadWithChecksum", params, stream, None, return_type
         )
         self.context.add_query(qry)
         return return_type
@@ -555,6 +570,26 @@ class File(AbstractFile):
         self.context.add_query(qry)
         return self
 
+    def finish_upload_with_checksum(self, upload_id, file_offset, checksum, stream):
+        """Uploads the last file fragment and commits the file. The current file content is changed when this method
+        completes.
+
+        :param str upload_id: Upload session id
+        :param int file_offset: File offset
+        :param str checksum: File checksum
+        :param bytes stream: File content
+        """
+        payload = {
+            "uploadID": upload_id,
+            "fileOffset": file_offset,
+            "checksum": checksum,
+        }
+        qry = ServiceOperationQuery(
+            self, "FinishUploadWithChecksum", payload, stream, None, self
+        )
+        self.context.add_query(qry)
+        return self
+
     @staticmethod
     def save_binary(context, server_relative_url, content):
         """Uploads a file
@@ -599,15 +634,13 @@ class File(AbstractFile):
         """
 
         def _save_content(return_type):
-            """
-            :type return_type: ClientResult
-            """
+            # type: (ClientResult[AnyStr]) -> None
             file_object.write(return_type.value)
             if callable(after_downloaded):
                 after_downloaded(self)
 
         def _download_inner():
-            return_type = self.get_content().after_execute(_save_content)
+            self.get_content().after_execute(_save_content)
 
         self.ensure_property("ServerRelativePath", _download_inner)
         return self
@@ -627,19 +660,15 @@ class File(AbstractFile):
         def _download_as_stream():
             qry = ServiceOperationQuery(self, "$value")
 
-            def _construct_download_request(request):
-                """
-                :type request: office365.runtime.http.request_options.RequestOptions
-                """
+            def _construct_request(request):
+                # type: (RequestOptions) -> None
                 request.stream = True
                 request.method = HttpMethod.Get
 
-            self.context.before_execute(_construct_download_request)
+            self.context.before_execute(_construct_request)
 
-            def _process_download_response(response):
-                """
-                :type response: requests.Response
-                """
+            def _process_response(response):
+                # type: (requests.Response) -> None
                 response.raise_for_status()
                 bytes_read = 0
                 for chunk in response.iter_content(chunk_size=chunk_size):
@@ -648,7 +677,7 @@ class File(AbstractFile):
                         chunk_downloaded(bytes_read)
                     file_object.write(chunk)
 
-            self.context.after_execute(_process_download_response)
+            self.context.after_execute(_process_response)
             self.context.add_query(qry)
 
         if use_path:
@@ -660,7 +689,6 @@ class File(AbstractFile):
     def rename(self, new_file_name):
         """
         Rename a file
-
         :param str new_file_name: A new file name
         """
         item = self.listItemAllFields
@@ -689,15 +717,20 @@ class File(AbstractFile):
             User(self.context, ResourcePath("CheckedOutByUser", self.resource_path)),
         )
 
+    @property
+    def check_out_type(self):
+        # type: () -> Optional[int]
+        return self.properties.get("CheckOutType", None)
+
     @property
     def expiration_date(self):
-        """
-        Required. Specifies the date and time when the file expires.
-        """
+        # type: () -> Optional[datetime.datetime]
+        """Specifies the date and time when the file expires."""
         return self.properties.get("ExpirationDate", datetime.datetime.min)
 
     @property
     def version_events(self):
+        # type: () -> EntityCollection[FileVersionEvent]
         """Gets the history of events on this version object."""
         return self.properties.get(
             "VersionEvents",
@@ -727,9 +760,7 @@ class File(AbstractFile):
 
     @property
     def information_rights_management_settings(self):
-        """
-        Returns the Information Rights Management (IRM) settings for the file.
-        """
+        """Returns the Information Rights Management (IRM) settings for the file."""
         return self.properties.get(
             "InformationRightsManagementSettings",
             InformationRightsManagementFileSettings(
@@ -762,6 +793,7 @@ class File(AbstractFile):
 
     @property
     def versions(self):
+        # type: () -> FileVersionCollection
         """Gets a value that returns a collection of file version objects that represent the versions of the file."""
         return self.properties.get(
             "Versions",
@@ -772,9 +804,7 @@ class File(AbstractFile):
 
     @property
     def modified_by(self):
-        """
-        Gets a value that returns the user who last modified the file.
-        """
+        """Gets a value that returns the user who last modified the file."""
         return self.properties.get(
             "ModifiedBy",
             User(self.context, ResourcePath("ModifiedBy", self.resource_path)),
@@ -782,9 +812,7 @@ class File(AbstractFile):
 
     @property
     def locked_by_user(self):
-        """
-        Gets a value that returns the user that owns the current lock on the file.
-        """
+        """Gets a value that returns the user that owns the current lock on the file."""
         return self.properties.get(
             "LockedByUser",
             User(self.context, ResourcePath("LockedByUser", self.resource_path)),
@@ -792,127 +820,107 @@ class File(AbstractFile):
 
     @property
     def serverRelativeUrl(self):
-        """Gets the relative URL of the file based on the URL for the server.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets the relative URL of the file based on the URL for the server."""
         return self.properties.get("ServerRelativeUrl", None)
 
     @property
     def server_relative_path(self):
-        """Gets the server-relative Path of the list folder.
-
-        :rtype: SPResPath or None
-        """
+        """Gets the server-relative Path of the list folder."""
         return self.properties.get("ServerRelativePath", SPResPath())
 
     @property
     def length(self):
-        """Gets the file size.
-
-        :rtype: int or None
-        """
-        return int(self.properties.get("Length", -1))
+        # type: () -> Optional[int]
+        """Gets the file size."""
+        return int(self.properties.get("Length", 0))
 
     @property
     def exists(self):
-        """Specifies whether the file exists.
-        :rtype: bool or None
-        """
+        # type: () -> Optional[bool]
+        """Specifies whether the file exists."""
         return self.properties.get("Exists", None)
 
     @property
     def irm_enabled(self):
+        # type: () -> Optional[bool]
         """Specifies whether or not Information Rights Management (IRM) is enabled at the file level.
         A value of true indicates IRM is enabled; a value of false indicates IRM is disabled.
-        :rtype: bool or None
         """
         return self.properties.get("IrmEnabled", None)
 
     @property
     def level(self):
-        """Specifies the publishing level of the file.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Specifies the publishing level of the file."""
         return self.properties.get("Level", None)
 
     @property
     def linking_uri(self):
-        """Specifies the URL that is suitable for durable linking to the file.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Specifies the URL that is suitable for durable linking to the file."""
         return self.properties.get("LinkingUri", None)
 
     @property
     def name(self):
+        # type: () -> Optional[str]
         """Specifies the file name including the extension.
-            It MUST NOT be NULL. Its length MUST be equal to or less than 260.
-        :rtype: str or None
+        It MUST NOT be NULL. Its length MUST be equal to or less than 260.
         """
         return self.properties.get("Name", None)
 
     @property
     def list_id(self):
-        """Gets the GUID that identifies the List containing the file.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets the GUID that identifies the List containing the file."""
         return self.properties.get("ListId", None)
 
     @property
     def site_id(self):
-        """Gets the GUID that identifies the site collection containing the file.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets the GUID that identifies the site collection containing the file."""
         return self.properties.get("SiteId", None)
 
     @property
     def web_id(self):
-        """Gets the GUID for the site containing the file.
-
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets the GUID for the site containing the file."""
         return self.properties.get("WebId", None)
 
     @property
     def time_created(self):
-        """Gets a value that specifies when the file was created.
-        :rtype: str or None
-        """
+        # type: () -> Optional[datetime.datetime]
+        """Gets a value that specifies when the file was created."""
         return self.properties.get("TimeCreated", datetime.datetime.min)
 
     @property
     def time_last_modified(self):
+        # type: () -> Optional[datetime.datetime]
         """Specifies when the file was last modified."""
         return self.properties.get("TimeLastModified", datetime.datetime.min)
 
     @property
     def minor_version(self):
-        """
-        Gets a value that specifies the minor version of the file.
-        """
-        return int(self.properties.get("MinorVersion", -1))
+        # type: () -> Optional[int]
+        """Gets a value that specifies the minor version of the file."""
+        return self.properties.get("MinorVersion", None)
 
     @property
     def major_version(self):
-        """
-        Gets a value that specifies the major version of the file.
-        :rtype: int or None
-        """
-        return int(self.properties.get("MajorVersion", -1))
+        # type: () -> Optional[int]
+        """Gets a value that specifies the major version of the file."""
+        return self.properties.get("MajorVersion", None)
 
     @property
     def unique_id(self):
-        """
-        Gets a value that specifies the a file unique identifier
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Gets a value that specifies the a file unique identifier"""
         return self.properties.get("UniqueId", None)
 
     @property
     def customized_page_status(self):
-        """Specifies the customization status of the file.
-        :rtype: int or None
-        """
+        # type: () -> Optional[int]
+        """Specifies the customization status of the file."""
         return self.properties.get("CustomizedPageStatus", None)
 
     @property

office365/sharepoint/files/versions/collection.py

@@ -4,7 +4,7 @@ from office365.sharepoint.entity_collection import EntityCollection
 from office365.sharepoint.files.versions.version import FileVersion
 
 
-class FileVersionCollection(EntityCollection):
+class FileVersionCollection(EntityCollection[FileVersion]):
     """Represents a collection of FileVersion."""
 
     def __init__(self, context, resource_path=None):
@@ -17,6 +17,10 @@ class FileVersionCollection(EntityCollection):
             ServiceOperationPath("getById", [version_id], self.resource_path),
         )
 
+    def get_by_label(self, label):
+        """Gets the file version with the specified Label."""
+        return self.single("VersionLabel eq '{0}'".format(label))
+
     def delete_all(self):
         """Deletes all the file version objects in the collection."""
         qry = ServiceOperationQuery(self, "DeleteAll")
@@ -25,7 +29,6 @@ class FileVersionCollection(EntityCollection):
 
     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})
@@ -35,7 +38,6 @@ class FileVersionCollection(EntityCollection):
     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})

office365/sharepoint/files/versions/event.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 from office365.runtime.client_value_collection import ClientValueCollection
 from office365.sharepoint.entity import Entity
 from office365.sharepoint.sharing.shared_with_user import SharedWithUser
@@ -8,14 +10,14 @@ class FileVersionEvent(Entity):
 
     @property
     def event_type(self):
+        # type: () -> Optional[str]
         """Returns the type of the event."""
         return self.properties.get("EventType", None)
 
     @property
     def editor(self):
-        """Returns the name of the user who initiated the event.
-        :rtype: str or None
-        """
+        # type: () -> Optional[str]
+        """Returns the name of the user who initiated the event."""
         return self.properties.get("Editor", None)
 
     @property
@@ -25,6 +27,7 @@ class FileVersionEvent(Entity):
 
     @property
     def shared_with_users(self):
+        # type: () -> ClientValueCollection[SharedWithUser]
         """Returns the array of users that have been shared in sharing action for the change log."""
         return self.properties.get(
             "SharedWithUsers", ClientValueCollection(SharedWithUser)