[docs] Fix documentation inconsistencies in doc/ folder#6
Draft
github-actions[bot] wants to merge 1 commit intomainfrom
Draft
[docs] Fix documentation inconsistencies in doc/ folder#6github-actions[bot] wants to merge 1 commit intomainfrom
github-actions[bot] wants to merge 1 commit intomainfrom
Conversation
- static_type_checking.md: Update pinned mypy version from 1.9.0 to 1.18.1
and pyright version from 1.1.287 to 1.1.405 to match azpysdk/mypy.py and
azpysdk/pyright.py source of truth.
- request_builders.md / send_request.md: Fix two bugs in async code examples:
1. 'except HttpResponseError:' was missing 'as e', causing NameError when
the handler calls print(str(e)).
2. 'await response.load_body()' is a backcompat-only internal method; replace
with the public API 'await response.read()'.
- packaging.md: Update the setup.py example to reflect current conventions:
- Read from '_version.py' (not 'version.py') — matches actual packages.
- Use README.md with text/markdown content type instead of README.rst/HISTORY.rst.
- Remove deprecated msrest, msrestazure, azure-common install_requires.
- Update minimum Python version from 3.8 to 3.9 throughout; add Python 3.13
classifier.
- tests.md / dev_setup.md: Update minimum Python version references from 3.8
to 3.9 (matching azure-core, azure-storage-blob, and CI configuration); fix
old Microsoft Store URL format for Python 3.9/3.10 to apps.microsoft.com
format; remove Python 3.8 entry since it is no longer supported.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR fixes several inconsistencies found between the
doc/documentation and the actual source code/repository structure.1.
doc/dev/static_type_checking.md— Wrong pinned tool versionsIssue: The guide stated mypy was pinned to
1.9.0and pyright to1.1.287, but the actual source of truth (eng/tools/azure-sdk-tools/azpysdk/mypy.pyandpyright.py) hasMYPY_VERSION = "1.18.1"andPYRIGHT_VERSION = "1.1.405".Fix: Updated all version references (linked text,
pip installcommands) to match the actual pinned versions in the tooling:1.9.0→1.18.11.1.287→1.1.405(three occurrences: Run pyright section, Run verifytypes section)2.
doc/request_builders.mdanddoc/send_request.md— Broken async code examplesIssue 1 —
NameErrorin exception handler: The sync and async example code usedexcept HttpResponseError:(withoutas e) but then calledprint(str(e)). This would raiseNameError: name 'e' is not definedat runtime.Issue 2 — Deprecated internal API: The async examples called
await response.load_body(). This method is marked as a backcompat-only internal alias inazure/core/rest/_aiohttp.py(backcompat_attrs = ["load_body"]). The correct public API isawait response.read().Fix:
except HttpResponseError:→except HttpResponseError as e:(in both files)await response.load_body()→await response.read()(in both files)3.
doc/dev/packaging.md— Outdatedsetup.pyexampleIssue: The example
setup.pyhad several divergences from actual current packages:'version.py'but all actual packages (e.g.,azure-storage-blob,azure-keyvault-secrets) use'_version.py'README.rstandHISTORY.rst(concatenated aslong_description) — modern packages useREADME.mdmsrest,msrestazure, andazure-commonasinstall_requires— these are deprecated dependencies no longer used in modern SDK packagespython_requires=">=3.8"and classifierPython :: 3.8— the actual minimum enforced across core packages (azure-core, azure-storage-blob, etc.) and CI is 3.9Fix: Updated the example
setup.pyto match current conventions:'version.py'→'_version.py'README.rst/HISTORY.rst→README.mdwithlong_description_content_type='text/markdown'msrest/msrestazure/azure-common; replaced withazure-core>=1.30.0as a representative modern dependencypython_requiresand classifiers from 3.8→3.9, added Python 3.134.
doc/dev/tests.mdanddoc/dev/dev_setup.md— Stale Python 3.8 referencesIssue: Both files referenced Python 3.8 as the minimum supported version, and
tests.mdincluded Windows Store links in the old(www.microsoft.com/redacted) format (not working for 3.8/3.9/3.10). Theeng_sys_checks.mdand CI pipelines use Python 3.9 as the minimum, and core packages likeazure-coreandazure-storage-blobdeclarepython_requires=">=3.9"`.Fix:
apps.microsoft.com/detail/...format (matching the 3.11/3.12 links already present)py -3.8comment indev_setup.md→py -3.9Warning
The following domains were blocked by the firewall during workflow execution:
docs.microsoft.comreleaseassets.githubusercontent.comTo allow these domains, add them to the
network.allowedlist in your workflow frontmatter:See Network Configuration for more information.