gapic-generator 0.2.3 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a5c16d4ae2bf94ccb62b00d0a7cd0d35fbebc348072649684f7550950ef370d
-  data.tar.gz: 162528840170a3992fa85e76d17e6110779cad71d22e5c670cc07647e6c931e6
+  metadata.gz: bd638c7b5855aa89dfd03c87f3f5d8d936d78005b51dd04a409ac7552e3eea05
+  data.tar.gz: 6372183134b8556a0a5ac7a4a6bf1250820c5b167b576454fae5f0228194078c
 SHA512:
-  metadata.gz: 9b0f283cae815e46051faed3bb47ce892772f3f8635b9ce85d6c1d1af7e7d66f87e5900079011abe356ff5f34e1a5e3b0a2bb5eb49d85237f47a695724b7acb1
-  data.tar.gz: d81fb0ca1e7787beb0dd886a2cf8e58ad53b05de862b73334e1f8eafb395de6d4f30538bd53b0ff27876c6e9d14d3dc4641297b6b669d6f99c193f80a925c71d
+  metadata.gz: 67b82518fe047ac185a3b596af6b3da223c774c96dbc6cb01761998920ca164e546bd72fc2222c6a945636c49e39a5b80ded892b821d493d79f40133fa973fa3
+  data.tar.gz: c316dd8c291a1204e73f18d7df06800734bf7e3690db5d5967e586cbaf0c215b02496a090a44eb5baee9b501fd418717312b8bb33d096fda5f5c6ef84e11d1fa

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Release History for gapic-generator
 
+### 0.4.2 / 2020-04-28
+
+* Prepend double-colon to absolute/global namespaces to prevent conflicts.
+* Fix documentation/examples of timeouts to clarify they are in seconds.
+
+### 0.4.0 / 2020-04-20
+
+* Support generating clients of "common" interfaces by delegating to another service config.
+* Added an accessor for the long-running-operation client from the main client.
+* Generate tests for the configure method and operations client accessor.
+* Prevent generation of RPC or factory methods with reserved names.
+* Fixed: LRO clients weren't inheriting custom endpoints from the main client.
+* Fixed: Cross-references weren't interpreted if the text included backticks, spaces, or hyphens.
+
+### 0.3.3 / 2020-04-13
+
+* Fix cross-reference links to multi-word enum values.
+
+### 0.3.2 / 2020-04-12
+
+* Fix the talent.v4beta1 hack.
+
+### 0.3.1 / 2020-04-11
+
+* Disable ModuleLength metric for generated code.
+* Omit nonconforming resource patterns instead of crashing.
+
+### 0.3.0 / 2020-04-10
+
+* Detect when a resource is referenced implicitly via child_type, and generate path helpers.
+* Update grpc-google-iam-v1 dependency to require the latest version.
+* Generated require graph is more sane and does not include cycles.
+* The bundler entrypoint now loads the entire gem for wrapper gems.
+* Generated readmes are more useful and include a quickstart.
+* Package and service modules now have basic documentation.
+* Overloads for methods now have basic explanatory documentation, including how to pass an empty request.
+* Request object documentation no longer duplicates the method documentation.
+
 ### 0.2.3 / 2020-04-06
 
 * No changes

data/lib/gapic/formatting_utils.rb

@@ -22,7 +22,7 @@ module Gapic
   #
   module FormattingUtils
     @brace_detector = /\A(?<pre>[^`]*(`[^`]*`[^`]*)*[^`\\])?\{(?<inside>[^\s][^}]*)\}(?<post>.*)\z/m
-    @xref_detector = /\A(?<pre>[^`]*(`[^`]*`[^`]*)*)?\[(?<text>[\w\.]+)\]\[(?<addr>[\w\.]+)\](?<post>.*)\z/m
+    @xref_detector = /\A(?<pre>[^`]*(`[^`]*`[^`]*)*)?\[(?<text>[\w\. `-]+)\]\[(?<addr>[\w\.]+)\](?<post>.*)\z/m
     @list_element_detector = /\A\s*(\*|\+|-|[0-9a-zA-Z]+\.)\s/
 
     class << self
@@ -137,13 +137,15 @@ module Gapic
 
         case entity
         when Gapic::Schema::Service
-          "{#{convert_address_to_ruby entity}::Client #{text}}"
+          "{::#{convert_address_to_ruby entity}::Client #{text}}"
         when Gapic::Schema::Method
-          "{#{convert_address_to_ruby entity.parent}::Client##{entity.name.underscore} #{text}}"
-        when Gapic::Schema::Message, Gapic::Schema::Enum, Gapic::Schema::EnumValue
-          "{#{convert_address_to_ruby entity} #{text}}"
+          "{::#{convert_address_to_ruby entity.parent}::Client##{entity.name.underscore} #{text}}"
+        when Gapic::Schema::Message, Gapic::Schema::Enum
+          "{::#{convert_address_to_ruby entity} #{text}}"
+        when Gapic::Schema::EnumValue
+          "{::#{convert_address_to_ruby entity.parent}::#{entity.name} #{text}}"
         when Gapic::Schema::Field
-          "{#{convert_address_to_ruby entity.parent}##{entity.name} #{text}}"
+          "{::#{convert_address_to_ruby entity.parent}##{entity.name} #{text}}"
         end
       end
 
@@ -153,7 +155,7 @@ module Gapic
         address = entity.address
         address = address.join "." if address.is_a? Array
         address = address.sub file.package, file.ruby_package if file.ruby_package&.present?
-        address.split(".").reject(&:empty?).map(&:camelize).map { |node| api.fix_namespace node }.join("::")
+        address.split(/\.|::/).reject(&:empty?).map(&:camelize).map { |node| api.fix_namespace node }.join("::")
       end
     end
   end

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.2.3"
+    VERSION = "0.4.2"
   end
 end

data/lib/gapic/generators/default_generator.rb

@@ -63,16 +63,17 @@ module Gapic
         end
 
         # Gem level files
-        files << g("gem/gitignore.erb", ".gitignore",                   gem: gem)
-        files << g("gem/version.erb",   "lib/#{gem.version_file_path}", gem: gem)
-        files << g("gem/gemspec.erb",   "#{gem.name}.gemspec",          gem: gem)
-        files << g("gem/gemfile.erb",   "Gemfile",                      gem: gem)
-        files << g("gem/rakefile.erb",  "Rakefile",                     gem: gem)
-        files << g("gem/readme.erb",    "README.md",                    gem: gem)
-        files << g("gem/changelog.erb", "CHANGELOG.md",                 gem: gem)
-        files << g("gem/rubocop.erb",   ".rubocop.yml",                 gem: gem)
-        files << g("gem/yardopts.erb",  ".yardopts",                    gem: gem)
-        files << g("gem/license.erb",   "LICENSE.md",                   gem: gem)
+        files << g("gem/gitignore.erb",  ".gitignore",                   gem: gem)
+        files << g("gem/version.erb",    "lib/#{gem.version_file_path}", gem: gem)
+        files << g("gem/gemspec.erb",    "#{gem.name}.gemspec",          gem: gem)
+        files << g("gem/gemfile.erb",    "Gemfile",                      gem: gem)
+        files << g("gem/rakefile.erb",   "Rakefile",                     gem: gem)
+        files << g("gem/readme.erb",     "README.md",                    gem: gem)
+        files << g("gem/changelog.erb",  "CHANGELOG.md",                 gem: gem)
+        files << g("gem/rubocop.erb",    ".rubocop.yml",                 gem: gem)
+        files << g("gem/yardopts.erb",   ".yardopts",                    gem: gem)
+        files << g("gem/license.erb",    "LICENSE.md",                   gem: gem)
+        files << g("gem/entrypoint.erb", "lib/#{gem.name}.rb",           gem: gem)
 
         gem.proto_files.each do |proto_file|
           files << g("proto_docs/proto_file.erb", "proto_docs/#{proto_file.docs_file_path}", file: proto_file)

data/lib/gapic/helpers/filepath_helper.rb

@@ -25,6 +25,7 @@ module Gapic
       ##
       # Converts a ruby namespace string to a file path string.
       def ruby_file_path api, namespace
+        namespace = namespace.sub(/^::/, "")
         file_path = ruby_file_path_for_namespace namespace
         fix_file_path api, file_path
       end

data/lib/gapic/helpers/namespace_helper.rb

@@ -38,7 +38,14 @@ module Gapic
       # Ruby double-semicolon separators.
       def ruby_namespace_for_address address
         address = address.split "." if address.is_a? String
-        address.reject(&:empty?).map(&:camelize).join "::"
+        ensure_absolute_namespace address.reject(&:empty?).map(&:camelize).join("::")
+      end
+
+      ##
+      # Returns the given namespace, ensuring double colons are prepended
+      #
+      def ensure_absolute_namespace namespace
+        namespace.start_with?("::") ? namespace : "::#{namespace}"
       end
 
       ##

data/lib/gapic/presenters/field_presenter.rb

@@ -95,21 +95,21 @@ module Gapic
         base_type =
           if field.message?
             type = message_ruby_type field.message
-            output ? type : "#{type} | Hash"
+            output ? type : "#{type}, ::Hash"
           elsif field.enum?
             # TODO: handle when arg message is nil and enum is the type
             message_ruby_type field.enum
           else
             case field.type
-            when 1, 2                              then "Float"
-            when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "Integer"
-            when 9, 12                             then "String"
-            when 8                                 then "Boolean"
+            when 1, 2                              then "::Float"
+            when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "::Integer"
+            when 9, 12                             then "::String"
+            when 8                                 then "::Boolean"
             else
-              "Object"
+              "::Object"
             end
           end
-        field.repeated? ? "Array<#{base_type}>" : base_type
+        field.repeated? ? "::Array<#{base_type}>" : base_type
       end
 
       def field_map_type entry_message, output
@@ -118,7 +118,7 @@ module Gapic
           key_field = field if field.name == "key"
           value_field = field if field.name == "value"
         end
-        class_name = output ? "Google::Protobuf::Map" : "Hash"
+        class_name = output ? "::Google::Protobuf::Map" : "::Hash"
         if key_field && value_field
           key_type = field_doc_types key_field, output
           value_type = field_doc_types value_field, output
@@ -141,7 +141,7 @@ module Gapic
           when 9, 12                             then "\"hello world\""
           when 8                                 then "true"
           else
-            "Object"
+            "::Object"
           end
         end
       end

data/lib/gapic/presenters/file_presenter.rb

@@ -39,7 +39,7 @@ module Gapic
       end
 
       def namespace
-        return @file.ruby_package if @file.ruby_package.present?
+        return ensure_absolute_namespace @file.ruby_package if @file.ruby_package.present?
         ruby_namespace_for_address address
       end
 

data/lib/gapic/presenters/gem_presenter.rb

@@ -37,6 +37,10 @@ module Gapic
         end
       end
 
+      def packages?
+        !packages.empty?
+      end
+
       def services
         @services ||= begin
           files = @api.generate_files

data/lib/gapic/presenters/method_presenter.rb

@@ -16,6 +16,7 @@
 
 require "active_support/inflector"
 require "gapic/path_template"
+require "gapic/ruby_info"
 require "gapic/helpers/namespace_helper"
 
 module Gapic
@@ -36,7 +37,11 @@ module Gapic
       end
 
       def name
-        ActiveSupport::Inflector.underscore @method.name
+        @name ||= begin
+          candidate = ActiveSupport::Inflector.underscore @method.name
+          candidate = "call_#{candidate}" if Gapic::RubyInfo.excluded_method_names.include? candidate
+          candidate
+        end
       end
 
       def kind
@@ -59,13 +64,13 @@ module Gapic
 
       def doc_response_type
         ret = return_type
-        ret = "Gapic::Operation" if lro?
+        ret = "::Gapic::Operation" if lro?
         if server_streaming?
-          ret = "Enumerable<#{ret}>"
+          ret = "::Enumerable<#{ret}>"
         elsif paged?
           paged_type = paged_response_type
-          paged_type = "Gapic::Operation" if paged_type == "Google::Longrunning::Operation"
-          ret = "Gapic::PagedEnumerable<#{paged_type}>"
+          paged_type = "::Gapic::Operation" if paged_type == "::Google::Longrunning::Operation"
+          ret = "::Gapic::PagedEnumerable<#{paged_type}>"
         end
         ret
       end
@@ -118,7 +123,7 @@ module Gapic
           return [
             OpenStruct.new(
               name:      "operation",
-              doc_types: "Gapic::Operation"
+              doc_types: "::Gapic::Operation"
             )
           ]
         end
@@ -129,7 +134,7 @@ module Gapic
           ),
           OpenStruct.new(
             name:      "operation",
-            doc_types: "GRPC::ActiveCall::Operation"
+            doc_types: "::GRPC::ActiveCall::Operation"
           )
         ]
       end
@@ -145,9 +150,9 @@ module Gapic
       end
 
       def lro?
-        return paged_response_type == "Google::Longrunning::Operation" if paged?
+        return paged_response_type == "::Google::Longrunning::Operation" if paged?
 
-        message_ruby_type(@method.output) == "Google::Longrunning::Operation"
+        message_ruby_type(@method.output) == "::Google::Longrunning::Operation"
       end
 
       def client_streaming?
@@ -166,8 +171,9 @@ module Gapic
         # to be removed when these methods no longer conform to AIP-4233.) For
         # detailed information, see internal link go/actools-talent-pagination.
         address = @method.address.join "."
-        return false if address == "google.cloud.talent.v4beta1.SearchProfiles"
-        return false if address == "google.cloud.talent.v4beta1.SearchJobs"
+        return false if address == "google.cloud.talent.v4beta1.ProfileService.SearchProfiles"
+        return false if address == "google.cloud.talent.v4beta1.JobService.SearchJobs"
+        return false if address == "google.cloud.talent.v4beta1.JobService.SearchJobsForAlert"
 
         paged_request?(@method.input) && paged_response?(@method.output)
       end
@@ -214,18 +220,18 @@ module Gapic
 
       def doc_types_for arg
         if arg.message?
-          "#{message_ruby_type arg.message} | Hash"
+          "#{message_ruby_type arg.message}, Hash"
         elsif arg.enum?
           # TODO: handle when arg message is nil and enum is the type
           message_ruby_type arg.enum
         else
           case arg.type
-          when 1, 2                              then "Float"
-          when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "Integer"
-          when 9, 12                             then "String"
-          when 8                                 then "Boolean"
+          when 1, 2                              then "::Float"
+          when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "::Integer"
+          when 9, 12                             then "::String"
+          when 8                                 then "::Boolean"
           else
-            "Object"
+            "::Object"
           end
         end
       end
@@ -250,7 +256,7 @@ module Gapic
           when 9, 12                             then "\"hello world\""
           when 8                                 then "true"
           else
-            "Object"
+            "::Object"
           end
         end
       end

data/lib/gapic/presenters/package_presenter.rb

@@ -45,10 +45,25 @@ module Gapic
         ruby_namespace_for_address address
       end
 
+      def parent_namespace
+        namespace.split("::")[0...-1].join("::")
+      end
+
+      def module_name
+        namespace.split("::").last
+      end
+
+      # Services whose clients should be generated in this package namespace.
       def services
         @services ||= begin
           files = @api.generate_files.select { |f| f.package == @package }
-          files.map(&:services).flatten.map { |s| ServicePresenter.new @api, s }
+          services = files.map(&:services).flatten
+          # Omit common services in this package. Common service clients do not
+          # go into their own package.
+          normal_services = services.select { |s| @api.delegate_service_for(s).nil? }
+          # But include common services that delegate to normal services in this package.
+          common_services = normal_services.flat_map { |s| @api.common_services_for s }
+          (normal_services + common_services).map { |s| ServicePresenter.new @api, s }
         end
       end
 

data/lib/gapic/presenters/resource_presenter.rb

@@ -38,15 +38,9 @@ module Gapic
           )
         end
 
-        @patterns.each do |pattern|
-          # URI path template verification for expected proto resource usage
-          if named_arg_patterns? pattern.segments
-            raise ArgumentError, "only resources without named patterns are supported, " \
-                                " not #{pattern.template}"
-          elsif positional_args? pattern.segments
-            raise ArgumentError, "only resources with named segments are supported, " \
-                                " not #{pattern.template}"
-          end
+        # Keep only patterns that can be used to create path helpers
+        @patterns.reject! do |pattern|
+          named_arg_patterns?(pattern.segments) || positional_args?(pattern.segments)
         end
       end
 

data/lib/gapic/presenters/service_presenter.rb

@@ -55,8 +55,26 @@ module Gapic
         @service.address
       end
 
+      # Returns a presenter for this service's delegate (if it is a common service)
+      # otherwise returns `nil`.
+      def common_service_delegate
+        unless defined? @common_service_delegate
+          delegate = @api.delegate_service_for @service
+          @common_service_delegate = delegate ? ServicePresenter.new(@api, delegate) : nil
+        end
+        @common_service_delegate
+      end
+
+      # The namespace of the client. Normally this is the version module. This
+      # may be different from the proto namespace for a common service.
       def namespace
-        return @service.ruby_package if @service.ruby_package.present?
+        # If this service is a common service, its client should go into its
+        # delegate's namespace rather than its own. For example, KMS includes
+        # the common IAMPolicy service, but that service's client should go
+        # into the KMS namespace.
+        return common_service_delegate.namespace if common_service_delegate
+
+        return ensure_absolute_namespace @service.ruby_package if @service.ruby_package.present?
 
         namespace = ruby_namespace_for_address @service.address[0...-1]
         fix_namespace @api, namespace
@@ -74,8 +92,22 @@ module Gapic
         @service.name
       end
 
+      # The namespace of the protos. This may be different from the client
+      # namespace for a common service.
+      def proto_namespace
+        return ensure_absolute_namespace @service.ruby_package if @service.ruby_package.present?
+
+        namespace = ruby_namespace_for_address @service.address[0...-1]
+        @api.override_proto_namespaces? ? fix_namespace(@api, namespace) : namespace
+      end
+
       def proto_service_name_full
-        fix_namespace @api, "#{namespace}::#{name}"
+        name_full = "#{proto_namespace}::#{name}"
+        @api.override_proto_namespaces? ? fix_namespace(@api, name_full) : name_full
+      end
+
+      def module_name
+        service_name_full.split("::").last
       end
 
       def proto_service_file_path
@@ -106,6 +138,10 @@ module Gapic
         "#{proto_service_name_full}::Stub"
       end
 
+      def service_name_full
+        fix_namespace @api, "#{namespace}::#{name}"
+      end
+
       def service_file_path
         service_require + ".rb"
       end
@@ -114,8 +150,12 @@ module Gapic
         service_file_path.split("/").last
       end
 
+      def service_directory_name
+        service_require.split("/").last
+      end
+
       def service_require
-        ruby_file_path @api, proto_service_name_full
+        ruby_file_path @api, service_name_full
       end
 
       def client_name
@@ -123,7 +163,7 @@ module Gapic
       end
 
       def client_name_full
-        fix_namespace @api, "#{proto_service_name_full}::#{client_name}"
+        fix_namespace @api, "#{service_name_full}::#{client_name}"
       end
 
       def create_client_call
@@ -147,12 +187,17 @@ module Gapic
       end
 
       def client_endpoint
-        return @parent_service.client_endpoint if @parent_service
-        @service.host || default_config(:default_host) || "localhost"
+        @parent_service&.client_endpoint ||
+          common_service_delegate&.client_endpoint ||
+          @service.host ||
+          default_config(:default_host) ||
+          "localhost"
       end
 
       def client_scopes
-        @service.scopes || default_config(:oauth_scopes)
+        common_service_delegate&.client_scopes ||
+          @service.scopes ||
+          default_config(:oauth_scopes)
       end
 
       def client_proto_name
@@ -164,7 +209,7 @@ module Gapic
       end
 
       def credentials_name_full
-        fix_namespace @api, "#{proto_service_name_full}::#{credentials_name}"
+        fix_namespace @api, "#{service_name_full}::#{credentials_name}"
       end
 
       def credentials_class_xref
@@ -192,7 +237,7 @@ module Gapic
       end
 
       def helpers_require
-        ruby_file_path @api, "#{proto_service_name_full}::Helpers"
+        ruby_file_path @api, "#{service_name_full}::Helpers"
       end
 
       def references
@@ -208,7 +253,7 @@ module Gapic
       end
 
       def paths_name_full
-        fix_namespace @api, "#{proto_service_name_full}::#{paths_name}"
+        fix_namespace @api, "#{service_name_full}::#{paths_name}"
       end
 
       def paths_file_path
@@ -220,7 +265,7 @@ module Gapic
       end
 
       def paths_require
-        ruby_file_path @api, "#{proto_service_name_full}::#{paths_name}"
+        ruby_file_path @api, "#{service_name_full}::#{paths_name}"
       end
 
       def test_client_file_path
@@ -252,7 +297,7 @@ module Gapic
       end
 
       def operations_name_full
-        fix_namespace @api, "#{proto_service_name_full}::#{operations_name}"
+        fix_namespace @api, "#{service_name_full}::#{operations_name}"
       end
 
       def operations_file_path
@@ -264,7 +309,7 @@ module Gapic
       end
 
       def operations_require
-        ruby_file_path @api, "#{proto_service_name_full}::#{operations_name}"
+        ruby_file_path @api, "#{service_name_full}::#{operations_name}"
       end
 
       def lro_service