diff --git a/docs/python/design.md b/docs/python/design.md index ddd3056b237c..c8af3d65a938 100644 --- a/docs/python/design.md +++ b/docs/python/design.md @@ -617,8 +617,6 @@ Despite the availability of the `asyncio` library and the `async`/`await` keywor {% include requirement/MUST id="python-client-sync-async" %} provide both sync and async versions of your APIs -{% include requirement/MUST id="python-client-async-keywords" %} use the `async`/`await` keywords. Do not use the [yield from coroutine or asyncio.coroutine](https://docs.python.org/3.4/library/asyncio-task.html) syntax. - {% include requirement/MUST id="python-client-separate-sync-async" %} provide two separate client classes for synchronous and asynchronous operations. Do not combine async and sync operations in the same class. ```python @@ -831,7 +829,7 @@ Code samples are small applications that demonstrate a certain feature that is r {% include requirement/MUST id="python-samples-runnable" %} ensure that each sample file is runnable. -{% include requirement/MUST id="python-samples-coding-style" %} avoid using features newer than the Python 3 baseline support. The current supported Python version is 3.10. +{% include requirement/MUST id="python-samples-coding-style" %} avoid using features newer than the Python baseline support. The current supported Python version is 3.10. {% include requirement/MUST id="python-samples-grafting" %} ensure that code samples can be easily grafted from the documentation into a users own application. For example, don't rely on variable declarations in other samples. diff --git a/docs/python/implementation.md b/docs/python/implementation.md index cf05ec601df5..3cb51c8ff655 100644 --- a/docs/python/implementation.md +++ b/docs/python/implementation.md @@ -185,11 +185,11 @@ Client library usage telemetry is used by service teams (not consumers) to monit - ``: optional application-specific string. May contain a slash, but must not contain a space. The string is supplied by the user of the client library, e.g. "AzCopy/10.0.4-Preview" - ``: client library (distribution) package name as it appears to the developer, replacing slashes with dashes and removing the Azure indicator. For example, "azure-keyvault-secrets" would specify "azsdk-python-keyvault-secrets". - ``: the version of the package. Note: this is not the version of the service -- ``: information about the currently executing language runtime and OS, e.g. "Python/3.8.4 (Windows-10-10.0.19041-SP0)" +- ``: information about the currently executing language runtime and OS, e.g. "Python/3.10.4 (Windows-10-10.0.19041-SP0)" For example, if we re-wrote `AzCopy` in Python using the Azure Blob Storage client library, we may end up with the following user-agent strings: -- (Python) `AzCopy/10.0.4-Preview azsdk-python-storage/4.0.0 Python/3.7.3 (Ubuntu; Linux x86_64; rv:34.0)` +- (Python) `AzCopy/10.0.4-Preview azsdk-python-storage/4.0.0 Python/3.10.4 (Ubuntu; Linux x86_64; rv:34.0)` The `azure.core.pipeline.policies.UserAgentPolicy` will provide this functionality if added to the HttpPipeline. @@ -547,7 +547,7 @@ azure.exampleservice.some_internal_module {% include requirement/MUST id="python-codestyle-use-builtin-generics" %} use built-in generic types (`list`, `dict`, `tuple`, `set`) in type annotations instead of their `typing` module counterparts (`typing.List`, `typing.Dict`, `typing.Tuple`, `typing.Set`). This is supported as of Python 3.9 ([PEP 585](https://www.python.org/dev/peps/pep-0585/)). ```python -# Yes (Python 3.9+): +# Yes (Python 3.10+): def get_things() -> list[str]: ... def get_mapping() -> dict[str, int]: ... @@ -557,19 +557,15 @@ def get_things() -> List[str]: ... def get_mapping() -> Dict[str, int]: ... ``` -{% include requirement/MUST id="python-codestyle-union-optional" %} use `typing.Union` and `typing.Optional` for union types. - - +{% include requirement/MUST id="python-codestyle-union-optional" %} use the `X | Y` union syntax ([PEP 604](https://www.python.org/dev/peps/pep-0604/)) instead of `typing.Union[X, Y]`, and `X | None` instead of `typing.Optional[X]`. This is supported as of Python 3.10. ```python -# Yes (Python 3.9): +# Yes (Python 3.10+): +def foo(x: int | str) -> str | None: ... + +# No: from typing import Optional, Union def foo(x: Union[int, str]) -> Optional[str]: ... - -# No (requires Python 3.10+): -def foo(x: int | str) -> str | None: ... ``` ### Threading