From 3764591183c811b61e159020d1ca8c346579d721 Mon Sep 17 00:00:00 2001 From: Paul Van Eck Date: Tue, 5 May 2026 21:03:31 +0000 Subject: [PATCH 1/3] [Docs] Misc updates Applied some formatting, cleanup, and updating of various docs. Signed-off-by: Paul Van Eck --- doc/README.md | 2 +- doc/dev/README.md | 54 +++++++++++++++----- doc/dev/code_snippets.md | 4 +- doc/dev/dev_setup.md | 19 ++++++- doc/dev/engineering_assumptions.md | 27 ---------- doc/dev/find_sdk/find_sdk_in_cli_command.md | 4 +- doc/dev/issues/resolve_issues_effectively.md | 6 +-- doc/dev/perfstress_tests.md | 6 +-- doc/dev/release.md | 35 ++----------- doc/dev/tests.md | 2 +- doc/python_version_support_policy.md | 17 ++++-- 11 files changed, 83 insertions(+), 93 deletions(-) delete mode 100644 doc/dev/engineering_assumptions.md diff --git a/doc/README.md b/doc/README.md index ac43f47fb97a..8997ad4c3633 100644 --- a/doc/README.md +++ b/doc/README.md @@ -13,6 +13,7 @@ This folder contains documentation for the Azure SDK for Python repository. - [Send Request](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/send_request.md) - Send request pattern documentation - [Analyze Check Versions](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/analyze_check_versions.md) - Check version analysis - [Tool Usage Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/tool_usage_guide.md) - How to use the `azpysdk` CLI tool +- [SDK and AI](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/sdk_and_ai.md) - AI-assisted SDK development guidance ## Developer Documentation @@ -47,7 +48,6 @@ See the [dev](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/) - [Customize Long Running Operations](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/customize_long_running_operation.md) - LRO customization - [CredScan Process](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/credscan_process.md) - Credential scanning - [Recording Migration Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/recording_migration_guide.md) - Migrating test recordings -- [Engineering Assumptions](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/engineering_assumptions.md) - SDK engineering assumptions - [Conda Builds](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-builds.md) / [Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-release.md) / [Dev Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-release-dev.md) - Conda packaging ## Sphinx Reference Documentation diff --git a/doc/dev/README.md b/doc/dev/README.md index c14a53d11fa5..c03bc3aae3bd 100644 --- a/doc/dev/README.md +++ b/doc/dev/README.md @@ -2,27 +2,55 @@ This folder contains documentation for developers of SDKs: internal teams at Microsoft, or advanced contributors. -Overview of the documents: -- [Developer Set-Up](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/dev_setup.md) : How to create a development environment for this repo -- [Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/release.md) : How to release a package when ready -- [Packaging](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/packaging.md) : How to organize packaging information for packages under `azure` -- [Changelog](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/changelog_updates.md) : How to document package changes using Chronus (for packages with `pyproject.toml`) -- [Testing](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md): How to write unit and functional tests for a library -- [Docstrings](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/docstring.md): How to document an SDK (API View) and our documentation at [MS Docs][ms_docs] and the [azure.github.io][azure_github_io] site. -- [Type Hints and Type Checking](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking.md) / [Cheatsheet](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md): How to add type hints to your library code and run type checking. +## Getting Started -The [mgmt](https://github.com/Azure/azure-sdk-for-python/tree/main/doc/dev/mgmt) folder contains information specific to management packages (i.e. packages prefixed by `azure-mgmt`) +- [Developer Set-Up](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/dev_setup.md) - How to create a development environment for this repo +- [Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/release.md) - How to release a package when ready +- [Packaging](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/packaging.md) - How to organize packaging information for packages under `azure` +- [Changelog](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/changelog_updates.md) - How to document package changes using Chronus (for packages with `pyproject.toml`) +- [Package Versioning](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/package_version/package_version_rule.md) - Version numbering rules -### Troubleshooting +## Testing + +- [Testing](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md) - How to write unit and functional tests for a library +- [Advanced Testing](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests-advanced.md) - Advanced testing topics +- [Performance Testing](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/perfstress_tests.md) - How to write and run perf tests +- [Recording Migration Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/recording_migration_guide.md) - Migrating test recordings +- [CredScan Process](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/credscan_process.md) - Credential scanning + +## Code Quality & Documentation + +- [Docstrings](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/docstring.md) - How to document an SDK (API View) and our documentation at [MS Learn][ms_learn] and the [azure.github.io][azure_github_io] site +- [Type Hints and Type Checking](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking.md) / [Cheatsheet](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/static_type_checking_cheat_sheet.md) - How to add type hints and run type checking +- [Pylint](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/pylint_checking.md) - Pylint checking guidance +- [Sample Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/sample_guide.md) - How to write SDK samples +- [Code Snippets](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/code_snippets.md) - How to include code snippets in docs + +## Troubleshooting - [Common Issues and FAQ](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/common_issues.md) - Common SDK issues and how to resolve them +- [Test Proxy Troubleshooting](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/test_proxy_troubleshooting.md) - Test proxy issues +- [Debug Guide](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/debug_guide.md) - Debugging tips +- [Resolve Issues Effectively](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/issues/resolve_issues_effectively.md) - How to triage and resolve customer issues +- [Find SDK in CLI Command](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/find_sdk/find_sdk_in_cli_command.md) - Mapping CLI commands to SDK packages -### Code Generation +## Code Generation - [Dataplane SDK Generation](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/dataplane_generation.md) - Generate a dataplane SDK from a TypeSpec definition +- [Management Plane](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/mgmt/) - Management plane SDK documentation +- [Customize Long Running Operations](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/customize_long_running_operation.md) - LRO customization + +## AI-Assisted Development + +- [AI Prompt Workflow](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/ai/ai_prompt_workflow.md) - Using AI agents for SDK development +- [TypeSpec Generation with AI](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/ai/typespec_generation.md) - AI-assisted TypeSpec generation + +## Conda -### Additional Topics +- [Conda Builds](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-builds.md) - Conda packaging +- [Conda Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-release.md) - Conda release process +- [Conda Dev Release](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/conda-release-dev.md) - Conda dev release process -[ms_docs]: https://docs.microsoft.com/python/api/overview/azure/appconfiguration-readme?view=azure-python +[ms_learn]: https://learn.microsoft.com/python/api/overview/azure/appconfiguration-readme?view=azure-python [azure_github_io]: https://azure.github.io/azure-sdk-for-python/ diff --git a/doc/dev/code_snippets.md b/doc/dev/code_snippets.md index 7c40bb893b00..de136c8232ac 100644 --- a/doc/dev/code_snippets.md +++ b/doc/dev/code_snippets.md @@ -29,7 +29,7 @@ https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/samp Instead of copying the code snippet into README which is hard to maintain and validate, we add reference to the sample snippet in README. We use the annotation `\` to refer the code snippet in README file. -If you have a file in `samples\text_example_async.py` with a snippet named `asyncio`, you can reference it in your README like: +If you have a file in `samples/test_example_async.py` with a snippet named `asyncio`, you can reference it in your README like: ````markdown @@ -40,7 +40,7 @@ If you have a file in `samples\text_example_async.py` with a snippet named `asyn > Make sure you include a Python code fence within the snippet reference! -## Run update_snippet tool +## Run update_snippet tool The update_snippet tool is included in the [azpysdk CLI](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/tool_usage_guide.md), which is installed with `azure-sdk-tools`. diff --git a/doc/dev/dev_setup.md b/doc/dev/dev_setup.md index 1306904e5387..e9e9498f4943 100644 --- a/doc/dev/dev_setup.md +++ b/doc/dev/dev_setup.md @@ -25,12 +25,20 @@ or execute the various commands available in the toolbox. You can initialize a virtual environment this way: ``` - python -m venv env # Might be "python3" or "py -3.8" depending on your Python installation + python -m venv env # Might be "python3" or "py" depending on your Python installation source env/bin/activate # Linux shell (Bash, ZSH, etc.) only ./env/scripts/activate # PowerShell only ./env/scripts/activate.bat # Windows CMD only ``` + Alternatively, you can use [uv][uv] which is faster and handles Python version management automatically: + + ``` + uv venv + source .venv/bin/activate # Linux shell (Bash, ZSH, etc.) only + .venv\Scripts\activate # PowerShell only + ``` + 4. Setup your development environment Install the development requirements for a specific library (located in the `dev_requirements.txt` file at the root of the library) and an editable install of your library. This will also install `azure-sdk-tools` which provides the `azpysdk` CLI for running checks. For example, to install requirements for `azure-ai-formrecognizer`: @@ -40,9 +48,15 @@ or execute the various commands available in the toolbox. azure-sdk-for-python/sdk/formrecognizer/azure-ai-formrecognizer> pip install -e . ``` + Or with uv: + ``` + azure-sdk-for-python/sdk/formrecognizer/azure-ai-formrecognizer> uv pip install -r dev_requirements.txt + azure-sdk-for-python/sdk/formrecognizer/azure-ai-formrecognizer> uv pip install -e . + ``` + 5. Create a .env file to store your secrets. - The recommended place to store your .env file in the root of the SDK repository, as it will be gitignored. + Create a `.env` file to store secrets needed for live tests (e.g. connection strings, resource endpoints). Place it in the root of the SDK repository where it is gitignored. See [tests.md][tests] for details on which environment variables are needed for each package. ## Follow test-running guidance @@ -54,3 +68,4 @@ After following the steps above, you'll be able to run recorded SDK tests with ` [python_312]: https://apps.microsoft.com/detail/9ncvdn91xzqp [tests]: https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/tests.md [virtual_environment]: https://docs.python.org/3/tutorial/venv.html +[uv]: https://docs.astral.sh/uv/ diff --git a/doc/dev/engineering_assumptions.md b/doc/dev/engineering_assumptions.md deleted file mode 100644 index 5debb67a2ae3..000000000000 --- a/doc/dev/engineering_assumptions.md +++ /dev/null @@ -1,27 +0,0 @@ -## Engineering System Assumptions, Gotchas, and Minutiae - -1. All wheels are generated with influence from `setup.cfg` at the built package root. This means that for most of our packages, the `universal` flag is set within the `setup.cfg`. - -``` -[bdist_wheel] -universal=1 -``` -2. If a package does _not_ have `universal` set, then the default build will produce a wheel for `py3`. This is due to the fact that wheels are currently generated by a CI step running `Python 3.6`. - -## Build - -Build CI for `azure-sdk-for-python` essentially builds and tests packages in one of two methodologies. - -### Individual Packages -1. Leverage `azpysdk` to create wheel, install, and execute tests against newly installed wheel -2. Tests each package in isolation (outside of dev_requirements.txt dependencies + necessary `pylint` and `mypy`) - -### Global Method - -1. Install on packages (and their dev_requirements!) in one go. -2. Run `pytest , pytest ` where folders correspond to package folders - 1. While all packages are installed alongside each other, each test run is individual to the package. This has the benefit of not allowing `packageA`'s `conftest.py` to mess with `packageB`'s environment.' - -### So when do they run? - -A standard pull request will option target the `Individual Packages` option. On a nightly cadence, the `python - client` build installs the entire world and tests in _both_ methodologies outlined above. diff --git a/doc/dev/find_sdk/find_sdk_in_cli_command.md b/doc/dev/find_sdk/find_sdk_in_cli_command.md index 330c17a07379..e19abf8ce15f 100644 --- a/doc/dev/find_sdk/find_sdk_in_cli_command.md +++ b/doc/dev/find_sdk/find_sdk_in_cli_command.md @@ -1,4 +1,4 @@ -How to Find the SDK in CLI +How to Find the SDK in CLI ====== This article aims to provide a guide for customer to find the sdk in Azure CLI. @@ -91,6 +91,6 @@ In this file, you could search the function name to find the function definition Above the `begin_delete` function, you could find it from [here](https://github.com/Azure/azure-sdk-for-python/blob/9d3f4aaf3125cc6ae63c8425d0d15d20d488d61e/sdk/resources/azure-mgmt-resource/azure/mgmt/resource/resources/operations/_operations.py#L4188). The same, the `create_or_update` function is [here](https://github.com/Azure/azure-sdk-for-python/blob/9d3f4aaf3125cc6ae63c8425d0d15d20d488d61e/sdk/resources/azure-mgmt-resource/azure/mgmt/resource/resources/operations/_operations.py#L4019). -Finally, you also could find the usage of function by [Azure doc](https://docs.microsoft.com/azure/developer/python/sdk/examples/azure-sdk-example-resource-group#3-write-code-to-provision-a-resource-group) or [Azure samples](https://github.com/Azure-Samples/azure-samples-python-management). +Finally, you also could find the usage of function by [Azure doc](https://learn.microsoft.com/azure/developer/python/sdk/examples/azure-sdk-example-resource-group#3-write-code-to-provision-a-resource-group) or [Azure samples](https://github.com/Azure-Samples/azure-samples-python-management). Feel free to contact Azure SDK team at any time through any channels. We are passionate to build the world-class cloud product. diff --git a/doc/dev/issues/resolve_issues_effectively.md b/doc/dev/issues/resolve_issues_effectively.md index 0d443b23c8a6..58e109f39f93 100644 --- a/doc/dev/issues/resolve_issues_effectively.md +++ b/doc/dev/issues/resolve_issues_effectively.md @@ -29,7 +29,7 @@ If you can provide detailed reproduction steps, it will help us locate and solve If the code you use needs to set wait() function for the Long Running Operation to wait for the result, it should be the SDK of Track1. We have stopped maintenance at present. We strongly recommend that you update the SDK version. Then you will find that in the SDK of Track2, we all use the function name prefixed with `begin_` for LRO operations, and the result() method can be used to get the returned result. -(More Details: [guidance][guidance]) +(More Details: [guidance][guidance]) ### Possible Error from Service Since the python SDK is generated based on the [rest API][rest API], it will not deliberately change the returned results. So if you think the returned result is not as expected, please open the issue under the [rest issue][rest issue]. @@ -56,7 +56,6 @@ Fault localization is critical to bug fix. Some tips: 2. Step-by-step debugging. Most modern IDEs provide integrated debugging experience. - ### Fix the bug Once you have confirmed the bug and found the fault location, it should be easy to fix the bug. Add a sample if it is missing. Remember to tell users when the fix will released. @@ -66,9 +65,6 @@ Once you have confirmed the bug and found the fault location, it should be easy If the issue is not from the SDK but from the [rest API][rest API], you can reply to the user and reopen the issue in the appropriate place. -### Error like (AttributeError: 'PipelineResponse' object has no attribute 'get') -When this error occurs, you can check the version of `msrest` and upgrade it to latest version then try again. - [sample repo]: https://github.com/Azure-Samples/azure-samples-python-management [rest API]: https://github.com/Azure/azure-rest-api-specs diff --git a/doc/dev/perfstress_tests.md b/doc/dev/perfstress_tests.md index 405694cdc9e1..ab13746bdcd3 100644 --- a/doc/dev/perfstress_tests.md +++ b/doc/dev/perfstress_tests.md @@ -344,7 +344,7 @@ class UploadTest(_StorageStreamTestBase): # Setup service clients blob_name = "uploadtest" self.blob_client = self.service_client.get_blob_client(self.container_name, blob_name) - self.async_blob_client = self.async_serive_client.get_blob_client(self.container_name, blob_name) + self.async_blob_client = self.async_service_client.get_blob_client(self.container_name, blob_name) # Setup readable file-like upload data sources, using the configurable 'size' argument self.upload_stream = RandomStream(self.args.size) @@ -388,7 +388,7 @@ class DownloadTest(_StorageStreamTestBase): # Setup service clients blob_name = "downloadtest" self.blob_client = self.service_client.get_blob_client(self.container_name, blob_name) - self.async_blob_client = self.async_serive_client.get_blob_client(self.container_name, blob_name) + self.async_blob_client = self.async_service_client.get_blob_client(self.container_name, blob_name) self.download_stream = WriteStream() @@ -475,7 +475,7 @@ perfstress_tests # Running the tests In order to run the performance tests, the `devtools_testutils` package must be installed. This is done as part of the `dev_requirements`. -Start be creating a new virtual environment for your perf tests. This will need to be a Python 3 environment, preferably >=3.7. +Start be creating a new virtual environment for your perf tests. This will need to be a Python 3 environment. Note that tests for T1 and T2 SDKs usually cannot be run from the same environment, and will need to be setup separately. ### Setup for test resources diff --git a/doc/dev/release.md b/doc/dev/release.md index d3481ad5cc11..d4858ee5add4 100644 --- a/doc/dev/release.md +++ b/doc/dev/release.md @@ -15,14 +15,12 @@ For client (data plane) packages, ensure that: Python packages are uploaded to [PyPI](https://pypi.org/). Once you've uploaded to PyPI, there's no way to overwrite the package. In case of problems, you'll need to increment the version number. Be sure that before going forward your package has passed all the necessary testing. -### Production - Deploy with Azure Dev Ops +### Production - Deploy with Azure DevOps -To avoid "accidental" pushes to our target repositories, [approval](https://docs.microsoft.com/azure/devops/pipelines/release/approvals/approvals?view=azure-devops) will be requested directly prior to the final PyPI publish. Reference this [wiki page](https://aka.ms/python-approval-groups) and click on `Release to PyPI Approvers` to add yourself to the group for PyPI publishing. +To avoid "accidental" pushes to our target repositories, [approval](https://learn.microsoft.com/azure/devops/pipelines/release/approvals/approvals?view=azure-devops) will be requested directly prior to the final PyPI publish. Reference this [page](https://aka.ms/azsdk/access) Instead of a single central pipeline, the python SDK has moved to `service directory` associated build pipelines. These are driven by yml templates at the root of each service folder. [Example for storage service folder.](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/storage/ci.yml#L44) -As an aside, please note that the preview feature `multi-stage pipelines` must be enabled to properly interact with unified pipelines. If you aren't aware, find out how to enable by visiting [this link.](https://docs.microsoft.com/azure/devops/project/navigation/preview-features?view=azure-devops) - #### Releasing Through Unified Pipelines 1. Begin by locating your pipeline on the `internal` project under the `python` folder. Naming convention is `python - `. @@ -35,30 +33,7 @@ Validate artifacts prior to clicking `approve` on the release stage for the pack [Additional Internal Wiki Walkthrough](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/69/Package-release-via-Unified-Pipelines) -### Production - Deploy manually - -To build a package manually: -``` -python .\build_package.py azure-mgmt-myservice -``` - -This will a sdist and a wheel file. This requires `wheel` package installed in your environment. - -If you want to manually release on a regular basis, you should create a .pypirc: -``` -[pypi] -repository = https://pypi.python.org/pypi -username = -password = -``` - -To upload to production: -``` -twine upload dist\*.zip -twine upload dist\*.whl -``` - -It's recommended that you create a Github tag using the format "packagename_version". Example: `azure-mgmt-compute_2.0.0` +> **Note:** All releases to PyPI are handled through the ESRP release process. Manual uploads via `twine` are no longer permitted. See [ESRP Release Process](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/esrp_release.md) for details. # NOTE REGARDING ARTIFACTS Note that the unified pipeline will maintain a separate release step for each defined artifact in the `Artifacts` parameter in the relevant `ci.yml` file. [Example](https://github.com/Azure/azure-sdk-for-python/blob/cffaa424f4198bae99033c8ab2474fe87fb2451a/sdk/storage/ci.yml#L44) @@ -80,7 +55,3 @@ Resulting Release Stages: ![Example Release Stages](./release_stage.png "Example Release Stages") This means that new `mgmt` packages **_must_** be added to this list of artifacts manually. - -# IMPORTANT NOTE - -If this is a new package (i.e. first release), the "microsoft" account MUST be added as owner of your package. Please contact the engineering system team to do so. diff --git a/doc/dev/tests.md b/doc/dev/tests.md index 61cd4a17b8d4..322b06e7954e 100644 --- a/doc/dev/tests.md +++ b/doc/dev/tests.md @@ -48,7 +48,7 @@ C:\Users> env\scripts\activate.bat # Windows CMD only To create virtual environment for different versions of Python use the `-p` flag to pass the specific Python executable you want to use ```cmd -C:\Users> python -m venv -p py38_venv +C:\Users> python -m venv -p py314_venv ``` ### SDK root directory diff --git a/doc/python_version_support_policy.md b/doc/python_version_support_policy.md index bdc2d43a1b0c..2e7a8acf41b0 100644 --- a/doc/python_version_support_policy.md +++ b/doc/python_version_support_policy.md @@ -6,16 +6,23 @@ End of support means, in the SDK context, that new features will not be supporte > **Note:** The "SDKs End Of Support" date is inclusive — the listed day is the last supported day, and the next day is the first unsupported day. +## Currently supported versions + | Python Version | PSF End of Support | SDKs End Of Support | |----------------|--------------------|---------------------| -| 2.7 ([PEP 373](https://peps.python.org/pep-0373/)) | April 2020 | January 2022 | -| 3.6 ([PEP 494](https://www.python.org/dev/peps/pep-0494/#lifespan)) | December 2021 | August 2022 | -| 3.7 ([PEP 537](https://www.python.org/dev/peps/pep-0537/#lifespan)) | June 2023 | December 2023 | -| 3.8 ([PEP 569](https://www.python.org/dev/peps/pep-0569/#lifespan)) | October 2024 | April 2025 | -| 3.9 ([PEP 596](https://www.python.org/dev/peps/pep-0596/#lifespan)) | October 2025 | April 30, 2026 | | 3.10 ([PEP 619](https://www.python.org/dev/peps/pep-0619/#lifespan)) | October 2026 | April 30, 2027 | | 3.11 ([PEP 664](https://www.python.org/dev/peps/pep-0664/#lifespan)) | October 2027 | April 30, 2028 | | 3.12 ([PEP 693](https://www.python.org/dev/peps/pep-0693/#lifespan)) | October 2028 | April 30, 2029 | | 3.13 ([PEP 719](https://www.python.org/dev/peps/pep-0719/#lifespan)) | October 2029 | April 30, 2030 | | 3.14 ([PEP 745](https://www.python.org/dev/peps/pep-0745/#lifespan)) | October 2030 | April 30, 2031 | | 3.15 ([PEP 790](https://www.python.org/dev/peps/pep-0790/#lifespan)) | October 2031 | April 30, 2032 | + +## End-of-life versions (no longer supported) + +| Python Version | PSF End of Support | SDKs End Of Support | +|----------------|--------------------|---------------------| +| 3.9 ([PEP 596](https://www.python.org/dev/peps/pep-0596/#lifespan)) | October 2025 | April 30, 2026 | +| 3.8 ([PEP 569](https://www.python.org/dev/peps/pep-0569/#lifespan)) | October 2024 | April 2025 | +| 3.7 ([PEP 537](https://www.python.org/dev/peps/pep-0537/#lifespan)) | June 2023 | December 2023 | +| 3.6 ([PEP 494](https://www.python.org/dev/peps/pep-0494/#lifespan)) | December 2021 | August 2022 | +| 2.7 ([PEP 373](https://peps.python.org/pep-0373/)) | April 2020 | January 2022 | From 1b39e06681a2c97f6a6531a437ec998f74c1e3ce Mon Sep 17 00:00:00 2001 From: Paul Van Eck Date: Wed, 6 May 2026 00:08:57 +0000 Subject: [PATCH 2/3] Updates Signed-off-by: Paul Van Eck --- doc/dev/dev_setup.md | 11 ++++++----- doc/dev/perfstress_tests.md | 2 +- doc/dev/release.md | 2 +- doc/dev/tests.md | 4 ++-- 4 files changed, 10 insertions(+), 9 deletions(-) diff --git a/doc/dev/dev_setup.md b/doc/dev/dev_setup.md index e9e9498f4943..d126ede3d418 100644 --- a/doc/dev/dev_setup.md +++ b/doc/dev/dev_setup.md @@ -26,17 +26,18 @@ or execute the various commands available in the toolbox. ``` python -m venv env # Might be "python3" or "py" depending on your Python installation - source env/bin/activate # Linux shell (Bash, ZSH, etc.) only - ./env/scripts/activate # PowerShell only - ./env/scripts/activate.bat # Windows CMD only + source env/bin/activate # Linux shell (Bash, ZSH, etc.) + .\env\Scripts\Activate.ps1 # PowerShell + .\env\Scripts\activate.bat # Windows CMD ``` Alternatively, you can use [uv][uv] which is faster and handles Python version management automatically: ``` uv venv - source .venv/bin/activate # Linux shell (Bash, ZSH, etc.) only - .venv\Scripts\activate # PowerShell only + source .venv/bin/activate # Linux shell (Bash, ZSH, etc.) + .\.venv\Scripts\Activate.ps1 # PowerShell + .\.venv\Scripts\activate.bat # Windows CMD ``` 4. Setup your development environment diff --git a/doc/dev/perfstress_tests.md b/doc/dev/perfstress_tests.md index ab13746bdcd3..71f2f7cad2b8 100644 --- a/doc/dev/perfstress_tests.md +++ b/doc/dev/perfstress_tests.md @@ -475,7 +475,7 @@ perfstress_tests # Running the tests In order to run the performance tests, the `devtools_testutils` package must be installed. This is done as part of the `dev_requirements`. -Start be creating a new virtual environment for your perf tests. This will need to be a Python 3 environment. +Start by creating a new virtual environment for your perf tests. This will need to be a Python 3 environment. Note that tests for T1 and T2 SDKs usually cannot be run from the same environment, and will need to be setup separately. ### Setup for test resources diff --git a/doc/dev/release.md b/doc/dev/release.md index d4858ee5add4..2e3b7c6695e1 100644 --- a/doc/dev/release.md +++ b/doc/dev/release.md @@ -17,7 +17,7 @@ Python packages are uploaded to [PyPI](https://pypi.org/). Once you've uploaded ### Production - Deploy with Azure DevOps -To avoid "accidental" pushes to our target repositories, [approval](https://learn.microsoft.com/azure/devops/pipelines/release/approvals/approvals?view=azure-devops) will be requested directly prior to the final PyPI publish. Reference this [page](https://aka.ms/azsdk/access) +To avoid "accidental" pushes to our target repositories, [approval](https://learn.microsoft.com/azure/devops/pipelines/release/approvals/approvals?view=azure-devops) will be requested directly prior to the final PyPI publish. Reference this [page](https://aka.ms/azsdk/access) to learn how to request access to Azure SDK DevOps for release approval. Instead of a single central pipeline, the python SDK has moved to `service directory` associated build pipelines. These are driven by yml templates at the root of each service folder. [Example for storage service folder.](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/storage/ci.yml#L44) diff --git a/doc/dev/tests.md b/doc/dev/tests.md index 322b06e7954e..14caabaa25dc 100644 --- a/doc/dev/tests.md +++ b/doc/dev/tests.md @@ -45,10 +45,10 @@ C:\Users> env\scripts\activate.bat # Windows CMD only (env) C:\Users> ``` -To create virtual environment for different versions of Python use the `-p` flag to pass the specific Python executable you want to use +To create virtual environment for different versions of Python, use the executable for that version. For example, for Python 3.14: ```cmd -C:\Users> python -m venv -p py314_venv +C:\Users> -m venv py314_venv ``` ### SDK root directory From a69634fddf64db0ea89e5331e8a904ea1221ae42 Mon Sep 17 00:00:00 2001 From: Paul Van Eck Date: Wed, 6 May 2026 17:06:42 +0000 Subject: [PATCH 3/3] Updates Remove docs regarding legacy t1 perf tests. Signed-off-by: Paul Van Eck --- doc/dev/perfstress_tests.md | 32 ++------------------------------ 1 file changed, 2 insertions(+), 30 deletions(-) diff --git a/doc/dev/perfstress_tests.md b/doc/dev/perfstress_tests.md index 71f2f7cad2b8..c0f7fa851bf0 100644 --- a/doc/dev/perfstress_tests.md +++ b/doc/dev/perfstress_tests.md @@ -9,7 +9,6 @@ 2. [Adding performance tests to an SDK](#adding-performance-tests-to-an-sdk) - [Writing a test](#writing-a-test) - [Writing a batch test](#writing-a-batch-test) - - [Adding legacy T1 tests](#adding-legacy-t1-tests) 3. [Running the tests](#running-the-tests) - [Running the system tests](#running-the-system-tests) 4. [Readme](#readme) @@ -113,7 +112,6 @@ class PerfStressTest: async def run_async(self) -> None: # Must be implemented. This will be the perf test to be run asynchronously. - # If writing a test for an SDK without async support (e.g. a T1 legacy SDK), implement this method and raise an exception. ``` ### The BatchPerfTest baseclass @@ -133,7 +131,6 @@ class BatchPerfTest: # Run cumulative operation(s) asynchronously - i.e. an operation that results in more than a single logical result. # When inheriting from BatchPerfTest, this method will need to be implemented. # Must return the number of completed results represented by a single successful test run. - # If writing a test for an SDK without async support (e.g. a T1 legacy SDK), implement this method and raise an exception. ``` ### The EventPerfTest baseclass @@ -455,28 +452,9 @@ class MessageReceiveTest(BatchPerfTest): ``` -## Adding legacy T1 tests -To compare performance against T1 libraries, you can add tests for a legacy SDK. To do this, add a submodule into the `perfstress_tests` module called `T1_legacy_tests` (and add an empty `__init__.py`). -To configure the exact T1 SDK you wish to compare perf against, add a `t1_test_requirements.txt` file to install any package requirements. Note that this will likely be incompatible with the T2 SDK testing environment, and running the legacy tests will probably need to be from a separate virtual environment (see the [Running the tests](#running-the-tests) section below). -Writing the tests themselves will be done exactly the same way - however it's recommended to prefix the test names with `Legacy` (or similar) to avoid confusion. -``` -perfstress_tests -│ README.md -| __init__.py -│ upload.py -| download.py -│ -└───T1_legacy_tests -| | __init__.py -│ │ legacy_upload.py -│ │ legacy_download.py -| | t1_test_requirements.txt -``` - # Running the tests In order to run the performance tests, the `devtools_testutils` package must be installed. This is done as part of the `dev_requirements`. -Start by creating a new virtual environment for your perf tests. This will need to be a Python 3 environment. -Note that tests for T1 and T2 SDKs usually cannot be run from the same environment, and will need to be setup separately. +Start by creating a new virtual environment for your perf tests. This will need to be a [supported Python version](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/python_version_support_policy.md). ### Setup for test resources Depending on the tests, some resource configuration (e.g. environment variables) may need to be done first. This should documented in the perfstress_tests readme file. @@ -490,12 +468,6 @@ AZURE_STORAGE_CONNECTION_STRING= (env) ~/azure-storage-file-share> pip install -r dev_requirements.txt (env) ~/azure-storage-file-share> pip install -e . ``` -### Setup for T1 legacy perf test runs - -```cmd -(legacy-env) ~/azure-storage-file-share> pip install -r dev_requirements.txt -(legacy-env) ~/azure-storage-file-share> pip install tests/perfstress_tests/T1_legacy_tests/t1_test_requirements.txt -``` ### Test commands When `devtools_testutils` is installed, you will have access to the `perfstress` command line tool, which will scan the current module for runable perf tests. Only a specific test can be run at a time (i.e. there is no "run all" feature). @@ -503,7 +475,7 @@ When `devtools_testutils` is installed, you will have access to the `perfstress` ```cmd (env) ~/azure-storage-file-share> perfstress ``` -Using the `perfstress` command alone will list the available perf tests found. Note that the available tests discovered will vary depending on whether your environment is configured for the T1 or T2 SDK. +Using the `perfstress` command alone will list the available perf tests found. If your tests are not being discovered, run the `perfstressdebug` command instead for additional logging. ### Example test run command