nytimes-articles 0.4.0

data/lib/nytimes_articles/base.rb

@@ -0,0 +1,124 @@
+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
+			@@decode_html_entities = true
+
+			##
+			# 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
+			
+			##
+			# Set whether or not to decode HTML entities when returning text fields.
+			def self.decode_html_entities=(flag)
+			  @@decode_html_entities = 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.to_s)}"}.join('&')
+			end
+			
+			def self.text_field(value)
+				return nil if value.nil?
+				@@decode_html_entities ? HTMLEntities.new.decode(value) : 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/facet_hash.rb

@@ -0,0 +1,26 @@
+module Nytimes
+	module Articles
+		class FacetHash
+			def initialize(hash)
+				@facets = hash
+			end
+			
+			def [](key)
+				case key
+				when Symbol
+					key = Facet.symbol_name(key)
+				when String
+					# do nothing
+				else
+					raise ArgumentError, "Argument to facets hash must be a symbol or string name"
+				end
+				
+				@facets[key]
+			end
+			
+			def self.init_from_api(hash)
+				new(hash)
+			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{|f| f.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 = FacetHash.init_from_api(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