Merge pull request #218 from Vonage/improve-rest-calls

Improve rest calls and remove deprecated methods

Author: maxkahan

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.8.0
+current_version = 3.0.0
 commit = True
 tag = False
 

CHANGES.md

@@ -1,10 +1,19 @@
-# 3.0.0 (Unreleased, WIP)
-- Removed automatic client creation when instantiating an `sms`, `voice` or `verify` object
-- Removed methods to call the Message Search API, which has been retired by Vonage
-- Added `get_all_countries_pricing` method to `Account` object
-- Added a `type` parameter for pricing calls, so `sms` or `voice` pricing can now be chosen
-- Removed deprecated voice and number insight methods from `voice.py` and `number_insight.py`
-- Removed deprecated methods from `client.py` that are now available in specific modules related to each of the available Vonage APIs
+# 3.0.0
+
+Breaking changes:
+- Removed deprecated methods from `client.py` that are now available in specific modules related to each of the available Vonage APIs. E.g. to call the number insight API, the methods are now called in this way: `client.number_insight.get_basic_number_insight(...)`, or by instantiating the `NumberInsight` class directly: `ni = vonage.NumberInsight(client)`, `ni.get_basic_number_insight(...)` etc.
+- Removed automatic client creation when instantiating an `sms`, `voice` or `verify` object. You can now use these APIs from a client instance you create (e.g. `client.sms.send_message()`) or pass in a client to the API class to create it (e.g. `sms = vonage.Sms(client)`), as has been the case since v2.7.0 of the SDK.
+- Removed methods to call the Message Search API, which has been retired by Vonage.
+- Removed deprecated voice and number insight methods from `voice.py` (`initiate_call, initiate_tts_call and initiate_tts_prompt_call`) and `number_insight.py` (`request_number_insight`).
+- Deprecated the ApplicationV2 class and created an Application class with the same methods to bring the naming in line with other classes. This can be called from the client object with `client.application.create_application(...)` etc. or directly with `application = vonage.Application(client)`, `application.create_application(...)` etc.
+- Deprecated old Pricing API methods `get_sms_pricing` and `get_voice_pricing`.
+- Deprecated Redact class as it's a dev preview product that's unsupported in the SDK and will be removed in a later release.
+- Renamed the `Account.delete_secret()` method to `revoke_secret()` to bring it in line with what is described in our documentation.
+
+Enhancements:
+- Added `get_all_countries_pricing` method to `Account` object.
+- Added a `type` parameter for pricing calls, so `sms` or `voice` pricing can now be chosen.
+- Added `max_retries`, `timeout`, `pool_connections` and `pool_maxsize` optional keyword arguments to the `Client` class, which can now be specified on instantiation and used in the API calls made with the client.
 
 # 2.8.0
 - Added Messages API v1.0 support. Messages API can now be used by calling the `client.messages.send_message()` method.

README.md

@@ -142,6 +142,16 @@ response = client.sms.send_message({
 client.sms.submit_sms_conversion(response['message-id'])
 ```
 
+### Update the default SMS webhook URLs for callbacks/delivery reciepts
+```python
+client.sms.update_default_sms_webhook({
+    'moCallBackUrl': 'new.url.vonage.com',      # Default inbound sms webhook url
+    'drCallBackUrl': 'different.url.vonage.com' # Delivery receipt url
+    }})
+```
+
+The delivery receipt URL can be unset by sending an empty string.
+
 ## Messages API
 
 The Messages API is an API that allows you to send messages via SMS, MMS, WhatsApp, Messenger and Viber. Call the API from your Python code by 
@@ -458,6 +468,37 @@ client.number_insight.get_advanced_number_insight(number='447700900000')
 
 Docs: [https://developer.nexmo.com/api/number-insight#getNumberInsightAdvanced](https://developer.nexmo.com/api/number-insight?utm_source=DEV_REL&utm_medium=github&utm_campaign=python-client-library#getNumberInsightAdvanced)
 
+## Account API
+
+### Get your account balance
+```python
+client.account.get_balance()
+```
+
+### Top up your account
+This feature is only enabled when you enable auto-reload for your account in the dashboard.
+```python
+# trx is the reference from when auto-reload was enabled and money was added
+client.account.topup(trx=transaction_reference) 
+```
+
+## Pricing API
+
+### Get pricing for a single country
+```python
+client.get_country_pricing(country_code='GB', type='sms') # Default type is sms
+```
+
+### Get pricing for all countries
+```python
+client.get_all_countries_pricing(type='sms') # Default type is sms, can be voice
+```
+
+### Get pricing for a specific dialling prefix
+```python
+client.get_country_pricing(prefix='44', type='sms')
+```
+
 ## Managing Secrets
 
 An API is provided to allow you to rotate your API secrets. You can create a new secret (up to a maximum of two secrets) and delete the existing one once all applications have been updated.
@@ -468,6 +509,12 @@ An API is provided to allow you to rotate your API secrets. You can create a new
 secrets = client.account.list_secrets(API_KEY)
 ```
 
+### Get information about a specific secret
+
+```python
+secrets = client.account.get_secret(API_KEY, secret_id)
+```
+
 ### Create A New Secret
 
 Create a new secret (the created dates will help you know which is which):
@@ -481,47 +528,47 @@ client.account.create_secret(API_KEY, 'awes0meNewSekret!!;');
 Delete the old secret (any application still using these credentials will stop working):
 
 ```python
-client.account.delete_secret(API_KEY, 'my-secret-id')
+client.account.revoke_secret(API_KEY, 'my-secret-id')
 ```
 
 ## Application API
 
 ### Create an application
 
 ```python
-response = client.application_v2.create_application({name='Example App', type='voice'})
+response = client.application.create_application({name='Example App', type='voice'})
 ```
 
 Docs: [https://developer.nexmo.com/api/application.v2#createApplication](https://developer.nexmo.com/api/application.v2#createApplication?utm_source=DEV_REL&utm_medium=github&utm_campaign=python-client-library#create-an-application)
 
 ### Retrieve a list of applications
 
 ```python
-response = client.application_v2.list_applications()
+response = client.application.list_applications()
 ```
 
 Docs: [https://developer.nexmo.com/api/application.v2#listApplication](https://developer.nexmo.com/api/application.v2#listApplication?utm_source=DEV_REL&utm_medium=github&utm_campaign=python-client-library#retrieve-your-applications)
 
 ### Retrieve a single application
 
 ```python
-response = client.application_v2.get_application(uuid)
+response = client.application.get_application(uuid)
 ```
 
 Docs: [https://developer.nexmo.com/api/application.v2#getApplication](https://developer.nexmo.com/api/application.v2#getApplication?utm_source=DEV_REL&utm_medium=github&utm_campaign=python-client-library#retrieve-an-application)
 
 ### Update an application
 
 ```python
-response = client.application_v2.update_application(uuid, answer_method='POST')
+response = client.application.update_application(uuid, answer_method='POST')
 ```
 
 Docs: [https://developer.nexmo.com/api/application.v2#updateApplication](https://developer.nexmo.com/api/application.v2#updateApplication?utm_source=DEV_REL&utm_medium=github&utm_campaign=python-client-library#update-an-application)
 
 ### Delete an application
 
 ```python
-response = client.application_v2.delete_application(uuid)
+response = client.application.delete_application(uuid)
 ```
 
 Docs: [https://developer.nexmo.com/api/application.v2#deleteApplication](https://developer.nexmo.com/api/application.v2#deleteApplication?utm_source=DEV_REL&utm_medium=github&utm_campaign=python-client-library#destroy-an-application)
@@ -608,7 +655,7 @@ The following is a list of Vonage APIs and whether the Python SDK provides suppo
 | Number Insight API    | General Availability |     ✅     |
 | Number Management API | General Availability |     ✅     |
 | Pricing API           | General Availability |     ✅     |
-| Redact API            | General Availability |     ✅     |
+| Redact API            |   Developer Preview  |     ❌     |
 | Reports API           |         Beta         |     ❌     |
 | SMS API               | General Availability |     ✅     |
 | Verify API            | General Availability |     ✅     |

docs/conf.py

@@ -66,9 +66,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = "2.8.0"
+version = "3.0.0"
 # The full version, including alpha/beta/rc tags.
-release = "2.8.0"
+release = "3.0.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -143,7 +143,7 @@
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = u'Vonage v2.8.0'
+# html_title = u'Vonage v3.0.0'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #

setup.py

@@ -11,7 +11,7 @@
 
 setup(
     name="vonage",
-    version="2.8.0",
+    version="3.0.0",
     description="Vonage Server SDK for Python",
     long_description=long_description,
     long_description_content_type="text/markdown",

src/vonage/__init__.py

@@ -1,3 +1,3 @@
 from .client import *
 
-__version__ = "2.8.0"
+__version__ = "3.0.0"

src/vonage/account.py

@@ -1,75 +1,110 @@
 from .errors import PricingTypeError
 
+from deprecated import deprecated
 class Account:
+    account_auth_type = 'params'
+    pricing_auth_type = 'params'
+    secrets_auth_type = 'header'
+
     allowed_pricing_types = {'sms', 'sms-transit', 'voice'}
 
     def __init__(self, client):
         self._client = client
 
     def get_balance(self):
-        return self._client.get(self._client.host(), "/account/get-balance")
+        return self._client.get(self._client.host(), "/account/get-balance", auth_type=Account.account_auth_type)
 
     def topup(self, params=None, **kwargs):
-        return self._client.post(self._client.host(), "/account/top-up", params or kwargs)
+        return self._client.post(
+            self._client.host(), 
+            "/account/top-up",
+            params or kwargs, 
+            auth_type=Account.account_auth_type,
+            body_is_json=False,
+        )
 
     def get_country_pricing(self, country_code: str, type: str = 'sms'):
         self._check_allowed_pricing_type(type)
         return self._client.get(
-            self._client.host(), f"/account/get-pricing/outbound/{type}", {"country": country_code}
+            self._client.host(), 
+            f"/account/get-pricing/outbound/{type}", 
+            {"country": country_code},
+            auth_type=Account.pricing_auth_type
         )
 
     def get_all_countries_pricing(self, type: str = 'sms'):
         self._check_allowed_pricing_type(type)
         return self._client.get(
-            self._client.host(), f"/account/get-full-pricing/outbound/{type}"
+            self._client.host(), f"/account/get-full-pricing/outbound/{type}", auth_type=Account.pricing_auth_type
         )
 
     def get_prefix_pricing(self, prefix: str, type: str = 'sms'):
         self._check_allowed_pricing_type(type)
         return self._client.get(
-            self._client.host(), f"/account/get-prefix-pricing/outbound/{type}", {"prefix": prefix}
+            self._client.host(), 
+            f"/account/get-prefix-pricing/outbound/{type}",
+            {"prefix": prefix},
+            auth_type=Account.pricing_auth_type,
         )
 
+    @deprecated(version='3.0.0', reason='The "account/get-phone-pricing" endpoint is deprecated.')
     def get_sms_pricing(self, number: str):
         return self._client.get(
-            self._client.host(), "/account/get-phone-pricing/outbound/sms", {"phone": number}
+            self._client.host(), 
+            "/account/get-phone-pricing/outbound/sms", 
+            {"phone": number},
+            auth_type=Account.pricing_auth_type,
         )
 
+    @deprecated(version='3.0.0', reason='The "account/get-phone-pricing" endpoint is deprecated.')
     def get_voice_pricing(self, number: str):
         return self._client.get(
-            self._client.host(), "/account/get-phone-pricing/outbound/voice", {"phone": number}
+            self._client.host(), 
+            "/account/get-phone-pricing/outbound/voice", 
+            {"phone": number},
+            auth_type=Account.pricing_auth_type,
         )
 
     def update_default_sms_webhook(self, params=None, **kwargs):
-        return self._client.post(self._client.host(), "/account/settings", params or kwargs)
+        return self._client.post(
+            self._client.host(), 
+            "/account/settings", 
+            params or kwargs,
+            auth_type=Account.account_auth_type,
+            body_is_json=False,
+        )
 
     def list_secrets(self, api_key):
         return self._client.get(
             self._client.api_host(),
             f"/accounts/{api_key}/secrets",
-            header_auth=True,
+            auth_type=Account.secrets_auth_type,
         )
 
     def get_secret(self, api_key, secret_id):
         return self._client.get(
             self._client.api_host(),
             f"/accounts/{api_key}/secrets/{secret_id}",
-            header_auth=True,
+            auth_type=Account.secrets_auth_type,
         )
 
     def create_secret(self, api_key, secret):
         body = {"secret": secret}
-        return self._client._post_json(
-            self._client.api_host(), f"/accounts/{api_key}/secrets", body
+        return self._client.post(
+            self._client.api_host(), 
+            f"/accounts/{api_key}/secrets",
+            body,
+            auth_type=Account.secrets_auth_type,
+            body_is_json=False,
         )
 
     def revoke_secret(self, api_key, secret_id):
         return self._client.delete(
             self._client.api_host(),
             f"/accounts/{api_key}/secrets/{secret_id}",
-            header_auth=True,
+            auth_type=Account.secrets_auth_type,
         )
 
     def _check_allowed_pricing_type(self, type):
-        if type not in self.allowed_pricing_types:
+        if type not in Account.allowed_pricing_types:
             raise PricingTypeError('Invalid pricing type specified.')