Azure · iscai-msft · Dec 18, 2020 · Dec 15, 2020 · Dec 18, 2020 · Dec 18, 2020
diff --git a/.gitignore b/.gitignore
@@ -112,7 +112,7 @@ venv.bak/
 node_modules/
 
 # autorest default folder
-generated
+/generated
 **/code-model-v4-no-tags.yaml
 
 # VS code

diff --git a/docs/client/initializing.md b/docs/client/initializing.md
@@ -15,7 +15,7 @@ Putting this together, we import our client like so:
 from azure.pets import PetsClient
 ```
 
-### Dependencies of Your Client
+## Minimum Dependencies of Your Client
 
 The only scenario the generated code can force dependencies is if you generate with a `setup.py` file using the `--basic-setup-py` flag.
 The following are core libraries your generated code depend on, and the minimum version we highly recommend:
@@ -77,7 +77,6 @@ from azure.pets import PetsClient
 client = PetsClient(credential=DefaultAzureCredential(), api_version="v1")
 ```
 
-
 <!-- LINKS -->
 [multiapi_generation]: ../generate/multiapi.md
 [azure_core_library]: https://pypi.org/project/azure-core/

diff --git a/docs/client/models.md b/docs/client/models.md
@@ -0,0 +1,29 @@
+# <img align="center" src="../images/logo.png">  Accessing Models and Enums
+
+## General
+
+Models and enums are generated in the `models` namespace. So, say you are using package `azure.pets`. To access model `Dog`, you would use the following code
+snippet
+
+```
+from azure.pets.models import Dog
+```
+
+Enums are also listed in the `models` namespace, so say you have enum class `DogTypes`. To access the `DALMATION` enum, your code would look like
+
+```
+from azure.pets.models import DogTypes
+
+my_dog_type = DogTypes.DALMATION
+```
+
+## Multi API
+
+There is also a `models` module in a multi API client. There, you can access the latest version of each models.
+
+If you want to access a specific API version's models, you can do so through the [`models()`][models_ex] class method we expose on the multi API client.
+It accepts optional parameter `api_version`. If specified, it will retrieve the models from that API version. Otherwise, retrieves models from the
+default API version the code was generated with.
+
+<!-- LINKS -->
+[models_ex]: https://github.com/Azure/autorest.python/blob/autorestv3/test/multiapi/Expected/AcceptanceTests/Multiapi/multiapi/_multiapi_service_client.py#L91
diff --git a/docs/client/operations.md b/docs/client/operations.md
@@ -149,7 +149,7 @@ a pager that pages through the final lists of data.
 [initializing]: ./initializing.md
 [lro_poller]:  https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.polling.lropoller?view=azure-python
 [custom_poller]: ../generate/directives.md#generate-with-a-custom-poller
-[example_swagger]: ../generate/examples/pollingPaging.json
+[example_swagger]: ../samples/specification/directives/pollingPaging.json
 [poller_guidelines]: https://azure.github.io/azure-sdk/python_design.html#service-operations
 [async_lro_poller]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.polling.asynclropoller?view=azure-python
 [item_paged]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.paging.itempaged?view=azure-python

diff --git a/docs/client/readme.md b/docs/client/readme.md
@@ -1,16 +1,17 @@
-# <img align="center" src="./images/logo.png">  Using the Python Client
+# <img align="center" src="../images/logo.png">  Using the Python Client
 
 After [generating][generate] your client, this section tells you how to actually use your generated client.
 
 * [Initializing Your Python Client][initializing]
 * [Calling Operations with Your Python Client][operations]
+* [Accessing Models and Enums][models]
 * [Error Handling][error_handling]
 * [Tracing][tracing]
-* Dependencies Your Generated Code Has
 
 <!-- LINKS -->
 [generate]: https://github.com/Azure/autorest/tree/master/docs/generate/readme.md
 [initializing]: ./initializing.md
 [operations]: ./operations.md
+[models]: ./models.md
 [error_handling]: ./error_handling.md
 [tracing]: ./tracing.md
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,19 @@
+# <img align="center" src="./images/logo.png">  FAQ
+
+1. What are the minimum dependencies?
+
+    The minimum dependencies are listed [here][min_dependencies]. This list will be continuously updated.
+
+2. What version of AutoRest Python should I use?
+
+    We highly recommend you use the latest AutoRest Python version published to [npm][autorest_npm]. The latest version
+    is the default if you use flag `--python`, though you may need to run an `autorest --reset` if it seems
+    the latest version is not being grabbed.
+
+    If you *really* want to use an older version of AutoRest Python,
+    you can specify the version with the flag `--use`, i.e. `--use=@autorest/[email protected]`.
+
+
+<!-- LINKS -->
+[min_dependencies]: ./client/initializing.md#minimum-dependencies-of-your-client
+[autorest_npm]: https://www.npmjs.com/package/@autorest/python
diff --git a/docs/generate/directives.md b/docs/generate/directives.md
@@ -1,6 +1,6 @@
 # <img align="center" src="../images/logo.png">  Python-Specific Directives
 
-If you want to see how to generally use a directive to change AutoRest behavior, check out the [main docs](https://github.com/Azure/autorest/tree/master/docs/generate/directives.md). This section will go into the Python-specific directives.
+If you want to see how to generally use a directive to change AutoRest behavior, check out the [main docs][main_docs]. This section will go into the Python-specific directives.
 
 These directives all start out with this general skeleton of a directive:
 
@@ -145,14 +145,14 @@ Here is the before and after of the generated code.
 # <img align="center" src="../images/after_paging_method_directive.png">
 
 
-We have put all of these Python-specific directives in a [config file][directive_readme] for you to refer to.
+For a full multiapi config example, see our [sample][sample_directives]
 
 <!-- LINKS -->
-
+[main_docs]: https://github.com/Azure/autorest/tree/master/docs/generate/directives.md
 [lro_poller_docs]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.polling.lropoller?view=azure-python
 [azure_core_pypi]: https://pypi.org/project/azure-core/
 [async_lro_poller_docs]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.polling.asynclropoller?view=azure-python
-[polling_paging_swagger]: ./examples/pollingPaging.json
+[polling_paging_swagger]: ../samples/specification/directives/pollingPaging.json
 
 [lro_base_polling_docs]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.polling.base_polling.lrobasepolling?view=azure-python
 [async_lro_base_polling_docs]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.polling.async_base_polling.asynclrobasepolling?view=azure-python
@@ -163,3 +163,4 @@ We have put all of these Python-specific directives in a [config file][directive
 
 [item_paged_docs]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.paging.itempaged?view=azure-python
 [async_item_paged_docs]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.async_paging.asyncitempaged?view=azure-python
+[sample_directives]: ../samples/specification/directives/readme.md
diff --git a/docs/generate/examples/multiapi/readme.md b/docs/generate/examples/multiapi/readme.md
diff --git a/docs/generate/multiapi.md b/docs/generate/multiapi.md
@@ -1,8 +1,8 @@
-# <img align="center" src="./images/logo.png">  Generating a Multi API Python Client with AutoRest
+# <img align="center" src="../images/logo.png">  Generating a Multi API Python Client with AutoRest
 
 If you want to generate one client that handles multiple API versions (a common use-case for this is supporting multiple Azure clouds, since a service's API versions can differ between them), this is the section for you. Python is the only language that supports this, hence why these docs are in the Python-specific section.
 
-Before getting into the multiapi specific sections that need to be added to your readme, you need to make sure you have a tag set up for every single API version you want to generate. See the ["Adding Tags When Generating"](https://github.com/Azure/autorest/tree/master/docs/generate/readme.md#adding-tags-when-generating) docs to find out how to set this up. Following the [main example]((https://github.com/Azure/autorest/tree/master/docs/generate/examples/tags/readme.md), this example will suppose you're generating 2 different API versions: `v1` and `v2`.
+Before getting into the multiapi specific sections that need to be added to your readme, you need to make sure you have a tag set up for every single API version you want to generate. See the ["Adding Tags When Generating"][tags] docs to find out how to set this up. In this example we will s generate 3 different API versions: `v1`, `v2`, and `v3`.
 
 The flag you use on the command line to specify you want multiapi code generation is `--multiapi`. Thus, we need to add a `multiapi` specific section to our readme.
 Let's add it underneath `General Settings` to keep it to the top of our readme
@@ -25,6 +25,8 @@ These settings apply only when `--multiapi` is specified on the command line.
 batch:
     - tag: v1
     - tag: v2
+    - tag: v3
+    - multiapiscript: true
 ```
 ````
 
@@ -35,10 +37,10 @@ of your config. Users should never specify `multiapiscript` on the command line,
 file to let AutoRest know it has to run its multiapi script.
 
 ````
-```yaml $(multiapiscript)
-output-folder: $(python-sdks-folder)/pets/azure-pets/azure/pets
-perform-load: false
+``` yaml $(multiapiscript)
+output-folder: $(python-sdks-folder)/generated/azure/multiapi/sample
 clear-output-folder: false
+perform-load: false
 ```
 ````
 
@@ -62,8 +64,13 @@ These settings apply only when `--multiapi` is specified on the command line.
 batch:
     - tag: v1
     - tag: v2
+    - tag: v3
     - multiapiscript: true
 ```
 ````
 
-And that's it! We've included the final config file in our [examples folder](./examples/multiapi/readme.md), please feel free to refer to this.
+And that's it! We've included the final config file in our [samples folder][samples], please feel free to refer to this.
+
+<!-- LINKS -->
+[tags]: https://github.com/Azure/autorest/tree/master/docs/generate/readme.md#adding-tags-when-generating
+[samples]: ../samples/specification/multiapi/readme.md
diff --git a/docs/generate/readme.md b/docs/generate/readme.md
@@ -1,4 +1,4 @@
-# <img align="center" src="./images/logo.png">  Generating Python Clients with AutoRest
+# <img align="center" src="../images/logo.png">  Generating Python Clients with AutoRest
 
 Most of the information you'll need to generate a Python client can be found in the general docs [here][general]. In these docs, we go over a couple Python-specific scenarios.
 

diff --git a/docs/migrate/readme.md b/docs/migrate/readme.md
@@ -1,10 +1,8 @@
 # <img align="center" src="../images/logo.png">  Migrating to Latest AutoRest
 
-## Generating Changes
+See the [main docs][main_docs] for changes in versioning and flags, this section focuses on how the generated code differs.
 
-## Generated Code
-
-### Breaking Changes
+## Breaking Changes
 
 * The credential system has been completely revamped:
     - Previously we had used `azure.common.credentials` or `msrestazure.azure_active_directory` instances, which
@@ -21,7 +19,7 @@ tell AutoRest during generation time to keep the current version file in the dir
     - `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
+## 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.
@@ -30,11 +28,12 @@ code for this, and you can see our [tracing docs][tracing_docs] for more informa
 
 
 <!-- LINKS -->
+[main_docs]: https://github.com/Azure/autorest/blob/master/docs/migrate/readme.md
 [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
+[flag_index]: https://github.com/Azure/autorest/blob/master/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

diff --git a/docs/readme.md b/docs/readme.md
@@ -1,6 +1,6 @@
 # AutoRest Python Documentation
 
-These documents are Python-specific, see [our main docs](https://github.com/Azure/autorest/tree/master/docs) for more general information
+These documents are Python-specific, see [our main docs][main_docs] for more general information
 
 
 1. Generating Python Clients with AutoRest
@@ -13,19 +13,25 @@ These documents are Python-specific, see [our main docs](https://github.com/Azur
     - 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)? Main docs [here][main_dev]
+    - How do I generate or contribute to AutoRest in [dev mode][python_dev] Main docs [here][main_dev]
 
 5. Samples
-    - [Sample](./samples/readme.md) readmes and generated code for common scenarios.
+    - [Sample][sample] readmes and generated code for common scenarios.
 
-6. [FAQ](./faq.md)
+6. [FAQ][faq]
+
+7. [Troubleshooting][troubleshooting]
 
 <!-- LINKS -->
+[main_docs]: https://github.com/Azure/autorest/tree/master/docs
 [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
+[main_dev]: https://github.com/Azure/autorest/tree/master/docs/dev/readme.md
+[sample]: ./samples/readme.md
+[faq]: ./faq.md
+[trobleshooting]: ./troubleshooting.md
diff --git a/docs/samples/readme.md b/docs/samples/readme.md
@@ -0,0 +1,20 @@
+# <img align="center" src="../images/logo.png"> Sample Python Generation
+
+Here are our samples for common generation scenarios
+
+
+| Scenario | README | Generated Code
+|------------------|-------------|-------------
+|Generating [management plane][mgmt] | [readme.md][mgmt_readme] | [generated][mgmt_generated]
+|Generating multi API code | [readme.md][multiapi_readme] | [generated][multiapi_generated]
+|Generating with [`AzureKeyCredential`][azure_key_credential] | [readme.md][azure_key_credential_readme] | [generated][azure_key_credential_generated]
+
+<!-- LINKS -->
+[mgmt]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/control-plane-and-data-plane#control-plane
+[mgmt_readme]: ./specification/management/readme.md
+[mgmt_generated]: ./specification/management/generated
+[multiapi_readme]: ./specification/multiapi/readme.md
+[multiapi_generated]: ./specification/multiapi/generated
+[azure_key_credential]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.credentials.azurekeycredential?view=azure-python
+[azure_key_credential_readme]: ./specification/azure_key_credential/readme.md
+[azure_key_credential_generated]: ./specification/azure_key_credential/generated
diff --git a/docs/samples/specification/azure_key_credential/generated/azure/__init__.py b/docs/samples/specification/azure_key_credential/generated/azure/__init__.py
@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: ignore
diff --git a/docs/samples/specification/azure_key_credential/generated/azure/key/__init__.py b/docs/samples/specification/azure_key_credential/generated/azure/key/__init__.py
@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: ignore
diff --git a/docs/samples/specification/azure_key_credential/generated/azure/key/credential/__init__.py b/docs/samples/specification/azure_key_credential/generated/azure/key/credential/__init__.py
@@ -0,0 +1 @@
+__path__ = __import__('pkgutil').extend_path(__path__, __name__)  # type: ignore
diff --git a/...ples/specification/azure_key_credential/generated/azure/key/credential/sample/__init__.py b/...ples/specification/azure_key_credential/generated/azure/key/credential/sample/__init__.py
@@ -0,0 +1,19 @@
+# coding=utf-8
+# --------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for license information.
+# Code generated by Microsoft (R) AutoRest Code Generator.
+# Changes may cause incorrect behavior and will be lost if the code is regenerated.
+# --------------------------------------------------------------------------
+
+from ._auto_rest_head_test_service import AutoRestHeadTestService
+from ._version import VERSION
+
+__version__ = VERSION
+__all__ = ['AutoRestHeadTestService']
+
+try:
+    from ._patch import patch_sdk  # type: ignore
+    patch_sdk()
+except ImportError:
+    pass
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		__path__ = __import__('pkgutil').extend_path(__path__, __name__) # type: ignore