[formrecognizer] add api version enum (#12888)

* add FormRecognizerApiVersion enum

* update test

* changelog

* update test

* updates

sdk/formrecognizer/azure-ai-formrecognizer/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 3.0.0b2 (Unreleased)
 
+**New features**
+
+- Client-level, keyword argument `api_version` can be used to specify the service API version to use. Currently only v2.0
+is supported. See the enum `FormRecognizerApiVersion` for supported API versions.
 
 ## 3.0.0b1 (2020-08-11)
 

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/__init__.py

@@ -33,9 +33,11 @@
     CustomFormModelField,
     FieldValueType
 )
+from ._api_versions import FormRecognizerApiVersion
 
 
 __all__ = [
+    "FormRecognizerApiVersion",
     'FormRecognizerClient',
     'FormTrainingClient',
     'LengthUnit',

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_api_versions.py

@@ -3,16 +3,25 @@
 # Licensed under the MIT License.
 # ------------------------------------
 
+from enum import Enum
+
+
+class FormRecognizerApiVersion(str, Enum):
+    """Form Recognizer service API versions supported by this package"""
+
+    V2_0 = "v2.0"
 
-_SUPPORTED_API_VERSIONS = [
-    "2.0",
-]
 
 def validate_api_version(api_version):
     # type: (str) -> None
-    """Raise error if api_version is invalid """
+    """Raise ValueError 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))
+
+    try:
+        api_version = FormRecognizerApiVersion(api_version)
+    except ValueError:
+        raise ValueError(
+            "Unsupported API version '{}'. Please select from:\n{}".format(
+                api_version, ", ".join(v.value for v in FormRecognizerApiVersion))
+        )

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_form_recognizer_client.py

@@ -45,9 +45,10 @@ class FormRecognizerClient(object):
         credential from :mod:`azure.identity`.
     :type credential: :class:`~azure.core.credentials.AzureKeyCredential` or
         :class:`~azure.core.credentials.TokenCredential`
-    :keyword str api_version:
+    :keyword api_version:
         The API version of the service to use for requests. It defaults to the latest service version.
         Setting to an older version may result in reduced feature compatibility.
+    :paramtype api_version: str or ~azure.ai.formrecognizer.FormRecognizerApiVersion
 
     .. admonition:: Example:
 

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_form_training_client.py

@@ -57,9 +57,10 @@ class FormTrainingClient(object):
         credential from :mod:`azure.identity`.
     :type credential: :class:`~azure.core.credentials.AzureKeyCredential` or
         :class:`~azure.core.credentials.TokenCredential`
-    :keyword str api_version:
+    :keyword api_version:
         The API version of the service to use for requests. It defaults to the latest service version.
         Setting to an older version may result in reduced feature compatibility.
+    :paramtype api_version: str or ~azure.ai.formrecognizer.FormRecognizerApiVersion
 
     .. admonition:: Example:
 

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/aio/_form_recognizer_client_async.py

@@ -46,9 +46,10 @@ class FormRecognizerClient(object):
         credential from :mod:`azure.identity`.
     :type credential: :class:`~azure.core.credentials.AzureKeyCredential`
         or :class:`~azure.core.credentials_async.AsyncTokenCredential`
-    :keyword str api_version:
+    :keyword api_version:
         The API version of the service to use for requests. It defaults to the latest service version.
         Setting to an older version may result in reduced feature compatibility.
+    :paramtype api_version: str or ~azure.ai.formrecognizer.FormRecognizerApiVersion
 
     .. admonition:: Example:
 

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/aio/_form_training_client_async.py

@@ -58,9 +58,10 @@ class FormTrainingClient(object):
         credential from :mod:`azure.identity`.
     :type credential: :class:`~azure.core.credentials.AzureKeyCredential`
         or :class:`~azure.core.credentials_async.AsyncTokenCredential`
-    :keyword str api_version:
+    :keyword api_version:
         The API version of the service to use for requests. It defaults to the latest service version.
         Setting to an older version may result in reduced feature compatibility.
+    :paramtype api_version: str or ~azure.ai.formrecognizer.FormRecognizerApiVersion
 
     .. admonition:: Example:
 

sdk/formrecognizer/azure-ai-formrecognizer/tests/test_mgmt.py

@@ -8,7 +8,7 @@
 from azure.core.credentials import AzureKeyCredential
 from azure.core.exceptions import ResourceNotFoundError, ClientAuthenticationError
 from azure.core.pipeline.transport import RequestsTransport
-from azure.ai.formrecognizer import FormTrainingClient
+from azure.ai.formrecognizer import FormTrainingClient, FormRecognizerApiVersion
 from testcase import FormRecognizerTest, GlobalFormRecognizerAccountPreparer
 from testcase import GlobalClientPreparer as _GlobalClientPreparer
 
@@ -164,6 +164,8 @@ def test_get_form_recognizer_client(self, resource_group, location, form_recogni
     @GlobalFormRecognizerAccountPreparer()
     def test_api_version_form_training_client(self, resource_group, location, form_recognizer_account, form_recognizer_account_key):
         with self.assertRaises(ValueError):
-            ftc = FormTrainingClient(endpoint=form_recognizer_account, credential=AzureKeyCredential(form_recognizer_account_key), api_version="2.1")
-
-        ftc = FormTrainingClient(endpoint=form_recognizer_account, credential=AzureKeyCredential(form_recognizer_account_key), api_version="2.0")
+            ftc = FormTrainingClient(endpoint=form_recognizer_account, credential=AzureKeyCredential(form_recognizer_account_key), api_version="v9.1")
+
+        # these do not raise
+        ftc = FormTrainingClient(endpoint=form_recognizer_account, credential=AzureKeyCredential(form_recognizer_account_key), api_version="v2.0")
+        ftc = FormTrainingClient(endpoint=form_recognizer_account, credential=AzureKeyCredential(form_recognizer_account_key), api_version=FormRecognizerApiVersion.V2_0)