dewey 0.1.4 → 0.2.0

data/CHANGELOG.md

@@ -1,8 +1,37 @@
+## 0.2.0 (October 20, 2010)
+
+Additions:
+  
+  - Class-wide authentication. You only have to set up authentication once and
+    then utilize that in all successive calls.
+  - All file operations are stateless (Dewey.put, Dewey.get, etc)
+  - Store multiple authorizations simultaneously.
+  
+Changes:
+
+  - Convert API change. Format is required, not an option.
+  - No longer supports upload or download, instead use put or get.
+
+## 0.1.4 (October 19, 2010)
+  
+Additions:
+  
+  - Handle bad mimetypes.
+  - Modular validation
+  - Removed service option, needless.
+  - Automatic implicit authorization, removes need to call authorize! manually.
+
+Bugfixes:
+  
+  - Prevent peer certificate warnings in 1.9
+  - Fixed id extraction regex that prevented resources with dashes or underscores
+    from being pulled.
+
 ## 0.1.3 (June 29, 2010)
 
 Bugfixes:
 
-  - Handle mime type changes for files with no extension
+  - Handle mime type changes for files with no extension.
 
 ## 0.1.2 (June 28, 2010)
 

data/README.md

@@ -15,32 +15,49 @@ Let Google do all of the hard work of converting your documents!
 
 Dewey is in alpha. It is not recommended you use this in production code.
 
-## Getting Started
+## Authorization
 
-First, create a new Dewey::Document instance using your google docs account and
-password.
+You can configure Dewey to connect with either ClientLogin or OAuth. If you choose
+OAuth you'll only have to authenticate the first time you connect and subsequent
+connections will use the saved token.
 
-    dewey = Dewey::Document.new(:account => 'example.account', :password => 'example')
+ClientLogin
 
-Next, choose a local document to upload or convert.
+    Dewey.authorization :client, :email => 'example@gmail.com', :password => 'password'
+    
+OAuth
 
-    document = File.new('my_document.doc')
-    spreadsheet = File.new('my_spreadsheet.xls')
+    Dewey.authorization :oauth, :idontknowwhatgoeshereyet
+
+## File Operations
+
+You can put, get, delete and convert documents, spreadsheets or presentations in
+any of the formats that Docs accepts. There is a full listing in dewey/validations.rb
+or available here: http://code.google.com/apis/documents/faq.html#WhatKindOfFilesCanIUpload
 
-Finally, handle the upload, download, and delete manually or use the convenient
-`convert` method.
+Be sure to set up authorization before attempting any file operations! You don't
+need to explictely call authorize though, as it will attempt to do that on the
+first operation.
 
-    dewey.convert(document, :html)
-    dewey.convert(spreadsheet, :csv)
+Putting a document:
+
+    document = File.new('my_document.doc')
+    resource = Dewey.put(document, 'My First Upload') # Returns the id when successful
 
-## Testing
+Getting a document:
 
-Until testing is converted to an offline solution you will have to provide some
-credentials for testing. All that is required is a valid Google Docs account, no
-fussing about with getting an application API.
+    # Upload your file
+    id = Dewey.put(File.new('my_document.doc'), 'My Second Upload')
+    
+    # Get it in various formats
+    original = Dewey.get(id)     # -> Tempfile
+    pdf  = Dewey.get(id, :pdf)   # -> Tempfile
+    html = Dewey.get(id, :html)  # -> Tempfile
+    
+    # A tempfile is returned, so you'll have to move it
+    FileUtils.mv html.path, 'path/to/destination'
 
-By default the spec will look for a file called dewey.yml inside of the spec 
-folder. The file should contain two lines:
+Deleting a document:
 
-    email: <your gmail account>
-    password: <your gmail password>
+    id = Dewey.put(File.new('my_spreadsheet.xls'))
+    result = Dewey.delete(id) # -> true

data/lib/dewey.rb

@@ -1,13 +1,3 @@
-require 'uri'
-require 'net/https'
-require 'open-uri'
-require 'rexml/document'
-require 'tempfile'
-require 'dewey/https'
-require 'dewey/mime'
-require 'dewey/utils'
-require 'dewey/validation'
-
 module Dewey
   GOOGLE_DOCS_URL  = "https://docs.google.com"
   GOOGLE_SPRD_URL  = "https://spreadsheets.google.com"
@@ -17,193 +7,14 @@ module Dewey
   GOOGLE_DOCUMENT_URL    = GOOGLE_DOCS_URL + "/feeds/download/documents/Export"
   GOOGLE_SPREADSHEET_URL = GOOGLE_SPRD_URL + "/feeds/download/spreadsheets/Export"
   
-  class DeweyException < Exception
-  end
-  
-  # Doc
-  # This base class handles authentication and requests
-  #
-  class Document
-    attr_accessor :account, :password, :token
-    
-    # Create a new Doc object
-    # Options specified in +opts+ consist of:
-    #
-    # * :account - The Google Doc's account that will be used for authentication.
-    #   This will most typically be a gmail account, i.e. +example@gmail.com+
-    # * :password - The password for the Google Doc's account.
-    def initialize(options = {})
-      @account  = options[:account]
-      @password = options[:password]
-    end
-    
-    # Returns true if this instance has been authorized
-    def authorized?
-      !! @token
-    end
-    
-    # Gets an authorization token for this instance. Raises an error if no
-    # credentials have been provided, +false+ if authorization fails, and +true+ if
-    # authorization is successful.
-    def authorize!
-      if @account.nil? || @password.nil?
-        raise DeweyException, "Account or password missing."
-      end
-      
-      url = URI.parse(GOOGLE_LOGIN_URL)
-      params = { 'accountType' => 'HOSTED_OR_GOOGLE', 'Email' => @account,
-                 'Passwd' => @password, 'service'=> 'writely' }
-      
-      response = Net::HTTPS.post_form(url, params)
-      
-      case response
-      when Net::HTTPSuccess
-        @token = response.body.split(/=/).last
-        true
-      when Net::HTTPForbidden
-        false
-      else
-        raise DeweyException, "Unexpected response: #{response}"
-      end
-    end
-    
-    # Upload a file to the account. A successful upload will return the resource
-    # id, which is useful for downloading the file without doing a title search.
-    # * file  - A File reference
-    # * title - An alternative title, to be used instead of the filename
-    def put(file, title = nil)
-      authorize! unless authorized?
-      
-      extension = File.extname(file.path).sub('.', '')
-      basename  = File.basename(file.path, ".#{extension}")
-      mimetype  = Dewey::Mime.mime_type(file)
-      service   = Dewey::Mime.guess_service(mimetype)
-      
-      title ||= basename
-      
-      raise DeweyException, "Invalid file type: #{extension}" unless Dewey::Validation.valid_upload_format?(extension, service)
-      
-      headers = base_headers
-      headers['Content-Length'] = File.size?(file).to_s
-      headers['Slug']           = Dewey::Utils.escape(title)
-      headers['Content-Type']   = mimetype unless mimetype =~ /Can't expand summary_info/
-      
-      # Rewind the file in the case of multiple uploads, or conversions
-      file.rewind
-      
-      response = post_request(GOOGLE_FEED_URL, file.read.to_s, headers)
-      
-      case response
-      when Net::HTTPCreated
-        extract_rid(response.body)
-      else
-        nil
-      end
-    end
-    
-    alias :upload :put
-    
-    # Download, or export more accurately, a file to a specified format
-    # * rid    - A resource id, for example +document:12345+
-    # * format - The output format, see *_EXPORT_FORMATS for possiblibilites
-    def get(rid, format = nil)
-      authorize! unless authorized?
-      
-      spreadsheet = !! rid.match(/^spreadsheet/)
-      id = rid.sub(/[a-z]+:/, '')
-      
-      url  = ''
-      url << (spreadsheet ? GOOGLE_SPREADSHEET_URL : GOOGLE_DOCUMENT_URL)
-      url << (spreadsheet ? "?key=#{id}" : "?docID=#{id}")
-      url << "&exportFormat=#{format.to_s}" unless format.nil?
-      
-      headers = base_headers
-      
-      file = Tempfile.new([rid, format].join('.'))
-      file.binmode
-      
-      open(url, headers) { |data| file.write data.read }
-      
-      file
-    end
-    
-    alias :download :get
-    
-    # Deletes a document referenced either by resource id or by name.
-    # * id - A resource id or exact file name matching a document in the account
-    def delete(id)
-      authorize! unless authorized?
-      
-      headers = base_headers
-      headers['If-Match'] = '*' # We don't care if others have modified
-      
-      url = GOOGLE_FEED_URL + "/#{Dewey::Utils.escape(id)}?delete=true"
-      response = delete_request(url, headers)
-      
-      case response
-      when Net::HTTPOK
-        true
-      else
-        false
-      end
-    end
-    
-    # Convenience method for +upload+, +download+, +delete+. Returns a Tempfile
-    # with in the provided type.
-    # * file    - The file that will be converted
-    # * options - Takes :title and :format. See +upload+ for title, and +download+
-    #             for format.
-    def convert(file, options = {})
-      rid = upload(file, options[:title])
-      con = download(rid, options[:format])
-      
-      delete(rid)
-      
-      con
-    end
-    
-    private
-    
-    def post_request(url, data, headers) #:nodoc:
-      http_request(:post, url, headers, data)
-    end
-    
-    def delete_request(url, headers) #:nodoc:
-      http_request(:delete, url, headers)
-    end
-    
-    def http_request(method, url, headers, data = nil) #:nodoc:      
-      url = URI.parse(url) if url.kind_of? String
+  class DeweyException < Exception; end
+  class DeweyAuthorizationException < Exception; end
+end
 
-      connection = (url.scheme == 'https') ? Net::HTTPS.new(url.host, url.port) : Net::HTTP.new(url.host, url.port)
-      
-      case method
-      when :post
-        connection.post(url.path, data, headers)
-      when :delete
-        connection.delete(url.path, headers)
-      else
-        raise DeweyException, "Invalid request type. Valid options are :post and :delete"
-      end
-    end
-    
-    def base_headers #:nodoc:
-      base = {}
-      base['GData-Version'] = '3.0'
-      base['Content-Type']  = 'application/x-www-form-urlencoded'
-      base['Authorization'] = "GoogleLogin auth=#{@token}" if authorized?
-      
-      base
-    end
-    
-    def extract_rid(response) #:nodoc:
-      xml = REXML::Document.new(response)
-      
-      begin
-        "#{$1}:#{$2}" if xml.elements['//id'].text =~ /.+(document|spreadsheet|presentation)%3A([0-9a-zA-Z_-]+)$/
-      rescue 
-        raise DeweyException, "id could not be extracted from: #{response}"
-      end
-    end
-  end
-end
+require 'dewey/core'
+require 'dewey/client_auth'
+require 'dewey/https'
+require 'dewey/mime'
+require 'dewey/utils'
+require 'dewey/validation'
+require 'dewey/version'

data/lib/dewey/client_auth.rb

@@ -0,0 +1,48 @@
+module Dewey
+  class ClientAuth
+    attr_reader :authentications
+
+    def initialize(email, password) 
+      @email          = email
+      @password       = password
+      @authentications = {}
+    end
+
+    def authenticated?(service = nil)
+      if service
+        @authentications.has_key?(service)
+      else
+        @authentications.any? 
+      end
+    end
+    
+    def authenticate!(service = nil)
+      service ||= :writely
+
+
+      params = { 'accountType' => 'HOSTED_OR_GOOGLE',
+                 'Email'       => @email,
+                 'Passwd'      => @password,
+                 'service'     => service.to_s
+              }
+
+      url      = URI.parse(Dewey::GOOGLE_LOGIN_URL)
+      response = Net::HTTPS.post_form(url, params)
+
+      case response
+      when Net::HTTPSuccess
+        @authentications[service] = response.body.split('=').last
+        true
+      when Net::HTTPForbidden
+        false
+      else
+        raise DeweyAuthorizationException, "Unexpected response: #{response}"
+      end
+    end
+    
+    def token(service = nil)
+      @authentications[service || :writely]
+    end
+  end
+end
+

data/lib/dewey/core.rb

@@ -0,0 +1,158 @@
+require 'uri'
+require 'net/https'
+require 'open-uri'
+require 'rexml/document'
+require 'tempfile'
+
+module Dewey
+  class << self
+    def authentication(strategy, options)
+      case strategy
+      when :client
+        @@authenticator = Dewey::ClientAuth.new(options[:email], options[:password])
+      end
+    end
+    
+    def authenticated?
+      !@@authenticator.nil? && @@authenticator.authenticated?
+    end
+    
+    def authenticate!
+      @@authenticator.authenticate!
+    end
+    
+    # Upload a file to the account. A successful upload will return the resource
+    # id, which is useful for downloading the file without doing a title search.
+    # * file  - A File reference
+    # * title - An alternative title, to be used instead of the filename
+    def put(file, title = nil)
+      authenticate! unless authenticated?
+  
+      extension = File.extname(file.path).sub('.', '')
+      basename  = File.basename(file.path, ".#{extension}")
+      mimetype  = Dewey::Mime.mime_type(file)
+      service   = Dewey::Mime.guess_service(mimetype)
+  
+      title ||= basename
+  
+      raise DeweyException, "Invalid file type: #{extension}" unless Dewey::Validation.valid_upload_format?(extension, service)
+  
+      headers = base_headers
+      headers['Content-Length'] = File.size?(file).to_s
+      headers['Slug']           = Dewey::Utils.escape(title)
+      headers['Content-Type']   = mimetype unless mimetype =~ /Can't expand summary_info/
+  
+      # Rewind the file in the case of multiple uploads, or conversions
+      file.rewind
+  
+      response = post_request(GOOGLE_FEED_URL, file.read.to_s, headers)
+  
+      case response
+      when Net::HTTPCreated
+        extract_rid(response.body)
+      else
+        false
+      end
+    end
+
+    # Download, or export more accurately, a file to a specified format
+    # * rid    - A resource id, for example +document:12345+
+    # * format - The output format, see *_EXPORT_FORMATS for possiblibilites
+    def get(rid, format = nil)
+      authenticate! unless authenticated?
+  
+      spreadsheet = !! rid.match(/^spreadsheet/)
+      id = rid.sub(/[a-z]+:/, '')
+  
+      url  = ''
+      url << (spreadsheet ? GOOGLE_SPREADSHEET_URL : GOOGLE_DOCUMENT_URL)
+      url << (spreadsheet ? "?key=#{id}" : "?docID=#{id}")
+      url << "&exportFormat=#{format.to_s}" unless format.nil?
+  
+      headers = base_headers
+  
+      file = Tempfile.new([rid, format].join('.'))
+      file.binmode
+  
+      open(url, headers) { |data| file.write data.read }
+  
+      file
+    end
+
+    # Deletes a document referenced either by resource id or by name.
+    # * id - A resource id or exact file name matching a document in the account
+    def delete(id)
+      authenticate! unless authenticated?
+  
+      headers = base_headers
+      headers['If-Match'] = '*' # We don't care if others have modified
+  
+      url = GOOGLE_FEED_URL + "/#{Dewey::Utils.escape(id)}?delete=true"
+      response = delete_request(url, headers)
+  
+      case response
+      when Net::HTTPOK
+        true
+      else
+        false
+      end
+    end
+
+    # Convenience method for +put+, +get+, +delete+. Returns a Tempfile
+    # with in the provided type. Note that if you omit the format option it will
+    # simply upload the file and return it.
+    # * file    - The file that will be converted
+    # * options - Takes :title and :format. See +upload+ for title, and +download+
+    #             for format.
+    def convert(file, options = {})
+      rid = put(file, options[:title])
+      con = get(rid, options[:format])
+  
+      delete(rid)
+  
+      con
+    end
+
+    def post_request(url, data, headers) #:nodoc:
+      http_request(:post, url, headers, data)
+    end
+
+    def delete_request(url, headers) #:nodoc:
+      http_request(:delete, url, headers)
+    end
+
+    def http_request(method, url, headers, data = nil) #:nodoc:      
+      url = URI.parse(url) if url.kind_of? String
+
+      connection = (url.scheme == 'https') ? Net::HTTPS.new(url.host, url.port) : Net::HTTP.new(url.host, url.port)
+  
+      case method
+      when :post
+        connection.post(url.path, data, headers)
+      when :delete
+        connection.delete(url.path, headers)
+      else
+        raise DeweyException, "Invalid request type. Valid options are :post and :delete"
+      end
+    end
+
+    def base_headers #:nodoc:
+      base = {}
+      base['GData-Version'] = '3.0'
+      base['Content-Type']  = 'application/x-www-form-urlencoded'
+      base['Authorization'] = "GoogleLogin auth=#{@@authenticator.token}" if authenticated?
+  
+      base
+    end
+
+    def extract_rid(response) #:nodoc:
+      xml = REXML::Document.new(response)
+  
+      begin
+        "#{$1}:#{$2}" if xml.elements['//id'].text =~ /.*(document|spreadsheet|presentation)%3A([0-9a-zA-Z_-]+)$/
+      rescue 
+        raise DeweyException, "id could not be extracted from: #{response}"
+      end
+    end
+  end
+end

data/lib/dewey/version.rb

@@ -0,0 +1,3 @@
+module Dewey
+  VERSION = '0.2.0'
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 4
-  version: 0.1.4
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Parker Selbert
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-19 00:00:00 -05:00
+date: 2010-10-23 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -40,14 +40,16 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- lib/dewey/client_auth.rb
+- lib/dewey/core.rb
 - lib/dewey/https.rb
 - lib/dewey/mime.rb
 - lib/dewey/utils.rb
 - lib/dewey/validation.rb
+- lib/dewey/version.rb
 - lib/dewey.rb
 - README.md
 - CHANGELOG.md
-- TODO.md
 has_rdoc: true
 homepage: http://github.com/sorentwo/dewey
 licenses: []

data/TODO.md

@@ -1,5 +0,0 @@
-## Dewey TODO List
-  - Implement the OAuth gem to manage service switching
-  - Add presentation support
-  - Documents: list
-  - Add support for folders