[Storage] [STG 104] NFS List V2 Files and Directories

sdk/storage/azure-storage-file-share/CHANGELOG.md

@@ -7,6 +7,9 @@
 `FileRange` and support continuation tokens and `results_per_page` for enumerating file ranges across multiple
 service responses.
 - Added a new `FileRange` model with `start`, `end`, and `cleared` properties.
+- Added support for listing NFS files, directories, and special file types (symbolic links, block devices,
+character devices, FIFOs, and sockets) via `list_directories_and_files`. The `include` keyword now accepts
+the values `"Permissions"`, `"LinkCount"`, `"NfsAttributes"`, and `"All"`.
 
 ### Other Changes
 - Deprecated `ShareFileClient`'s `get_ranges` and `get_ranges_diff` APIs in favor of `list_ranges` and

sdk/storage/azure-storage-file-share/api.md

@@ -290,6 +290,7 @@ namespace azure.storage.fileshare
         last_access_time: Optional[datetime]
         last_modified: datetime
         last_write_time: Optional[Union[datetime, str]]
+        link_count: Optional[int]
         metadata: Dict[str, str]
         name: str
         nfs_file_type: Optional[Literal["Directory"]]
@@ -386,6 +387,8 @@ namespace azure.storage.fileshare
         content_settings: ContentSettings
         copy: CopyProperties
         creation_time: Optional[Union[datetime, str]]
+        device_major: Optional[int]
+        device_minor: Optional[int]
         etag: str
         file_attributes: Union[str, NTFSAttributes]
         file_id: str
@@ -398,9 +401,10 @@ namespace azure.storage.fileshare
         last_write_time: Optional[Union[datetime, str]]
         lease: LeaseProperties
         link_count: Optional[int]
+        link_text: Optional[str]
         metadata: Dict[str, str]
         name: str
-        nfs_file_type: Optional[Literal["Regular"]]
+        nfs_file_type: Optional[Literal["Regular", "SymLink", "BlockDevice", "CharacterDevice", "Socket", "Fifo"]]
         owner: Optional[str]
         parent_id: Optional[str]
         path: Optional[str]
@@ -455,6 +459,62 @@ namespace azure.storage.fileshare
         def values(self): ...
 
 
+    class azure.storage.fileshare.FileRange(DictMixin):
+        cleared: bool
+        end: int
+        start: int
+
+        def __contains__(self, key): ...
+
+        def __delitem__(self, key): ...
+
+        def __eq__(self, other): ...
+
+        def __getitem__(self, key): ...
+
+        def __init__(
+                self, 
+                start: int, 
+                end: int, 
+                *, 
+                cleared: bool = False
+            ) -> None: ...
+
+        def __len__(self): ...
+
+        def __ne__(self, other): ...
+
+        def __repr__(self): ...
+
+        def __setitem__(
+                self, 
+                key, 
+                item
+            ): ...
+
+        def __str__(self): ...
+
+        def get(
+                self, 
+                key, 
+                default = None
+            ): ...
+
+        def has_key(self, k): ...
+
+        def items(self): ...
+
+        def keys(self): ...
+
+        def update(
+                self, 
+                *args, 
+                **kwargs
+            ): ...
+
+        def values(self): ...
+
+
     class azure.storage.fileshare.FileSasPermissions:
         create: bool = False
         delete: bool = False
@@ -1510,6 +1570,32 @@ namespace azure.storage.fileshare
                 **kwargs: Any
             ) -> ItemPaged[Handle]: ...
 
+        @distributed_trace
+        def list_ranges(
+                self, 
+                *, 
+                lease: Union[ShareLeaseClient, str] = ..., 
+                length: Optional[int] = ..., 
+                offset: Optional[int] = ..., 
+                results_per_page: Optional[int] = ..., 
+                timeout: Optional[int] = ..., 
+                **kwargs: Any
+            ) -> ItemPaged[FileRange]: ...
+
+        @distributed_trace
+        def list_ranges_diff(
+                self, 
+                previous_sharesnapshot: Union[str, Dict[str, Any]], 
+                *, 
+                include_renames: Optional[bool] = ..., 
+                lease: Union[ShareLeaseClient, str] = ..., 
+                length: Optional[int] = ..., 
+                offset: Optional[int] = ..., 
+                results_per_page: Optional[int] = ..., 
+                timeout: Optional[int] = ..., 
+                **kwargs: Any
+            ) -> ItemPaged[FileRange]: ...
+
         @distributed_trace
         def rename_file(
                 self, 
@@ -3067,6 +3153,32 @@ namespace azure.storage.fileshare.aio
                 **kwargs: Any
             ) -> AsyncItemPaged[Handle]: ...
 
+        @distributed_trace
+        def list_ranges(
+                self, 
+                *, 
+                lease: Union[ShareLeaseClient, str] = ..., 
+                length: Optional[int] = ..., 
+                offset: Optional[int] = ..., 
+                results_per_page: Optional[int] = ..., 
+                timeout: Optional[int] = ..., 
+                **kwargs: Any
+            ) -> AsyncItemPaged[FileRange]: ...
+
+        @distributed_trace
+        def list_ranges_diff(
+                self, 
+                previous_sharesnapshot: Union[str, Dict[str, Any]], 
+                *, 
+                include_renames: Optional[bool] = ..., 
+                lease: Union[ShareLeaseClient, str] = ..., 
+                length: Optional[int] = ..., 
+                offset: Optional[int] = ..., 
+                results_per_page: Optional[int] = ..., 
+                timeout: Optional[int] = ..., 
+                **kwargs: Any
+            ) -> AsyncItemPaged[FileRange]: ...
+
         @distributed_trace_async
         async def rename_file(
                 self, 

sdk/storage/azure-storage-file-share/api.metadata.yml

@@ -1,3 +1,3 @@
-apiMdSha256: 3c2f71c139d0f1e3430e1f6802e9b27f9940c011b1da95748721350c53a0c6f8
+apiMdSha256: 541db07d93195aaab2f93a873a1cecbfa6dd0133b2165cfa5a4f5e874c5aaf71
 parserVersion: 0.3.28
 pythonVersion: 3.13.14

sdk/storage/azure-storage-file-share/azure/apiview-properties.json

@@ -2,11 +2,14 @@
     "CrossLanguagePackageId": null,
     "CrossLanguageDefinitionId": {
         "azure.storage.fileshare.models.AccessPolicy": null,
+        "azure.storage.fileshare.models.BlockDeviceItem": null,
+        "azure.storage.fileshare.models.CharDeviceItem": null,
         "azure.storage.fileshare.models.ClearRange": null,
         "azure.storage.fileshare.models.CopyFileSmbInfo": null,
         "azure.storage.fileshare.models.CorsRule": null,
         "azure.storage.fileshare.models.DestinationLeaseAccessConditions": null,
         "azure.storage.fileshare.models.DirectoryItem": null,
+        "azure.storage.fileshare.models.FifoItem": null,
         "azure.storage.fileshare.models.FileHTTPHeaders": null,
         "azure.storage.fileshare.models.FileItem": null,
         "azure.storage.fileshare.models.FileProperty": null,
@@ -32,23 +35,25 @@
         "azure.storage.fileshare.models.ShareStats": null,
         "azure.storage.fileshare.models.SignedIdentifier": null,
         "azure.storage.fileshare.models.SmbMultichannel": null,
+        "azure.storage.fileshare.models.SocketItem": null,
         "azure.storage.fileshare.models.SourceLeaseAccessConditions": null,
         "azure.storage.fileshare.models.SourceModifiedAccessConditions": null,
         "azure.storage.fileshare.models.StorageError": null,
         "azure.storage.fileshare.models.StorageServiceProperties": null,
         "azure.storage.fileshare.models.StringEncoded": null,
+        "azure.storage.fileshare.models.SymLinkItem": null,
         "azure.storage.fileshare.models.UserDelegationKey": null,
         "azure.storage.fileshare.models.ListSharesIncludeType": null,
         "azure.storage.fileshare.models.LeaseStatusType": null,
         "azure.storage.fileshare.models.LeaseStateType": null,
         "azure.storage.fileshare.models.LeaseDurationType": null,
         "azure.storage.fileshare.models.ShareRootSquash": null,
         "azure.storage.fileshare.models.ListFilesIncludeType": null,
+        "azure.storage.fileshare.models.NfsFileType": null,
         "azure.storage.fileshare.models.AccessRight": null,
         "azure.storage.fileshare.models.ShareTokenIntent": null,
         "azure.storage.fileshare.models.ShareAccessTier": null,
         "azure.storage.fileshare.models.FilePropertySemantics": null,
-        "azure.storage.fileshare.models.NfsFileType": null,
         "azure.storage.fileshare.models.StorageErrorCode": null,
         "azure.storage.fileshare.models.PermissionCopyModeType": null,
         "azure.storage.fileshare.models.FilePermissionFormat": null,

sdk/storage/azure-storage-file-share/azure/storage/fileshare/_directory_client.py

@@ -581,7 +581,10 @@ def list_directories_and_files(
             begin with the specified prefix.
         :keyword List[str] include:
             Include this parameter to specify one or more datasets to include in the response.
-            Possible str values are "timestamps", "Etag", "Attributes", "PermissionKey".
+            Possible str values are "timestamps", "Etag", "Attributes", "PermissionKey",
+            "Permissions", "LinkCount", "NfsAttributes", and "All".
+            The values "Permissions", "LinkCount", "NfsAttributes", and "All" apply to NFS shares,
+            with the exception of "All" which can also be used on SMB shares.
 
             .. versionadded:: 12.6.0
 

sdk/storage/azure-storage-file-share/azure/storage/fileshare/_generated/aio/operations/_file_operations.py

@@ -153,7 +153,8 @@ async def create(  # pylint: disable=too-many-locals
          None.
         :type file_mode: str
         :param nfs_file_type: Optional, NFS only. Type of the file or directory. Known values are:
-         "Regular", "Directory", and "SymLink". Default value is None.
+         "Regular", "Directory", "SymLink", "BlockDevice", "CharacterDevice", "Socket", and "Fifo".
+         Default value is None.
         :type nfs_file_type: str or ~azure.storage.fileshare.models.NfsFileType
         :param content_md5: An MD5 hash of the content. This hash is used to verify the integrity of
          the data during transport. When the Content-MD5 header is specified, the File service compares
@@ -1576,8 +1577,6 @@ async def get_range_list(
         timeout: Optional[int] = None,
         range: Optional[str] = None,
         support_rename: Optional[bool] = None,
-        marker: Optional[str] = None,
-        maxresults: Optional[int] = None,
         lease_access_conditions: Optional[_models.LeaseAccessConditions] = None,
         **kwargs: Any
     ) -> _models.ShareFileRangeList:
@@ -1604,15 +1603,6 @@ async def get_range_list(
          operation will result in a failure with 409 (Conflict) response. The default value is false.
          Default value is None.
         :type support_rename: bool
-        :param marker: A string value that identifies the portion of the list to be returned with the
-         next list operation. The operation returns a marker value within the response body if the list
-         returned was not complete. The marker value may then be used in a subsequent call to request
-         the next set of list items. The marker value is opaque to the client. Default value is None.
-        :type marker: str
-        :param maxresults: Specifies the maximum number of entries to return. If the request does not
-         specify maxresults, or specifies a value greater than 5,000, the server will return up to 5,000
-         items. Default value is None.
-        :type maxresults: int
         :param lease_access_conditions: Parameter group. Default value is None.
         :type lease_access_conditions: ~azure.storage.fileshare.models.LeaseAccessConditions
         :return: ShareFileRangeList or the result of cls(response)
@@ -1646,8 +1636,6 @@ async def get_range_list(
             range=range,
             lease_id=_lease_id,
             support_rename=support_rename,
-            marker=marker,
-            maxresults=maxresults,
             allow_trailing_dot=self._config.allow_trailing_dot,
             file_request_intent=self._config.file_request_intent,
             comp=comp,

sdk/storage/azure-storage-file-share/azure/storage/fileshare/_generated/models/__init__.py

@@ -15,11 +15,14 @@
 
 from ._models_py3 import (  # type: ignore
     AccessPolicy,
+    BlockDeviceItem,
+    CharDeviceItem,
     ClearRange,
     CopyFileSmbInfo,
     CorsRule,
     DestinationLeaseAccessConditions,
     DirectoryItem,
+    FifoItem,
     FileHTTPHeaders,
     FileItem,
     FileProperty,
@@ -45,11 +48,13 @@
     ShareStats,
     SignedIdentifier,
     SmbMultichannel,
+    SocketItem,
     SourceLeaseAccessConditions,
     SourceModifiedAccessConditions,
     StorageError,
     StorageServiceProperties,
     StringEncoded,
+    SymLinkItem,
     UserDelegationKey,
 )
 
@@ -81,11 +86,14 @@
 
 __all__ = [
     "AccessPolicy",
+    "BlockDeviceItem",
+    "CharDeviceItem",
     "ClearRange",
     "CopyFileSmbInfo",
     "CorsRule",
     "DestinationLeaseAccessConditions",
     "DirectoryItem",
+    "FifoItem",
     "FileHTTPHeaders",
     "FileItem",
     "FileProperty",
@@ -111,11 +119,13 @@
     "ShareStats",
     "SignedIdentifier",
     "SmbMultichannel",
+    "SocketItem",
     "SourceLeaseAccessConditions",
     "SourceModifiedAccessConditions",
     "StorageError",
     "StorageServiceProperties",
     "StringEncoded",
+    "SymLinkItem",
     "UserDelegationKey",
     "AccessRight",
     "CopyStatusType",

sdk/storage/azure-storage-file-share/azure/storage/fileshare/_generated/models/_azure_file_storage_enums.py

@@ -93,6 +93,10 @@ class ListFilesIncludeType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
     ETAG = "Etag"
     ATTRIBUTES = "Attributes"
     PERMISSION_KEY = "PermissionKey"
+    PERMISSIONS = "Permissions"
+    LINK_COUNT = "LinkCount"
+    NFS_ATTRIBUTES = "NfsAttributes"
+    ALL = "All"
 
 
 class ListSharesIncludeType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
@@ -111,11 +115,15 @@ class ModeCopyMode(str, Enum, metaclass=CaseInsensitiveEnumMeta):
 
 
 class NfsFileType(str, Enum, metaclass=CaseInsensitiveEnumMeta):
-    """NfsFileType."""
+    """Type of the file."""
 
     REGULAR = "Regular"
     DIRECTORY = "Directory"
     SYM_LINK = "SymLink"
+    BLOCK_DEVICE = "BlockDevice"
+    CHARACTER_DEVICE = "CharacterDevice"
+    SOCKET = "Socket"
+    FIFO = "Fifo"
 
 
 class OwnerCopyMode(str, Enum, metaclass=CaseInsensitiveEnumMeta):