Extending the Visit Framework

Step One - Create your model

I added the following in my main model.py:

class VisitIP(SQLObject):

      class sqlmeta:
          table = 'visit_ip' # SQL object default naming is visitor_i_p, not pretty

      visit = ForeignKey('TG_Visit')
      ip_address = StringCol(length=20)

Create the table in your database with tg-admin sql create --class=VisitIP.

Step Two - Add Plugin Logic

I made a new module in my project named visit_plugin.py. Its contents are as follows:

import cherrypy
  from turbogears import visit
  from model import VisitIP

  def ip_tracking_is_on():
      "Returns True if ip tracking is properly enabled, False otherwise."
      return cherrypy.config.get('visit.on', False) and
      cherrypy.config.get('visit.ip_tracking.on', False)

  #Interface for the TurboGears extension
  def start_extension():
      if not ip_tracking_is_on():
          return
      cherrypy.log( "Visit ip tracker starting" )

      #Register the plugin for the Visit Tracking framework
      visit.enable_visit_plugin( IPVisitPlugin() )

  def shutdown_extension():
      if not ip_tracking_is_on():
          return
      cherrypy.log( "Visit ip tracker shutting down" )

  class IPVisitPlugin(object):

      def __init__(self):
          cherrypy.log("IPVisitPlugin extension starting")

      def record_request(self, visit_id):
          # This method gets called on every single visit, so if you
          # want to record something every time they make a request, this
          # is the place to do it.
          pass

      def new_visit(self, visit_id):
          # This method gets called the first time the visit is started.
          # I think IP tracking makes sense in here.
          v = visit.TG_Visit.get(visit_id)

          # add a new visit ip object to the database
          VisitIP(visit=v, ip_address=cherrypy.request.remoteAddr)

The start_extension and shutdown_extension functions are called by turbogears when starting up and shutting down (imagine that). The key is this process is the visit.enable_visit_plugin call, which registers your plugin with the visit framework.

Step Three: Tie in the extension in setup.py

In your project's setup.py, add an entry_points parameter to the setup() function:

setup(
      # Lots of stuff snipped
      test_suite = 'nose.collector'
      # begin new
      , entry_points="""
      [turbogears.extensions]
      my_visit_extension = ip_plugin.visit_plugin
      """
      # end new
      )

My project name is ip_plugin, so you will need to edit this a bit make this point to the right module in your project. (Aside: I'm not sure that [turbogears.extensions] is the right place to put this entry point. If there is a better area to place this in, please edit as appropriate. But, the above does work).

Step Four: Update Config File

Add a configuration variable so that the tracking can be turned on and off. Somewhere in config.py, add the line

visit.ip_tracking.on=True

Step Five: Update egg info

This step just re-generates the egg information for your project so that the extension actually gets called at runtime. From the command line, at the root level of your project run 'python setup.py egg_info'.

Conclusion

That's it. Fire up your project and you should be tracking ip activity just like the NSA.

It may be possible to register the plugin (via visit.enable_visit_plugin()) some other way (perhaps in setup.py?). If you believe there is a more canonical way that things like this should be done, please go ahead and make the edit.