Merge pull request #1 from pixability/feature/upgrade_tw_api

Feature/upgrade tw api

Author: agrant917

.gitignore

@@ -61,3 +61,7 @@ target/
 
 # Virtualenv
 sdk/
+
+# IDE files
+.project
+.pydevproject

.pullapprove.yml

@@ -10,11 +10,13 @@ matrix:
   include:
     - python: 2.7
       script: python setup.py flake8 && python setup.py test
-    - python: 3.2
-      script: python setup.py test
     - python: 3.3
       script: python setup.py test
     - python: 3.4
       script: python setup.py test
+    - python: 3.5
+      script: python setup.py test
     - python: pypy
       script: python setup.py flake8 && python setup.py test
+    - python: pypy3
+      script: pip install setuptools_scm && python setup.py test 

.travis.yml

@@ -16,6 +16,7 @@ Quick Start
 
     from twitter_ads.client import Client
     from twitter_ads.campaign import Campaign
+    from twitter_ads.enum import ENTITY_STATUS
 
     CONSUMER_KEY = 'your consumer key'
     CONSUMER_SECRET = 'your consumer secret'
@@ -33,7 +34,7 @@ Quick Start
     # load and update a specific campaign
     campaign = account.campaigns().next()
     campaign.name = 'updated campaign name'
-    campaign.paused = True
+    campaign.entity_status = ENTITY_STATUS.PAUSED
     campaign.save()
 
     # iterate through campaigns
@@ -62,13 +63,13 @@ This project is designed to work with Python 2.7 or greater. While it
 may work on other version of Python, below are the platform and runtime
 versions we officially support and regularly test against.
 
-+------------+----------------------+
-| Platform   | Versions             |
-+============+======================+
-| CPython    | 2.7, 3.2, 3.3, 3.4   |
-+------------+----------------------+
-| PyPy       | 2.x, 4.x             |
-+------------+----------------------+
++------------+-------------------------+
+| Platform   | Versions                |
++============+=========================+
+| CPython    | 2.7, 3.3, 3.4, 3.5      |
++------------+-------------------------+
+| PyPy       | 2.x, 4.x                |
++------------+-------------------------+
 
 All releases adhere to strict `semantic versioning`_. For Example,
 major.minor.patch-pre (aka. stick.carrot.oops-peek).

README.rst

@@ -30,6 +30,7 @@ Quick Start
 
     from twitter_ads.client import Client
     from twitter_ads.campaign import Campaign
+    from twitter_ads.enum import ENTITY_STATUS
 
     # initialize the client
     client = Client(CONSUMER_KEY,
@@ -43,7 +44,7 @@ Quick Start
     # load and update a specific campaign
     campaign = list(account.campaigns())[0]
     campaign.name = 'updated campaign name'
-    campaign.paused = True
+    campaign.entity_status = ENTITY_STATUS.PAUSED
     campaign.save()
 
     # iterate through campaigns
@@ -70,13 +71,13 @@ This project is designed to work with Python 2.7 or greater. While it
 may work on other version of Python, below are the platform and runtime
 versions we officially support and regularly test against.
 
-+------------+----------------------+
-| Platform   | Versions             |
-+============+======================+
-| CPython    | 2.7, 3.2, 3.3, 3.4   |
-+------------+----------------------+
-| PyPy       | 2.x, 4.x             |
-+------------+----------------------+
++------------+-------------------------+
+| Platform   | Versions                |
++============+=========================+
+| CPython    | 2.7, 3.3, 3.4, 3.5      |
++------------+-------------------------+
+| PyPy       | 2.x, 4.x                |
++------------+-------------------------+
 
 All releases adhere to strict `semantic versioning`_. For Example,
 major.minor.patch-pre (aka. stick.carrot.oops-peek).

docs/source/index.rst

@@ -0,0 +1,48 @@
+# Copyright (C) 2015-2016 Twitter, Inc.
+# Note: All account_media/media_creatives must be uploaded via the media-upload endpoints
+# See: https://dev.twitter.com/rest/media/uploading-media
+
+from twitter_ads.client import Client
+from twitter_ads.http import Request
+from twitter_ads.enums import CREATIVE_TYPE
+from twitter_ads.creative import AccountMedia, MediaCreative
+
+CONSUMER_KEY = 'your consumer key'
+CONSUMER_SECRET = 'your consumer secret'
+ACCESS_TOKEN = 'access token'
+ACCESS_TOKEN_SECRET = 'access token secret'
+ACCOUNT_ID = '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)
+
+# grab the first line_item on the account
+line_item_id = account.line_items().first.id
+
+# retrive the `id` of the media creative associated with a line item
+print account.media_creatives().first.id
+
+# retrieve the `id` of the first account media associated with the account
+account_media_id = account.account_media().first.id
+
+# create a new account media
+account_media = AccountMedia(account)
+account_media.media_id = 'your-media-id' 
+# OR account_media.video_id OR account_media.vast_url
+# see the media_upload.py example for more details
+account_media.creative_type = CREATIVE_TYPE.BANNER
+account_media.save()
+
+
+#create a new media creative
+media_creative = MediaCreative(account)
+media_creative.line_item_id = line_item_id
+media_creative.account_media_id = account_media_id
+media_creative.landing_url = "https://my-landing-url"
+media_creative.save()
+
+# delete the media creative
+media_creative.delete()

examples/account_media.py

@@ -7,6 +7,8 @@
 # https://dev.twitter.com/ads/analytics/metrics-and-segmentation
 # https://dev.twitter.com/ads/analytics/metrics-derived
 
+import time
+
 from twitter_ads.client import Client
 from twitter_ads.campaign import LineItem
 from twitter_ads.enum import METRIC_GROUP
@@ -36,3 +38,17 @@
 # fetching stats for multiple line items
 ids = map(lambda x: x.id, line_items)
 LineItem.all_stats(account, ids, metric_groups)
+
+# fetching async stats on the instance
+queued_job = LineItem.queue_async_stats_job(account, ids, metric_groups)
+
+# get the job_id:
+job_id = queued_job['id']
+
+# let the job complete
+seconds = 15
+time.sleep(seconds)
+
+async_stats_job_result = LineItem.async_stats_job_result(account, job_id)
+
+async_data = LineItem.async_stats_job_data(account, async_stats_job_result['url'])

examples/analytics.py

@@ -0,0 +1,92 @@
+from datetime import datetime
+
+from twitter_ads.client import Client
+from twitter_ads.campaign import Campaign, LineItem, TargetingCriteria
+from twitter_ads.enum import ENTITY_STATUS, OBJECTIVE, PLACEMENT, PRODUCT
+
+CONSUMER_KEY = 'your consumer key'
+CONSUMER_SECRET = 'your consumer secret'
+ACCESS_TOKEN = 'user access token'
+ACCESS_TOKEN_SECRET = 'user access token secret'
+ADS_ACCOUNT = 'ads account id'
+
+# initialize the twitter ads api client
+client = Client(CONSUMER_KEY, CONSUMER_SECRET, ACCESS_TOKEN, ACCESS_TOKEN_SECRET)
+
+# load up the account instance
+account = client.accounts(ADS_ACCOUNT)
+
+# create two campaigns
+campaign_1 = Campaign(account)
+campaign_1.funding_instrument_id = account.funding_instruments().next().id
+campaign_1.daily_budget_amount_local_micro = 1000000
+campaign_1.name = 'my first campaign'
+campaign_1.entity_status = ENTITY_STATUS.PAUSED
+campaign_1.start_time = datetime.utcnow()
+
+campaign_2 = Campaign(account)
+campaign_2.funding_instrument_id = account.funding_instruments().next().id
+campaign_2.daily_budget_amount_local_micro = 2000000
+campaign_2.name = 'my second campaign'
+campaign_2.entity_status = ENTITY_STATUS.PAUSED
+campaign_2.start_time = datetime.utcnow()
+
+campaigns_list = [campaign_1, campaign_2]
+Campaign.batch_save(account, campaigns_list)
+
+# modify the created campaigns
+campaign_1.name = 'my modified first campaign'
+campaign_2.name = 'my modified second campaign'
+
+Campaign.batch_save(account, campaigns_list)
+
+# create line items for campaign_1
+line_item_1 = LineItem(account)
+line_item_1.campaign_id = campaign_1.id
+line_item_1.name = 'my first ad'
+line_item_1.product_type = PRODUCT.PROMOTED_TWEETS
+line_item_1.placements = [PLACEMENT.ALL_ON_TWITTER]
+line_item_1.objective = OBJECTIVE.TWEET_ENGAGEMENTS
+line_item_1.bid_amount_local_micro = 10000
+line_item_1.entity_status = ENTITY_STATUS.PAUSED
+
+line_item_2 = LineItem(account)
+line_item_2.campaign_id = campaign_1.id
+line_item_2.name = 'my second ad'
+line_item_2.product_type = PRODUCT.PROMOTED_TWEETS
+line_item_2.placements = [PLACEMENT.ALL_ON_TWITTER]
+line_item_2.objective = OBJECTIVE.TWEET_ENGAGEMENTS
+line_item_2.bid_amount_local_micro = 20000
+line_item_2.entity_status = ENTITY_STATUS.PAUSED
+
+line_items_list = [line_item_1, line_item_2]
+LineItem.batch_save(account, line_items_list)
+
+# create targeting criteria for line_item_1
+targeting_criterion_1 = TargetingCriteria(account)
+targeting_criterion_1.line_item_id = line_item_1.id
+targeting_criterion_1.targeting_type = 'LOCATION'
+targeting_criterion_1.targeting_value = '00a8b25e420adc94'
+
+targeting_criterion_2 = TargetingCriteria(account)
+targeting_criterion_2.line_item_id = line_item_1.id
+targeting_criterion_2.targeting_type = 'PHRASE_KEYWORD'
+targeting_criterion_2.targeting_value = 'righteous dude'
+
+targeting_criteria_list = [targeting_criterion_1, targeting_criterion_2]
+TargetingCriteria.batch_save(account, targeting_criteria_list)
+
+targeting_criterion_1.to_delete = True
+targeting_criterion_2.to_delete = True
+
+TargetingCriteria.batch_save(account, targeting_criteria_list)
+
+line_item_1.to_delete = True
+line_item_2.to_delete = True
+
+LineItem.batch_save(account, line_items_list)
+
+campaign_1.to_delete = True
+campaign_2.to_delete = True
+
+Campaign.batch_save(account, campaigns_list)

examples/batch_request.py

@@ -0,0 +1,54 @@
+import json
+
+from twitter_ads.campaign import TargetingCriteria
+from twitter_ads.client import Client
+
+CONSUMER_KEY = ""
+CONSUMER_SECRET = ""
+ACCESS_TOKEN = ""
+ACCESS_TOKEN_SECRET = ""
+ADS_ACCOUNT = ""
+
+# initialize the twitter ads api client
+client = Client(CONSUMER_KEY, CONSUMER_SECRET, ACCESS_TOKEN, ACCESS_TOKEN_SECRET)
+
+# load up the account instance
+account = client.accounts(ADS_ACCOUNT)
+
+# load file
+# assumes targeting.json is structured as follows
+"""
+[  
+  {  
+    "operation_type":"Create",
+    "params":{  
+      "line_item_id":"1a2bc",
+      "targeting_value":"digital",
+      "operator_type":"EQ",
+      "targeting_type":"BROAD_KEYWORD"
+    }
+  },
+  {  
+    "operation_type":"Create",
+    "params":{  
+      "line_item_id":"1a2bc",
+      "targeting_value":"analog",
+      "operator_type":"NE",
+      "targeting_type":"BROAD_KEYWORD"
+    }
+  }
+]
+"""
+with open('targeting.json', 'r') as f:
+    targeting_data = json.load(f)
+
+targeting = []
+for obj in targeting_data:
+    tc = TargetingCriteria(account)
+    tc.line_item_id = obj['params']['line_item_id']
+    tc.operator_type = obj['params']['operator_type']
+    tc.targeting_type = obj['params']['targeting_type']
+    tc.targeting_value = obj['params']['targeting_value']
+    targeting.append(tc)
+
+TargetingCriteria.batch_save(account, targeting)

examples/batch_tc_from_file.py

@@ -42,4 +42,4 @@
 
 # execute requests and iterate cursor until exhausted
 for obj in cursor:
-    print(object['name'])
+    print(obj['name'])

examples/manual_request.py

@@ -19,7 +19,7 @@
 line_item = account.line_items(None, campaign_ids=campaign.id).next()
 
 # create request for a simple nullcasted tweet
-tweet1 = Tweet.create(account, 'There can be only one...')
+tweet1 = Tweet.create(account, text='There can be only one...')
 
 # promote the tweet using our line item
 promoted_tweet = PromotedTweet(account)
@@ -29,8 +29,8 @@
 
 # create request for a nullcasted tweet with a website card
 website_card = WebsiteCard.all(account).next()
-status = "Fine. There can be two. {card_url}".format(card_url=website_card.preview_url)
-tweet2 = Tweet.create(account, status)
+text = "Fine. There can be two. {card_url}".format(card_url=website_card.preview_url)
+tweet2 = Tweet.create(account, text)
 
 # promote the tweet using our line item
 promoted_tweet = PromotedTweet(account)

examples/promoted_tweet.py

@@ -2,7 +2,7 @@
 
 from twitter_ads.client import Client
 from twitter_ads.campaign import Campaign, LineItem, TargetingCriteria
-from twitter_ads.enum import PRODUCT, PLACEMENT, OBJECTIVE
+from twitter_ads.enum import ENTITY_STATUS, OBJECTIVE, PLACEMENT, PRODUCT
 
 CONSUMER_KEY = 'your consumer key'
 CONSUMER_SECRET = 'your consumer secret'
@@ -21,7 +21,7 @@
 campaign.funding_instrument_id = account.funding_instruments().next().id
 campaign.daily_budget_amount_local_micro = 1000000
 campaign.name = 'my first campaign'
-campaign.paused = True
+campaign.entity_status = ENTITY_STATUS.PAUSED
 campaign.start_time = datetime.utcnow()
 campaign.save()
 
@@ -33,7 +33,7 @@
 line_item.placements = [PLACEMENT.ALL_ON_TWITTER]
 line_item.objective = OBJECTIVE.TWEET_ENGAGEMENTS
 line_item.bid_amount_local_micro = 10000
-line_item.paused = True
+line_item.entity_status = ENTITY_STATUS.PAUSED
 line_item.save()
 
 # add targeting criteria