diff --git a/doc/deprecation_process.md b/doc/deprecation_process.md index dcac872088cb..d759a669f464 100644 --- a/doc/deprecation_process.md +++ b/doc/deprecation_process.md @@ -67,7 +67,7 @@ Replace ALL existing text with a disclaimer in the following format. ## CHANGELOG.md and _version.py - Update the version in the `azure/mypackage/_version.py` file. The new version should be: - - A [post-release](https://peps.python.org/pep-0440/#post-releases) of the last released version **only if** this deprecation release contains no code changes (i.e. the only updates are to metadata files such as `README.md`, `CHANGELOG.md`, `setup.py` classifiers, `sdk_packaging.toml`, `ci.yml`, etc.). If the last released version is already a post-release, increment the existing post segment instead of appending another `.post1`. For example: + - A [post-release](https://peps.python.org/pep-0440/#post-releases) of the last released version **only if** this deprecation release contains no code changes (i.e. the only updates are to metadata files such as `README.md`, `CHANGELOG.md`, `pyproject.toml` classifiers, `sdk_packaging.toml`, `ci.yml`, etc.). If the last released version is already a post-release, increment the existing post segment instead of appending another `.post1`. For example: - If the last released version was 1.0.0b1, the new version should be 1.0.0b1.post1. - If the last released version was 1.0.0b1.post1, the new version should be 1.0.0b1.post2. - If the last released version was 1.2.3, the new version should be 1.2.3.post1. @@ -96,12 +96,9 @@ Replace ALL existing text with a disclaimer in the following format. ## pyproject.toml - Ensure `ci_enabled = false` is NOT present in pyproject.toml. If it is, remove the line, as this will prevent you from releasing the package. - -## setup.py - -- Update the `Development Status` classifier in `setup.py` to `Development Status :: 7 - Inactive`. +- Update the `Development Status` classifier in `pyproject.toml` to `Development Status :: 7 - Inactive`. - `Inactive` packages are disabled from most CI verification such as tests/mypy/pylint/etc., therefore the CI should be faster and have fewer requirements. - + ## ci.yml - Ensure the package is listed under `Artifacts` so that the artifact is generated for release. If not listed, add it. diff --git a/doc/dev/changelog_updates.md b/doc/dev/changelog_updates.md index c39d8d49e25e..dfe2ef9dca73 100644 --- a/doc/dev/changelog_updates.md +++ b/doc/dev/changelog_updates.md @@ -107,7 +107,7 @@ npx chronus status ## Packages Using `pyproject.toml` -Packages in this repository that use `pyproject.toml` (instead of or alongside `setup.py`) are fully supported by Chronus. The `pyproject.toml` is used for package metadata, while the `CHANGELOG.md` in the package directory remains the canonical user-facing changelog. +Packages in this repository that use `pyproject.toml` are fully supported by Chronus. The `pyproject.toml` is used for package metadata, while the `CHANGELOG.md` in the package directory remains the canonical user-facing changelog. Chronus reads the package version from the Python package metadata and writes changelog entries into the `CHANGELOG.md` file with `npx chronus changelog`. You do not need to manually edit `CHANGELOG.md` for your changes. diff --git a/doc/dev/dataplane_generation.md b/doc/dev/dataplane_generation.md index f01e2877faa5..af2f33999c9b 100644 --- a/doc/dev/dataplane_generation.md +++ b/doc/dev/dataplane_generation.md @@ -53,7 +53,7 @@ Normally, the folder structure would be something like: - `/tests`: folder of test files - `/samples`: folder of sample files - `azure-{service_name}-{module_name}`: package name. Usually, package name is same with part of **${PROJECT_ROOT} folder**. After release, you can find it in pypi. For example: you can find [azure-messaging-webpubsubservice](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/webpubsub/azure-messaging-webpubsubservice) in [pypi](https://pypi.org/project/azure-messaging-webpubsubservice/). - - there are also some other files (like setup.py, README.md, etc.) which are necessary for a complete package. + - there are also some other files (like `pyproject.toml`, README.md, etc.) which are necessary for a complete package. More details on the structure of Azure SDK repos is available in the [Azure SDK common repo](https://github.com/Azure/azure-sdk/blob/main/docs/policies/repostructure.md#sdk-directory-layout). diff --git a/doc/dev/packaging.md b/doc/dev/packaging.md index 64ea4e64c43f..3e6a8ee8031d 100644 --- a/doc/dev/packaging.md +++ b/doc/dev/packaging.md @@ -2,6 +2,8 @@ [comment]: # ( cspell:ignore myservice ) +> **Note:** This document covers legacy packaging using `setup.py`. New packages should use `pyproject.toml` instead. See the [`sdk/template/azure-template`](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/template/azure-template) for the current package template. + This article describes the recommendations for defining namespace packaging to release a package inside the `azure` namespace. Being inside the `azure` namespace means that a service `myservice` can be imported using: ```python import azure.myservice diff --git a/doc/dev/static_type_checking.md b/doc/dev/static_type_checking.md index a1b2bc731263..433f7823c37f 100644 --- a/doc/dev/static_type_checking.md +++ b/doc/dev/static_type_checking.md @@ -114,7 +114,11 @@ given the expressiveness of Python as a language. So, in practice, what should y - include the path to the `py.typed` in the MANIFEST.in ([example](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/MANIFEST.in)). This is important as it ensures the `py.typed` is included in both the sdist/bdist. - - set `include_package_data=True` and `package_data={"azure.core": ["py.typed"]}` in the setup.py. + - set `[tool.setuptools.package-data]` in `pyproject.toml` to include the `py.typed` file. For example: + ```toml + [tool.setuptools.package-data] + "azure.core" = ["py.typed"] + ``` Note that the key should be the namespace of where the `py.typed` file is found. 2) Add type hints anywhere in the source code where unit tests are worth writing. Consider typing/mypy as "free" tests @@ -173,7 +177,7 @@ class Tree: ``` If using `typing-extensions`, you must add it to the install dependencies for your library (do not rely on install by `azure-core`) -[[example](https://github.com/Azure/azure-sdk-for-python/blob/5fd52b9ee039f8711322bd7ea43af763d326291a/sdk/eventhub/azure-eventhub/setup.py#L73)]. +[[example](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/eventhub/azure-eventhub/pyproject.toml#L27)]. When importing a backported type into code, `typing-extensions` does a try/except on your behalf (either importing from `typing` if supported, or `typing-extensions` if the Python version is too old) so there is no need to do this check yourself. @@ -196,7 +200,7 @@ environment run in CI and brings in the third party stub packages necessary. To ### Run mypy -mypy is currently pinned to version [1.9.0](https://pypi.org/project/mypy/1.9.0/). +mypy is currently pinned to version [1.19.1](https://pypi.org/project/mypy/1.19.1/). To run mypy on your library, run `azpysdk mypy` at the package level: @@ -204,7 +208,7 @@ To run mypy on your library, run `azpysdk mypy` at the package level: If you don't want to use `azpysdk` you can also install and run mypy on its own: -`pip install mypy==1.9.0` +`pip install mypy==1.19.1` `.../azure-sdk-for-python/sdk/textanalytics/azure-ai-textanalytics>mypy azure` @@ -226,7 +230,7 @@ Full documentation on mypy config options found here: https://mypy.readthedocs.i ### Run pyright -We pin the version of pyright to version [1.1.287](https://github.com/microsoft/pyright). +We pin the version of pyright to version [1.1.407](https://github.com/microsoft/pyright). Note that pyright requires that node is installed. The command-line [wrapper package](https://pypi.org/project/pyright/) for pyright will check if node is in the `PATH`, and if not, will download it at runtime. @@ -236,7 +240,7 @@ To run pyright on your library, run `azpysdk pyright` at the package level: If you don't want to use `azpysdk` you can also install and run pyright on its own: -`pip install pyright==1.1.287` +`pip install pyright==1.1.407` `.../azure-sdk-for-python/sdk/textanalytics/azure-ai-textanalytics>pyright azure` @@ -268,7 +272,7 @@ To run verifytypes on your library, run `azpysdk verifytypes` at the package lev If you don't want to use `azpysdk` you can also install and run pyright/verifytypes on its own: -`pip install pyright==1.1.287` +`pip install pyright==1.1.407` `.../azure-sdk-for-python/sdk/textanalytics/azure-ai-textanalytics>pyright --verifytypes azure.ai.textanalytics --ignoreexternal` diff --git a/doc/dev/tests.md b/doc/dev/tests.md index 4e3bb6bfcf47..5366b5c3426b 100644 --- a/doc/dev/tests.md +++ b/doc/dev/tests.md @@ -57,8 +57,7 @@ In the root directory of our SDK, a number of mandatory files have been added. W - README.md. This is the description and guidance for customers or your SDK. Please see the guide on writing a README to make sure you have the complete [content requirements and formatting](https://review.learn.microsoft.com/help/platform/reference-document-sdk-client-libraries#readme). - CHANGELOG.md. This is where you will add the summary of changes for each new release. Please see [the guidance](https://azure.github.io/azure-sdk/policies_releases.html#changelog-guidance) for correct formatting. -- setup.py. This is the 'installer' for your Python SDK. Please see [the guide on Python packaging][packaging] for details on customizing this for a specific package. -- setup.cfg. This is an artifact used in building the Python package. Please see [the guide on Python packaging][packaging] for details. +- pyproject.toml. This is the package configuration file for your Python SDK. Please see [the guide on Python packaging][packaging] for details on customizing this for a specific package. - MANIFEST.in. This is an artifact used in building the Python package. Please see [the guide on Python packaging][packaging] for details. - dev_requirements.txt. This is for developers, and lists the packages required for running the tests and samples. See the dependency installation section below. - sdk_packaging.toml. This configuration is used by the packaging pipeline and no further modifications should be required. diff --git a/doc/eng_sys_checks.md b/doc/eng_sys_checks.md index 28839bf6d6af..9b1a4ccc5427 100644 --- a/doc/eng_sys_checks.md +++ b/doc/eng_sys_checks.md @@ -108,7 +108,7 @@ Setting any of the following variables to `true` at queue time suppresses the co ## The pyproject.toml -Starting with [this pr](https://github.com/Azure/azure-sdk-for-python/pull/28345), which checks apply to which packages are now **established** in a `pyproject.toml`, right next to each package's `setup.py`. This not only allows devs to fine-tune which checks that are applied at a package-level, but also seriously reduces confusion as to which checks apply when. +Starting with [this pr](https://github.com/Azure/azure-sdk-for-python/pull/28345), which checks apply to which packages are now **established** in a `pyproject.toml`. This not only allows devs to fine-tune which checks that are applied at a package-level, but also seriously reduces confusion as to which checks apply when. We default to **enabling** most of our checks like `pylint`, `mypy`, etc. Due to that, most `pyproject.toml` settings will likely be **disabling** checks. @@ -176,7 +176,7 @@ analyze_python_version = "3.11" This setting is read by `eng/scripts/dispatch_checks.py` and is passed to `azpysdk` via the `--python` flag (which requires `--isolate` and `uv`). This is useful for packages that use newer syntax or type features that require a more recent Python interpreter. -> **Note:** This setting only affects the Python interpreter version used for the analyze venv; it does not change the minimum supported Python version declared in `setup.py`/`pyproject.toml`. +> **Note:** This setting only affects the Python interpreter version used for the analyze venv; it does not change the minimum supported Python version declared in `pyproject.toml`. ## Environment variables important to CI @@ -402,7 +402,7 @@ azpysdk verifywhl . -Verifies that directories included in the sdist match the manifest file, and ensures that `py.typed` configuration is correct within `setup.py`. +Verifies that directories included in the sdist match the manifest file, and ensures that `py.typed` configuration is correct within `pyproject.toml`. To run locally: @@ -414,7 +414,7 @@ azpysdk verifysdist . -Verifies that the keyword `azure sdk` is present in the targeted package's `keywords` field (in `setup.py` or `pyproject.toml`). This ensures consistent discovery on PyPI. +Verifies that the keyword `azure sdk` is present in the targeted package's `keywords` field (in `pyproject.toml`). This ensures consistent discovery on PyPI. To run locally: @@ -458,7 +458,7 @@ azpysdk sdist . -For each Azure SDK dependency declared in `setup.py` (dev-only requirements are excluded), this check resolves the **oldest** published version available on PyPI that satisfies the requirement range, installs it in place of the in-repo dev version, and then runs the full test suite. This confirms that the package works across the full declared version range — not just against the latest release. +For each Azure SDK dependency declared in `pyproject.toml` (dev-only requirements are excluded), this check resolves the **oldest** published version available on PyPI that satisfies the requirement range, installs it in place of the in-repo dev version, and then runs the full test suite. This confirms that the package works across the full declared version range — not just against the latest release. To run locally: @@ -474,7 +474,7 @@ The following checks are the additional entries in `FULL_BUILD_SET` beyond the P -The `import_all` check ensures all modules in a target package can be successfully imported. Installing and importing verifies that all package requirements are properly set in `setup.py`/`pyproject.toml` and that the `__all__` for the package is properly defined. This test installs the package and its required packages, then executes `from import *`. For example from `azure-core`, the following would be invoked: `from azure.core import *`. +The `import_all` check ensures all modules in a target package can be successfully imported. Installing and importing verifies that all package requirements are properly set in `pyproject.toml` and that the `__all__` for the package is properly defined. This test installs the package and its required packages, then executes `from import *`. For example from `azure-core`, the following would be invoked: `from azure.core import *`. To run locally: @@ -498,7 +498,7 @@ azpysdk whl_no_aio . -For each Azure SDK dependency declared in `setup.py`/`pyproject.toml` (dev-only requirements are excluded), this check resolves the **latest** published version available on PyPI that satisfies the requirement range, installs it in place of the in-repo dev version, and then runs the full test suite. This confirms that the package works with the newest available version of each of its dependencies. +For each Azure SDK dependency declared in `pyproject.toml` (dev-only requirements are excluded), this check resolves the **latest** published version available on PyPI that satisfies the requirement range, installs it in place of the in-repo dev version, and then runs the full test suite. This confirms that the package works with the newest available version of each of its dependencies. To run locally: diff --git a/doc/tool_usage_guide.md b/doc/tool_usage_guide.md index e36b59f6b7f5..762c25d9fa68 100644 --- a/doc/tool_usage_guide.md +++ b/doc/tool_usage_guide.md @@ -24,7 +24,7 @@ The following checks are available via the `azpysdk` entrypoint. |`apistub`| Generates `api.md`, API metadata, or APIView token files for the package. | `azpysdk apistub .` | |`bandit`| Runs `bandit` checks, which detect common security issues. | `azpysdk bandit .` | |`verifywhl`| Verifies that the root directory in whl is azure, and verifies manifest so that all directories in source are included in sdist. | `azpysdk verifywhl .` | -|`verifysdist`| Verify directories included in sdist and contents in manifest file. Also ensures that py.typed configuration is correct within the setup.py. | `azpysdk verifysdist .` | +|`verifysdist`| Verify directories included in sdist and contents in manifest file. Also ensures that py.typed configuration is correct within `pyproject.toml`. | `azpysdk verifysdist .` | |`verify_keywords`| Verify that the keyword 'azure sdk' is present in the targeted package's keywords. | `azpysdk verify_keywords .` | |`import_all`| Installs the package w/ default dependencies, then attempts to `import *` from the base namespace. Ensures that all imports will resolve after a base install and import. | `azpysdk import_all .` | |`generate`| Regenerates the code. | `azpysdk generate .` |