taylorbarstow-nytimes-articles 0.2.1

data/lib/nytimes_articles/base.rb

@@ -0,0 +1,118 @@
+require 'open-uri'
+require 'json'
+require 'htmlentities'
+
+module Nytimes
+	module Articles
+		class Base
+			API_SERVER = 'api.nytimes.com'
+			API_VERSION = 'v1'
+			API_NAME = 'article'
+			API_BASE = "/svc/search/#{API_VERSION}/#{API_NAME}"
+
+			@@api_key = nil
+			@@debug = false
+
+			##
+			# Set the API key used for operations. This needs to be called before any requests against the API. To obtain an API key, go to http://developer.nytimes.com/
+			def self.api_key=(key)
+				@@api_key = key
+			end
+			
+			def self.debug=(flag)
+				@@debug = flag
+			end
+
+			##
+			# Returns the current value of the API Key
+			def self.api_key
+				@@api_key
+			end
+
+			##
+			# Builds a request URI to call the API server
+			def self.build_request_url(params)
+				URI::HTTP.build :host => API_SERVER,
+				:path => API_BASE,
+				:query => params.map {|k,v| "#{URI.escape(k)}=#{URI.escape(v)}"}.join('&')
+			end
+			
+			def self.text_field(value)
+				return nil if value.nil?
+				coder = HTMLEntities.new
+				coder.decode(value)
+			end
+			
+			def self.integer_field(value)
+				return nil if value.nil?
+				value.to_i
+			end
+			
+			def self.date_field(value)
+				return nil unless value =~ /^\d{8}$/
+				Date.strptime(value, "%Y%m%d")
+			end
+			
+			def self.boolean_field(value)
+				case value
+				when nil
+					false
+				when TrueClass
+					true
+				when FalseClass
+					false
+				when 'Y'
+					true
+				when 'N'
+					false
+				else
+					false
+				end
+			end
+
+			def self.invoke(params={})
+				begin
+					if @@api_key.nil?
+						raise AuthenticationError, "You must initialize the API key before you run any API queries"
+					end
+
+					full_params = params.merge 'api-key' => @@api_key
+					uri = build_request_url(full_params)	
+					
+					puts "REQUEST: #{uri}" if @@debug
+						
+					reply = uri.read
+					parsed_reply = JSON.parse reply
+
+					if parsed_reply.nil?
+						raise BadResponseError, "Empty reply returned from API"
+					end
+
+					#case parsed_reply['status']
+					# FIXME
+					#end
+
+					parsed_reply
+				rescue OpenURI::HTTPError => e
+					# FIXME: Return message from body?
+					case e.message
+					when /^400/
+						raise BadRequestError
+					when /^403/
+						raise AuthenticationError
+					when /^404/
+						return nil
+					when /^500/
+						raise ServerError
+					else
+						raise ConnectionError
+					end
+
+					raise "Error connecting to URL #{uri} #{e}"
+				rescue JSON::ParserError => e
+					raise BadResponseError, "Invalid JSON returned from API:\n#{reply}"
+				end
+			end
+		end
+	end
+end

data/lib/nytimes_articles/exceptions.rb

@@ -0,0 +1,38 @@
+module Nytimes
+	module Articles
+		##
+		# The generic Error class from which all other Errors are derived.
+		class Error < ::RuntimeError
+		end
+		
+		##
+		# This error is thrown if there are problems authenticating your API key.
+		class AuthenticationError < Error
+		end
+		
+		##
+		# This error is thrown if the request was not parsable by the API server.
+		class BadRequestError < Error
+		end
+		
+		##
+		# This error is thrown if the response from the API server is not parsable.
+		class BadResponseError < Error
+		end
+		
+		##
+		# This error is thrown if there is an error connecting to the API server.
+		class ServerError < Error
+		end
+		
+		##
+		# This error is thrown if there is a timeout connecting to the server (to be implemented).
+		class TimeoutError < Error
+		end
+		
+		##
+		# This error is thrown for general connection errors to the API server.
+		class ConnectionError < Error
+		end
+	end
+end

data/lib/nytimes_articles/facet.rb

@@ -0,0 +1,128 @@
+module Nytimes
+	module Articles
+		
+		##
+		# This class represents a Facet used in the ArticleSearch API. Facets can be used to both search for matching articles (see Article#search) and
+		# are also returned as article and search metadata. Facets are made up of 3 parts:
+		# * <tt>facet_type</tt> - a string; see Article#search for a list of facet types
+		# * <tt>term</tt> - a string as well
+		# * <tt>count</tt> - Facets returned as search metadata (via the <tt>:facets</tt> parameter to Article#search) also include a non-nil count of matching articles for that facet
+		class Facet
+			##
+			# The term for the facet
+			attr_reader :term
+			
+			##
+			# The number of times this facet has appeared in the search results (note: this only applies for facets returned in the facets header on an Article#search)
+			attr_reader :count
+			
+			##
+			# The facet type
+			attr_reader :facet_type
+			
+			# Facet name constants
+			CLASSIFIERS = 'classifiers_facet'
+			COLUMN = 'column_facet'
+			DATE = 'date'
+			DAY_OF_WEEK = 'day_of_week_facet'
+			DESCRIPTION = 'des_facet'
+			DESK = 'desk_facet'
+			GEO = 'geo_facet'
+			MATERIAL_TYPE = 'material_type_facet'
+			ORGANIZATION = 'org_facet'
+			PAGE = 'page_facet'
+			PERSON = 'per_facet'
+			PUB_DAY = 'publication_day'
+			PUB_MONTH = 'publication_month'
+			PUB_YEAR = 'publication_year'
+			SECTION_PAGE = 'section_page_facet'
+			SOURCE = 'source_facet'
+			WORKS_MENTIONED = 'works_mentioned_facet'
+			
+			# Facets of content formatted for nytimes.com
+			NYTD_BYLINE = 'nytd_byline'
+			NYTD_DESCRIPTION = 'nytd_des_facet'
+			NYTD_GEO = 'nytd_geo_facet'
+			NYTD_ORGANIZATION = 'nytd_org_facet'
+			NYTD_PERSON = 'nytd_per_facet'
+			NYTD_SECTION = 'nytd_section_facet'
+			NYTD_WORKS_MENTIONED = 'nytd_works_mentioned_facet'
+			
+			# The default 5 facets to return
+		  DEFAULT_RETURN_FACETS = [DESCRIPTION, GEO, ORGANIZATION, PERSON, DESK]
+		
+			ALL_FACETS = [CLASSIFIERS, COLUMN, DATE, DAY_OF_WEEK, DESCRIPTION, DESK, GEO, MATERIAL_TYPE, ORGANIZATION, PAGE, PERSON, PUB_DAY,
+														PUB_MONTH, PUB_YEAR, SECTION_PAGE, SOURCE, WORKS_MENTIONED, NYTD_BYLINE, NYTD_DESCRIPTION, NYTD_GEO,
+														NYTD_ORGANIZATION, NYTD_PERSON, NYTD_SECTION, NYTD_WORKS_MENTIONED]
+			
+			##
+			# Initializes the facet. There is seldom a reason for you to call this.
+			def initialize(facet_type, term, count)
+				@facet_type = facet_type
+				@term = term
+				@count = count
+			end
+			
+			##
+			# Takes a symbol name and subs it to a string constant
+			def self.symbol_name(facet)
+				case facet
+				when String
+					return facet
+				when Facet
+					return facet.facet_type
+				when Symbol
+					# fall through
+				else
+					raise ArgumentError, "Unsupported type to Facet#symbol_to_api_name"
+				end
+				
+				case facet
+				when :geography
+					GEO
+				when :org, :orgs
+					ORGANIZATION
+				when :people
+					PERSON
+				when :nytd_geography
+					NYTD_GEO
+				when :nytd_org, :nytd_orgs
+					NYTD_ORGANIZATION
+				when :nytd_people
+					NYTD_PERSON
+				else
+					name = facet.to_s.upcase
+					
+					if const_defined?(name)
+						const_get(name)
+					elsif name =~ /S$/ && const_defined?(name.gsub(/S$/, ''))
+						const_get(name.gsub(/S$/, ''))
+					else
+						raise ArgumentError, "Unable to find a matching facet key for symbol :#{facet}"
+					end
+				end
+			end
+			
+			##
+			# Initializes a selection of Facet objects returned from the API. Used for marshaling Facets in articles and metadata from search results
+			# (Note: some facets are returned as scalar values)
+			def self.init_from_api(api_hash)
+				return nil if api_hash.nil?
+				
+				unless api_hash.is_a? Hash
+					raise ArgumentError, "expecting a Hash only"
+				else
+					return nil if api_hash.empty?
+				end
+				
+				out = {}
+				
+				api_hash.each_pair do |k,v|
+					out[k] = v.map {|f| Facet.new(k, f['term'], f['count'])}
+				end
+				
+				out
+			end
+		end
+	end
+end

data/lib/nytimes_articles/query.rb

@@ -0,0 +1,28 @@
+require 'digest'
+
+module Nytimes
+	module Articles
+	  ##
+	  # The Query class represents a single query to the Article Search API.  Supports
+	  # all of the named parameters to Article.search as accessor methods.
+	  #
+	  class Query
+      FIELDS = [:only_facets, :except_facets, :begin_date, :end_date, :since, 
+	              :before, :fee, :has_thumbnail, :facets, :fields, :query, :offset] + Article::TEXT_FIELDS.map(&:to_sym)
+      FIELDS.each {|f| attr_accessor f}
+      
+      # Produce a hash which uniquely identifies this query
+      def hash
+        strs = FIELDS.collect {|f| "#{f}:#{send(f).inspect}"}
+        Digest::SHA256.hexdigest(strs.join(' '))
+      end
+      
+      # Perform this query.  Returns result of Article.search
+      def perform
+        params = {}
+        FIELDS.each {|f| params[f] = send(f) unless send(f).nil?}
+        Article.search(params)
+      end
+    end
+  end
+end

data/lib/nytimes_articles/result_set.rb

@@ -0,0 +1,66 @@
+require 'rubygems'
+require 'forwardable'
+
+module Nytimes
+	module Articles
+		##
+		# The ResultSet is returned by Article#search and contains an array of up to 10 results out of the total matches. For your convenience, this
+		# object provides a selection of array methods on the underlying collection of articles.
+		class ResultSet < Base
+			extend Forwardable
+
+			##
+			# The offset of the result_set. Note that this is essentially the ordinal position of the batch among all results. First 10 results are offset
+			# 0, the next 10 are offset 1, etc.
+			attr_reader :offset
+			
+			##
+			# The total results that matched the query.
+			attr_reader :total_results
+			
+			##
+			# The results array of articles returned. Note that if you call Articles#find with :fields => :none, this will return nil even if 
+			# there are matching results.
+			attr_reader :results
+			
+			##
+			# If you have specified a list of <tt>:facets</tt> for Article#search, they will be returned in a hash keyed by the facet name here.
+			attr_reader :facets
+			
+			BATCH_SIZE = 10
+			
+			def_delegators :@results, :&, :*, :+, :-, :[], :at, :collect, :compact, :each, :each_index, :empty?, :fetch, :first, :include?, :index, :last, :length, :map, :nitems, :reject, :reverse, :reverse_each, :rindex, :select, :size, :slice  
+			
+			def initialize(params)
+				@offset = params[:offset]
+				@total_results = params[:total_results]
+				@results = params[:results]
+				@facets = params[:facets]
+			end
+			
+			##
+			# For your convenience, the page_number method is an alternate version of #offset that counts up from 1.
+			def page_number
+				return 0 if @total_results == 0
+				@offset + 1
+			end
+			
+			##
+			# Calculates the total number of pages in the results based on the standard batch size and total results.
+			def total_pages
+				return 0 if @total_results == 0
+				(@total_results.to_f / BATCH_SIZE).ceil
+			end
+			
+			##
+			# Used to initialize a new result_set from Article#search.
+			def self.init_from_api(api_hash)
+				self.new(:offset => integer_field(api_hash['offset']),
+								 :total_results => integer_field(api_hash['total']),
+								 :results => api_hash['results'].map {|r| Article.init_from_api(r)},
+								 :facets => Facet.init_from_api(api_hash['facets'])
+								)
+			end
+		end
+	end
+end

data/lib/nytimes_articles/thumbnail.rb

@@ -0,0 +1,30 @@
+module Nytimes
+	module Articles
+		##
+		# If requested in <tt>:fields</tt> for an article search, some articles are returned with a matching thumbnail image. The several thumbnail
+		# fields are collected together into a single Thumbnail instance for your convenience. 
+		class Thumbnail
+			attr_reader :url, :width, :height
+			
+			def initialize(url, width, height)
+				@url = url
+				@width = width
+				@height = height
+			end
+			
+			def self.init_from_api(api_hash)
+				return nil unless !api_hash.nil? && api_hash['small_image_url']
+				
+				unless api_hash['small_image_width'].nil?
+					width = api_hash['small_image_width'].to_i
+				end
+				
+				unless api_hash['small_image_height'].nil?
+					height = api_hash['small_image_height'].to_i
+				end
+				
+				new(api_hash['small_image_url'], width, height)
+			end
+		end
+	end
+end

data/test/nytimes/articles/test_article.rb

@@ -0,0 +1,640 @@
+require File.dirname(__FILE__) + '/../../test_helper.rb'
+
+ARTICLE_API_HASH = {"page_facet"=>"8", "lead_paragraph"=>"", "classifiers_facet"=>["Top/News/Business", "Top/Classifieds/Job Market/Job Categories/Banking, Finance and Insurance", "Top/News/Business/Markets"], "title"=>"Wall St. Treads Water as It Waits on Washington", "nytd_title"=>"Wall St. Treads Water as It Waits on Washington", "byline"=>"By JACK HEALY", "body"=>"Wall Street held its breath on Monday as it awaited details on a banking bailout from Washington. Investors had expected to start the week with an announcement from the Treasury Department outlining its latest plans to stabilize the financial system. But the Obama administration delayed releasing the details until at least Tuesday to keep the focus", "material_type_facet"=>["News"], "url"=>"http://www.nytimes.com/2009/02/10/business/10markets.html", "publication_month"=>"02", "date"=>"20090210", "publication_year"=>"2009", "nytd_section_facet"=>["Business"], "source_facet"=>"The New York Times", "desk_facet"=>"Business", "publication_day"=>"10", "des_facet"=>["STOCKS AND BONDS"], "day_of_week_facet"=>"Tuesday"}
+
+ARTICLE_API_HASH2 = {"page_facet"=>"29", "lead_paragraph"=>"", "geo_facet"=>["WALL STREET (NYC)"], "small_image_width"=>"75", "classifiers_facet"=>["Top/News/New York and Region", "Top/Classifieds/Job Market/Job Categories/Education", "Top/Features/Travel/Guides/Destinations/North America", "Top/Classifieds/Job Market/Job Categories/Banking, Finance and Insurance", "Top/Features/Travel/Guides/Destinations/North America/United States/New York", "Top/Features/Travel/Guides/Destinations/North America/United States", "Top/News/Education"], "title"=>"OUR TOWNS; As Pipeline to Wall Street Narrows, Princeton Students Adjust Sights", "nytd_title"=>"As Pipeline to Wall Street Narrows, Princeton Students Adjust Sights", "byline"=>"By PETER APPLEBOME", "body"=>"Princeton, N.J. There must be a screenplay in the fabulous Schoppe twins, Christine and Jennifer, Princeton University juniors from Houston. They had the same G.P.A. and SATs in high school, where they became Gold Award Girl Scouts , sort of the female version of Eagle Scouts. They live together and take all the same courses, wear identical necklac", "material_type_facet"=>["News"], "url"=>"http://www.nytimes.com/2009/02/08/nyregion/08towns.html", "publication_month"=>"02", "small_image_height"=>"75", "date"=>"20090208", "column_facet"=>"Our Towns", "small_image"=>"Y", "publication_year"=>"2009", "nytd_section_facet"=>["New York and Region", "Education"], "source_facet"=>"The New York Times", "org_facet"=>["PRINCETON UNIVERSITY"], "desk_facet"=>"New York Region", "publication_day"=>"08", "small_image_url"=>"http://graphics8.nytimes.com/images/2009/02/08/nyregion/08towns.751.jpg", "des_facet"=>["EDUCATION AND SCHOOLS", "BANKS AND BANKING"], "day_of_week_facet"=>"Sunday"}
+
+class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
+	include Nytimes::Articles
+
+	def setup
+		init_test_key
+		Article.stubs(:parse_reply)
+	end
+
+	context "Article.search" do
+		should "accept a String for the first argument that is passed through to the query in the API" do
+			Article.expects(:invoke).with(has_entry("query", "FOO BAR"))
+			Article.search "FOO BAR"
+		end
+
+		should "accept a Hash for the first argument" do
+			Article.expects(:invoke).with(has_entry("query", "FOO BAR"))
+			Article.search :query => 'FOO BAR', :page => 2
+		end
+
+		context "date ranges" do
+			should "pass a string argument to begin_date straight through" do
+				date = "20081212"
+				Article.expects(:invoke).with(has_entry("begin_date", date))
+				Article.search :begin_date => date
+			end
+
+			should "convert begin_date from a Date or Time to YYYYMMDD format" do
+				time = Time.now
+				Article.expects(:invoke).with(has_entry("begin_date", time.strftime("%Y%m%d")))
+				Article.search :begin_date => time
+			end
+
+			should "pass a string argument to end_date straight through" do
+				date = "20081212"
+				Article.expects(:invoke).with(has_entry("end_date", date))
+				Article.search :end_date => date
+			end
+
+			should "convert end_date from a Date or Time to YYYYMMDD format" do
+				time = Time.now
+				Article.expects(:invoke).with(has_entry("end_date", time.strftime("%Y%m%d")))
+				Article.search :end_date => time
+			end
+
+			should "raise an ArgumentError if the begin_date is NOT a string and does not respond_to strftime" do
+				assert_raise(ArgumentError) { Article.search :begin_date => 23 }
+			end
+
+			should "raise an ArgumentError if the end_date is NOT a string and does not respond_to strftime" do
+				assert_raise(ArgumentError) { Article.search :end_date => 23 }
+			end
+			
+			context ":before" do
+				should "send the :before value through as a end_date" do
+					t = Time.now
+					Article.expects(:invoke).with(has_entry('end_date', t.strftime("%Y%m%d")))
+					Article.search :before => t
+				end
+				
+				should "not send through :before as an argument to the API" do
+					t = Time.now
+					Article.expects(:invoke).with(Not(has_key('before')))
+					Article.search :before => t
+				end
+				
+				should "raise an ArgumentError if the before_date is NOT a string and does not respond_to strftime" do
+					assert_raise(ArgumentError) { Article.search :before => 23 }
+				end
+				
+				should "add a begin_date in 1980 if no :since or :begin_date argument is provided" do
+					Article.expects(:invoke).with(has_entry('begin_date', Article::EARLIEST_BEGIN_DATE))
+					Article.search :before => Time.now
+				end
+				
+				should "not automatically add a begin_date is there is a :since argument" do
+					since = Time.now - 12000
+					Article.expects(:invoke).with(has_entry('begin_date', since.strftime("%Y%m%d")))
+					Article.search :before => Time.now, :since => since
+				end
+				
+				should "not automatically add a begin_date if there is a :begin_date argument already" do
+					since = Time.now - 12000
+					Article.expects(:invoke).with(has_entry('begin_date', since.strftime("%Y%m%d")))
+					Article.search :before => Time.now, :begin_date => since
+				end
+				
+				should "raise an ArgumentError if there is also an :end_date argument" do
+					assert_raise(ArgumentError) { Article.search :before => Time.now, :end_date => Time.now }
+				end
+			end
+
+			context ":since" do
+				should "send the :since value through as a begin_date" do
+					t = Time.now - 1200
+					Article.expects(:invoke).with(has_entry('begin_date', t.strftime("%Y%m%d")))
+					Article.search :since => t
+				end
+				
+				should "not send through :since as an argument to the API" do
+					t = Time.now
+					Article.expects(:invoke).with(Not(has_key('since')))
+					Article.search :since => t
+				end
+				
+				should "raise an ArgumentError if the before_date is NOT a string and does not respond_to strftime" do
+					assert_raise(ArgumentError) { Article.search :since => 23 }
+				end
+				
+				# This is to fix an error where the begin and end date are the same
+				should "add a end_date of tomorrow if no :before or :end_date argument is provided" do
+					Article.expects(:invoke).with(has_entry('end_date', (Date.today + 1).strftime("%Y%m%d")))
+					Article.search :since => Date.today
+				end
+				
+				should "not automatically add a end_date is there is a :before argument" do
+					since = '19990101'
+					Article.expects(:invoke).with(has_entry('end_date', '20030101'))
+					Article.search :before => '20030101', :since => since
+				end
+				
+				should "not automatically add a end_date if there is a :end_date argument already" do
+					since = '19990101'
+					Article.expects(:invoke).with(has_entry('end_date', '20030101'))
+					Article.search :end_date => '20030101', :since => since
+				end
+				
+				should "raise an ArgumentError if there is also an :begin_date argument" do
+					assert_raise(ArgumentError) { Article.search :since => Time.now, :begin_date => Time.now }
+				end
+			end			
+		end
+
+		context "facets" do
+			should "accept a single string" do
+				Article.expects(:invoke).with(has_entry("facets", Facet::DATE))
+				Article.search "FOO BAR", :facets => Facet::DATE
+			end
+
+			should "accept an array of strings" do
+				Article.expects(:invoke).with(has_entry("facets", [Facet::DATE, Facet::GEO].join(',')))
+				Article.search "FOO BAR", :facets => [Facet::DATE, Facet::GEO]
+			end
+		end
+		
+		context "only_facets" do
+			should "accept a String" do
+				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA]"))
+				Article.search :only_facets => "#{Facet::GEO}:[CALIFORNIA]"
+			end
+			
+			should "accept a single hash value Facet string to a term" do
+				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA]"))
+				Article.search :only_facets => {Facet::GEO => 'CALIFORNIA'}
+			end
+			
+			should "accept an Facet string hashed to an array terms" do
+				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA] #{Facet::GEO}:[GREAT BRITAIN]"))
+				Article.search :only_facets => {Facet::GEO => ['CALIFORNIA', 'GREAT BRITAIN']}
+			end
+			
+			should "accept a single Facet object" do
+				f = Facet.new(Facet::GEO, 'CALIFORNIA', 2394)
+				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA]"))
+				Article.search :only_facets => f
+			end
+			
+			should "accept an array of Facet objects" do
+				f = Facet.new(Facet::GEO, 'CALIFORNIA', 2394)
+				f2 = Facet.new(Facet::NYTD_ORGANIZATION, 'University Of California', 12)
+				
+				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA] #{Facet::NYTD_ORGANIZATION}:[University Of California]"))
+				Article.search :only_facets => [f, f2]
+			end
+			
+			should "merge multiple Facets objects in the array of the same type into one array" do
+				f = Facet.new(Facet::GEO, 'CALIFORNIA', 2394)
+				f2 = Facet.new(Facet::GEO, 'IOWA', 12)
+				
+				Article.expects(:invoke).with(has_entry("query", "#{Facet::GEO}:[CALIFORNIA] #{Facet::GEO}:[IOWA]"))
+				Article.search :only_facets => [f, f2]
+			end
+			
+			should "not stomp on an existing query string" do
+				Article.expects(:invoke).with(has_entry("query", "ice cream #{Facet::GEO}:[CALIFORNIA]"))
+				Article.search "ice cream", :only_facets => {Facet::GEO => "CALIFORNIA"}
+			end
+		end
+
+		context "except_facets" do
+			should "accept a String" do
+				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA]"))
+				Article.search :except_facets => "-#{Facet::GEO}:[CALIFORNIA]"
+			end
+			
+			should "accept a single hash value Facet string to a term" do
+				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA]"))
+				Article.search :except_facets => {Facet::GEO => 'CALIFORNIA'}
+			end
+			
+			should "accept an Facet string hashed to an array terms" do
+				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA] -#{Facet::GEO}:[GREAT BRITAIN]"))
+				Article.search :except_facets => {Facet::GEO => ['CALIFORNIA', 'GREAT BRITAIN']}
+			end
+			
+			should "accept a single Facet object" do
+				f = Facet.new(Facet::GEO, 'CALIFORNIA', 2394)
+				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA]"))
+				Article.search :except_facets => f
+			end
+			
+			should "accept an array of Facet objects" do
+				f = Facet.new(Facet::GEO, 'CALIFORNIA', 2394)
+				f2 = Facet.new(Facet::NYTD_ORGANIZATION, 'University Of California', 12)
+				
+				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA] -#{Facet::NYTD_ORGANIZATION}:[University Of California]"))
+				Article.search :except_facets => [f, f2]
+			end
+			
+			should "merge multiple Facets objects in the array of the same type into one array" do
+				f = Facet.new(Facet::GEO, 'CALIFORNIA', 2394)
+				f2 = Facet.new(Facet::GEO, 'IOWA', 12)
+				
+				Article.expects(:invoke).with(has_entry("query", "-#{Facet::GEO}:[CALIFORNIA] -#{Facet::GEO}:[IOWA]"))
+				Article.search :except_facets => [f, f2]
+			end
+			
+			should "not stomp on an existing query string" do
+				Article.expects(:invoke).with(has_entry("query", "ice cream -#{Facet::GEO}:[CALIFORNIA]"))
+				Article.search "ice cream", :except_facets => {Facet::GEO => "CALIFORNIA"}
+			end
+		end
+
+		context ":fee" do
+			should "send through as fee:Y if set to true" do
+				Article.expects(:invoke).with(has_entry("query", "ice cream fee:Y"))
+				Article.search "ice cream", :fee => true
+			end
+			
+			should "send through as -fee:Y if set to false" do
+				Article.expects(:invoke).with(has_entry("query", "ice cream -fee:Y"))
+				Article.search "ice cream", :fee => false
+			end
+		end
+
+		context ":fields" do
+			context "for the :all argument" do
+				should "pass all fields in a comma-delimited list" do
+					Article.expects(:invoke).with(has_entry('fields', Article::ALL_FIELDS.join(',')))
+					Article.search "FOO BAR", :fields => :all
+				end
+			end
+			
+			context "for the :none argument" do
+				should "request a blank space for the fields argument" do
+					Article.expects(:invoke).with(has_entry('fields', ' '))
+					Article.search "FOO BAR", :fields => :none
+				end
+				
+				should "request the standard :facets if no :facets have been explicitly provided" do
+					Article.expects(:invoke).with(has_entry('facets', Facet::DEFAULT_RETURN_FACETS.join(',')))
+					Article.search "FOO BAR", :fields => :none	
+				end
+				
+				should "request the given :facets field if provided" do
+					Article.expects(:invoke).with(has_entry('facets', "#{Facet::GEO}"))
+					Article.search "FOO BAR", :fields => :none, :facets => Facet::GEO
+				end
+			end
+			
+			context ":thumbnail" do
+				should "accept the symbol version of the argument" do
+					Article.expects(:invoke).with(has_entry('fields', Article::IMAGE_FIELDS.join(',')))
+					Article.search "FOO BAR", :fields => :thumbnail
+				end
+				
+				should "accept the string version of the argument" do
+					Article.expects(:invoke).with(has_entry('fields', Article::IMAGE_FIELDS.join(',')))
+					Article.search "FOO BAR", :fields => 'thumbnail'
+				end				
+			end
+			
+			context ":multimedia" do
+				should "be implemented"
+			end
+			
+			should "accept a single string as an argument" do
+				Article.expects(:invoke).with(has_entry('fields', 'body'))
+				Article.search "FOO BAR", :fields => 'body'
+			end
+			
+			should "accept a single symbol as an argument" do
+				Article.expects(:invoke).with(has_entry('fields', 'body'))
+				Article.search "FOO BAR", :fields => :body
+			end
+			
+			should "accept an array of strings and symbols" do
+				Article.expects(:invoke).with(has_entry('fields', 'abstract,body'))
+				Article.search "FOO BAR", :fields => [:abstract, 'body']
+			end
+			
+			should "raise an ArgumentError otherwise" do
+				assert_raise(ArgumentError) { Article.search :fields => 12 }
+			end
+		end
+
+		context ":has_multimedia" do
+			should "send through as related_multimedia:Y if set to true" do
+				Article.expects(:invoke).with(has_entry("query", "ice cream related_multimedia:Y"))
+				Article.search "ice cream", :has_multimedia => true
+			end
+			
+			should "send through as -related_multimedia:Y if set to false" do
+				Article.expects(:invoke).with(has_entry("query", "ice cream -related_multimedia:Y"))
+				Article.search "ice cream", :has_multimedia => false
+			end
+		end
+
+		context ":has_thumbnail" do
+			should "send through as small_image:Y if set to true" do
+				Article.expects(:invoke).with(has_entry("query", "ice cream small_image:Y"))
+				Article.search "ice cream", :has_thumbnail => true
+			end
+			
+			should "send through as -small_image:Y if set to false" do
+				Article.expects(:invoke).with(has_entry("query", "ice cream -small_image:Y"))
+				Article.search "ice cream", :has_thumbnail => false
+			end
+		end
+
+		context ":offset" do
+			should "pass through an explicit offset parameter if specified" do
+				Article.expects(:invoke).with(has_entry("offset", 10))
+				Article.search :offset => 10
+			end
+
+			should "raise an ArgumentError if the offset is not an Integer" do
+				assert_raise(ArgumentError) { Article.search :offset => 'apple' }
+			end
+
+			should "pass through an offset of page - 1 if :page is used instead" do
+				Article.expects(:invoke).with(has_entry("offset", 2))
+				Article.search :page => 3
+			end
+
+			should "not pass through a page parameter to the API" do
+				Article.expects(:invoke).with(Not(has_key("page")))
+				Article.search :page => 3
+			end
+
+			should "raise an ArgumentError if the page is not an Integer" do
+				assert_raise(ArgumentError) { Article.search :page => 'orange' }
+			end
+			
+			should "raise an ArgumentError if the page is less than 1" do
+				assert_raise(ArgumentError) { Article.search :page => 0 }
+			end
+
+			should "use the :offset argument if both an :offset and :page are provided" do
+				Article.expects(:invoke).with(has_entry("offset", 2))
+				Article.search :offset => 2, :page => 203
+			end
+		end
+
+		context "rank" do
+			%w(newest oldest closest).each do |rank|
+				should "accept #{rank} as the argument to rank" do
+					Article.expects(:invoke).with(has_entry("rank", rank))
+					Article.search :rank => rank.to_sym
+				end
+			end
+
+			should "raise an ArgumentError if rank is something else" do
+				assert_raise(ArgumentError) { Article.search :rank => :clockwise }
+			end
+		end
+
+		Article::TEXT_FIELDS.each do |tf|
+			context ":#{tf} parameter" do
+				should "prefix each non-quoted term with the #{tf}: field identifier in the query to the API" do
+					Article.expects(:invoke).with(has_entry("query", "#{tf}:ice #{tf}:cream"))
+					Article.search tf.to_sym => 'ice cream'
+				end
+				
+				should "prefix -terms (excluded terms) with -#{tf}:" do
+					Article.expects(:invoke).with(has_entry("query", "#{tf}:ice -#{tf}:cream"))
+					Article.search tf.to_sym => 'ice -cream'
+				end
+				
+				should "put quoted terms behind the field spec" do
+					Article.expects(:invoke).with(has_entry("query", "#{tf}:\"ice cream\" #{tf}:cone"))
+					Article.search tf.to_sym => '"ice cream" cone'
+				end
+				
+				should "handle complicated combinations of expressions" do
+					Article.expects(:invoke).with(has_entry("query", "#{tf}:\"ice cream\" -#{tf}:cone #{tf}:\"waffle\""))
+					Article.search tf.to_sym => '"ice cream" -cone "waffle"'
+				end
+			end
+		end
+		
+		# context "query parameters" do
+		# 	context "abstract" do
+		# 		should "be prefixed with the abstract: field identifier in the query"
+		# 		should "cast the argument to a string (will figure out processing later)"
+		# 	end
+		# 
+		# 	context "author" do
+		# 		should "be prefixed with the author: field identifier in the query"
+		# 		should "cast the argument to a string (will figure out processing later)"
+		# 	end
+		# 
+		# 	context "body" do
+		# 		should "be prefixed with the body: field identifier in the query"
+		# 		should "cast the argument to a string (will figure out processing later)"
+		# 	end
+		# 
+		# 	context "byline" do
+		# 		should "be prefixed with the body: field identifier in the query"
+		# 		should "cast the argument to a string (will figure out processing later)"
+		# 	end
+		# end
+	end
+
+	context "Article.init_from_api" do
+		setup do
+			@article = Article.init_from_api(ARTICLE_API_HASH2)
+		end
+
+		Article::TEXT_FIELDS.each do |tf|
+			context "@#{tf}" do
+				should "read the value from the hash input" do
+					hash = {}
+					hash[tf] = "TEST TEXT"
+					article = Article.init_from_api(hash)
+					assert_equal "TEST TEXT", article.send(tf)
+				end
+
+				should "properly translate HTML entities back into characters" do
+					article = Article.init_from_api(tf => '&#8220;Money for Nothing&#8221;')
+					assert_equal "“Money for Nothing”", article.send(tf), article.inspect
+				end
+
+				should "only provide read-only access to the field" do
+					article = Article.init_from_api(tf => "TEST TEXT")
+					assert !article.respond_to?("#{tf}=")
+				end
+
+				should "return nil if the value is not provided in the hash" do
+					article = Article.init_from_api({"foo" => "bar"})
+					assert_nil article.send(tf)
+				end
+			end
+		end
+
+		Article::NUMERIC_FIELDS.each do |tf|
+			context "@#{tf}" do
+				should "read and coerce the string value from the hash input" do
+					article = Article.init_from_api(tf => "23")
+					assert_equal 23, article.send(tf)
+				end
+
+				should "only provide read-only access to the field" do
+					article = Article.init_from_api(tf => "23")
+					assert !article.respond_to?("#{tf}=")
+				end
+
+				should "return nil if the value is not provided in the hash" do
+					article = Article.init_from_api({"foo" => "bar"})
+					assert_nil article.send(tf)
+				end	
+			end				
+		end
+		
+		# all the rest
+		context "@fee" do
+			setup do
+				@article = Article.init_from_api(ARTICLE_API_HASH)
+			end
+			
+			should "be true if returned as true from the API" do
+				article = Article.init_from_api('fee' => true)
+				assert_equal true, article.fee?
+				assert_equal false, article.free?
+			end
+			
+			should "be true if returned as Y from the API" do
+				article = Article.init_from_api('fee' => 'Y')
+				assert_equal true, article.fee?
+				assert_equal false, article.free?
+			end
+			
+			should "default to false if not specified in the hash" do
+				assert_equal false, @article.fee?
+				assert_equal true, @article.free?
+			end
+			
+			should "default to false if returned as N from the API" do
+				article = Article.init_from_api('fee' => 'N')
+				assert_equal false, article.fee?
+				assert_equal true, article.free?
+			end
+		end
+		
+		context "@url" do
+			setup do
+				@article = Article.init_from_api(ARTICLE_API_HASH)
+			end
+			
+			should "read the value from the hash" do
+				assert_equal ARTICLE_API_HASH['url'], @article.url
+			end
+			
+			should "return a String" do
+				assert_kind_of(String, @article.url)
+			end
+
+			should "only provide read-only access to the field" do
+				assert !@article.respond_to?("url=")
+			end
+
+			should "return nil if the value is not provided in the hash" do
+				article = Article.init_from_api({"foo" => "bar"})
+				assert_nil article.url
+			end	
+		end
+		
+		context "@page" do
+			should "read the value from the page_facet field" do
+				assert_equal ARTICLE_API_HASH2['page_facet'].to_i, @article.page
+			end
+
+			should "only provide read-only access to the field" do
+				article = Article.new
+				assert !article.respond_to?("page=")
+			end
+
+			should "return nil if the value is not provided in the hash" do
+				article = Article.init_from_api({"foo" => "bar"})
+				assert_nil article.page
+			end
+		end
+		
+		context "@thumbnail" do
+			should "assign nil to thumbnail otherwise" do
+				article = Article.init_from_api({"foo" => "bar"})
+				assert_nil article.thumbnail
+			end
+
+			should "create a thumbnail object if a small_image_url is part of the return hash" do
+				article = Article.init_from_api(ARTICLE_API_HASH2)
+				thumbnail = article.thumbnail
+				assert_not_nil thumbnail
+				assert_kind_of Thumbnail, thumbnail
+				assert_equal ARTICLE_API_HASH2['small_image_url'], thumbnail.url
+				assert_equal ARTICLE_API_HASH2['small_image_width'].to_i, thumbnail.width
+				assert_equal ARTICLE_API_HASH2['small_image_height'].to_i, thumbnail.height
+			end
+		end
+	end
+end
+
+
+# abstract 	String 	X 	  	X 	A summary of the article, written by Times indexers
+# author 	String 	X 	  	X 	An author note, such as an e-mail address or short biography (compare byline)
+# body 	String 	X 	  	X 	A portion of the beginning of the article. Note: Only a portion of the article body is included in responses. But when you search against the body field, you search the full text of the article.
+# byline 	String 	X 	  	X 	The article byline, including the author's name
+# classifers_facet 	Array (Strings) 	  	X 	X 	Taxonomic classifiers that reflect Times content categories, such as Top/News/Sports
+# column_facet 	String 	  	X 	X 	A Times column title (if applicable), such as  Weddings or Ideas & Trends
+# date 	Date 	  	X 	X 	The publication date in YYYYMMDD format
+# day_of_week_facet 	String 	  	X 	X 	The day of the week (e.g., Monday, Tuesday) the article was published (compare publication_day, which is the numeric date rather than the day of the week)
+# des_facet 	Array (Strings) 	  	X 	X 	Descriptive subject terms assigned by Times indexers
+# 
+# When used in a request, values must be UPPERCASE
+# desk_facet
+# desk_facet 	String 	  	X 	X 	The Times desk that produced the story (e.g., Business/Financial Desk)
+# fee 	Boolean 	X 	  	X 	Indicates whether users must pay a fee to retrieve the full article
+# geo_facet 	Array (Strings) 	  	X 	X 	Standardized names of geographic locations, assigned by Times indexers
+# 
+# When used in a request, values must be UPPERCASE
+# lead_paragraph 	String 	X 	  	X 	The first paragraph of the article (as it appeared in the printed newspaper)
+# material_type_facet 	Array (Strings) 	  	X 	X 	The general article type, such as Biography, Editorial or Review
+# multimedia 	Array 	  	  	X 	Associated multimedia features, including URLs (see also the related_multimedia field)
+# nytd_byline_facet 	String 	  	X 	X 	The article byline, formatted for NYTimes.com
+# nytd_des_facet 	Array (Strings) 	  	X 	X 	Descriptive subject terms, assigned for use on NYTimes.com (to get standardized terms, use the TimesTags API)
+# 
+# When used in a request, values must be Mixed Case
+# nytd_geo_facet 	Array (Strings) 	  	X 	X 	Standardized names of geographic locations, assigned for use on NYTimes.com (to get standardized terms, use the TimesTags API)
+# 
+# When used in a request, values must be Mixed Case
+# nytd_lead_paragraph 	String 	X 	  	X 	The first paragraph of the article (as it appears on NYTimes.com)
+# nytd_org_facet 	Array (Strings) 	  	X 	X 	Standardized names of organizations, assigned for use on NYTimes.com (to get standardized terms, use the TimesTags API)
+# 
+# When used in a request, values must be Mixed Case
+# nytd_per_facet 	Array (Strings) 	  	X 	X 	Standardized names of people, assigned for use on NYTimes.com (to get standardized terms, use the TimesTags API)
+# 
+# When used in a request, values must be Mixed Case
+# nytd_section_facet 	Array (Strings) 	  	X 	X 	The section the article appears in (on NYTimes.com)
+# nytd_title 	String 	X 	  	X 	The article title on NYTimes.com (this field may or may not match the title field; headlines may be shortened and edited for the Web)
+# nytd_works_mentioned
+# _facet 	String 	  	X 	X 	Literary works mentioned (titles formatted for use on NYTimes.com)
+# org_facet 	Array (Strings) 	  	X 	X 	Standardized names of organizations, assigned by Times indexers
+# 
+# When used in a request, values must be UPPERCASE
+# page_facet 	String 	  	X 	X 	The page the article appeared on (in the printed paper)
+# per_facet 	Array (Strings) 	  	X 	X 	Standardized names of people, assigned by Times indexers
+# 
+# When used in a request, values must be UPPERCASE
+# publication_day
+# publication_month
+# publication_year 	Date
+# Date
+# Date 	  	X
+# X
+# X 	X
+# x
+# x 	The day (DD), month (MM) and year (YYYY) segments of date, separated for use as facets
+# related_multimedia 	Boolean 	X 	  	X 	Indicates whether multimedia features are associated with this article. Additional metadata for each related multimedia feature appears in the multimedia array.
+# section_page_facet 	String 	  	X 	X 	The full page number of the printed article (e.g., D00002)
+# small_image
+# small_image_url
+# small_image_height
+# small_image_width 	Boolean
+# String
+# Integer
+# Integer 	X 	  	X
+# X
+# X
+# X 	The small_image field indicates whether a smaller thumbnail image is associated with the article. The small_image_url field provides the URL of the image on NYTimes.com. The small_image_height and small_image_width fields provide the image dimensions.
+# source_facet 	String 	  	X 	X 	The originating body  (e.g., AP, Dow Jones, The New York Times)
+# text 	String 	X 	  	  	The text field consists of title + byline + body (combined in an OR search) and is the default field for keyword searches. For more information, see Constructing a Search Query.
+# title 	String 	X 	  	X 	The article title (headline); corresponds to the headline that appeared in the printed newspaper
+# url 	String 	X 	  	X 	The URL of the article on NYTimes.com
+# word_count 	Integer 	  	  	X 	The full article word count
+# works_mentioned_facet