Skip to content

Doc imprvment for Storage #7601

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lmazuel merged 7 commits into from
Oct 4, 2019
Merged

Doc imprvment for Storage #7601

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1d30e04
Docstring improvement
lmazuel Oct 3, 2019
5b86644
File docstring
lmazuel Oct 3, 2019
1af4232
Queue docstrings
lmazuel Oct 4, 2019
5ebe4e1
Merge remote-tracking branch 'upstream/feature/storage-preview4' into…
lmazuel Oct 4, 2019
c4bbc5c
More doc fixes
lmazuel Oct 4, 2019
6f4932d
More doc fixes
lmazuel Oct 4, 2019
d8cfca1
Merge remote-tracking branch 'origin/feature/storage-preview4' into d…
lmazuel Oct 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
File docstring
  • Loading branch information
@lmazuel
lmazuel committed Oct 3, 2019
commit 5b86644ea00adc31c227a00d314876bfe4a78cd2
14 changes: 7 additions & 7 deletions sdk/storage/azure-storage-file/azure/storage/file/aio/directory_client_async.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ class DirectoryClient(AsyncStorageAccountHostsMixin, DirectoryClientBase):
or share, in which case the directory and/or share must also be specified.
:param share: The share for the directory. If specified, this value will override
a share value specified in the directory URL.
:type share: str or ~azure.storage.file.models.ShareProperties
:type share: str or ~azure.storage.file.ShareProperties
:param str directory_path:
The directory path for the directory with which to interact.
If specified, this value will override a directory value specified in the directory URL.
Expand Down Expand Up @@ -213,7 +213,7 @@ def list_directories_and_files(self, name_starts_with=None, timeout=None, **kwar
:param int timeout:
The timeout parameter is expressed in seconds.
:returns: An auto-paging iterable of dict-like DirectoryProperties and FileProperties
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.storage.file.models.DirectoryProperties]
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.storage.file.DirectoryProperties]

.. admonition:: Example:

Expand Down Expand Up @@ -245,7 +245,7 @@ def list_handles(self, recursive=False, timeout=None, **kwargs):
:param int timeout:
The timeout parameter is expressed in seconds.
:returns: An auto-paging iterable of HandleItems
:rtype: ~azure.storage.file.models.HandlesPaged
:rtype: ~azure.storage.file.HandlesPaged
"""
results_per_page = kwargs.pop('results_per_page', None)
command = functools.partial(
Expand Down Expand Up @@ -274,7 +274,7 @@ async def close_handles(
:param handle:
Optionally, a specific handle to close. The default value is '*'
which will attempt to close all open handles.
:type handle: str or ~azure.storage.file.models.Handle
:type handle: str or ~azure.storage.file.Handle
:param bool recursive:
Boolean that specifies if operation should apply to the directory specified by the client,
its files, its subdirectories and their files. Default value is False.
Expand Down Expand Up @@ -317,7 +317,7 @@ async def get_directory_properties(self, timeout=None, **kwargs):
:param int timeout:
The timeout parameter is expressed in seconds.
:returns: DirectoryProperties
:rtype: ~azure.storage.file.models.DirectoryProperties
:rtype: ~azure.storage.file.DirectoryProperties
"""
try:
response = await self._client.directory.get_properties(
Expand Down Expand Up @@ -373,7 +373,7 @@ async def set_http_headers(self, file_attributes="none", # type: Union[str, NTF
The file system attributes for files and directories.
If not set, indicates preservation of existing values.
Here is an example for when the var type is str: 'Temporary|Archive'
:type file_attributes: str or :class:`~azure.storage.file.models.NTFSAttributes`
:type file_attributes: str or :class:`~azure.storage.file.NTFSAttributes`
:param file_creation_time: Creation time for the file
Default value: Now.
:type file_creation_time: str or datetime
Expand Down Expand Up @@ -495,7 +495,7 @@ async def upload_file(
:param metadata:
Name-value pairs associated with the file as metadata.
:type metadata: dict(str, str)
:param ~azure.storage.file.models.ContentSettings content_settings:
:param ~azure.storage.file.ContentSettings content_settings:
ContentSettings object used to set file properties.
:param bool validate_content:
If true, calculates an MD5 hash for each range of the file. The storage
Expand Down
22 changes: 11 additions & 11 deletions sdk/storage/azure-storage-file/azure/storage/file/aio/file_client_async.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ class FileClient(AsyncStorageAccountHostsMixin, FileClientBase):
or share, in which case the file and/or share must also be specified.
:param share: The share for the file. If specified, this value will override
a share value specified in the file URL.
:type share: str or ~azure.storage.file.models.ShareProperties
:type share: str or ~azure.storage.file.ShareProperties
:param str file_path:
The file path to the file with which to interact. If specified, this value will override
a file value specified in the file URL.
Expand Down Expand Up @@ -162,7 +162,7 @@ async def create_file( # type: ignore

:param int size: Specifies the maximum size for the file,
up to 1 TB.
:param ~azure.storage.file.models.ContentSettings content_settings:
:param ~azure.storage.file.ContentSettings content_settings:
ContentSettings object used to set file properties.
:param metadata:
Name-value pairs associated with the file as metadata.
Expand All @@ -174,7 +174,7 @@ async def create_file( # type: ignore
If not set, the default value would be "None" and the attributes will be set to "Archive".
Here is an example for when the var type is str: 'Temporary|Archive'.
file_attributes value is not case sensitive.
:type file_attributes: str or :class:`~azure.storage.file.models.NTFSAttributes`
:type file_attributes: str or :class:`~azure.storage.file.NTFSAttributes`
:param file_creation_time: Creation time for the file
Default value: Now.
:type file_creation_time: str or datetime
Expand Down Expand Up @@ -265,7 +265,7 @@ async def upload_file(
:param metadata:
Name-value pairs associated with the file as metadata.
:type metadata: dict(str, str)
:param ~azure.storage.file.models.ContentSettings content_settings:
:param ~azure.storage.file.ContentSettings content_settings:
ContentSettings object used to set file properties.
:param bool validate_content:
If true, calculates an MD5 hash for each range of the file. The storage
Expand All @@ -285,7 +285,7 @@ async def upload_file(
If not set, the default value would be "None" and the attributes will be set to "Archive".
Here is an example for when the var type is str: 'Temporary|Archive'.
file_attributes value is not case sensitive.
:type file_attributes: str or :class:`~azure.storage.file.models.NTFSAttributes`
:type file_attributes: str or :class:`~azure.storage.file.NTFSAttributes`
:param file_creation_time: Creation time for the file
Default value: Now.
:type file_creation_time: str or datetime
Expand Down Expand Up @@ -406,7 +406,7 @@ async def abort_copy(self, copy_id, timeout=None, **kwargs):
:param copy_id:
The copy operation to abort. This can be either an ID, or an
instance of FileProperties.
:type copy_id: str or ~azure.storage.file.models.FileProperties
:type copy_id: str or ~azure.storage.file.FileProperties
:rtype: None
"""
try:
Expand Down Expand Up @@ -515,7 +515,7 @@ async def get_file_properties(self, timeout=None, **kwargs):
:param int timeout:
The timeout parameter is expressed in seconds.
:returns: FileProperties
:rtype: ~azure.storage.file.models.FileProperties
:rtype: ~azure.storage.file.FileProperties
"""
try:
file_props = await self._client.file.get_properties(
Expand All @@ -542,15 +542,15 @@ async def set_http_headers(self, content_settings, # type: ContentSettings
# type: (ContentSettings, Optional[int], Optional[Any]) -> Dict[str, Any]
"""Sets HTTP headers on the file.

:param ~azure.storage.file.models.ContentSettings content_settings:
:param ~azure.storage.file.ContentSettings content_settings:
ContentSettings object used to set file properties.
:param int timeout:
The timeout parameter is expressed in seconds.
:param file_attributes:
The file system attributes for files and directories.
If not set, indicates preservation of existing values.
Here is an example for when the var type is str: 'Temporary|Archive'
:type file_attributes: str or :class:`~azure.storage.file.models.NTFSAttributes`
:type file_attributes: str or :class:`~azure.storage.file.NTFSAttributes`
:param file_creation_time: Creation time for the file
Default value: Now.
:type file_creation_time: str or datetime
Expand Down Expand Up @@ -857,7 +857,7 @@ def list_handles(self, timeout=None, **kwargs):
:param int timeout:
The timeout parameter is expressed in seconds.
:returns: An auto-paging iterable of HandleItems
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.storage.file.models.Handle]
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.storage.file.Handle]
"""
results_per_page = kwargs.pop("results_per_page", None)
command = functools.partial(
Expand Down Expand Up @@ -885,7 +885,7 @@ async def close_handles(
:param handle:
Optionally, a specific handle to close. The default value is '*'
which will attempt to close all open handles.
:type handle: str or ~azure.storage.file.models.Handle
:type handle: str or ~azure.storage.file.Handle
:param int timeout:
The timeout parameter is expressed in seconds.
:returns: A long-running poller to get operation status.
Expand Down
16 changes: 8 additions & 8 deletions sdk/storage/azure-storage-file/azure/storage/file/aio/file_service_client_async.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,16 +130,16 @@ async def set_service_properties(
:param hour_metrics:
The hour metrics settings provide a summary of request
statistics grouped by API in hourly aggregates for files.
:type hour_metrics: ~azure.storage.file.models.Metrics
:type hour_metrics: ~azure.storage.file.Metrics
:param minute_metrics:
The minute metrics settings provide request statistics
for each minute for files.
:type minute_metrics: ~azure.storage.file.models.Metrics
:type minute_metrics: ~azure.storage.file.Metrics
:param cors:
You can include up to five CorsRule elements in the
list. If an empty list is specified, all CORS rules will be deleted,
and CORS will be disabled for the service.
:type cors: list(:class:`~azure.storage.file.models.CorsRule`)
:type cors: list(:class:`~azure.storage.file.CorsRule`)
:param int timeout:
The timeout parameter is expressed in seconds.
:rtype: None
Expand Down Expand Up @@ -185,7 +185,7 @@ def list_shares(
:param int timeout:
The timeout parameter is expressed in seconds.
:returns: An iterable (auto-paging) of ShareProperties.
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.storage.file.models.ShareProperties]
:rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.storage.file.ShareProperties]

.. admonition:: Example:

Expand Down Expand Up @@ -233,7 +233,7 @@ async def create_share(
Quota in bytes.
:param int timeout:
The timeout parameter is expressed in seconds.
:rtype: ~azure.storage.file.aio.share_client_async.ShareClient
:rtype: ~azure.storage.file.aio.ShareClient

.. admonition:: Example:

Expand Down Expand Up @@ -263,7 +263,7 @@ async def delete_share(
:param share_name:
The share to delete. This can either be the name of the share,
or an instance of ShareProperties.
:type share_name: str or ~azure.storage.file.models.ShareProperties
:type share_name: str or ~azure.storage.file.ShareProperties
:param bool delete_snapshots:
Indicates if snapshots are to be deleted.
:param int timeout:
Expand Down Expand Up @@ -292,11 +292,11 @@ def get_share_client(self, share, snapshot=None):
:param share:
The share. This can either be the name of the share,
or an instance of ShareProperties.
:type share: str or ~azure.storage.file.models.ShareProperties
:type share: str or ~azure.storage.file.ShareProperties
:param str snapshot:
An optional share snapshot on which to operate.
:returns: A ShareClient.
:rtype: ~azure.storage.file.aio.share_client_async.ShareClient
:rtype: ~azure.storage.file.aio.ShareClient

.. admonition:: Example:

Expand Down
4 changes: 2 additions & 2 deletions sdk/storage/azure-storage-file/azure/storage/file/aio/models.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ class SharePropertiesPaged(AsyncPageIterator):
:ivar str location_mode: The location mode being used to list results. The available
options include "primary" and "secondary".
:ivar current_page: The current page of listed results.
:vartype current_page: list(~azure.storage.file.models.ShareProperties)
:vartype current_page: list(~azure.storage.file.ShareProperties)

:param callable command: Function to retrieve the next page of items.
:param str prefix: Filters the results to return only shares whose names
Expand Down Expand Up @@ -83,7 +83,7 @@ class HandlesPaged(AsyncPageIterator):
:ivar str location_mode: The location mode being used to list results. The available
options include "primary" and "secondary".
:ivar current_page: The current page of listed results.
:vartype current_page: list(~azure.storage.file.models.Handle)
:vartype current_page: list(~azure.storage.file.Handle)

:param callable command: Function to retrieve the next page of items.
:param int results_per_page: The maximum number of share names to retrieve per
Expand Down
22 changes: 11 additions & 11 deletions sdk/storage/azure-storage-file/azure/storage/file/aio/share_client_async.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ class ShareClient(AsyncStorageAccountHostsMixin, ShareClientBase):
:param str share_url: The full URI to the share.
:param share: The share with which to interact. If specified, this value will override
a share value specified in the share URL.
:type share: str or ~azure.storage.file.models.ShareProperties
:type share: str or ~azure.storage.file.ShareProperties
:param str snapshot:
An optional share snapshot on which to operate.
:param credential:
Expand Down Expand Up @@ -253,7 +253,7 @@ async def get_share_properties(self, timeout=None, **kwargs):
:param int timeout:
The timeout parameter is expressed in seconds.
:returns: The share properties.
:rtype: ~azure.storage.file.models.ShareProperties
:rtype: ~azure.storage.file.ShareProperties

.. admonition:: Example:

Expand Down Expand Up @@ -378,7 +378,7 @@ async def set_share_access_policy(self, signed_identifiers=None, timeout=None, *
A dictionary of access policies to associate with the share. The
dictionary may contain up to 5 elements. An empty dictionary
will clear the access policies set on the service.
:type signed_identifiers: dict(str, :class:`~azure.storage.file.models.AccessPolicy`)
:type signed_identifiers: dict(str, :class:`~azure.storage.file.AccessPolicy`)
:param int timeout:
The timeout parameter is expressed in seconds.
:returns: Share-updated property dict (Etag and last modified).
Expand Down Expand Up @@ -470,8 +470,8 @@ async def create_permission_for_share(self, file_permission, # type: str
**kwargs # type: Any
):
# type: (...) -> str
"""
Create a permission(a security descriptor) at the share level.
"""Create a permission(a security descriptor) at the share level.

This 'permission' can be used for the files/directories in the share.
If a 'permission' already exists, it shall return the key of it, else
creates a new permission at the share level and return its key.
Expand All @@ -480,8 +480,8 @@ async def create_permission_for_share(self, file_permission, # type: str
File permission, a Portable SDDL
:param int timeout:
The timeout parameter is expressed in seconds.
:returns a file permission key
:rtype str
:returns: a file permission key
:rtype: str
"""
options = self._create_permission_for_share_options(file_permission, timeout=timeout, **kwargs)
try:
Expand All @@ -496,16 +496,16 @@ async def get_permission_for_share( # type: ignore
**kwargs # type: Any
):
# type: (...) -> str
"""
Get a permission(a security descriptor) for a given key.
"""Get a permission(a security descriptor) for a given key.

This 'permission' can be used for the files/directories in the share.

:param str file_permission_key:
Key of the file permission to retrieve
:param int timeout:
The timeout parameter is expressed in seconds.
:returns a file permission(a portable SDDL)
:rtype str
:returns: a file permission(a portable SDDL)
:rtype: str
"""
try:
return await self._client.share.get_permission( # type: ignore
Expand Down
Loading