TextLinkAds | The Leader in Text Link Search Engine Optimization

Python 2.6.2 Installation Instructions

Signup and Site Submission Required to fully install plugin.

Create a directory named tla and copy the source code below into tla/__init__.py. Then use the following code in your application

from tla import *

tla = TextLinkAds('XXXXXXJOINtextlinkadsFORKEYXXXXXX')
print (tla.get_html())

Package Info

This Python module integrates our Standard Text Links Ads functionality directly into your Python driven site. It is for Python version 3.0 + see the 2.6 version.

Version 3.0.1

Ad Code

#!/usr/bin/env python

"""
    =================
    Python TLA Client
    =================
    
    Library to retrieve, parse and display text link ads from 
    TLA (www.text-link-ads.com)
    
    License
    =======
    
    Licensed under BSD License with the following exceptions:
    
    Copyright (C) 2009, Project Fondue. All rights reserved.
    
    Software License Agreement (BSD License)
    
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are met:
    
    * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
    * Neither the name of Project Fondue nor the names of its contributors 
    may be used to endorse or promote products derived from this software 
    without specific prior written permission of Project Fondue.
    
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS" 
    AND ANYEXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
    THE IMPLIED WARRANTIES OF MERCHANT ABILITY AND FITNESS FOR A PARTICULAR 
    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS 
    BE LIABLE FOR ANYDIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
    POSSIBILITY OF SUCH DAMAGE.
    
    Dependencies
    ============
    
    httplib2 - more info at http://tinyurl.com/6mpw2v
    python-memcached - more info at http://tinyurl.com/5agmel
    
    Command Line Usage
    ==================
    
    Test output with python tla.py
    
    Usage with application
    ======================
    
    .. sourcecode:: python
    
    import tla
    
    tla = TextLinkAds('XXXXXXJOINtextlinkadsFORKEYXXXXXX')
    print tla.get_html()
    
    """

import json
import logging
import os
import urllib

try:
    import httplib2
except ImportError:
    print ("httplib2 is available at http://tinyurl.com/6mpw2v")

TLA_URL = 'http://www.text-link-ads.com/xml.php?k=%s&l=python-tla-2.0.1&f=json'

HTTP_TIMEOUT = 5
HTTP_CACHE_FILENAME = '/tmp/tla.%s.json' # %s replaced with inventory key

LOG_FILENAME = '/tmp/tla.%s.log' # %s replaced with inventory key
LOG_LEVELS = {
    'debug': logging.DEBUG,
    'info': logging.INFO,
    'warning': logging.WARNING,
    'error': logging.ERROR,
    'critical': logging.CRITICAL
}
LOG_LEVEL = 'info'

MEMCACHE_ENABLED = False
CACHE_EXPIRY = 3600 # defaults to 1 hour
MEMCACHE_HOSTS = ('127.0.0.1:11211',)

if MEMCACHE_ENABLED:
    try:
        import memcache
    except ImportError:
        print ("python-memcached is available at http://tinyurl.com/5agmel")
        raise


class TextLinkAds:
    """library for returning and caching text link ads from TLA"""
    
    def __init__(self, inventory_key, **kwargs):
        """class constructor"""
        
        url = kwargs.get('url', TLA_URL)
        
        self.http_timeout = kwargs.get('http_timeout', HTTP_TIMEOUT)
        self.http_cache_filename = kwargs.get(
                                              'http_cache_filename', HTTP_CACHE_FILENAME
                                              ) % inventory_key
        
        self.log_filename = kwargs.get('log_filename', 
                                       LOG_FILENAME % inventory_key)
        self.log_levels = kwargs.get('log_levels', LOG_LEVELS)
        self.log_level = kwargs.get('log_level', LOG_LEVEL)
        self.logger = self.setup_logger()
        
        self.url = url % inventory_key
        
        self.caching_enabled = kwargs.get('caching_enabled', MEMCACHE_ENABLED)
        
        # instantiate memcache instance - if it fails disable using memcache 
        # and make a new request to TLA for each page view
        if self.caching_enabled:
            memcache_hosts = kwargs.get('memcache_hosts', MEMCACHE_HOSTS or [])
            self.memcache_expiry = kwargs.get('cache_expiry', CACHE_EXPIRY)
            self.memcache_key = 'tla%s' % inventory_key
            try:
                self.memcache = memcache.Client(memcache_hosts, debug=0)
                self.caching_enabled = True
            except ValueError as msg:
                self.caching_enabled = False
                self.logger.error(
                                  'Incorrect memcache server format specifed (%s)' % (msg)
                                  )
    
    
    def setup_logger(self):
        """ set up logger to record errors to file """
        
        logger = logging.getLogger('TLA')
        logger.setLevel(self.log_levels[self.log_level])
        file_handle = logging.FileHandler(self.log_filename)
        file_handle.setLevel(self.log_levels[self.log_level])
        formatter = logging.Formatter(
                                      "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
                                      )
        file_handle.setFormatter(formatter)
        logger.addHandler(file_handle)
        return logger
    
    
    def write_http_cache(self, content):
        """ write response of http request to file """
        
        try:
            http_cache_file = open(self.http_cache_filename, 'w')
            http_cache_file.write(content)
            http_cache_file.close()
            
            return True
        except IOError as msg:
            self.logger.error(
                              'Failed to write http cache file (%s)' % (msg)
                              )
    
    
    def read_http_cache(self):
        """ read cached copy of last successful http request from file """
        
        if os.path.exists(self.http_cache_filename):
            try:
                http_cache_file = open(self.http_cache_filename, 'r')
                content = http_cache_file.read()
                http_cache_file.close()
                
                return content
            except IOError as msg:
                self.logger.error(
                                  'Failed to read http cache file (%s)' % (msg)
                                  )
    
    
    def fetch(self):
        """make http request for TLA ads"""
        
        # no cache details specified as TLA doesn't seem to do anything 
        # with last modified or etag - it returns a 200 each time
        request = httplib2.Http(timeout=self.http_timeout)
        
        # httplib2 will return a status code instead of an exception on 
        # error - easier to handle when all we care about is whether or  
        # not we got a 200
        request.force_exception_to_status_code = True
        
        response, content = request.request(self.url)
        # anything but a 200 means data wasn't successfully retrieved
        if response.status == 200:
            # cache response in file in case of future failed requests
            str_content = content.decode('utf-8')
            self.write_http_cache(str_content)
            
            return str_content
        else:
            # http request failed, retrieve data from cache file if present
            return self.read_http_cache()
    
    
    def get_data(self):
        """Get a dictionary of raw data containing links from TLA"""
        
        if self.caching_enabled and self.memcache.get(self.memcache_key):
            return self.memcache.get(self.memcache_key)
        else:
            data = self.fetch()
            
            if data:
                links = json.loads(data)
                link_data = []
                
                # build list containing details of each ad
                for link in links:
                    link_data.append({
                                     'url': link['URL'],
                                     'text': link['Text'],
                                     'beforeText': link['BeforeText'],
                                     'afterText': link['AfterText']
                                     })
                
                if self.caching_enabled:
                    self.memcache.set(
                                      self.memcache_key, 
                                      link_data, 
                                      self.memcache_expiry
                                      )
                
                return link_data
    
    def get_html(self, **kwargs):
        """get rendered list of links
            
            Optionally allows the user to pass in the following:
            
            header_level (1-6) -  The heading level to be displayed as html
            header_text - the text for the heading. (may contain html)
            
            class_attr - an optional classname for the ul
            id_attr - an optional id for the ul
            
            """
        links = self.get_data()
        
        if links:
            html = []
            
            header_level = kwargs.get('header_level')
            header_text  = kwargs.get('header_text')
            class_attr  = kwargs.get('class_attr')
            id_attr  = kwargs.get('id_attr')
            
            if header_level and header_text:
                
                html.append('<h%s>%s</h%s>' % (
                                               header_level, header_text, header_level)
                            )
            
            
            class_attr = class_attr and " class='%s'" % class_attr or ''   
            id_attr = id_attr and " id='%s'" % id_attr or ''   
            
            html.append('<ul%s%s>' % (class_attr, id_attr))
            
            for link in links:
                if link['url'] and link['text']:
                    html.append(
                                '<li>%s<a href="%s">%s</a>%s</li>' % (
                                                                      link['beforeText'], 
                                                                      link['url'], 
                                                                      link['text'], 
                                                                      link['afterText'],
                                                                      )
                                )
            
            html.append('</ul>')
            
            return '\n'.join(html)