Bing Ads Python SDK version 10.4.4 release

HISTORY.rst

@@ -3,6 +3,14 @@
 Release History
 ---------------
 
+10.4.4(2016-05-30)
+++++++++++++++++++
+
+* Add App Install Ad support
+* Add state property in OAuthAuthorization classes
+* Support oauth_tokens initialization in Authentication classes
+* Updated wsdl proxy to latest version
+
 10.4.3(2016-04-30)
 ++++++++++++++++++
 

bingads/authorization.py

@@ -249,17 +249,21 @@ class OAuthAuthorization(Authentication):
     * :class:`.OAuthWebAuthCodeGrant`
     """
 
-    def __init__(self, client_id):
+    def __init__(self, client_id, oauth_tokens=None):
         """ Initializes a new instance of the OAuthAuthorization class.
 
         :param client_id: The client identifier corresponding to your registered application.
         :type client_id: str
+        :param oauth_tokens: Contains information about OAuth access tokens received from the Microsoft Account authorization service
+        :type oauth_tokens: OAuthTokens
+        :rtype: str
         """
 
         if client_id is None:
             raise ValueError('Client id cannot be None.')
         self._client_id = client_id
-        self._oauth_tokens = None
+        self._oauth_tokens = oauth_tokens
+        self._state = None
 
     @property
     def client_id(self):
@@ -283,6 +287,21 @@ def oauth_tokens(self):
 
         return self._oauth_tokens
 
+    @property
+    def state(self):
+        """ An opaque value used by the client to maintain state between the request and callback
+        :rtype: str
+        """
+
+        return self._state
+
+    @state.setter
+    def state(self, value):
+        """ An opaque value used by the client to maintain state between the request and callback
+        :rtype: str
+        """
+        self._state = value
+
     @property
     def redirection_uri(self):
         """ The URI to which the user of the app will be redirected after receiving user consent.
@@ -319,22 +338,24 @@ class OAuthWithAuthorizationCode(OAuthAuthorization):
     For more information about registering a Bing Ads application, see http://go.microsoft.com/fwlink/?LinkID=511607.
     """
 
-    def __init__(self, client_id, client_secret, redirection_uri, token_refreshed_callback=None):
+    def __init__(self, client_id, client_secret, redirection_uri, token_refreshed_callback=None, oauth_tokens=None):
         """ Initialize a new instance of this class.
 
         :param client_id: The client identifier corresponding to your registered application.
         :type client_id: str
-        :param client_secret: The client secret corresponding to your registered application, or null if your app is a
+        :param client_secret: The client secret corresponding to your registered application, or None if your app is a
         desktop or mobile app.
         :type client_secret: str or None
         :param redirection_uri: The URI to which the user of the app will be redirected after receiving user consent.
         :type redirection_uri: str
         :param token_refreshed_callback: (optional) Call back function when oauth_tokens be refreshed.
         :type token_refreshed_callback: (OAuthTokens)->None or None
+        :param oauth_tokens: Contains information about OAuth access tokens received from the Microsoft Account authorization service
+        :type oauth_tokens: OAuthTokens
         :return:
         """
 
-        super(OAuthWithAuthorizationCode, self).__init__(client_id)
+        super(OAuthWithAuthorizationCode, self).__init__(client_id, oauth_tokens=oauth_tokens)
         self._client_secret = client_secret
         self._redirection_uri = redirection_uri
         self._token_refreshed_callback = token_refreshed_callback
@@ -345,13 +366,13 @@ def get_authorization_endpoint(self):
         :return: The Microsoft Account authorization endpoint.
         :rtype: str
         """
-
-        return str.format(
+        endpoint = str.format(
             'https://login.live.com/oauth20_authorize.srf?client_id={0}&scope=bingads.manage&response_type={1}&redirect_uri={2}',
             self._client_id,
             'code',
             self._redirection_uri
         )
+        return endpoint if self.state is None else endpoint + '&state=' + self.state
 
     def request_oauth_tokens_by_response_uri(self, response_uri):
         """ Retrieves OAuth access and refresh tokens from the Microsoft Account authorization service.
@@ -373,6 +394,7 @@ def request_oauth_tokens_by_response_uri(self, response_uri):
                 "Please make sure the uri has a code in it, for example http://myurl.com?code=123"
             )
         code = parameters['code'][0]
+
         self._oauth_tokens = _LiveComOAuthService.get_access_token(
             client_id=self.client_id,
             client_secret=self.client_secret,
@@ -411,7 +433,7 @@ def request_oauth_tokens_by_refresh_token(self, refresh_token):
 
     @property
     def client_secret(self):
-        """ The client secret corresponding to your registered application, or null if your app is a desktop or mobile app.
+        """ The client secret corresponding to your registered application, or None if your app is a desktop or mobile app.
 
         :rtype: str
         """
@@ -463,17 +485,20 @@ class OAuthDesktopMobileAuthCodeGrant(OAuthWithAuthorizationCode):
     For more information about registering a Bing Ads application, see http://go.microsoft.com/fwlink/?LinkID=511607.
     """
 
-    def __init__(self, client_id):
+    def __init__(self, client_id, oauth_tokens=None):
         """ Initializes a new instance of the this class with the specified client id.
 
         :param client_id: The client identifier corresponding to your registered application.
         :type client_id: str
+        :param oauth_tokens: Contains information about OAuth access tokens received from the Microsoft Account authorization service
+        :type oauth_tokens: OAuthTokens
         """
 
         super(OAuthDesktopMobileAuthCodeGrant, self).__init__(
             client_id,
             None,
             _LiveComOAuthService.DESKTOP_REDIRECTION_URI,
+            oauth_tokens=oauth_tokens,
         )
 
 
@@ -506,14 +531,16 @@ class OAuthDesktopMobileImplicitGrant(OAuthAuthorization):
     For more information about registering a Bing Ads application, see http://go.microsoft.com/fwlink/?LinkID=511607.
     """
 
-    def __init__(self, client_id):
+    def __init__(self, client_id, oauth_tokens=None):
         """ Initializes a new instance of the this class with the specified client id.
 
         :param client_id: The client identifier corresponding to your registered application.
         :type client_id: str
+        :param oauth_tokens: Contains information about OAuth access tokens received from the Microsoft Account authorization service
+        :type oauth_tokens: OAuthTokens
         """
 
-        super(OAuthDesktopMobileImplicitGrant, self).__init__(client_id)
+        super(OAuthDesktopMobileImplicitGrant, self).__init__(client_id, oauth_tokens=oauth_tokens)
 
     def get_authorization_endpoint(self):
         """ Gets the Microsoft Account authorization endpoint where the user should be navigated to give his or her consent.
@@ -522,12 +549,13 @@ def get_authorization_endpoint(self):
         :rtype: str
         """
 
-        return str.format(
+        endpoint = str.format(
             'https://login.live.com/oauth20_authorize.srf?client_id={0}&scope=bingads.manage&response_type={1}&redirect_uri={2}',
             self.client_id,
             'token',
             _LiveComOAuthService.DESKTOP_REDIRECTION_URI,
         )
+        return endpoint if self.state is None else endpoint + '&state=' + self.state
 
     def extract_access_token_from_uri(self, redirection_uri):
         """ Extracts the access token from the specified redirect URI.

bingads/manifest.py

@@ -1,4 +1,4 @@
-VERSION = '10.4.3'
+VERSION = '10.4.4'
 BULK_FORMAT_VERSION = '3.0'
 BULK_FORMAT_VERSION_4 = '4.0'
 WORKING_NAME = 'BingAdsSDKPython'

bingads/v10/bulk/entities/bulk_ads.py

@@ -8,6 +8,7 @@
 # Define type used
 ProductAd = type(_CAMPAIGN_OBJECT_FACTORY_V10.create('ProductAd'))
 TextAd = type(_CAMPAIGN_OBJECT_FACTORY_V10.create('TextAd'))
+AppInstallAd = type(_CAMPAIGN_OBJECT_FACTORY_V10.create('AppInstallAd'))
 
 
 class _BulkAd(_SingleRecordBulkEntity):
@@ -17,6 +18,7 @@ class _BulkAd(_SingleRecordBulkEntity):
 
     * :class:`.BulkProductAd`
     * :class:`.BulkTextAd`
+    * :class:`.BulkAppInstallAd`
     """
 
     def __init__(self,
@@ -309,3 +311,81 @@ def process_mappings_to_row_values(self, row_values, exclude_readonly_data):
         self._validate_property_not_null(self.text_ad, 'text_ad')
         super(BulkTextAd, self).process_mappings_to_row_values(row_values, exclude_readonly_data)
         self.convert_to_values(row_values, BulkTextAd._MAPPINGS)
+
+
+class BulkAppInstallAd(_BulkAd):
+    """ Represents an App Install Ad.
+
+    This class exposes the :attr:`app_install_ad` property that can be read and written as fields of the App Install Ad record in a bulk file.
+
+    For more information, see App Install Ad at http://go.microsoft.com/fwlink/?LinkID=730549.
+
+    *See also:*
+
+    * :class:`.BulkServiceManager`
+    * :class:`.BulkOperation`
+    * :class:`.BulkFileReader`
+    * :class:`.BulkFileWriter`
+    """
+
+    def __init__(self,
+                 ad_group_id=None,
+                 campaign_name=None,
+                 ad_group_name=None,
+                 ad=None):
+        super(BulkAppInstallAd, self).__init__(
+            ad_group_id,
+            campaign_name,
+            ad_group_name,
+            ad,
+        )
+        self.app_install_ad = ad
+
+    @property
+    def app_install_ad(self):
+        """ The App Install Ad.
+
+        see App Install Ad at http://go.microsoft.com/fwlink/?LinkID=730549.
+        """
+
+        return self._ad
+
+    @app_install_ad.setter
+    def app_install_ad(self, app_install_ad):
+        if app_install_ad is not None and not isinstance(app_install_ad, AppInstallAd):
+            raise ValueError('Not an instance of AppInstallAd')
+        self._ad = app_install_ad
+
+    _MAPPINGS = [
+        _SimpleBulkMapping(
+            header=_StringTable.AppPlatform,
+            field_to_csv=lambda c: c.app_install_ad.AppPlatform,
+            csv_to_field=lambda c, v: setattr(c.app_install_ad, 'AppPlatform', v)
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.AppStoreId,
+            field_to_csv=lambda c: c.app_install_ad.AppStoreId,
+            csv_to_field=lambda c, v: setattr(c.app_install_ad, 'AppStoreId', v)
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.Title,
+            field_to_csv=lambda c: c.app_install_ad.Title,
+            csv_to_field=lambda c, v: setattr(c.app_install_ad, 'Title', v)
+        ),
+        _SimpleBulkMapping(
+            header=_StringTable.Text,
+            field_to_csv=lambda c: c.app_install_ad.Text,
+            csv_to_field=lambda c, v: setattr(c.app_install_ad, 'Text', v)
+        ),
+    ]
+
+    def process_mappings_from_row_values(self, row_values):
+        self.app_install_ad = _CAMPAIGN_OBJECT_FACTORY_V10.create('AppInstallAd')
+        self.app_install_ad.Type = 'AppInstall'
+        super(BulkAppInstallAd, self).process_mappings_from_row_values(row_values)
+        row_values.convert_to_entity(self, BulkAppInstallAd._MAPPINGS)
+
+    def process_mappings_to_row_values(self, row_values, exclude_readonly_data):
+        self._validate_property_not_null(self.app_install_ad, 'app_install_ad')
+        super(BulkAppInstallAd, self).process_mappings_to_row_values(row_values, exclude_readonly_data)
+        self.convert_to_values(row_values, BulkAppInstallAd._MAPPINGS)

bingads/v10/internal/bulk/bulk_object_factory.py

@@ -50,6 +50,7 @@ class _BulkObjectFactory():
         #_StringTable.MobileAd: _EntityInfo(lambda: BulkMobileAd()),
         _StringTable.ProductAd: _EntityInfo(lambda: BulkProductAd()),
         _StringTable.TextAd: _EntityInfo(lambda: BulkTextAd()),
+        _StringTable.AppInstallAd: _EntityInfo(lambda: BulkAppInstallAd()),
         "Campaign Negative Site": _EntityInfo(
             lambda: BulkCampaignNegativeSite(),
             _StringTable.Website,

bingads/v10/internal/bulk/string_table.py

@@ -15,6 +15,7 @@ class _StringTable:
     Keyword = "Keyword"
     TextAd = "Text Ad"
     ProductAd = "Product Ad"
+    AppInstallAd = "App Install Ad"
     Title = "Title"
     EditorialStatus = "Editorial Status"
     EditorialAppealStatus = "Editorial Appeal Status"

setup.py

@@ -3,7 +3,7 @@
 except ImportError:
     from distutils.core import setup
 
-VERSION = '10.4.3'
+VERSION = '10.4.4'
 
 with open('README.rst', 'r') as f:
     readme = f.read()