harrisj-nytimes-articles 0.3.0 → 0.4.0

data/.gitignore

@@ -0,0 +1,3 @@
+*.sw?
+.DS_Store
+coverage

data/HISTORY

@@ -0,0 +1,9 @@
+HISTORY
+
+= 0.4.0
+  - Changed facet format returned from search
+  - Changed default fields returned to all
+  - Added basic fields type
+
+= 0.3.0
+  - Whoops, I never had a history file!

data/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2008 Jacob Harris
+
+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.
+
+THIS LICENSE ALSO APPLIES ONLY TO THE RUBY GEM FOR ACCESSING THE NYTIMES
+ARTICLE SEARCH API AND DOES NOT SUPPLEMENT OR ABROGATE ANY TERMS OF USE
+OF THE API AT THE NEW YORK TIMES.

data/README

@@ -0,0 +1,32 @@
+= nytimes-articles
+
+A simple GEM for interacting with the New York Times' Article Search API (http://developer.nytimes.com/docs/article_search_api)
+
+== CREDITS
+
+* Jacob Harris (http://open.blogs.nytimes.com/)
+* Taylor Barstow (http://www.nytexplorer.com/)
+
+== USAGE
+
+	require 'rubygems'
+	require 'nytimes-articles'
+	
+	include Nytimes::Articles
+	Base.api_key = 'YOUR API KEY'
+	Article.search 'ice cream'
+	Article.search :title => '"ice cream"', :since => 3.weeks.ago, :fields => :basic
+	Article.search :author => 'Sewell Chan', :facets => [:geo, :person]
+
+See the RDOC for Article#search for better instructions on usage.
+
+== TODO
+
+The following functionality is still to be implemented:
+
+* Parsing multimedia and related_multimedia fields
+* Coercion of some facet results into more suitable Ruby types (mostly Dates / Integer fields)
+* Next / previous result set pagination (with memoization?)
+
+== COPYRIGHT
+Copyright (c) 2008 Jacob Harris. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "nytimes-articles"
+    s.summary = %Q{A gem for accessing the NYTimes Article Search API}
+    s.email = "jharris@nytimes.com"
+    s.homepage = "http://github.com/harrisj/nytimes-articles"
+    s.description = "A gem for accessing the New York Times Article Search API"
+    s.authors = ["Jacob Harris"]
+		s.requirements << 'Unicode'
+		s.requirements << 'The htmlentities gem'
+		s.add_dependency('htmlentities')
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'nytimes-articles'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib' << 'test'
+  t.pattern = 'test/**/test_*.rb'
+  t.verbose = false
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |t|
+    t.libs << 'test'
+    t.test_files = FileList['test/**/test_*.rb']
+    t.verbose = true
+  end
+rescue LoadError
+  puts "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+end
+
+begin
+  require 'cucumber/rake/task'
+  Cucumber::Rake::Task.new(:features)
+rescue LoadError
+  puts "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
+end
+
+task :default => :test

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:minor: 3
 :patch: 0
 :major: 0
+:minor: 4

data/features/nytimes_articles.feature

@@ -0,0 +1,9 @@
+Feature: something something
+  In order to something something
+  A user something something
+  something something something
+
+  Scenario: something something
+    Given inspiration
+    When I create a sweet new gem
+    Then everyone should see how awesome I am

data/features/support/env.rb

@@ -0,0 +1,13 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
+require 'nytimes_articles'
+
+require 'test/unit/assertions'
+
+require 'test/unit/assertions'
+
+World do |world|
+  
+  world.extend(Test::Unit::Assertions)
+  
+  world
+end

data/lib/nytimes_articles.rb

@@ -1,6 +1,6 @@
 # should I be setting this?
 $KCODE = 'UTF8'
 
-%w(exceptions base facet thumbnail article result_set query).each do |f|
+%w(exceptions base facet facet_hash thumbnail article result_set query).each do |f|
   require File.join(File.dirname(__FILE__), 'nytimes_articles', f)
 end

data/lib/nytimes_articles/article.rb

@@ -30,6 +30,10 @@ module Nytimes
 			attr_reader :classifiers, :descriptions, :geo, :material_types, :organizations, :persons, :nytd_bylines, :nytd_descriptions, :nytd_geo, :nytd_organizations, :nytd_persons, :nytd_sections, :nytd_works_mentioned, :works_mentioned
 			alias :people :persons
 			alias :nytd_people :nytd_persons
+			alias :places :geo
+			alias :nytd_places :nytd_geo
+			alias :subjects :descriptions
+			alias :nytd_subjects :nytd_descriptions
 			
 			##
 			# Create a new Article from hash arguments. You really don't need to call this as Article instances are automatically returned from the API
@@ -183,13 +187,14 @@ module Nytimes
 		  #
 		  # == ARTICLE FIELDS
 		  #
-		  # The <tt>:fields</tt> parameter is used to indicate what fields are returned with each article from the search results. If not specified, only
-		  # the following fields are returned for each article: body, byline, date, title, and url. To return specific fields, any of the search fields
+		  # The <tt>:fields</tt> parameter is used to indicate what fields are returned with each article from the search results. If not specified, all
+		  # fields are returned. To return specific fields, any of the search fields
 		  # from above can be explicitly specified in a comma-delimited list, as well as the additional display-only (not searchable) fields below (these
 		  # are strings or symbols):
 		  # 
 		  # * <tt>:all</tt> - return all fields for the article
 		  # * <tt>:none</tt> - display only the facet breakdown and no article results
+		  # * <tt>:basic</tt> - return only the body, byline, date, title, and url
 		  # * <tt>:multimedia</tt> - return any related multimedia links for the article
 		  # * <tt>:thumbnail</tt> - return information for a related thumbnail image (if the article has one)
 		  # * <tt>:word_count</tt> - the word_count of the article.
@@ -226,9 +231,8 @@ module Nytimes
 			end
 
 			def self.facet_params(params, facet_name)
-				return nil if params[facet_name].nil?
-
-				params[facet_name].map {|f| Facet.new(facet_name, f, nil) }
+				#return nil if params[facet_name].nil?
+				params[facet_name] # .map {|f| Facet.new(facet_name, f, nil) }
 			end
 
 			def self.text_argument(field, argument)
@@ -273,10 +277,10 @@ module Nytimes
 
 			def self.add_fields_param(out_params, in_params)
 				case in_params[:fields]
-				when nil
-					# do nothing
-				when :all
+				when nil, :all
 					out_params['fields'] = ALL_FIELDS.join(',')
+				when :basic
+					# do nothing, the API will return basic URLs
 				when :none
 					out_params['fields'] = ' '
 					unless out_params['facets']

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

@@ -8,7 +8,7 @@ module Nytimes
 	  #
 	  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)
+	              :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

data/lib/nytimes_articles/result_set.rb

@@ -35,7 +35,7 @@ module Nytimes
 				@offset = params[:offset]
 				@total_results = params[:total_results]
 				@results = params[:results]
-				@facets = params[:facets]
+				@facets = FacetHash.init_from_api(params[:facets])
 			end
 			
 			##

data/nytimes-articles.gemspec

@@ -0,0 +1,73 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{nytimes-articles}
+  s.version = "0.4.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jacob Harris"]
+  s.date = %q{2009-07-23}
+  s.description = %q{A gem for accessing the New York Times Article Search API}
+  s.email = %q{jharris@nytimes.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README"
+  ]
+  s.files = [
+    ".gitignore",
+     "HISTORY",
+     "LICENSE",
+     "README",
+     "Rakefile",
+     "VERSION.yml",
+     "features/nytimes_articles.feature",
+     "features/steps/nytimes_articles_steps.rb",
+     "features/support/env.rb",
+     "lib/nytimes_articles.rb",
+     "lib/nytimes_articles/article.rb",
+     "lib/nytimes_articles/base.rb",
+     "lib/nytimes_articles/exceptions.rb",
+     "lib/nytimes_articles/facet.rb",
+     "lib/nytimes_articles/facet_hash.rb",
+     "lib/nytimes_articles/query.rb",
+     "lib/nytimes_articles/result_set.rb",
+     "lib/nytimes_articles/thumbnail.rb",
+     "nytimes-articles.gemspec",
+     "script/console",
+     "test/nytimes/articles/test_article.rb",
+     "test/nytimes/articles/test_base.rb",
+     "test/nytimes/articles/test_facet.rb",
+     "test/nytimes/articles/test_query.rb",
+     "test/nytimes/articles/test_result_set.rb",
+     "test/nytimes/articles/test_thumbnail.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/harrisj/nytimes-articles}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.requirements = ["Unicode", "The htmlentities gem"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{A gem for accessing the NYTimes Article Search API}
+  s.test_files = [
+    "test/nytimes/articles/test_article.rb",
+     "test/nytimes/articles/test_base.rb",
+     "test/nytimes/articles/test_facet.rb",
+     "test/nytimes/articles/test_query.rb",
+     "test/nytimes/articles/test_result_set.rb",
+     "test/nytimes/articles/test_thumbnail.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<htmlentities>, [">= 0"])
+    else
+      s.add_dependency(%q<htmlentities>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<htmlentities>, [">= 0"])
+  end
+end

data/script/console

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# File: script/console
+irb = RUBY_PLATFORM =~ /(:?mswin|mingw)/ ? 'irb.bat' : 'irb'
+
+libs =  " -r irb/completion"
+# Perhaps use a console_lib to store any extra methods I may want available in the cosole
+# libs << " -r #{File.dirname(__FILE__) + '/../lib/console_lib/console_logger.rb'}"
+libs <<  " -r #{File.dirname(__FILE__) + '/../lib/nytimes_articles.rb'}"
+puts "Loading nytimes_articles gem"
+exec "#{irb} #{libs} --simple-prompt"

data/test/nytimes/articles/test_article.rb

@@ -249,6 +249,13 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 		end
 
 		context ":fields" do
+			context "when not specified at all" 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 :all argument" do
 				should "pass all fields in a comma-delimited list" do
 					Article.expects(:invoke).with(has_entry('fields', Article::ALL_FIELDS.join(',')))
@@ -256,6 +263,13 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 				end
 			end
 			
+			context "for the :basic argument" do
+				should "not send a fields argument to the api" do
+					Article.expects(:invoke).with(Not(has_key('fields')))
+					Article.search "FOO BAR", :fields => :basic
+				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', ' '))
@@ -562,79 +576,9 @@ class TestNytimes::TestArticles::TestArticle < Test::Unit::TestCase
 				assert_equal ARTICLE_API_HASH2['small_image_height'].to_i, thumbnail.height
 			end
 		end
+		
+		context "array facets" do
+			should "have some tests for array facets"
+		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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: harrisj-nytimes-articles
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Jacob Harris
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-03-03 00:00:00 -08:00
+date: 2009-07-23 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -28,21 +28,30 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- LICENSE
+- README
 files: 
+- .gitignore
+- HISTORY
+- LICENSE
+- README
+- Rakefile
 - VERSION.yml
-- lib/nytimes_articles
+- features/nytimes_articles.feature
+- features/steps/nytimes_articles_steps.rb
+- features/support/env.rb
+- lib/nytimes_articles.rb
 - lib/nytimes_articles/article.rb
 - lib/nytimes_articles/base.rb
 - lib/nytimes_articles/exceptions.rb
 - lib/nytimes_articles/facet.rb
+- lib/nytimes_articles/facet_hash.rb
 - lib/nytimes_articles/query.rb
 - lib/nytimes_articles/result_set.rb
 - lib/nytimes_articles/thumbnail.rb
-- lib/nytimes_articles.rb
-- test/nytimes
-- test/nytimes/articles
+- nytimes-articles.gemspec
+- script/console
 - test/nytimes/articles/test_article.rb
 - test/nytimes/articles/test_base.rb
 - test/nytimes/articles/test_facet.rb
@@ -50,11 +59,10 @@ files:
 - test/nytimes/articles/test_result_set.rb
 - test/nytimes/articles/test_thumbnail.rb
 - test/test_helper.rb
-has_rdoc: true
+has_rdoc: false
 homepage: http://github.com/harrisj/nytimes-articles
 post_install_message: 
 rdoc_options: 
-- --inline-source
 - --charset=UTF-8
 require_paths: 
 - lib
@@ -76,7 +84,13 @@ requirements:
 rubyforge_project: 
 rubygems_version: 1.2.0
 signing_key: 
-specification_version: 2
+specification_version: 3
 summary: A gem for accessing the NYTimes Article Search API
-test_files: []
-
+test_files: 
+- test/nytimes/articles/test_article.rb
+- test/nytimes/articles/test_base.rb
+- test/nytimes/articles/test_facet.rb
+- test/nytimes/articles/test_query.rb
+- test/nytimes/articles/test_result_set.rb
+- test/nytimes/articles/test_thumbnail.rb
+- test/test_helper.rb