Merge pull request #40 from ChenxiJiang333/update-qas

update qas

Author: msyyc

QA/for_ci/test-cases-for-python.md

@@ -0,0 +1,30 @@
+# Problem releasing remoterendering SDK for deprecation
+
+## question
+Hi,
+I'm trying to release the remoterendering SDK with the deprecation notice according to Step 4 in [azure-sdk-for-python/doc/deprecation_process.md at main · Azure/azure-sdk-for-python](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/deprecation_process.md).
+
+I did all the merging and executed the `Prepare-Release.ps1step` described in the guide, but then I tried to follow [Run release SDK pipeline](https://eng.ms/docs/products/azure-developer-experience/develop/sdk-release/sdk-release-pipeline) to actually release the package and I ran into problems.
+
+The output of the `python - remoterendering` pipeline [here](https://dev.azure.com/azure-sdk/internal/_build/results?buildId=5452798&view=results) does not look at all like the output described on the guide page for the release. I don't see any `package-signed` artifacts or any review step I could do.
+
+I see that the `Integration` step in the pipeline is skipping quiet a lot of things, but I don't know how to convince it to do more.
+
+Any help?
+
+The content of ci.yml contains this:
+```
+extends:
+  template: ../../eng/pipelines/templates/stages/archetype-sdk-client.yml
+  parameters:
+    ServiceDirectory: remoterendering
+    TestProxy: true
+    Artifacts:
+    - name: azure-mixedreality-remoterendering
+      safeName: azuremixedrealityremoterendering
+```
+
+## answer
+Your manually queued build here: [Pipelines - Run 20251015.1](https://dev.azure.com/azure-sdk/internal/_build/results?buildId=5459981&view=results)
+
+DOES reflect the stages you're expecting. The link you linked to above is the individual CI which runs automatically when a merge happens in that folder to `main`. They both have identical `SHA` ref, so you should be clear to release the deprecation now from your manually queued build.

QA/python_2025_10_17.md

@@ -0,0 +1,11 @@
+# Python sdk release
+
+## question
+Hu team , I am trying to release python sdk for oracle databse however build keep failing . Please help mitigate the issue , here is the link to the pipeline https://dev.azure.com/azure-sdk/internal/_build/results?buildId=5453800&view=results.
+
+## answer
+Two options.
+
+1. Regenerate your package using the `emitter-package.json` that's in `main`. Submit that PR.
+Submit a targeted PR that changes the `pyproject.toml` for your package to exclude the directories that shouldn't be there. Here is a PR generated from the newer emitter package. https://github.com/Azure/azure-sdk-for-python/pull/43272/files#r2430170753
+2. You could manually update your `pyproject.toml` to align with what you see in this PR. That's also an option.

QA/python_2025_10_24.md

@@ -0,0 +1,16 @@
+# Ubunty 2303 pypy39 specific failure
+
+## question
+Hi,
+
+I am seeing this error in the pipeline. Can anyone check please?
+```
+         --- stderr
+        error: the configured PyPy interpreter version (3.9) is lower than
+      PyO3's minimum supported version (3.11)
+      warning: build failed, waiting for other jobs to finish...
+```
+[Pipelines - Run 20251030.12 logs](https://dev.azure.com/azure-sdk/public/_build/results?buildId=5517166&view=logs&j=98792cce-2755-554b-a8ad-f8c76be41d33&t=7feb2094-2399-5589-4545-1b2ca3b7ddc8)
+
+## answer
+You have a dependency that doesn't ship a pypy39 dep. That's all. You could swap that with pypy311 in your matrix if you wanted to give it a shot.

QA/python_2025_10_31.md

@@ -0,0 +1,79 @@
+# NOTICE.txt updates
+
+## question
+Are there any recommendations to update the NOTICE.txt file in the root of the packages?
+
+We have recently received a GH issue [NOTICE calls out gpl-3.0 for non-gpl-3.0 packages · Issue #43717 · Azure/azure-sdk-for-python](https://github.com/Azure/azure-sdk-for-python/issues/43717) requesting to update the NOTICE.txt in azure-ai-ml package.
+
+We found the general recommendations here [NOTICE generation | Docs - Microsoft Open Source](https://docs.opensource.microsoft.com/tools/cg/legal/notice/). Could someone please help us figure out what is the right approach to update the NOTICE.txt?
+
+## answer
+Attaching the links shared by Justin：
+1. [Attribution guidelines | Docs - Microsoft Open Source](https://docs.opensource.microsoft.com/legal/cela-guidance/attribution-guidelines/)
+2. [NOTICE FAQ | Docs - Microsoft Open Source](https://docs.opensource.microsoft.com/using/guidance-for-open-source-usage/notice-faq/#q-when-do-i-need-a-notice)
+3. [NOTICE FAQ | Docs - Microsoft Open Source](https://docs.opensource.microsoft.com/using/guidance-for-open-source-usage/notice-faq/#q-does-cela-need-to-review-the-notice)
+
+So it seems we would need a notice if:
+- compiled build or any other scenario where the recipient can no longer access or view the code in source code form (attribute the full dependency tree that is distributed).
+  Since it's Python, we only deliver source files in Python. This SDK does not even include native code in C/C++.
+- source code repository (attribute open source copied into the repo; not referenced dependencies).
+  This SDK doesn't copy/paste OSS code from 3P offering.
+
+The SDK package we put on PyPI doesn't contain any source file that is copied from any other OSS components. So my understanding is that we don't need a NOTICE.
+
+# Python emitter issue with bulleted list TypeSpec doc string, and other
+
+## question
+This TypeSpec repo/branch/folder: https://github.com/Azure/azure-rest-api-specs-pr/tree/feature/ai-foundry/agents-v2/specification/ai/Azure.AI.Projects
+
+Is emitted into this Python repo/branch/folder: https://github.com/Azure/azure-sdk-for-python/tree/feature/azure-ai-projects/2.0.0b1/sdk/ai/azure-ai-projects
+
+Using the command `tsp-client update --debug --local-spec-repo <path>`
+
+I have a green build, other than errors in the "Build Docs" stage, as seen in this build of the branc: https://dev.azure.com/azure-sdk/internal/_build/results?buildId=5527867&view=results
+
+I need some guidance on how to update TypeSpec to make these Python doc generation go away.
+
+The errors are the following:
+
+```
+updating environment: [new config] 7 added, 0 changed, 0 removed
+docstring of azure.ai.projects.models.Reasoning.generate_summary:6: WARNING: Inline strong start-string without end-string. [docutils]
+docstring of azure.ai.projects.models.WorkflowDefinition.workflow:2: WARNING: Duplicate explicit target name: "learn more". [docutils]
+docstring of azure.ai.projects.models.WorkflowDefinition.workflow:2: WARNING: Duplicate explicit target name: "learn more". [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:54: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:61: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:64: ERROR: Unexpected indentation. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:65: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:67: ERROR: Unexpected indentation. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:79: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:82: ERROR: Unexpected indentation. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:83: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:89: ERROR: Unexpected indentation. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:90: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:109: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._models.Response:112: ERROR: Unexpected indentation. [docutils]
+docstring of azure.ai.projects.models.WorkflowDefinition.workflow:2: WARNING: Duplicate explicit target name: "learn more". [docutils]
+docstring of azure.ai.projects.models.Response.output:10: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+docstring of azure.ai.projects.models.Response.output:12: WARNING: Definition list ends without a blank line; unexpected unindent. [docutils]
+docstring of azure.ai.projects.models.Response.tools:9: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+docstring of azure.ai.projects.models.Response.tools:12: ERROR: Unexpected indentation. [docutils]
+docstring of azure.ai.projects.models.Response.tools:13: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+docstring of azure.ai.projects.models.Response.truncation:8: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+docstring of azure.ai.projects.models.Response.truncation:11: ERROR: Unexpected indentation. [docutils]
+docstring of azure.ai.projects.models.Response.truncation:12: WARNING: Block quote ends without a blank line; unexpected unindent. [docutils]
+docstring of azure.ai.projects.models.WorkflowDefinition.workflow:2: WARNING: Duplicate explicit target name: "learn more". [docutils]
+E:\src\sdk-repos\azure-sdk-for-python\sdk\ai\azure-ai-projects\.tox\sphinx\Lib\site-packages\azure\ai\projects\models\__init__.py:docstring of azure.ai.projects.models._enums.ServiceTier:4: WARNING: Bullet list ends without a blank line; unexpected unindent. [docutils]
+```
+
+It comes from two TypeSpec models, direct link here:
+Response model - https://github.com/Azure/azure-rest-api-specs-pr/blob/feature/ai-foundry/agents-v2/specification/ai/Azure.AI.Projects/.external-readonly/openai.external.typespec/responses/custom.tsp#L38
+ServiceTier union - https://github.com/Azure/azure-rest-api-specs-pr/blob/feature/ai-foundry/agents-v2/specification/ai/Azure.AI.Projects/.external-readonly/openai.external.typespec/responses/custom.tsp#L38
+
+## answer
+Within the pyproject.toml for the problematic package, disable the sphinx environment is my advice. that way you won't hit these sphinx failures.
+
+```
+[tool.azure-sdk-build]
+sphinx = false
+```

QA/python_2025_11_07.md

@@ -0,0 +1,66 @@
+# When emitting Python from TypeSpec, how do I rename an operation path parameter?
+
+## question
+I have this operation defined in TypeSpec. I know I can add the `@clientName` to change the name of the input parameter in the emitted Python operation method. This TypeSpec compiles fine (see [full TypeSpec file here](https://github.com/Azure/azure-rest-api-specs-pr/blob/feature/ai-foundry/agents-v2/specification/ai/Azure.AI.Projects/agents/operations.tsp#L56)):
+
+```
+interface Agents {
+
+  @post
+  @route("/agents/{agent_name}")
+  @tag("Agents")
+  updateAgent is AgentOperation<
+    {
+      @path
+      @clientName("name", "python")
+      agent_name: string;
+
+      ...UpdateAgentRequest;
+    },
+    AgentObject
+  >;
+
+}
+```
+
+However I'm trying to avoid adding @clientName decorators in TypeSpec model definitions, and instead have them all in the client.tsp file.
+
+My question: how do I do the above, but using @@clientName in client.tsp file instead? I've tried many things, but no luck. Including:
+
+```
+@@clientName(Agents.updateAgent::parameters.agent_name, "name", "python");
+```
+
+which files to compile with error `Model doesn't have member agent_name`. In the above case it's not a member but a path, so perhaps that's the reason for the error, but I don't know how to fix it.
+
+## answer
+You could define an alias to include path parameters then rename the path parameters by the alias like :
+```
+
+alias UpdateAgentParams = {
+    @path originalName1: string;
+};
+
+interface MyOp {
+  @post
+  @route("/name/{originalName1}")
+  updateAgent1 is AgentOperation<
+    UpdateAgentParams,
+    void
+  >;
+
+  @post
+  @route("/name/{originalName2}")
+  updateAgent2 is AgentOperation<
+    {
+      @path originalName2: string;
+    },
+    void
+  >;
+}
+
+@@clientName(UpdateAgentParams.originalName1, "newName1"); // OK
+
+// Can't work since Typespec can't refer to parameter defined in an anonymous model in Template
+// @clientName(MyOp.updateAgent2::parameters.originalName2, "newName2");
+```

QA/python_2025_11_14.md

@@ -0,0 +1,22 @@
+# "black" job in pipeline fails, but when I run locally, the tool does not make any changes
+
+## question
+I like to run the "black" tool before PRs, and I ask others in my project to do the same. A few hours ago I found out that I can turn on this check in the pipeline. I was happy to see this. So I added the following to pyproject.toml:
+
+```
+[tool.azure-sdk-build]
+black = true
+```
+
+I run "black" before commiting my last change to the PR, and no updates were needed.
+
+But the pipeline called out a "black" failure: https://dev.azure.com/azure-sdk/public/_build/results?buildId=5606772&view=logs&j=b70e5e73-bbb6-5567-0939-8415943fadb9&t=efe9ac6d-3fdb-50af-24e1-4319f36eecb4
+
+I see the pipeline used black version 24.4.0. I had a newer version when I run locally. I install 24.4.0 and run that, but it also did not do any changes to the code.
+
+Any idea how to fix it? (other than removing it from the pipeline...).
+
+## answer
+I tried the same command used by ci: `python -m azpysdk.main black --isolate /mnt/vss/_work/1/s/sdk/ai/azure-ai-projects`, and find that your project has one file reformatted.
+
+NOTE: the command ci uses need some time and I recommend you use one simple command which usually has same effect and much faster: `black sdk/ai/azure-ai-projects/ -l 120`

QA/python_2025_11_28.md

@@ -0,0 +1,66 @@
+# Generate docs CI check keeps failing
+
+## question
+I’m working on a Python SDK PR and the **generate-docs** CI check continues failing.
+The error points to `CreateDeploymentDetails.azure_resource_ids` with:
+> “Definition list ends without a blank line; unexpected unindent.”
+I’ve already updated the docstring based on this message, but CI still reports the same failure.
+Here is the error log: [Pipelines - Run 20251209.42 logs](https://dev.azure.com/azure-sdk/public/public%20Team/_build/results?buildId=5652585&view=logs&j=7b8caaf3-aec7-5f50-aa20-46d4a6342ac3&t=286a7ccb-1111-5827-fc90-5c974fed4202&l=313)
+
+For reference:
+- Generated model location: https://github.com/Azure/azure-sdk-for-python/blob/a03b420f1222064b0c332d772ed8955e8ae578d1/sdk/cognitivelanguage/azure-ai-language-conversations-authoring/azure/ai/language/conversations/authoring/models/_models.py#L633
+- Patched model location: https://github.com/Azure/azure-sdk-for-python/blob/a03b420f1222064b0c332d772ed8955e8ae578d1/sdk/cognitivelanguage/azure-ai-language-conversations-authoring/azure/ai/language/conversations/authoring/models/_models.py#L633
+
+Could you please advise:
+1. Is there a recommended way to run the generate-docs step locally so I can verify the fix without pusshing repeatedly?
+2. Any guidance on the correct docstring formatting expected here?
+
+## answer
+There is an easy way to repro your failures: install `eng/tools/azure-sdk-tools[build]` . then just `azpysdk sphinx .` from your package directory.
+
+# Pytest failure: test fixtures not being recognized
+
+## question
+I’m following the Python SDK testing guidance (link: [Dataplane Codegen Quick Start for Test · Azure/azure-sdk-for-python Wiki](https://github.com/Azure/azure-sdk-for-python/wiki/Dataplane-Codegen-Quick-Start-for-Test)), but I’m seeing an issue related to fixtures not being recognized by pytest.
+When running the tests, I get the following error: **fixture 'text_analysis_endpoint' not found**.
+
+But I have the environment variables correctly configured in my `.env` , and I have a `conftest.py` file that follows the guidance exactly.
+For reference, here is the `conftest.py` I’m using: [azure-sdk-for-python/sdk/cognitivelanguage/azure-ai-textanalytics/tests/conftest.py at dd52517afed9…](https://github.com/Azure/azure-sdk-for-python/blob/dd52517afed9dffae02a0239bb397be091643310/sdk/cognitivelanguage/azure-ai-textanalytics/tests/conftest.py)
+```
+import pytest
+
+@pytest.fixture(scope="session", autouse=True)
+def start_proxy(test_proxy, patch_sleep, patch_async_sleep):
+    return
+```
+
+It seems like the fixtures are not being loaded into the test environment.
+Did I miss something in the setup? Any pointers would be greatly appreciated — thank you!
+
+## answer
+The issue could resolved by directly defining the endpoint/key fixtures in conftest.py.
+```
+import pytest
+from devtools_testutils import EnvironmentVariableLoader
+
+# Environment variable keys
+ENV_ENDPOINT = "TEXT_ANALYSIS_ENDPOINT"
+ENV_KEY = "TEXT_ANALYSIS_KEY"
+
+@pytest.fixture(scope="session")
+def text_analysis_endpoint(environment_variables: EnvironmentVariableLoader) -> str:
+    """Endpoint for Text Analysis tests."""
+    return environment_variables.get(ENV_ENDPOINT)
+
+@pytest.fixture(scope="session")
+def text_analysis_key(environment_variables: EnvironmentVariableLoader) -> str:
+    """API key for Text Analysis tests."""
+    return environment_variables.get(ENV_KEY)
+
+# autouse=True will trigger this fixture on each pytest run
+# test_proxy auto-starts the test proxy
+# patch_sleep and patch_async_sleep remove wait times during polling
+@pytest.fixture(scope="session", autouse=True)
+def start_proxy(test_proxy, patch_sleep, patch_async_sleep):
+    return
+```