Twitter-ads

**Added**

* Ability to set custom request headers

**Added**
* Audience summary endpoint
* Granular TAP placements
* Advertiser Business Categories

**Removed**
* Reach estimate endpoint

**Changed**
* `serving_status` to `entity_status` for media creatives

As we announced, we're releasing a new version that is incompatible with Python 2.7. All Python 2.7-related issues/questions are no longer be supported as of v6.1.0.

Our CI (Travis test) no longer perform tests with Python 2 environment. The minimum required Python version is now 3.5+. We're not using/adding any Python 3-specific features such as async/await syntax in our SDK code at the moment but we may in the future. Please upgrade your Python version if you're still on Python 2.x.

See our original announcement: https://github.com/twitterdev/twitter-python-ads-sdk/issues/215

Bug fix
- Fix MediaLibrary class https://github.com/twitterdev/twitter-python-ads-sdk/pull/235
- Duplicated `save()` method and introduced `add()` = POST and `update()` = PUT methods
- Fixed VideoConversionCard entity resource property references https://github.com/twitterdev/twitter-python-ads-sdk/pull/231 by shaun10

New
- Added new client options `timeout` and `retry_on_timeouts` https://github.com/twitterdev/twitter-python-ads-sdk/pull/234 Thanks to ariarijp
- You have now the control of a timeout duration specified by the `timeout` option (tuple).
- You can now retry on timeouts using the `retry_on_timeouts` option (boolean) in addition to the `retry_on_status` option (list).

py
client = Client(
CONSUMER_KEY,
CONSUMER_SECRET,
ACCESS_TOKEN,
ACCESS_TOKEN_SECRET,
options={
'handle_rate_limit': True,
'retry_max': 3,
'retry_delay': 5000,
'retry_on_status': [404, 500, 503],
'retry_on_timeouts': True,
'timeout': (1.0, 3.0) https://2.python-requests.org/en/master/user/advanced/#timeouts
})



|parameter|default|description|
|---|:---:|---|
|`retry_on_timeouts`|`False` (boolean)|Set `True` will catch the timeout error and retry the request.|
|`timeout`|`None`|You can specify either a single value OR a tuple. If a single value is specified, the timeout value will be applied to both the `connect` and the `read` timeouts. See https://2.python-requests.org/en/master/user/advanced/#timeouts for more details of the usage.|

New
- Added support for the new Tweets endpoint https://github.com/twitterdev/twitter-python-ads-sdk/pull/228
- Added following endpoints support:
- LineItemApps
- LineItemPlacements
- ContentCategories
- IabCategories

Changed
- The `Analytics` class now moved from `twitter_ads.resouce` to its dedicated path `twitter_ads.analytics`. Please updated the import path accordingly (PR: https://github.com/twitterdev/twitter-python-ads-sdk/pull/227):

diff
- from twitter_ads.resouce import Analytics
+ from twitter_ads.analytics import Analytics

This release is mainly focused on following the recent Ads API version 6 release.
Several important changes are made in version 6 so please see the full details as to what's changed: https://twittercommunity.com/t/ads-api-version-6/129060

You can check all the SDK changes we made in this new release from this PR: https://github.com/twitterdev/twitter-python-ads-sdk/pull/223
We also updated the handy [Postman collection](https://github.com/twitterdev/postman-twitter-ads-api) (v6 support) to make your testing and development workflow even easier.
[](https://app.getpostman.com/run-collection/369a02c0adc626ff6a06#?env%5BTwitter%20Ads%20API%5D=W3sia2V5IjoiYWNjb3VudF9pZCIsInZhbHVlIjoieW91cl9hZHNfYWNjb3VudF9pZCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidmVyc2lvbiIsInZhbHVlIjoiNiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfa2V5IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX2tleSIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiY29uc3VtZXJfc2VjcmV0IiwidmFsdWUiOiJ5b3VyX2NvbnN1bWVyX3NlY3JldCIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoiYWNjZXNzX3Rva2VuIiwidmFsdWUiOiJ5b3VyX2FjY2Vzc190b2tlbiIsImVuYWJsZWQiOnRydWV9LHsia2V5IjoidG9rZW5fc2VjcmV0IiwidmFsdWUiOiJ5b3VyX3Rva2VuX3NlY3JldCIsImVuYWJsZWQiOnRydWV9XQ==)


New
Number of processing jobs
https://twittercommunity.com/t/ads-api-version-6/129060/1#heading--number-of-processing-jobs
In order to make it easier to manage asynchronous analytics workflows, the Ads API now returns two new response headers:

- `X-Concurrent-Job-Limit`: The maximum number of jobs that may be in a processing state at any given time
- `X-Concurrent-Job-Limit-Remaining`: The number of jobs that can be created given the number currently being processed

These values are returned when asynchronous analytics jobs are created using the POST stats/jobs/accounts/:account_id endpoint, and SDK users can access these headers through instance variables:

py
stats = LineItem.queue_async_stats_job(account, ids, metric_groups)

print(stats.concurrent_job_limit)
print(stats.concurrent_job_limit_remaining)


New helper function `split_list()`
This small new helper function`split_list()` can be used for splitting `list` that contains entity ids by a given number.

py

from twitter_ads.utils import split_list

test_list = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
print(list(split_list(test_list, 2)))
=> [[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]]

promoted_tweets = PromotedTweet.all(account)
ids = list(map(lambda x: x.id, promoted_tweets))

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(PromotedTweet.all_stats(account, chunk_ids, metric_groups))

print(sync_data)


Changed
`Analytics.queue_async_stats_job()`
- `Analytics.queue_async_stats_job()` can now be called directly (with specifying entity parameter)
- `Analytics.queue_async_stats_job()` now returns instance rather than dict
diff
- job_id = LineItem.queue_async_stats_job(account, ids, metric_groups)[id]
+ job_id = LineItem.queue_async_stats_job(account, ids, metric_groups).id

`as_user_id` now required https://github.com/twitterdev/twitter-python-ads-sdk/pull/223/commits/c8f0e0e6a2cec3ec04acfb76c703288abd677a11
https://twittercommunity.com/t/ads-api-version-6/129060/1#heading--as-user-id-now-required
Given the impact of this change, SDK now provides a new class method `UserIdLookup.load()` that can be used to lookup an user_id by a given Twitter screen name.
py
user_id = UserIdLookup.load(account, screen_name='your_twitter_handle_name').id


Deprecated
Scoped Timeline
The GET accounts/:account_id/scoped_timeline endpoint is no longer available in v6. https://github.com/twitterdev/twitter-python-ads-sdk/pull/223/commits/fcb60969051e9006e811bf624862fd5d8dc8a2b8
https://twittercommunity.com/t/ads-api-version-6/129060/1#heading--scoped-timeline
\* SDK will continue to support this endpoint until the v5 became sunset.

Removed
Audience Intelligence
https://twittercommunity.com/t/announcement-audience-intelligence-deprecation/127907

Old Tweet preview endpoints
Below endpoints are removed in this release:
- GET accounts/:account_id/tweet/preview
- GET accounts/:account_id/tweet/preview/:tweet_id
- GET accounts/:account_id/draft_tweets/preview/:draft_tweet_id
- GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id