translate.rb in google-cloud-translate-2.0.0

- old
+ new

@@ -1,6 +1,6 @@
-# Copyright 2016 Google LLC
+# Copyright 2019 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
 #
@@ -12,13 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
 
 require "google-cloud-translate"
-require "google/cloud/translate/api"
 require "google/cloud/config"
-require "google/cloud/env"
+require "google/gax"
+require "pathname"
 
 module Google
   module Cloud
     ##
     # # Google Cloud Translation API
@@ -34,65 +34,129 @@
     # Afrikaans to Zulu. Used in combination, this enables translation between
     # thousands of language pairs. Also, you can send in HTML and receive HTML
     # with translated text back. You don't need to extract your source text or
     # reassemble the translated content.
     #
+    # The google-cloud-translate 2.0 gem contains a generated v3 client and a legacy hand-written v2 client.
+    # To use the legacy v2 client, call {Google::Cloud::Translate.new} and specify `version: :v2`.
+    # See [Migrating to Translation v3](https://cloud.google.com/translate/docs/migrate-to-v3) for details regarding
+    # differences between v2 and v3.
+    #
     # See {file:OVERVIEW.md Translation Overview}.
     #
     module Translate
+      FILE_DIR = File.realdirpath Pathname.new(__FILE__).join("..").join("translate")
+
+      AVAILABLE_VERSIONS = Dir["#{FILE_DIR}/*"]
+                           .select { |file| File.directory? file }
+                           .select { |dir| Google::Gax::VERSION_MATCHER.match File.basename(dir) }
+                           .select { |dir| File.exist? dir + ".rb" }
+                           .map { |dir| File.basename dir }
+
       ##
-      # Creates a new object for connecting to Cloud Translation API. Each call
-      # creates a new connection.
+      # Provides natural language translation operations.
       #
-      # Like other Cloud Platform services, Google Cloud Translation API
-      # supports authentication using a project ID and OAuth 2.0 credentials. In
-      # addition, it supports authentication using a public API access key. (If
-      # both the API key and the project and OAuth 2.0 credentials are provided,
-      # the API key will be used.) Instructions and configuration options are
-      # covered in the {file:AUTHENTICATION.md Authentication Guide}.
+      # @overload new(version:, credentials:, scopes:, client_config:, timeout:)
+      #   @param version [Symbol, String]
+      #     The major version of the service to be used. By default `:v3` is used.
+      #   @param credentials [Google::Auth::Credentials, String, Hash, GRPC::Core::Channel,
+      #     GRPC::Core::ChannelCredentials, Proc]
+      #     Provides the means for authenticating requests made by the client. This parameter can be many types.
+      #     A `Google::Auth::Credentials` uses a the properties of its represented keyfile for authenticating requests
+      #     made by this client.
+      #     A `String` will be treated as the path to the keyfile to be used for the construction of credentials for
+      #     this client.
+      #     A `Hash` will be treated as the contents of a keyfile to be used for the construction of credentials for
+      #     this client.
+      #     A `GRPC::Core::Channel` will be used to make calls through.
+      #     A `GRPC::Core::ChannelCredentials` for the setting up the RPC client. The channel credentials should already
+      #     be composed with a `GRPC::Core::CallCredentials` object.
+      #     A `Proc` will be used as an updater_proc for the Grpc channel. The proc transforms the metadata for
+      #     requests, generally, to give OAuth credentials.
+      #   @param scopes [Array<String>]
+      #     The OAuth scopes for this service. This parameter is ignored if an updater_proc is supplied.
+      #   @param client_config [Hash]
+      #     A Hash for call options for each method. See Google::Gax#construct_settings for the structure of this data.
+      #     Falls back to the default config if not specified or the specified config is missing data points.
+      #   @param timeout [Numeric]
+      #     The default timeout, in seconds, for calls made through this client.
+      #   @param metadata [Hash]
+      #     Default metadata to be sent with each request. This can be overridden on a per call basis.
+      #   @param service_address [String]
+      #     Override for the service hostname, or `nil` to leave as the default.
+      #   @param service_port [Integer]
+      #     Override for the service port, or `nil` to leave as the default.
+      #   @param exception_transformer [Proc]
+      #     An optional proc that intercepts any exceptions raised during an API call to inject custom error handling.
+      # @overload new(version:, project_id:, credentials:, key:, scope:, retries:, timeout:, endpoint:)
+      #   @param version [Symbol, String]
+      #     The major version of the service to be used. Specifying `:v2` will return the legacy client.
+      #   @param [String] project_id Project identifier for the Cloud Translation service you are connecting to. If not
+      #     present, the default project for the credentials is used.
+      #   @param [String, Hash, Google::Auth::Credentials] credentials The path to the keyfile as a String, the contents
+      #     of the keyfile as a Hash, or a Google::Auth::Credentials object. (See
+      #     {Google::Cloud::Translate::V2::Credentials})
+      #   @param [String] key a public API access key (not an OAuth 2.0 token)
+      #   @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the set of resources and operations that
+      #     the connection can access. See [Using OAuth 2.0 to Access Google
+      #     APIs](https://developers.google.com/identity/protocols/OAuth2).
       #
-      # @param [String] project_id Project identifier for the Cloud Translation
-      #   service you are connecting to. If not present, the default project for
-      #   the credentials is used.
-      # @param [String, Hash, Google::Auth::Credentials] credentials The path to
-      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
-      #   Google::Auth::Credentials object. (See {Translate::Credentials})
-      # @param [String] key a public API access key (not an OAuth 2.0 token)
-      # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
-      #   the set of resources and operations that the connection can access.
-      #   See [Using OAuth 2.0 to Access Google
-      #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+      #     The default scope is:
       #
-      #   The default scope is:
+      #     * `https://www.googleapis.com/auth/cloud-platform`
+      #   @param [Integer] retries Number of times to retry requests on server error. The default value is `3`.
+      #     Optional.
+      #   @param [Integer] timeout Default timeout to use in requests. Optional.
+      #   @param [String] endpoint Override of the endpoint host name. Optional. If the param is nil, uses the default
+      #     endpoint.
       #
-      #   * `https://www.googleapis.com/auth/cloud-platform`
-      # @param [Integer] retries Number of times to retry requests on server
-      #   error. The default value is `3`. Optional.
-      # @param [Integer] timeout Default timeout to use in requests. Optional.
-      # @param [String] endpoint Override of the endpoint host name. Optional.
-      #   If the param is nil, uses the default endpoint.
-      # @param [String] project Alias for the `project_id` argument. Deprecated.
-      # @param [String] keyfile Alias for the `credentials` argument.
-      #   Deprecated.
+      # @example Using the v3 client.
+      #   require "google/cloud/translate"
       #
-      # @return [Google::Cloud::Translate::Api]
+      #   client = Google::Cloud::Translate.new
       #
-      # @example
+      #   project_id = "my-project-id"
+      #   location_id = "us-central1"
+      #   model_id = "my-automl-model-id"
+      #
+      #   # The `model` type requested for this translation.
+      #   model = "projects/#{project_id}/locations/#{location_id}/models/#{model_id}"
+      #   # The content to translate in string format
+      #   contents = ["Hello, world!"]
+      #   # Required. The BCP-47 language code to use for translation.
+      #   target_language = "fr"
+      #   # Optional. The BCP-47 language code of the input text.
+      #   source_language = "en"
+      #   # Optional. Can be "text/plain" or "text/html".
+      #   mime_type = "text/plain"
+      #   parent = client.class.location_path project_id, location_id
+      #
+      #   response = client.translate_text contents, target_language, parent,
+      #     source_language_code: source_language, model: model, mime_type: mime_type
+      #
+      #   # Display the translation for each input text provided
+      #   response.translations.each do |translation|
+      #     puts "Translated text: #{translation.translated_text}"
+      #   end
+      #
+      # @example Using the legacy v2 client.
       #   require "google/cloud/translate"
       #
       #   translate = Google::Cloud::Translate.new(
+      #     version: :v2,
       #     project_id: "my-todo-project",
       #     credentials: "/path/to/keyfile.json"
       #   )
       #
       #   translation = translate.translate "Hello world!", to: "la"
       #   translation.text #=> "Salve mundi!"
       #
-      # @example Using API Key.
+      # @example Using the legacy v2 client with an API Key.
       #   require "google/cloud/translate"
       #
       #   translate = Google::Cloud::Translate.new(
+      #     version: :v2,
       #     key: "api-key-abc123XYZ789"
       #   )
       #
       #   translation = translate.translate "Hello world!", to: "la"
       #   translation.text #=> "Salve mundi!"
@@ -100,102 +164,51 @@
       # @example Using API Key from the environment variable.
       #   require "google/cloud/translate"
       #
       #   ENV["TRANSLATE_KEY"] = "api-key-abc123XYZ789"
       #
-      #   translate = Google::Cloud::Translate.new
+      #   translate = Google::Cloud::Translate.new version: :v2
       #
       #   translation = translate.translate "Hello world!", to: "la"
       #   translation.text #=> "Salve mundi!"
       #
-      def self.new project_id: nil, credentials: nil, key: nil, scope: nil,
-                   retries: nil, timeout: nil, endpoint: nil, project: nil,
-                   keyfile: nil
-        project_id ||= (project || default_project_id)
-        key        ||= configure.key
-        retries    ||= configure.retries
-        timeout    ||= configure.timeout
-        endpoint   ||= configure.endpoint
-
-        if key
-          return Google::Cloud::Translate::Api.new(
-            Google::Cloud::Translate::Service.new(
-              project_id.to_s, nil,
-              retries: retries, timeout: timeout, key: key, host: endpoint
-            )
-          )
+      def self.new *args, version: :v3, **kwargs
+        unless AVAILABLE_VERSIONS.include? version.to_s.downcase
+          raise "The version: #{version} is not available. The available versions " \
+            "are: [#{AVAILABLE_VERSIONS.join ', '}]"
         end
 
-        scope       ||= configure.scope
-        credentials ||= keyfile || default_credentials(scope: scope)
-
-        unless credentials.is_a? Google::Auth::Credentials
-          credentials = Translate::Credentials.new credentials, scope: scope
-        end
-
-        project_id = resolve_project_id project_id, credentials
-        raise ArgumentError, "project_id is missing" if project_id.empty?
-
-        Translate::Api.new(
-          Translate::Service.new(
-            project_id, credentials,
-            retries: retries, timeout: timeout, host: endpoint
-          )
-        )
+        require "#{FILE_DIR}/#{version.to_s.downcase}"
+        version_module = Google::Cloud::Translate
+                         .constants
+                         .select { |sym| sym.to_s.casecmp(version.to_s).zero? }
+                         .first
+        Google::Cloud::Translate.const_get(version_module).new(*args, **kwargs)
       end
 
       ##
       # Configure the Google Cloud Translate library.
       #
       # The following Translate configuration parameters are supported:
       #
-      # * `project_id` - (String) Identifier for a Translate project. (The
-      #   parameter `project` is considered deprecated, but may also be used.)
-      # * `credentials` - (String, Hash, Google::Auth::Credentials) The path to
-      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
-      #   Google::Auth::Credentials object. (See {Translate::Credentials}) (The
-      #   parameter `keyfile` is considered deprecated, but may also be used.)
-      # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
-      #   the set of resources and operations that the connection can access.
-      # * `retries` - (Integer) Number of times to retry requests on server
-      #   error.
+      # * `project_id` - (String) Identifier for a Translate project.
+      # * `credentials` - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of
+      #   the keyfile as a Hash, or a Google::Auth::Credentials object. (See
+      #   {Google::Cloud::Translate::V2::Credentials})
+      # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling the set of resources and operations that
+      #   the connection can access.
+      # * `retries` - (Integer) Number of times to retry requests on server error.
       # * `timeout` - (Integer) Default timeout to use in requests.
-      # * `endpoint` - (String) Override of the endpoint host name, or `nil`
-      #   to use the default endpoint.
+      # * `endpoint` - (String) Override of the endpoint host name, or `nil` to use the default endpoint.
       #
-      # @return [Google::Cloud::Config] The configuration object the
-      #   Google::Cloud::Translate library uses.
+      # @note These values are only used by the legacy v2 client.
       #
+      # @return [Google::Cloud::Config] The configuration object the Google::Cloud::Translate library uses.
+      #
       def self.configure
         yield Google::Cloud.configure.translate if block_given?
 
         Google::Cloud.configure.translate
-      end
-
-      ##
-      # @private Default project.
-      def self.default_project_id
-        Google::Cloud.configure.translate.project_id ||
-          Google::Cloud.configure.project_id ||
-          Google::Cloud.env.project_id
-      end
-
-      ##
-      # @private Default credentials.
-      def self.default_credentials scope: nil
-        Google::Cloud.configure.translate.credentials ||
-          Google::Cloud.configure.credentials ||
-          Translate::Credentials.default(scope: scope)
-      end
-
-      ##
-      # @private Resolve project.
-      def self.resolve_project_id project_id, credentials
-        # Always cast to a string
-        return project_id.to_s unless credentials.respond_to? :project_id
-
-        # Always cast to a string
-        project_id || credentials.project_id.to_s
       end
     end
   end
 end