update qas 0919

Author: ChenxiJiang333

QA/python_2025_09_19.md

@@ -0,0 +1,71 @@
+# Guidance needed on namespace and migration from old SDK folder to new one
+
+## question
+Hi team,
+
+We’re working on the Python SDK for azure-ai-textanalytics and would like your guidance on a few points regarding namespace and migration.
+
+Background:
+We currently have an older SDK package `azure-ai-analytics` (v5) under the textanalytics folder.
+A new major version (v6) has been created under the **cognitivelanguage** folder, where other Language SDKs (`azure-ai-language-conversation`, `azure-ai-language-text`, `azure-ai-language-questionanswering`) are also located.
+
+Links for reference:
+New location in `cognitivelanguage`: [azure-sdk-for-python/sdk/cognitivelanguage/azure-ai-textanalytics at 9dcb87416cc10a3fd2487bffea84aa…](https://github.com/Azure/azure-sdk-for-python/tree/9dcb87416cc10a3fd2487bffea84aa03f3dc13c0/sdk/cognitivelanguage/azure-ai-textanalytics)
+Old location in `textanalytics`: [azure-sdk-for-python/sdk/textanalytics/azure-ai-textanalytics at 9dcb87416cc10a3fd2487bffea84aa03f3…](https://github.com/Azure/azure-sdk-for-python/tree/9dcb87416cc10a3fd2487bffea84aa03f3dc13c0/sdk/textanalytics/azure-ai-textanalytics)
+PR link: [\[Textanalytics\] Textanalytics sdk 20250515prevew by amber-Chen-86 · Pull Request #42685 · Azure/azu…](https://github.com/Azure/azure-sdk-for-python/pull/42685)
+
+**Question1: Namespace**
+For consistency across the Azure AI Language SDKs, the new `azure-ai-analytics` v6 uses the namespace `azure.ai.language.text` (aligned with `azure.ai.language.conversation`, etc.). Is it acceptable to keep the package name as `azure-ai-analytics` while using the `azure.ai.language.text` namespace? Or could we instead rename the package to `azure-ai-language-text` to match the namespace?
+
+**Question2: CI Conflict on Package Name**
+Since both the old and new versions currently share the same package name but are in different folders, CI fails with a package name conflict (preventing APIView generation). Example error: [https://dev.azure.com/azure-sdk/public/_build/results?buildId=5300001&view=logs&j=b70e5e73-…].
+
+One option suggested earlier was to remove the old SDK from the `textanalytics` folder and leave only a README redirecting users to the new location, ensuring uniqueness of the package name.
+However, we would prefer to **keep the old SDK until the new one GA’s** (as Anna suggested). Is there a recommended way to keep both temporarily without blocking CI?
+
+**Question3: Migration Guide**
+As this involves moving the SDK to a new folder (and possibly a namespace adjustment), we’ll need to publish a clear migration guide for customers.
+Do we have an existing example or format for such migration documentation that we can reference?
+
+Thanks in advance for the guidance!
+
+## answer
+1. Amber we discussed and think it is best to match the package name with the namespace, so `azure-ai-textanalytics` package with namespace `azure.ai.textanalytics`. This follows the same pattern our other libraries use and we believe customers have a strong expectation on that structure.
+
+2. We're good with putting `azure-ai-textanalytics` under the `cognitivelanguage` directory.
+
+3. Here's an example of a migration guide we've used to show users how to migrate from one version to another in the same package: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/formrecognizer/azure-ai-formrecognizer/…
+
+And to solve the CI issue, we only need to remove the old package code from the `ci.yml`:
+```
+Since both the old and new versions currently share the same package name but are in different folders, CI fails with a package name conflict (preventing APIView generation). Example error: [https://dev.azure.com/azure-sdk/public/_build/results?buildId=5300001&view=logs&j=b70e5e73-…].
+```
+
+# Tox commands to run quality gates no longer work for pyproject.toml
+
+## question
+The Tox instructions here to run quality gate no longer work with new Python projects that use `pyproject.toml`
+https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md#tox
+
+For example, when I run `tox run -e pylint -c ../../../eng/tox/tox.ini --root .` I get the error below. Note that I'm developing in azure-sdk-for-python-pr, if that makes a difference. I do have a pyproject.toml in my folder.
+
+Is there documentation on how to run quality gates for projects that use pyproject.toml?
+
+Thanks!
+
+```
+.pkg: The --no-wheel and --wheel options are deprecated. They have no effect for Python > 3.8 as wheel is no longer bundled in virtualenv.
+pylint: The --no-wheel and --wheel options are deprecated. They have no effect for Python > 3.8 as wheel is no longer bundled in virtualenv.
+pylint: install_deps> python -m pip install -r dev_requirements.txt -r E:\src\sdk-repos\azure-sdk-for-python-pr/eng/test_tools.txt --cache-dir E:\src\sdk-repos\azure-sdk-for-python-pr\sdk\ai\azure-ai-agents-v2/../.tox_pip_cache_pylint
+Looking in indexes: https://pypi.org/simple, https://pypi.python.org/simple
+Obtaining file:///E:/src/sdk-repos/azure-sdk-for-python-pr/tools/azure-sdk-tools (from -r dev_requirements.txt (line 1))
+ERROR: file:///E:/src/sdk-repos/azure-sdk-for-python-pr/tools/azure-sdk-tools (from -r dev_requirements.txt (line 1)) does not appear to be a Python project: neither 'setup.py' nor 'pyproject.toml' found.
+pylint: exit 1 (3.06 seconds) E:\src\sdk-repos\azure-sdk-for-python-pr\sdk\ai\azure-ai-agents-v2> python -m pip install -r dev_requirements.txt -r E:\src\sdk-repos\azure-sdk-for-python-pr/eng/test_tools.txt --cache-dir E:\src\sdk-repos\azure-sdk-for-python-pr\sdk\ai\azure-ai-agents-v2/../.tox_pip_cache_pylint pid=22792
+  pylint: FAIL code 1 (12.25 seconds)
+  evaluation failed :( (13.77 seconds)
+```
+
+## answer
+Not sure if this will fully solve the problem, but it looks like the dev_reqs.txt for that library is pointing to the old location of azure-sdk-tools: [azure-sdk-for-python-pr/sdk/ai/azure-ai-agents-v2/dev_requirements.txt at feature/ai-foundry/agents…](https://github.com/Azure/azure-sdk-for-python-pr/blob/feature/ai-foundry/agents-v2/sdk/ai/azure-ai-agents-v2/dev_requirements.txt#L1)
+
+Should be: `-e ../../../eng/tools/azure-sdk-tools`