nanowrimo 0.7

data/History.txt

@@ -0,0 +1,22 @@
+=== 0.7 / 2009-05-29
+
+* Refactored many similar methods into a Nanowrimo::Core class per a suggestion from ZenSpider.
+* Implemented a basic caching mechanism. This isn't fully implemented yet, and will be tuned in future releases.
+* Documentation added to all classes.
+
+=== 0.6 / 2009-05-25
+
+* page scraping in place for extra user data
+* not all functionality is useful for this, since profile pages have minimal data. submitted request for API changes to Nanowrimo.org crew.
+
+=== 0.5 / 2009-05-21
+
+* first major release
+* API is fully functional as a wrapper for the Nanowrimo API
+
+=== 0.1 / 2009-05-17
+
+* 1 major enhancement
+
+  * Birthday!
+

data/Manifest.txt

@@ -0,0 +1,27 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/nanowrimo.rb
+lib/nanowrimo/cache.rb
+lib/nanowrimo/core.rb
+lib/nanowrimo/genre.rb
+lib/nanowrimo/region.rb
+lib/nanowrimo/site.rb
+lib/nanowrimo/user.rb
+test/test_cache.rb
+test/test_core.rb
+test/test_genre.rb
+test/test_nanowrimo.rb
+test/test_region.rb
+test/test_site.rb
+test/test_user.rb
+test/fixtures/genre_wc.xml
+test/fixtures/genre_wc_history.xml
+test/fixtures/region_wc.xml
+test/fixtures/region_wc_history.xml
+test/fixtures/site_wc.xml
+test/fixtures/site_wc_history.xml
+test/fixtures/user_page.htm
+test/fixtures/user_wc.xml
+test/fixtures/user_wc_history.xml

data/README.txt

@@ -0,0 +1,82 @@
+= nanowrimo
+
+* http://nanowrimo.rubyforge.org
+* http://github.com/illuminerdi/nanowrimo
+* http://www.nanowrimo.org
+
+== DESCRIPTION:
+
+A simple API wrapper for Nanowrimo.org. Nanowrimo Word Count API documentation here:
+http://www.nanowrimo.org/eng/wordcount_api
+
+== FEATURES/PROBLEMS:
+
+Features:
+* Simple! Clean! Well-tested!
+* Easy to roll into a Rails application (that's next)
+* Separate APIs for Users, Site, Regions, and Genres
+* Page scraping place for basic user data from the profile page
+* Caches data to avoid November bandwidth issues
+
+Problems:
+* The Genres API on Nanowrimo.org is a little broken right now, so there's not much data to be loaded.
+* Page scraping is dumb and costly. And the data I get is minimal. Submitted request for new API features with Nanowrimo.org crew.
+* Caching is still fairly immature in this package. Need to tune it further before November hits.
+
+== SYNOPSIS:
+
+  >> me = Nanowrimo::User.new(240659)
+  => #<Nanowrimo::User:0x105b904 @uid=240659>
+  >> me.load
+  => ["uid", "uname", "user_wordcount"]
+  >> me.user_wordcount
+  => "55415"
+  >> me.winner?
+  => true
+  # YAY!
+  
+  # Want to get a list of your writing buddies?
+  >> me.parse_profile
+  >> me.buddies
+  => ["94450", "208549", "236224", "244939", "301080", "405136", "139709", "229531", "240149", "245095", "309620"]
+
+  # Want an array of day-by-day progress for yourself?
+  >> me.load_history
+
+  # Want an array of day-by-day progress for your region?
+  >> my_region = Nanowrimo::Region.new(84)
+  >> my_region.load_history
+
+== REQUIREMENTS:
+
+* ruby 1.8.6
+* mechanize 0.9.2
+
+== INSTALL:
+
+* sudo gem install nanowrimo
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2009 Joshua Clingenpeel
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,13 @@
+# -*- ruby -*-
+
+$: << 'lib'
+require 'rubygems'
+require 'hoe'
+require './lib/nanowrimo.rb'
+
+Hoe.new('nanowrimo', Nanowrimo::VERSION) do |p|
+  # p.rubyforge_name = 'nanowrimox' # if different than lowercase project name
+  p.developer('Joshua Clingenpeel', 'joshua.clingenpeel@gmail.com')
+end
+
+# vim: syntax=Ruby

data/lib/nanowrimo.rb

@@ -0,0 +1,76 @@
+#! /usr/bin/env ruby -w
+
+# Nanowrimo is an API Wrapper for the Nanowrimo.org WCAPI.
+# In its current implementation it manages all data brought down from the WCAPI.
+#
+# Author:: Joshua Clingenpeel (joshua.clingenpeel@gmail.com)
+# Copyright:: Copyright (c) 2009 Joshua Clingenpeel
+# License:: MIT License
+
+require 'rubygems'
+require 'mechanize'
+require 'open-uri'
+require 'nanowrimo/core'
+require 'nanowrimo/user'
+require 'nanowrimo/site'
+require 'nanowrimo/region'
+require 'nanowrimo/genre'
+require 'nanowrimo/cache'
+
+# This module handles caching, a few constants, and the all-important XML parsing method
+# for both current data and historical data from the WCAPI. It should be generic enough to
+# never have to be touched again, but keep your fingers crossed anyway.
+
+module Nanowrimo
+  # Current API version
+  VERSION = '0.7'
+  # Current static root WCAPI uri
+  API_URI = 'http://www.nanowrimo.org/wordcount_api'
+  # Current individual user word count goal. For fun!
+  GOAL = 50_000
+  Nanowrimo::Cache.load_cache if Nanowrimo::Cache.cache_data == {}
+
+  # Pull requested data from cache or from the WCAPI
+  def self.parse(path, key, attribs)
+    result = data_from_cache(path, key) ||
+      data_from_internets(path, key, attribs)
+  end
+
+  # Finds the data in the cache and returns it, or nil, taking into account age of cache data.
+  def self.data_from_cache(path, key)
+    type = path.split('/').first
+    Nanowrimo::Cache.find_data(type, key)
+  end
+
+  # Parses XML from the WCAPI and returns an array of hashes with the data. Caches it, too.
+  def self.data_from_internets(path, key, attribs)
+    type = path.split('/').first
+    uri = "#{API_URI}/#{type}"
+    uri = "#{uri}/#{key}" unless key.nil?
+    result = []
+    begin
+      timeout(2) {
+        doc = Nokogiri::XML(open(uri))
+        doc.xpath(path).each {|n|
+          node = {}
+          attribs.each {|d|
+            node[d.intern] = n.at(d).content
+          }
+          result << node
+        }
+      }
+    rescue Timeout::Error
+      throw NanowrimoError, "Timed out attempting to connect to Nanowrimo.org"
+    end
+    key ||= type # kinda hackish, but for the site stats it's needed
+    Nanowrimo::Cache.add_to_cache("#{type}","#{key}",result)
+    result
+  end
+
+  at_exit {
+    Nanowrimo::Cache.save_cache_to_disk
+  }
+end
+
+# Generic error class
+class NanowrimoError < StandardError; end

data/lib/nanowrimo/cache.rb

@@ -0,0 +1,52 @@
+#! /usr/bin/env ruby -w
+
+require 'thread'
+require 'yaml'
+
+module Nanowrimo
+  # Handles caching of WCAPI data
+  class Cache
+    CACHE_FILE = './nano_cache'
+    # 24 hours in seconds, defines when cached data expires.
+    DEFAULT_MAX_CACHE_AGE = (24*60*60)
+    @@cache_data = {}
+    @@cache_mutex = Mutex.new
+    def self.cache_data
+      @@cache_data
+    end
+    def self.cache_mutex
+      @@cache_mutex
+    end
+
+    # Load the cached data into memory from disk.
+    def self.load_cache
+      if File.exist?(CACHE_FILE)
+        @@cache_data = YAML::load(File.read(CACHE_FILE))
+      end
+    end
+
+    def self.find_data(type, key)
+      @@cache_mutex.synchronize {
+        return nil unless @@cache_data["#{type}"]
+        return nil unless @@cache_data["#{type}"]["#{key}"]
+        if Time.now - @@cache_data["#{type}"]["#{key}"][:created_at] < DEFAULT_MAX_CACHE_AGE
+          @@cache_data["#{type}"]["#{key}"][:data]
+        end
+      }
+    end
+
+    # For when the cache needs to be not in memory anymore.
+    def self.save_cache_to_disk
+      File.open(CACHE_FILE, 'w') do |out|
+        YAML.dump(@@cache_data, out)
+      end
+    end
+
+    # Receives data that needs to be added to the cache
+    def self.add_to_cache type, key, data=[]
+      @@cache_mutex.synchronize{
+        @@cache_data["#{type}"] = {"#{key}" => Hash[:data, data, :created_at, Time.now]}
+      }
+    end
+  end
+end

data/lib/nanowrimo/core.rb

@@ -0,0 +1,19 @@
+#! /usr/bin/env ruby -w
+
+module Nanowrimo
+  # Core load methods
+  class Core
+    # Returns the values for all attributes for a given WCAPI type
+    def load
+      attribs = Nanowrimo.parse(load_field,id,self.class::FIELDS).first
+      self.class::FIELDS.each do |attrib|
+        self.send(:"#{attrib}=", attribs[attrib.intern])
+      end
+    end
+
+    # Returns the values for all attributes for a given WCAPI type's history
+    def load_history
+      self.history = Nanowrimo.parse(load_history_field,id,self.class::HISTORY_FIELDS)
+    end
+  end
+end

data/lib/nanowrimo/genre.rb

@@ -0,0 +1,32 @@
+#! /usr/bin/env ruby -w
+
+module Nanowrimo
+  # Handles Nanowrimo Genre data.
+  class Genre < Core
+    # fields expected from the main Genre WCAPI
+    FIELDS = %w[gid gname genre_wordcount max min stddev average count]
+    # fields expected from the Genre history WCAPI
+    HISTORY_FIELDS = %w[wc wcdate max min stddev average count]
+    attr_accessor(*FIELDS)
+    attr_accessor :history
+    # creates a new Region object
+    def initialize(gid)
+      @gid = gid
+    end
+
+    # converts the WCAPI unique identifier for this type into a Nanowrimo::Core-friendly 'id'
+    def id
+      @gid
+    end
+
+    # converts the WCAPI path for this type into something Nanowrimo::Core-friendly
+    def load_field
+      'wcgenre'
+    end
+
+    # converts the WCAPI history path for this type into something Nanowrimo::Core-friendly
+    def load_history_field
+      'wcgenrehist/wordcounts/wcentry'
+    end
+  end
+end

data/lib/nanowrimo/region.rb

@@ -0,0 +1,32 @@
+#! /usr/bin/env ruby -w
+
+module Nanowrimo
+  # Handles Nanowrimo Region data.
+  class Region < Core
+    # fields expected from the main Region WCAPI
+    FIELDS = %w[rid rname region_wordcount max min stddev average count donations numdonors]
+    # fields expected from the Region history WCAPI
+    HISTORY_FIELDS = %w[wc wcdate max min stddev average count donations donors]
+    attr_accessor(*FIELDS)
+    attr_accessor :history
+    # creates a new Region object
+    def initialize(rid)
+      @rid = rid
+    end
+    
+    # converts the WCAPI unique identifier for this type into a Nanowrimo::Core-friendly 'id'
+    def id
+      @rid
+    end
+
+    # converts the WCAPI path for this type into something Nanowrimo::Core-friendly
+    def load_field
+      'wcregion'
+    end
+
+    # converts the WCAPI history path for this type into something Nanowrimo::Core-friendly
+    def load_history_field
+      'wcregionhist/wordcounts/wcentry'
+    end
+  end
+end

data/lib/nanowrimo/site.rb

@@ -0,0 +1,27 @@
+#! /usr/bin/env ruby -w
+
+module Nanowrimo
+  # Handles Nanowrimo Site data.
+  class Site < Core
+    # fields expected from the main Site WCAPI
+    FIELDS = %w[site_wordcount max min stddev average count]
+    # fields expected from the Site history WCAPI
+    HISTORY_FIELDS = %w[wc wcdate max min stddev average count]
+    attr_accessor(*FIELDS)
+    attr_accessor :history
+    # converts the WCAPI unique identifier for this type into a Nanowrimo::Core-friendly 'id'
+    def id
+      nil
+    end
+
+    # converts the WCAPI path for this type into something Nanowrimo::Core-friendly
+    def load_field
+      'wcstatssummary'
+    end
+
+    # converts the WCAPI history path for this type into something Nanowrimo::Core-friendly
+    def load_history_field
+      'wcstats/wordcounts/wcentry'
+    end
+  end
+end

data/lib/nanowrimo/user.rb

@@ -0,0 +1,69 @@
+#! /usr/bin/env ruby -w
+
+module Nanowrimo
+  # Handles Nanowrimo User data.
+  class User < Core
+    # fields expected from the main User WCAPI
+    FIELDS = %w[uid uname user_wordcount]
+    # history fields expected from the User History WCAPI
+    HISTORY_FIELDS = %w[wc wcdate]
+    # fields needed to store data ripped from a user's profile page
+    USER_FIELDS = %w[rid novel genre buddies]
+    # profile page base URI
+    PROFILE_URI = "http://www.nanowrimo.org/eng/user"
+
+    attr_accessor(*FIELDS)
+    attr_accessor(*USER_FIELDS)
+    attr_accessor :history, :profile_data
+    # creates a new User object
+    def initialize uid
+      @uid = uid
+      @novel = {}
+      @genre = {}
+      @buddies = []
+    end
+
+    # converts the WCAPI 'uid' into a Nanowrimo::Core-friendly 'id'
+    def id
+      @uid
+    end
+
+    # converts the WCAPI path for this type into something Nanowrimo::Core-friendly
+    def load_field
+      'wc'
+    end
+
+    # converts the WCAPI history path for this type into something Nanowrimo::Core-friendly
+    def load_history_field
+      'wchistory/wordcounts/wcentry'
+    end
+
+    # Determines if the User's current wordcount meets the month's goal.
+    def winner?
+      self.user_wordcount.to_i >= Nanowrimo::GOAL
+    end
+
+    # Method to pull down a WWW::Mechanize::Page instance of the User's profile page
+    def load_profile_data
+      # mechanize might be overkill, but at some point if they don't add more to the API
+      # I'll have to dig deeper behind the site's authentication layer in order to pull out
+      # some needed data.
+      agent = WWW::Mechanize.new
+      @profile_data = agent.get("#{PROFILE_URI}/#{@uid}")
+    end
+
+    # Parses the profile page data pulling out extra information for the User.
+    def parse_profile
+      load_profile_data
+      # get the buddies
+      @buddies = @profile_data.search("div[@class='buddies']//a").map{|b| b['href'].split('/').last; }
+      @buddies.reject!{|b| b.to_i == 0}
+      # title and genre are in the same element
+      titlegenre = @profile_data.search("div[@class='titlegenre']").text.split("Genre:")
+      @genre[:name] = titlegenre.last.strip
+      @novel[:title] = titlegenre.first.gsub('Novel:','').strip
+      # finally, the region is annoying to grab
+      @rid = @profile_data.search("div[@class='infoleft']//a").first['href'].split('/').last
+    end
+  end
+end