rscribd 0.0.2 → 0.0.3

data/lib/scribd/base.rb

@@ -1,381 +0,0 @@
-#!/usr/bin/env ruby
-
-require 'md5'
-require 'rexml/document'
-require 'net/http'
-require 'parsedate'
-
-# Main Scribd API class
-class Scribd
-  # Default API key
-  API_KEY = ''
-  
-  # Default API signature
-  API_SIG = ''
-  
-  # Default API endpoint
-  ENDPOINT = 'http://tikhon.com/api'
-
-  # Number of tries to call a method
-  TRIES = 3
-  
-  attr_reader :api_key, :host, :port, :path
-  attr_accessor :async, :debug
-
-  # Outputs whatever is given into the $stderr if debugging is enabled.
-  #
-  # Parameters:
-  #   args - content to output
-  def debug(*args) $stderr.puts(sprintf(*args)) if @debug end
-
-  # Initializes API
-  #
-  # Parameters:
-  #   api_key  - API key to use
-  #   api_sig  - API signature to use
-  #   endpoint - API endpoint, 
-  def initialize(api_key = API_KEY, api_sig = API_SIG, endpoint = ENDPOINT)
-    @async = false
-
-    @api_key = api_key
-    @api_sig = api_sig
-    @endpoint = endpoint
-
-    proto, @host, @port, @path, user, pass = parse_url(@endpoint)
-    raise ProtoUnknownError.new("Unhandled protocol '#{proto}'") if proto.downcase != 'http'
-  end
-
-  # Returns Docs API interface.
-  def docs() @docs ||= Docs.new(self) end
-  
-  # Returns Search API interface.
-  def search() @search || Search.new(self) end
-
-  # Sends the HTTP form to the server API with the given fields.
-  #
-  # Parameters:
-  #   method - method name.
-  #   fields - the Hash of field names to field values. If a field requires
-  #            its mime-type set, you specify its value in array where the
-  #            first element is value, the second is mime-type, and the third
-  #            is file name, like this:
-  #            Simple value: :user => 'john', :pass => 'nhoj'
-  #            Typed value : :user => 'john', :file => [data, type, name]
-  #                     or : ... :file => { :data => data, :mimetype => type, :filename => 'test.txt' }
-  #            
-  # Returns:
-  #   REXML::Document with the response of the server.
-  #   
-  # Raises:
-  #   Scribd::ResponseError upon getting the 'fail' code from the server API.
-  #   Timeout::Error if unable to connect to the server.
-  #
-  def send_form(method, fields)
-    # See if method is given
-    raise ArgumentError, "Method should be given" if method.nil? || method.empty?
-
-    # Complete fields with the method name
-    fields = {} if fields.nil?
-    fields['method'] = method
-    
-    # Create a multi-part form from given fields
-    form = Scribd::MultiPartForm.new
-    form.parts = prepare_parts(fields)
-
-    debug(form.to_s)
-
-    # Configure proper boundary in the headers
-    headers = { "Content-Type" => "multipart/form-data; boundary=" + form.boundary }
-
-    # Create the connection
-    http = Net::HTTP.new(host, port)
-    # TODO configure timeouts through the properties
-    #		http.read_timeout = 900 # 15 minutes max upload time
-
-    tries = TRIES
-    begin
-      tries -= 1
-      res = http.post(path, form.to_s, headers)
-    rescue Timeout::Error => err
-      $stderr.puts "Timed out, will retry #{tries} more."
-      retry if tries > 0
-      raise err
-    end
-    
-    debug(res.body)
-
-    # Convert response into XML
-    xml = REXML::Document.new(res.body)
-    
-    # See if there was an error and raise an exception
-    if xml.elements['/rsp'].attributes['stat'] == 'fail'
-      # Load default code and error
-      code, message = -1, "Unidentified error:\n#{res.body}"
-
-      # Get actual error code and message
-      err = xml.elements['/rsp/error']
-      code, message = err.attributes['code'], err.attributes['message'] if err
-
-      # Add more data
-      message = "Method: #{method} Response: code=#{code} message=#{message}"
-      
-      raise Scribd::ResponseError.new(code), message
-    end
-    
-    return xml
-  end
-
-  private
-  
-  # Sign the arguments hash with our very own signature.
-  #
-  # Parameters:
-  #   args - method arguments to be sent to the server API
-  # 
-  # Returns:
-  #   signature
-  #
-  def sign(args)
-    return MD5.md5(@api_sig + args.sort.flatten.join).to_s
-  end
-
-  # Parses given URL into pieces
-  # 
-  # Parameters:
-  #   url - URL to parse
-  # 
-  # Returns:
-  #   array of protocol, host, port, path, user, and password
-  #
-  def parse_url(url)
-    url =~ /([^:]+):\/\/([^\/]*)(.*)/
-    proto = $1.to_s
-    hostplus = $2.to_s
-    path = $3.to_s
-
-    hostplus =~ /(?:(.*)@)?(.*)/
-    userpass = $1
-    hostport = $2
-    user, pass = userpass.to_s.split(':', 2)
-    host, port = hostport.to_s.split(':', 2)
-    port = port ? port.to_i : 80
-
-    return proto, host, port, path, user, pass
-  end
-
-  # Prepares a list of parts for a multi-part form.
-  # The signature is added to the end of the list as a part.
-  # Fields with mime-type set are ignored during the signature calculation.
-  #
-  # Parameters:
-  #   fields - the Hash of field names to field values. If a field requires
-  #            its mime-type set, you specify its value in array where the
-  #            first element is value, the second is mime-type, and the third
-  #            is file name, like this:
-  #            Simple value: :user => 'john', :pass => 'nhoj'
-  #            Typed value : :user => 'john', :file => [data, type, name]
-  #                     or : ... :file => { :data => data, :mimetype => type, :filename => 'test.txt' }
-  #            
-  # Returns:
-  #   array of Scribd::FormPart objects
-  #
-  def prepare_parts(fields)
-    # Parameter check
-    raise "Fields must be a Hash" unless fields.nil? || fields.class == Hash
-    
-    # Build the list of form parts and the list of non-typed
-    # arguments in parallel. The list of arguments will be used
-    # for the signature calculation.
-    parts = []
-    args = {}
-    fields.each do |k, v|
-      if v.class == Array
-        data, mimetype, filename = v
-      elsif v.class == Hash
-        data, mimetype, filename = v[:data], v[:mimetype], v[:filename]
-      else
-        data = v.to_s
-      end
-      
-      parts << Scribd::FormPart.new(k.to_s, data, mimetype, filename)
-
-      # We don't place fields with mime-type set into the array
-      # as they usually are files and other binary data we don't
-      # want to hash.
-      args[k.to_s] = v.to_s if mimetype.nil?
-    end
-    parts << Scribd::FormPart.new('api_key', api_key)
-
-    # Add the key and calculate the signature
-    args['api_key'] = api_key
-    parts << Scribd::FormPart.new('api_sig', sign(args))
-    
-    return parts
-  end
-end
-
-# Base class for API groups
-class Scribd::APIBase  
-  attr_reader :scribd
-
-  # Initializes API group
-  def initialize(scribd) @scribd = scribd end
-
-  protected 
-
-  # FIXME: Since we don't need XMLRPC, the exception could be different
-  # TODO: It would probably be better if we wrapped the fault
-  # in something more meaningful. At the very least, a broad
-  # division of errors, such as retryable and fatal. 
-  def error(el)
-    att = el.attributes
-    fe = XMLRPC::FaultException.new(att['code'].to_i, att['msg'])
-    $stderr.puts "ERR: #{fe.faultString} (#{fe.faultCode})"
-    raise fe
-  end
-
-  # Checks if a string parameter is given and not empty.
-  # 
-  # Parameters:
-  #   name  - parameter name for an error message.
-  #   value - value.
-  #   
-  # Raises:
-  #   ArgumentError if the value is nil, or empty.
-  #
-  def check_not_empty(name, value)
-    check_given(name, value)
-    raise ArgumentError, "#{name} must not be empty" if value.to_s.empty?
-  end
-
-  # Checks an integer parameter for being given, being a number,
-  # and being within the range.
-  # 
-  # Parameters:
-  #   name  - parameter name for an error message.
-  #   value - value.
-  #   min   - range minimum.
-  #   max   - range maximum.
-  # 
-  # Raises:
-  #   ArgumentError if the value is nil, not Fixnum, or outside the [min, max] range.
-  #
-  def check_in_range(name, value, min, max)
-    check_given(name, value)
-    raise ArgumentError, "#{name} is not a number" if value.class != Fixnum
-    raise ArgumentError, "#{name} is out of range [#{min}, #{max}]" if value < min || value > max
-  end
-
-  # Checks the value for being given, and being mentioned in the list.
-  # 
-  # Parameters:
-  #   name    - parameter name for an error message.
-  #   value   - value.
-  #   allowed - list of allowed values.
-  #   
-  # Raises:
-  #   ArgumentError if the value is nil, or not among the allowed values.
-  #
-  def check_allowed(name, value, allowed)
-    check_given(name, value)
-    raise ArgumentError, "#{name} is out of range #{allowed.inspect}" unless allowed.include?(value.to_sym)
-  end
-
-  # Checks if the value is given.
-  #
-  # Parameters:
-  #   name  - parameter name for an error message.
-  #   value - value.
-  #   
-  # Raises:
-  #   ArgumentError if the value is nil.
-  #
-  def check_given(name, value)
-    raise ArgumentError, "#{name} must be given" if value.nil?
-  end
-end
-
-# Form part class represents a single block of attributes, or
-# file or other part of the form.
-class Scribd::FormPart
-  attr_reader :data, :mime_type, :attributes
-
-  # Initializes the part.
-  # 
-  # Parameters:
-  #   name      - name
-  #   data      - data
-  #   mime_type - optional type of the form part
-  #   filename  - optional name of the file (use with mime-type)
-  #
-  def initialize(name, data, mime_type = nil, filename = nil)
-    @attributes = {}
-    @attributes['name'] = name
-    @attributes['filename'] = filename unless filename.nil?
-    @data = data
-    @mime_type = mime_type
-  end
-
-  # Returns string representation.
-  def to_s
-    mime_present = @mime_type.nil? || @mime_type.empty?
-    
-    # Disposition
-    fld_disposition = "Content-Disposition: form-data"
-    attributes.each { |k, v| fld_disposition += "; #{k}=\"#{v}\"" }
-
-    # Fields
-    fields = [ fld_disposition ]
-    unless mime_present
-      fields << "Content-Type: #{@mime_type}"
-      fields << "Content-Transfer-Encoding: binary"
-    end
-    
-    # Add empty line and data block
-    fields << ''
-    fields << data
-    
-    return fields.join("\r\n")
-  end
-end
-
-# Multi-part form object.
-class Scribd::MultiPartForm
-  attr_accessor :boundary, :parts
-
-  # Creates the form object.
-  # 
-  # Parameters:
-  #   boundary - optional boundary to use for parts separation
-  #
-  def initialize(boundary = nil)
-    @boundary = boundary || "----------------------------Ruby#{rand(1000000000000)}"
-    @parts = []
-  end
-
-  # Returns string representation.
-  def to_s
-    "--#@boundary\r\n" +
-    parts.map { |p| p.to_s }.join("\r\n--#@boundary\r\n") +
-    "\r\n--#@boundary--\r\n"
-  end
-end
-
-# Response error that indicates there was a problem during
-# processing your request to the server, which resulted in
-# the response with the 'fail' code.
-# 
-# You can find the code and the message inside.
-#
-class Scribd::ResponseError < RuntimeError
-  attr_reader :code
-  
-  # Initializes the error.
-  #
-  # Parameters:
-  #   code - error code.
-  #
-  def initialize(code)
-    @code = code
-  end
-end

data/lib/scribd/docs.rb

@@ -1,246 +0,0 @@
-require 'rubygems'
-require 'scribd/base'
-require 'mime/types'
-
-# Interface to the Docs server API
-class Scribd::Docs < Scribd::APIBase
-
-  DISPLAY_FORMAT    = [:html, :flash]
-  PARENTAL_ADVISORY = [:safe, :adult]
-  BOOLEAN           = [:true, :false]
-  ACCESS            = [:public, :private]
-  COMMENTING        = [:none, :allow]
-  
-  # Settings with their allowed values
-  SETTINGS = {
-    :display_format => DISPLAY_FORMAT,
-    :parental_advisory => PARENTAL_ADVISORY,
-    :access => ACCESS,
-    :commenting => COMMENTING,
-    :allow_word_download => BOOLEAN,
-    :allow_text_download => BOOLEAN,
-    :allow_pdf_download => BOOLEAN
-  }
-
-  # Uploads a file specified by its name (path) and returns the
-  # pair of document ID and GUID as an array. In addition to the
-  # file name, you need to specify document and access types.
-  # 
-  # Parameters:
-  #   filename - name of the file to upload.
-  #   doc_type - optional type of the document:
-  #              "pdf", "doc", "txt", "ppt", "pps", "xls", "ps", "htm",
-  #              "html", "rtf", "odt", "odp", "ods", "odg", "odf", "sxw",
-  #              "sxc", "sxi", "sxd", "jpg", "jpeg", "gif", "png"
-  #   public   - optional flag showing if the document is public (default)
-  #              or private.
-  # 
-  # Returns:
-  #   array with two elements: doc_id and doc_guid
-  # 
-  # Raises:
-  #   ArgumentError         if file name isn't given.
-  #   Scribd::ResponseError upon getting the 'fail' code from the server API.
-  #   Timeout::Error        if unable to connect to the server.
-  #
-  def upload(filename, doc_type = nil, public = nil)
-    # See if URL is given
-    check_not_empty('filename', filename)
-    
-    # Get file type and load its data
-    mimetype = MIME::Types.of(filename)
-    mimetype = 'application/octet-stream' if mimetype.nil? || mimetype.empty?
-    data = File.open(filename, 'rb').read
-
-    # Make a request form
-    fields = {}
-    fields[:file] = { :data => data, :mimetype => mimetype,
-                      :filename => File.basename(filename) }
-    
-    return upload_impl('docs.upload', fields, doc_type, public)
-  end
-  
-  # Uploads a file specified by an URL and returns the
-  # pair of document ID and GUID as an array. In addition to the
-  # file name, you need to specify document and access types.
-  # 
-  # Parameters:
-  #   url      - URL of the file to upload.
-  #   doc_type - optional type of the document:
-  #              "pdf", "doc", "txt", "ppt", "pps", "xls", "ps", "htm",
-  #              "html", "rtf", "odt", "odp", "ods", "odg", "odf", "sxw",
-  #              "sxc", "sxi", "sxd", "jpg", "jpeg", "gif", "png"
-  #   public   - optional flag showing if the document is public (default)
-  #              or private.
-  # 
-  # Returns:
-  #   array with two elements: doc_id and doc_guid
-  #   
-  # Raises:
-  #   ArgumentError         if URL isn't given.
-  #   Scribd::ResponseError upon getting the 'fail' code from the server API.
-  #   Timeout::Error        if unable to connect to the server.
-  #
-  def upload_from_url(url, doc_type = nil, public = nil)
-    # See if URL is given
-    check_not_empty('url', url)
-    
-    # Make a request form
-    fields = {}
-    fields[:url] = url
-    
-    return upload_impl('docs.uploadFromUrl', fields, doc_type, public)
-  end
-  
-  # Deletes a document from the repository by its ID.
-  # 
-  # Parameters:
-  #   doc_id - document ID.
-  #   
-  # Returns:
-  #   id of the deleted document.
-  #   
-  # Raises:
-  #   ArgumentError         if document ID isn't given.
-  #   Scribd::ResponseError upon getting the 'fail' code from the server API.
-  #   Timeout::Error        if unable to connect to the server.
-  #
-  def delete(doc_id)
-    # See if document ID is given
-    raise ArgumentError, "Document ID must be given" if doc_id.nil?
-    
-    # Send form and return the result
-    res = @scribd.send_form('docs.delete', :doc_id => doc_id)
-    return res.elements['/rsp/doc_id'].text
-  end
-  
-  # Returns the status of the document conversion.
-  # 
-  # Parameters:
-  #   doc_id - document ID.
-  #   
-  # Returns:
-  #   status string: "CONVERSION_ERROR", "CONVERTING", "ENCRYPTED_ERROR",
-  #   "FAILED_TO_CONVERT", "IN_QUEUE", "PUBLISHED", "UPLOADED".
-  #   
-  # Raises:
-  #   ArgumentError         if document ID isn't given.
-  #   Scribd::ResponseError upon getting the 'fail' code from the server API.
-  #   Timeout::Error        if unable to connect to the server.
-  #
-  def get_conversion_status(doc_id)
-    # See if document ID is given
-    check_given('doc_id', doc_id)
-    
-    # Send form and return the result
-    res = @scribd.send_form('docs.getConversionStatus', :doc_id => doc_id)
-    return res.elements['/rsp/conversion_status'].text
-  end
-
-  # Changes the settings of the document specified by its ID. The settings
-  # is a Hash with any number of settings key-pairs from the list below. If
-  # no settings are given, the method call isn't relayed to the server for
-  # the performance reasons.
-  # 
-  # Settings keys and values you can update with this method:
-  #   title               - document title.
-  #   description         - document description.
-  #   display_format      - "html" (for plain text, HTML and images),
-  #                         "flash" (for everything else). 
-  #   access              - "public" or "private"
-  #   language            - "ar", "bg", "da", "de", "en", "es", "fr", "he",
-  #                         "hu", "it", "ja", "ko", "nl", "no", "pt", "ro",
-  #                         "ru", "unknown" (default), "zh"
-  #   license             - "by", "by-nc" (Creative Commons), "by-nc-nd",
-  #                         "by-nc-sa", "by-nd", "by-sa",
-  #                         "c" (traditional copyright),
-  #                         "pd" (public domain)
-  #   allow_word_download - "true" or "false". Allow others to download a
-  #                         MS Word version of this document. Default: "true".
-  #   allow_text_download - "true" or "false". Allow others to download a
-  #                         plain text version of this document. Default: "true".
-  #   allow_pdf_download  - "true" or "false". Allow others to download a
-  #                         PDF version of this document. Default: "true".
-  #   commenting          - "none" or "allow". Allow others to comment. Default: "allow".
-  #   paretal_advisory    - "safe" or "adult". Default: "safe".
-  #   tags                - comma-separated list of tags. Tags cannot contain whitespace.
-  #   
-  # Parameters:
-  #   doc_id   - document ID.
-  #   settings - hash with any combination of above settings.
-  #   
-  # Returns:
-  #   id of the updated document.
-  #   
-  # Raises:
-  #   ArgumentError         if document ID isn't given.
-  #   Scribd::ResponseError upon getting the 'fail' code from the server API.
-  #   Timeout::Error        if unable to connect to the server.
-  #
-  def change_settings(doc_id, settings = nil)
-    # See if document ID is given
-    check_given('doc_id', doc_id)
-    check_settings(settings)
-    
-    # If settings aren't given, return. Otherwise see if they are given in a Hash
-    return doc_id if settings.nil? || (settings.class == Hash && settings.empty?)
-    raise ArgumentError, "Settings must be given in a Hash" if settings.class != Hash
-    
-    # Copy the settings as we'll be adding more keys to it
-    fields = settings.dup
-    fields[:doc_id] = doc_id
-
-    # Send the form and return the result
-    res = @scribd.send_form('docs.changeSettings', fields)
-    return res.elements['/rsp/doc_id'].text
-  end
-
-  private
-
-  # Checks if known settings are inside their allowed lists.
-  # 
-  # Parameters:
-  #   settings - Hash of settings to check, as given to #change_settings.
-  # 
-  # Raises:
-  #   ArgumentError if some setting is not given a value, or
-  #                 falls out of allowed set.
-  #
-  def check_settings(settings)
-    settings.each do |name, value|
-      allowed = SETTINGS[name.to_sym]
-
-      # If it's the setting we check, do it
-      unless allowed.nil?
-        check_given(name, value)
-        check_allowed(name, value, allowed)
-      end
-    end
-  end
-  
-  # Uploads the file.
-  #
-  # Parameters:
-  #   method   - method name.
-  #   fields   - method arguments.
-  #   doc_type - document type (see concrete methods for description).
-  #   public   - public / private boolean flag.
-  #   
-  # Returns:
-  #   array with two elements: doc_id and doc_guid
-  #   
-  def upload_impl(method, fields, doc_type, public)
-    fields = {} if fields.nil?
-    fields[:doc_type] = doc_type unless doc_type.nil?
-    fields[:access] = (public ? 'public' : 'private') unless public.nil?
-
-    # Send it and wait for the result
-    res = @scribd.send_form(method, fields)
-
-    # Extract our response
-    doc_id = res.elements['/rsp/doc_id'].text
-    doc_guid = res.elements['/rsp/doc_guid'].text
-    
-    return doc_id, doc_guid
-  end
-end

data/lib/scribd/search.rb

@@ -1,85 +0,0 @@
-require 'scribd/base'
-
-# Interface to the Search server API
-class Scribd::Search < Scribd::APIBase
-  
-  SORT_BY           = [:popularity, :relevance, :scribds, :time, :views]
-  SCOPE             = [:all, :api]
-  PARENTAL_ADVISORY = [:safe, :adult]
-
-  # Looks for documents matching a given query. Additional optional
-  # parameters can be used to control the output.
-  # 
-  # Parameters:
-  #   query             - query to pass to the server.
-  #   num_results       - desired maximum number of records to return [1-1000].
-  #   num_start         - first record in the result set to start from [1-1000].
-  #   sort_by           - order of sorting, default :relevance. See SORT_BY
-  #                       constant for the list of allowed values.
-  #   scope             - scope of search:
-  #                         :all   - all of Scribd
-  #                         :api   - only user documents
-  #   parental_advisory - filter for adult content:
-  #                         :safe  - no adult content
-  #                         :adult - everything
-  # 
-  # Returns:
-  #   list of Scribd::Document objects.
-  #   
-  # Raises:
-  #   ArgumentError         if query is not given, or
-  #                         num_results is out of range, or
-  #                         num_start is out of range, or
-  #                         sort_by is not one of allowed, or
-  #                         scope is not one of allowed, or
-  #                         parental_advisory is not one of allowed.
-  #   Scribd::ResponseError upon getting the 'fail' code from the server API.
-  #   Timeout::Error        if unable to connect to the server.
-  #
-  def docs(query, num_results = 10, num_start = 1, sort_by = :relevance,
-           scope = :all, parental_advisory = :safe)
-    
-    # Verify the parameters
-    check_not_empty('query', query)
-    check_in_range('num_results', num_results, 1, 1000)
-    check_in_range('num_start', num_start, 1, 1000)
-    check_allowed('sort_by', sort_by, SORT_BY)
-    check_allowed('scope', scope, SCOPE)
-    check_allowed('parental_advisory', parental_advisory, PARENTAL_ADVISORY)
-    
-    # Send the form
-    res = @scribd.send_form('search.docs', fields)
-    
-    # Get documents
-    documents = []
-    res.elements['/response/result_set/result'].each do |doc|
-      documents << Scribd::Document.new(
-        doc.elements['title'], 
-        doc.elements['description'], 
-        doc.elements['scribd_url'], 
-        doc.elements['doc_id'])
-    end
-    
-    return documents
-  end
-  end
-
-# Document returned from the search
-class Scribd::Document
-  attr_reader :title, :description, :scribd_url, :doc_id
-  
-  # Initializes a document.
-  # 
-  # Parameters:
-  #   title       - document title.
-  #   description - description.
-  #   scribd_url  - Scribd URL.
-  #   doc_id      - document ID.
-  #
-  def initialize(title, description, scribd_url, doc_id)
-    @title = title
-    @description = description
-    @scribd_url = scribd_url
-    @doc_id = doc_id
-  end
-end