v6 release (#223)

* v6: Expose concurrent job limit

- Analytics.queue_async_stats_job() now returns instance rather than dict
- Analytics.queue_async_stats_job() can now be called directly (with specifying entity parameter)

* Add support for PROMOTED_ACCOUNT stats entity

* Rename CITIES segmentation name to METROS

* remove Scoped Timeline

* as_user_id is now required parameter

* Add additional optimization enum

* remove tailored_audience_type request parameter

* rename lookalike_expansion to audience_expansion

* Media identifier consistency

https://twittercommunity.com/t/ads-api-version-6/129060#heading--media-identifier-consistency

* change API_VERSION

* Revert "remove Scoped Timeline"

This reverts commit 34264d3.

* mark scoped_timeline as deprecated

* update comment

* update example

* Add helper function

- split_list() can be used for splitting entity ids by a given number

Author: smaeda-ks

examples/analytics.py

@@ -13,6 +13,7 @@
 from twitter_ads.client import Client
 from twitter_ads.campaign import LineItem
 from twitter_ads.enum import METRIC_GROUP
+from twitter_ads.utils import split_list
 
 CONSUMER_KEY = 'your consumer key'
 CONSUMER_SECRET = 'your consumer secret'
@@ -42,20 +43,29 @@
     print('Error: A minimum of 1 items must be provided for entity_ids')
     sys.exit()
 
-LineItem.all_stats(account, ids, metric_groups)
+sync_data = []
+# Sync/Async endpoint can handle max 20 entity IDs per request
+# so split the ids list into multiple requests
+for chunk_ids in split_list(ids, 20):
+    sync_data.append(LineItem.all_stats(account, chunk_ids, metric_groups))
 
-# fetching async stats on the instance
-queued_job = LineItem.queue_async_stats_job(account, ids, metric_groups)
+print(sync_data)
 
-# get the job_id:
-job_id = queued_job['id']
+# create async stats jobs and get job ids
+queued_job_ids = []
+for chunk_ids in split_list(ids, 20):
+    queued_job_ids.append(LineItem.queue_async_stats_job(account, chunk_ids, metric_groups).id)
+
+print(queued_job_ids)
 
 # let the job complete
-seconds = 15
+seconds = 30
 time.sleep(seconds)
 
-async_stats_job_result = LineItem.async_stats_job_result(account, [job_id]).first
+async_stats_job_results = LineItem.async_stats_job_result(account, queued_job_ids)
 
-async_data = LineItem.async_stats_job_data(account, async_stats_job_result.url)
+async_data = []
+for result in async_stats_job_results:
+    async_data.append(LineItem.async_stats_job_data(account, result.url))
 
 print(async_data)

examples/draft_tweet.py

@@ -1,6 +1,7 @@
 from twitter_ads.client import Client
 from twitter_ads.campaign import Tweet
 from twitter_ads.creative import DraftTweet
+from twitter_ads.restapi import UserIdLookup
 
 
 CONSUMER_KEY = 'your consumer key'
@@ -15,6 +16,9 @@
 # load the advertiser account instance
 account = client.accounts(ACCOUNT_ID)
 
+# get user_id for as_user_id parameter
+user_id = UserIdLookup.load(account, screen_name='your_twitter_handle_name').id
+
 # fetch draft tweets from a given account
 tweets = DraftTweet.all(account)
 for tweet in tweets:
@@ -24,6 +28,7 @@
 # create a new draft tweet
 draft_tweet = DraftTweet(account)
 draft_tweet.text = 'draft tweet - new'
+draft_tweet.as_user_id = user_id
 draft_tweet = draft_tweet.save()
 print(draft_tweet.id_str)
 print(draft_tweet.text)
@@ -41,7 +46,7 @@
 print(draft_tweet.text)
 
 # create a nullcasted tweet using draft tweet metadata
-tweet = Tweet.create(account, text=draft_tweet.text)
+tweet = Tweet.create(account, text=draft_tweet.text, as_user_id=user_id)
 print(tweet)
 
 # delete draft tweet

examples/promoted_tweet.py

@@ -3,6 +3,7 @@
 from twitter_ads.client import Client
 from twitter_ads.campaign import Tweet
 from twitter_ads.creative import PromotedTweet, WebsiteCard
+from twitter_ads.restapi import UserIdLookup
 
 CONSUMER_KEY = 'your consumer key'
 CONSUMER_SECRET = 'your consumer secret'
@@ -15,15 +16,23 @@
 
 # load up the account instance, campaign and line item
 account = client.accounts(ACCOUNT_ID)
+
+# get user_id for as_user_id parameter
+user_id = UserIdLookup.load(account, screen_name='your_twitter_handle_name').id
+
 campaign = account.campaigns().next()
 line_item = account.line_items(None, campaign_ids=campaign.id).next()
 
 # create request for a simple nullcasted tweet
-tweet1 = Tweet.create(account, text='There can be only one...')
+tweet1 = Tweet.create(account, text='There can be only one...', as_user_id=user_id)
 
 # create request for a nullcasted tweet with a website card
 website_card = WebsiteCard.all(account).next()
-tweet2 = Tweet.create(account, text='Fine. There can be two.', card_uri=website_card.card_uri)
+tweet2 = Tweet.create(
+    account,
+    text='Fine. There can be two.',
+    as_user_id=user_id,
+    card_uri=website_card.card_uri)
 
 # promote the tweet using our line item
 tweet_ids = [tweet1['id'], tweet2['id']]

examples/scheduled_tweet.py

@@ -1,24 +1,29 @@
 from datetime import datetime, timedelta
 
 from twitter_ads.client import Client
-from twitter_ads.campaign import LineItem, ScheduledPromotedTweet
+from twitter_ads.campaign import ScheduledPromotedTweet
 from twitter_ads.creative import ScheduledTweet
+from twitter_ads.restapi import UserIdLookup
 
 CONSUMER_KEY = 'your consumer key'
 CONSUMER_SECRET = 'your consumer secret'
-ACCESS_TOKEN = 'access token'
-ACCESS_TOKEN_SECRET = 'access token secret'
-ACCOUNT_ID = 'account id'
+ACCESS_TOKEN = 'user access token'
+ACCESS_TOKEN_SECRET = 'user access token secret'
+ACCOUNT_ID = 'ads account id'
 
 # initialize the client
 client = Client(CONSUMER_KEY, CONSUMER_SECRET, ACCESS_TOKEN, ACCESS_TOKEN_SECRET)
 
 # load the advertiser account instance
 account = client.accounts(ACCOUNT_ID)
 
+# get user_id for as_user_id parameter
+user_id = UserIdLookup.load(account, screen_name='your_twitter_handle_name').id
+
 # create the Scheduled Tweet
 scheduled_tweet = ScheduledTweet(account)
 scheduled_tweet.text = 'Future'
+scheduled_tweet.as_user_id = user_id
 scheduled_tweet.scheduled_at = datetime.utcnow() + timedelta(days=2)
 scheduled_tweet.save()
 

tests/test_analytics_async.py

@@ -6,7 +6,7 @@
 from twitter_ads.client import Client
 from twitter_ads.campaign import Campaign
 from twitter_ads.resource import Analytics
-from twitter_ads.enum import METRIC_GROUP, GRANULARITY
+from twitter_ads.enum import ENTITY, METRIC_GROUP, GRANULARITY
 from twitter_ads import API_VERSION
 
 
@@ -20,7 +20,11 @@ def test_analytics_async():
     responses.add(responses.POST,
                   with_resource('/' + API_VERSION + '/stats/jobs/accounts/2iqph'),
                   body=with_fixture('analytics_async_post'),
-                  content_type='application/json')
+                  content_type='application/json',
+                  headers={
+                      'x-concurrent-job-limit': '100',
+                      'x-concurrent-job-limit-remaining': '99'
+                  })
 
     responses.add(responses.GET,
                   with_resource('/' + API_VERSION + '/stats/jobs/accounts/2iqph'),
@@ -45,14 +49,30 @@ def test_analytics_async():
         granularity=GRANULARITY.TOTAL
     )
 
-    # test POST request response - queue_async_stats_job()
+    # call queue_async_stats_job() through Campaign class (inheritance)
     assert 'granularity=TOTAL' in responses.calls[1].request.url
     assert stats is not None
-    assert isinstance(stats, dict)
-    assert stats['entity_ids'] == ids
+    assert isinstance(stats, Analytics)
+    assert stats.entity_ids == ids
+    assert stats.concurrent_job_limit == '100'
+
+    stats2 = Analytics.queue_async_stats_job(
+        account,
+        ids,
+        metric_groups,
+        granularity=GRANULARITY.TOTAL,
+        entity=ENTITY.CAMPAIGN
+    )
+
+    # call queue_async_stats_job() from Analytics class directly
+    assert 'entity=CAMPAIGN' in responses.calls[1].request.url
+    assert stats2 is not None
+    assert isinstance(stats2, Analytics)
+    assert stats2.entity_ids == ids
+    assert stats2.concurrent_job_limit == '100'
 
     # call async_stats_job_result() through Campaign class (inheritance)
-    job_id = stats['id_str']
+    job_id = stats.id_str
     job_result = Campaign.async_stats_job_result(
         account,
         [job_id]).first

tests/test_rate_limit.py

@@ -77,8 +77,7 @@ def test_rate_limit_handle_with_retry_success_1(monkeypatch):
     assert len(responses.calls) == 4
     assert cursor is not None
     assert isinstance(cursor, Cursor)
-    assert cursor.rate_limit is None
-    assert cursor.account_rate_limit == '10000'
+    assert cursor.account_rate_limit_limit == '10000'
     assert cursor.account_rate_limit_remaining == '9999'
     assert cursor.account_rate_limit_reset == '1546300800'
 
@@ -146,8 +145,7 @@ def test_rate_limit_handle_with_retry_success_2(monkeypatch):
     assert len(responses.calls) == 4
     assert cursor is not None
     assert isinstance(cursor, Cursor)
-    assert cursor.rate_limit is None
-    assert cursor.account_rate_limit == '10000'
+    assert cursor.account_rate_limit_limit == '10000'
     assert cursor.account_rate_limit_remaining == '9999'
     assert cursor.account_rate_limit_reset == '1546300800'
 
@@ -199,8 +197,7 @@ def test_rate_limit_handle_success(monkeypatch):
     assert len(responses.calls) == 3
     assert cursor is not None
     assert isinstance(cursor, Cursor)
-    assert cursor.rate_limit is None
-    assert cursor.account_rate_limit == '10000'
+    assert cursor.account_rate_limit_limit == '10000'
     assert cursor.account_rate_limit_remaining == '9999'
     assert cursor.account_rate_limit_reset == '1546300800'
 
@@ -287,8 +284,7 @@ def test_rate_limit_cursor_class_access():
     cursor = Campaign.all(account)
     assert cursor is not None
     assert isinstance(cursor, Cursor)
-    assert cursor.rate_limit is None
-    assert cursor.account_rate_limit == '10000'
+    assert cursor.account_rate_limit_limit == '10000'
     assert cursor.account_rate_limit_remaining == '9999'
     assert cursor.account_rate_limit_reset == '1546300800'
 
@@ -333,7 +329,6 @@ def test_rate_limit_resource_class_access():
     assert isinstance(data, Resource)
     assert data.id == '2wap7'
     assert data.entity_status == 'ACTIVE'
-    assert data.rate_limit is None
-    assert data.account_rate_limit == '10000'
+    assert data.account_rate_limit_limit == '10000'
     assert data.account_rate_limit_remaining == '9999'
     assert data.account_rate_limit_reset == '1546300800'

tests/test_retry_count.py

@@ -61,8 +61,7 @@ def test_retry_count_success(monkeypatch):
     assert len(responses.calls) == 3
     assert cursor is not None
     assert isinstance(cursor, Cursor)
-    assert cursor.rate_limit is None
-    assert cursor.account_rate_limit == '10000'
+    assert cursor.account_rate_limit_limit == '10000'
     assert cursor.account_rate_limit_remaining == '9999'
     assert cursor.account_rate_limit_reset == '1546300800'
 

twitter_ads/__init__.py

@@ -1,7 +1,7 @@
 # Copyright (C) 2015 Twitter, Inc.
 
-VERSION = (5, 3, 0)
-API_VERSION = '5'
+VERSION = (6, 0, 0)
+API_VERSION = '6'
 
 from twitter_ads.utils import get_version
 

twitter_ads/account.py

@@ -6,6 +6,7 @@
 from twitter_ads.enum import TRANSFORM
 from twitter_ads.http import Request
 from twitter_ads.cursor import Cursor
+from twitter_ads.utils import Deprecated
 from twitter_ads import API_VERSION
 
 from twitter_ads.resource import resource_property, Resource
@@ -27,7 +28,7 @@ class Account(Resource):
     RESOURCE_COLLECTION = '/' + API_VERSION + '/accounts'
     RESOURCE = '/' + API_VERSION + '/accounts/{id}'
     FEATURES = '/' + API_VERSION + '/accounts/{id}/features'
-    SCOPED_TIMELINE = '/' + API_VERSION + '/accounts/{id}/scoped_timeline'
+    SCOPED_TIMELINE = '/5/accounts/{id}/scoped_timeline'
 
     def __init__(self, client):
         self._client = client
@@ -155,6 +156,8 @@ def video_website_cards(self, id=None, **kwargs):
         """
         return self._load_resource(VideoWebsiteCard, id, **kwargs)
 
+    @Deprecated('This method has been deprecated as of version 5'
+                'and no longer works in the latest version.')
     def scoped_timeline(self, *id, **kwargs):
         """
         Returns the most recent promotable Tweets created by the specified Twitter user.

twitter_ads/campaign.py

@@ -143,7 +143,6 @@ def tv_shows(klass, account, **kwargs):
 resource_property(TargetingCriteria, 'targeting_type')
 resource_property(TargetingCriteria, 'targeting_value')
 resource_property(TargetingCriteria, 'tailored_audience_expansion')
-resource_property(TargetingCriteria, 'tailored_audience_type')
 # sdk-only
 resource_property(TargetingCriteria, 'to_delete', transform=TRANSFORM.BOOL)
 
@@ -298,7 +297,7 @@ def targeting_criteria(self, id=None, **kwargs):
 resource_property(LineItem, 'end_time', transform=TRANSFORM.TIME)
 resource_property(LineItem, 'entity_status')
 resource_property(LineItem, 'include_sentiment')
-resource_property(LineItem, 'lookalike_expansion')
+resource_property(LineItem, 'audience_expansion')
 resource_property(LineItem, 'name')
 resource_property(LineItem, 'objective')
 resource_property(LineItem, 'optimization')
@@ -348,9 +347,9 @@ def create(klass, account, **kwargs):
         params = {}
         params.update(kwargs)
 
-        # handles array to string conversion for media IDs
-        if 'media_ids' in params and isinstance(params['media_ids'], list):
-            params['media_ids'] = ','.join(map(str, params['media_ids']))
+        # handles array to string conversion for media keys
+        if 'media_keys' in params and isinstance(params['media_keys'], list):
+            params['media_keys'] = ','.join(map(str, params['media_keys']))
 
         resource = klass.TWEET_CREATE.format(account_id=account.id)
         response = Request(account.client, 'post', resource, params=params).perform()