From 24c75afa23a91bf99a2bb655061c1c2786f24c8c Mon Sep 17 00:00:00 2001 From: Sean Kane <68240067+seankane-msft@users.noreply.github.com> Date: Fri, 23 Apr 2021 15:50:08 -0400 Subject: [PATCH] [Tables] Updates for apiview & sphinx docs (#18134) --- .../azure/data/tables/_entity.py | 2 +- .../azure/data/tables/_models.py | 65 +++++++---- .../azure/data/tables/_policies.py | 2 +- .../azure/data/tables/_serialize.py | 2 +- .../azure/data/tables/_table_batch.py | 13 ++- .../azure/data/tables/_table_client.py | 104 +++++++++--------- .../data/tables/_table_service_client.py | 70 ++++++------ .../tables/_table_shared_access_signature.py | 4 +- .../data/tables/aio/_table_batch_async.py | 27 ++--- .../data/tables/aio/_table_client_async.py | 89 +++++++-------- .../tables/aio/_table_service_client_async.py | 68 +++++------- .../azure-data-tables/samples/README.md | 2 +- 12 files changed, 224 insertions(+), 224 deletions(-) diff --git a/sdk/tables/azure-data-tables/azure/data/tables/_entity.py b/sdk/tables/azure-data-tables/azure/data/tables/_entity.py index 8d20acf5fefc..5b9049c54a7f 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/_entity.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/_entity.py @@ -44,7 +44,7 @@ def __getattr__(self, name): :param name:name of entity entry :type name: str :return: TableEntity dictionary - :rtype: dict[str,str] + :rtype: Dict[str,str] """ try: return self[name] diff --git a/sdk/tables/azure-data-tables/azure/data/tables/_models.py b/sdk/tables/azure-data-tables/azure/data/tables/_models.py index 9b4197c3da4e..29d52dbf4b0b 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/_models.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/_models.py @@ -4,6 +4,8 @@ # license information. # -------------------------------------------------------------------------- from enum import Enum +from typing import TYPE_CHECKING + from azure.core.exceptions import HttpResponseError from azure.core.paging import PageIterator @@ -22,6 +24,11 @@ from ._error import _process_table_error from ._constants import NEXT_PARTITION_KEY, NEXT_ROW_KEY, NEXT_TABLE_NAME +if TYPE_CHECKING: + from ._generated.models import TableQueryResponse + from azure.core.pipeline.transport import HttpResponse + from typing import Any, Dict, List + class TableServiceStats(GenTableServiceStats): """Stats for the service @@ -133,7 +140,7 @@ class Metrics(GeneratedMetrics): :keyword str version: The version of Storage Analytics to configure. :keyword bool enabled: Required. Indicates whether metrics are enabled for the service. - :keyword bool include_ap_is: Indicates whether metrics should generate summary + :keyword bool include_apis: Indicates whether metrics should generate summary statistics for called API operations. :keyword ~azure.data.tables.RetentionPolicy retention_policy: Required. The retention policy for the metrics. @@ -150,7 +157,7 @@ def __init__( # pylint: disable=super-init-not-called @classmethod def _from_generated(cls, generated): - # type: (...) -> cls + # type: (...) -> Metrics """A summary of request statistics grouped by API in hour or minute aggregates. :param Metrics generated: generated Metrics @@ -194,7 +201,7 @@ def __init__( # pylint: disable=super-init-not-called @classmethod def _from_generated(cls, generated, **kwargs): # pylint: disable=unused-argument - # type: (...) -> cls + # type: (GeneratedRetentionPolicy, Dict[str, Any]) -> RetentionPolicy """The retention policy which determines how long the associated data should persist. @@ -400,12 +407,15 @@ def __init__( self.delete = kwargs.pop("delete", None) or ("d" in _str) def __or__(self, other): + # type: (TableSasPermissions) -> TableSasPermissions return TableSasPermissions(_str=str(self) + str(other)) def __add__(self, other): + # type: (TableSasPermissions) -> TableSasPermissions return TableSasPermissions(_str=str(self) + str(other)) def __str__(self): + # type: () -> TableSasPermissions return ( ("r" if self.read else "") + ("a" if self.add else "") @@ -416,9 +426,10 @@ def __str__(self): @classmethod def from_string( cls, - permission, # type: str + permission, **kwargs ): + # Type: (str, Dict[str, Any]) -> AccountSasPermissions """Create AccountSasPermissions from a string. To specify read, write, delete, etc. permissions you need only to @@ -428,8 +439,8 @@ def from_string( :param str permission: Specify permissions in the string with the first letter of the word. :keyword callable cls: A custom type or function that will be passed the direct response - :return: A AccountSasPermissions object - :rtype: ~azure.data.tables.AccountSasPermissions + :return: An AccountSasPermissions object + :rtype: :class:`~azure.data.tables.AccountSasPermissions` """ p_read = "r" in permission p_add = "a" in permission @@ -477,23 +488,28 @@ def service_properties_deserialize(generated): class TableItem(object): """ - Represents an Azure TableItem. Returned by TableServiceClient.list_tables - and TableServiceClient.query_tables. + Represents an Azure TableItem. + Returned by TableServiceClient.list_tables and TableServiceClient.query_tables. - :param str name: The name of the table. + :ivar str name: The name of the table. :ivar str api_version: The API version included in the service call :ivar str date: The date the service call was made """ def __init__(self, name, **kwargs): - # type: (str, **Any) -> None + # type: (str, Dict[str, Any]) -> None + """ + :param str name: Name of the Table + :keyword str api_version: The API version included in the service call + :keyword str date: The date the service call was made + """ self.name = name self.api_version = kwargs.get("version") self.date = kwargs.get("date") or kwargs.get("Date") @classmethod def _from_generated(cls, generated, **kwargs): - # type: (obj, **Any) -> cls + # type: (TableQueryResponse, Dict[str, Any]) -> TableItem return cls(generated.table_name, **kwargs) @@ -541,12 +557,18 @@ class SASProtocol(str, Enum): class BatchErrorException(HttpResponseError): """There is a failure in batch operations. - :param str message: The message of the exception. + :param message: The message of the exception. + :type message: str :param response: Server response to be deserialized. - :param list parts: A list of the parts in multipart response. + :type response: str + :param parts: A list of the parts in multipart response. + :type parts: ~azure.core.pipeline.transport.HttpResponse + :param args: Args to be passed through + :type args: List[:class:`~azure.core.pipeline.transport.HttpResponse`] """ def __init__(self, message, response, parts, *args, **kwargs): + # type: (str, str, HttpResponse, List[HttpResponse], Dict[str, Any]) -> None self.parts = parts super(BatchErrorException, self).__init__( message=message, response=response, *args, **kwargs @@ -577,9 +599,8 @@ class ResourceTypes(object): Access to object-level APIs for tables (e.g. Get/Create/Query Entity etc.) """ - def __init__( - self, service=False, object=False - ): # pylint: disable=redefined-builtin + def __init__(self, service=False, object=False): # pylint: disable=redefined-builtin + # type: (bool, bool) -> None self.service = service self.object = object self._str = ("s" if self.service else "") + ("o" if self.object else "") @@ -589,6 +610,7 @@ def __str__(self): @classmethod def from_string(cls, string): + # type: (str) -> ResourceTypes """Create a ResourceTypes from a string. To specify service, container, or object you need only to @@ -598,7 +620,7 @@ def from_string(cls, string): :param str string: Specify service, container, or object in in the string with the first letter of the word. :return: A ResourceTypes object - :rtype: ~azure.data.tables.ResourceTypes + :rtype: :class:`~azure.data.tables.ResourceTypes` """ res_service = "s" in string res_object = "o" in string @@ -664,17 +686,18 @@ def __str__(self): @classmethod def from_string(cls, permission, **kwargs): + # type: (str, Dict[str]) -> AccountSasPermissions """Create AccountSasPermissions from a string. To specify read, write, delete, etc. permissions you need only to include the first letter of the word in the string. E.g. for read and write permissions you would provide a string "rw". - :param str permission: Specify permissions in - the string with the first letter of the word. + :param permission: Specify permissions in the string with the first letter of the word. + :type permission: str :keyword callable cls: A custom type or function that will be passed the direct response - :return: A AccountSasPermissions object - :rtype: ~azure.data.tables.AccountSasPermissions + :return: An AccountSasPermissions object + :rtype: :class:`~azure.data.tables.AccountSasPermissions` """ p_read = "r" in permission p_write = "w" in permission diff --git a/sdk/tables/azure-data-tables/azure/data/tables/_policies.py b/sdk/tables/azure-data-tables/azure/data/tables/_policies.py index 2fc780e731a0..e0623c4f5d96 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/_policies.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/_policies.py @@ -184,7 +184,7 @@ def send(self, request): :param request: The PipelineRequest object :type request: ~azure.core.pipeline.PipelineRequest :return: Returns the PipelineResponse or raises error if maximum retries exceeded. - :rtype: ~azure.core.pipeline.PipelineResponse + :rtype: :class:`~azure.core.pipeline.PipelineResponse` :raises: ~azure.core.exceptions.AzureError if maximum retries exceeded. :raises: ~azure.core.exceptions.ClientAuthenticationError if authentication """ diff --git a/sdk/tables/azure-data-tables/azure/data/tables/_serialize.py b/sdk/tables/azure-data-tables/azure/data/tables/_serialize.py index 58a51eb291ca..22a26d681347 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/_serialize.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/_serialize.py @@ -56,7 +56,7 @@ def _parameter_filter_substitution(parameters, query_filter): # type: (Dict[str, str], str) -> str """Replace user defined parameter in filter :param parameters: User defined parameters - :param filter: Filter for querying + :param str query_filter: Filter for querying """ if parameters: filter_strings = query_filter.split(' ') diff --git a/sdk/tables/azure-data-tables/azure/data/tables/_table_batch.py b/sdk/tables/azure-data-tables/azure/data/tables/_table_batch.py index 017ff00ba7c1..a1de59e59a90 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/_table_batch.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/_table_batch.py @@ -86,6 +86,7 @@ def create_entity( :param entity: The properties for the table entity. :type entity: TableEntity or dict[str,str] :return: None + :rtype: None :raises ValueError: .. admonition:: Example: @@ -212,8 +213,10 @@ def update_entity( :param mode: Merge or Replace entity :type mode: ~azure.data.tables.UpdateMode :keyword str etag: Etag of the entity - :keyword ~azure.core.MatchConditions match_condition: MatchCondition + :keyword match_condition: MatchCondition + :paramtype match_condition: ~azure.core.MatchCondition :return: None + :rtype: None :raises ValueError: .. admonition:: Example: @@ -298,7 +301,6 @@ def _batch_update_entity( :type query_options: ~azure.data.tables.models.QueryOptions :return: None :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: """ _format = None @@ -406,7 +408,6 @@ def _batch_merge_entity( :type query_options: ~azure.data.tables.models.QueryOptions :return: None :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: """ _format = None @@ -492,7 +493,8 @@ def delete_entity( :param row_key: The row key of the entity. :type row_key: str :keyword str etag: Etag of the entity - :keyword ~azure.core.MatchConditions match_condition: MatchCondition + :keyword match_condition: MatchCondition + :paramtype match_condition: ~azure.core.MatchCondition :raises ValueError: .. admonition:: Example: @@ -561,7 +563,6 @@ def _batch_delete_entity( :type query_options: ~azure.data.tables.models.QueryOptions :return: None :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: """ _format = None @@ -632,7 +633,7 @@ def upsert_entity( :param entity: The properties for the table entity. :type entity: TableEntity or dict[str,str] - :param mode: Merge or Replace and Insert on fail + :param mode: Merge or Replace entity :type mode: ~azure.data.tables.UpdateMode :raises ValueError: diff --git a/sdk/tables/azure-data-tables/azure/data/tables/_table_client.py b/sdk/tables/azure-data-tables/azure/data/tables/_table_client.py index 02f37a2f056e..fedba022d1df 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/_table_client.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/_table_client.py @@ -34,7 +34,10 @@ class TableClient(TablesBaseClient): - """ :ivar str account_name: Name of the storage account (Cosmos or Azure)""" + """ + :ivar str account_name: Name of the storage account (Cosmos or Azure) + :ivar str table_name: The name of the table + """ def __init__( self, @@ -88,7 +91,7 @@ def from_connection_string( :param table_name: The table name. :type table_name: str :returns: A table client. - :rtype: ~azure.data.tables.TableClient + :rtype: :class:`~azure.data.tables.TableClient` .. admonition:: Example: @@ -109,15 +112,14 @@ def from_table_url(cls, table_url, credential=None, **kwargs): # type: (str, Optional[Any], Any) -> TableClient """A client to interact with a specific Table. - :param table_url: The full URI to the table, including SAS token if used. - :type table_url: str + :param str table_url: The full URI to the table, including SAS token if used. :param credential: The credentials with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string, an account shared access key. :type credential: str :returns: A table client. - :rtype: ~azure.data.tables.TableClient + :rtype: :class:`~azure.data.tables.TableClient` """ try: if not table_url.lower().startswith("http"): @@ -155,8 +157,8 @@ def get_table_access_policy( used with Shared Access Signatures. :return: Dictionary of SignedIdentifiers - :rtype: dict[str,AccessPolicy] - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: Dict[str, :class:`~azure.data.tables.AccessPolicy`] + :raises: :class:`~azure.core.exceptions.HttpResponseError` """ timeout = kwargs.pop("timeout", None) try: @@ -179,11 +181,11 @@ def set_table_access_policy( # type: (...) -> None """Sets stored access policies for the table that may be used with Shared Access Signatures. - :param signed_identifiers: - :type signed_identifiers: dict[str,AccessPolicy] + :param signed_identifiers: Access policies to set for the table + :type signed_identifiers: Dict[str, :class:`~azure.data.tables.AccessPolicy`] :return: None :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: + :raises: :class:`~azure.core.exceptions.HttpResponseError` """ identifiers = [] for key, value in signed_identifiers.items(): @@ -216,8 +218,8 @@ def create_table( """Creates a new table under the current account. :return: Dictionary of operation metadata returned from service - :rtype: dict[str,str] - :raises ~azure.core.exceptions.ResourceExistsError: If the table already exists + :rtype: Dict[str,str] + :raises: :class:`~azure.core.exceptions.ResourceExistsError` If the entity already exists .. admonition:: Example: @@ -248,7 +250,7 @@ def delete_table( :return: None :rtype: None - :raises ~azure.core.exceptions.ResourceNotFoundError: If the table does not exist + :raises: :class:`~azure.core.exceptions.ResourceNotFoundError` If the table does not exist .. admonition:: Example: @@ -279,10 +281,11 @@ def delete_entity( :param row_key: The row key of the entity. :type row_key: str :keyword str etag: Etag of the entity - :keyword ~azure.core.MatchConditions match_condition: MatchCondition + :keyword match_condition: MatchCondition + :paramtype match_condition: ~azure.core.MatchConditions :return: None :rtype: None - :raises ~azure.core.exceptions.ResourceNotFoundError: If the entity does not exist + :raises: :class:`~azure.core.exceptions.ResourceNotFoundError` If the entity already does not exist .. admonition:: Example: @@ -325,10 +328,10 @@ def create_entity( """Insert entity in a table. :param entity: The properties for the table entity. - :type entity: TableEntity or dict[str,str] + :type entity: ~azure.data.tables.TableEntity or Dict[str,str] :return: Dictionary mapping operation metadata returned from the service - :rtype: dict[str,str] - :raises ~azure.core.exceptions.ResourceExistsError: If the entity already exists + :rtype: Dict[str,str] + :raises: :class:`~azure.core.exceptions.ResourceExistsError` If the entity already exists .. admonition:: Example: @@ -365,16 +368,15 @@ def update_entity( """Update entity in a table. :param entity: The properties for the table entity. - :type entity: TableEntity or dict[str,str] + :type entity: ~azure.data.tables.TableEntity or Dict[str,str] :param mode: Merge or Replace entity :type mode: ~azure.data.tables.UpdateMode - :keyword str partition_key: The partition key of the entity. - :keyword str row_key: The row key of the entity. :keyword str etag: Etag of the entity - :keyword ~azure.core.MatchConditions match_condition: MatchCondition + :keyword match_condition: MatchCondition + :paramtype match_condition: ~azure.core.MatchCondition :return: Dictionary mapping operation metadata returned from the service - :rtype: dict[str,str] - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: Dict[str,str] + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -436,10 +438,10 @@ def list_entities( :keyword int results_per_page: Number of entities per page in return ItemPaged :keyword select: Specify desired properties of an entity to return certain entities - :paramtype select: str or list[str] - :return: Query of table entities - :rtype: ~azure.core.paging.ItemPaged[~azure.data.tables.TableEntity] - :raises ~azure.core.exceptions.HttpResponseError: + :paramtype select: str or List[str] + :return: ItemPaged[:class:`~azure.data.tables.TableEntity`] + :rtype: ~azure.core.paging.ItemPaged + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -470,17 +472,17 @@ def query_entities( query_filter, **kwargs ): - # type: (...) -> ItemPaged[TableEntity] + # type: (str, Dict[str, Any]) -> ItemPaged[TableEntity] """Lists entities in a table. - :param str filter: Specify a filter to return certain entities + :param str query_filter: Specify a filter to return certain entities :keyword int results_per_page: Number of entities per page in return ItemPaged :keyword select: Specify desired properties of an entity to return certain entities - :paramtype select: str or list[str] - :keyword dict parameters: Dictionary for formatting query with additional, user defined parameters - :return: Query of table entities - :rtype: ~azure.core.paging.ItemPaged[~azure.data.tables.TableEntity] - :raises ~azure.core.exceptions.HttpResponseError: + :paramtype select: str or List[str] + :keyword Dict[str, Any] parameters: Dictionary for formatting query with additional, user defined parameters + :return: ItemPaged[:class:`~azure.data.tables.TableEntity`] + :rtype: ~azure.core.paging.ItemPaged + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -525,8 +527,8 @@ def get_entity( :param row_key: The row key of the entity. :type row_key: str :return: Dictionary mapping operation metadata returned from the service - :rtype: ~azure.data.tables.TableEntity - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: :class:`~azure.data.tables.TableEntity` + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -561,12 +563,12 @@ def upsert_entity( """Update/Merge or Insert entity into table. :param entity: The properties for the table entity. - :type entity: TableEntity or dict[str,str] - :param mode: Merge or Replace and Insert on fail + :type entity: ~azure.data.tables.TableEntity or Dict[str,str] + :param mode: Merge or Replace entity :type mode: ~azure.data.tables.UpdateMode :return: Dictionary mapping operation metadata returned from the service - :rtype: dict[str,str] - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: Dict[str,str] + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -612,14 +614,12 @@ def upsert_entity( except HttpResponseError as error: _process_table_error(error) - def create_batch( - self, **kwargs # type: Dict[str, Any] - ): - # type: (...) -> azure.data.tables.TableBatchOperations + def create_batch(self, **kwargs): + # type: (Dict[str, Any]) -> TableBatchOperations """Create a Batching object from a Table Client :return: Object containing requests and responses - :rtype: ~azure.data.tables.TableBatchOperations + :rtype: :class:`~azure.data.tables.TableBatchOperations` .. admonition:: Example: @@ -640,18 +640,16 @@ def create_batch( **kwargs ) - def send_batch( - self, - batch, # type: azure.data.tables.TableBatchOperations - **kwargs # type: Any - ): - # type: (...) -> List[Tuple[Mapping[str, Any], Mapping[str, Any]]] + def send_batch(self, batch, **kwargs): + # type: (TableBatchOperations, Dict[str, Any]) -> List[Tuple[Mapping[str, Any], Mapping[str, Any]]] """Commit a TableBatchOperations to send requests to the server + :param batch: Batch of operations + :type batch: ~azure.data.tables.TableBatchOperations :return: A list of tuples, each containing the entity operated on, and a dictionary of metadata returned from the service. :rtype: List[Tuple[Mapping[str, Any], Mapping[str, Any]]] - :raises ~azure.data.tables.BatchErrorException: + :raises: :class:`~azure.data.tables.BatchErrorException` .. admonition:: Example: diff --git a/sdk/tables/azure-data-tables/azure/data/tables/_table_service_client.py b/sdk/tables/azure-data-tables/azure/data/tables/_table_service_client.py index 5edfdb74f3fd..c80e1c54d238 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/_table_service_client.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/_table_service_client.py @@ -5,7 +5,7 @@ # -------------------------------------------------------------------------- import functools -from typing import Any, Union +from typing import Any, Union, Optional, Dict from azure.core.exceptions import HttpResponseError, ResourceExistsError from azure.core.paging import ItemPaged from azure.core.tracing.decorator import distributed_trace @@ -70,11 +70,9 @@ def from_connection_string( ): # type: (...) -> TableServiceClient """Create TableServiceClient from a connection string. - :param conn_str: - A connection string to an Azure Storage or Cosmos account. - :type conn_str: str + :param str conn_str: A connection string to an Azure Storage or Cosmos account. :returns: A Table service client. - :rtype: ~azure.data.tables.TableServiceClient + :rtype: :class:`~azure.data.tables.TableServiceClient` .. admonition:: Example: @@ -92,14 +90,13 @@ def from_connection_string( @distributed_trace def get_service_stats(self, **kwargs): - # type: (...) -> dict[str,object] + # type: (Dict[str, Any]) -> TableServiceStats """Retrieves statistics related to replication for the Table service. It is only available on the secondary location endpoint when read-access geo-redundant replication is enabled for the account. - :keyword callable cls: A custom type or function that will be passed the direct response :return: Dictionary of service stats - :rtype: ~azure.data.tables.models.TableServiceStats - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: :class:`~azure.data.tables.models.TableServiceStats` + :raises: :class:`~azure.core.exceptions.HttpResponseError:` """ try: timeout = kwargs.pop("timeout", None) @@ -112,13 +109,13 @@ def get_service_stats(self, **kwargs): @distributed_trace def get_service_properties(self, **kwargs): - # type: (...) -> dict[str,Any] + # type: (...) -> Dict[str, Any] """Gets the properties of an account's Table service, including properties for Analytics and CORS (Cross-Origin Resource Sharing) rules. :return: Dictionary of service properties - :rtype:dict[str, Any] - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: :class:`~azure.data.tables.models.TableServiceProperties` + :raises: :class:`~azure.core.exceptions.HttpResponseError` """ timeout = kwargs.pop("timeout", None) try: @@ -150,7 +147,7 @@ def set_service_properties( :type cors: ~azure.data.tables.CorsRule :return: None :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: + :raises: :class:`~azure.core.exceptions.HttpResponseError` """ props = TableServiceProperties( logging=analytics_logging, @@ -175,8 +172,8 @@ def create_table( :param table_name: The Table name. :type table_name: str :return: TableClient - :rtype: ~azure.data.tables.TableClient - :raises ~azure.core.exceptions.ResourceExistsError: + :rtype: :class:`~azure.data.tables.TableClient` + :raises: :class:`~azure.core.exceptions.ResourceExistsError` .. admonition:: Example: @@ -205,8 +202,8 @@ def create_table_if_not_exists( :param table_name: The Table name. :type table_name: str :return: TableClient - :rtype: ~azure.data.tables.TableClient - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: :class:`~azure.data.tables.TableClient` + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -237,7 +234,7 @@ def delete_table( :type table_name: str :return: None :rtype: None - :raises ~azure.core.exceptions.ResourceNotFoundError: + :raises: :class:`~azure.core.exceptions.ResourceNotFoundError` .. admonition:: Example: @@ -255,20 +252,19 @@ def delete_table( def query_tables( self, query_filter, - **kwargs # type: Any + **kwargs ): - # type: (...) -> ItemPaged[TableItem] + # type: (str, Dict[str, Any]) -> ItemPaged[TableItem] """Queries tables under the given account. - :param filter: Specify a filter to return certain tables. - :type filter: str + :param str query_filter: Specify a filter to return certain tables. :keyword int results_per_page: Number of tables per page in return ItemPaged :keyword select: Specify desired properties of a table to return certain tables - :paramtype select: str or list[str] - :keyword dict[str,str] parameters: Dictionary for formatting query with additional, user defined parameters - :return: An ItemPaged of tables - :rtype: ~azure.core.paging.ItemPaged[TableItem] - :raises ~azure.core.exceptions.HttpResponseError: + :paramtype select: str or List[str] + :keyword Dict[str, str] parameters: Dictionary for formatting query with additional, user defined parameters + :return: ItemPaged[:class:`~azure.data.tables.TableItem`] + :rtype: ~azure.core.paging.ItemPaged + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -298,18 +294,16 @@ def query_tables( ) @distributed_trace - def list_tables( - self, **kwargs # type: Any - ): - # type: (...) -> ItemPaged[TableItem] + def list_tables(self, **kwargs): + # type: (Any) -> ItemPaged[TableItem] """Queries tables under the given account. :keyword int results_per_page: Number of tables per page in return ItemPaged :keyword select: Specify desired properties of a table to return certain tables - :paramtype select: str or list[str] - :return: A query of tables - :rtype: ~azure.core.paging.ItemPaged[TableItem] - :raises ~azure.core.exceptions.HttpResponseError: + :paramtype select: str or List[str] + :return: ItemPaged[:class:`~azure.data.tables.TableItem`] + :rtype: ~azure.core.paging.ItemPaged + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -339,11 +333,9 @@ def get_table_client(self, table_name, **kwargs): The table need not already exist. - :param table_name: - The table name - :type table_name: str + :param str table_name: The table name :returns: A :class:`~azure.data.tables.TableClient` object. - :rtype: ~azure.data.tables.TableClient + :rtype: :class:`~azure.data.tables.TableClient` """ pipeline = Pipeline( diff --git a/sdk/tables/azure-data-tables/azure/data/tables/_table_shared_access_signature.py b/sdk/tables/azure-data-tables/azure/data/tables/_table_shared_access_signature.py index 42c1e607c07f..f8d1306fa053 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/_table_shared_access_signature.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/_table_shared_access_signature.py @@ -30,9 +30,9 @@ def generate_account_sas( Use the returned signature with the sas_token parameter of TableService. :param account_name: Account name - :type account_name:str + :type account_name: str :param account_key: Account key - :type account_key:str + :type account_key: str :param resource_types: Specifies the resource types that are accessible with the account SAS. :type resource_types: ResourceTypes diff --git a/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_batch_async.py b/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_batch_async.py index 8fd66c4ac148..f07cde4bca8c 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_batch_async.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_batch_async.py @@ -75,6 +75,7 @@ def create_entity( :param entity: The properties for the table entity. :type entity: TableEntity or dict[str,str] :return: None + :rtype: None :raises ValueError: .. admonition:: Example: @@ -197,12 +198,14 @@ def update_entity( """Adds an update operation to the current batch. :param entity: The properties for the table entity. - :type entity: TableEntity or dict[str,str] + :type entity: TableEntity or Dict[str,str] :param mode: Merge or Replace entity :type mode: ~azure.data.tables.UpdateMode :keyword str etag: Etag of the entity - :keyword ~azure.core.MatchConditions match_condition: MatchCondition + :keyword match_condition: MatchCondition + :paramtype match_condition: ~azure.core.MatchCondition :return: None + :rtype: None :raises ValueError: .. admonition:: Example: @@ -284,10 +287,6 @@ def _batch_update_entity( :type table_entity_properties: dict[str, object] :param query_options: Parameter group. :type query_options: ~azure.data.tables.models.QueryOptions - :keyword callable cls: A custom type or function that will be passed the direct response - :return: None, or the result of cls(response) - :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: """ _format = None @@ -392,10 +391,6 @@ def _batch_merge_entity( :type table_entity_properties: dict[str, object] :param query_options: Parameter group. :type query_options: ~azure.data.tables.models.QueryOptions - :keyword callable cls: A custom type or function that will be passed the direct response - :return: None, or the result of cls(response) - :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: """ _format = None @@ -482,9 +477,8 @@ def delete_entity( :param row_key: The row key of the entity. :type row_key: str :keyword str etag: Etag of the entity - :keyword ~azure.core.MatchConditions match_condition: MatchCondition - :return: None - :raises ValueError: + :keyword match_condition: MatchCondition + :paramtype match_condition: ~azure.core.MatchCondition .. admonition:: Example: @@ -549,10 +543,6 @@ def _batch_delete_entity( :type request_id_parameter: str :param query_options: Parameter group. :type query_options: ~azure.data.tables.models.QueryOptions - :keyword callable cls: A custom type or function that will be passed the direct response - :return: None, or the result of cls(response) - :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: """ _format = None @@ -623,9 +613,10 @@ def upsert_entity( :param entity: The properties for the table entity. :type entity: TableEntity or dict[str,str] - :param mode: Merge or Replace and Insert on fail + :param mode: Merge or Replace entity :type mode: ~azure.data.tables.UpdateMode :return: None + :rtype: None :raises ValueError: .. admonition:: Example: diff --git a/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_client_async.py b/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_client_async.py index 6fb1345900e6..e8686630e0f1 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_client_async.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_client_async.py @@ -40,7 +40,10 @@ class TableClient(AsyncTablesBaseClient): - """ :ivar str account_name: Name of the storage account (Cosmos or Azure)""" + """ + :ivar str account_name: Name of the storage account (Cosmos or Azure) + :ivar str table_name: The name of the table + """ def __init__( self, @@ -94,7 +97,7 @@ def from_connection_string( :param table_name: The table name. :type table_name: str :returns: A table client. - :rtype: ~azure.data.tables.TableClient + :rtype: :class:`~azure.data.tables.TableClient` .. admonition:: Example: @@ -123,7 +126,7 @@ def from_table_url(cls, table_url, credential=None, **kwargs): shared access key. :type credential: str :returns: A table client. - :rtype: ~azure.data.tables.TableClient + :rtype: :class:`~azure.data.tables.TableClient` """ try: if not table_url.lower().startswith("http"): @@ -153,17 +156,14 @@ def from_table_url(cls, table_url, credential=None, **kwargs): return cls(account_url, table_name=table_name, credential=credential, **kwargs) @distributed_trace_async - async def get_table_access_policy( - self, **kwargs # type: Any - ): - # type: (...) -> dict[str,AccessPolicy] + async def get_table_access_policy(self, **kwargs: Any) -> Dict[str, AccessPolicy]: """ Retrieves details about any stored access policies specified on the table that may be used with Shared Access Signatures. :return: Dictionary of SignedIdentifiers - :rtype: dict[str,~azure.data.tables.AccessPolicy] - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: Dict[str, :class:`~azure.data.tables.AccessPolicy`] + :raises: :class:`~azure.core.exceptions.HttpResponseError` """ timeout = kwargs.pop("timeout", None) try: @@ -190,11 +190,11 @@ async def set_table_access_policy( # type: (...) -> None """Sets stored access policies for the table that may be used with Shared Access Signatures. - :param signed_identifiers: - :type signed_identifiers: dict[str,AccessPolicy] + :param signed_identifiers: Access policies to set for the table + :type signed_identifiers: Dict[str, :class:`~azure.data.tables.AccessPolicy`] :return: None :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: + :raises: :class:`~azure.core.exceptions.HttpResponseError` """ identifiers = [] for key, value in signed_identifiers.items(): @@ -227,8 +227,8 @@ async def create_table( """Creates a new table under the given account. :return: Dictionary of operation metadata returned from service - :rtype: dict[str,str] - :raises ~azure.core.exceptions.ResourceExistsError: If the table already exists + :rtype: Dict[str,str] + :raises: :class:`~azure.core.exceptions.ResourceExistsError` If the entity already exists .. admonition:: Example: @@ -259,7 +259,7 @@ async def delete_table( :return: None :rtype: None - :raises ~azure.core.exceptions.ResourceNotFoundError: + :raises: :class:`~azure.core.exceptions.ResourceNotFoundError` If the table does not exist .. admonition:: Example: @@ -290,10 +290,11 @@ async def delete_entity( :param row_key: The row key of the entity. :type row_key: str :keyword str etag: Etag of the entity - :keyword ~azure.core.MatchConditions match_condition: MatchCondition + :keyword match_condition: MatchCondition + :paramtype match_condition: ~azure.core.MatchConditions :return: None :rtype: None - :raises ~azure.core.exceptions.ResourceNotFoundError: If the table does not exist + :raises: :class:`~azure.core.exceptions.ResourceNotFoundError` If the entity already does not exist .. admonition:: Example: @@ -334,10 +335,11 @@ async def create_entity( """Insert entity in a table. :param entity: The properties for the table entity. - :type entity: TableEntity or dict[str,str] + :type entity: ~azure.data.tables.TableEntity or Dict[str,str] :return: Dictionary mapping operation metadata returned from the service - :rtype: dict[str,str] - :raises ~azure.core.exceptions.ResourceExistsError: If the entity already exists + :rtype: Dict[str,str] + :raises: :class:`~azure.core.exceptions.ResourceExistsError` If the entity already exists + .. admonition:: Example: @@ -377,13 +379,12 @@ async def update_entity( :type entity: dict[str, str] :param mode: Merge or Replace entity :type mode: ~azure.data.tables.UpdateMode - :keyword str partition_key: The partition key of the entity. - :keyword str row_key: The row key of the entity. :keyword str etag: Etag of the entity - :keyword ~azure.core.MatchConditions match_condition: MatchCondition + :keyword match_condition: MatchCondition + :paramtype match_condition: ~azure.core.MatchCondition :return: Dictionary of operation metadata returned from service - :rtype: dict[str,str] - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: Dict[str,str] + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -444,10 +445,10 @@ def list_entities( :keyword int results_per_page: Number of entities per page in return AsyncItemPaged :keyword select: Specify desired properties of an entity to return certain entities - :paramtype select: str or list[str] - :return: Query of table entities - :rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.data.tables.TableEntity] - :raises ~azure.core.exceptions.HttpResponseError: + :paramtype select: str or List[str] + :return: AsyncItemPaged[:class:`~azure.data.tables.TableEntity`] + :rtype: ~azure.core.async_paging.AsyncItemPaged + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -478,17 +479,17 @@ def query_entities( query_filter, **kwargs ): - # type: (...) -> AsyncItemPaged[TableEntity] + # type: (str, Dict[str, Any]) -> AsyncItemPaged[TableEntity] """Lists entities in a table. - :param str filter: Specify a filter to return certain entities + :param str query_filter: Specify a filter to return certain entities :keyword int results_per_page: Number of entities per page in return AsyncItemPaged :keyword select: Specify desired properties of an entity to return certain entities - :paramtype select: str or list[str] - :keyword dict parameters: Dictionary for formatting query with additional, user defined parameters - :return: Query of table entities - :rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.data.tables.TableEntity] - :raises ~azure.core.exceptions.HttpResponseError: + :paramtype select: str or List[str] + :keyword Dict[str, Any] parameters: Dictionary for formatting query with additional, user defined parameters + :return: AsyncItemPaged[:class:`~azure.data.tables.TableEntity`] + :rtype: ~azure.core.async_paging.AsyncItemPaged + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -533,8 +534,8 @@ async def get_entity( :param row_key: The row key of the entity. :type row_key: str :return: Dictionary mapping operation metadata returned from the service - :rtype: ~azure.data.tables.TableEntity - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: :class:`~azure.data.tables.TableEntity` + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -570,11 +571,11 @@ async def upsert_entity( :param entity: The properties for the table entity. :type entity: TableEntity or dict[str,str] - :param mode: Merge or Replace and Insert on fail + :param mode: Merge or Replace entity :type mode: ~azure.data.tables.UpdateMode :return: Dictionary mapping operation metadata returned from the service - :rtype: dict[str,str] - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: Dict[str,str] + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -626,7 +627,7 @@ def create_batch(self, **kwargs: Dict[str, Any]) -> TableBatchOperations: """Create a Batching object from a Table Client :return: Object containing requests and responses - :rtype: ~azure.data.tables.TableBatchOperations + :rtype: :class:`~azure.data.tables.TableBatchOperations` .. admonition:: Example: @@ -652,10 +653,12 @@ async def send_batch( ) -> List[Tuple[Mapping[str, Any], Mapping[str, Any]]]: """Commit a TableBatchOperations to send requests to the server + :param batch: Batch of operations + :type batch: ~azure.data.tables.TableBatchOperations :return: A list of tuples, each containing the entity operated on, and a dictionary of metadata returned from the service. :rtype: List[Tuple[Mapping[str, Any], Mapping[str, Any]]] - :raises ~azure.data.tables.BatchErrorException: + :raises: :class:`~azure.data.tables.BatchErrorException` .. admonition:: Example: diff --git a/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_service_client_async.py b/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_service_client_async.py index e3be666c4879..ea880e900406 100644 --- a/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_service_client_async.py +++ b/sdk/tables/azure-data-tables/azure/data/tables/aio/_table_service_client_async.py @@ -33,12 +33,12 @@ class TableServiceClient(AsyncTablesBaseClient): This client provides operations to retrieve and configure the account properties as well as list, create and delete tables within the account. - For operations relating to a specific queue, a client for this entity + For operations relating to a specific table, a client for this entity can be retrieved using the :func:`~get_table_client` function. :param str account_url: The URL to the table service endpoint. Any other entities included - in the URL path (e.g. queue) will be discarded. This URL can be optionally + in the URL path (e.g. table) will be discarded. This URL can be optionally authenticated with a SAS token. :param str credential: The credentials with which to authenticate. This is optional if the @@ -91,7 +91,7 @@ def from_connection_string( A connection string to an Azure Storage or Cosmos account. :type conn_str: str :returns: A Table service client. - :rtype: ~azure.data.tables.TableServiceClient + :rtype: :class:`~azure.data.tables.aio.TableServiceClient` .. admonition:: Example: @@ -114,11 +114,9 @@ async def get_service_stats(self, **kwargs): """Retrieves statistics related to replication for the Table service. It is only available on the secondary location endpoint when read-access geo-redundant replication is enabled for the account. - :keyword callable cls: A custom type or function that will be passed the direct response - :return: Dictionary of service stats - :rtype: ~azure.data.tables.models.TableServiceStats - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: :class:`~azure.data.tables.models.TableServiceStats` + :raises: :class:`~azure.core.exceptions.HttpResponseError` """ try: timeout = kwargs.pop("timeout", None) @@ -137,8 +135,8 @@ async def get_service_properties(self, **kwargs): :keyword callable cls: A custom type or function that will be passed the direct response :return: TableServiceProperties, or the result of cls(response) - :rtype: ~azure.data.tables.models.TableServiceProperties - :raises ~azure.core.exceptions.HttpResponseError: + :rtype: :class:`~azure.data.tables.models.TableServiceProperties` + :raises: :class:`~azure.core.exceptions.HttpResponseError` """ timeout = kwargs.pop("timeout", None) try: @@ -170,7 +168,7 @@ async def set_service_properties( :type cors: ~azure.data.tables.CorsRule :return: None :rtype: None - :raises ~azure.core.exceptions.HttpResponseError: + :raises: :class:`~azure.core.exceptions.HttpResponseError` """ props = TableServiceProperties( logging=analytics_logging, @@ -193,11 +191,10 @@ async def create_table( """Creates a new table under the given account. :param headers: - :param table_name: The Table name. - :type table_name: ~azure.data.tables._models.Table + :param str table_name: The Table name. :return: TableClient, or the result of cls(response) - :rtype: ~azure.data.tables.TableClient or None - :raises ~azure.core.exceptions.ResourceExistsError: + :rtype: :class:`~azure.data.tables.aio.TableClient` + :raises: :class:`~azure.core.exceptions.ResourceExistsError` .. admonition:: Example: @@ -226,7 +223,7 @@ async def create_table_if_not_exists( :param table_name: The Table name. :type table_name: str :return: TableClient - :rtype: ~azure.data.tables.aio.TableClient + :rtype: :class:`~azure.data.tables.aio.TableClient` .. admonition:: Example: @@ -253,11 +250,10 @@ async def delete_table( # type: (...) -> None """Deletes the table under the current account - :param table_name: The Table name. - :type table_name: str + :param str table_name: The Table name. :return: None :rtype: None - :raises ~azure.core.exceptions.ResourceNotFoundError: + :raises: :class:`~azure.core.exceptions.ResourceNotFoundError` .. admonition:: Example: @@ -280,10 +276,10 @@ def list_tables( :keyword int results_per_page: Number of tables per page in return ItemPaged :keyword select: Specify desired properties of a table to return certain tables - :paramtype select: str or list[str] - :return: AsyncItemPaged - :rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.data.tables.TableItem] - :raises ~azure.core.exceptions.HttpResponseError: + :paramtype select: str or List[str] + :return: AsyncItemPaged[:class:`~azure.data.tables.TableItem`] + :rtype: ~azure.core.async_paging.AsyncItemPaged + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -310,21 +306,20 @@ def list_tables( @distributed_trace def query_tables( self, - query_filter, # type: str - **kwargs # type: Any + query_filter, + **kwargs ): - # type: (...) -> AsyncItemPaged[TableItem] + # type: (str, Dict[str, Any]) -> AsyncItemPaged[TableItem] """Queries tables under the given account. - :param query_filter: Specify a filter to return certain tables. - :type query_filter: str + :param str query_filter: Specify a filter to return certain tables. :keyword int results_per_page: Number of tables per page in return ItemPaged :keyword select: Specify desired properties of a table to return certain tables - :paramtype select: str or list[str] - :keyword dict[str,str] parameters: Dictionary for formatting query with additional, user defined parameters - :return: An ItemPaged of tables - :rtype: ~azure.core.async_paging.AsyncItemPaged[~azure.data.tables.TableItem] - :raises ~azure.core.exceptions.HttpResponseError: + :paramtype select: str or List[str] + :keyword Dict[str, Any] parameters: Dictionary for formatting query with additional, user defined parameters + :return: AsyncItemPaged[:class:`~azure.data.tables.TableItem`] + :rtype: ~azure.core.async_paging.AsyncItemPaged + :raises: :class:`~azure.core.exceptions.HttpResponseError` .. admonition:: Example: @@ -362,12 +357,9 @@ def get_table_client( The table need not already exist. - :param table: - The queue. This can either be the name of the queue, - or an instance of QueueProperties. - :type table: str or ~azure.storage.table.TableProperties - :returns: A :class:`~azure.data.tables.TableClient` object. - :rtype: ~azure.data.tables.TableClient + :param str table_name: The table name + :returns: A :class:`~azure.data.tables.aio.TableClient` object. + :rtype: :class:`~azure.data.tables.aio.TableClient` """ pipeline = AsyncPipeline( diff --git a/sdk/tables/azure-data-tables/samples/README.md b/sdk/tables/azure-data-tables/samples/README.md index 17e49ae5323d..d3997215dc36 100644 --- a/sdk/tables/azure-data-tables/samples/README.md +++ b/sdk/tables/azure-data-tables/samples/README.md @@ -55,7 +55,7 @@ pip install --pre azure-data-tables |------------|------------------| |`Equal`|`eq`| |`GreaterThan`|`gt`| -|`GreaterTahnOrEqual`|`ge`| +|`GreaterThanOrEqual`|`ge`| |`LessThan`|`lt`| |`LessThanOrEqual`|`le`| |`NotEqual`|`ne`|