Update readme samples (#13486)

* updated each sample to use env variables, more informative print statements

* updating readme with more accurate links, still missing a few

* grammar fixes

* added a readme, and async versions for auth and create/delete operations

* added more files (copies for async), and a README to the samples portion

* basic commit, merging others into one branch

* put async into another folder

* more README updates to align with .NET

* initial draft of README and samples

* initial comments from cala and kate

* caught a text analytics reference, thanks kate

* caught a text analytics reference, thanks kate

* reverting version

* fixing two broken links

* recording for test_list_tables that got left out

* fixing broken links

* another attempt at broken links

* changing parentheses to a bracket per kristas recommendation

* commenting out one test with weird behavior

* found an actual broken link

* lint fixes

* update to readme and samples per cala, issy, and kates recs. added examples to sphinx docs that were not there.

* added a quote around odata filter, thanks Chris for the catch

* updating a few more broken links

* adding an aka.ms link for pypi

* two more broken links

* reverting a change back

* fixing missing END statements, removing link to nowhere, correcting logger

sdk/tables/azure-data-tables/azure/__init__.py

@@ -1 +1 @@
-__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: str
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: ignore

sdk/tables/azure-data-tables/azure/data/__init__.py

@@ -1 +1 @@
-__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: str
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: ignore

sdk/tables/azure-data-tables/azure/data/tables/_table_client.py

@@ -80,6 +80,15 @@ def from_connection_string(
         :type table_name: str
         :returns: A table client.
         :rtype: ~azure.data.tables.TableClient
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_create_client.py
+                :start-after: [START create_table_client]
+                :end-before: [END create_table_client]
+                :language: python
+                :dedent: 8
+                :caption: Authenticating a TableServiceClient from a connection_string
         """
         account_url, credential = parse_connection_str(
             conn_str=conn_str, credential=None, service='table', keyword_args=kwargs)
@@ -189,6 +198,15 @@ def create_table(
         :return: Dictionary of operation metadata returned from service
         :rtype: dict[str,str]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_create_delete_table.py
+                :start-after: [START create_table_from_table_client]
+                :end-before: [END create_table_from_table_client]
+                :language: python
+                :dedent: 8
+                :caption: Creating a table from the TableClient object
         """
         table_properties = TableProperties(table_name=self.table_name, **kwargs)
         try:
@@ -209,6 +227,15 @@ def delete_table(
 
         :return: None
         :rtype: None
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_create_delete_table.py
+                :start-after: [START delete_table_from_table_client]
+                :end-before: [END delete_table_from_table_client]
+                :language: python
+                :dedent: 8
+                :caption: Deleting a table from the TableClient object
         """
         try:
             self._client.table.delete(table=self.table_name, **kwargs)
@@ -234,6 +261,15 @@ def delete_entity(
         :return: None
         :rtype: None
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_insert_delete_entities.py
+                :start-after: [START delete_entity]
+                :end-before: [END delete_entity]
+                :language: python
+                :dedent: 8
+                :caption: Deleting an entity to a Table
         """
 
         if_match, _ = _get_match_headers(kwargs=dict(kwargs, etag=kwargs.pop('etag', None),
@@ -264,6 +300,15 @@ def create_entity(
         :return: Dictionary mapping operation metadata returned from the service
         :rtype: dict[str,str]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_insert_delete_entities.py
+                :start-after: [START create_entity]
+                :end-before: [END create_entity]
+                :language: python
+                :dedent: 8
+                :caption: Creating and adding an entity to a Table
         """
 
         if "PartitionKey" in entity and "RowKey" in entity:
@@ -301,6 +346,15 @@ def update_entity(  # pylint:disable=R1710
         :return: Dictionary mapping operation metadata returned from the service
         :rtype: dict[str,str]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_update_upsert_merge_entities.py
+                :start-after: [START update_entity]
+                :end-before: [END update_entity]
+                :language: python
+                :dedent: 8
+                :caption: Updating an already exiting entity in a Table
         """
 
         if_match, _ = _get_match_headers(kwargs=dict(kwargs, etag=kwargs.pop('etag', None),
@@ -349,6 +403,15 @@ def list_entities(
         :return: Query of table entities
         :rtype: ItemPaged[TableEntity]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_update_upsert_merge_entities.py
+                :start-after: [START query_entities]
+                :end-before: [END query_entities]
+                :language: python
+                :dedent: 8
+                :caption: List all entities held within a table
         """
         user_select = kwargs.pop('select', None)
         if user_select and not isinstance(user_select, str):
@@ -380,6 +443,15 @@ def query_entities(
         :return: Query of table entities
         :rtype: ItemPaged[TableEntity]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_query_table.py
+                :start-after: [START query_entities]
+                :end-before: [END query_entities]
+                :language: python
+                :dedent: 8
+                :caption: Query entities held within a table
         """
         parameters = kwargs.pop('parameters', None)
         filter = self._parameter_filter_substitution(parameters, filter)  # pylint: disable = W0622
@@ -446,6 +518,15 @@ def upsert_entity(  # pylint:disable=R1710
         :return: Dictionary mapping operation metadata returned from the service
         :rtype: dict[str,str]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_update_upsert_merge_entities.py
+                :start-after: [START upsert_entity]
+                :end-before: [END upsert_entity]
+                :language: python
+                :dedent: 8
+                :caption: Update/merge or insert an entity into a table
         """
 
         partition_key = entity['PartitionKey']

sdk/tables/azure-data-tables/azure/data/tables/_table_service_client.py

@@ -42,6 +42,22 @@ def __init__(
             key.
         :type credential: str
         :returns: None
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_authentication.py
+                :start-after: [START auth_from_sas]
+                :end-before: [END auth_from_sas]
+                :language: python
+                :dedent: 8
+                :caption: Authenticating a TableServiceClient from a Shared Access Key
+
+            .. literalinclude:: ../samples/sample_authentication.py
+                :start-after: [START auth_from_shared_key]
+                :end-before: [END auth_from_shared_key]
+                :language: python
+                :dedent: 8
+                :caption: Authenticating a TableServiceClient from a Shared Account Key
         """
 
         super(TableServiceClient, self).__init__(account_url, service='table', credential=credential, **kwargs)
@@ -59,6 +75,15 @@ def from_connection_string(
         :type conn_str: str
         :returns: A Table service client.
         :rtype: ~azure.data.tables.TableServiceClient
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_authentication.py
+                :start-after: [START auth_from_connection_string]
+                :end-before: [END auth_from_connection_string]
+                :language: python
+                :dedent: 8
+                :caption: Authenticating a TableServiceClient from a connection_string
         """
         account_url, credential = parse_connection_str(
             conn_str=conn_str, credential=None, service='table', keyword_args=kwargs)
@@ -149,6 +174,15 @@ def create_table(
         :return: TableClient
         :rtype: ~azure.data.tables.TableClient
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_create_delete_table.py
+                :start-after: [START create_table_from_tc]
+                :end-before: [END create_table_from_tc]
+                :language: python
+                :dedent: 8
+                :caption: Creating a table from the TableServiceClient object
         """
         table = self.get_table_client(table_name=table_name)
         table.create_table(**kwargs)
@@ -170,6 +204,15 @@ def create_table_if_not_exists(
         :return: TableClient
         :rtype: ~azure.data.tables.TableClient
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_create_delete_table.py
+                :start-after: [START create_table_if_not_exists]
+                :end-before: [END create_table_if_not_exists]
+                :language: python
+                :dedent: 8
+                :caption: Deleting a table from the TableServiceClient object
         """
         table = self.get_table_client(table_name=table_name)
         try:
@@ -191,6 +234,15 @@ def delete_table(
         :type table_name: str
         :return: None
         :rtype: None
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_create_delete_table.py
+                :start-after: [START delete_table_from_tc]
+                :end-before: [END delete_table_from_tc]
+                :language: python
+                :dedent: 8
+                :caption: Deleting a table from the TableServiceClient object
         """
         table = self.get_table_client(table_name=table_name)
         table.delete_table(**kwargs)
@@ -211,6 +263,15 @@ def query_tables(
         :return: A query of tables
         :rtype: ItemPaged[TableItem]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_query_tables.py
+                :start-after: [START tsc_query_tables]
+                :end-before: [END tsc_query_tables]
+                :language: python
+                :dedent: 8
+                :caption: Querying tables in a storage account
         """
         parameters = kwargs.pop('parameters', None)
         filter = self._parameter_filter_substitution(parameters, filter)  # pylint: disable=W0622
@@ -241,6 +302,15 @@ def list_tables(
         :return: A query of tables
         :rtype: ItemPaged[TableItem]
         :raises: ~azure.core.exceptions.HttpResponseError
+
+        .. admonition:: Example:
+
+            .. literalinclude:: ../samples/sample_query_tables.py
+                :start-after: [START tsc_list_tables]
+                :end-before: [END tsc_list_tables]
+                :language: python
+                :dedent: 8
+                :caption: Listing all tables in a storage account
         """
         user_select = kwargs.pop('select', None)
         if user_select and not isinstance(user_select, str):