Merge pull request #5 from Azure/main

Update 7/9

Author: BigCat20196

common/smoketest/requirements_async.txt

@@ -1 +1 @@
-aiohttp==3.5.4
+aiohttp==3.7.4

doc/dev/debug_guide.md

@@ -0,0 +1,23 @@
+# Debug
+
+This guide is to help Python SDK users to get the process about how SDK call REST api
+
+(1) Copy the following code in your .py file
+```
+import sys
+import logging
+
+logger = logging.getLogger('')
+logger.setLevel(logging.DEBUG)
+handler = logging.StreamHandler(stream=sys.stdout, )
+logger.addHandler(handler)
+formatter = logging.Formatter(
+    '%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+handler.setFormatter(formatter)
+```
+
+![Position example](./debug_guide_position.png "Position example")
+
+(2) Run your .py program and you could find the log info in screen. It is convenient to get the process about how SDK call REST api:
+
+![example](./debug_guide_example.png "example")

doc/dev/debug_guide_example.png

@@ -27,7 +27,6 @@ pyOpenSSL==19.1.0
 json-delta==2.0
 ConfigArgParse==1.2.3
 six==1.14.0
-vcrpy==3.0.0
 pyyaml==5.3.1
 pytest==5.4.2; python_version >= '3.5'
 pytest==4.6.9; python_version == '2.7'

doc/dev/debug_guide_position.png

@@ -119,6 +119,26 @@ function MergeHashes([hashtable] $source, [psvariable] $dest) {
     }
 }
 
+function BuildBicepFile([System.IO.FileSystemInfo] $file) {
+    if (!(Get-Command bicep -ErrorAction Ignore)) {
+        Write-Error "A bicep file was found at '$($file.FullName)' but the Azure Bicep CLI is not installed. See https://aka.ms/install-bicep-pwsh"
+        throw
+    }
+
+    $tmp = $env:TEMP ? $env:TEMP : [System.IO.Path]::GetTempPath()
+    $templateFilePath = Join-Path $tmp "test-resources.$(New-Guid).compiled.json"
+
+    # Az can deploy bicep files natively, but by compiling here it becomes easier to parse the
+    # outputted json for mismatched parameter declarations.
+    bicep build $file.FullName --outfile $templateFilePath
+    if ($LASTEXITCODE) {
+        Write-Error "Failure building bicep file '$($file.FullName)'"
+        throw
+    }
+
+    return $templateFilePath
+}
+
 # Support actions to invoke on exit.
 $exitActions = @({
     if ($exitActions.Count -gt 1) {
@@ -140,15 +160,18 @@ try {
     # Enumerate test resources to deploy. Fail if none found.
     $repositoryRoot = "$PSScriptRoot/../../.." | Resolve-Path
     $root = [System.IO.Path]::Combine($repositoryRoot, "sdk", $ServiceDirectory) | Resolve-Path
-    $templateFileName = 'test-resources.json'
     $templateFiles = @()
 
-    Write-Verbose "Checking for '$templateFileName' files under '$root'"
-    Get-ChildItem -Path $root -Filter $templateFileName -Recurse | ForEach-Object {
-        $templateFile = $_.FullName
-
-        Write-Verbose "Found template '$templateFile'"
-        $templateFiles += $templateFile
+    'test-resources.json', 'test-resources.bicep' | ForEach-Object {
+        Write-Verbose "Checking for '$_' files under '$root'"
+        Get-ChildItem -Path $root -Filter "$_" -Recurse | ForEach-Object {
+            Write-Verbose "Found template '$($_.FullName)'"
+            if ($_.Extension -eq '.bicep') {
+                $templateFiles += (BuildBicepFile $_)
+            } else {
+                $templateFiles += $_.FullName
+            }
+        }
     }
 
     if (!$templateFiles) {
@@ -556,6 +579,11 @@ try {
             Log "Invoking post-deployment script '$postDeploymentScript'"
             &$postDeploymentScript -ResourceGroupName $ResourceGroupName -DeploymentOutputs $deploymentOutputs @PSBoundParameters
         }
+
+        if ($templateFile.EndsWith('.compiled.json')) {
+            Write-Verbose "Removing compiled bicep file $templateFile"
+            Remove-Item $templateFile
+        }
     }
 
 } finally {

eng/ci_tools.txt

@@ -58,3 +58,5 @@ steps:
         -Force `
         -Verbose | Out-Null
     displayName: Deploy test resources
+    env:
+      TEMP: $(Agent.TempDirectory)

eng/common/TestResources/New-TestResources.ps1

@@ -27,10 +27,10 @@ parameters:
   default: []
 - name: Pool
   type: string
-  default: azsdk-pool-mms-ubuntu-1804-general
+  default: azsdk-pool-mms-ubuntu-2004-general
 - name: OsVmImage
   type: string
-  default: MMSUbuntu18.04
+  default: MMSUbuntu20.04
 # This parameter is only necessary if there are multiple invocations of this template within the SAME STAGE.
 # When that occurs, provide a name other than the default value.
 - name: GenerateJobName

eng/common/TestResources/deploy-test-resources.yml

@@ -39,9 +39,15 @@ steps:
               Write-Host "Repository $($repository.Name) has already been initialized. Skipping this step."
             } else {
               Write-Host "Repository $($repository.Name) is being initialized."
+
+              Write-Host "git clone --no-checkout --filter=tree:0 git://github.com/$($repository.Name) ."
               git clone --no-checkout --filter=tree:0 git://github.com/$($repository.Name) .
+
+              Write-Host "git sparse-checkout init"
               git sparse-checkout init
-              git sparse-checkout set eng
+
+              Write-Host "git sparse-checkout set '/*' '!/*/' '/eng'"
+              git sparse-checkout set '/*' '!/*/' '/eng'
             }
 
             $gitsparsecmd = "git sparse-checkout add $paths"

eng/common/pipelines/templates/jobs/archetype-sdk-tests-generate.yml

@@ -18,7 +18,6 @@ pyOpenSSL==19.1.0
 json-delta==2.0
 ConfigArgParse==1.2.3
 six==1.14.0
-vcrpy==3.0.0
 pyyaml==5.3.1
 packaging==20.4
 wheel==0.34.2

eng/common/pipelines/templates/steps/sparse-checkout.yml

@@ -56,5 +56,6 @@
     "azure-purview-catalog",
     "azure-messaging-nspkg",
     "azure-agrifood-farming",
-    "azure-eventhub"
+    "azure-eventhub",
+    "azure-ai-language-questionanswering"
 ]

eng/test_tools.txt

@@ -0,0 +1,6 @@
+# Release History
+
+## 1.0.0b1 (unreleased)
+
+### Features Added
+* Initial release.

eng/tox/allowed_pylint_failures.py

@@ -0,0 +1,8 @@
+include _meta.json
+include *.md
+include azure/__init__.py
+include azure/ai/__init__.py
+include azure/ai/language/__init__.py
+recursive-include tests *.py
+recursive-include samples *.py *.md
+include azure/ai/language/questionanswering/py.typed

sdk/cognitivelanguage/azure-ai-language-questionanswering/CHANGELOG.md

@@ -0,0 +1,212 @@
+[![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/azure-sdk-for-python.client?branchName=main)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=46?branchName=main)
+
+# Azure Cognitive Language Services Question Answering client library for Python
+
+Question Answering is a cloud-based API service that lets you create a conversational question-and-answer layer over your existing data. Use it to build a knowledge base by extracting questions and answers from your semi-structured content, including FAQ, manuals, and documents. Answer users’ questions with the best answers from the QnAs in your knowledge base—automatically. Your knowledge base gets smarter, too, as it continually learns from users' behavior.
+
+[Source code][questionanswering_client_src] | [Package (PyPI)][questionanswering_pypi_package] | [API reference documentation][questionanswering_refdocs] | [Product documentation][questionanswering_docs] | [Samples][questionanswering_samples]
+
+## Getting started
+
+### Prerequisites
+
+* Python 2.7, or 3.6 or later is required to use this package.
+* An [Azure subscription][azure_subscription]
+* An existing Question Answering resource
+
+> Note: the new unified Cognitive Language Services are not currently available for deployment.
+
+### Install the package
+
+Install the Azure QuestionAnswering client library for Python with [pip][pip_link]:
+
+```bash
+pip install azure-ai-language-questionanswering
+```
+
+### Authenticate the client
+
+In order to interact with the Question Answering service, you'll need to create an instance of the [`QuestionAnsweringClient`][questionanswering_client_class] class. You will need an **endpoint**, and an **API key** instantiate a client object. For more information regarding authenticating with Cognitive Services, see [Authenticate requests to Azure Cognitive Services][cognitive_auth].
+
+#### Get an API key
+
+You can get the **endpoint** and an **API key** from the Cognitive Services resource or Question Answering resource in the [Azure Portal][azure_portal].
+
+Alternatively, use the [Azure CLI][azure_cli] command shown below to get the API key from the Question Answering resource.
+
+```powershell
+az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
+```
+
+#### Create QuestionAnsweringClient
+
+Once you've determined your **endpoint** and **API key** you can instantiate a `QuestionAnsweringClient`:
+
+```python
+from azure.core.credentials import AzureKeyCredential
+from azure.ai.language.questionanswering import QuestionAnsweringClient
+
+endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
+credential = AzureKeyCredential("{api-key}")
+
+client = QuestionAnsweringClient(endpoint, credential)
+```
+
+## Key concepts
+
+### QuestionAnsweringClient
+
+The [`QuestionAnsweringClient`][questionanswering_client_class] is the primary interface for asking questions using a knowledge base with your own information, or text input using pre-trained models. 
+For asynchronous operations, an async `QuestionAnsweringClient` is in the `azure.ai.language.questionanswering.aio` namespace.
+
+## Examples
+
+The `azure-ai-language-questionanswering` client library provides both synchronous and asynchronous APIs.
+
+The following examples show common scenarios using the `client` [created above](#create-questionansweringclient).
+- [Ask a question](#ask-a-question)
+- [Ask a follow-up question](#ask-a-follow-up-question)
+- [Asynchronous operations](#asynchronous-operations)
+
+### Ask a question
+
+The only input required to ask a question using a knowledgebase is just the question itself:
+
+```python
+from azure.ai.language.questionanswering import models as qna
+
+params = qna.KnowledgebaseQueryParameters(
+    question="How long should my Surface battery last?"
+)
+
+output = client.query_knowledgebase(
+    project_name="FAQ",
+    knowledgebase_query_parameters=params
+)
+for candidate in output.answers:
+    print("({}) {}".format(candidate.confidence_score, candidate.answer))
+    print("Source: {}".format(candidate.source))
+
+```
+
+You can set additional properties on `KnowledgebaseQueryParameters` to limit the number of answers, specify a minimum confidence score, and more.
+
+### Ask a follow-up question
+
+If your knowledgebase is configured for [chit-chat][questionanswering_docs_chat], you can ask a follow-up question provided the previous question-answering ID and, optionally, the exact question the user asked:
+
+```python
+params = qna.models.KnowledgebaseQueryParameters(
+    question="How long should charging take?"
+    context=qna.models.KnowledgebaseAnswerRequestContext(
+        previous_user_query="How long should my Surface battery last?",
+        previous_qna_id=previous_answer.id
+    )
+)
+
+output = client.query_knowledgebase(
+    project_name="FAQ",
+    knowledgebase_query_parameters=params
+)
+for candidate in output.answers:
+    print("({}) {}".format(candidate.confidence_score, candidate.answer))
+    print("Source: {}".format(candidate.source))
+
+```
+### Asynchronous operations
+
+The above examples can also be run asynchronously using the client in the `aio` namespace:
+```python
+from azure.core.credentials import AzureKeyCredential
+from azure.ai.language.questionanswering.aio import QuestionAnsweringClient
+from azure.ai.language.questionanswering import models as qna
+
+client = QuestionAnsweringClient(endpoint, credential)
+
+params = qna.KnowledgebaseQueryParameters(
+    question="How long should my Surface battery last?"
+)
+
+output = await client.query_knowledgebase(
+    project_name="FAQ",
+    knowledgebase_query_parameters=params
+)
+```
+
+## Optional Configuration
+Optional keyword arguments can be passed in at the client and per-operation level. The azure-core [reference documentation][azure_core_ref_docs] describes available configurations for retries, logging, transport protocols, and more.
+
+## Troubleshooting
+
+### General
+Azure QuestionAnswering clients raise exceptions defined in [Azure Core][azure_core_readme].
+When you interact with the Cognitive Language Services Question Answering client library using the .Python SDK, errors returned by the service correspond to the same HTTP status codes returned for [REST API][questionanswering_rest_docs] requests.
+
+For example, if you submit a question to a non-existant knowledge base, a `400` error is returned indicating "Bad Request".
+
+```python
+from azure.core.exceptions import HttpResponseError
+
+try:
+    client.query_knowledgebase(
+        project_name="invalid-knowledgebase",
+        knowledgebase_query_parameters=params
+    )
+except HttpResponseError as error:
+    print("Query failed: {}".format(error.message))
+```
+
+### Logging
+This library uses the standard
+[logging][python_logging] library for logging.
+Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO
+level.
+
+Detailed DEBUG level logging, including request/response bodies and unredacted
+headers, can be enabled on a client with the `logging_enable` argument.
+
+See full SDK logging documentation with examples [here][sdk_logging_docs].
+
+## Next steps
+
+* View our [samples][questionanswering_samples].
+* Read about the different [features][questionanswering_docs_features] of the Question Answering service.
+* Try our service [demos][questionanswering_docs_demos].
+
+## Contributing
+
+See the [CONTRIBUTING.md][contributing] for details on building, testing, and contributing to this library.
+
+This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla].
+
+When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [[email protected]][coc_contact] with any additional questions or comments.
+
+<!-- LINKS -->
+[azure_cli]: https://docs.microsoft.com/cli/azure/
+[azure_portal]: https://portal.azure.com/
+[azure_subscription]: https://azure.microsoft.com/free/
+[cla]: https://cla.microsoft.com
+[coc_contact]: mailto:[email protected]
+[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
+[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
+[cognitive_auth]: https://docs.microsoft.com/azure/cognitive-services/authentication/
+[contributing]: https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md
+[python_logging]: https://docs.python.org/3/library/logging.html
+[sdk_logging_docs]: https://docs.microsoft.com/azure/developer/python/azure-sdk-logging
+[azure_core_ref_docs]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/latest/azure.core.html
+[azure_core_readme]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
+[pip_link]:https://pypi.org/project/pip/
+[questionanswering_client_class]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_question_answering_client.py#L27
+[questionanswering_client_src]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/
+[questionanswering_docs]: https://azure.microsoft.com/services/cognitive-services/qna-maker/
+[questionanswering_docs_chat]: https://docs.microsoft.com/azure/cognitive-services/qnamaker/how-to/chit-chat-knowledge-base
+[questionanswering_docs_demos]: https://azure.microsoft.com/services/cognitive-services/qna-maker/#demo
+[questionanswering_docs_features]: https://azure.microsoft.com/services/cognitive-services/qna-maker/#features
+[questionanswering_pypi_package]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/
+[questionanswering_refdocs]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/
+[questionanswering_rest_docs]: https://docs.microsoft.com/rest/api/cognitiveservices-qnamaker/
+[questionanswering_samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/samples/README.md
+
+![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Ftemplate%2Fazure-template%2FREADME.png)

sdk/cognitivelanguage/azure-ai-language-questionanswering/MANIFEST.in

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

sdk/cognitivelanguage/azure-ai-language-questionanswering/README.md

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)

sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/__init__.py

@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)