olibrary 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 560b9646842794293b3becab99d240100e81766cd39f013f1759f1e5dd2a7c7f
+  data.tar.gz: 390a0b4d16559d487342cd4811b8993d980104b97bf0db75e983b5c149ac10ab
+SHA512:
+  metadata.gz: 39adb4f98f9b3dee1f49dd164bf21ab71915971963bd07b2d8db7b9a6534606117b587f34e1fc3886efe6115951cb970e6ea19a64e6fe1925ae9dcc02df4cd98
+  data.tar.gz: f494fa9e4fa25380048bf467c24dd175daceb8c69d4b15bf32adee323349b25a3dd06a5f8a45df4515490bcbe36186dea687f4162c50a1c2a359cb714379a299

data/.gitignore

@@ -0,0 +1,9 @@
+.idea
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.rvmrc
+*~
+*.swp
+.rbenv-version

data/.ruby-gemset

@@ -0,0 +1 @@
+olibrary

data/.ruby-version

@@ -0,0 +1 @@
+3.1.1

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in olibrary.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,238 @@
+== Olibrary
+
+> This project is a fork of https://github.com/jayfajardo/openlibrary with a focus on search.
+
+The olibrary gem provides Ruby clients for the {Open Library REST API}[http://openlibrary.org/dev/docs/restful_api] and {Books API}[http://openlibrary.org/dev/docs/api/books].
+
+For more information about Open Library development, visit the {Open Library Developer Center}[http://openlibrary.org/developers/api] and {Developer Notes}[http://openlibrary.org/dev].
+
+
+== Installation
+
+  gem install olibrary
+
+or in your Gemfile:
+
+  gem 'olibrary'
+
+== Usage
+
+You can use the Books client to retrieve a book's Open Library listing information, and the REST client to perform more advanced queries and save changes to Open Library.
+
+  # just require
+  require 'olibrary'
+
+== REST Client
+
+You can use the REST client to look up books, authors, the revision history of any Open Library object, and recent changes to Open Library.
+
+You can also use the REST client to log in and save changes to Open Library, after you register your profile (or your bot's profile) with the {API Usergroup}[http://openlibrary.org/usergroup/api]. Send a message to the {ol-tech mailing list}[http://mail.archive.org/cgi-bin/mailman/listinfo/ol-tech] to learn how!
+
+=== Getting Started
+
+Before anything else, create a new client:
+
+  client = Olibrary::Client.new
+
+=== Books
+
+Since Open Library has varying amounts of information about the books in its database, and returns data in a schemaless format, not every book will have the same properties. Common properties include `title`, `works`, and `contributors`, but most books will have more.
+
+Find a book by its OLID:
+
+  book = client.book('olid')
+
+  book.contributors     # array of book contributors
+  book.covers           # array of book cover ids
+  book.works            # array of works associated with the book
+  book.subjects         # array of subjects of the book
+
+  book.title            # book title
+  book.by_statement     # name of primary author(s) of the book
+  book.number_of_pages  # number of pages in the book
+  book.copyright_date   # book's copyright date
+  book.physical_format  # book's physical format
+  book.isbn_10[0]       # book's ISBN-10 identifier
+  book.isbn_13[0]       # book's ISBN-13 identifier
+  book.goodreads[0]     # book's goodreads id
+
+Get data on book contributors:
+
+  book.contributors.each do |c|
+    name = c.name   # contributor's name
+    role = c.role   # contributor's role (e.g., cover art)
+  end
+
+Get the book's subjects:
+
+  book.subjects.each do |s|
+    subject = s
+  end
+
+Get a book's Open Library object keys by its ISBN, LCCN, or OCLC identifier:
+
+  keys = client.book_by_isbn('isbn')   # isbn must be 10 or 13 characters long
+  keys = client.book_by_lccn('lccn')
+  keys = client.book_by_oclc('oclc')
+
+Iterate through the array of keys:
+
+  keys.each do |k|
+    key = k['key']  # keys are in the format '/books/{OLID}'
+  end
+
+Although keys are returned in an array, most arrays will only have one element.
+
+=== Authors
+
+Find an author by their OLID:
+
+  author = client.author('olid')
+
+  author.name                 # author name
+  author.birth_date           # author's birth date
+  author.death_date           # author's death date
+  author.last_modified.value  # date and time of last change to page
+  author.revision             # number of current revision
+  author.key!                 # author key, in the format '/authors/{OLID}
+
+=== Search
+
+Find books through the Open Library free text search:
+
+  results = client.search("A Tale of Two Cities")
+
+Search by book attributes:
+
+  results = client.search({author: "Doctorow", title: "Little Brother"})
+
+You can add multiple requirements to a single parameter by including a comma within the string.
+
+  results = client.search({subject: "Science, Physics"}) # works as AND
+
+Results are arrays of book documents
+
+  results[0].title            # the title of the first result
+
+Results include convienence functions for digging deeper
+
+  results[0].book.call() # a proc that will return a book document as returned by the `book` method for the current documents id.
+  results[0].authors.call() # a proc that will return an array of author documents as returned by the `author` method for each of the current documents author ids.
+
+=== Revision History
+
+Get the revision history of any Open Library object:
+
+  history = client.rev_history('key')
+
+The key should be in the format '/type/OLID'. E.g., '/books/OL9220552M', '/authors/OL27349A', or '/works/OL468516W'.
+
+=== Recent Changes
+
+Get an array of recent changes to Open Library:
+
+  changes = client.recent
+
+=== Saving Changes
+
+Use the login method to get a session cookie:
+
+  cookie = client.login('username', 'password')
+
+Set the other parameters for the object you want to change:
+
+  key     = '/type/OLID'              # e.g., '/books/OL9220552M'
+  update  = full_object_with_changes  # must be JSON format
+  comment = 'changed X, Y, and Z'
+
+Save your changes and receive the updated object as a response:
+
+  object = client.save(key, cookie, update, comment)
+
+NOTICE: Before you can actually save changes to Open Library, you need to register your profile (or bot) with the {API Usergroup}[http://openlibrary.org/usergroup/api]. Send a message to the {ol-tech mailing list}[http://mail.archive.org/cgi-bin/mailman/listinfo/ol-tech] to learn how!
+
+== Books Client
+
+There are three classes in the openlibrary gem you can use to access the {Books API}[http://openlibrary.org/dev/docs/api/books]. Use Olibrary::View to look up Open Library listing information, Olibrary::Data to get a book's full metadata details, and Olibrary::Details to get book details in addition to what the Olibrary::View class provides.
+
+=== Olibrary::View
+
+Instantiate the class:
+
+  view = Olibrary::View
+
+Look up a book by its ISBN-10 or ISBN-13:
+
+  book = view.find_by_isbn("0451526538")
+
+  book.info_url      # book's URL on Open Library
+  book.preview       # book's preview state, either 'noview' or 'full'
+  book.thumbnail_url # url of thumbnail cover of the book, if available
+
+  book.preview_url
+  # Links to an archive.org page with a readable version of the book,
+  # if one is available. If not, links to the book's Open Library
+  # page. `book.preview` should be used first to test if a readable
+  # preview of the book exists.
+
+Other built-in finder methods:
+
+  view.find_by_lccn   # Library of Congress catalog number
+  view.find_by_oclc   # Worldcat Control Number
+  view.find_by_olid   # Open Library ID
+
+
+=== Olibrary::Data
+
+Instantiate the class:
+
+  data = Olibrary::Data
+
+Look up a book by its ISBN-10 or ISBN-13:
+
+  book_data = data.find_by_isbn("0451526538")
+
+  book_data.title    # book's title
+  book_data.authors  # array of authors
+
+Other built-in finder methods:
+
+  data.find_by_lccn   # Library of Congress catalog number
+  data.find_by_oclc   # Worldcat Control Number
+  data.find_by_olid   # Open Library ID
+
+=== Olibrary::Details
+
+Instantiate the class:
+  
+  details = Olibrary::Details
+
+Look up a book by its ISBN-10 or ISBN-13:
+
+  book_details = details.find_by_isbn("0451526538")
+
+  book_details.info_url    # book's URL on Open Library
+  book_details.details     # additional details, such as description
+
+Other built-in finder methods:
+
+  details.find_by_lccn   # Library of Congress catalog number
+  details.find_by_oclc   # Worldcat Control Number
+  details.find_by_olid   # Open Library ID
+
+== CONTRIBUTORS
+
+* Jay Fajardo https://github.com/jayfajardo
+* John Shutt https://github.com/pemulis
+* Robert Berry https://github.com/bdigital
+* Eric Larson https://github.com/ewlarson
+* Charles Horn https://github.com/hornc
+* Alex Grant https://github.com/grantovich
+* Bryan L. Fordham https://github.com/bfordham
+* Kyle Corbitt https://github.com/kcorbitt
+* Matt Dressel https://github.com/dresselm
+* Scott Lesser https://github.com/okcscott
+
+== LICENSE
+
+This code is released under the {CC0 License}[http://creativecommons.org/publicdomain/zero/1.0/], and may be used for any purpose without restrictions.

data/Rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')
+

data/lib/olibrary/client/authors.rb

@@ -0,0 +1,10 @@
+module Olibrary
+  module Authors 
+    # Find authors in Open Library by their key 
+    #
+    def author(key)
+      data = request("/authors/#{key}")
+      Hashie::Mash.new(data)
+    end
+  end
+end

data/lib/olibrary/client/books.rb

@@ -0,0 +1,31 @@
+module Olibrary
+  module Books
+    # Find books in Open Library by OLID, ISBN, LCCN, or OCLC
+    #
+    def book(olid)
+      data = request("/books/#{olid}")
+      Hashie::Mash.new(data)
+    end
+
+    def book_by_isbn(isbn)
+      type = "/type/edition"
+      if isbn.length == 10
+        data = query("type=#{type}&isbn_10=#{isbn}")
+      elsif isbn.length == 13
+        data = query("type=#{type}&isbn_13=#{isbn}")
+      else
+        raise ArgumentError, "ISBN must be 10 or 13 characters."
+      end
+    end
+
+    def book_by_lccn(lccn)
+      type = "/type/edition"
+      data = query("type=#{type}&lccn=#{lccn}")
+    end
+
+    def book_by_oclc(oclc)
+      type = "/type/edition"
+      data = query("type=#{type}&oclc_numbers=#{oclc}")
+    end
+  end
+end

data/lib/olibrary/client/editions.rb

@@ -0,0 +1,10 @@
+module Olibrary
+  module Editions
+    # Get the editions of a work
+    #
+    def editions(work, limit=10, offset=0)
+      data = request("/works/#{work}/editions.json?limit=#{limit}&offset=#{offset}")
+      editions = Hashie::Mash.new(data)
+    end
+  end
+end

data/lib/olibrary/client/history.rb

@@ -0,0 +1,9 @@
+module Olibrary
+  module History
+    # Get the revision history of an object in Open Library
+    #
+    def rev_history(object_key)
+      data = history("#{object_key}")
+    end
+  end
+end

data/lib/olibrary/client/login.rb

@@ -0,0 +1,10 @@
+module Olibrary
+  module Login
+    # Log in to Open Library
+    #
+    def login(username, password)
+      response = protected_login("#{username}", "#{password}")
+      cookie = Hashie::Mash.new(response).session
+    end
+  end
+end

data/lib/olibrary/client/recent.rb

@@ -0,0 +1,9 @@
+module Olibrary
+  module Recent
+    # Get an array of recent changes to Open Library
+    #
+    def recent
+      data = request("/recentchanges")
+    end
+  end
+end

data/lib/olibrary/client/save.rb

@@ -0,0 +1,18 @@
+module Olibrary
+  module Save
+    # Save changes to Open Library
+    # 
+    # key     - Open Library object key
+    # cookie  - Cookie retrieved by login method
+    # update  - Complete, updated Open Library JSON object
+    # comment - String comment describing the changes
+    #
+    # Note that 'update' can reference an external JSON file or 
+    # a properly formatted Ruby object.
+    #
+    def save(key, cookie, update, comment)
+      response = update("#{key}", "#{cookie}", "#{update}", "#{comment}")
+      Hashie::Mash.new(response)
+    end
+  end
+end

data/lib/olibrary/client/search.rb

@@ -0,0 +1,50 @@
+module Olibrary
+  module Search
+    # Robust access to the Olibrary free-text search.
+    #
+    # A simple search is converted to a cross field query.
+    # @example search("A brief history of time")
+    #
+    # You can add multiple requirements to a single parameter by including a comma within the string.
+    # @example: search({subject: "Science, Physics"}) will find all books with both science AND physics as subjects)
+    #
+    # Likewise you can combine multiple parameters to refine your results
+    # @example search({title:"A Brief History of Time", subject: "Science, Physics", author: "Stephen Hawking"})
+    #
+    # Possible search parameter keys include
+    # :q (cross-field query)
+    # :author
+    # :publisher
+    # :isbn
+    # :title
+    # :person
+    # :place
+    # :subject
+    # @param limit defaults to 10 but can be set to any number or nil for all. OpenLibrary returns results in batches of 100 so a limit greater than that will make subsequent requests until the limit or end of results is reached. Be warned that high limits on broad queries will take considerable time and return large data sets.
+    # @param offset is useful if you want to continue a search from a given offset.
+    #
+    # @return An array of documents matching the query with all attributes accessible via method calls. Additional convenience methods 'book' and 'authors' are procs for retrieving the full document for the book and authors respectively. Usage: results[0].book.call() => client.book(results[0]['cover_edition_key'])
+    def search(search_params, limit = 10, offset = 0)
+      processed_params = search_params.is_a?(String) ? { q: search_params } : search_params
+      _search(processed_params, limit, offset)
+    end
+
+    private
+
+    def _search(search_params, limit, offset)
+      results = []
+      loop do
+        data = request('/search.json', params: search_params.merge({ limit: limit, offset: offset }))
+        data['docs'].each do |result|
+          result['book'] = -> { book(result['cover_edition_key']) }
+          result['authors'] = -> { result['author_key'].map { |key| author(key) } }
+          results << Hashie::Mash.new(result)
+        end
+        offset = data['offset'] + data['docs'].count
+        break if offset >= data['numFound'] || results.count >= limit
+      end
+      results
+    end
+
+  end
+end

data/lib/olibrary/client.rb

@@ -0,0 +1,31 @@
+require_relative 'request'
+require_relative 'client/books'
+require_relative 'client/authors'
+require_relative 'client/history'
+require_relative 'client/recent'
+require_relative 'client/editions'
+require_relative 'client/search'
+require_relative 'client/login'
+require_relative 'client/save'
+
+module Olibrary
+  class Client
+    include Olibrary::Request
+    include Olibrary::Books
+    include Olibrary::Authors
+    include Olibrary::History
+    include Olibrary::Recent
+    include Olibrary::Editions
+    include Olibrary::Search
+    include Olibrary::Login
+    include Olibrary::Save
+
+    # Initialize an Olibrary::Client instance
+    #
+    def initialize(options={})
+      unless options.kind_of?(Hash)
+        raise ArgumentError, "Options hash required."
+      end
+    end
+  end
+end

data/lib/olibrary/data.rb

@@ -0,0 +1,76 @@
+module Olibrary
+
+  class Data 
+    attr_accessor :url
+    attr_accessor :title
+    attr_accessor :subtitle
+    attr_accessor :authors
+    attr_accessor :identifiers
+    attr_accessor :classifications
+    attr_accessor :subjects, :subject_places, :subject_people, :subject_times
+    attr_accessor :publishers, :publish_places
+    attr_accessor :publish_date
+    attr_accessor :excerpts
+    attr_accessor :links
+    attr_accessor :cover
+    attr_accessor :ebooks
+    attr_accessor :pages
+    attr_accessor :weight
+
+    def self.find_by_isbn(key)
+      find("ISBN",key)
+    end
+
+    def self.find_by_lccn(key)
+      find("LCCN",key)
+    end
+
+    def self.find_by_oclc(key)
+      find("OCLC",key)
+    end
+
+    def self.find_by_olid(key)
+      find("OLID",key)
+    end
+
+    def self.find(type,key)
+      type_for_uri = URI.encode_www_form_component(type)
+      key_for_uri = URI.encode_www_form_component(key)
+
+      response = RestClient.get "http://openlibrary.org/api/books" +
+        "?bibkeys=#{type_for_uri}:#{key_for_uri}&format=json&jscmd=data"
+      response_data = JSON.parse(response)
+      book = response_data["#{type}:#{key}"]
+
+      if book 
+        book_meta = new  
+
+        book_meta.title = book["title"] 
+        book_meta.subtitle = book["subtitle"]
+        book_meta.authors = book["authors"]
+        book_meta.identifiers = book["identifiers"]
+        book_meta.classifications = book["classifications"]
+        book_meta.subjects = book["subjects"]
+        book_meta.subject_places = book["subject_places"]
+        book_meta.subject_people = book["subject_people"]
+        book_meta.subject_times = book["subject_times"]
+        book_meta.publishers = book["publishers"]
+        book_meta.publish_places = book["publish_places"]
+        book_meta.publish_date = book["publish_date"]
+        book_meta.excerpts = book["excerpts"]
+        book_meta.links = book["links"]
+        book_meta.cover = book["cover"]
+        book_meta.ebooks = book["ebooks"]
+        book_meta.pages = book["number_of_pages"]
+        book_meta.weight = book["weight"]
+        
+        book_meta
+      else
+        nil
+      end    
+    end
+  end
+
+
+end
+

data/lib/olibrary/details.rb

@@ -0,0 +1,53 @@
+module Olibrary
+
+  class Details 
+    attr_accessor :info_url
+    attr_accessor :bib_key
+    attr_accessor :preview_url
+    attr_accessor :thumbnail_url
+    attr_accessor :details
+
+    def self.find_by_isbn(key)
+      find("ISBN",key)
+    end
+
+    def self.find_by_lccn(key)
+      find("LCCN",key)
+    end
+
+    def self.find_by_oclc(key)
+      find("OCLC",key)
+    end
+
+    def self.find_by_olid(key)
+      find("OLID",key)
+    end
+
+    def self.find(type,key)
+      type_for_uri = URI.encode_www_form_component(type)
+      key_for_uri = URI.encode_www_form_component(key)
+
+      response = RestClient.get "http://openlibrary.org/api/books" +
+        "?bibkeys=#{type_for_uri}:#{key_for_uri}&format=json&jscmd=data"
+      response_data = JSON.parse(response)
+      book = response_data["#{type}:#{key}"]
+
+      if book 
+        book_meta = new  
+
+        book_meta.info_url = book["info_url"]
+        book_meta.bib_key = book["bib_key"]
+        book_meta.preview_url = book["preview_url"]
+        book_meta.thumbnail_url = book["thumbnail_url"]
+        book_meta.details = book["details"]
+        
+        book_meta
+      else
+        nil
+      end    
+    end
+  end
+
+
+end
+

data/lib/olibrary/errors.rb

@@ -0,0 +1,6 @@
+module Olibrary
+  class Error         < StandardError; end
+  class Unauthorized  < Error; end
+  class NotFound      < Error; end
+  class Redirect      < Error; end
+end