changing docstrings and return types for lro and paging

Azure · Apr 1, 2020 · 1836f02 · 1836f02
1 parent 79229a9
commit 1836f02
Show file tree

Hide file tree

Showing 20 changed files with 408 additions and 371 deletions.
diff --git a/autorest/codegen/models/paging_operation.py b/autorest/codegen/models/paging_operation.py
@@ -100,8 +100,10 @@ def imports(self, code_model, async_mode: bool) -> FileImport:
         if async_mode:
             file_import.add_from_import("azure.core.async_paging", "AsyncItemPaged", ImportType.AZURECORE)
             file_import.add_from_import("azure.core.async_paging", "AsyncList", ImportType.AZURECORE)
+            file_import.add_from_import("typing", "AsyncIterable", ImportType.STDLIB)
         else:
             file_import.add_from_import("azure.core.paging", "ItemPaged", ImportType.AZURECORE)
+            file_import.add_from_import("typing", "Iterable", ImportType.STDLIB)
 
         if code_model.options["tracing"]:
             file_import.add_from_import(

diff --git a/autorest/codegen/templates/lro_operation.py.jinja2 b/autorest/codegen/templates/lro_operation.py.jinja2
@@ -5,8 +5,8 @@
 {% set poller = "async_poller" if async_mode else "LROPoller" %}
 {% set operation_name = operation.python_name if async_mode else "begin_"+operation.python_name %}
 {% macro return_docstring() %}
-:return: An instance of LROPoller that returns {{ operation.responses[0].schema.name if operation.responses[0].has_body else "None"}}
-    :rtype: ~azure.core.polling.LROPoller[{{ operation.responses[0].schema.docstring_type if operation.responses[0].has_body else "None" }}]
+:return: {{ "" if async_mode else "An instance of LROPoller that returns " }}{{ operation.responses[0].schema.name if operation.responses[0].has_body else "None"}}
+:rtype: {{"" if async_mode else "~azure.core.polling.LROPoller["}}{{ operation.responses[0].schema.docstring_type if operation.responses[0].has_body else "None" }}{{ "" if async_mode else "]" }}
 {% endmacro %}
 {% macro param_documentation_string(parameter) %}:param {{ parameter.serialized_name }}: {{ parameter.description }}{% endmacro %}
 {% macro response_headers(response) %}
@@ -21,9 +21,11 @@ response_headers = {
 {% if code_model.options['tracing'] %}
 {{ trace_decorator }}
 {% endif %}
-{{ op_tools.method_signature(operation, operation_name, async_mode=async_mode, coroutine=async_mode) }}
+{% set return_type_wrapper = "" if async_mode else "LROPoller" %}
+{{ op_tools.method_signature(operation, operation_name, async_mode=async_mode, coroutine=async_mode, return_type_wrapper=return_type_wrapper) }}
 {%- if not async_mode %}
-    {{ op_tools.sync_return_type_annotation(operation) }}
+{# overriding sync_return_type_annotation because we know if it's sync, it's return type is just LROPoller #}
+    # type: (...) -> LROPoller
 {% endif %}
     """{{operation.description }}
     {% if operation.summary %}
@@ -46,7 +48,7 @@ response_headers = {
     :keyword polling: True for ARMPolling, False for no polling, or a
      polling object for personal polling strategy
     :paramtype polling: bool or ~azure.core.polling.{{ "Async" if async_mode else "" }}PollingMethod
-    {{ return_docstring() }}
+    {{ return_docstring()|indent }}
     :raises ~azure.core.exceptions.HttpResponseError:
     """
     polling = kwargs.pop('polling', {{ "True" if code_model.options['azure_arm'] else "False" }})  # type: Union[bool, {{ "Async" if async_mode else "" }}PollingMethod]

diff --git a/autorest/codegen/templates/metadata.json.jinja2 b/autorest/codegen/templates/metadata.json.jinja2
@@ -44,7 +44,8 @@
         {{ operation.name | tojson }} : {
             "doc": {{ op_tools.operation_docstring(operation) | tojson }},
             {% set sync_operation_name = "begin_" + operation.name if is_lro(operation) else operation.name %}
-            "signature": {{ op_tools.method_signature(operation, sync_operation_name, False, False) | tojson }},
+            {% set return_type_wrapper = "LROPoller" if is_lro(operation) else ("ItemPaged" if is_paging(operation) else "") %}
+            "signature": {{ op_tools.method_signature(operation, sync_operation_name, False, False, return_type_wrapper) | tojson }},
             "call": {{ operation.parameters.method | map(attribute="serialized_name") | join(', ') | tojson }}
         }{{ "," if not loop.last else "" }}
         {% endfor %}

diff --git a/autorest/codegen/templates/operation.py.jinja2 b/autorest/codegen/templates/operation.py.jinja2
@@ -6,14 +6,14 @@
 {%- if code_model.options['tracing'] and operation.want_tracing -%}
 {{ trace_decorator }}
 {% endif %}
-{{ op_tools.method_signature(operation, operation.python_name, async_mode=async_mode, coroutine=async_mode) }}
+{{ op_tools.method_signature(operation, operation.python_name, async_mode=async_mode, coroutine=async_mode, return_type_wrapper="") }}
 {%- if not async_mode %}
-    {{ op_tools.sync_return_type_annotation(operation) }}
+    {{ op_tools.sync_return_type_annotation(operation, "") }}
 {% endif %}
 {% if operation.want_description_docstring %}
 {{ op_tools.operation_docstring(operation)|indent }}
 {% endif %}
-    cls = kwargs.pop('cls', None)  # type: ClsType[{{ op_tools.return_type_annotation(operation) }}]
+    cls = kwargs.pop('cls', None)  # type: {{ op_tools.return_type_annotation(operation, "ClsType") }}
 {% if operation.deprecated %}
     warnings.warn('Method {{operation.name}} is deprecated', DeprecationWarning)
 {% endif %}

diff --git a/autorest/codegen/templates/operation_tools.jinja2 b/autorest/codegen/templates/operation_tools.jinja2
@@ -34,28 +34,28 @@
 {{ return_docstring(operation) }}
 :raises: ~azure.core.exceptions.HttpResponseError
 """{% endmacro %}
-{% macro return_type_annotation(operation) %}
-{{("Union[" if operation.responses | selectattr('has_body') | map(attribute='schema') | map(attribute='operation_type_annotation') | unique | list  | length > 1 else "") ~
+{% macro return_type_annotation(operation, return_type_wrapper) %}
+{{ ((return_type_wrapper + "[") if return_type_wrapper else "") ~ ("Union[" if operation.responses | selectattr('has_body') | map(attribute='schema') | map(attribute='operation_type_annotation') | unique | list  | length > 1 else "") ~
 (operation.responses | selectattr('has_body') | map(attribute='schema') | map(attribute='operation_type_annotation') | unique | join(', ')) ~
-("]" if operation.responses | selectattr('has_body') | map(attribute='schema') | map(attribute='operation_type_annotation')| unique | list | length > 1 else "")
+("]" if operation.responses | selectattr('has_body') | map(attribute='schema') | map(attribute='operation_type_annotation')| unique | list | length > 1 else "") ~ ( "]" if return_type_wrapper else "")
 if operation.responses | selectattr('has_body') | first
-else "None" }}{% endmacro %}
+else ((return_type_wrapper + "[") if return_type_wrapper else "") ~ "None" ~ ( "]" if return_type_wrapper else "") }}{% endmacro %}
 {# get async mypy typing #}
-{% macro async_return_type_annotation(operation) %}
-{{ " -> " + return_type_annotation(operation) }}{% endmacro %}
+{% macro async_return_type_annotation(operation, return_type_wrapper) %}
+{{ " -> " + return_type_annotation(operation, return_type_wrapper) }}{% endmacro %}
 {# get sync mypy typing #}
-{% macro sync_return_type_annotation(operation) %}
-{{ "# type: (...) -> " + return_type_annotation(operation) }}{% endmacro %}
+{% macro sync_return_type_annotation(operation, return_type_wrapper) %}
+{{ "# type: (...) -> " + return_type_annotation(operation, return_type_wrapper) }}{% endmacro %}
 {# get method signature #}
-{% macro method_signature(operation, operation_name, async_mode, coroutine) %}
+{% macro method_signature(operation, operation_name, async_mode, coroutine, return_type_wrapper) %}
 {{ "async " if coroutine else "" }}def {{ operation_name }}(
 {% if async_mode %}
     self,
     {% for param_signature in operation.parameters.async_method_signature %}
     {{ param_signature }},
     {% endfor %}
     **kwargs
-){{ async_return_type_annotation(operation) }}:
+){{ async_return_type_annotation(operation, return_type_wrapper) }}:
 {% else %}
     self,
     {% for param_signature in operation.parameters.sync_method_signature %}

diff --git a/autorest/codegen/templates/paging_operation.py.jinja2 b/autorest/codegen/templates/paging_operation.py.jinja2
@@ -3,10 +3,11 @@
 {% set send_xml = "xml" if operation.parameters.has_body and "xml" in operation.request_content_type  %}
 {% set request_as_xml = ", is_xml=True" if send_xml else "" %}
 {% set stream_request_parameter = "stream=" ~ ("True" if operation.is_stream_response else "False") %}
+{% set item_paged = "AsyncItemPaged" if async_mode else "ItemPaged" %}
 {% macro return_docstring() %}
 {% if operation.responses | selectattr('has_body') | first %}
-:return: {{ operation.responses|selectattr('has_body')|map(attribute='schema')|map(attribute='docstring_text')|unique|join(' or ') }} or the result of cls(response)
-    :rtype: {% for response in operation.responses %}{{response.schema.docstring_type if response.has_body else "None"}}{% if not loop.last %} or {% endif %}{% endfor %}
+:return: An iterator like instance of {{ operation.responses|selectattr('has_body')|map(attribute='schema')|map(attribute='docstring_text')|unique|join(' or ') }} or the result of cls(response)
+:rtype: ~azure.core.{{ "async_" if async_mode else "" }}paging.{{ item_paged }}[{% for response in operation.responses %}{{response.schema.docstring_type if response.has_body else "None"}}{% if not loop.last %} or {% endif %}{% endfor %}]
 {% else %}
 :return: None
 :rtype: None
@@ -18,9 +19,10 @@
 {% if code_model.options['tracing'] and operation.want_tracing %}
 @distributed_trace
 {% endif %}
-{{ op_tools.method_signature(operation, operation.python_name, async_mode=async_mode, coroutine=False) }}
+{% set return_type_wrapper = "AsyncIterable" if async_mode else "Iterable" %}
+{{ op_tools.method_signature(operation, operation.python_name, async_mode=async_mode, coroutine=False, return_type_wrapper=return_type_wrapper) }}
 {%- if not async_mode %}
-    {{ op_tools.sync_return_type_annotation(operation) }}
+    {{ op_tools.sync_return_type_annotation(operation, return_type_wrapper) }}
 {% endif %}
 {% if operation.want_description_docstring %}
     """{{operation.description }}
@@ -41,7 +43,7 @@
     :type {{ parameter.serialized_name }}: {{ parameter.schema.docstring_type }}
 {% endfor %}
     :keyword callable cls: A custom type or function that will be passed the direct response
-    {{ return_docstring() }}
+    {{ return_docstring()|indent }}
     :raises: ~azure.core.exceptions.HttpResponseError
     """
 {% endif %}
@@ -129,11 +131,7 @@
 
         return pipeline_response
 
-{% if async_mode %}
-    return AsyncItemPaged(
-{% else %}
-    return ItemPaged(
-{% endif %}
+    return {{ item_paged }}(
         get_next, extract_data
     )
 {{ operation.python_name }}.metadata = {'url': '{{ operation.url|replace("'", "\\'") }}'}  # type: ignore
diff --git a/...ests/CustomUrlPaging/custombaseurlpaging/aio/operations_async/_paging_operations_async.py b/...ests/CustomUrlPaging/custombaseurlpaging/aio/operations_async/_paging_operations_async.py
@@ -5,7 +5,7 @@
 # Code generated by Microsoft (R) AutoRest Code Generator.
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
-from typing import Any, Callable, Dict, Generic, Optional, TypeVar
+from typing import Any, AsyncIterable, Callable, Dict, Generic, Optional, TypeVar
 import warnings
 
 from azure.core.async_paging import AsyncItemPaged, AsyncList
@@ -48,14 +48,15 @@ def get_pages_partial_url(
         self,
         account_name: str,
         **kwargs
-    ) -> "models.ProductResult":
+    ) -> AsyncIterable["models.ProductResult"]:
         """A paging operation that combines custom url, paging and partial URL and expect to concat after host.
 
         :param account_name: Account Name.
         :type account_name: str
         :keyword callable cls: A custom type or function that will be passed the direct response
-        :return: ProductResult or the result of cls(response)
-        :rtype: ~custombaseurlpaging.models.ProductResult
+        :return: An iterator like instance of ProductResult or the result of cls(response)
+        :rtype: ~azure.core.async_paging.AsyncItemPaged[~custombaseurlpaging.models.ProductResult]
+
         :raises: ~azure.core.exceptions.HttpResponseError
         """
         cls = kwargs.pop('cls', None)  # type: ClsType["models.ProductResult"]
@@ -118,14 +119,15 @@ def get_pages_partial_url_operation(
         self,
         account_name: str,
         **kwargs
-    ) -> "models.ProductResult":
+    ) -> AsyncIterable["models.ProductResult"]:
         """A paging operation that combines custom url, paging and partial URL with next operation.
 
         :param account_name: Account Name.
         :type account_name: str
         :keyword callable cls: A custom type or function that will be passed the direct response
-        :return: ProductResult or the result of cls(response)
-        :rtype: ~custombaseurlpaging.models.ProductResult
+        :return: An iterator like instance of ProductResult or the result of cls(response)
+        :rtype: ~azure.core.async_paging.AsyncItemPaged[~custombaseurlpaging.models.ProductResult]
+
         :raises: ~azure.core.exceptions.HttpResponseError
         """
         cls = kwargs.pop('cls', None)  # type: ClsType["models.ProductResult"]

diff --git a/...cted/AcceptanceTests/CustomUrlPaging/custombaseurlpaging/operations/_paging_operations.py b/...cted/AcceptanceTests/CustomUrlPaging/custombaseurlpaging/operations/_paging_operations.py
@@ -5,7 +5,7 @@
 # Code generated by Microsoft (R) AutoRest Code Generator.
 # Changes may cause incorrect behavior and will be lost if the code is regenerated.
 # --------------------------------------------------------------------------
-from typing import Any, Callable, Dict, Generic, Optional, TypeVar
+from typing import Any, Callable, Dict, Generic, Iterable, Optional, TypeVar
 import warnings
 
 from azure.core.exceptions import HttpResponseError, ResourceExistsError, ResourceNotFoundError, map_error
@@ -48,14 +48,15 @@ def get_pages_partial_url(
         account_name,  # type: str
         **kwargs  # type: Any
     ):
-        # type: (...) -> "models.ProductResult"
+        # type: (...) -> Iterable["models.ProductResult"]
         """A paging operation that combines custom url, paging and partial URL and expect to concat after host.
 
         :param account_name: Account Name.
         :type account_name: str
         :keyword callable cls: A custom type or function that will be passed the direct response
-        :return: ProductResult or the result of cls(response)
-        :rtype: ~custombaseurlpaging.models.ProductResult
+        :return: An iterator like instance of ProductResult or the result of cls(response)
+        :rtype: ~azure.core.paging.ItemPaged[~custombaseurlpaging.models.ProductResult]
+
         :raises: ~azure.core.exceptions.HttpResponseError
         """
         cls = kwargs.pop('cls', None)  # type: ClsType["models.ProductResult"]
@@ -119,14 +120,15 @@ def get_pages_partial_url_operation(
         account_name,  # type: str
         **kwargs  # type: Any
     ):
-        # type: (...) -> "models.ProductResult"
+        # type: (...) -> Iterable["models.ProductResult"]
         """A paging operation that combines custom url, paging and partial URL with next operation.
 
         :param account_name: Account Name.
         :type account_name: str
         :keyword callable cls: A custom type or function that will be passed the direct response
-        :return: ProductResult or the result of cls(response)
-        :rtype: ~custombaseurlpaging.models.ProductResult
+        :return: An iterator like instance of ProductResult or the result of cls(response)
+        :rtype: ~azure.core.paging.ItemPaged[~custombaseurlpaging.models.ProductResult]
+
         :raises: ~azure.core.exceptions.HttpResponseError
         """
         cls = kwargs.pop('cls', None)  # type: ClsType["models.ProductResult"]

diff --git a/...ted/AcceptanceTests/Lro/lro/aio/operations_async/_lr_os_custom_header_operations_async.py b/...ted/AcceptanceTests/Lro/lro/aio/operations_async/_lr_os_custom_header_operations_async.py
@@ -105,8 +105,8 @@ async def put_async_retry_succeeded(
         :keyword polling: True for ARMPolling, False for no polling, or a
          polling object for personal polling strategy
         :paramtype polling: bool or ~azure.core.polling.AsyncPollingMethod
-        :return: An instance of LROPoller that returns Product
-        :rtype: ~azure.core.polling.LROPoller[~lro.models.Product]
+        :return: Product
+        :rtype: ~lro.models.Product
 
         :raises ~azure.core.exceptions.HttpResponseError:
         """
@@ -203,8 +203,8 @@ async def put201_creating_succeeded200(
         :keyword polling: True for ARMPolling, False for no polling, or a
          polling object for personal polling strategy
         :paramtype polling: bool or ~azure.core.polling.AsyncPollingMethod
-        :return: An instance of LROPoller that returns Product
-        :rtype: ~azure.core.polling.LROPoller[~lro.models.Product]
+        :return: Product
+        :rtype: ~lro.models.Product
 
         :raises ~azure.core.exceptions.HttpResponseError:
         """
@@ -291,8 +291,8 @@ async def post202_retry200(
         :keyword polling: True for ARMPolling, False for no polling, or a
          polling object for personal polling strategy
         :paramtype polling: bool or ~azure.core.polling.AsyncPollingMethod
-        :return: An instance of LROPoller that returns None
-        :rtype: ~azure.core.polling.LROPoller[None]
+        :return: None
+        :rtype: None
 
         :raises ~azure.core.exceptions.HttpResponseError:
         """
@@ -377,8 +377,8 @@ async def post_async_retry_succeeded(
         :keyword polling: True for ARMPolling, False for no polling, or a
          polling object for personal polling strategy
         :paramtype polling: bool or ~azure.core.polling.AsyncPollingMethod
-        :return: An instance of LROPoller that returns None
-        :rtype: ~azure.core.polling.LROPoller[None]
+        :return: None
+        :rtype: None
 
         :raises ~azure.core.exceptions.HttpResponseError:
         """