nytimes-events 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in nytimes-events.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Dylan Drop
+
+MIT License
+
+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/README.md

@@ -0,0 +1,60 @@
+# Nytimes::Events
+
+A Ruby wrapper for the NYTimes Event Listings API.
+
+Currently v0.0.1. As of right now, you can supply any legal parameters and receive the response back from NYTimes as a JSON hash. Next to come: faceted search, spatial search, and more robust error handling. Possible other features include an option for XML response. Also, if there are any other features that people may want, feel free to contribute or let me know. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'nytimes-events'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install nytimes-events
+
+## Usage
+
+A simple usage example, as of right now:
+
+    listing = Nytimes::Event::List.new(MY_API_KEY)
+    listing.find('query' => 'food')
+
+`search` takes a hash of parameters which directly correspond to the parameters found on the NYTimes' Event Listings API page. You must initialize any object with your API key which can be obtained from the NYTimes API website.
+
+Query parameters can be found here: http://developer.nytimes.com/docs/read/events_api
+
+You will receive back a JSON hash of events.
+
+**IMPORTANT**
+
+`nytimes-event` is based off of the linked-list data structure. That is, `Nytimes::Event::List` actually retrieves `batch_size` number of events, and you can retrieve the next `batch_size` events or the previous `batch_size` events.
+
+`batch_size` by default is 20.
+
+For example:
+
+    listing = Nytimes::Event::List.new(MY_API_KEY)
+    listing.batch_size = 10
+    listing.find('query' => 'food')
+    #=> next retrieves the next 10 events
+    listing.next
+    #=> previous retrieves the previous 10 events
+    listing.prev
+
+Also, you can reset to head (such that the results are those which would appear if you hadn't called next or previous at all) by calling `to_head`:
+
+    listing.to_head
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/nytimes-events/base.rb

@@ -0,0 +1,29 @@
+module Nytimes
+  module Events
+    class Base
+      API_SERVER = 'api.nytimes.com'
+      API_VERSION = 'v2'
+      API_NAME = 'events'
+      API_OBJECTS = 'listings'
+      RESPONSE_TYPE = 'json'
+      API_URL = "http://#{API_SERVER}/svc/#{API_NAME}/#{API_VERSION}/listings.#{RESPONSE_TYPE}"
+
+      def initialize(api_key)
+        @api_key = api_key
+      end
+
+      def api_key=(key)
+        @api_key = key
+      end
+
+      def api_key
+        @api_key
+      end
+
+      def api_url(params)
+        prmstr = params.collect { |k, v| "#{k.to_s}=#{v.to_s.gsub(' ','+')}" }.join('&') + "&api-key=" + api_key
+        API_URL + "?" + prmstr
+      end
+    end
+  end
+end

data/lib/nytimes-events/list.rb

@@ -0,0 +1,70 @@
+module Nytimes
+  module Events
+    class List < Base
+      attr_reader :batch_size
+
+      def initialize(api_key, batch_size = 20)
+        super(api_key)
+        @batch_size = batch_size
+        @current_offset = 0
+        @results = 0
+        @previous_params = Hash.new
+      end
+
+      def find(params = {})
+        to_head if previous_params_differ_from(params)
+
+        @previous_params = params
+        response = RestClient.get(api_url_for(params))
+
+        case response_code_for response
+        when 403
+          raise RestClient::Exception, "Access forbidden by NYTimes API. Perhaps the API key isn't working?"
+        when 200
+          json = JSON.parse(response)
+          set_results_returned(json)
+          json
+        end
+      end
+
+      def batch_size=(amount)
+        @batch_size = amount
+      end
+
+      def next_page
+        @current_offset += @batch_size unless @current_offset + @batch_size > @results
+        find(@previous_params)
+      end
+      alias :next :next_page
+
+      def prev_page
+        @current_offset -= @batch_size unless @batch_size > @current_offset
+        find(@previous_params)
+      end
+      alias :previous :prev_page
+
+      def to_head
+        @current_offset = 0
+      end
+
+      private
+
+      def previous_params_differ_from(params)
+        params = params.delete_if {|key, value| key == 'offset' || key == 'limit' }
+        params != @previous_params
+      end
+
+      def response_code_for response
+        response.net_http_res.instance_of?(Fixnum) ? response.net_http_res : response.code
+      end
+
+      def api_url_for params
+        api_url(params.merge({'limit' => @batch_size, 'offset' => @current_offset}))
+      end
+
+      def set_results_returned incoming_json
+        @results = incoming_json['num_results'].to_i
+      end
+    end
+  end
+end

data/lib/nytimes-events/version.rb

@@ -0,0 +1,5 @@
+module Nytimes
+  module Events
+    VERSION = "0.0.1"
+  end
+end

data/lib/nytimes-events.rb

@@ -0,0 +1,12 @@
+require 'rest_client'
+require 'json'
+
+require 'nytimes-events/base'
+require 'nytimes-events/list'
+require 'nytimes-events/version'
+
+module Nytimes
+  module Events
+    class Error < StandardError; end
+  end
+end

data/nytimes-events.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/nytimes-events/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Dylan"]
+  gem.email         = ["dylandrop@gmail.com"]
+  gem.description   = %q{NYTimes Events Ruby API}
+  gem.summary       = %q{A Ruby wrapper for the NYTimes Events API.}
+  gem.homepage      = "https://github.com/dylandrop/nytimes-events"
+
+  gem.add_development_dependency "rspec"
+  gem.add_dependency "rest-client", ">0"
+  gem.add_dependency "json", ">0"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "nytimes-events"
+  gem.require_paths = ["lib"]
+  gem.version       = Nytimes::Events::VERSION
+end

data/spec/base_spec.rb

@@ -0,0 +1,13 @@
+require 'spec-helper'
+
+describe Nytimes::Events::Base do
+  it "should form the correct url from a basic query string" do
+    base = Nytimes::Events::Base.new("XXXX")
+    base.api_url('query' => 'food').should == "http://api.nytimes.com/svc/events/v2/listings.json?query=food&api-key=XXXX"
+  end
+
+  it "should substitute spaces with plusses" do
+    base = Nytimes::Events::Base.new("XXXX")
+    base.api_url('query' => 'foo bar').should == "http://api.nytimes.com/svc/events/v2/listings.json?query=foo+bar&api-key=XXXX"
+  end
+end

data/spec/list_spec.rb

@@ -0,0 +1,65 @@
+require 'spec-helper'
+
+describe Nytimes::Events::List do
+  it "raises an exception on 403" do
+    listing = Nytimes::Events::List.new("XXXX")
+    RestClient.stub(:get).and_return(RestClient::Response.create("{}", 403, {}))
+    expect {listing.find('foo' => 'bar')}.to raise_error(RestClient::Exception)
+  end
+
+  it "parses the body of the response on 200" do
+    listing = Nytimes::Events::List.new("XXXX")
+    RestClient.stub(:get).and_return(RestClient::Response.create("{\"thing1\":\"thing2\"}", 200, {}))
+    listing.find('foo' => 'bar').should == {'thing1' => 'thing2'}
+  end
+
+  it "allows you to set and retrieve the batch size" do
+    listing = Nytimes::Events::List.new("XXXX")
+    listing.batch_size = 40
+    listing.batch_size.should == 40
+  end
+
+  it "fetches the next 'batch' number of items when next_page is requested" do
+    listing = Nytimes::Events::List.new("XXXX")
+    RestClient.stub(:get).and_return(RestClient::Response.create("{\"num_results\":\"23\"}", 200, {}))
+    listing.find('foo' => 'bar')
+    listing.next_page
+    listing.instance_variable_get(:@current_offset).should == listing.instance_variable_get(:@batch_size)
+  end
+
+  it "fetches the last 'batch' number of items when next_page is requested" do
+    listing = Nytimes::Events::List.new("XXXX")
+    RestClient.stub(:get).and_return(RestClient::Response.create("{\"thing1\":\"thing2\"}", 200, {}))
+    listing.find('foo' => 'bar')
+    listing.instance_variable_set(:@current_offset, 20)
+    listing.prev_page
+    listing.instance_variable_get(:@current_offset).should == 0
+  end
+
+  it "doesn't fetch the last items if the current offset would be negative" do
+    listing = Nytimes::Events::List.new("XXXX")
+    RestClient.stub(:get).and_return(RestClient::Response.create("{\"thing1\":\"thing2\"}", 200, {}))
+    listing.find('foo' => 'bar')
+    listing.instance_variable_set(:@current_offset, 0)
+    listing.prev_page
+    listing.instance_variable_get(:@current_offset).should == 0
+  end
+
+  it "doesn't fetch the next items if the new current offset would be greater than the number of results" do
+    listing = Nytimes::Events::List.new("XXXX")
+    RestClient.stub(:get).and_return(RestClient::Response.create("{\"num_results\":\"6\"}", 200, {}))
+    listing.find('foo' => 'bar')
+    listing.instance_variable_set(:@current_offset, 0)
+    listing.next_page
+    listing.instance_variable_get(:@current_offset).should == 0
+  end
+
+  it "should reset to head if new query is performed" do
+    listing = Nytimes::Events::List.new("XXXX")
+    RestClient.stub(:get).and_return(RestClient::Response.create("{\"num_results\":\"6\"}", 200, {}))
+    listing.find('foo' => 'bar')
+    listing.instance_variable_set(:@current_offset, 40)
+    listing.find('foo' => 'qwerty')
+    listing.instance_variable_get(:@current_offset).should == 0
+  end
+end

data/spec/spec-helper.rb

@@ -0,0 +1,3 @@
+require File.dirname(__FILE__) + '/../lib/nytimes-events'
+
+require 'nytimes-events'

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: nytimes-events
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Dylan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>'
+      - !ruby/object:Gem::Version
+        version: '0'
+description: NYTimes Events Ruby API
+email:
+- dylandrop@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/nytimes-events.rb
+- lib/nytimes-events/base.rb
+- lib/nytimes-events/list.rb
+- lib/nytimes-events/version.rb
+- nytimes-events.gemspec
+- spec/base_spec.rb
+- spec/list_spec.rb
+- spec/spec-helper.rb
+homepage: https://github.com/dylandrop/nytimes-events
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A Ruby wrapper for the NYTimes Events API.
+test_files:
+- spec/base_spec.rb
+- spec/list_spec.rb
+- spec/spec-helper.rb