additions for scrubbers, grammar fixes (Azure#17240)

* additions for scrubbers, grammar fixes

* addressing comments

Author: seankane-msft

doc/dev/packaging.md

@@ -1,25 +1,25 @@
 # Azure packaging
 
-This article describes how to declare setup.py and all packaging information for packages inside the "azure" namespace
+This article describes how to declare setup.py and all packaging information for packages inside the `azure` namespace
 
 Namespace packaging is complicated in Python, here's a few reading if you still doubt it:
 - https://packaging.python.org/guides/packaging-namespace-packages/
 - https://www.python.org/dev/peps/pep-0420/
 - https://github.com/pypa/sample-namespace-packages
 
-This articles describes the recommendation on how to do it if you want to release a package inside the "azure" namespace. Being inside the "azure" namespace meaning you have a service "myservice" that you want to import using:
+This article describes the recommendation on how to define namespace packaging to release a package inside the `azure` namespace. Being inside the `azure` namespace meaning you have a service `myservice` that you want to import using:
 ```python
 import azure.myservice
 ```
 
-Notes:
+Note:
 - This article is not about setup.py or setup.cfg or the right way to *write* the packaging, it's about what instructions you should use to achieve this. If you are fluent in setuptools, and prefer to write the suggestions in setup.cfg and not in setup.py, this is not a concern.
 
 # What are the constraints?
 
 We want to build sdist and wheels in order to follow the following constraints:
 - Solution should work with *recent* versions of pip and setuptools (not the very latest only, but not archaeology either)
-- Wheels must work with Python 2.7 and 3.4+
+- Wheels must work with Python 2.7 and 3.6+
 - easy-install scenario is a plus, but cannot be considered critical anymore
 - mixed dev installation and PyPI installation should be explicitly addressed
 
@@ -46,7 +46,7 @@ recursive-include samples *.py *.md
 ```
 In your setup.py:
 
-The "packages" section MUST EXCLUDE the "azure" package. Example:
+The "packages" section MUST EXCLUDE the `azure` package. Example:
 ```python
     packages=find_packages(exclude=[
         'tests',
@@ -147,4 +147,4 @@ This syntax works with setuptools >= 17.1 and pip >= 6.0, which is considered en
 
 - wheels must NOT contain a `azure/__init__.py` file (you can open it with a zip util to check)
 - wheels installs `azure-nskpg` ONLY on Python 2.
-- sdist must contains a `azure/__init__.py` file that declares the "azure" as a namespace package using the `pkgutil` syntax
+- sdist must contain a `azure/__init__.py` file that declares `azure` as a namespace package using the `pkgutil` syntax

doc/dev/tests-advanced.md

@@ -169,11 +169,11 @@ Notes:
 
 ## mgmt_settings_real file
 
-Instead of using a `.env` file, you can use the `mgmt_settings_real.py` file by copying `sdk/tools/azure-sdk-tools/devtools_testutils/mgmt_settings_fake.py` to `sdk/tools/azure-sdk-tools/devtools_testutils/mgmt_settings_real.py` and providing real credentials to it. To
+A `mgmt_settings_real.py` can be used in place of a `.env` file by copying `sdk/tools/azure-sdk-tools/devtools_testutils/mgmt_settings_fake.py` to `sdk/tools/azure-sdk-tools/devtools_testutils/mgmt_settings_real.py` and providing real credentials to it. The following changes need to be made to the `mgmt_settings_real.py` file:
 
-1. Change the value of the `SUBSCRIPTION_ID` variable to your organizations subscription ID. If you don't have it, you can find it in the "Overview" section of the "Subscriptions" blade in the [Azure portal](https://portal.azure.com/).
-2. Defining `TENANT_ID`, `CLIENT_ID`, and `CLIENT_SECRET` which are available after creating a Service Principal or can be retrieved from the Azure Portal if you have already created a Service Principal. If you do not have a Service Principal, check out the [Azure docs](https://docs.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az_ad_sp_create_for_rbac) on a simple one line command to create one. The recommended practice is to include your alias or name in the Service Principal name.
-3. Change the `get_azure_core_credentials(**kwargs):` function to construct and return a `ClientSecretCredential` object. The `client_id`, `client_secret`, `tenant_id` are provided when you create a service principal. These values can be found in the Azure Portal. This method should look like this:
+1. Change the value of the `SUBSCRIPTION_ID` variable to your organizations subscription ID, which can be found in the "Overview" section of the "Subscriptions" blade in the [Azure portal](https://portal.azure.com/).
+2. Define `TENANT_ID`, `CLIENT_ID`, and `CLIENT_SECRET`, which are available after creating a Service Principal or can be retrieved from the Azure Portal after creating a Service Principal. Check out the [Azure docs](https://docs.microsoft.com/cli/azure/ad/sp?view=azure-cli-latest#az_ad_sp_create_for_rbac) to create  a Service Principal with a simple one line command to create one. The recommended practice is to include your alias or name in the Service Principal name.
+3. Change the [`get_azure_core_credentials(**kwargs):`](https://github.com/Azure/azure-sdk-for-python/blob/master/tools/azure-sdk-tools/devtools_testutils/mgmt_settings_fake.py#L39-L53) function in the `mgmt_settings_real.py` file to construct and return a `ClientSecretCredential` object. Pass in the `CLIENT_ID`, `CLIENT_SECRET`, and `TENANT_ID` values to the `ClientSecretCredential` object. This method should look like this:
 ```python
 def get_azure_core_credentials(**kwargs):
     from azure.identity import ClientSecretCredential

doc/dev/tests.md

@@ -11,6 +11,7 @@ In this document we will provide the introduction to the testing framework by:
 - [Write our test](#writing-your-test)
 - [An example test](#an-example-test)
 - [Run and record our tests](#run-and-record-the-test)
+    -[Purging secrets from recording files](#purging-secrets)
 
 ## Setup your development environment
 
@@ -266,6 +267,14 @@ From your terminal run the `pytest` command to run all the tests that you have w
 
 Your update should run smooth and have green dots representing passing tests. Now if you look at the contents of your `tests` directory there should be a new directory called `recording` with four `.yaml` files. Each `yaml` file is a recording for a single test. To run a test in playback mode change the `testsettings_local.cfg` to `live-mode: false` and rerun the tests with the same command. The test infrastructure will use the automatically created `.yaml` recordings to mock the HTTP traffic and run the tests.
 
+### Purging Secrets
+
+The `yaml` files created from running tests in live mode store the request and response interactions between the library and the service and this can include authorization, account names, shared access signatures, and other secrets. The recordings are included in our public GitHub repository, making it important for us to remove any secrets from these recordings before committing them to the repository. There are two easy ways to remove secrets. The first is the `PowerShellPreparer` implementation, discussed above. This method will automatically purge the keys with the provided fake values. The second way is to use the `self.scrubber.register_name_pair(key, fake_key)` method (This method is a function of the base `AzureTestCase` class), which is used when a secret is dynamically created during a test. For example, [Tables](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/tables/azure-data-tables/tests/_shared/cosmos_testcase.py#L86-L89) uses this method to replace storage account names with standard names.
+
+#### Special Case: Shared Access Signature
+
+Tests that use the Shared Access Signature (SAS) to authenticate a client should use the [`AzureTestCase.generate_sas`](https://github.com/Azure/azure-sdk-for-python/blob/master/tools/azure-sdk-tools/devtools_testutils/azure_testcase.py#L357-L370) method to generate the SAS and purge the value from the recordings. An example of using this method can be found [here](https://github.com/Azure/azure-sdk-for-python/blob/78650ba08523c14227ce8139cba5f4d1e6ed7956/sdk/tables/azure-data-tables/tests/test_table_entity.py#L1628-L1636). The method takes any number of positional arguments, with the first being the method that creates the SAS, and any number of keyword arguments (**kwargs). The method will be purged appropriately and allow for these tests to be run in playback mode.
+
 ## Functional vs. Unit Tests
 
 The test written above is a functional test, it generates HTTP traffic and sends data to the service. Most of our clients have some client-side validation for account names, formatting, or properties that do not generate HTTP traffic. For unit tests, the best practice is to have a separate test class from the `AzureTestCase` class which tests client side validation methods. For example, the `azure-data-tables` library has client-side validation for the table name and properties of the entity, below is an example of how these could be tested: