| Name | azure-ai-textanalytics-authoring JSON |
| Version |
1.0.0b1
JSON |
| download |
| home_page | None |
| Summary | Microsoft Corporation Azure Ai Textanalytics Authoring Client Library for Python |
| upload_time | 2025-09-19 22:32:38 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
azure
azure sdk
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
[](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=46?branchName=main)
# Azure Text Authoring client library for Python
**Text Authoring** is part of Azure AI Language. It provides APIs and SDKs to **create, manage, train, evaluate, and deploy** text projects and models (for example, custom single/multi-label classification). With the `TextAuthoringClient`, you can automate much of what you’d otherwise do in Language Studio, including:
- **Project management**: Create, update, export, and import projects.
- **Training jobs**: Start, monitor, and cancel model training jobs.
- **Evaluation**: Retrieve model evaluation summaries and document-level results.
- **Deployments**: Create, update, swap, and delete deployments.
- **Snapshots**: Load a trained model snapshot back into a project.
- **Resource assignment**: Assign or unassign Azure resources to a deployment.
[Source code][text_authoring_client_src]
| [Package (PyPI)][text_authoring_pypi_package]
| [API reference][api_reference_authoring]
| [Samples][text_authoring_samples]
| [Product docs][text_authoring_docs]
| [REST API docs][text_authoring_restdocs]
---
## Getting started
### Prerequisites
- Python 3.7 or later
- An [Azure subscription][azure_subscription]
- An Azure AI [Language resource][language_resource]
### Install the package
Install the Azure Text Authoring client library for Python with [pip][pip_link]:
```bash
pip install azure-ai-textanalytics-authoring
```
> Note: This version of the client library defaults to the 2025-05-15-preview version of the service.
This table shows the relationship between SDK versions and supported API versions of the service
| SDK version | Supported API version of service |
| ------------ | --------------------------------- |
| 1.0.0b1 - Latest preview release | 2023-04-01, 2024-11-15-preview, 2025-05-15-preview (default) |
### Authenticate the client
To interact with the Text Authoring service, you'll need to create an instance of the `TextAuthoringClient`. You will need an **endpoint** and an **API key** to 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 **API key** from your Cognitive Services resource in the [Azure Portal][azure_portal].
Alternatively, use the [Azure CLI][azure_cli] command shown below to get the API key from the Cognitive Service resource:
```powershell
az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>
```
#### Create a TextAuthoringClient with an Azure Active Directory Credential
To use an [Azure Active Directory (AAD) token credential][cognitive_authentication_aad],
provide an instance of the desired credential type obtained from the [azure-identity][azure_identity_credentials] library.
> Note: Regional endpoints do not support AAD authentication.
> You must create a [custom subdomain][custom_subdomain] for your resource in order to use this type of authentication.
Authentication with AAD requires some initial setup:
- [Install azure-identity][install_azure_identity]
- [Register a new AAD application][register_aad_app]
- [Grant access][grant_role_access] to the Language service by assigning the **Cognitive Services Language Owner** role to your service principal
After setup, you can choose which type of [credential][azure_identity_credentials] to use.
As an example, [DefaultAzureCredential][default_azure_credential] can be used to authenticate the client:
Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables:
`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`
Use the returned token credential to authenticate the client:
```python
from azure.ai.textanalytics.authoring import TextAuthoringClient
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
client = TextAuthoringClient(
endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/",
credential=credential,
)
```
#### Create a TextAuthoringClient using AzureKeyCredential
Once you've determined your **endpoint** and **API key**, you can instantiate a `TextAuthoringClient`:
```python
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics.authoring import TextAuthoringClient
endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api-key>")
client = TextAuthoringClient(endpoint, credential)
```
## Key concepts
### TextAuthoringClient
The `TextAuthoringClient` is the primary entry point for interacting with the Text Authoring service.
It provides top-level APIs to **manage projects** (create, delete, list) and retrieve **project-scoped clients**.
You can call `get_project_client(project_name)` to obtain a `TextAuthoringProjectClient`, which exposes operations specific to a given project.
For asynchronous operations, an async version of the client is available in the `azure.ai.textanalytics.authoring.aio` namespace.
### TextAuthoringProjectClient
The `TextAuthoringProjectClient` is a **project-scoped client** returned by `TextAuthoringClient.get_project_client(project_name)`.
It organizes project functionality into operation groups:
- **deployment** → [`DeploymentOperations`]: manage deployments (create, update, delete, swap).
- **exported_model** → [`ExportedModelOperations`]: handle exported model operations.
- **project** → [`ProjectOperations`]: manage project-level operations (train, import/export, cancel jobs, assign resources).
- **trained_model** → [`TrainedModelOperations`]: interact with trained models (evaluation, snapshots, delete models).
This separation ensures you can focus on project-level actions while still using the main `TextAuthoringClient` for higher-level management.
## Examples
The `azure-ai-textanalytics-authoring` client library provides both **synchronous** and **asynchronous** APIs.
The following examples show common **Text Authoring** scenarios using the `TextAuthoringClient` or `TextAuthoringProjectClient` (created above).
### Create a Text Project
```python
import os
from azure.identity import DefaultAzureCredential
from azure.ai.textanalytics.authoring import TextAuthoringClient
from azure.ai.textanalytics.authoring.models import (
CreateProjectOptions,
ProjectKind,
)
def sample_text_create_project():
# settings
endpoint = os.environ["AZURE_TEXT_ENDPOINT"]
project_name = os.environ.get("PROJECT_NAME", "<project-name>")
language_tag = os.environ.get("LANGUAGE_TAG", "<language-tag>") # e.g., "en"
storage_container = os.environ.get("STORAGE_INPUT_CONTAINER_NAME", "<storage-container-name>")
description = os.environ.get("DESCRIPTION", "<description>")
# create a client with AAD
credential = DefaultAzureCredential()
client = TextAuthoringClient(endpoint, credential=credential)
# build project definition (Custom Multi-Label Classification)
body = CreateProjectOptions(
project_kind=ProjectKind.CUSTOM_MULTI_LABEL_CLASSIFICATION,
storage_input_container_name=storage_container,
project_name=project_name,
language=language_tag,
description=description,
multilingual=True,
)
# create project
result = client.create_project(project_name=project_name, body=body)
# print project details (direct attribute access; no getattr)
print("=== Create Text Authoring Project Result ===")
print(f"Project Name: {result.project_name}")
print(f"Language: {result.language}")
print(f"Kind: {result.project_kind}")
print(f"Multilingual: {result.multilingual}")
print(f"Description: {result.description}")
print(f"Storage Input Container: {result.storage_input_container_name}")
```
### Import a Project
```python
import os
from azure.identity import DefaultAzureCredential
from azure.core.exceptions import HttpResponseError
from azure.ai.textanalytics.authoring import TextAuthoringClient
from azure.ai.textanalytics.authoring.models import (
CreateProjectOptions,
ExportedProject,
ProjectSettings,
ExportedCustomSingleLabelClassificationProjectAsset,
ExportedCustomSingleLabelClassificationDocument,
ExportedDocumentClass,
ExportedClass,
ProjectKind,
StringIndexType,
)
def sample_import_project():
# settings
endpoint = os.environ["AZURE_TEXT_ENDPOINT"]
project_name = os.environ.get("PROJECT_NAME", "<project-name>")
language_tag = os.environ.get("LANGUAGE_TAG", "<language-tag>") # e.g., "en"
storage_container = os.environ.get("STORAGE_INPUT_CONTAINER_NAME", "<storage-container-name>")
doc1_path = os.environ.get("DOC1_PATH", "<doc1-path>") # e.g., "01.txt"
doc2_path = os.environ.get("DOC2_PATH", "<doc2-path>") # e.g., "02.txt"
# create a client with AAD
credential = DefaultAzureCredential()
client = TextAuthoringClient(endpoint, credential=credential)
# project-scoped client
project_client = client.get_project_client(project_name)
# ---------- Arrange metadata (project definition) ----------
project_metadata = CreateProjectOptions(
project_kind=ProjectKind.CUSTOM_SINGLE_LABEL_CLASSIFICATION,
storage_input_container_name=storage_container,
project_name=project_name,
language=language_tag,
description="Sample project imported via Python SDK.",
multilingual=False,
settings=ProjectSettings(),
)
# ---------- Arrange assets (classes + labeled documents) ----------
project_assets = ExportedCustomSingleLabelClassificationProjectAsset(
classes=[
ExportedClass(category="ClassA"),
ExportedClass(category="ClassB"),
ExportedClass(category="ClassC"),
],
documents=[
ExportedCustomSingleLabelClassificationDocument(
class_property=ExportedDocumentClass(category="ClassA"),
location=doc1_path,
language=language_tag,
),
ExportedCustomSingleLabelClassificationDocument(
class_property=ExportedDocumentClass(category="ClassB"),
location=doc2_path,
language=language_tag,
),
],
)
exported_project = ExportedProject(
project_file_version="2022-05-01",
string_index_type=StringIndexType.UTF16_CODE_UNIT,
metadata=project_metadata,
assets=project_assets,
)
# ---------- Import (LRO) with error handling ----------
poller = project_client.project.begin_import(body=exported_project)
try:
poller.result() # completes with None; raises on failure
print("Import completed.")
print(f"done: {poller.done()}")
print(f"status: {poller.status()}")
except HttpResponseError as e:
msg = getattr(getattr(e, "error", None), "message", str(e))
print(f"Operation failed: {msg}")
```
### Train a Model
```python
import os
from azure.identity import DefaultAzureCredential
from azure.core.exceptions import HttpResponseError
from azure.ai.textanalytics.authoring import TextAuthoringClient
from azure.ai.textanalytics.authoring.models import (
TrainingJobDetails,
EvaluationDetails,
EvaluationKind,
)
def sample_train_project():
# settings
endpoint = os.environ["AZURE_TEXT_ENDPOINT"]
project_name = os.environ.get("PROJECT_NAME", "<project-name>")
model_label = os.environ.get("MODEL_LABEL", "<model-label>")
training_config_version = os.environ.get("TRAINING_CONFIG_VERSION", "<training-config-version>")
# create a client with AAD
credential = DefaultAzureCredential()
client = TextAuthoringClient(endpoint, credential=credential)
# project-scoped client
project_client = client.get_project_client(project_name)
# build training job details (80/20 split by percentage)
training_job_details = TrainingJobDetails(
model_label=model_label,
training_config_version=training_config_version,
evaluation_options=EvaluationDetails(
kind=EvaluationKind.PERCENTAGE,
testing_split_percentage=20,
training_split_percentage=80,
),
)
# begin training (LRO) and handle success/error
poller = project_client.project.begin_train(body=training_job_details)
try:
poller.result() # completes with None; raises on failure
print("Train completed.")
print(f"done: {poller.done()}")
print(f"status: {poller.status()}")
except HttpResponseError as e:
msg = getattr(getattr(e, "error", None), "message", str(e))
print(f"Operation failed: {msg}")
```
## 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
The Text Authoring client will raise exceptions defined in [Azure Core][azure_core_exceptions].
These exceptions provide consistent error handling across Azure SDK libraries.
### Logging
This library uses Python’s built-in [logging][python_logging] module for diagnostic logging.
- Basic information about HTTP requests (URLs, headers) is logged at **INFO** level.
- Detailed request/response information (including bodies and unredacted headers) is logged at **DEBUG** level.
You can enable logging when constructing the client by passing `logging_enable=True`.
```python
import sys
import logging
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics.authoring import TextAuthoringClient
# Configure logger
logger = logging.getLogger("azure")
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)
endpoint = "https://<endpoint>.cognitiveservices.azure.com/"
credential = DefaultAzureCredential()
# This client will log detailed HTTP information
client = TextAuthoringClient(endpoint, credential, logging_enable=True)
```
Similarly, `logging_enable` can enable detailed logging for a single operation, even when it isn't enabled for the client:
```python
result = client.create_project(
project_name="<project-name>",
body={...},
logging_enable=True,
)
```
## Next steps
### More sample code
See the [Sample README][text_authoring_samples] for additional examples that demonstrate common Text Authoring workflows such as:
- Creating and managing projects
- Importing and exporting project assets
- Training models and retrieving evaluation results
- Deploying and swapping models
- Assigning or unassigning resources
- Loading snapshots and managing trained models
---
## Contributing
See the [CONTRIBUTING.md][contributing] guide 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 repositories 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 [opencode@microsoft.com][coc_contact] with any additional questions.
---
<!-- LINKS -->
[azure_cli]: https://learn.microsoft.com/cli/azure/
[azure_portal]: https://portal.azure.com/
[azure_subscription]: https://azure.microsoft.com/free/
[language_resource]: https://portal.azure.com/#create/Microsoft.CognitiveServicesTextAnalytics
[cla]: https://cla.microsoft.com
[coc_contact]: mailto:opencode@microsoft.com
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
[cognitive_auth]: https://learn.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://learn.microsoft.com/azure/developer/python/azure-sdk-logging
[azure_core_ref_docs]: https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/latest/azure.core.html
[azure_core_exceptions]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md
[pip_link]: https://pypi.org/project/pip/
[text_authoring_client_src]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-textanalytics-authoring
[text_authoring_pypi_package]: https://pypi.org/project/azure-ai-textanalytics-authoring/
[text_authoring_samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-textanalytics-authoring/samples/README.md
[text_authoring_docs]: https://learn.microsoft.com/azure/ai-services/language-service/custom-text-classification/overview
[api_reference_authoring]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-textanalytics-authoring
<!-- TODO: change api_reference_documentation to azuresdkdocs link after first publish -->
[text_authoring_restdocs]: https://learn.microsoft.com/rest/api/language/text-authoring-project?view=rest-language-2023-04-01
[azure_language_portal]: https://language.cognitive.azure.com/home
[cognitive_authentication_aad]: https://learn.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory
[azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials
[custom_subdomain]: https://learn.microsoft.com/azure/cognitive-services/authentication#create-a-resource-with-a-custom-subdomain
[install_azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#install-the-package
[register_aad_app]: https://learn.microsoft.com/azure/cognitive-services/authentication#assign-a-role-to-a-service-principal
[grant_role_access]: https://learn.microsoft.com/azure/cognitive-services/authentication#assign-a-role-to-a-service-principal
[default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential
# Release History
## 1.0.0b1 (2025-09-19)
### Features Added
* Initial release
Raw data
{
"_id": null,
"home_page": null,
"name": "azure-ai-textanalytics-authoring",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "azure, azure sdk",
"author": null,
"author_email": "Microsoft Corporation <azpysdkhelp@microsoft.com> License-Expression: MIT",
"download_url": "https://files.pythonhosted.org/packages/ad/41/78b8d8ef07d7550167b79f605ec03ed3789c73b244c03d7ae22c7c2fe918/azure_ai_textanalytics_authoring-1.0.0b1.tar.gz",
"platform": null,
"description": "[](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=46?branchName=main)\n\n# Azure Text Authoring client library for Python\n\n**Text Authoring** is part of Azure AI Language. It provides APIs and SDKs to **create, manage, train, evaluate, and deploy** text projects and models (for example, custom single/multi-label classification). With the `TextAuthoringClient`, you can automate much of what you\u2019d otherwise do in Language Studio, including:\n\n- **Project management**: Create, update, export, and import projects. \n- **Training jobs**: Start, monitor, and cancel model training jobs. \n- **Evaluation**: Retrieve model evaluation summaries and document-level results. \n- **Deployments**: Create, update, swap, and delete deployments. \n- **Snapshots**: Load a trained model snapshot back into a project. \n- **Resource assignment**: Assign or unassign Azure resources to a deployment. \n\n[Source code][text_authoring_client_src]\n| [Package (PyPI)][text_authoring_pypi_package]\n| [API reference][api_reference_authoring]\n| [Samples][text_authoring_samples]\n| [Product docs][text_authoring_docs]\n| [REST API docs][text_authoring_restdocs]\n\n---\n\n## Getting started\n\n### Prerequisites\n\n- Python 3.7 or later \n- An [Azure subscription][azure_subscription] \n- An Azure AI [Language resource][language_resource]\n\n### Install the package\n\nInstall the Azure Text Authoring client library for Python with [pip][pip_link]:\n\n```bash\npip install azure-ai-textanalytics-authoring\n```\n\n> Note: This version of the client library defaults to the 2025-05-15-preview version of the service.\n\nThis table shows the relationship between SDK versions and supported API versions of the service\n\n| SDK version | Supported API version of service |\n| ------------ | --------------------------------- |\n| 1.0.0b1 - Latest preview release | 2023-04-01, 2024-11-15-preview, 2025-05-15-preview (default) |\n\n### Authenticate the client\n\nTo interact with the Text Authoring service, you'll need to create an instance of the `TextAuthoringClient`. You will need an **endpoint** and an **API key** to instantiate a client object. For more information regarding authenticating with Cognitive Services, see [Authenticate requests to Azure Cognitive Services][cognitive_auth].\n\n#### Get an API key\n\nYou can get the **endpoint** and **API key** from your Cognitive Services resource in the [Azure Portal][azure_portal].\n\nAlternatively, use the [Azure CLI][azure_cli] command shown below to get the API key from the Cognitive Service resource:\n\n```powershell\naz cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>\n```\n\n#### Create a TextAuthoringClient with an Azure Active Directory Credential\n\nTo use an [Azure Active Directory (AAD) token credential][cognitive_authentication_aad], \nprovide an instance of the desired credential type obtained from the [azure-identity][azure_identity_credentials] library.\n\n> Note: Regional endpoints do not support AAD authentication. \n> You must create a [custom subdomain][custom_subdomain] for your resource in order to use this type of authentication.\n\nAuthentication with AAD requires some initial setup:\n\n- [Install azure-identity][install_azure_identity] \n- [Register a new AAD application][register_aad_app] \n- [Grant access][grant_role_access] to the Language service by assigning the **Cognitive Services Language Owner** role to your service principal \n\nAfter setup, you can choose which type of [credential][azure_identity_credentials] to use. \nAs an example, [DefaultAzureCredential][default_azure_credential] can be used to authenticate the client:\n\nSet the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: \n`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`\n\nUse the returned token credential to authenticate the client:\n\n```python\nfrom azure.ai.textanalytics.authoring import TextAuthoringClient\nfrom azure.identity import DefaultAzureCredential\n\ncredential = DefaultAzureCredential()\nclient = TextAuthoringClient(\n endpoint=\"https://<my-custom-subdomain>.cognitiveservices.azure.com/\",\n credential=credential,\n)\n```\n\n#### Create a TextAuthoringClient using AzureKeyCredential\n\nOnce you've determined your **endpoint** and **API key**, you can instantiate a `TextAuthoringClient`:\n\n```python\nfrom azure.core.credentials import AzureKeyCredential\nfrom azure.ai.textanalytics.authoring import TextAuthoringClient\n\nendpoint = \"https://<my-custom-subdomain>.cognitiveservices.azure.com/\"\ncredential = AzureKeyCredential(\"<api-key>\")\nclient = TextAuthoringClient(endpoint, credential)\n```\n\n## Key concepts\n\n### TextAuthoringClient\n\nThe `TextAuthoringClient` is the primary entry point for interacting with the Text Authoring service. \nIt provides top-level APIs to **manage projects** (create, delete, list) and retrieve **project-scoped clients**.\n\nYou can call `get_project_client(project_name)` to obtain a `TextAuthoringProjectClient`, which exposes operations specific to a given project.\n\nFor asynchronous operations, an async version of the client is available in the `azure.ai.textanalytics.authoring.aio` namespace.\n\n### TextAuthoringProjectClient\n\nThe `TextAuthoringProjectClient` is a **project-scoped client** returned by `TextAuthoringClient.get_project_client(project_name)`. \n\nIt organizes project functionality into operation groups:\n\n- **deployment** \u2192 [`DeploymentOperations`]: manage deployments (create, update, delete, swap). \n- **exported_model** \u2192 [`ExportedModelOperations`]: handle exported model operations. \n- **project** \u2192 [`ProjectOperations`]: manage project-level operations (train, import/export, cancel jobs, assign resources). \n- **trained_model** \u2192 [`TrainedModelOperations`]: interact with trained models (evaluation, snapshots, delete models). \n\nThis separation ensures you can focus on project-level actions while still using the main `TextAuthoringClient` for higher-level management.\n\n## Examples\n\nThe `azure-ai-textanalytics-authoring` client library provides both **synchronous** and **asynchronous** APIs.\n\nThe following examples show common **Text Authoring** scenarios using the `TextAuthoringClient` or `TextAuthoringProjectClient` (created above).\n\n### Create a Text Project\n\n```python\nimport os\nfrom azure.identity import DefaultAzureCredential\nfrom azure.ai.textanalytics.authoring import TextAuthoringClient\nfrom azure.ai.textanalytics.authoring.models import (\n CreateProjectOptions,\n ProjectKind,\n)\n\n\ndef sample_text_create_project():\n # settings\n endpoint = os.environ[\"AZURE_TEXT_ENDPOINT\"]\n project_name = os.environ.get(\"PROJECT_NAME\", \"<project-name>\")\n language_tag = os.environ.get(\"LANGUAGE_TAG\", \"<language-tag>\") # e.g., \"en\"\n storage_container = os.environ.get(\"STORAGE_INPUT_CONTAINER_NAME\", \"<storage-container-name>\")\n description = os.environ.get(\"DESCRIPTION\", \"<description>\")\n\n # create a client with AAD\n credential = DefaultAzureCredential()\n client = TextAuthoringClient(endpoint, credential=credential)\n\n # build project definition (Custom Multi-Label Classification)\n body = CreateProjectOptions(\n project_kind=ProjectKind.CUSTOM_MULTI_LABEL_CLASSIFICATION,\n storage_input_container_name=storage_container,\n project_name=project_name,\n language=language_tag,\n description=description,\n multilingual=True,\n )\n\n # create project\n result = client.create_project(project_name=project_name, body=body)\n\n # print project details (direct attribute access; no getattr)\n print(\"=== Create Text Authoring Project Result ===\")\n print(f\"Project Name: {result.project_name}\")\n print(f\"Language: {result.language}\")\n print(f\"Kind: {result.project_kind}\")\n print(f\"Multilingual: {result.multilingual}\")\n print(f\"Description: {result.description}\")\n print(f\"Storage Input Container: {result.storage_input_container_name}\")\n```\n\n### Import a Project\n\n```python\nimport os\nfrom azure.identity import DefaultAzureCredential\nfrom azure.core.exceptions import HttpResponseError\nfrom azure.ai.textanalytics.authoring import TextAuthoringClient\nfrom azure.ai.textanalytics.authoring.models import (\n CreateProjectOptions,\n ExportedProject,\n ProjectSettings,\n ExportedCustomSingleLabelClassificationProjectAsset,\n ExportedCustomSingleLabelClassificationDocument,\n ExportedDocumentClass,\n ExportedClass,\n ProjectKind,\n StringIndexType,\n)\n\n\ndef sample_import_project():\n # settings\n endpoint = os.environ[\"AZURE_TEXT_ENDPOINT\"]\n project_name = os.environ.get(\"PROJECT_NAME\", \"<project-name>\")\n language_tag = os.environ.get(\"LANGUAGE_TAG\", \"<language-tag>\") # e.g., \"en\"\n storage_container = os.environ.get(\"STORAGE_INPUT_CONTAINER_NAME\", \"<storage-container-name>\")\n doc1_path = os.environ.get(\"DOC1_PATH\", \"<doc1-path>\") # e.g., \"01.txt\"\n doc2_path = os.environ.get(\"DOC2_PATH\", \"<doc2-path>\") # e.g., \"02.txt\"\n\n # create a client with AAD\n credential = DefaultAzureCredential()\n client = TextAuthoringClient(endpoint, credential=credential)\n\n # project-scoped client\n project_client = client.get_project_client(project_name)\n\n # ---------- Arrange metadata (project definition) ----------\n project_metadata = CreateProjectOptions(\n project_kind=ProjectKind.CUSTOM_SINGLE_LABEL_CLASSIFICATION,\n storage_input_container_name=storage_container,\n project_name=project_name,\n language=language_tag,\n description=\"Sample project imported via Python SDK.\",\n multilingual=False,\n settings=ProjectSettings(),\n )\n\n # ---------- Arrange assets (classes + labeled documents) ----------\n project_assets = ExportedCustomSingleLabelClassificationProjectAsset(\n classes=[\n ExportedClass(category=\"ClassA\"),\n ExportedClass(category=\"ClassB\"),\n ExportedClass(category=\"ClassC\"),\n ],\n documents=[\n ExportedCustomSingleLabelClassificationDocument(\n class_property=ExportedDocumentClass(category=\"ClassA\"),\n location=doc1_path,\n language=language_tag,\n ),\n ExportedCustomSingleLabelClassificationDocument(\n class_property=ExportedDocumentClass(category=\"ClassB\"),\n location=doc2_path,\n language=language_tag,\n ),\n ],\n )\n\n exported_project = ExportedProject(\n project_file_version=\"2022-05-01\",\n string_index_type=StringIndexType.UTF16_CODE_UNIT,\n metadata=project_metadata,\n assets=project_assets,\n )\n\n # ---------- Import (LRO) with error handling ----------\n poller = project_client.project.begin_import(body=exported_project)\n try:\n poller.result() # completes with None; raises on failure\n print(\"Import completed.\")\n print(f\"done: {poller.done()}\")\n print(f\"status: {poller.status()}\")\n except HttpResponseError as e:\n msg = getattr(getattr(e, \"error\", None), \"message\", str(e))\n print(f\"Operation failed: {msg}\")\n```\n\n### Train a Model\n\n```python\nimport os\nfrom azure.identity import DefaultAzureCredential\nfrom azure.core.exceptions import HttpResponseError\nfrom azure.ai.textanalytics.authoring import TextAuthoringClient\nfrom azure.ai.textanalytics.authoring.models import (\n TrainingJobDetails,\n EvaluationDetails,\n EvaluationKind,\n)\n\n\ndef sample_train_project():\n # settings\n endpoint = os.environ[\"AZURE_TEXT_ENDPOINT\"]\n project_name = os.environ.get(\"PROJECT_NAME\", \"<project-name>\")\n model_label = os.environ.get(\"MODEL_LABEL\", \"<model-label>\")\n training_config_version = os.environ.get(\"TRAINING_CONFIG_VERSION\", \"<training-config-version>\")\n\n # create a client with AAD\n credential = DefaultAzureCredential()\n client = TextAuthoringClient(endpoint, credential=credential)\n\n # project-scoped client\n project_client = client.get_project_client(project_name)\n\n # build training job details (80/20 split by percentage)\n training_job_details = TrainingJobDetails(\n model_label=model_label,\n training_config_version=training_config_version,\n evaluation_options=EvaluationDetails(\n kind=EvaluationKind.PERCENTAGE,\n testing_split_percentage=20,\n training_split_percentage=80,\n ),\n )\n\n # begin training (LRO) and handle success/error\n poller = project_client.project.begin_train(body=training_job_details)\n try:\n poller.result() # completes with None; raises on failure\n print(\"Train completed.\")\n print(f\"done: {poller.done()}\")\n print(f\"status: {poller.status()}\")\n except HttpResponseError as e:\n msg = getattr(getattr(e, \"error\", None), \"message\", str(e))\n print(f\"Operation failed: {msg}\")\n```\n\n## Optional Configuration\n\nOptional 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.\n\n## Troubleshooting\n\n### General\n\nThe Text Authoring client will raise exceptions defined in [Azure Core][azure_core_exceptions]. \nThese exceptions provide consistent error handling across Azure SDK libraries.\n\n### Logging\n\nThis library uses Python\u2019s built-in [logging][python_logging] module for diagnostic logging. \n\n- Basic information about HTTP requests (URLs, headers) is logged at **INFO** level. \n- Detailed request/response information (including bodies and unredacted headers) is logged at **DEBUG** level. \n\nYou can enable logging when constructing the client by passing `logging_enable=True`.\n\n```python\nimport sys\nimport logging\nfrom azure.core.credentials import AzureKeyCredential\nfrom azure.ai.textanalytics.authoring import TextAuthoringClient\n\n# Configure logger\nlogger = logging.getLogger(\"azure\")\nlogger.setLevel(logging.DEBUG)\nhandler = logging.StreamHandler(stream=sys.stdout)\nlogger.addHandler(handler)\n\nendpoint = \"https://<endpoint>.cognitiveservices.azure.com/\"\ncredential = DefaultAzureCredential()\n\n# This client will log detailed HTTP information\nclient = TextAuthoringClient(endpoint, credential, logging_enable=True)\n```\n\nSimilarly, `logging_enable` can enable detailed logging for a single operation, even when it isn't enabled for the client:\n\n```python\nresult = client.create_project(\n project_name=\"<project-name>\",\n body={...},\n logging_enable=True,\n)\n```\n\n## Next steps\n\n### More sample code\n\nSee the [Sample README][text_authoring_samples] for additional examples that demonstrate common Text Authoring workflows such as:\n\n- Creating and managing projects \n- Importing and exporting project assets \n- Training models and retrieving evaluation results \n- Deploying and swapping models \n- Assigning or unassigning resources \n- Loading snapshots and managing trained models \n\n---\n\n## Contributing\n\nSee the [CONTRIBUTING.md][contributing] guide for details on building, testing, and contributing to this library.\n\nThis 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].\n\nWhen 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 repositories using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. \nFor more information, see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions.\n\n---\n\n<!-- LINKS -->\n[azure_cli]: https://learn.microsoft.com/cli/azure/\n[azure_portal]: https://portal.azure.com/\n[azure_subscription]: https://azure.microsoft.com/free/\n[language_resource]: https://portal.azure.com/#create/Microsoft.CognitiveServicesTextAnalytics\n[cla]: https://cla.microsoft.com\n[coc_contact]: mailto:opencode@microsoft.com\n[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/\n[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/\n[cognitive_auth]: https://learn.microsoft.com/azure/cognitive-services/authentication/\n[contributing]: https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md\n[python_logging]: https://docs.python.org/3/library/logging.html\n[sdk_logging_docs]: https://learn.microsoft.com/azure/developer/python/azure-sdk-logging\n[azure_core_ref_docs]: https://azuresdkdocs.z19.web.core.windows.net/python/azure-core/latest/azure.core.html\n[azure_core_exceptions]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md\n[pip_link]: https://pypi.org/project/pip/\n[text_authoring_client_src]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-textanalytics-authoring\n[text_authoring_pypi_package]: https://pypi.org/project/azure-ai-textanalytics-authoring/\n[text_authoring_samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-textanalytics-authoring/samples/README.md\n[text_authoring_docs]: https://learn.microsoft.com/azure/ai-services/language-service/custom-text-classification/overview\n[api_reference_authoring]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-textanalytics-authoring\n<!-- TODO: change api_reference_documentation to azuresdkdocs link after first publish -->\n[text_authoring_restdocs]: https://learn.microsoft.com/rest/api/language/text-authoring-project?view=rest-language-2023-04-01\n[azure_language_portal]: https://language.cognitive.azure.com/home\n[cognitive_authentication_aad]: https://learn.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory\n[azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials\n[custom_subdomain]: https://learn.microsoft.com/azure/cognitive-services/authentication#create-a-resource-with-a-custom-subdomain\n[install_azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#install-the-package\n[register_aad_app]: https://learn.microsoft.com/azure/cognitive-services/authentication#assign-a-role-to-a-service-principal\n[grant_role_access]: https://learn.microsoft.com/azure/cognitive-services/authentication#assign-a-role-to-a-service-principal\n[default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#defaultazurecredential\n# Release History\n\n## 1.0.0b1 (2025-09-19)\n\n### Features Added\n* Initial release\n",
"bugtrack_url": null,
"license": null,
"summary": "Microsoft Corporation Azure Ai Textanalytics Authoring Client Library for Python",
"version": "1.0.0b1",
"project_urls": {
"repository": "https://github.com/Azure/azure-sdk-for-python"
},
"split_keywords": [
"azure",
" azure sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "100094c44490f28ecfb8215a1fe1c2ec5aa652d5e3ccb4bf68acef798a939b2d",
"md5": "b85622d39f829cfeb65b9b2fcaf4e67e",
"sha256": "c4a87f7dd1601d874dce06d5c9e1c23fad693f22bbbfa950da8082fd0b96444f"
},
"downloads": -1,
"filename": "azure_ai_textanalytics_authoring-1.0.0b1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b85622d39f829cfeb65b9b2fcaf4e67e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 105895,
"upload_time": "2025-09-19T22:32:40",
"upload_time_iso_8601": "2025-09-19T22:32:40.708476Z",
"url": "https://files.pythonhosted.org/packages/10/00/94c44490f28ecfb8215a1fe1c2ec5aa652d5e3ccb4bf68acef798a939b2d/azure_ai_textanalytics_authoring-1.0.0b1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ad4178b8d8ef07d7550167b79f605ec03ed3789c73b244c03d7ae22c7c2fe918",
"md5": "18ba03a3211bab362e897c4012b68634",
"sha256": "db4eca1746e705a0ae2386c5f2cefe1b0b0028cb2857455b3c309372c64e99f8"
},
"downloads": -1,
"filename": "azure_ai_textanalytics_authoring-1.0.0b1.tar.gz",
"has_sig": false,
"md5_digest": "18ba03a3211bab362e897c4012b68634",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 120439,
"upload_time": "2025-09-19T22:32:38",
"upload_time_iso_8601": "2025-09-19T22:32:38.965327Z",
"url": "https://files.pythonhosted.org/packages/ad/41/78b8d8ef07d7550167b79f605ec03ed3789c73b244c03d7ae22c7c2fe918/azure_ai_textanalytics_authoring-1.0.0b1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-19 22:32:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Azure",
"github_project": "azure-sdk-for-python",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "azure-ai-textanalytics-authoring"
}
