Refactor begin_reserve_phone_numbers() by flattening CreateSearchOptions into args (Azure#15378)

* refactor the params of begin_reserve_phone_numbers

* update test and samples

* rename reserve_phone_numbers_response to create_reservation_poller

* refactor async method begin_reserve_phone_numbers

* update samples for reserve_phone_numbers_poller

* correct missed async calls

* refresh tests and the generated test yaml files

* refresh CHANGELOG

Author: HeliWang

sdk/communication/azure-communication-administration/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## 1.0.0b4 (Unreleased)
 
+##### `PhoneNumberAdministrationClient`
+-  `begin_reserve_phone_numbers` now takes `display_name`, `description`, `phone_plan_ids`, 
+`area_code`, `quantity`, `location_options`, or `continuation_token` keywords as input. 
+Caller must provide one of the following:
+ (1) all of keywords `display_name`, `description`, `phone_plan_ids`, `area_code`, `quantity` if all the phone plans
+ to reserve are toll-free plans.
+ (2) all of keywords `display_name`, `description`, `phone_plan_ids`, `area_code`, `quantity`, `location_options`
+ if at least one phone plan to reserve is not toll-free plans.
+ (3) only keyword `continuation_token` to restart a poller from a saved state.
 
 ## 1.0.0b3 (2020-11-16)
 

sdk/communication/azure-communication-administration/azure/communication/administration/_phone_number_administration_client.py

@@ -4,7 +4,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
-from azure.communication.administration._phonenumber._generated.models import ReleaseStatus
+from azure.communication.administration._phonenumber._generated.models import ReleaseStatus, CreateSearchOptions
 from azure.core.tracing.decorator import distributed_trace
 from azure.core.paging import ItemPaged
 from azure.core.polling import LROPoller
@@ -444,10 +444,21 @@ def begin_reserve_phone_numbers(
     ):
         # type: (...) -> LROPoller[PhoneNumberReservation]
         """Begins creating a phone number search to reserve phone numbers.
-        Caller must provide either options, or continuation_token keywords to use the method.
-        If both options and continuation_token are specified, only continuation_token will be used to
-        restart a poller from a saved state, and keyword options will be ignored.
-        :keyword azure.communication.administration.CreateSearchOptions options: reservation options.
+        Caller must provide one of the following:
+         (1) all of keywords display_name, description, phone_plan_ids, area_code, quantity if all the phone plans
+         to reserve are toll-free plans.
+         (2) all of keywords display_name, description, phone_plan_ids, area_code, quantity, location_options
+         if at least one phone plan to reserve is not toll-free plans.
+         (3) only keyword continuation_token to restart a poller from a saved state.
+        If both continuation_token and other keywords are specified, only continuation_token will be used to
+        restart a poller from a saved state, and other keywords will be ignored.
+        :keyword str display_name: display name of the search.
+        :keyword str description: description of the search.
+        :keyword list[str] phone_plan_ids: the plan subtype ids from which to create the search.
+        :keyword str area_code: the area code from which to create the search.
+        :keyword int quantity: the quantity of phone numbers to request.
+        :keyword list[~azure.communication.administration.models.LocationOptionsDetails] location_options:
+            the location options of the search.
         :keyword str continuation_token: A continuation token to restart a poller from a saved state.
         :rtype: ~azure.core.polling.LROPoller[~azure.communication.administration.PhoneNumberReservation]
         """
@@ -470,10 +481,23 @@ def begin_reserve_phone_numbers(
                 client=self._phone_number_administration_client.phone_number_administration
             )
 
-        if "options" not in kwargs:
-            raise ValueError("Either kwarg 'options' or 'continuation_token' needs to be specified")
+        required_kwargs = ['display_name', 'description', 'phone_plan_ids', 'area_code', 'quantity']
+        for required_kwarg in required_kwargs:
+            if required_kwarg not in kwargs:
+                raise ValueError("Either kwarg 'continuation_token', or a set of kwargs " +
+                                 "'display_name', 'description', 'phone_plan_ids', "
+                                 "'area_code', 'quantity' needs to be specified")
+
+        reservation_options = CreateSearchOptions(
+                display_name=kwargs.pop('display_name'),
+                description=kwargs.pop('description'),
+                phone_plan_ids=kwargs.pop('phone_plan_ids'),
+                area_code=kwargs.pop('area_code'),
+                quantity=kwargs.pop('quantity')
+            )
 
-        reservation_options = kwargs.pop('options')  # type: str
+        if 'location_options' in kwargs:
+            reservation_options.location_options = kwargs.pop('location_options')
 
         create_reservation_response = self._phone_number_administration_client.\
             phone_number_administration.create_search(

sdk/communication/azure-communication-administration/azure/communication/administration/aio/_phone_number_administration_client_async.py

@@ -6,7 +6,7 @@
 # ------------------------------------
 from typing import Dict, List
 
-from azure.communication.administration._phonenumber._generated.models import ReleaseStatus
+from azure.communication.administration._phonenumber._generated.models import ReleaseStatus, CreateSearchOptions
 from azure.core.async_paging import AsyncItemPaged
 from azure.core.tracing.decorator import distributed_trace
 from azure.core.tracing.decorator_async import distributed_trace_async
@@ -454,10 +454,21 @@ async def begin_reserve_phone_numbers(
     ):
         # type: (...) -> AsyncLROPoller[PhoneNumberReservation]
         """Begins creating a phone number search to reserve phone numbers.
-        Caller must provide either options, or continuation_token keywords to use the method.
-        If both options and continuation_token are specified, only continuation_token will be used to
-        restart a poller from a saved state, and keyword options will be ignored.
-        :keyword azure.communication.administration.CreateSearchOptions options: reservation options.
+        Caller must provide one of the following:
+         (1) all of keywords display_name, description, phone_plan_ids, area_code, quantity if all the phone plans
+         to reserve are toll-free plans.
+         (2) all of keywords display_name, description, phone_plan_ids, area_code, quantity, location_options
+         if at least one phone plan to reserve is not toll-free plans.
+         (3) only keyword continuation_token to restart a poller from a saved state.
+        If both continuation_token and other keywords are specified, only continuation_token will be used to
+        restart a poller from a saved state, and other keywords will be ignored.
+        :keyword str display_name: display name of the search.
+        :keyword str description: description of the search.
+        :keyword list[str] phone_plan_ids: the plan subtype ids from which to create the search.
+        :keyword str area_code: the area code from which to create the search.
+        :keyword int quantity: the quantity of phone numbers to request.
+        :keyword list[~azure.communication.administration.models.LocationOptionsDetails] location_options:
+            the location options of the search.
         :keyword str continuation_token: A continuation token to restart a poller from a saved state.
         :rtype: ~azure.core.polling.AsyncLROPoller[~azure.communication.administration.PhoneNumberReservation]
         """
@@ -480,18 +491,31 @@ async def begin_reserve_phone_numbers(
                 client=self._phone_number_administration_client.phone_number_administration
             )
 
-        if "options" not in kwargs:
-            raise ValueError("Either kwarg 'options' or 'continuation_token' needs to be specified")
+        required_kwargs = ['display_name', 'description', 'phone_plan_ids', 'area_code', 'quantity']
+        for required_kwarg in required_kwargs:
+            if required_kwarg not in kwargs:
+                raise ValueError("Either kwarg 'continuation_token', or a set of kwargs " +
+                                 "'display_name', 'description', 'phone_plan_ids', "
+                                 "'area_code', 'quantity' needs to be specified")
+
+        reservation_options = CreateSearchOptions(
+                display_name=kwargs.pop('display_name'),
+                description=kwargs.pop('description'),
+                phone_plan_ids=kwargs.pop('phone_plan_ids'),
+                area_code=kwargs.pop('area_code'),
+                quantity=kwargs.pop('quantity')
+            )
 
-        reservation_options = kwargs.pop('options')  # type: str
+        if 'location_options' in kwargs:
+            reservation_options.location_options = kwargs.pop('location_options')
 
-        create_search_response = await self._phone_number_administration_client.\
+        create_reservation_response = await self._phone_number_administration_client.\
             phone_number_administration.create_search(
                 body=reservation_options,
                 **kwargs
-            )
+        )
         initial_state = await self._phone_number_administration_client.phone_number_administration.get_search_by_id(
-            search_id=create_search_response.search_id
+            search_id=create_reservation_response.search_id
         )
         return AsyncLROPoller(client=self._phone_number_administration_client.phone_number_administration,
                          initial_response=initial_state,

sdk/communication/azure-communication-administration/samples/phone_number_orders_sample.py

@@ -73,19 +73,16 @@ def get_reservation_by_id():
 
 def begin_reserve_phone_numbers():
     # [START begin_reserve_phone_numbers]
-    reservationOptions = CreateSearchOptions(
+    reserve_phone_numbers_poller = phone_number_administration_client.begin_reserve_phone_numbers(
         area_code=area_code_for_reservation,
         description="testreservation20200014",
         display_name="testreservation20200014",
         phone_plan_ids=[phone_plan_id],
         quantity=1
     )
-    reserve_phone_numbers_response = phone_number_administration_client.begin_reserve_phone_numbers(
-        options=reservationOptions
-    )
     # [END begin_reserve_phone_numbers]
     print('reserve phone numbers status:')
-    print(reserve_phone_numbers_response.status())
+    print(reserve_phone_numbers_poller.status())
 
 
 def cancel_reservation():

sdk/communication/azure-communication-administration/samples/phone_number_orders_sample_async.py

@@ -87,11 +87,15 @@ async def begin_reserve_phone_numbers():
         quantity=1
     )
     async with phone_number_administration_client:
-        reserve_phone_numbers_response = await phone_number_administration_client.begin_reserve_phone_numbers(
-            options=reservationOptions
+        reserve_phone_numbers_poller = await phone_number_administration_client.begin_reserve_phone_numbers(
+            area_code=area_code_for_reservation,
+            description="testreservation20200014",
+            display_name="testreservation20200014",
+            phone_plan_ids=[phone_plan_id],
+            quantity=1
         )
         print('reserve phone numbers status:')
-        print(reserve_phone_numbers_response.status())
+        print(reserve_phone_numbers_poller.status())
     # [END begin_reserve_phone_numbers]
 
 

sdk/communication/azure-communication-administration/tests/recordings/test_phone_number_administration_client.test_cancel_reservation.yaml

@@ -11,7 +11,7 @@ interactions:
       Content-Length:
       - '0'
       Date:
-      - Tue, 27 Oct 2020 17:26:49 GMT
+      - Mon, 23 Nov 2020 22:11:17 GMT
       User-Agent:
       - azsdk-python-communication-administration/1.0.0b2 Python/3.6.9 (Linux-5.4.0-48-generic-x86_64-with-Ubuntu-18.04-bionic)
       x-ms-return-client-request-id:
@@ -25,11 +25,11 @@ interactions:
       content-length:
       - '0'
       date:
-      - Tue, 27 Oct 2020 17:26:50 GMT
+      - Mon, 23 Nov 2020 22:11:17 GMT
       ms-cv:
-      - QytXiS0WYUWt+Aklz2RkDQ.0
+      - mbCpJZCKiUK4caapFCbzQg.0
       x-processing-time:
-      - 472ms
+      - 258ms
     status:
       code: 202
       message: Accepted

sdk/communication/azure-communication-administration/tests/recordings/test_phone_number_administration_client.test_configure_number.yaml

@@ -1,7 +1,7 @@
 interactions:
 - request:
     body: 'b''{"pstnConfiguration": {"callbackUrl": "https://callbackurl", "applicationId":
-      "ApplicationId"}, "phoneNumber": "+1area_code_for_reservation7840394"}'''
+      "ApplicationId"}, "phoneNumber": "+1area_code_for_reservation4501240"}'''
     headers:
       Accept:
       - '*/*'
@@ -14,7 +14,7 @@ interactions:
       Content-Type:
       - application/json
       Date:
-      - Tue, 27 Oct 2020 17:26:50 GMT
+      - Mon, 23 Nov 2020 22:11:17 GMT
       User-Agent:
       - azsdk-python-communication-administration/1.0.0b2 Python/3.6.9 (Linux-5.4.0-48-generic-x86_64-with-Ubuntu-18.04-bionic)
       x-ms-return-client-request-id:
@@ -28,11 +28,11 @@ interactions:
       content-length:
       - '0'
       date:
-      - Tue, 27 Oct 2020 17:26:50 GMT
+      - Mon, 23 Nov 2020 22:11:18 GMT
       ms-cv:
-      - Bv+CA5160EOmb87qa0O06Q.0
+      - G9imTJyYkkSUmuTD6LmwNg.0
       x-processing-time:
-      - 552ms
+      - 886ms
     status:
       code: 200
       message: OK