Migrate

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)
 ```
 
-
 <!-- LINKS -->
 [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

docs/migrate/readme.md

@@ -0,0 +1,44 @@
+# <img align="center" src="../images/logo.png">  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.
+
+
+<!-- LINKS -->
+[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

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)
+
+<!-- LINKS -->
+[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