[Storage] [STG93 GA] APIView Feedback (#35331)

sdk/storage/azure-storage-blob/azure/storage/blob/_shared/models.py

@@ -453,19 +453,20 @@ def from_string(cls, permission):
 class Services(object):
     """Specifies the services accessible with the account SAS.
 
-    :param bool blob:
-        Access for the `~azure.storage.blob.BlobServiceClient`
-    :param bool queue:
-        Access for the `~azure.storage.queue.QueueServiceClient`
-    :param bool fileshare:
-        Access for the `~azure.storage.fileshare.ShareServiceClient`
+    :keyword bool blob:
+        Access for the `~azure.storage.blob.BlobServiceClient`. Default is False.
+    :keyword bool queue:
+        Access for the `~azure.storage.queue.QueueServiceClient`. Default is False.
+    :keyword bool fileshare:
+        Access for the `~azure.storage.fileshare.ShareServiceClient`. Default is False.
     """
 
-    blob: bool = False
-    queue: bool = False
-    fileshare: bool = False
-
-    def __init__(self, blob: bool = False, queue: bool = False, fileshare: bool = False):
+    def __init__(
+        self, *,
+        blob: bool = False,
+        queue: bool = False,
+        fileshare: bool = False
+    ) -> None:
         self.blob = blob
         self.queue = queue
         self.fileshare = fileshare
@@ -493,7 +494,7 @@ def from_string(cls, string):
         res_queue = 'q' in string
         res_file = 'f' in string
 
-        parsed = cls(res_blob, res_queue, res_file)
+        parsed = cls(blob=res_blob, queue=res_queue, fileshare=res_file)
         parsed._str = string  # pylint: disable = protected-access
         return parsed
 

sdk/storage/azure-storage-file-datalake/azure/storage/filedatalake/_data_lake_directory_client.py

@@ -297,14 +297,12 @@ def get_directory_properties(self, **kwargs):
             Use of customer-provided keys must be done over HTTPS.
             Required if the directory was created with a customer-provided key.
         :keyword bool upn:
-            Optional. Valid only when Hierarchical Namespace is
-            enabled for the account. If "True", the user identity values returned
-            in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be
-            transformed from Azure Active Directory Object IDs to User Principal
-            Names. If "False", the values will be returned as Azure Active
-            Directory Object IDs. The default value is false. Note that group and
-            application Object IDs are not translated because they do not have
-            unique friendly names.
+            If True, the user identity values returned in the x-ms-owner, x-ms-group,
+            and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User
+            Principal Names in the owner, group, and acl fields of
+            :class:`~azure.storage.filedatalake.DirectoryProperties`. If False, the values will be returned
+            as Azure Active Directory Object IDs. The default value is False. Note that group and application
+            Object IDs are not translate because they do not have unique friendly names.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.

sdk/storage/azure-storage-file-datalake/azure/storage/filedatalake/_data_lake_file_client.py

@@ -315,22 +315,20 @@ def get_file_properties(self, **kwargs):
             Use of customer-provided keys must be done over HTTPS.
             Required if the file was created with a customer-provided key.
         :keyword bool upn:
-            Optional. Valid only when Hierarchical Namespace is
-            enabled for the account. If "True", the user identity values returned
-            in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be
-            transformed from Azure Active Directory Object IDs to User Principal
-            Names. If "False", the values will be returned as Azure Active
-            Directory Object IDs. The default value is false. Note that group and
-            application Object IDs are not translated because they do not have
-            unique friendly names.
+            If True, the user identity values returned in the x-ms-owner, x-ms-group,
+            and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User
+            Principal Names in the owner, group, and acl fields of
+            :class:`~azure.storage.filedatalake.FileProperties`. If False, the values will be returned
+            as Azure Active Directory Object IDs. The default value is False. Note that group and application
+            Object IDs are not translate because they do not have unique friendly names.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-file-datalake
             #other-client--per-operation-configuration>`_.
         :returns: All user-defined metadata, standard HTTP properties, and system properties for the file.
-        :rtype: FileProperties
+        :rtype: ~azure.storage.filedatalake.FileProperties
 
         .. admonition:: Example:
 

sdk/storage/azure-storage-file-datalake/azure/storage/filedatalake/_file_system_client.py

@@ -569,14 +569,12 @@ def get_paths(
             number of items to return per page. If omitted or greater than 5,000, the
             response will include up to 5,000 items per page.
         :keyword bool upn:
-            Optional. Valid only when Hierarchical Namespace is
-            enabled for the account. If "True", the user identity values returned
-            in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be
-            transformed from Azure Active Directory Object IDs to User Principal
-            Names. If "False", the values will be returned as Azure Active
-            Directory Object IDs. The default value is false. Note that group and
-            application Object IDs are not translated because they do not have
-            unique friendly names.
+            If True, the user identity values returned in the x-ms-owner, x-ms-group,
+            and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User
+            Principal Names in the owner, group, and acl fields of
+            :class:`~azure.storage.filedatalake.PathProperties`. If False, the values will be returned
+            as Azure Active Directory Object IDs. The default value is False. Note that group and application
+            Object IDs are not translate because they do not have unique friendly names.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.

sdk/storage/azure-storage-file-datalake/azure/storage/filedatalake/_path_client.py

@@ -929,14 +929,12 @@ def _get_path_properties(self, **kwargs):
             Use of customer-provided keys must be done over HTTPS.
             Required if the file/directory was created with a customer-provided key.
         :keyword bool upn:
-            Optional. Valid only when Hierarchical Namespace is
-            enabled for the account. If "True", the user identity values returned
-            in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be
-            transformed from Azure Active Directory Object IDs to User Principal
-            Names. If "False", the values will be returned as Azure Active
-            Directory Object IDs. The default value is false. Note that group and
-            application Object IDs are not translated because they do not have
-            unique friendly names.
+            If True, the user identity values returned in the x-ms-owner, x-ms-group,
+            and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User 
+            Principal Names in the owner, group, and acl fields of the respective property object returned.
+            If False, the values will be returned as Azure Active Directory Object IDs.
+            The default value is False. Note that group and application Object IDs are not translate
+            because they do not have unique friendly names.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.

sdk/storage/azure-storage-file-datalake/azure/storage/filedatalake/_shared/models.py

@@ -453,19 +453,20 @@ def from_string(cls, permission):
 class Services(object):
     """Specifies the services accessible with the account SAS.
 
-    :param bool blob:
-        Access for the `~azure.storage.blob.BlobServiceClient`
-    :param bool queue:
-        Access for the `~azure.storage.queue.QueueServiceClient`
-    :param bool fileshare:
-        Access for the `~azure.storage.fileshare.ShareServiceClient`
+    :keyword bool blob:
+        Access for the `~azure.storage.blob.BlobServiceClient`. Default is False.
+    :keyword bool queue:
+        Access for the `~azure.storage.queue.QueueServiceClient`. Default is False.
+    :keyword bool fileshare:
+        Access for the `~azure.storage.fileshare.ShareServiceClient`. Default is False.
     """
 
-    blob: bool = False
-    queue: bool = False
-    fileshare: bool = False
-
-    def __init__(self, blob: bool = False, queue: bool = False, fileshare: bool = False):
+    def __init__(
+        self, *,
+        blob: bool = False,
+        queue: bool = False,
+        fileshare: bool = False
+    ) -> None:
         self.blob = blob
         self.queue = queue
         self.fileshare = fileshare
@@ -493,7 +494,7 @@ def from_string(cls, string):
         res_queue = 'q' in string
         res_file = 'f' in string
 
-        parsed = cls(res_blob, res_queue, res_file)
+        parsed = cls(blob=res_blob, queue=res_queue, fileshare=res_file)
         parsed._str = string  # pylint: disable = protected-access
         return parsed
 

sdk/storage/azure-storage-file-datalake/azure/storage/filedatalake/aio/_data_lake_directory_client_async.py

@@ -273,14 +273,12 @@ async def get_directory_properties(self, **kwargs):
             Use of customer-provided keys must be done over HTTPS.
             Required if the directory was created with a customer-provided key.
         :keyword bool upn:
-            Optional. Valid only when Hierarchical Namespace is
-            enabled for the account. If "True", the user identity values returned
-            in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be
-            transformed from Azure Active Directory Object IDs to User Principal
-            Names. If "False", the values will be returned as Azure Active
-            Directory Object IDs. The default value is false. Note that group and
-            application Object IDs are not translated because they do not have
-            unique friendly names.
+            If True, the user identity values returned in the x-ms-owner, x-ms-group,
+            and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User
+            Principal Names in the owner, group, and acl fields of
+            :class:`~azure.storage.filedatalake.DirectoryProperties`. If False, the values will be returned
+            as Azure Active Directory Object IDs. The default value is False. Note that group and application
+            Object IDs are not translate because they do not have unique friendly names.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.

sdk/storage/azure-storage-file-datalake/azure/storage/filedatalake/aio/_data_lake_file_client_async.py

@@ -281,22 +281,20 @@ async def get_file_properties(self, **kwargs):
             Use of customer-provided keys must be done over HTTPS.
             Required if the file was created with a customer-provided key.
         :keyword bool upn:
-            Optional. Valid only when Hierarchical Namespace is
-            enabled for the account. If "True", the user identity values returned
-            in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be
-            transformed from Azure Active Directory Object IDs to User Principal
-            Names. If "False", the values will be returned as Azure Active
-            Directory Object IDs. The default value is false. Note that group and
-            application Object IDs are not translated because they do not have
-            unique friendly names.
+            If True, the user identity values returned in the x-ms-owner, x-ms-group,
+            and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User
+            Principal Names in the owner, group, and acl fields of
+            :class:`~azure.storage.filedatalake.FileProperties`. If False, the values will be returned
+            as Azure Active Directory Object IDs. The default value is False. Note that group and application
+            Object IDs are not translate because they do not have unique friendly names.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.
             This value is not tracked or validated on the client. To configure client-side network timesouts
             see `here <https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/storage/azure-storage-file-datalake
             #other-client--per-operation-configuration>`_.
         :returns: All user-defined metadata, standard HTTP properties, and system properties for the file.
-        :rtype: FileProperties
+        :rtype: ~azure.storage.filedatalake.FileProperties
 
         .. admonition:: Example:
 

sdk/storage/azure-storage-file-datalake/azure/storage/filedatalake/aio/_file_system_client_async.py

@@ -511,14 +511,12 @@ def get_paths(
             number of items to return per page. If omitted or greater than 5,000, the
             response will include up to 5,000 items per page.
         :keyword bool upn:
-            Optional. Valid only when Hierarchical Namespace is
-            enabled for the account. If "True", the user identity values returned
-            in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be
-            transformed from Azure Active Directory Object IDs to User Principal
-            Names. If "False", the values will be returned as Azure Active
-            Directory Object IDs. The default value is false. Note that group and
-            application Object IDs are not translated because they do not have
-            unique friendly names.
+            If True, the user identity values returned in the x-ms-owner, x-ms-group,
+            and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User
+            Principal Names in the owner, group, and acl fields of
+            :class:`~azure.storage.filedatalake.PathProperties`. If False, the values will be returned
+            as Azure Active Directory Object IDs. The default value is False. Note that group and application
+            Object IDs are not translate because they do not have unique friendly names.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.

sdk/storage/azure-storage-file-datalake/azure/storage/filedatalake/aio/_path_client_async.py

@@ -718,14 +718,12 @@ async def _get_path_properties(self, **kwargs):
             Use of customer-provided keys must be done over HTTPS.
             Required if the file/directory was created with a customer-provided key.
         :keyword bool upn:
-            Optional. Valid only when Hierarchical Namespace is
-            enabled for the account. If "True", the user identity values returned
-            in the x-ms-owner, x-ms-group, and x-ms-acl response headers will be
-            transformed from Azure Active Directory Object IDs to User Principal
-            Names. If "False", the values will be returned as Azure Active
-            Directory Object IDs. The default value is false. Note that group and
-            application Object IDs are not translated because they do not have
-            unique friendly names.
+            If True, the user identity values returned in the x-ms-owner, x-ms-group,
+            and x-ms-acl response headers will be transformed from Azure Active Directory Object IDs to User 
+            Principal Names in the owner, group, and acl fields of the respective property object returned.
+            If False, the values will be returned as Azure Active Directory Object IDs.
+            The default value is False. Note that group and application Object IDs are not translate
+            because they do not have unique friendly names.
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations.

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

@@ -718,7 +718,7 @@ def start_copy_from_url(self, source_url, **kwargs):
 
         :keyword metadata:
             Name-value pairs associated with the file as metadata.
-        :type metadata: dict[str, str]
+        :paramtype metadata: dict[str, str]
         :keyword lease:
             Required if the file has an active lease. Value can be a ShareLeaseClient object
             or the lease ID as a string.

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

@@ -349,8 +349,9 @@ def create_share(self, **kwargs):
         """Creates a new Share under the account. If a share with the
         same name already exists, the operation fails.
 
-        :keyword dict[str, str] metadata:
+        :keyword metadata:
             Name-value pairs associated with the share as metadata.
+        :paramtype metadata: dict[str, str]
         :keyword int quota:
             The quota to be allotted.
         :keyword access_tier:
@@ -428,8 +429,9 @@ def create_snapshot( # type: ignore
         is taken, with a DateTime value appended to indicate the time at which the
         snapshot was taken.
 
-        :keyword dict[str, str] metadata:
+        :keyword metadata:
             Name-value pairs associated with the share as metadata.
+        :paramtype metadata: dict[str, str]
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations.
@@ -470,7 +472,9 @@ def delete_share(
         later deleted during garbage collection.
 
         :param delete_snapshots:
-            Indicates if snapshots are to be deleted.
+            Indicates if snapshots are to be deleted. If "True" or enum "include", snapshots will
+            be deleted (but not include leased). To include leased snapshots, specify the "include-leased"
+            enum.
         :type delete_snapshots:
             Optional[Union[bool, Literal['include', 'include-leased']]]
         :keyword lease:
@@ -978,7 +982,7 @@ def create_directory(self, directory_name, **kwargs):
             The name of the directory.
         :keyword metadata:
             Name-value pairs associated with the directory as metadata.
-        :type metadata: dict[str, str]
+        :paramtype metadata: dict[str, str]
         :keyword int timeout:
             Sets the server-side timeout for the operation in seconds. For more details see
             https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-file-service-operations.