diff --git a/QA/python_2025_09_19.md b/QA/python_2025_09_19.md new file mode 100644 index 000000000000..b12eabed2942 --- /dev/null +++ b/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`