update version number and API_version support

sdk/search/azure-search-documents/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Release History
 
+## 11.0.0 (2020-07-07)
+
+**Features**
+
+- Exposed more models:
+
+  * BM25SimilarityAlgorithm
+  * ClassicSimilarityAlgorithm
+  * EdgeNGramTokenFilterSide
+  * EntityCategory
+  * EntityRecognitionSkillLanguage
+  * FieldMapping
+  * FieldMappingFunction
+  * ImageAnalysisSkillLanguage
+  * ImageDetail
+  * IndexerExecutionStatus
+  * IndexerStatus
+  * KeyPhraseExtractionSkillLanguage
+  * MicrosoftStemmingTokenizerLanguage
+  * MicrosoftTokenizerLanguage
+  * OcrSkillLanguage
+  * PhoneticEncoder
+  * ScoringFunctionAggregation
+  * ScoringFunctionInterpolation
+
 ## 1.0.0b4 (2020-06-09)
 
 **Breaking Changes**
@@ -10,18 +35,18 @@
 - Now Search Synonym Map creation/update returns a model    #11514
 - Renaming  #11565
 
-  SearchIndexerDataSource -> SearchIndexerDataSourceConnection
-  SearchField.SynonymMaps -> SearchField.SynonymMapNames
-  SearchField.Analyzer -> SearchField.AnalyzerName
-  SearchField.IndexAnalyzer -> SearchField.IndexAnalyzerName
-  SearchField.SearchAnalyzer -> SearchField.SearchAnalyzerName
-  SearchableField.SynonymMaps -> SearchableField.SynonymMapNames
-  SearchableField.Analyzer -> SearchableField.AnalyzerName
-  SearchableField.IndexAnalyzer -> SearchableField.IndexAnalyzerName
-  SearchableField.SearchAnalyzer -> SearchableField.SearchAnalyzerName
-  Similarity -> SimilarityAlgorithm
-  Suggester -> SearchSuggester
-  PathHierarchyTokenizerV2 -> PathHierarchyTokenizer
+  * SearchIndexerDataSource -> SearchIndexerDataSourceConnection
+  * SearchField.SynonymMaps -> SearchField.SynonymMapNames
+  * SearchField.Analyzer -> SearchField.AnalyzerName
+  * SearchField.IndexAnalyzer -> SearchField.IndexAnalyzerName
+  * SearchField.SearchAnalyzer -> SearchField.SearchAnalyzerName
+  * SearchableField.SynonymMaps -> SearchableField.SynonymMapNames
+  * SearchableField.Analyzer -> SearchableField.AnalyzerName
+  * SearchableField.IndexAnalyzer -> SearchableField.IndexAnalyzerName
+  * SearchableField.SearchAnalyzer -> SearchableField.SearchAnalyzerName
+  * Similarity -> SimilarityAlgorithm
+  * Suggester -> SearchSuggester
+  * PathHierarchyTokenizerV2 -> PathHierarchyTokenizer
 - Renamed DataSource methods to DataSourceConnection    #11693
 - Autocomplete & suggest methods now takes arguments search_text & suggester_name rather than query objects   #11747
 - Create_or_updates methods does not support partial updates    #11800

sdk/search/azure-search-documents/README.md

@@ -133,7 +133,7 @@ client = SearchClient(endpoint=endpoint,
                       credential=credential)
 
 # Let's get the top 5 jobs related to Microsoft
-results = client.search(search_text="Microsoft", include_total_result_count=5)
+results = client.search(search_text="Microsoft", top=5)
 
 for result in results:
     # Print out the title and job description
@@ -325,6 +325,27 @@ print("Upload of new document succeeded: {}".format(result[0].succeeded))
 ```
 
 
+### Async APIs
+This library includes a complete async API supported on Python 3.5+. To use it, you must
+first install an async transport, such as [aiohttp](https://pypi.org/project/aiohttp/).
+See
+[azure-core documentation](https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/README.md#transport)
+for more information.
+
+
+```py
+from azure.core.credentials import AzureKeyCredential
+from azure.search.documents.aio import SearchClient
+
+client = SearchClient(endpoint, index_name, AzureKeyCredential(api_key))
+
+async with client:
+  results = await client.search(search_text="hotel")
+  async for result in results:
+    print("{}: {})".format(result["hotelId"], result["hotelName"]))
+...
+
+
 ## Troubleshooting
 
 ### General

sdk/search/azure-search-documents/azure/search/documents/_api_versions.py

@@ -0,0 +1,24 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+_SUPPORTED_API_VERSIONS = [
+    "2019-05-06-Preview",
+]
+
+def validate_api_version(api_version):
+    # type: (str) -> None
+    """Raise error if api_version is invalid """
+    if not api_version:
+        return
+    if api_version not in _SUPPORTED_API_VERSIONS:
+        versions = '\n'.join(_SUPPORTED_API_VERSIONS)
+        raise ValueError("Unsupported API version '{}'. Please select from:\n{}".format(api_version, versions))
+
+
+def get_api_version(kwargs, default):
+    # type: (Dict[str, Any], str) -> str
+    api_version = kwargs.pop('api_version', None)
+    validate_api_version(api_version)
+    return api_version or default

sdk/search/azure-search-documents/azure/search/documents/_internal/_search_client.py

@@ -8,6 +8,7 @@
 import six
 
 from azure.core.tracing.decorator import distributed_trace
+from .._api_versions import validate_api_version
 from ._generated import SearchIndexClient
 from ._generated.models import IndexBatch, IndexingResult
 from ._index_documents_batch import IndexDocumentsBatch
@@ -59,6 +60,7 @@ class SearchClient(HeadersMixin):
     :type index_name: str
     :param credential: A credential to authorize search client requests
     :type credential: ~azure.core.credentials.AzureKeyCredential
+    :keyword str api_version: The Search API version to use for requests.
 
     .. admonition:: Example:
 
@@ -75,6 +77,8 @@ class SearchClient(HeadersMixin):
     def __init__(self, endpoint, index_name, credential, **kwargs):
         # type: (str, str, AzureKeyCredential, **Any) -> None
 
+        api_version = kwargs.pop('api_version', None)
+        validate_api_version(api_version)
         self._endpoint = endpoint  # type: str
         self._index_name = index_name  # type: str
         self._credential = credential  # type: AzureKeyCredential
@@ -138,6 +142,54 @@ def search(self, search_text, **kwargs):
 
         :param str search_text: A full-text search query expression; Use "*" or omit this parameter to
         match all documents.
+        :keyword bool include_total_count: A value that specifies whether to fetch the total count of
+        results. Default is false. Setting this value to true may have a performance impact. Note that
+        the count returned is an approximation.
+        :keyword list[str] facets: The list of facet expressions to apply to the search query. Each facet
+         expression contains a field name, optionally followed by a comma-separated list of name:value
+         pairs.
+        :keyword str filter: The OData $filter expression to apply to the search query.
+        :keyword list[str] highlight_fields: The list of field names to use for hit highlights. Only searchable
+         fields can be used for hit highlighting.
+        :keyword str highlight_post_tag: A string tag that is appended to hit highlights. Must be set with
+         highlightPreTag. Default is </em>.
+        :keyword str highlight_pre_tag: A string tag that is prepended to hit highlights. Must be set with
+         highlightPostTag. Default is <em>.
+        :keyword float minimum_coverage: A number between 0 and 100 indicating the percentage of the index that
+         must be covered by a search query in order for the query to be reported as a success. This
+         parameter can be useful for ensuring search availability even for services with only one
+         replica. The default is 100.
+        :keyword list[str] order_by: The list of OData $orderby expressions by which to sort the results. Each
+         expression can be either a field name or a call to either the geo.distance() or the
+         search.score() functions. Each expression can be followed by asc to indicate ascending, and
+         desc to indicate descending. The default is ascending order. Ties will be broken by the match
+         scores of documents. If no OrderBy is specified, the default sort order is descending by
+         document match score. There can be at most 32 $orderby clauses.
+        :keyword query_type: A value that specifies the syntax of the search query. The default is
+         'simple'. Use 'full' if your query uses the Lucene query syntax. Possible values include:
+         'simple', 'full'.
+        :paramtype query_type: str or ~search_index_client.models.QueryType
+        :keyword list[str] scoring_parameters: The list of parameter values to be used in scoring functions (for
+         example, referencePointParameter) using the format name-values. For example, if the scoring
+         profile defines a function with a parameter called 'mylocation' the parameter string would be
+         "mylocation--122.2,44.8" (without the quotes).
+        :keyword str scoring_profile: The name of a scoring profile to evaluate match scores for matching
+         documents in order to sort the results.
+        :keyword list[str] search_fields: The list of field names to which to scope the full-text search. When
+         using fielded search (fieldName:searchExpression) in a full Lucene query, the field names of
+         each fielded search expression take precedence over any field names listed in this parameter.
+        :keyword search_mode: A value that specifies whether any or all of the search terms must be
+         matched in order to count the document as a match. Possible values include: 'any', 'all'.
+        :paramtype search_mode: str or ~search_index_client.models.SearchMode
+        :keyword list[str] select: The list of fields to retrieve. If unspecified, all fields marked as retrievable
+         in the schema are included.
+        :keyword int skip: The number of search results to skip. This value cannot be greater than 100,000.
+         If you need to scan documents in sequence, but cannot use $skip due to this limitation,
+         consider using $orderby on a totally-ordered key and $filter with a range query instead.
+        :keyword int top: The number of search results to retrieve. This can be used in conjunction with
+         $skip to implement client-side paging of search results. If results are truncated due to
+         server-side paging, the response will include a continuation token that can be used to issue
+         another Search request for the next page of results.
         :rtype:  SearchItemPaged[dict]
 
         .. admonition:: Example:
@@ -167,7 +219,7 @@ def search(self, search_text, **kwargs):
                 :dedent: 4
                 :caption: Get search result facets.
         """
-        include_total_result_count = kwargs.pop("include_total_result_count", None)
+        include_total_result_count = kwargs.pop("include_total_count", None)
         facets = kwargs.pop("facets", None)
         filter_arg = kwargs.pop("filter", None)
         highlight_fields = kwargs.pop("highlight_fields", None)
@@ -217,6 +269,32 @@ def suggest(self, search_text, suggester_name, **kwargs):
         character, and no more than 100 characters.
         :param str suggester_name: Required. The name of the suggester as specified in the suggesters
         collection that's part of the index definition.
+        :keyword str filter: An OData expression that filters the documents considered for suggestions.
+        :keyword bool use_fuzzy_matching: A value indicating whether to use fuzzy matching for the suggestions
+         query. Default is false. When set to true, the query will find terms even if there's a
+         substituted or missing character in the search text. While this provides a better experience in
+         some scenarios, it comes at a performance cost as fuzzy suggestions queries are slower and
+         consume more resources.
+        :keyword str highlight_post_tag: A string tag that is appended to hit highlights. Must be set with
+         highlightPreTag. If omitted, hit highlighting of suggestions is disabled.
+        :keyword str highlight_pre_tag: A string tag that is prepended to hit highlights. Must be set with
+         highlightPostTag. If omitted, hit highlighting of suggestions is disabled.
+        :keyword float minimum_coverage: A number between 0 and 100 indicating the percentage of the index that
+         must be covered by a suggestions query in order for the query to be reported as a success. This
+         parameter can be useful for ensuring search availability even for services with only one
+         replica. The default is 80.
+        :keyword list[str] order_by: The list of OData $orderby expressions by which to sort the results. Each
+         expression can be either a field name or a call to either the geo.distance() or the
+         search.score() functions. Each expression can be followed by asc to indicate ascending, or desc
+         to indicate descending. The default is ascending order. Ties will be broken by the match scores
+         of documents. If no $orderby is specified, the default sort order is descending by document
+         match score. There can be at most 32 $orderby clauses.
+        :keyword list[str] search_fields: The list of field names to search for the specified search text. Target
+         fields must be included in the specified suggester.
+        :keyword list[str] select: The list of fields to retrieve. If unspecified, only the key field will be
+         included in the results.
+        :keyword int top: The number of suggestions to retrieve. The value must be a number between 1 and
+         100. The default is 5.
         :rtype:  List[dict]
 
         .. admonition:: Example:
@@ -266,6 +344,29 @@ def autocomplete(self, search_text, suggester_name, **kwargs):
         :param str search_text: The search text on which to base autocomplete results.
         :param str suggester_name: The name of the suggester as specified in the suggesters
         collection that's part of the index definition.
+        :keyword mode: Specifies the mode for Autocomplete. The default is 'oneTerm'. Use
+         'twoTerms' to get shingles and 'oneTermWithContext' to use the current context while producing
+         auto-completed terms. Possible values include: 'oneTerm', 'twoTerms', 'oneTermWithContext'.
+        :paramtype mode: str or ~search_index_client.models.AutocompleteMode
+        :keyword str filter: An OData expression that filters the documents used to produce completed terms
+         for the Autocomplete result.
+        :keyword bool use_fuzzy_matching: A value indicating whether to use fuzzy matching for the
+         autocomplete query. Default is false. When set to true, the query will find terms even if
+         there's a substituted or missing character in the search text. While this provides a better
+         experience in some scenarios, it comes at a performance cost as fuzzy autocomplete queries are
+         slower and consume more resources.
+        :keyword str highlight_post_tag: A string tag that is appended to hit highlights. Must be set with
+         highlightPreTag. If omitted, hit highlighting is disabled.
+        :keyword str highlight_pre_tag: A string tag that is prepended to hit highlights. Must be set with
+         highlightPostTag. If omitted, hit highlighting is disabled.
+        :keyword float minimum_coverage: A number between 0 and 100 indicating the percentage of the index that
+         must be covered by an autocomplete query in order for the query to be reported as a success.
+         This parameter can be useful for ensuring search availability even for services with only one
+         replica. The default is 80.
+        :keyword list[str] search_fields: The list of field names to consider when querying for auto-completed
+         terms. Target fields must be included in the specified suggester.
+        :keyword int top: The number of auto-completed terms to retrieve. This must be a value between 1 and
+         100. The default is 5.
         :rtype:  List[dict]
 
         .. admonition:: Example:
@@ -277,7 +378,7 @@ def autocomplete(self, search_text, suggester_name, **kwargs):
                 :dedent: 4
                 :caption: Get a auto-completions.
         """
-        autocomplete_mode = kwargs.pop("autocomplete_mode", None)
+        autocomplete_mode = kwargs.pop("mode", None)
         filter_arg = kwargs.pop("filter", None)
         use_fuzzy_matching = kwargs.pop("use_fuzzy_matching", None)
         highlight_post_tag = kwargs.pop("highlight_post_tag", None)