aws-sdk-resources 2.11.549

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

@@ -0,0 +1,331 @@
+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(namespace, resource, definition['has'] || {})
+          define_has_many(namespace, resource, definition['hasMany'] || {})
+          define_data_attributes(namespace, resource, definition)
+        end
+      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)
+        end
+      end
+
+      def each_resource_class(namespace, &block)
+        each_definition do |name, definition|
+          yield(namespace.const_get(name), definition)
+        end
+      end
+
+      def define_batch_actions(namespace, resource, batch_actions)
+        batch_actions.each do |name, definition|
+          method_name = "batch_" + underscore(name)
+          method_name += '!' if dangerous?(name, definition)
+          operation = build_operation(namespace, resource, definition)
+          resource.add_batch_operation(method_name, operation)
+        end
+      end
+
+      def dangerous?(name, definition)
+        if
+          name.match(/delete/i) ||
+          name.match(/terminate/i) ||
+          definition['request']['operation'].match(/delete/i) ||
+          definition['request']['operation'].match(/terminate/i)
+        then
+          true
+        else
+          false
+        end
+      end
+
+      def define_data_attributes(namespace, resource, definition)
+        if shape_name = definition['shape']
+          shape = resource.client_class.api.metadata['shapes'][shape_name]
+          shape.member_names.each do |member_name|
+            if
+              resource.instance_methods.include?(member_name) ||
+              data_attribute_is_an_identifier?(member_name, resource, definition)
+            then
+              next # some data attributes are duplicates to identifiers
+            else
+              resource.add_data_attribute(member_name)
+            end
+          end
+        end
+      end
+
+      def data_attribute_is_an_identifier?(attr_name, resource, definition)
+        resource.identifiers.include?(attr_name) ||
+        definition['identifiers'].any? { |i| underscore(i['dataMember']) == attr_name.to_s }
+      end
+
+      def define_load(namespace, resource, definition)
+        return unless definition
+        resource.load_operation = Operations::LoadOperation.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)
+        if definition['resource']
+          build_resource_action(namespace, resource, definition)
+        else
+          build_basic_action(namespace, resource, definition)
+        end
+      end
+
+      def build_basic_action(namespace, resource, definition)
+        Operations::Operation.new(
+          request: define_request(definition['request']),
+          source: source(definition)
+        )
+      end
+
+      def build_resource_action(namespace, resource, definition)
+        builder = define_builder(namespace, definition['resource'])
+        if path = definition['resource']['path']
+          builder.sources << BuilderSources::ResponsePath.new({
+            source: underscore(path),
+            target: :data,
+          })
+        end
+        Operations::ResourceOperation.new(
+          request: define_request(definition['request']),
+          builder: builder,
+          source: source(definition)
+        )
+      end
+
+      def has_many(namespace, resource, definition)
+        builder = define_builder(namespace, definition['resource'])
+        if path = definition['resource']['path']
+          builder.sources << BuilderSources::ResponsePath.new({
+            source: underscore(path),
+            target: :data,
+          })
+        end
+        Operations::HasManyOperation.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']
+        operation = resource.client_class.api.operation(underscore(operation_name))
+        if operation[:pager]
+          operation[:pager].limit_key
+        else
+          nil
+        end
+      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|
+          send("#{definition['source']}_request_param", definition)
+        end
+      end
+
+      def identifier_request_param(definition)
+        RequestParams::Identifier.new({
+          target: underscore(definition['target']),
+          name: underscore(definition['name']).to_sym,
+        })
+      end
+
+      def data_request_param(definition)
+        RequestParams::DataMember.new({
+          target: underscore(definition['target']),
+          path: underscore(definition['path']),
+        })
+      end
+
+      def string_request_param(definition)
+        RequestParams::Literal.new({
+          target: underscore(definition['target']),
+          value: definition['value'],
+        })
+      end
+      alias integer_request_param string_request_param
+      alias float_request_param string_request_param
+      alias boolean_request_param string_request_param
+      alias null_request_param string_request_param
+
+      def define_has_many(namespace, resource, has_many)
+        has_many.each do |name, definition|
+          operation = has_many(namespace, resource, definition)
+          resource.add_operation(underscore(name), operation)
+        end
+      end
+
+      def define_has(namespace, resource, has)
+        has.each do |name, definition|
+          has_operation(namespace, resource, name, definition)
+        end
+      end
+
+      def has_operation(namespace, resource, name, definition)
+        builder = define_builder(namespace, definition['resource'])
+        if path = definition['resource']['path']
+          builder.sources << BuilderSources::DataMember.new({
+            source: underscore(path),
+            target: :data,
+          })
+        end
+        operation = Operations::HasOperation.new(
+          builder: builder,
+          source: source(definition))
+        resource.add_operation(underscore(name), operation)
+      end
+
+      def define_builder(namespace, definition)
+        Builder.new(
+          resource_class: namespace.const_get(definition['type']),
+          sources: builder_sources(definition['identifiers'] || [])
+        )
+      end
+
+      def builder_sources(sources)
+        sources.map do |definition|
+          send("#{definition['source']}_builder_source", definition, sources)
+        end
+      end
+
+      def input_builder_source(definition, sources)
+        arguments = sources.select { |s| s['source'] == 'input' }
+        BuilderSources::Argument.new({
+          source: arguments.index(definition),
+          target: underscore(definition['target']),
+        })
+      end
+
+      def identifier_builder_source(definition, _)
+        BuilderSources::Identifier.new({
+          source: underscore(definition['name']),
+          target: underscore(definition['target']),
+        })
+      end
+
+      def data_builder_source(definition, _)
+        BuilderSources::DataMember.new({
+          source: underscore(definition['path']),
+          target: underscore(definition['target']),
+        })
+      end
+
+      def requestParameter_builder_source(definition, _)
+        BuilderSources::RequestParameter.new({
+          source: underscore(definition['path']),
+          target: underscore(definition['target']),
+        })
+      end
+
+      def response_builder_source(definition, _)
+        BuilderSources::ResponsePath.new({
+          source: underscore(definition['path']),
+          target: underscore(definition['target']),
+        })
+      end
+
+      def string_builder_source(definition, _)
+        BuilderSources::ResponsePath.new({
+          source: underscore(definition['value']),
+          target: underscore(definition['target']),
+        })
+      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 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,70 @@
+require 'json'
+
+module Aws
+  module Resources
+    class Documenter
+
+      autoload :BaseOperationDocumenter, 'aws-sdk-resources/documenter/base_operation_documenter'
+      autoload :HasOperationDocumenter, 'aws-sdk-resources/documenter/has_operation_documenter'
+      autoload :HasManyOperationDocumenter, 'aws-sdk-resources/documenter/has_many_operation_documenter'
+      autoload :OperationDocumenter, 'aws-sdk-resources/documenter/operation_documenter'
+      autoload :ResourceOperationDocumenter, 'aws-sdk-resources/documenter/resource_operation_documenter'
+      autoload :WaiterOperationDocumenter, 'aws-sdk-resources/documenter/waiter_operation_documenter'
+
+      class << self
+
+        include Seahorse::Model::Shapes
+
+        def apply_customizations
+          document_s3_object_upload_file_additional_options
+          document_s3_object_copy_from_options
+        end
+
+        private
+
+        def document_s3_object_upload_file_additional_options
+          input = Aws::S3::Client.api.operation(:create_multipart_upload).input
+          opts = input.shape.member_names - [:bucket, :key]
+          tags = opts.map do |opt|
+            ref = input.shape.member(opt)
+            type = case ref.shape
+            when StructureShape then 'Structure'
+            when ListShape then 'Array'
+            when MapShape then 'Hash'
+            when StringShape then 'String'
+            when IntegerShape then 'Integer'
+            when FloatShape then 'Float'
+            when BooleanShape then 'Boolean'
+            when TimestampShape then 'Time'
+            when BlobShape then 'IO'
+            else
+              raise "unhandled shape class `#{ref.shape.class.name}'"
+            end
+            docs = ref.documentation || ref.shape.documentation
+            "@option options [#{type}] :#{opt} #{docs}"
+          end
+          tags = YARD::DocstringParser.new.parse(tags).to_docstring.tags
+          m = YARD::Registry['Aws::S3::Object#upload_file']
+          tags.each { |tag| m.add_tag(tag) }
+        end
+
+        def document_s3_object_copy_from_options
+          copy_from = YARD::Registry['Aws::S3::Object#copy_from']
+          copy_to = YARD::Registry['Aws::S3::Object#copy_to']
+          existing_tags = copy_from.tags
+          existing_tags.each do |tag|
+            if tag.tag_name == 'option' && tag.pair.name != ":copy_source"
+              copy_from.add_tag(tag)
+              copy_to.add_tag(tag)
+            end
+          end
+        end
+
+        def tag(string)
+          YARD::DocstringParser.new.parse(string).to_docstring.tags.first
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,279 @@
+require 'set'
+
+module Aws
+  module Resources
+    class Documenter
+      class BaseOperationDocumenter
+
+        include Api::Docs::Utils
+        include Seahorse::Model::Shapes
+
+        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}"
+            @yard_client_operation = YARD::Registry["#{@resource_class.client_class.name}##{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
+          if m = YARD::Registry[@resource_class.name + "##{operation_name}"]
+          else
+            m = YARD::CodeObjects::MethodObject.new(yard_class, operation_name)
+            m.docstring = docstring
+            m.parameters = parameters
+          end
+          m.scope = :instance
+          if source
+            m.source_type = :json
+            m.source = source.format
+            filename = source.file
+            filename = filename.match('(aws-sdk-core/apis/.+)')[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
+            [['options', '{}']]
+          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
+          if api_request && api_request.input
+            [request_syntax_example_tag]
+          else
+            []
+          end
+        end
+
+        def request_syntax_example_tag
+          input = operation_input_ref(api_request, without: fixed_param_names)
+          params = Api::Docs::ParamFormatter.new(input).format
+          example = "#{variable_name}.#{operation_name}(#{params})"
+          example = "@example Request syntax example with placeholder values" +
+            "\n\n    " + example.lines.join('    ')
+          tag(example)
+        end
+
+        def option_tags
+          if api_request && api_request.input
+            skip = fixed_param_names
+            tags = []
+            @yard_client_operation.tags.each do |tag|
+              if YARD::Tags::OptionTag === tag
+                next if skip.include?(tag.pair.name[1..-1]) # remove `:` prefix
+                tags << tag
+              end
+            end
+            tags
+          else
+            []
+          end
+        end
+
+        # Returns a set of root input params that are provided by default
+        # by this operation. These params should not be documented in syntax
+        # examples or in option tags.
+        def fixed_param_names
+          if api_request_params
+            Set.new(api_request_params.map { |p| p.target.split(/\b/).first })
+          else
+            Set.new
+          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
+
+        # 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 StructureShape then 'Structure'
+          when ListShape then 'Array'
+          when MapShape then 'Hash'
+          when StringShape then 'String'
+          when IntegerShape then 'Integer'
+          when FloatShape then 'Float'
+          when BooleanShape then 'Boolean'
+          when TimestampShape then 'Time'
+          when BlobShape 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
+          output = api.operation(@operation.request.method_name).output
+          output ? output.shape : nil
+        end
+
+        def resolve_shape(shape, path)
+          if path != '@'
+            shape = path.scan(/\w+|\[.*?\]/).inject(shape) do |shape, part|
+              if part[0] == '['
+                shape.member.shape
+              else
+                shape.member(part).shape
+              end
+            end
+          end
+        end
+
+        def param_type(ref)
+          case ref.shape
+          when BlobShape then 'IO'
+          when BooleanShape then 'Boolean'
+          when FloatShape then 'Float'
+          when IntegerShape then 'Integer'
+          when ListShape then 'Array'
+          when MapShape then 'Hash'
+          when StringShape then 'String'
+          when StructureShape then 'Hash'
+          when TimestampShape then 'Time'
+          else raise 'unhandled type'
+          end
+        end
+
+        def docs(ref)
+          ref.documentation || ref.shape.documentation
+        end
+
+      end
+    end
+  end
+end