google-api-client 0.4.7 → 0.5.0

data/lib/google/api_client/client_secrets.rb

@@ -20,8 +20,42 @@ require 'compat/multi_json'
 module Google
   class APIClient
     ##
-    # Manages the persistence of client configuration data and secrets.
+    # Manages the persistence of client configuration data and secrets. Format
+    # inspired by the Google API Python client.
+    #
+    # @see https://developers.google.com/api-client-library/python/guide/aaa_client_secrets
+    #
+    # @example
+    #   {
+    #     "web": {
+    #       "client_id": "asdfjasdljfasdkjf",
+    #       "client_secret": "1912308409123890",
+    #       "redirect_uris": ["https://www.example.com/oauth2callback"],
+    #       "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+    #       "token_uri": "https://accounts.google.com/o/oauth2/token"
+    #     }
+    #   }
+    #
+    # @example
+    #   {
+    #     "installed": {
+    #       "client_id": "837647042410-75ifg...usercontent.com",
+    #       "client_secret":"asdlkfjaskd",
+    #       "redirect_uris": ["http://localhost", "urn:ietf:oauth:2.0:oob"],
+    #       "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+    #       "token_uri": "https://accounts.google.com/o/oauth2/token"
+    #     }
+    #   }
     class ClientSecrets
+      
+      ##
+      # Reads client configuration from a file
+      #
+      # @param [String] filename
+      #   Path to file to load
+      #
+      # @return [Google::APIClient::ClientSecrets]
+      #   OAuth client settings
       def self.load(filename=nil)
         if filename && File.directory?(filename)
           search_path = File.expand_path(filename)
@@ -44,6 +78,11 @@ module Google
         return self.new(data)
       end
 
+      ##
+      # Intialize OAuth client settings.
+      #
+      # @param [Hash] options
+      #   Parsed client secrets files
       def initialize(options={})
         # Client auth configuration
         @flow = options[:flow] || options.keys.first.to_s || 'web'
@@ -77,6 +116,11 @@ module Google
         :refresh_token, :id_token, :expires_in, :expires_at, :issued_at
       )
 
+      ##
+      # Serialize back to the original JSON form
+      #
+      # @return [String]
+      #   JSON
       def to_json
         return MultiJson.dump({
           self.flow => ({

data/lib/google/api_client/discovery/api.rb

@@ -29,13 +29,9 @@ module Google
       ##
       # Creates a description of a particular version of a service.
       #
-      # @param [String] api
-      #   The identifier for the service.  Note that while this frequently
-      #   matches the first segment of all of the service's RPC names, this
-      #   should not be assumed.  There is no requirement that these match.
-      # @param [String] version
-      #   The identifier for the service version.
-      # @param [Hash] api_description
+      # @param [String] document_base
+      #   Base URI for the service
+      # @param [Hash] discovery_document
       #   The section of the discovery document that applies to this service
       #   version.
       #
@@ -57,6 +53,9 @@ module Google
           end
         end
       end
+      
+      # @return [String] unparsed discovery document for the API
+      attr_reader :discovery_document
 
       ##
       # Returns the id of the service.
@@ -159,7 +158,7 @@ module Google
       ##
       # Updates the hierarchy of resources and methods with the new base.
       #
-      # @param [Addressable::URI, #to_str, String] new_base
+      # @param [Addressable::URI, #to_str, String] new_method_base
       #   The new base URI to use for the service.
       def method_base=(new_method_base)
         @method_base = Addressable::URI.parse(new_method_base)

data/lib/google/api_client/discovery/method.rb

@@ -34,7 +34,7 @@ module Google
       #   The base URI for the service.
       # @param [String] method_name
       #   The identifier for the method.
-      # @param [Hash] method_description
+      # @param [Hash] discovery_document
       #   The section of the discovery document that applies to this method.
       #
       # @return [Google::APIClient::Method] The constructed method object.
@@ -45,6 +45,9 @@ module Google
         @discovery_document = discovery_document
       end
 
+      # @return [String] unparsed discovery document for the method
+      attr_reader :discovery_document
+
       ##
       # Returns the API this method belongs to.
       #
@@ -57,13 +60,6 @@ module Google
       # @return [String] The method identifier.
       attr_reader :name
 
-      ##
-      # Returns the parsed section of the discovery document that applies to
-      # this method.
-      #
-      # @return [Hash] The method description.
-      attr_reader :description
-
       ##
       # Returns the base URI for the method.
       #
@@ -74,13 +70,21 @@ module Google
       ##
       # Updates the method with the new base.
       #
-      # @param [Addressable::URI, #to_str, String] new_base
+      # @param [Addressable::URI, #to_str, String] new_method_base
       #   The new base URI to use for the method.
       def method_base=(new_method_base)
         @method_base = Addressable::URI.parse(new_method_base)
         @uri_template = nil
       end
 
+      ##
+      # Returns a human-readable description of the method.
+      #
+      # @return [Hash] The API description.
+      def description
+        return @discovery_document['description']
+      end
+      
       ##
       # Returns the method ID.
       #
@@ -176,6 +180,7 @@ module Google
       ##
       # Expands the method's URI template using a parameter list.
       #
+      # @api private
       # @param [Hash, Array] parameters
       #   The parameter list to use.
       #
@@ -214,6 +219,7 @@ module Google
       ##
       # Generates an HTTP request for this method.
       #
+      # @api private
       # @param [Hash, Array] parameters
       #   The parameters to send.
       # @param [String, StringIO] body The body for the HTTP request.
@@ -222,28 +228,14 @@ module Google
       #   The HTTP connection to use.
       #
       # @return [Array] The generated HTTP request.
-      def generate_request(parameters={}, body='', headers=[], options={})
-        options[:connection] ||= Faraday.default_connection
-        if body.respond_to?(:string)
-          body = body.string
-        elsif body.respond_to?(:to_str)
-          body = body.to_str
-        else
-          raise TypeError, "Expected String or StringIO, got #{body.class}."
-        end
+      def generate_request(parameters={}, body='', headers={}, options={})
         if !headers.kind_of?(Array) && !headers.kind_of?(Hash)
           raise TypeError, "Expected Hash or Array, got #{headers.class}."
         end
-        method = self.http_method
+        method = self.http_method.to_s.downcase.to_sym
         uri = self.generate_uri(parameters)
-        headers = headers.to_a if headers.kind_of?(Hash)
-        return options[:connection].build_request(
-          method.to_s.downcase.to_sym
-        ) do |req|
-          req.url(Addressable::URI.parse(uri).normalize.to_s)
-          req.headers = Faraday::Utils::Headers.new(headers)
-          req.body = body
-        end
+        headers = Faraday::Utils::Headers.new(headers)
+        return [method, uri, headers, body]
       end
 
 
@@ -302,6 +294,7 @@ module Google
       # Verifies that the parameters are valid for this method.  Raises an
       # exception if validation fails.
       #
+      # @api private
       # @param [Hash, Array] parameters
       #   The parameters to verify.
       #

data/lib/google/api_client/discovery/resource.rb

@@ -28,11 +28,13 @@ module Google
       ##
       # Creates a description of a particular version of a resource.
       #
-      # @param [Addressable::URI] base
+      # @param [Google::APIClient::API] api
+      #   The API this resource belongs to.
+      # @param [Addressable::URI] method_base
       #   The base URI for the service.
       # @param [String] resource_name
       #   The identifier for the resource.
-      # @param [Hash] resource_description
+      # @param [Hash] discovery_document
       #   The section of the discovery document that applies to this resource.
       #
       # @return [Google::APIClient::Resource] The constructed resource object.
@@ -56,29 +58,33 @@ module Google
         end
       end
 
+      # @return [String] unparsed discovery document for the resource
+      attr_reader :discovery_document
+
       ##
       # Returns the identifier for the resource.
       #
       # @return [String] The resource identifier.
       attr_reader :name
 
-      ##
-      # Returns the parsed section of the discovery document that applies to
-      # this resource.
-      #
-      # @return [Hash] The resource description.
-      attr_reader :description
-
       ##
       # Returns the base URI for this resource.
       #
       # @return [Addressable::URI] The base URI that methods are joined to.
       attr_reader :method_base
 
+      ##
+      # Returns a human-readable description of the resource.
+      #
+      # @return [Hash] The API description.
+      def description
+        return @discovery_document['description']
+      end
+
       ##
       # Updates the hierarchy of resources and methods with the new base.
       #
-      # @param [Addressable::URI, #to_str, String] new_base
+      # @param [Addressable::URI, #to_str, String] new_method_base
       #   The new base URI to use for the resource.
       def method_base=(new_method_base)
         @method_base = Addressable::URI.parse(new_method_base)

data/lib/google/api_client/discovery/schema.rb

@@ -27,6 +27,8 @@ require 'google/api_client/errors'
 
 module Google
   class APIClient
+    ##
+    # @api private
     module Schema
       def self.parse(api, schema_data)
         # This method is super-long, but hard to break up due to the

data/lib/google/api_client/media.rb

@@ -11,6 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+require 'google/api_client/reference'
 
 module Google
   class APIClient
@@ -23,7 +24,8 @@ module Google
     class UploadIO < Faraday::UploadIO      
       ##
       # Get the length of the stream
-      # @return [Integer]
+      #
+      # @return [Fixnum]
       #   Length of stream, in bytes
       def length
         io.respond_to?(:length) ? io.length : File.size(local_path)
@@ -33,41 +35,35 @@ module Google
     ##
     # Resumable uploader.
     #
-    class ResumableUpload
-      attr_reader :result
-      attr_accessor :client
+    class ResumableUpload < Request
+      # @return [Fixnum] Max bytes to send in a single request
       attr_accessor :chunk_size
-      attr_accessor :media
-      attr_accessor :location
   
       ##
       # Creates a new uploader.
       #
-      # @param [Google::APIClient::Result] result
-      #   Result of the initial request that started the upload
-      # @param [Google::APIClient::UploadIO] media
-      #   Media to upload
-      # @param [String] location
-      #  URL to upload to    
-      def initialize(result, media, location)
-        self.media = media
-        self.location = location
-        self.chunk_size = 256 * 1024
-        
-        @api_method = result.reference.api_method
-        @result = result
-        @offset = 0
+      # @param [Hash] options
+      #   Request options
+      def initialize(options={})
+        super options
+        self.uri = options[:uri]
+        self.http_method = :put
+        @offset = options[:offset] || 0
         @complete = false
+        @expired = false
       end
       
       ##
       # Sends all remaining chunks to the server
       #
+      # @deprecated Pass the instance to {Google::APIClient#execute} instead
+      #
       # @param [Google::APIClient] api_client
       #   API Client instance to use for sending
       def send_all(api_client)
+        result = nil
         until complete?
-          send_chunk(api_client)
+          result = send_chunk(api_client)
           break unless result.status == 308
         end
         return result
@@ -77,28 +73,12 @@ module Google
       ##
       # Sends the next chunk to the server
       #
+      # @deprecated Pass the instance to {Google::APIClient#execute} instead
+      #
       # @param [Google::APIClient] api_client
       #   API Client instance to use for sending
       def send_chunk(api_client)
-        if @offset.nil?
-          return resync_range(api_client)
-        end
-
-        start_offset = @offset
-        self.media.io.pos = start_offset
-        chunk = self.media.io.read(chunk_size)
-        content_length = chunk.bytesize
-
-        end_offset = start_offset + content_length - 1
-        @result = api_client.execute(
-          :uri => self.location,
-          :http_method => :put,
-          :headers => {
-            'Content-Length' => "#{content_length}",
-            'Content-Type' => self.media.content_type, 
-            'Content-Range' => "bytes #{start_offset}-#{end_offset}/#{media.length}" },
-          :body => chunk)
-        return process_result(@result)
+        return api_client.execute(self)
       end
 
       ##
@@ -117,54 +97,86 @@ module Google
       # @return [TrueClass, FalseClass]
       #   Whether or not the upload has expired and can not be resumed
       def expired?
-        return @result.status == 404 || @result.status == 410
+        return @expired
       end
       
       ##
-      # Get the last saved range from the server in case an error occurred 
-      # and the offset is not known.
+      # Check if upload is resumable. That is, neither complete nor expired
       #
-      # @param [Google::APIClient] api_client
-      #   API Client instance to use for sending
-      def resync_range(api_client)
-        r = api_client.execute(
-          :uri => self.location,
-          :http_method => :put,
-          :headers => { 
+      # @return [TrueClass, FalseClass] True if upload can be resumed
+      def resumable?
+        return !(self.complete? or self.expired?)
+      end
+      
+      ##
+      # Convert to an HTTP request. Returns components in order of method, URI,
+      # request headers, and body
+      #
+      # @api private
+      #
+      # @return [Array<(Symbol, Addressable::URI, Hash, [#read,#to_str])>]
+      def to_http_request
+        if @complete
+          raise Google::APIClient::ClientError, "Upload already complete"
+        elsif @offset.nil?
+          self.headers.update({ 
             'Content-Length' => "0", 
             'Content-Range' => "bytes */#{media.length}" })
-        return process_result(r)
+        else
+          start_offset = @offset
+          self.media.io.pos = start_offset
+          chunk = self.media.io.read(chunk_size)
+          content_length = chunk.bytesize
+          end_offset = start_offset + content_length - 1
+          
+          self.headers.update({
+            'Content-Length' => "#{content_length}",
+            'Content-Type' => self.media.content_type, 
+            'Content-Range' => "bytes #{start_offset}-#{end_offset}/#{media.length}" })
+          self.body = chunk
+        end
+        super
       end
       
       ##
       # Check the result from the server, updating the offset and/or location
       # if available.
       #
-      # @param [Google::APIClient::Result] r
-      #  Result of a chunk upload or range query
-      def process_result(result)
-        case result.status
+      # @api private
+      #
+      # @param [Faraday::Response] response
+      #   HTTP response
+      #
+      # @return [Google::APIClient::Result]
+      #   Processed API response
+      def process_http_response(response)
+        case response.status
         when 200...299
           @complete = true
-          if @api_method
-            # Inject the original API method so data is parsed correctly
-            result.reference.api_method = @api_method
-          end
-          return result
         when 308
-          range = result.headers['range']
+          range = response.headers['range']
           if range
             @offset = range.scan(/\d+/).collect{|x| Integer(x)}.last + 1
           end
-          if result.headers['location']
-            self.location = result.headers['location']
+          if response.headers['location']
+            self.uri = response.headers['location']
           end
+        when 400...499
+          @expired = true
         when 500...599
           # Invalidate the offset to mark it needs to be queried on the
           # next request
           @offset = nil
         end
-        return nil
+        return Google::APIClient::Result.new(self, response)
+      end
+      
+      ##
+      # Hashified verison of the API request
+      #
+      # @return [Hash]
+      def to_hash
+        super.merge(:offset => @offset)
       end
       
     end