aws-sdk-resources 2.0.0.pre

data/lib/aws-sdk-resources/definition.rb

@@ -0,0 +1,363 @@
+require 'set'
+
+module Aws
+  module Resources
+
+    # Given a resource definition document, a {Definition} can build a set
+    # of related resource classes.
+    class Definition
+
+      # @param [Hash] definition
+      # @option options [String] :source_path
+      def initialize(definition = {}, options = {})
+        @source = definition
+        @source_path = options[:source_path]
+      end
+
+      # @param [Module<Service>] namespace
+      # @return [void]
+      def apply(namespace)
+        build_resource_classes(namespace)
+        each_resource_class(namespace) do |resource, definition|
+          define_load(namespace, resource, definition['load'])
+          define_actions(namespace, resource, definition['actions'] || {})
+          define_batch_actions(namespace, resource, definition['batchActions'] || {})
+          define_waiters(namespace, resource, definition['waiters'] || {})
+          define_has_many(namespace, resource, definition['hasMany'] || {})
+          define_has_some(namespace, resource, definition['hasSome'] || {})
+          define_has_one(namespace, resource, definition['hasOne'] || {})
+          define_data_attributes(namespace, resource, definition['shape'])
+          define_subresources(namespace, resource, definition['subResources'] || {})
+        end
+        define_top_level_references(namespace)
+      end
+
+      private
+
+      def build_resource_classes(namespace)
+        each_definition do |name, definition|
+          resource_class = Class.new(Resource)
+          resource_class.client_class = namespace::Client
+          resource_class.resource_name = name
+          (definition['identifiers'] || []).each do |identifier|
+            resource_class.add_identifier(underscore(identifier['name']))
+          end
+          namespace.const_set(name, resource_class)
+          unless name == 'Resource'
+            resource_class.const_set(:Batch, Class.new(Batch))
+          end
+        end
+      end
+
+      def each_resource_class(namespace, &block)
+        each_definition do |name, definition|
+          yield(namespace.const_get(name), definition)
+        end
+      end
+
+      def define_subresources(namespace, parent, definition)
+        parent_name = parent.resource_name
+        identifiers = definition['identifiers'] || {}
+        (definition['resources'] || []).each do |child_name|
+
+          method_name = underscore(child_name.sub(/^#{parent_name}/, ''))
+          operation = subresource(namespace, child_name, identifiers)
+          parent.add_operation(method_name, operation)
+
+          method_name = underscore(parent_name)
+          operation = subresource(namespace, parent_name, identifiers.invert)
+          namespace.const_get(child_name).add_operation(method_name, operation)
+
+        end
+      end
+
+      def subresource(namespace, type, identifiers)
+        Operations::ReferenceOperation.new(builder: define_builder(namespace, {
+          'type' => type,
+          'identifiers' => identifiers.map { |source, target|
+            {
+              'target' => target,
+              'sourceType' => 'identifier',
+              'source' => source,
+            }
+          }
+        }))
+      end
+
+      def define_top_level_references(namespace)
+        top_level = Set.new(resource_definitions.keys)
+        each_resource_class(namespace) do |resource, definition|
+          unless resource.identifiers.count == 1
+            top_level.delete(resource.resource_name)
+          end
+          ((definition['subResources'] || {})['resources'] || {}).each do |child|
+            top_level.delete(child)
+          end
+        end
+        top_level.each do |resource_name|
+          method_name = underscore(resource_name)
+          operation = subresource(namespace, resource_name, {})
+          namespace::Resource.add_operation(method_name, operation)
+        end
+      end
+
+      def define_batch_actions(namespace, resource, batch_actions)
+        batch_actions.each do |name, definition|
+          method_name = underscore(name)
+          operation = build_operation(namespace, resource, definition)
+          resource::Batch.add_operation(method_name, operation)
+        end
+      end
+
+      def define_data_attributes(namespace, resource, shape_name)
+        return unless shape_name
+        shape = resource.client_class.api.shape_map.shape('shape' => shape_name)
+        shape.member_names.each do |member_name|
+          if
+            resource.identifiers.include?(member_name) ||
+            resource.instance_methods.include?(member_name)
+          then
+            next # some data attributes are duplicates to identifiers
+          else
+            resource.add_data_attribute(member_name)
+          end
+        end
+      end
+
+      def define_load(namespace, resource, definition)
+        return unless definition
+        resource.load_operation = Operations::DataOperation.new(
+          request: define_request(definition['request']),
+          path: underscore(definition['path']),
+          source: source(definition),
+        )
+      end
+
+      def define_actions(namespace, resource, actions)
+        actions.each do |name, action|
+          operation = build_operation(namespace, resource, action)
+          resource.add_operation(underscore(name), operation)
+        end
+      end
+
+      def define_waiters(namespace, resource, waiters)
+        waiters.each do |name, definition|
+          operation = build_waiter_operation(namespace, resource, definition)
+          resource.add_operation("wait_until_#{underscore(name)}", operation)
+        end
+      end
+
+      def build_operation(namespace, resource, definition)
+        type = operation_type(definition)
+        send("build_#{type}_operation", namespace, resource, definition)
+      end
+
+      def build_basic_operation(namespace, resource, definition)
+        Operations::Operation.new(
+          request: define_request(definition['request']),
+          source: source(definition)
+        )
+      end
+
+      def build_data_operation(namespace, resource, definition)
+        plural = definition['path'].include?('[')
+        source = source(definition)
+        if plural
+          Operations::EnumerateDataOperation.new(
+            request: define_request(definition['request']),
+            path: underscore(definition['path']),
+            source: source,
+            limit_key: limit_key(resource, definition)
+          )
+        else
+          Operations::DataOperation.new(
+            request: define_request(definition['request']),
+            path: underscore(definition['path']),
+            source: source
+          )
+        end
+      end
+
+      def build_resource_operation(namespace, resource, definition)
+        builder = define_builder(namespace, definition['resource'])
+        if path = definition['path']
+          source = underscore(path)
+          builder.sources << BuilderSources::ResponsePath.new(source, :data)
+        end
+        Operations::ResourceOperation.new(
+          request: define_request(definition['request']),
+          builder: builder,
+          source: source(definition)
+        )
+      end
+
+      def build_enumerate_resource_operation(namespace, resource, definition)
+        builder = define_builder(namespace, definition['resource'])
+        if path = definition['path']
+          source = underscore(path)
+          builder.sources << BuilderSources::ResponsePath.new(source, :data)
+        end
+        Operations::EnumerateResourceOperation.new(
+          request: define_request(definition['request']),
+          builder: builder,
+          source: source(definition),
+          limit_key: limit_key(resource, definition))
+      end
+
+      def build_waiter_operation(namespace, resource, definition)
+        Operations::WaiterOperation.new(
+          waiter_name: underscore(definition['waiterName']).to_sym,
+          waiter_params: request_params(definition['params']),
+          path: underscore(definition['path'])
+        )
+      end
+
+      def limit_key(resource, definition)
+        operation_name = definition['request']['operation']
+        paginators = resource.client_class.paginators
+        paginators.pager(operation_name).limit_key
+      end
+
+      def define_request(definition)
+        Request.new(
+          method_name: underscore(definition['operation']),
+          params: request_params(definition['params'] || [])
+        )
+      end
+
+      def request_params(params)
+        params.map do |definition|
+          param_class =
+            case definition['sourceType']
+            when 'identifier' then RequestParams::Identifier
+            when 'dataMember' then RequestParams::DataMember
+            when 'string'     then RequestParams::String
+            when 'integer'    then RequestParams::Integer
+            when 'boolean'    then RequestParams::Boolean
+            else
+              msg = "unhandled param source type `#{definition['sourceType']}'"
+              raise ArgumentError, msg
+            end
+          source = definition['source']
+          param_class.new(
+            param_class.literal? ? source : underscore(source),
+            underscore(definition['target'])
+          )
+        end
+      end
+
+      def define_has_many(namespace, resource, has_many)
+        has_many.each do |name, definition|
+          operation = build_enumerate_resource_operation(namespace, resource, definition)
+          resource.add_operation(underscore(name), operation)
+        end
+      end
+
+      def define_has_some(namespace, resource, has_some)
+        has_some.each do |name, definition|
+          define_reference(namespace, resource, name, definition)
+        end
+      end
+
+      def define_has_one(namespace, resource, has_one)
+        has_one.each do |name, definition|
+          define_reference(namespace, resource, name, definition)
+        end
+      end
+
+      def define_reference(namespace, resource, name, definition)
+        builder = define_builder(namespace, definition['resource'])
+        if path = definition['path']
+          source = underscore(path)
+          builder.sources << BuilderSources::DataMember.new(source, :data)
+        end
+        operation = Operations::ReferenceOperation.new(
+          builder: builder,
+          source: source(definition))
+        resource.add_operation(underscore(name), operation)
+      end
+
+      def define_builder(namespace, definition)
+        builder = Builder.new(
+          resource_class: namespace.const_get(definition['type']),
+          sources: builder_sources(definition['identifiers'] || [])
+        )
+        delta = builder.resource_class.identifiers - builder.sources.map(&:target)
+        if delta.size == 0
+          # all identifiers provided
+        elsif delta.size == 1
+          # all but one provided, adding an Argument source
+          target = delta.first
+          builder.sources << BuilderSources::Argument.new(target)
+        else
+          msg = "too many unsourced identifiers: #{definition.inspect}"
+          raise Errors::DefinitionError, msg
+        end
+        builder
+      end
+
+      def builder_sources(sources)
+        sources.map do |definition|
+          source_class =
+            case definition['sourceType']
+            when 'identifier'       then BuilderSources::Identifier
+            when 'dataMember'       then BuilderSources::DataMember
+            when 'requestParameter' then BuilderSources::RequestParameter
+            when 'responsePath'     then BuilderSources::ResponsePath
+            else
+              msg = "unhandled identifier source type `#{definition['sourceType']}'"
+              raise ArgumentError, msg
+            end
+          source_class.new(
+            underscore(definition['source']),
+            underscore(definition['target'])
+          )
+        end
+      end
+
+      def operation_type(action)
+        case action.keys.sort
+        when %w(request) then :basic
+        when %w(path request) then :data
+        when %w(request resource) then :resource
+        when %w(path request resource) then :resource
+        else
+          msg = "unhandled action: #{action.keys.inspect}"
+          raise Errors::DefinitionError, msg
+        end
+      end
+
+      def svc_definition
+        @source['service'] || {}
+      end
+
+      def resource_definitions
+        @source['resources'] || {}
+      end
+
+      def each_definition(&block)
+        yield('Resource', svc_definition)
+        resource_definitions.each(&block)
+      end
+
+      def underscore(str)
+        if str
+          str.gsub(/\w+/) { |part| Seahorse::Util.underscore(part) }
+        end
+      end
+
+      def pluralize(str)
+        underscore(str) + 's'
+      end
+
+      def source(definition)
+        if ENV['SOURCE']
+          Source.new(definition, @source_path)
+        else
+          nil
+        end
+      end
+
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter.rb

@@ -0,0 +1,18 @@
+require 'json'
+
+module Aws
+  module Resources
+    class Documenter
+
+      autoload :BaseOperationDocumenter, 'aws-sdk-resources/documenter/base_operation_documenter'
+      autoload :DataOperationDocumenter, 'aws-sdk-resources/documenter/data_operation_documenter'
+      autoload :EnumerateDataOperationDocumenter, 'aws-sdk-resources/documenter/enumerate_data_operation_documenter'
+      autoload :EnumerateResourceOperationDocumenter, 'aws-sdk-resources/documenter/enumerate_resource_operation_documenter'
+      autoload :OperationDocumenter, 'aws-sdk-resources/documenter/operation_documenter'
+      autoload :ReferenceOperationDocumenter, 'aws-sdk-resources/documenter/reference_operation_documenter'
+      autoload :ResourceOperationDocumenter, 'aws-sdk-resources/documenter/resource_operation_documenter'
+      autoload :WaiterOperationDocumenter, 'aws-sdk-resources/documenter/waiter_operation_documenter'
+
+    end
+  end
+end

data/lib/aws-sdk-resources/documenter/base_operation_documenter.rb

@@ -0,0 +1,269 @@
+module Aws
+  module Resources
+    class Documenter
+      class BaseOperationDocumenter
+
+        def initialize(yard_class, resource_class, operation_name, operation)
+          @yard_class = yard_class
+          @resource_class = resource_class
+          @resource_class_name = @resource_class.name.split('::').last
+          @operation_name = operation_name.to_s
+          @operation = operation
+          @source = @operation.source
+          if @operation.respond_to?(:request)
+            @api_request_name = @operation.request.method_name
+            @api_request = @resource_class.client_class.api.operation(@api_request_name)
+            @api_request_params = @operation.request.params
+            @request_operation_name = @operation.request.method_name.to_s
+            @called_operation = "Client##{@api_request_name}"
+          end
+          if @operation.respond_to?(:builder)
+            @builder = @operation.builder
+            @target_resource_class = @builder.resource_class
+            @target_resource_class_name = @target_resource_class.name.split('::').last
+          end
+        end
+
+        # @return [YARD::CodeObject::ClassObject]
+        attr_reader :yard_class
+
+        # @return [Class<Resource>] Returns the resource class this
+        #   operation belongs to.
+        attr_reader :resource_class
+
+        # @return [String] The name of this resource operation.
+        attr_reader :operation_name
+
+        # @return [String] Returns the name of the resource class being
+        #   documented without the namespace prefix. Example:
+        #
+        #   * Aws::S3::Resource => 'Resource'
+        #   * Aws::S3::Bucket => 'Bucket'
+        #
+        attr_reader :resource_class_name
+
+        # @return [Class<Resource>,nil] Returns the class of the resource
+        #   returned by invoking this operation. Returns `nil` if this operation
+        #   does not return any resource objects.
+        attr_reader :target_resource_class
+
+        # @return [String,nil] Returns the name of the resource class
+        #   returned by this operation. This is the base name of
+        #   the class without a namespace prefix. Returns `nil` if this
+        #   operation does not return any resource objects.
+        attr_reader :target_resource_class_name
+
+        # @return [String,nil] Returns the name of the API operation called
+        #   on the client. Returns `nil` if this operation does not make
+        #   any API requests.
+        attr_reader :api_request_name
+
+        # @return [Seahorse::Model::Operation,nil] Returns the model of the
+        #   API operation called. Returns `nil` if this operation does not make
+        #   any API requests.
+        attr_reader :api_request
+ 
+        # @return [Array<Resources::RequestParams::Base>, nil] Returns the
+        #   parameters this operation binds to the made request. Returns `nil`
+        #   if this operation does not make a request.
+        attr_reader :api_request_params
+
+        # @return [String,nil] Returns the `Client#operation_name` reference.
+        #   This is useful for generating `@see` tags and `{links}`.
+        attr_reader :called_operation
+
+        # @return [Builder,nil] Returns the resource builder for
+        #   this operation. Returns `nil` if this operation does not build
+        #   and return resource objects.
+        attr_reader :builder
+
+        # @return [Source]
+        attr_reader :source
+
+        # Constructs and returns a new YARD method object for this operation.
+        # @return [YARD::CodeObject::MethodObject]
+        def method_object
+          m = YARD::CodeObjects::MethodObject.new(yard_class, operation_name)
+          m.scope = :instance
+          m.parameters = parameters
+          m.docstring = docstring
+          if source
+            m.source_type = :json
+            m.source = source.format
+            filename = source.file
+            filename = filename.match('(aws-sdk-core/apis/.+\.resources\.json)')[1]
+            m.add_file(filename, nil, true)
+          end
+          tags.each do |tag|
+            m.add_tag(tag)
+          end
+          m
+        end
+
+        private
+
+        def parameters
+          if option_tags.empty?
+            []
+          else
+            [['params', '{}']]
+          end
+        end
+
+        def docstring
+          ''
+        end
+
+        def tags
+          (option_tags + example_tags + [return_tag] + see_also_tags).compact
+        end
+
+        # This method should be overridden in sub-classes to add YARD tags
+        # to the method code object.
+        # @return [Array<YARD::Tag>]
+        def example_tags
+          []
+        end
+
+        def option_tags
+          if api_request && api_request.input
+            tags = []
+            required = api_request.input.required
+            members = api_request.input.members
+            members = members.sort_by { |name,_| required.include?(name) ? 0 : 1 }
+            members.each do |member_name, member_shape|
+              if api_request_params.any? { |p| p.target.match(/^#{member_name}\b/) }
+                next
+              end
+              docstring = member_shape.documentation
+              req = ' **`required`** &mdash; ' if required.include?(member_name)
+              tags << "@option params [#{param_type(member_shape)}] :#{member_name} #{req}#{docstring}"
+            end
+            tags = tags.join("\n")
+            YARD::DocstringParser.new.parse(tags).to_docstring.tags
+          else
+            []
+          end
+        end
+
+        # If this operation makes an API request, then a `@see` tag is
+        # returned that references the client API operation.
+        # @return [Array<YARD::Tag>]
+        def see_also_tags
+          tags = []
+          tags += related_resource_operation_tags if target_resource_class
+          tags += called_operation_tag if called_operation
+          tags
+        end
+
+        def called_operation_tag
+          tag = "@see #{called_operation}"
+          YARD::DocstringParser.new.parse(tag).to_docstring.tags
+        end
+
+        def related_resource_operation_tags
+          tags = []
+          resource_class.operations.each do |name,op|
+            if
+              name.to_s != self.operation_name &&
+              op.respond_to?(:builder) &&
+              op.builder.resource_class == target_resource_class
+            then
+              tags << "@see ##{name}"
+            end
+          end
+          YARD::DocstringParser.new.parse(tags.sort.join("\n")).to_docstring.tags
+        end
+
+        def return_tag
+          if return_type == ['void'] && return_message.strip.empty?
+            nil
+          else
+            YARD::Tags::Tag.new(:return, return_message, return_type)
+          end
+        end
+
+        # The response object type for the @return tag. This must be overridden
+        # in sub-classes.
+        def return_type
+          raise NotImplementedError
+        end
+
+        # The message portion of the @return tag for this operation. This must
+        # be overidden in sub-classes.
+        def return_message
+          raise NotImplementedError
+        end
+
+        # Returns a suitable variable name for the resource class being
+        # documented:
+        #
+        #    Aws::S3::Resource => 's3'
+        #    Aws::S3::Bucket => 'bucket'
+        #
+        def variable_name
+          parts = resource_class.name.split('::')
+          (parts.last == 'Resource' ? parts[-2] : parts[-1]).downcase
+        end
+
+        def path_type
+          case path_shape
+          when Seahorse::Model::Shapes::Structure then 'Structure'
+          when Seahorse::Model::Shapes::List then 'Array'
+          when Seahorse::Model::Shapes::Map then 'Hash'
+          when Seahorse::Model::Shapes::String then 'String'
+          when Seahorse::Model::Shapes::Integer then 'Integer'
+          when Seahorse::Model::Shapes::Float then 'Float'
+          when Seahorse::Model::Shapes::Boolean then 'Boolean'
+          when Seahorse::Model::Shapes::Timestamp then 'Time'
+          when Seahorse::Model::Shapes::Blob then 'IO'
+          else
+            raise "unhandled shape class `#{path_shape.class.name}'"
+          end
+        end
+
+        def path_shape
+          resolve_shape(response_shape, @operation.path)
+        end
+
+        # Returns the output shape for the called operation.
+        def response_shape
+          api = resource_class.client_class.api
+          api.operation(@operation.request.method_name).output
+        end
+
+        def resolve_shape(shape, path)
+          if path != '$'
+            shape = path.scan(/\w+|\[.*?\]/).inject(shape) do |shape, part|
+              if part[0] == '['
+                shape.member
+              else
+                shape.member(part)
+              end
+            end
+          end
+        end
+
+        def param_type(shape)
+          case shape
+          when Seahorse::Model::Shapes::Blob then 'IO'
+          when Seahorse::Model::Shapes::Byte then  'String'
+          when Seahorse::Model::Shapes::Boolean then 'Boolean'
+          when Seahorse::Model::Shapes::Character then 'String'
+          when Seahorse::Model::Shapes::Double then 'Float'
+          when Seahorse::Model::Shapes::Float then 'Float'
+          when Seahorse::Model::Shapes::Integer then 'Integer'
+          when Seahorse::Model::Shapes::List then 'Array'
+          when Seahorse::Model::Shapes::Long then 'Integer'
+          when Seahorse::Model::Shapes::Map then 'Hash'
+          when Seahorse::Model::Shapes::String then 'String'
+          when Seahorse::Model::Shapes::Structure then 'Hash'
+          when Seahorse::Model::Shapes::Timestamp then 'Time'
+          else raise 'unhandled type'
+          end
+        end
+
+      end
+    end
+  end
+end