Added support for List/Close File Handles APIs

Author: zezha-msft

azure-storage-file/ChangeLog.md

@@ -5,6 +5,7 @@
 ## Version XX.XX.XX:
 - Support for 2018-11-09 REST version. Please see our REST API documentation and blogs for information about the related added features.
 - Added an option to get share stats in bytes.
+- Added support for List/Close File Handles APIs.
 
 ## Version 1.4.0:
 

azure-storage-file/azure/storage/file/_deserialization.py

@@ -13,6 +13,7 @@
     Share,
     Directory,
     File,
+    Handle,
     FileProperties,
     FileRange,
     ShareProperties,
@@ -31,6 +32,7 @@
     _to_str,
 )
 
+
 def _parse_snapshot_share(response, name):
     '''
     Extracts snapshot return header.
@@ -39,6 +41,7 @@ def _parse_snapshot_share(response, name):
 
     return _parse_share(response, name, snapshot)
 
+
 def _parse_share(response, name, snapshot=None):
     if response is None:
         return None
@@ -197,6 +200,71 @@ def _convert_xml_to_directories_and_files(response):
     return entries
 
 
+def _convert_xml_to_handles(response):
+    """
+    <?xml version="1.0" encoding="utf-8"?>
+    <EnumerationResults>
+      <HandleList>
+        <Handle>
+          <HandleId>handle-id</HandleId>
+          <Path>file-or-directory-name-including-full-path</Path>
+          <FileId>file-id</FileId>
+          <ParentId>parent-file-id</ParentId>
+          <SessionId>session-id</SessionId>
+          <ClientIp>client-ip</ClientIp>
+          <OpenTime>opened-time</OpenTime>
+          <LastReconnectTime>lastreconnect-time</LastReconnectTime>
+        </Handle>
+        ...
+      </HandleList>
+      <NextMarker>next-marker</NextMarker>
+    </EnumerationResults>
+    """
+    if response is None or response.body is None:
+        return None
+
+    entries = _list()
+    list_element = ETree.fromstring(response.body)
+
+    # Set next marker
+    next_marker = list_element.findtext('NextMarker') or None
+    setattr(entries, 'next_marker', next_marker)
+
+    handles_list_element = list_element.find('Entries')
+
+    for handle_element in handles_list_element.findall('Handle'):
+        # Name element
+        handle = Handle()
+        handle.handle_id = handle_element.findtext('HandleId')
+        handle.path = handle_element.findtext('Path')
+        handle.file_id = handle_element.findtext('FileId')
+        handle.parent_id = handle_element.findtext('ParentId')
+        handle.session_id = handle_element.findtext('SessionId')
+        handle.client_ip = handle_element.findtext('ClientIp')
+        handle.open_time = parser.parse(handle_element.findtext('OpenTime'))
+
+        last_connect_time_string = handle_element.findtext('LastReconnectTime')
+        if last_connect_time_string is not None:
+            handle.last_reconnect_time = parser.parse(last_connect_time_string)
+
+        # Add file to list
+        entries.append(handle)
+
+    return entries
+
+
+def _parse_close_handle_response(response):
+    if response is None or response.body is None:
+        return 0
+
+    results = _list()
+    results.append(int(response.headers['x-ms-number-of-handles-closed']))
+
+    next_marker = None if 'x-ms-marker' not in response.headers else response.headers['x-ms-marker']
+    setattr(results, 'next_marker', next_marker)
+    return results
+
+
 def _convert_xml_to_ranges(response):
     '''
     <?xml version="1.0" encoding="utf-8"?>

azure-storage-file/azure/storage/file/fileservice.py

@@ -62,6 +62,8 @@
 from ._deserialization import (
     _convert_xml_to_shares,
     _convert_xml_to_directories_and_files,
+    _convert_xml_to_handles,
+    _parse_close_handle_response,
     _convert_xml_to_ranges,
     _convert_xml_to_share_stats,
     _parse_file,
@@ -898,7 +900,7 @@ def get_share_stats(self, share_name, timeout=None):
         }
 
         usage = self._perform_request(request, _convert_xml_to_share_stats)
-        return int(math.ceil(float(usage)/_GB))
+        return int(math.ceil(float(usage) / _GB))
 
     def get_share_stats_in_bytes(self, share_name, timeout=None):
         """
@@ -1259,6 +1261,187 @@ def _list_directories_and_files(self, share_name, directory_name=None,
         return self._perform_request(request, _convert_xml_to_directories_and_files,
                                      operation_context=_context)
 
+    def list_handles(self, share_name, directory_name=None, file_name=None, recursive=None,
+                     max_results=None, marker=None, snapshot=None, timeout=None):
+
+        """
+        Returns a generator to list opened handles on a directory or a file under the specified share.
+        The generator will lazily follow the continuation tokens returned by
+        the service and stop when all handles have been returned or
+        num_results is reached.
+
+        If num_results is specified and the share has more than that number of
+        files and directories, the generator will have a populated next_marker
+        field once it finishes. This marker can be used to create a new generator
+        if more results are desired.
+
+        :param str share_name:
+            Name of existing share.
+        :param str directory_name:
+            The path to the directory.
+        :param str file_name:
+            Name of existing file.
+        :param bool recursive:
+            Boolean that specifies if operation should apply to the directory specified in the URI,
+            its files, its subdirectories and their files.
+        :param int max_results:
+            Specifies the maximum number of handles taken on files and/or directories to return.
+            If the request does not specify max_results or specifies a value greater than 5,000,
+            the server will return up to 5,000 items.
+            Setting max_results to a value less than or equal to zero results in error response code 400 (Bad Request).
+        :param str marker:
+            An opaque continuation token. This value can be retrieved from the
+            next_marker field of a previous generator object if max_results was
+            specified and that generator has finished enumerating results. If
+            specified, this generator will begin returning results from the point
+            where the previous generator stopped.
+        :param str snapshot:
+            A string that represents the snapshot version, if applicable.
+        :param int timeout:
+            The timeout parameter is expressed in seconds.
+        """
+        operation_context = _OperationContext(location_lock=True)
+        args = (share_name, directory_name, file_name)
+        kwargs = {'marker': marker, 'max_results': max_results, 'timeout': timeout, 'recursive': recursive,
+                  '_context': operation_context, 'snapshot': snapshot}
+
+        resp = self._list_handles(*args, **kwargs)
+
+        return ListGenerator(resp, self._list_handles, args, kwargs)
+
+    def _list_handles(self, share_name, directory_name=None, file_name=None, recursive=None,
+                      marker=None, max_results=None, timeout=None, _context=None, snapshot=None):
+        """
+        Returns a list of the directories and files under the specified share.
+
+        :param str share_name:
+            Name of existing share.
+        :param str directory_name:
+            The path to the directory.
+        :param str file_name:
+            Name of existing file.
+        :param bool recursive:
+            Boolean that specifies if operation should apply to the directory specified in the URI,
+            its files, its subdirectories and their files.
+        :param str marker:
+            An opaque continuation token. This value can be retrieved from the
+            next_marker field of a previous generator object if max_results was
+            specified and that generator has finished enumerating results. If
+            specified, this generator will begin returning results from the point
+            where the previous generator stopped.
+        :param int max_results:
+            Specifies the maximum number of handles to return,
+            including all directory elements. If the request does not specify
+            max_results or specifies a value greater than 5,000, the server will
+            return up to 5,000 items. Setting max_results to a value less than
+            or equal to zero results in error response code 400 (Bad Request).
+        :param int timeout:
+            The timeout parameter is expressed in seconds.
+        :param str snapshot:
+            A string that represents the snapshot version, if applicable.
+        """
+        _validate_not_none('share_name', share_name)
+        request = HTTPRequest()
+        request.method = 'GET'
+        request.host_locations = self._get_host_locations()
+        request.path = _get_path(share_name, directory_name, file_name)
+        request.query = {
+            'comp': 'listhandles',
+            'marker': _to_str(marker),
+            'maxresults': _int_to_str(max_results),
+            'timeout': _int_to_str(timeout),
+            'sharesnapshot': _to_str(snapshot)
+        }
+        request.headers = {
+            'x-ms-recursive': _to_str(recursive)
+        }
+
+        return self._perform_request(request, _convert_xml_to_handles,
+                                     operation_context=_context)
+
+    def close_handles(self, share_name, directory_name=None, file_name=None, recursive=None,
+                      handle_id=None, marker=None, snapshot=None, timeout=None):
+
+        """
+        Returns a generator to close opened handles on a directory or a file under the specified share.
+        The generator will lazily follow the continuation tokens returned by
+        the service and stop when all handles have been closed.
+        The yielded values represent the number of handles that were closed.
+
+
+        :param str share_name:
+            Name of existing share.
+        :param str directory_name:
+            The path to the directory.
+        :param str file_name:
+            Name of existing file.
+        :param bool recursive:
+            Boolean that specifies if operation should apply to the directory specified in the URI,
+            its files, its subdirectories and their files.
+        :param str handle_id:
+            Required. Specifies handle ID opened on the file or directory to be closed.
+            Astrix (‘*’) is a wildcard that specifies all handles.
+        :param str marker:
+            An opaque continuation token. This value can be retrieved from the
+            next_marker field of a previous generator object if it has not finished closing handles. If
+            specified, this generator will begin closing handles from the point
+            where the previous generator stopped.
+        :param str snapshot:
+            A string that represents the snapshot version, if applicable.
+        :param int timeout:
+            The timeout parameter is expressed in seconds.
+        """
+        operation_context = _OperationContext(location_lock=True)
+        args = (share_name, directory_name, file_name)
+        kwargs = {'marker': marker, 'handle_id': handle_id, 'timeout': timeout, 'recursive': recursive,
+                  '_context': operation_context, 'snapshot': snapshot}
+
+        resp = self._close_handles(*args, **kwargs)
+
+        return ListGenerator(resp, self._close_handles, args, kwargs)
+
+    def _close_handles(self, share_name, directory_name=None, file_name=None, recursive=None, handle_id=None,
+                       marker=None, timeout=None, _context=None, snapshot=None):
+        """
+        Returns the number of handles that got closed.
+
+        :param str share_name:
+            Name of existing share.
+        :param str directory_name:
+            The path to the directory.
+        :param str file_name:
+            Name of existing file.
+        :param bool recursive:
+            Boolean that specifies if operation should apply to the directory specified in the URI,
+            its files, its subdirectories and their files.
+        :param str handle_id:
+            Required. Specifies handle ID opened on the file or directory to be closed.
+            Astrix (‘*’) is a wildcard that specifies all handles.
+        :param str marker:
+            Specifies the maximum number of handles taken on files and/or directories to return.
+        :param int timeout:
+            The timeout parameter is expressed in seconds.
+        :param str snapshot:
+            A string that represents the snapshot version, if applicable.
+        """
+        _validate_not_none('share_name', share_name)
+        request = HTTPRequest()
+        request.method = 'PUT'
+        request.host_locations = self._get_host_locations()
+        request.path = _get_path(share_name, directory_name, file_name)
+        request.query = {
+            'comp': 'forceclosehandles',
+            'marker': _to_str(marker),
+            'timeout': _int_to_str(timeout),
+            'sharesnapshot': _to_str(snapshot)
+        }
+        request.headers = {
+            'x-ms-recursive': _to_str(recursive),
+            'x-ms-handle-id': _to_str(handle_id),
+        }
+
+        return self._perform_request(request, _parse_close_handle_response, operation_context=_context)
+
     def get_file_properties(self, share_name, directory_name, file_name, timeout=None, snapshot=None):
         '''
         Returns all user-defined metadata, standard HTTP properties, and

azure-storage-file/azure/storage/file/models.py

@@ -153,6 +153,44 @@ def __init__(self):
         self.server_encrypted = None
 
 
+class Handle(object):
+    """
+    Represents a file handle.
+
+    :ivar str handle_id:
+        Used to identify handle.
+    :ivar str path:
+        Used to identify the name of the object for which the handle is open.
+    :ivar str file_id:
+        Uniquely identifies the file.
+        This is useful when renames are happening as the file ID does not change.
+    :ivar str parent_id:
+        Uniquely identifies the parent directory.
+        This is useful when renames are happening as the parent ID does not change.
+    :ivar str session_id:
+        Session ID in context of which the file handle was opened.
+    :ivar str client_ip:
+        Used to identify client that has opened the handle.
+        The field is included only if client IP is known by the service.
+    :ivar datetime open_time:
+        Used to decide if handle may have been leaked.
+    :ivar datetime last_reconnect_time:
+        Used to decide if handle was reopened after client/server disconnect due to networking or other faults.
+        The field is included only if disconnect event occurred and handle was reopened.
+    """
+
+    def __init__(self, handle_id=None, path=None, file_id=None, parent_id=None, session_id=None,
+                 client_ip=None, open_time=None, last_reconnect_time=None):
+        self.handle_id = handle_id
+        self.path = path
+        self.file_id = file_id
+        self.parent_id = parent_id
+        self.session_id = session_id
+        self.client_ip = client_ip
+        self.open_time = open_time
+        self.last_reconnect_time = last_reconnect_time
+
+
 class ContentSettings(object):
     '''
     Used to store the content settings of a file.