diff --git a/docs/client/error_handling.md b/docs/client/error_handling.md index 964e5588dc9..83615b121a2 100644 --- a/docs/client/error_handling.md +++ b/docs/client/error_handling.md @@ -52,7 +52,6 @@ Network trace logging can also be enabled for any single operation: dog = client.get_dog(logging_enable=True) ``` - [azure_core_exceptions]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/core/azure-core#azure-core-library-exceptions [azure_error]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.exceptions.azureerror?view=azure-python diff --git a/docs/migrate/readme.md b/docs/migrate/readme.md new file mode 100644 index 00000000000..d7cb1ffcb1c --- /dev/null +++ b/docs/migrate/readme.md @@ -0,0 +1,44 @@ +# Migrating to Latest AutoRest + +## Generating Changes + +## Generated Code + +### Breaking Changes + +* The credential system has been completely revamped: + - Previously we had used `azure.common.credentials` or `msrestazure.azure_active_directory` instances, which + are no longer supported. We now use credentials from [`azure_identity`][azure_identity_credentials] and the [`AzureKeyCredential`][azure_key_credential] from + [`azure-core`][azure_core_library]. + - The `credentials` parameter to the service client has been renamed to `credential` +* The `config` attribute is no longer exposed on the client, and custom configurations should be passed as a kwarg. For example, we know have `Client(credential, subscription_id, enable_logging=True`). +For a complete set of supported inputs to your client, see our list of [acceptable initialization parameters in azure-core][azure_core_init_parameters]. +* You can't import a `version` module anymore, use `__version__` instead. Additionally, we only generate a version file if you specify a package version on the command line (`--package-version`), or you +tell AutoRest during generation time to keep the current version file in the directory (`--keep-version-file`). See our [flag index][flag_index] for more information on these 2 flags. +* Long running operations that used to return a `msrest.polling.LROPoller` now return a [`azure.core.polling.LROPoller`][lro_poller_docs] by default. These operations are also now prefixed with `begin_`. +* The exception tree has been simplified, and now most exceptions are an [`azure.core.exceptions.HttpResponseError`][http_response_error]. `CloudError` has been removed. +* Most of the operation kwargs have changed. The most noticeable are: + - `raw` has been removed. We now use `cls`, which is a callback that gives access to the internal HTTP response for advanced users. + - For a complete set of supported options, see the [acceptable parameters to operations in azure-core][azure_core_operation_parameters]. + +### New Features + +* Type annotations using the standard `typing` library. SDKs are [`mypy`][mypy] ready! +* This client has stable and official support for async. Look in the `aio` namespace of your generated package to find the async client. +* The client now natively supports tracing libraries such as [`OpenCensus`][open_census] and [`OpenTelemetry`][open_telemetry]. Use the flag `--trace` to generate +code for this, and you can see our [tracing docs][tracing_docs] for more information. + + + +[azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity#credentials +[azure_key_credential]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.credentials.azurekeycredential?view=azure-python +[azure_core_library]: https://pypi.org/project/azure-core/ +[azure_core_init_parameters]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md#available-policies +[flag_index]: https://github.com/Azure/autorest/blob/new_docs/docs/generate/flags.md +[lro_poller_docs]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.polling.lropoller?view=azure-python +[http_response_error]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.exceptions.httpresponseerror?view=azure-python +[azure_core_operation_parameters]: https://github.com/Azure/azure-sdk-for-python/blob/master/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md#available-policies +[mypy]: https://mypy.readthedocs.io/en/stable/introduction.html +[open_census]: https://opencensus.io/ +[open_telemetry]: https://opentelemetry.io/ +[tracing_docs]: ../client/tracing.md \ No newline at end of file diff --git a/docs/readme.md b/docs/readme.md index 5b7c2206478..608894a9a7a 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -4,18 +4,28 @@ These documents are Python-specific, see [our main docs](https://github.com/Azur 1. Generating Python Clients with AutoRest - - How do I generate code? Main documents are [here](https://github.com/Azure/autorest/tree/master/docs/generate/readme.md), while here are the [python-specific docs](.generate/readme.md) + - How do I generate code? Main documents are [here][main_generate], while here are the [python-specific docs][python_generate] 2. Using Your Generated Python Client - - How do I [use my Python client](./client/readme.md) now that I've generated it? Main docs are [here](https://github.com/Azure/autorest/tree/master/docs/generate/client.md) + - How do I [use my Python client][python_client] now that I've generated it? Main docs are [here][main_client] 3. Migrating from AutoRest 2.0 to 3.0 - - I have old generated code using the previous version of AutoRest. How do I [upgrade](./migrate/readme.md) my generation and use my new code? + - I have old generated code using the previous version of AutoRest. How do I upgrade my code? Main docs [here][main_migrate], Python-specific docs [here][python_migrate] 4. Developing with AutoRest - - How do I generate or contribute to AutoRest in [dev mode](./developer/readme.md)? + - How do I generate or contribute to AutoRest in [dev mode](./developer/readme.md)? Main docs [here][main_dev] 5. Samples - [Sample](./samples/readme.md) readmes and generated code for common scenarios. 6. [FAQ](./faq.md) + + +[main_generate]: https://github.com/Azure/autorest/tree/master/docs/generate/readme.md +[python_generate]: ./generate/readme.md +[python_client]: ./client/readme.md +[main_client]: https://github.com/Azure/autorest/tree/master/docs/generate/client.md +[main_migrate]: https://github.com/Azure/autorest/tree/master/docs/migrate/readme.md +[python_migrate]: ./migrate/readme.md +[python_dev]: ./developer/readme.md +[main_dev]: https://github.com/Azure/autorest/tree/master/docs/dev/readme.md \ No newline at end of file