[Communication] Phone Number Management - Nov Release (#15182)

* Azure Communication Services - Long Run Operations (#14606)

* commit last version of long run operation

* begin_create_search -> begin_reserve_phone_numbers
begin_purchase_search -> begin_purchase_reservation

* Add ReleasePhoneNumberPolling

* fix input params of release phone numbers

* update async methods

* update samples

* update tests

* fix the client for params when purchasing numbers

* update samples

* update live tests

* update comment of keyword body

* search_id -> reservation_id

* update tests for search_id -> reservation_id

* update samples for serach_id -> reservation_id

* put client as a positional argument to override from_continuation_token method

* Ignore W0221: parameters differ from overridden lint error

* update swagger for changing search id -> reservation id and Search -> Reservation

* refresh auto generated code

* update client method to return PhoneNumberReservation instead of PhoneNumberSearch

* add document types for __init__ function of polling

* rename body to options when starts a reservation

* update tests for the param changes

* update samples due to arg name change in begin_reserve_phone_numbers

* fix some missing name changes

* [Azure Communication Services] Phone Number Admin - Add CHANGELOG for Nov release (#15041)

* add changelog for Nov release

* add a section to beaking changes log

* add a section to new features log

* add backquote and period to the changelog

* Remove duplicate info from CHANGELOG for sync and async.

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

@@ -1,4 +1,31 @@
 # Release History
+## 1.0.0b3 (Unreleased) 
+
+**Breaking Changes**
+
+##### `PhoneNumberSearch` renamed to `PhoneNumberReservation`.
+
+##### `PhoneNumberReservation`
+- `search_id` has been renamed to `reservation_id`.
+
+##### `PhoneNumberAdministrationClient`
+- `get_search_by_id` has been renamed to `get_reservation_by_id`.
+- `create_search` has been renamed to `begin_reserve_phone_numbers`.
+-  `begin_reserve_phone_numbers` now takes either `options`, or `continuation_token` keywords as input.
+-  `begin_reserve_phone_numbers` now returns `LROPoller[PhoneNumberReservation]`.
+- `release_phone_numbers` has been renamed to `begin_release_phone_numbers`.
+-  `begin_release_phone_numbers` now takes either `phone_numbers`, or `continuation_token` keywords as input.
+-  `begin_release_phone_numbers` now returns `LROPoller[PhoneNumberRelease]`.
+- `purchase_search` has been renamed to `begin_purchase_reservation`.
+-  `begin_purchase_reservation` now takes either `reservation_id`, or `continuation_token` keywords as input.
+-  `begin_purchase_reservation` now returns `LROPoller[PurchaseReservationPolling]`.
+- `cancel_search` has been renamed to `cancel_reservation`.
+
+**New Features**
+
+##### `PhoneNumberAdministrationClient`
+- Add long run operation polling method `ReservePhoneNumberPolling`,`PurchaseReservationPolling`,
+`ReleasePhoneNumberPolling`.
 
 ## 1.0.0b2 (2020-10-06)
 - Added support for phone number administration.

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

@@ -6,6 +6,7 @@
 
 from ._communication_identity_client import CommunicationIdentityClient
 from ._phone_number_administration_client import PhoneNumberAdministrationClient
+from ._polling import ReservePhoneNumberPolling, PurchaseReservationPolling, ReleasePhoneNumberPolling
 
 from ._identity._generated.models import (
     CommunicationTokenRequest,
@@ -16,6 +17,7 @@
     AcquiredPhoneNumber,
     AcquiredPhoneNumbers,
     AreaCodes,
+    CreateSearchOptions,
     CreateSearchResponse,
     LocationOptionsQuery,
     LocationOptionsResponse,
@@ -24,14 +26,13 @@
     PhoneNumberCountries,
     PhoneNumberEntities,
     PhoneNumberRelease,
-    PhoneNumberSearch,
+    PhoneNumberReservation,
     PhonePlanGroups,
     PhonePlansResponse,
     PstnConfiguration,
     ReleaseResponse,
     UpdateNumberCapabilitiesResponse,
-    UpdatePhoneNumberCapabilitiesResponse,
-    CreateSearchOptions
+    UpdatePhoneNumberCapabilitiesResponse
 )
 
 from ._shared.models import (
@@ -43,6 +44,9 @@
 __all__ = [
     'CommunicationIdentityClient',
     'PhoneNumberAdministrationClient',
+    'ReservePhoneNumberPolling',
+    'PurchaseReservationPolling',
+    'ReleasePhoneNumberPolling',
 
     # from _identity
     'CommunicationTokenRequest',
@@ -52,6 +56,7 @@
     'AcquiredPhoneNumber',
     'AcquiredPhoneNumbers',
     'AreaCodes',
+    'CreateSearchOptions',
     'CreateSearchResponse',
     'LocationOptionsQuery',
     'LocationOptionsResponse',
@@ -60,14 +65,13 @@
     'PhoneNumberCountries',
     'PhoneNumberEntities',
     'PhoneNumberRelease',
-    'PhoneNumberSearch',
+    'PhoneNumberReservation',
     'PhonePlanGroups',
     'PhonePlansResponse',
     'PstnConfiguration',
     'ReleaseResponse',
     'UpdateNumberCapabilitiesResponse',
     'UpdatePhoneNumberCapabilitiesResponse',
-    'CreateSearchOptions',
 
     # from _shared
     'CommunicationUser',

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

@@ -4,27 +4,29 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
+from azure.communication.administration._phonenumber._generated.models import ReleaseStatus
 from azure.core.tracing.decorator import distributed_trace
 from azure.core.paging import ItemPaged
+from azure.core.polling import LROPoller
+from ._polling import ReleasePhoneNumberPolling, ReservePhoneNumberPolling, PurchaseReservationPolling
 
 from ._phonenumber._generated._phone_number_administration_service\
     import PhoneNumberAdministrationService as PhoneNumberAdministrationClientGen
 
 from ._phonenumber._generated.models import (
     AcquiredPhoneNumbers,
     AreaCodes,
-    CreateSearchResponse,
     LocationOptionsResponse,
     NumberConfigurationResponse,
     NumberUpdateCapabilities,
     PhoneNumberCountries,
     PhoneNumberEntities,
     PhoneNumberRelease,
-    PhoneNumberSearch,
+    PhoneNumberReservation,
     PhonePlanGroups,
     PhonePlansResponse,
     PstnConfiguration,
-    ReleaseResponse,
+    SearchStatus,
     UpdateNumberCapabilitiesResponse,
     UpdatePhoneNumberCapabilitiesResponse
 )
@@ -351,23 +353,54 @@ def get_release_by_id(
         )
 
     @distributed_trace
-    def release_phone_numbers(
+    def begin_release_phone_numbers(
             self,
-            phone_numbers,  # type: List[str]
             **kwargs  # type: Any
     ):
-        # type: (...) -> ReleaseResponse
-        """Creates a release for the given phone numbers.
-
-        :param phone_numbers: The list of phone numbers in the release request.
-        :type phone_numbers: list[str]
-        :rtype: ~azure.communication.administration.ReleaseResponse
+        # type: (...) -> LROPoller[PhoneNumberRelease]
+        """Begins creating a release for the given phone numbers.
+        Caller must provide either phone_numbers, or continuation_token keywords to use the method.
+        If both phone_numbers and continuation_token are specified, only continuation_token will be used to
+        restart a poller from a saved state, and keyword phone_numbers will be ignored.
+
+        :keyword list[str] phone_numbers: The list of phone numbers in the release request.
+        :keyword str continuation_token: A continuation token to restart a poller from a saved state.
+        :rtype: ~azure.core.polling.LROPoller[~azure.communication.administration.PhoneNumberRelease]
         """
-        return self._phone_number_administration_client.phone_number_administration.release_phone_numbers(
-            phone_numbers,
-            **kwargs
+        cont_token = kwargs.pop('continuation_token', None)  # type: Optional[str]
+
+        release_polling = ReleasePhoneNumberPolling(
+            is_terminated=lambda status: status in [
+                ReleaseStatus.Complete,
+                ReleaseStatus.Failed,
+                ReleaseStatus.Expired
+            ]
+        )
+
+        if cont_token is not None:
+            return LROPoller.from_continuation_token(
+                polling_method=release_polling,
+                continuation_token=cont_token,
+                client=self._phone_number_administration_client.phone_number_administration
+            )
+
+        if "phone_numbers" not in kwargs:
+            raise ValueError("Either kwarg 'phone_numbers' or 'continuation_token' needs to be specified")
+
+        create_release_response = self._phone_number_administration_client.\
+            phone_number_administration.release_phone_numbers(
+                **kwargs
+        )
+
+        initial_state = self._phone_number_administration_client.phone_number_administration.get_release_by_id(
+            release_id=create_release_response.release_id
         )
 
+        return LROPoller(client=self._phone_number_administration_client.phone_number_administration,
+                         initial_response=initial_state,
+                         deserialization_callback=None,
+                         polling_method=release_polling)
+
     @distributed_trace
     def list_all_releases(
             self,
@@ -387,40 +420,75 @@ def list_all_releases(
         )
 
     @distributed_trace
-    def get_search_by_id(
+    def get_reservation_by_id(
         self,
-        search_id,  # type: str
+        reservation_id,  # type: str
         **kwargs  # type: Any
     ):
-        # type: (...) -> PhoneNumberSearch
-        """Get search by search id.
+        # type: (...) -> PhoneNumberReservation
+        """Get reservation by reservation id.
 
-        :param search_id: The search id to be searched for.
-        :type search_id: str
-        :rtype: ~azure.communication.administration.PhoneNumberSearch
+        :param reservation_id: The reservation id to get reservation.
+        :type reservation_id: str
+        :rtype: ~azure.communication.administration.PhoneNumberReservation
         """
         return self._phone_number_administration_client.phone_number_administration.get_search_by_id(
-            search_id,
+            search_id=reservation_id,
             **kwargs
         )
 
     @distributed_trace
-    def create_search(
+    def begin_reserve_phone_numbers(
         self,
         **kwargs  # type: Any
     ):
-        # type: (...) -> CreateSearchResponse
-        """Creates a phone number search.
-
-        :keyword azure.communication.administration.CreateSearchOptions body:
-        An optional parameter for defining the search options.
-        The default is None.
-        :rtype: ~azure.communication.administration.CreateSearchResponse
+        # 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.
+        :keyword str continuation_token: A continuation token to restart a poller from a saved state.
+        :rtype: ~azure.core.polling.LROPoller[~azure.communication.administration.PhoneNumberReservation]
         """
-        return self._phone_number_administration_client.phone_number_administration.create_search(
-            **kwargs
+        cont_token = kwargs.pop('continuation_token', None)  # type: Optional[str]
+
+        reservation_polling = ReservePhoneNumberPolling(
+            is_terminated=lambda status: status in [
+                SearchStatus.Reserved,
+                SearchStatus.Expired,
+                SearchStatus.Success,
+                SearchStatus.Cancelled,
+                SearchStatus.Error
+            ]
+        )
+
+        if cont_token is not None:
+            return LROPoller.from_continuation_token(
+                polling_method=reservation_polling,
+                continuation_token=cont_token,
+                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")
+
+        reservation_options = kwargs.pop('options')  # type: str
+
+        create_reservation_response = self._phone_number_administration_client.\
+            phone_number_administration.create_search(
+                body=reservation_options,
+                **kwargs
         )
 
+        initial_state = self._phone_number_administration_client.phone_number_administration.get_search_by_id(
+            search_id=create_reservation_response.search_id
+        )
+        return LROPoller(client=self._phone_number_administration_client.phone_number_administration,
+                         initial_response=initial_state,
+                         deserialization_callback=None,
+                         polling_method=reservation_polling)
+
     @distributed_trace
     def list_all_searches(
             self,
@@ -440,37 +508,68 @@ def list_all_searches(
         )
 
     @distributed_trace
-    def cancel_search(
+    def cancel_reservation(
         self,
-        search_id,  # type: str
+        reservation_id,  # type: str
         **kwargs  # type: Any
     ):
         # type: (...) -> None
-        """Cancels the search. This means existing numbers in the search will be made available.
+        """Cancels the reservation. This means existing numbers in the reservation will be made available.
 
-        :param search_id: The search id to be canceled.
-        :type search_id: str
+        :param reservation_id: The reservation id to be canceled.
+        :type reservation_id: str
         :rtype: None
         """
         return self._phone_number_administration_client.phone_number_administration.cancel_search(
-            search_id,
+            search_id=reservation_id,
             **kwargs
         )
 
     @distributed_trace
-    def purchase_search(
-            self,
-            search_id,  # type: str
-            **kwargs  # type: Any
+    def begin_purchase_reservation(
+        self,
+        **kwargs  # type: Any
     ):
-        # type: (...) -> None
-        """Purchases the phone number search.
-
-        :param search_id: The search id to be purchased.
-        :type search_id: str
-        :rtype: None
+        # type: (...) -> LROPoller[PhoneNumberReservation]
+        """Begins purchase the reserved phone numbers of a phone number search.
+        Caller must provide either reservation_id, or continuation_token keywords to use the method.
+        If both reservation_id and continuation_token are specified, only continuation_token will be used to
+        restart a poller from a saved state, and keyword reservation_id will be ignored.
+        :keyword str reservation_id: The reservation id to be purchased.
+        :keyword str continuation_token: A continuation token to restart a poller from a saved state.
+        :rtype: ~azure.core.polling.LROPoller[~azure.communication.administration.PhoneNumberReservation]
         """
-        return self._phone_number_administration_client.phone_number_administration.purchase_search(
-            search_id,
+        cont_token = kwargs.pop('continuation_token', None)  # type: Optional[str]
+
+        reservation_polling = PurchaseReservationPolling(
+            is_terminated=lambda status: status in [
+                SearchStatus.Success,
+                SearchStatus.Expired,
+                SearchStatus.Cancelled,
+                SearchStatus.Error
+            ]
+        )
+
+        if cont_token is not None:
+            return LROPoller.from_continuation_token(
+                polling_method=reservation_polling,
+                continuation_token=cont_token,
+                client=self._phone_number_administration_client.phone_number_administration
+            )
+
+        if "reservation_id" not in kwargs:
+            raise ValueError("Either kwarg 'reservation_id' or 'continuation_token' needs to be specified")
+
+        reservation_id = kwargs.pop('reservation_id')  # type: str
+
+        self._phone_number_administration_client.phone_number_administration.purchase_search(
+            search_id=reservation_id,
             **kwargs
         )
+        initial_state = self._phone_number_administration_client.phone_number_administration.get_search_by_id(
+            search_id=reservation_id
+        )
+        return LROPoller(client=self._phone_number_administration_client.phone_number_administration,
+                         initial_response=initial_state,
+                         deserialization_callback=None,
+                         polling_method=reservation_polling)