[formrecognizer] Beta work

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

@@ -1,14 +1,24 @@
 # Release History
 
-## 3.1.3 (Unreleased)
+## 3.2.0b1 (Unreleased)
+
+This version of the SDK defaults to the latest supported API version, which currently is v2021-09-30-preview.
 
 ### Features Added
+- Added new `DocumentAnalysisClient` with  `begin_analyze_document` and `begin_analyze_document_from_url` methods. Use these methods with the latest Form Recognizer 
+API version to analyze documents, with prebuilt and custom models.
+- Added new models to use with the new `DocumentAnalysisClient`: `AnalyzeResult`, `AnalyzedDocument`, `BoundingRegion`, `DocumentElement`, `DocumentEntity`, `DocumentField`, `DocumentKeyValuePair`, `DocumentKeyValueElement`, `DocumentLine`, `DocumentPage`, `DocumentSelectionMark`, `DocumentSpan`, `DocumentStyle`, `DocumentTable`, `DocumentTableCell`, `DocumentWord`.
+- Added new `DocumentModelAdministrationClient` with methods: `begin_build_model`, `begin_create_composed_model`, `begin_copy_model`, `get_copy_authorization`, `get_model`, `delete_model`, `list_models`, `get_operation`, `list_operations`, `get_account_info`, `get_document_analysis_client`.
+- Added new models to use with the new `DocumentModelAdministrationClient`: `DocumentModel`, `DocumentModelInfo`, `DocTypeInfo`, `ModelOperation`, `ModelOperationInfo`, `AccountInfo`.
+- Added samples using the `DocumentAnalysisClient` and `DocumentModelAdministrationClient` under `/samples/v3.2-beta`.
+- Added `DocumentAnalysisApiVersion` to be used with `DocumentAnalysisClient` and `DocumentModelAdministrationClient`.
 
 ### Breaking Changes
 
 ### Bugs Fixed
 
 ### Other Changes
+- Python 3.5 is no longer supported in this release.
 
 ## 3.1.2 (2021-08-10)
 

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

@@ -16,7 +16,7 @@ from form documents. It includes the following main functionalities:
 ## Getting started
 
 ### Prerequisites
-* Python 2.7, or 3.5 or later is required to use this package.
+* Python 2.7, or 3.6 or later is required to use this package.
 * You must have an [Azure subscription][azure_subscription] and a
 [Cognitive Services or Form Recognizer resource][FR_or_CS_resource] to use this package.
 
@@ -436,7 +436,7 @@ These code samples show common scenario operations with the Azure Form Recognize
 * Create a composed model from a collection of models trained with labels: [sample_create_composed_model.py][sample_create_composed_model]
 
 ### Async APIs
-This library also includes a complete async API supported on Python 3.5+. To use it, you must
+This library also includes a complete async API supported on Python 3.6+. To use it, you must
 first install an async transport, such as [aiohttp](https://pypi.org/project/aiohttp/). Async clients
 are found under the `azure.ai.formrecognizer.aio` namespace.
 
@@ -507,29 +507,31 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
 [coc_contact]: mailto:opencode@microsoft.com
 
-[sample_authentication]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_authentication.py
-[sample_authentication_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_authentication_async.py
-[sample_manage_custom_models]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_manage_custom_models.py
-[sample_manage_custom_models_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_manage_custom_models_async.py
-[sample_recognize_content]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_content.py
-[sample_recognize_content_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_content_async.py
-[sample_recognize_custom_forms]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_custom_forms.py
-[sample_recognize_custom_forms_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_custom_forms_async.py
-[sample_recognize_receipts_from_url]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_receipts_from_url.py
-[sample_recognize_receipts_from_url_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_receipts_from_url_async.py
-[sample_recognize_receipts]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_receipts.py
-[sample_recognize_receipts_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_receipts_async.py
-[sample_recognize_business_cards]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_business_cards.py
-[sample_recognize_business_cards_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_business_cards_async.py
-[sample_recognize_invoices]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_invoices.py
-[sample_recognize_invoices_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_invoices_async.py
-[sample_recognize_identity_documents]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_recognize_identity_documents.py
-[sample_recognize_identity_documents_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_recognize_identity_documents_async.py
-[sample_train_model_with_labels]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_train_model_with_labels.py
-[sample_train_model_with_labels_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_train_model_with_labels_async.py
-[sample_train_model_without_labels]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_train_model_without_labels.py
-[sample_train_model_without_labels_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_train_model_without_labels_async.py
-[sample_copy_model]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_copy_model.py
-[sample_copy_model_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_copy_model_async.py
-[sample_create_composed_model]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/sample_create_composed_model.py
-[sample_create_composed_model_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/async_samples/sample_create_composed_model_async.py
+<!-- TODO re-enable when in public repo
+[sample_authentication]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_authentication.py
+[sample_authentication_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_authentication_async.py
+[sample_manage_custom_models]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_manage_custom_models.py
+[sample_manage_custom_models_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_manage_custom_models_async.py
+[sample_recognize_content]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_recognize_content.py
+[sample_recognize_content_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_recognize_content_async.py
+[sample_recognize_custom_forms]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_recognize_custom_forms.py
+[sample_recognize_custom_forms_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_recognize_custom_forms_async.py
+[sample_recognize_receipts_from_url]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_recognize_receipts_from_url.py
+[sample_recognize_receipts_from_url_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_recognize_receipts_from_url_async.py
+[sample_recognize_receipts]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_recognize_receipts.py
+[sample_recognize_receipts_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_recognize_receipts_async.py
+[sample_recognize_business_cards]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_recognize_business_cards.py
+[sample_recognize_business_cards_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_recognize_business_cards_async.py
+[sample_recognize_invoices]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_recognize_invoices.py
+[sample_recognize_invoices_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_recognize_invoices_async.py
+[sample_recognize_identity_documents]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_recognize_identity_documents.py
+[sample_recognize_identity_documents_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_recognize_identity_documents_async.py
+[sample_train_model_with_labels]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_train_model_with_labels.py
+[sample_train_model_with_labels_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_train_model_with_labels_async.py
+[sample_train_model_without_labels]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_train_model_without_labels.py
+[sample_train_model_without_labels_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_train_model_without_labels_async.py
+[sample_copy_model]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_copy_model.py
+[sample_copy_model_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_copy_model_async.py
+[sample_create_composed_model]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/sample_create_composed_model.py
+[sample_create_composed_model_async]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/samples/v2/async_samples/sample_create_composed_model_async.py
+-->

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

@@ -7,6 +7,9 @@
 from ._version import VERSION
 from ._form_recognizer_client import FormRecognizerClient
 from ._form_training_client import FormTrainingClient
+from ._document_analysis_client import DocumentAnalysisClient
+from ._document_model_administration_client import DocumentModelAdministrationClient
+from ._polling import DocumentModelAdministrationLROPoller
 from ._models import (
     FormElement,
     LengthUnit,
@@ -34,12 +37,36 @@
     CustomFormModelProperties,
     FormSelectionMark,
     TextAppearance,
+    AnalyzeResult,
+    AnalyzedDocument,
+    BoundingRegion,
+    DocumentElement,
+    DocumentEntity,
+    DocumentField,
+    DocumentKeyValuePair,
+    DocumentKeyValueElement,
+    DocumentLine,
+    DocumentPage,
+    DocumentSelectionMark,
+    DocumentSpan,
+    DocumentStyle,
+    DocumentTable,
+    DocumentTableCell,
+    DocumentWord,
+    ModelOperationInfo,
+    ModelOperation,
+    DocumentModel,
+    DocumentModelInfo,
+    DocTypeInfo,
+    AccountInfo
 )
-from ._api_versions import FormRecognizerApiVersion
+from ._api_versions import FormRecognizerApiVersion, DocumentAnalysisApiVersion
 
 
 __all__ = [
     "FormRecognizerApiVersion",
+    "DocumentAnalysisClient",
+    "DocumentModelAdministrationClient",
     "FormRecognizerClient",
     "FormTrainingClient",
     "LengthUnit",
@@ -68,6 +95,30 @@
     "CustomFormModelProperties",
     "FormSelectionMark",
     "TextAppearance",
+    "AnalyzeResult",
+    "AnalyzedDocument",
+    "BoundingRegion",
+    "DocumentElement",
+    "DocumentEntity",
+    "DocumentField",
+    "DocumentKeyValueElement",
+    "DocumentKeyValuePair",
+    "DocumentLine",
+    "DocumentPage",
+    "DocumentSelectionMark",
+    "DocumentSpan",
+    "DocumentStyle",
+    "DocumentTable",
+    "DocumentTableCell",
+    "DocumentWord",
+    "DocumentModelAdministrationLROPoller",
+    "ModelOperationInfo",
+    "ModelOperation",
+    "DocumentAnalysisApiVersion",
+    "DocumentModel",
+    "DocumentModelInfo",
+    "DocTypeInfo",
+    "AccountInfo"
 ]
 
 __VERSION__ = VERSION

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

@@ -6,25 +6,54 @@
 from enum import Enum
 
 
+class DocumentAnalysisApiVersion(str, Enum):
+    """Form Recognizer API versions supported by DocumentAnalysisClient and DocumentModelAdministrationClient."""
+
+    #: This is the default version
+    V2021_09_30_PREVIEW = "2021-09-30-preview"
+
+
 class FormRecognizerApiVersion(str, Enum):
-    """Form Recognizer API versions supported by this package"""
+    """Form Recognizer API versions supported by FormRecognizerClient and FormTrainingClient."""
 
     #: This is the default version
     V2_1 = "2.1"
     V2_0 = "2.0"
 
 
-def validate_api_version(api_version):
-    # type: (str) -> None
+def validate_api_version(api_version, client_kind):
+    # type: (str, str) -> None
     """Raise ValueError if api_version is invalid """
-    if not api_version:
-        return
-
-    try:
-        api_version = FormRecognizerApiVersion(api_version)
-    except ValueError:
-        raise ValueError(
-            "Unsupported API version '{}'. Please select from:\n{}".format(
+
+    if client_kind == "form":
+        try:
+            api_version = FormRecognizerApiVersion(api_version)
+        except ValueError:
+            err_message = "Unsupported API version '{}'. Please select from: {}".format(
                 api_version, ", ".join(v.value for v in FormRecognizerApiVersion)
             )
-        )
+            try:
+                api_version = DocumentAnalysisApiVersion(api_version)
+                err_message += (
+                    "\nAPI version '{}' is only available for "
+                    "DocumentAnalysisClient and DocumentModelAdministrationClient.".format(api_version)
+                )
+            except ValueError:
+                pass
+            raise ValueError(err_message)
+    else:
+        try:
+            api_version = DocumentAnalysisApiVersion(api_version)
+        except ValueError:
+            err_message = "Unsupported API version '{}'. Please select from: {}".format(
+                api_version, ", ".join(v.value for v in DocumentAnalysisApiVersion)
+            )
+            try:
+                api_version = FormRecognizerApiVersion(api_version)
+                err_message += (
+                    "\nAPI version '{}' is only available for "
+                    "FormRecognizerClient and FormTrainingClient.".format(api_version)
+                )
+            except ValueError:
+                pass
+            raise ValueError(err_message)