gapic-generator 0.7.5 → 0.10.0

data/lib/gapic/presenters/snippet_presenter.rb

@@ -0,0 +1,103 @@
+# 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.
+
+require "active_support/inflector"
+
+module Gapic
+  module Presenters
+    ##
+    # A presenter for snippets.
+    #
+    class SnippetPresenter
+      def initialize method_presenter, api
+        @method_presenter = method_presenter
+        @api = api
+      end
+
+      def client_streaming?
+        @method_presenter.client_streaming?
+      end
+
+      def bidi_streaming?
+        @method_presenter.client_streaming? && @method_presenter.server_streaming?
+      end
+
+      def response_kind
+        if @method_presenter.server_streaming?
+          :streaming
+        elsif @method_presenter.paged?
+          :paged
+        elsif @method_presenter.lro?
+          :lro
+        else
+          :simple
+        end
+      end
+
+      def snippet_file_path
+        "#{@method_presenter.service.service_require.split('/').last}/#{@method_presenter.name}.rb"
+      end
+
+      def require_path
+        @method_presenter.service.package.package_require
+      end
+
+      def client_type
+        @method_presenter.service.client_name_full.sub(/^::/, "")
+      end
+
+      def request_type
+        @method_presenter.request_type.sub(/^::/, "")
+      end
+
+      def return_type
+        base_type = @method_presenter.return_type.sub(/^::/, "")
+        @method_presenter.server_streaming? ? "Enumerable<#{base_type}>" : base_type
+      end
+
+      def paged_response_type
+        @method_presenter.paged_response_type
+      end
+
+      def base_response_type
+        @method_presenter.return_type
+      end
+
+      # TODO: Determine type of LRO response
+
+      def method_name
+        @method_presenter.name
+      end
+
+      def region_tag
+        gem_presenter = @method_presenter.service.gem
+        api_id = gem_presenter.api_shortname || gem_presenter.api_id&.split(".")&.first
+        names = gem_presenter.name.split "-"
+        final_name = names.pop
+        if final_name =~ /^v\d/
+          api_version = final_name
+          api_id ||= names.last
+        else
+          api_id ||= final_name
+          api_version = "v0"
+        end
+        service_name = @method_presenter.service.module_name
+        method_name = @method_presenter.method.name
+        "#{api_id}_#{api_version}_generated_#{service_name}_#{method_name}_sync"
+      end
+    end
+  end
+end

data/lib/gapic/schema/api.rb

@@ -89,6 +89,10 @@ module Gapic
         matching_files.first
       end
 
+      def overrides_of key
+        configuration&.fetch(:overrides, nil)&.fetch(key, nil) || {}
+      end
+
       def fix_file_path str
         str = String str
         return str if configuration[:overrides].nil?
@@ -241,6 +245,16 @@ module Gapic
         configuration[:transports].include? "grpc"
       end
 
+      # Whether to generate standalone snippets
+      def generate_standalone_snippets?
+        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
@@ -314,10 +328,15 @@ 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?
-        configuration[:overrides][:wrapper_gem_name]
+        return nil if configuration[:overrides][:wrapper_gem_name].nil?
+
+        wrapper_name_config = configuration[:overrides][:wrapper_gem_name].strip
+        return nil if wrapper_name_config.empty?
+
+        wrapper_name_config
       end
 
       private
@@ -340,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 = {}
@@ -353,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
@@ -363,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/request_param_parser.rb

@@ -75,7 +75,7 @@ module Gapic
               error_output
             )
 
-            if param_value
+            unless param_value.nil?
               RequestParameter.new param_val_input_str, param_name_input_esc, value_str, param_config_name, param_value
             end
           end.compact # known bool parameters with invalid values will not be added so we have to compact
@@ -148,7 +148,7 @@ module Gapic
           when :bool
             # bools should be either `true` or `false`
             unesc_val = unescape value_str
-            unesc_val if ["true", "false"].include? unesc_val
+            (unesc_val == "true") if ["true", "false"].include? unesc_val
           else
             # if it's an unknown type, just escape it without attempting to parse anything
             unescape value_str

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 -%>

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

@@ -14,22 +14,21 @@
 # on construction.
 #
 <%- unless method_service.methods.empty? -%>
-# # Examples
+# @example
 #
-# To modify the global config, setting the timeout for <%= method_service.methods.first.name %>
-# to 20 seconds, and all remaining timeouts to 10 seconds:
+#   # Modify the global config, setting the timeout for
+#   # <%= method_service.methods.first.name %> to 20 seconds,
+#   # and all remaining timeouts to 10 seconds.
+#   <%= service.client_name_full %>.configure do |config|
+#     config.timeout = 10.0
+#     config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
+#   end
 #
-#     <%= service.client_name_full %>.configure do |config|
-#       config.timeout = 10.0
-#       config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
-#     end
-#
-# To apply the above configuration only to a new client:
-#
-#     client = <%= service.client_name_full %>.new do |config|
-#       config.timeout = 10.0
-#       config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
-#     end
+#   # Apply the above configuration only to a new client.
+#   client = <%= service.client_name_full %>.new do |config|
+#     config.timeout = 10.0
+#     config.rpcs.<%= method_service.methods.first.name %>.timeout = 20.0
+#   end
 #
 <%- end -%>
 # @!attribute [rw] endpoint

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

@@ -12,10 +12,12 @@ class <%= service.credentials_name %> < ::Google::Auth::Credentials
   <%- end -%>
   ]
   <%- end -%>
+  <%- if service.gem.env_prefix -%>
   self.env_vars = [
     "<%= service.gem.env_prefix %>_CREDENTIALS",
     "<%= service.gem.env_prefix %>_KEYFILE",
     "<%= service.gem.env_prefix %>_CREDENTIALS_JSON",
     "<%= service.gem.env_prefix %>_KEYFILE_JSON"
   ]
+  <%- end -%>
 end

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

@@ -61,7 +61,7 @@ class <%= service.operations_name %>
     # Create credentials
     credentials = @config.credentials
     credentials ||= Credentials.default scope: @config.scope
-    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
     @quota_project_id = @config.quota_project

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

@@ -1,7 +1,7 @@
 <%- assert_locals service -%>
 # Path helper methods for the <%= service.name %> API.
 module Paths
-<%- service.references.each do |resource| -%>
+<%- service.deduped_references.each do |resource| -%>
 <%= indent render(partial: "service/client/resource", locals: { resource: resource }), 2 %>
 
 <%- end %>

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

@@ -6,7 +6,7 @@
     default_config.timeout = <%= format_number service.grpc_service_config.timeout_seconds %>
   <%- end -%>
   <%- if service.grpc_service_config.retry_policy -%>
-    default_config.retry_policy = <%= indent_tail render(partial: "service/client/self_configure_retry_policy", locals: { retry_policy: service.grpc_service_config.retry_policy }), 2 %>
+    default_config.retry_policy = <%= indent_tail service.service_config_presenter.retry_policy_fields, 2 %>
   <%- end -%>
 <%- end -%>
 <%- method_service.methods.each do |method| -%>
@@ -16,7 +16,7 @@
       default_config.rpcs.<%= method.name %>.timeout = <%= format_number method.grpc_service_config.timeout_seconds %>
     <%- end -%>
     <%- if method.grpc_service_config.retry_policy -%>
-      default_config.rpcs.<%= method.name %>.retry_policy =<%= indent_tail render(partial: "service/client/self_configure_retry_policy", locals: { retry_policy: method.grpc_service_config.retry_policy }), 2 %>
+      default_config.rpcs.<%= method.name %>.retry_policy =<%= indent_tail method.service_config_presenter.retry_policy_fields, 2 %>
     <%- end -%>
   <%- end -%>
 <%- end -%>

data/templates/default/service/client/method/_def.erb

@@ -4,12 +4,14 @@
 <%= indent method.doc_description, "# " %>
 #
 <%- end -%>
+<%= render partial: "service/client/method/docs/deprecated", locals: { method: method } -%>
 <%= render partial: "service/client/method/docs/request", locals: { method: method } -%>
 #
 <%= render partial: "service/client/method/docs/response", locals: { method: method } -%>
 #
 <%= render partial: "service/client/method/docs/error", locals: { method: method } -%>
 #
+<%= render partial: "service/client/method/docs/snippets", locals: { method: method } -%>
 <%= render partial: "service/client/method/docs/samples", locals: { method: method } -%>
 def <%= method.name %> request, options = nil
 <%= indent render(partial: "service/client/method/def/request", locals: { method: method }), 2 %>