Move example code to README and trim white space

tnydwrds · tnydwrds · commit 593e3c64fac3 · 2012-08-26T20:42:54.000-07:00
Temporarily moving example code to README.md until wiki for
documentation has been created.

Also trimming trailing white space now just because.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,2 @@
 ox_*.py
-*.pyc
+*.pyc
diff --git a/README.md b/README.md
@@ -1,4 +1,87 @@
 #OX3-Python-API-Client - Python class to access OpenX Enterprise API
 OX3-Python-API-Client is a small class to help demonstrate how to connect to the OpenX Enterprise API. It depends on the [simplegeo/python-oauth2](https://github.com/simplegeo/python-oauth2) module.
 
-It currently supports Python 2.7 and will be updated to support Python 3.x.
+It currently supports Python 2.7 and will be updated to support Python 3.x.
+
+````python
+import datetime
+import ox3apiclient
+
+# User credentials
+email_address = ''
+password = ''
+
+# OAuth credentials. These will be supplied by your Account Manager or Support.
+domain = ''
+realm = ''
+consumer_key = ''
+consumer_secret = ''
+
+
+ox = ox3apiclient.OX3APIClient(domain, realm, consumer_key, consumer_secret)
+
+# Step 1. Fetch temporary request token.
+ox.fetch_request_token()
+
+# Step 2. Log in to SSO server and authorize token.
+ox.authorize_token(email_address, password)
+
+# Step 3. Swap temporary request token for permanent access token.
+# If you need to store the access token yourself you can do so with something
+# similar to:
+#   token_str = ox.fetch_access_token()
+#   access_token = urlparse.parse_qs(token_str)['oauth_token'][0]
+ox.fetch_access_token()
+
+# Step 4. Validate your access token.
+# You'll more than likely want to call the validate_session method, but you can
+# manually validate your access token if needed. You will be resonpsible for
+# passing the requisite openx3_access_token for all successive API requests. A
+# method might look like the following:
+#   token_str = ox.fetch_access_token()
+#   access_token = urlparse.parse_qs(token_str)['oauth_token'][0]
+#   cookie_header = {'Cookie': 'openx3_access_token=' + access_token}
+#   ox.request(url='http://youruidomain.com/ox/3.0/a/session/validate',
+#       method='PUT',
+#       headers=cookie_header)
+ox.validate_session()
+
+
+# Now that we have connected let's try making a few API requests.
+# Print out account names. We use overload=medium to get more than just a
+# listing of ids.
+accounts = ox.get('/a/account?overload=medium')
+for account in accounts:
+    msg = 'Account ID: %s, Account Name: %s'
+    print(msg % (account['id'], account['name']))
+
+# We won't test object creation with accounts because they can't be deleted
+# currently. Instead, we will create an order under an advertiser account.
+account_id = 0 #<= Replace with a valid advertiser account id for your instance.
+
+if account_id:
+
+    # You can check to see what fields are required for the create action.
+    # required_fields = ox.get('/a/order/requiredFields?action=create')
+    # print(required_fields) #=> {u'status': u'string', u'name': u'string', u'account_id': u'int', u'start_date': u'datetime'}
+
+    # OX3APIClient methods accept Python dicts for data parameters, so we can
+    # define an order as a normal dict.
+    order = {
+        'status': 'Active',
+        'name': 'OX3APIClient Object Creation Test',
+        'account_id': account_id,
+        'start_date': datetime.datetime.today().strftime('%Y-%m-%d %H:%M:%S'),
+    }
+
+    new_order = ox.post('/a/order', data=order)
+    # print(order) #=> {u'id': 12345}
+    print('Created order id %s' % new_order['id'])
+
+    # Let's get all the details on the order we just created.
+    existing_order = ox.get('/a/order/%s' % new_order['id'])
+    print(existing_order)
+
+# Log out.
+ox.delete('/a/session')
+````
diff --git a/example.py b/example.py
diff --git a/ox3apiclient.py b/ox3apiclient.py
@@ -14,7 +14,7 @@
 HTTP_METHOD_OVERRIDES = ['DELETE', 'PUT']
 
 class OX3APIClient(object):
-    
+
     def __init__(self, domain, realm, consumer_key, consumer_secret,
                     callback_url='oob',
                     scheme='http',
@@ -23,9 +23,9 @@ def __init__(self, domain, realm, consumer_key, consumer_secret,
                     authorization_url=AUTHORIZATION_URL,
                     api_path=API_PATH):
         """
-        
+
         domain -- Your UI domain. The API is accessed off this domain.
-        realm -- Your sso realm. While not necessary for all OAuth 
+        realm -- Your sso realm. While not necessary for all OAuth
             implementations, it is a requirement for OpenX Enterprise
         consumer_key -- Your consumer key.
         consumer_secret -- Your consumer secret.
@@ -46,31 +46,31 @@ def __init__(self, domain, realm, consumer_key, consumer_secret,
         self.access_token_url = access_token_url
         self.authorization_url = authorization_url
         self.api_path = api_path
-        
+
         # You shouldn't need to access the oauth2 consumer and token objects
         # directly so we'll keep them "private".
         self._consumer = oauth.Consumer(self.consumer_key, self.consumer_secret)
         self._token = None
-        
+
         # Similarly you probably won't need to access the cookie jar directly,
         # so it is private as well.
         self._cookie_jar = cookielib.LWPCookieJar()
         opener = \
             urllib2.build_opener(urllib2.HTTPCookieProcessor(self._cookie_jar))
-         
+
         urllib2.install_opener(opener)
-    
+
     def _sign_request(self, req):
         """Utility method to sign a request."""
         parameters = {'oauth_callback': self.callback_url}
         headers = req.headers
         data = req.data
-        
+
         # Add any (POST) data to the parameters to be signed in the OAuth
         # request.
         if data:
             parameters.update(data)
-        
+
         # Create a temporary oauth2 Request object and sign it so we can steal
         # the Authorization header.
         oauth_req = oauth.Request.from_consumer_and_token(
@@ -80,80 +80,80 @@ def _sign_request(self, req):
             http_url=req.get_full_url(),
             parameters=parameters,
             is_form_encoded=True)
-        
+
         oauth_req.sign_request(
             oauth.SignatureMethod_HMAC_SHA1(),
             self._consumer,
             self._token)
-        
+
         # Update our original requests headers to include the OAuth Authorization
         # header and return it.
         req.headers.update(oauth_req.to_header(realm=self.realm))
         return \
             urllib2.Request(req.get_full_url(), headers=req.headers, data=data)
-    
+
     def request(self, url, method='GET', headers={}, data=None, sign=False):
         """Helper method to make a (optionally OAuth signed) HTTP request."""
-        
+
         # Since we are using a urllib2.Request object we need to assign a value
         # other than None to "data" in order to make the request a POST request,
         # even if there is no data to post.
         if method == 'POST':
             data = data if data else ''
-        
+
         req = urllib2.Request(url, headers=headers, data=data)
-        
+
         # We need to set the request's get_method function to return a HTTP
         # method for any values other than GET or POST.
         if method in HTTP_METHOD_OVERRIDES:
             req.get_method = lambda: method
-        
+
         if sign:
             req = self._sign_request(req)
-        
+
         # Stringify data.
         if data:
             req.add_data(urllib.urlencode(req.get_data()))
-        
+
         return urllib2.urlopen(req)
-    
+
     def fetch_request_token(self):
         """Helper method to fetch and set request token.
-        
+
         Returns token string.
         """
         res = self.request(url=self.request_token_url, method='POST', sign=True)
         self._token = oauth.Token.from_string(res.read())
         return self._token
-    
+
     def authorize_token(self, email, password):
         """Helper method to authorize."""
         data = {
             'email': email,
             'password': password,
             'oauth_token': self._token.key}
-        
+
         res = self.request(
                 url=self.authorization_url,
                 method='POST',
                 data=data,
                 sign=True)
-        
+
         verifier = urlparse.parse_qs(res.read())['oauth_verifier'][0]
         self._token.set_verifier(verifier)
-    
+
     def fetch_access_token(self):
         """Helper method to fetch and set access token.
-        
+
         Returns token string.
         """
         res = self.request(url=self.access_token_url, method='POST', sign=True)
         self._token = oauth.Token.from_string(res.read())
         return self._token
-    
+
     def validate_session(self):
         """Validate an API session."""
-        
+
         # We need to store our access token as the openx3_access_token cookie.
         # This cookie will be passed to all future API requests.
         cookie = cookielib.Cookie(
@@ -173,38 +173,38 @@ def validate_session(self):
             comment=None,
             comment_url=None,
             rest={})
-        
+
         self._cookie_jar.set_cookie(cookie)
-        
-        url = '%s://%s%s/a/session/validate' % (self.scheme, 
+
+        url = '%s://%s%s/a/session/validate' % (self.scheme,
                                                 self.domain,
                                                 self.api_path)
-        
+
         res = self.request(url=url, method='PUT')
         return res.read()
-    
+
     def _resolve_url(self, url):
         """"""
         parse_res = urlparse.urlparse(url)
         if not parse_res.scheme:
             url ='%s://%s%s%s' % (self.scheme, self.domain, self.api_path,
                                     parse_res.path)
             url = url + '?' + parse_res.query if parse_res.query else url
-        
+
         return url
-    
+
     def get(self, url):
         """"""
         res = self.request(self._resolve_url(url), method='GET')
         return json.loads(res.read())
-    
+
     def post(self, url, data=None):
         """"""
         res = self.request(self._resolve_url(url), method='POST', data=data)
         return json.loads(res.read())
-    
+
     def delete(self, url):
         """"""
         res = self.request(self._resolve_url(url), method='DELETE')
         return json.loads(res.read())
-    
+
