gapic-generator 0.8.0 → 0.10.1

data/lib/gapic/presenters/resource_presenter.rb

@@ -33,6 +33,10 @@ module Gapic
         @patterns.filter!(&:useful_for_helpers?)
       end
 
+      def dup
+        ResourcePresenter.new @resource
+      end
+
       def name
         @resource.type.split("/").delete_if(&:empty?).last
       end
@@ -62,6 +66,10 @@ module Gapic
         attr_reader :pattern
         attr_reader :path_string
 
+        def pattern_template
+          @parsed_pattern.template
+        end
+
         def useful_for_helpers?
           !@parsed_pattern.positional_segments? && !@parsed_pattern.nontrivial_pattern_segments?
         end

data/lib/gapic/presenters/service_config_presenter.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.
+
+module Gapic
+  module Presenters
+    ##
+    # A presenter for grpc service config.
+    #
+    class ServiceConfigPresenter
+      def initialize grpc_service_config
+        @grpc_service_config = grpc_service_config
+      end
+
+      attr_reader :grpc_service_config
+
+      def retry_policy_fields
+        elems = []
+        retry_policy = grpc_service_config&.retry_policy
+        if retry_policy&.initial_delay_seconds
+          elems << "initial_delay: #{Gapic::FormattingUtils.format_number retry_policy.initial_delay_seconds}"
+        end
+        if retry_policy&.max_delay_seconds
+          elems << "max_delay: #{Gapic::FormattingUtils.format_number retry_policy.max_delay_seconds}"
+        end
+        if retry_policy&.multiplier
+          elems << "multiplier: #{Gapic::FormattingUtils.format_number retry_policy.multiplier}"
+        end
+        if retry_policy&.status_codes
+          elems << "retry_codes: #{retry_policy.status_codes}"
+        end
+        elems.empty? ? "{}" : "{\n  #{elems.join ', '}\n}"
+      end
+    end
+  end
+end

data/lib/gapic/presenters/service_presenter.rb

@@ -50,6 +50,13 @@ module Gapic
         PackagePresenter.new @gem_presenter, @api, @service.parent.package
       end
 
+      ##
+      # @return [Boolean]
+      #
+      def is_deprecated?
+        @service.is_deprecated?
+      end
+
       ##
       # @return [Enumerable<Gapic::Presenters::MethodPresenter>]
       #
@@ -252,6 +259,34 @@ module Gapic
         @references ||= @service.resources.map { |resource| ResourcePresenter.new resource }.sort_by(&:name)
       end
 
+      ##
+      # Deduplicate resource presenters by combining resources with the same
+      # name. If multiple resources have the same name (though possibly
+      # different namespaces, e.g. `location.googleapis.com/Location` vs
+      # `documentai.googleapis.com/Location`), this combines (and dedups) their
+      # patterns into a single resource presenter.
+      #
+      # Used for generating path helpers while avoiding duplicate method names.
+      #
+      def deduped_references
+        @deduped_references ||= begin
+          hash = {}
+          references.each do |resource|
+            if hash.key? resource.name
+              existing = hash[resource.name]
+              resource.patterns.each do |pat|
+                unless existing.patterns.any? { |epat| epat.pattern_template == pat.pattern_template }
+                  existing.patterns << pat
+                end
+              end
+            else
+              hash[resource.name] = resource.dup
+            end
+          end
+          hash.values
+        end
+      end
+
       def paths?
         references.any?
       end
@@ -361,6 +396,10 @@ module Gapic
         @api.grpc_service_config.service_level_configs[grpc_full_name]
       end
 
+      def service_config_presenter
+        ServiceConfigPresenter.new grpc_service_config
+      end
+
       ##
       # The short proto name for this service
       #
@@ -405,6 +444,36 @@ module Gapic
         generate_rest_clients? ? "GRPC client" : "client"
       end
 
+      ##
+      # The method to use for quick start samples. Normally this is simply the
+      # first non-client-streaming method defined, but it can be overridden via
+      # a gem config.
+      #
+      # @return [Gapic::Presenters::MethodPresenter]
+      #
+      def quick_start_method
+        gem_config = @api.configuration[:gem]
+        preferred_method = gem_config[:quick_start_method] if gem_config
+        result = methods.find { |meth| meth.name == preferred_method } if preferred_method
+        result || methods.find { |meth| !meth.client_streaming? }
+      end
+
+      ##
+      # Returns this service presenter if there is a grpc client. Otherwise,
+      # returns the corresponding rest service presenter if there isn't a grpc
+      # client but there is a rest client. Otherwise, returns nil if there is
+      # neither client.
+      #
+      # @return [ServicePresenter,ServiceRestPresenter,nil]
+      #
+      def usable_service_presenter
+        if @api.generate_grpc_clients?
+          self
+        elsif @api.generate_rest_clients? && methods_rest_bindings?
+          rest
+        end
+      end
+
       private
 
       def default_config key

data/lib/gapic/presenters/service_rest_presenter.rb

@@ -43,6 +43,34 @@ module Gapic
         fix_namespace api, "#{main_service.service_name_full}::Rest"
       end
 
+      ##
+      # @return [String]
+      #
+      def service_stub_name
+        "ServiceStub"
+      end
+
+      ##
+      # @return [String]
+      #
+      def service_stub_name_full
+        fix_namespace api, "#{service_name_full}::#{service_stub_name}"
+      end
+
+      ##
+      # @return [String]
+      #
+      def service_stub_require
+        ruby_file_path api, service_stub_name_full
+      end
+
+      ##
+      # @return [String]
+      #
+      def service_stub_file_path
+        "#{service_stub_require}.rb"
+      end
+
       ##
       # @return [String]
       #
@@ -95,39 +123,37 @@ module Gapic
       ##
       # @return [String]
       #
-      def transcoding_helper_name
-        "GrpcTranscoding"
+      def test_client_file_path
+        main_service.service_file_path.sub ".rb", "_test.rb"
       end
 
       ##
       # @return [String]
       #
-      def transcoding_helper_name_full
-        fix_namespace api, "#{service_name_full}::#{transcoding_helper_name}"
+      def credentials_class_xref
+        main_service.credentials_class_xref
       end
 
       ##
       # @return [String]
       #
-      def transcoding_helper_require
-        ruby_file_path api, transcoding_helper_name_full
+      def configure_client_call
+        "#{client_name_full}.configure"
       end
 
       ##
-      # @return [String]
+      # The method to use for quick start samples. Normally this is simply the
+      # first non-client-streaming method defined, but it can be overridden via
+      # a gem config.
       #
-      def transcoding_helper_file_path
-        "#{transcoding_helper_require}.rb"
-      end
-
-      ##
-      # @return [String]
+      # @return [Gapic::Presenters::MethodRestPresenter] if there is a method
+      #     appropriatke for quick start
+      # @return [nil] if there is no method appropriate for quick start
       #
-      def test_client_file_path
-        main_service.service_file_path.sub ".rb", "_test.rb"
+      def quick_start_method
+        main_service.quick_start_method&.rest
       end
 
-
       private
 
       # @return [Gapic::Presenters::ServicePresenter]

data/lib/gapic/presenters/snippet_presenter.rb

@@ -52,7 +52,7 @@ module Gapic
       end
 
       def require_path
-        @method_presenter.service.service_require
+        @method_presenter.service.package.package_require
       end
 
       def client_type

data/lib/gapic/presenters.rb

@@ -26,6 +26,7 @@ require "gapic/presenters/package_presenter"
 require "gapic/presenters/resource_presenter"
 require "gapic/presenters/sample_presenter"
 require "gapic/presenters/service_presenter"
+require "gapic/presenters/service_config_presenter"
 require "gapic/presenters/service_rest_presenter"
 require "gapic/presenters/snippet_presenter"
 

data/lib/gapic/schema/api.rb

@@ -250,6 +250,11 @@ module Gapic
         configuration[:generate_standalone_snippets] ||= false
       end
 
+      # Whether to generate inline documentation snippets
+      def generate_yardoc_snippets?
+        configuration[:generate_yardoc_snippets] ||= false
+      end
+
       # Whether to generate gapic metadata (drift manifest) file
       # @return [Boolean]
       def generate_metadata
@@ -323,7 +328,7 @@ module Gapic
 
       ##
       # An override for the wrapper gem name in the configuration
-      # @return [String, Nil]
+      # @return [String, nil]
       def wrapper_gem_name_override
         return nil unless wrapper_gem_name_override?
         return nil if configuration[:overrides][:wrapper_gem_name].nil?
@@ -354,9 +359,14 @@ module Gapic
       # * A mapping from resource type to resource wrapper is returned.
       def analyze_resources
         # In order to set parent_resources, we first populate a mapping from
-        # parsed pattern to resource mapping (in the patterns variable). This
-        # is done in one pass along with populating the resource type mapping.
-        # Then, we go through all resources again, get its expected parent
+        # parsed pattern to resources that use it (in the patterns variable).
+        # Note that there may be multiple resources associated with a pattern.
+        # (This is uncommon, but one example is monitoring v3 which uses
+        # "projects/*" for its workspace type as well as inheriting the common
+        # project type. We thus map each pattern to an array of resources.)
+        # Constructing the patterns mapping is done in one pass along with
+        # populating the type mapping (which maps only to single resources.)
+        # Then, we go through all resources again, get each's expected parent
         # patterns, and anything that shows up in the patterns mapping is taken
         # to be a parent.
         types = {}
@@ -367,8 +377,8 @@ module Gapic
         end
         types.each do |_type, resource|
           parents = resource.parsed_parent_patterns
-                            .map { |pat| patterns[pat] }
-                            .compact.uniq
+                            .flat_map { |pat| Array(patterns[pat]) }
+                            .uniq
           resource.parent_resources.replace parents
         end
         types
@@ -377,7 +387,7 @@ module Gapic
       def populate_resource_lookups resource, types, patterns
         types[resource.type] = resource
         resource.parsed_patterns.each do |pat|
-          patterns[pat] = resource
+          ((patterns[pat] ||= []) << resource).uniq!
         end
       end
 

data/lib/gapic/schema/wrappers.rb

@@ -268,6 +268,12 @@ module Gapic
         parent.ruby_package
       end
 
+      # @return [Boolean] True if this service is marked as deprecated, false
+      # otherwise.
+      def is_deprecated?
+        options[:deprecated] if options
+      end
+
       # @return [Array<Google::Api::ResourceDescriptor>] A representation of the resource.
       #   This is generally intended to be attached to the "name" field.
       #   See `google/api/resource.proto`.
@@ -336,6 +342,12 @@ module Gapic
         options[:".google.longrunning.operation_info"] if options
       end
 
+      # @return [Boolean] True if this method is marked as deprecated, false
+      # otherwise.
+      def is_deprecated?
+        options[:deprecated] if options
+      end
+
       # @return [Google::Api::HttpRule] The HTTP bindings for this method. See
       #   `google/api/http.proto`.
       def http
@@ -641,6 +653,20 @@ module Gapic
         false
       end
 
+      # @return [Field, nil] a key field for this map
+      #   or nil if this field is not a map
+      def map_key_field
+        return nil? unless map?
+        @message.fields.find { |f| f.name == "key" }
+      end
+
+      # @return [Field, nil] a value field for this map
+      #   or nil if this field is not a map
+      def map_val_field
+        return nil? unless map?
+        @message.fields.find { |f| f.name == "value" }
+      end
+
       # @return [String] A reference to another resource message or resource
       #   definition. See `google/api/resource.proto`.
       def resource_reference

data/templates/default/gem/readme.erb

@@ -16,12 +16,12 @@ $ gem install <%= gem.name %>
 
 ```ruby
 require "<%= gem.entrypoint_require %>"
-<%- service = gem.first_non_common_service -%>
-<%- method = service&.methods.first -%>
+<%- service = gem.quick_start_service -%>
+<%- method = service&.quick_start_method -%>
 <%- if service && method -%>
 
 client = <%= service.create_client_call %>
-request = my_create_request
+request = <%= method.request_type %>.new # (request fields as keyword arguments...)
 response = client.<%= method.name %> request
 <%- end -%>
 ```

data/templates/default/lib/rest/_rest.erb

@@ -1,7 +1,5 @@
 <%- assert_locals service -%>
 <% @requires = capture do %>
-require "gapic/rest"
-require "<%= service.rest.transcoding_helper_require %>"
 require "<%= service.rest.client_require %>"
 <% end %>
 module <%= service.module_name %>

data/templates/default/service/client/_client.erb

@@ -23,14 +23,17 @@ class <%= service.client_name %>
   #
   # See {<%= service.client_name_full %>::Configuration}
   # for a description of the configuration fields.
+<%- if service.is_deprecated? -%>
   #
-  # ## Example
+  # @deprecated This service is deprecated and may be removed in the next major version update.
+<%- end -%>
   #
-  # To modify the configuration for all <%= service.name %> clients:
+  # @example
   #
-  #     <%= service.client_name_full %>.configure do |config|
-  #       config.timeout = 10.0
-  #     end
+  #   # Modify the configuration for all <%= service.name %> clients
+  #   <%= service.client_name_full %>.configure do |config|
+  #     config.timeout = 10.0
+  #   end
   #
   # @yield [config] Configure the <%= service.client_name %> client.
   # @yieldparam config [<%= service.client_name %>::Configuration]
@@ -64,19 +67,15 @@ class <%= service.client_name %>
   ##
   # Create a new <%= service.name %> client object.
   #
-  # ## Examples
-  #
-  # To create a new <%= service.name %> client with the default
-  # configuration:
-  #
-  #     client = <%= service.client_name_full %>.new
+  # @example
   #
-  # To create a new <%= service.name %> client with a custom
-  # configuration:
+  #   # Create a client using the default configuration
+  #   client = <%= service.client_name_full %>.new
   #
-  #     client = <%= service.client_name_full %>.new do |config|
-  #       config.timeout = 10.0
-  #     end
+  #   # Create a client using a custom configuration
+  #   client = <%= service.client_name_full %>.new do |config|
+  #     config.timeout = 10.0
+  #   end
   #
   # @yield [config] Configure the <%= service.name %> client.
   # @yieldparam config [<%= service.client_name %>::Configuration]
@@ -97,14 +96,13 @@ class <%= service.client_name %>
     # Create credentials
     credentials = @config.credentials
     <%- unless service.generic_endpoint? -%>
-    # Use self-signed JWT if the scope and endpoint are unchanged from default,
+    # Use self-signed JWT if the endpoint is unchanged from default,
     # but only if the default endpoint does not have a region prefix.
-    enable_self_signed_jwt = @config.scope == <%= service.client_name %>.configure.scope &&
-                             @config.endpoint == <%= service.client_name %>.configure.endpoint &&
+    enable_self_signed_jwt = @config.endpoint == <%= service.client_name %>.configure.endpoint &&
                              !@config.endpoint.split(".").first.include?("-")
     credentials ||= Credentials.default scope: @config.scope,
                                         enable_self_signed_jwt: enable_self_signed_jwt
-    if credentials.is_a?(String) || credentials.is_a?(Hash)
+    if credentials.is_a?(::String) || credentials.is_a?(::Hash)
       credentials = Credentials.new credentials, scope: @config.scope
     end
     <%- end -%>