ibm_watson 0.5.1 → 0.6.0

data/lib/ibm_watson/iam_token_manager.rb

@@ -5,16 +5,16 @@ require("json")
 require("rbconfig")
 require_relative("./version.rb")
 
-DEFAULT_IAM_URL = "https://iam.bluemix.net/identity/token"
-CONTENT_TYPE = "application/x-www-form-urlencoded"
-ACCEPT = "application/json"
-DEFAULT_AUTHORIZATION = "Basic Yng6Yng="
-REQUEST_TOKEN_GRANT_TYPE = "urn:ibm:params:oauth:grant-type:apikey"
-REQUEST_TOKEN_RESPONSE_TYPE = "cloud_iam"
-REFRESH_TOKEN_GRANT_TYPE = "refresh_token"
-
 # Class to manage IAM Token Authentication
 class IAMTokenManager
+  DEFAULT_IAM_URL = "https://iam.bluemix.net/identity/token"
+  CONTENT_TYPE = "application/x-www-form-urlencoded"
+  ACCEPT = "application/json"
+  DEFAULT_AUTHORIZATION = "Basic Yng6Yng="
+  REQUEST_TOKEN_GRANT_TYPE = "urn:ibm:params:oauth:grant-type:apikey"
+  REQUEST_TOKEN_RESPONSE_TYPE = "cloud_iam"
+  REFRESH_TOKEN_GRANT_TYPE = "refresh_token"
+
   attr_accessor :token_info, :user_access_token
   def initialize(iam_apikey: nil, iam_access_token: nil, iam_url: nil)
     @iam_apikey = iam_apikey
@@ -45,6 +45,7 @@ class IAMTokenManager
       )
     end
     return JSON.parse(response.body.to_s) if (200..299).cover?(response.code)
+
     require_relative("./watson_api_exception.rb")
     raise WatsonApiException.new(response: response)
   end
@@ -54,17 +55,18 @@ class IAMTokenManager
   #   2. If this class is managing tokens and does not yet have one, make a request for one
   #   3. If this class is managing tokens and the token has expired refresh it. In case the refresh token is expired, get a new one
   # If this class is managing tokens and has a valid token stored, send it
-  def _token
+  def token
     return @user_access_token unless @user_access_token.nil? || (@user_access_token.respond_to?(:empty?) && @user_access_token.empty?)
+
     if @token_info.all? { |_k, v| v.nil? }
-      token_info = _request_token
-      _save_token_info(
+      token_info = request_token
+      save_token_info(
         token_info: token_info
       )
       return @token_info["access_token"]
-    elsif _is_token_expired?
-      token_info = _is_refresh_token_expired? ? _request_token : _refresh_token
-      _save_token_info(
+    elsif token_expired?
+      token_info = refresh_token_expired? ? request_token : refresh_token
+      save_token_info(
         token_info: token_info
       )
       return @token_info["access_token"]
@@ -73,8 +75,10 @@ class IAMTokenManager
     end
   end
 
+  private
+
   # Request an IAM token using an API key
-  def _request_token
+  def request_token
     headers = {
       "Content-Type" => CONTENT_TYPE,
       "Authorization" => DEFAULT_AUTHORIZATION,
@@ -95,7 +99,7 @@ class IAMTokenManager
   end
 
   # Refresh an IAM token using a refresh token
-  def _refresh_token
+  def refresh_token
     headers = {
       "Content-Type" => CONTENT_TYPE,
       "Authorization" => DEFAULT_AUTHORIZATION,
@@ -114,23 +118,13 @@ class IAMTokenManager
     response
   end
 
-  # Set a self-managed IAM access token.
-  # The access token should be valid and not yet expired.
-  def _access_token(iam_access_token:)
-    @user_access_token = iam_access_token
-  end
-
-  # Set the IAM api key
-  def _iam_apikey(iam_apikey:)
-    @iam_apikey = iam_apikey
-  end
-
   # Check if currently stored token is expired.
   # Using a buffer to prevent the edge case of the
   # token expiring before the request could be made.
   # The buffer will be a fraction of the total TTL. Using 80%.
-  def _is_token_expired?
+  def token_expired?
     return true if @token_info["expiration"].nil? || @token_info["expires_in"].nil?
+
     fraction_of_ttl = 0.8
     time_to_live = @token_info["expires_in"].nil? ? 0 : @token_info["expires_in"]
     expire_time = @token_info["expiration"].nil? ? 0 : @token_info["expiration"]
@@ -142,8 +136,9 @@ class IAMTokenManager
   # Used as a fail-safe to prevent the condition of a refresh token expiring,
   # which could happen after around 30 days. This function will return true
   # if it has been at least 7 days and 1 hour since the last token was set
-  def _is_refresh_token_expired?
+  def refresh_token_expired?
     return true if @token_info["expiration"].nil?
+
     seven_days = 7 * 24 * 3600
     current_time = Time.now.to_i
     new_token_time = @token_info["expiration"] + seven_days
@@ -151,7 +146,7 @@ class IAMTokenManager
   end
 
   # Save the response from the IAM service request to the object's state
-  def _save_token_info(token_info:)
+  def save_token_info(token_info:)
     @token_info = token_info
   end
 end

data/lib/ibm_watson/language_translator_v3.rb

@@ -31,7 +31,7 @@ require_relative "./watson_service"
 module IBMWatson
   ##
   # The Language Translator V3 service.
-  class LanguageTranslatorV3
+  class LanguageTranslatorV3 < WatsonService
     include Concurrent::Async
     ##
     # @!method initialize(args)
@@ -72,7 +72,6 @@ module IBMWatson
     #   'https://iam.ng.bluemix.net/identity/token'.
     def initialize(args = {})
       @__async_initialized__ = false
-      super()
       defaults = {}
       defaults[:version] = nil
       defaults[:url] = "https://gateway.watsonplatform.net/language-translator/api"
@@ -82,84 +81,11 @@ module IBMWatson
       defaults[:iam_access_token] = nil
       defaults[:iam_url] = nil
       args = defaults.merge(args)
-      @watson_service = WatsonService.new(
-        vcap_services_name: "language_translator",
-        url: args[:url],
-        username: args[:username],
-        password: args[:password],
-        iam_apikey: args[:iam_apikey],
-        iam_access_token: args[:iam_access_token],
-        iam_url: args[:iam_url],
-        use_vcap_services: true
-      )
+      args[:vcap_services_name] = "language_translator"
+      super
       @version = args[:version]
     end
 
-    # :nocov:
-    def add_default_headers(headers: {})
-      @watson_service.add_default_headers(headers: headers)
-    end
-
-    def _iam_access_token(iam_access_token:)
-      @watson_service._iam_access_token(iam_access_token: iam_access_token)
-    end
-
-    def _iam_apikey(iam_apikey:)
-      @watson_service._iam_apikey(iam_apikey: iam_apikey)
-    end
-
-    # @return [DetailedResponse]
-    def request(args)
-      @watson_service.request(args)
-    end
-
-    # @note Chainable
-    # @param headers [Hash] Custom headers to be sent with the request
-    # @return [self]
-    def headers(headers)
-      @watson_service.headers(headers)
-      self
-    end
-
-    def password=(password)
-      @watson_service.password = password
-    end
-
-    def password
-      @watson_service.password
-    end
-
-    def username=(username)
-      @watson_service.username = username
-    end
-
-    def username
-      @watson_service.username
-    end
-
-    def url=(url)
-      @watson_service.url = url
-    end
-
-    def url
-      @watson_service.url
-    end
-
-    # @!method configure_http_client(proxy: {}, timeout: {})
-    # Sets the http client config, currently works with timeout and proxies
-    # @param proxy [Hash] The hash of proxy configurations
-    # @option proxy address [String] The address of the proxy
-    # @option proxy port [Integer] The port of the proxy
-    # @option proxy username [String] The username of the proxy, if authentication is needed
-    # @option proxy password [String] The password of the proxy, if authentication is needed
-    # @option proxy headers [Hash] The headers to be used with the proxy
-    # @param timeout [Hash] The hash for configuring timeouts. `per_operation` has priority over `global`
-    # @option timeout per_operation [Hash] Timeouts per operation. Requires `read`, `write`, `connect`
-    # @option timeout global [Integer] Upper bound on total request time
-    def configure_http_client(proxy: {}, timeout: {})
-      @watson_service.configure_http_client(proxy: proxy, timeout: timeout)
-    end
-    # :nocov:
     #########################
     # Translation
     #########################
@@ -182,6 +108,7 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def translate(text:, model_id: nil, source: nil, target: nil)
       raise ArgumentError("text must be provided") if text.nil?
+
       headers = {
       }
       params = {
@@ -239,6 +166,7 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def identify(text:)
       raise ArgumentError("text must be provided") if text.nil?
+
       headers = {
       }
       params = {
@@ -330,6 +258,7 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def create_model(base_model_id:, name: nil, forced_glossary: nil, parallel_corpus: nil, forced_glossary_filename: nil, parallel_corpus_filename: nil)
       raise ArgumentError("base_model_id must be provided") if base_model_id.nil?
+
       headers = {
       }
       params = {
@@ -382,6 +311,7 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def delete_model(model_id:)
       raise ArgumentError("model_id must be provided") if model_id.nil?
+
       headers = {
       }
       params = {
@@ -408,6 +338,7 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def get_model(model_id:)
       raise ArgumentError("model_id must be provided") if model_id.nil?
+
       headers = {
       }
       params = {

data/lib/ibm_watson/natural_language_classifier_v1.rb

@@ -30,7 +30,7 @@ require_relative "./watson_service"
 module IBMWatson
   ##
   # The Natural Language Classifier V1 service.
-  class NaturalLanguageClassifierV1
+  class NaturalLanguageClassifierV1 < WatsonService
     include Concurrent::Async
     ##
     # @!method initialize(args)
@@ -61,7 +61,6 @@ module IBMWatson
     #   'https://iam.ng.bluemix.net/identity/token'.
     def initialize(args = {})
       @__async_initialized__ = false
-      super()
       defaults = {}
       defaults[:url] = "https://gateway.watsonplatform.net/natural-language-classifier/api"
       defaults[:username] = nil
@@ -70,83 +69,10 @@ module IBMWatson
       defaults[:iam_access_token] = nil
       defaults[:iam_url] = nil
       args = defaults.merge(args)
-      @watson_service = WatsonService.new(
-        vcap_services_name: "natural_language_classifier",
-        url: args[:url],
-        username: args[:username],
-        password: args[:password],
-        iam_apikey: args[:iam_apikey],
-        iam_access_token: args[:iam_access_token],
-        iam_url: args[:iam_url],
-        use_vcap_services: true
-      )
-    end
-
-    # :nocov:
-    def add_default_headers(headers: {})
-      @watson_service.add_default_headers(headers: headers)
-    end
-
-    def _iam_access_token(iam_access_token:)
-      @watson_service._iam_access_token(iam_access_token: iam_access_token)
-    end
-
-    def _iam_apikey(iam_apikey:)
-      @watson_service._iam_apikey(iam_apikey: iam_apikey)
-    end
-
-    # @return [DetailedResponse]
-    def request(args)
-      @watson_service.request(args)
-    end
-
-    # @note Chainable
-    # @param headers [Hash] Custom headers to be sent with the request
-    # @return [self]
-    def headers(headers)
-      @watson_service.headers(headers)
-      self
-    end
-
-    def password=(password)
-      @watson_service.password = password
-    end
-
-    def password
-      @watson_service.password
-    end
-
-    def username=(username)
-      @watson_service.username = username
-    end
-
-    def username
-      @watson_service.username
-    end
-
-    def url=(url)
-      @watson_service.url = url
-    end
-
-    def url
-      @watson_service.url
+      args[:vcap_services_name] = "natural_language_classifier"
+      super
     end
 
-    # @!method configure_http_client(proxy: {}, timeout: {})
-    # Sets the http client config, currently works with timeout and proxies
-    # @param proxy [Hash] The hash of proxy configurations
-    # @option proxy address [String] The address of the proxy
-    # @option proxy port [Integer] The port of the proxy
-    # @option proxy username [String] The username of the proxy, if authentication is needed
-    # @option proxy password [String] The password of the proxy, if authentication is needed
-    # @option proxy headers [Hash] The headers to be used with the proxy
-    # @param timeout [Hash] The hash for configuring timeouts. `per_operation` has priority over `global`
-    # @option timeout per_operation [Hash] Timeouts per operation. Requires `read`, `write`, `connect`
-    # @option timeout global [Integer] Upper bound on total request time
-    def configure_http_client(proxy: {}, timeout: {})
-      @watson_service.configure_http_client(proxy: proxy, timeout: timeout)
-    end
-    # :nocov:
     #########################
     # Classify text
     #########################
@@ -161,7 +87,9 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def classify(classifier_id:, text:)
       raise ArgumentError("classifier_id must be provided") if classifier_id.nil?
+
       raise ArgumentError("text must be provided") if text.nil?
+
       headers = {
       }
       data = {
@@ -190,7 +118,9 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def classify_collection(classifier_id:, collection:)
       raise ArgumentError("classifier_id must be provided") if classifier_id.nil?
+
       raise ArgumentError("collection must be provided") if collection.nil?
+
       headers = {
       }
       data = {
@@ -230,7 +160,9 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def create_classifier(metadata:, training_data:, metadata_filename: nil, training_data_filename: nil)
       raise ArgumentError("metadata must be provided") if metadata.nil?
+
       raise ArgumentError("training_data must be provided") if training_data.nil?
+
       headers = {
       }
       mime_type = "application/json"
@@ -291,6 +223,7 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def get_classifier(classifier_id:)
       raise ArgumentError("classifier_id must be provided") if classifier_id.nil?
+
       headers = {
       }
       method_url = "/v1/classifiers/%s" % [ERB::Util.url_encode(classifier_id)]
@@ -310,6 +243,7 @@ module IBMWatson
     # @return [nil]
     def delete_classifier(classifier_id:)
       raise ArgumentError("classifier_id must be provided") if classifier_id.nil?
+
       headers = {
       }
       method_url = "/v1/classifiers/%s" % [ERB::Util.url_encode(classifier_id)]

data/lib/ibm_watson/natural_language_understanding_v1.rb

@@ -35,7 +35,7 @@ require_relative "./watson_service"
 module IBMWatson
   ##
   # The Natural Language Understanding V1 service.
-  class NaturalLanguageUnderstandingV1
+  class NaturalLanguageUnderstandingV1 < WatsonService
     include Concurrent::Async
     ##
     # @!method initialize(args)
@@ -76,7 +76,6 @@ module IBMWatson
     #   'https://iam.ng.bluemix.net/identity/token'.
     def initialize(args = {})
       @__async_initialized__ = false
-      super()
       defaults = {}
       defaults[:version] = nil
       defaults[:url] = "https://gateway.watsonplatform.net/natural-language-understanding/api"
@@ -86,84 +85,11 @@ module IBMWatson
       defaults[:iam_access_token] = nil
       defaults[:iam_url] = nil
       args = defaults.merge(args)
-      @watson_service = WatsonService.new(
-        vcap_services_name: "natural-language-understanding",
-        url: args[:url],
-        username: args[:username],
-        password: args[:password],
-        iam_apikey: args[:iam_apikey],
-        iam_access_token: args[:iam_access_token],
-        iam_url: args[:iam_url],
-        use_vcap_services: true
-      )
+      args[:vcap_services_name] = "natural-language-understanding"
+      super
       @version = args[:version]
     end
 
-    # :nocov:
-    def add_default_headers(headers: {})
-      @watson_service.add_default_headers(headers: headers)
-    end
-
-    def _iam_access_token(iam_access_token:)
-      @watson_service._iam_access_token(iam_access_token: iam_access_token)
-    end
-
-    def _iam_apikey(iam_apikey:)
-      @watson_service._iam_apikey(iam_apikey: iam_apikey)
-    end
-
-    # @return [DetailedResponse]
-    def request(args)
-      @watson_service.request(args)
-    end
-
-    # @note Chainable
-    # @param headers [Hash] Custom headers to be sent with the request
-    # @return [self]
-    def headers(headers)
-      @watson_service.headers(headers)
-      self
-    end
-
-    def password=(password)
-      @watson_service.password = password
-    end
-
-    def password
-      @watson_service.password
-    end
-
-    def username=(username)
-      @watson_service.username = username
-    end
-
-    def username
-      @watson_service.username
-    end
-
-    def url=(url)
-      @watson_service.url = url
-    end
-
-    def url
-      @watson_service.url
-    end
-
-    # @!method configure_http_client(proxy: {}, timeout: {})
-    # Sets the http client config, currently works with timeout and proxies
-    # @param proxy [Hash] The hash of proxy configurations
-    # @option proxy address [String] The address of the proxy
-    # @option proxy port [Integer] The port of the proxy
-    # @option proxy username [String] The username of the proxy, if authentication is needed
-    # @option proxy password [String] The password of the proxy, if authentication is needed
-    # @option proxy headers [Hash] The headers to be used with the proxy
-    # @param timeout [Hash] The hash for configuring timeouts. `per_operation` has priority over `global`
-    # @option timeout per_operation [Hash] Timeouts per operation. Requires `read`, `write`, `connect`
-    # @option timeout global [Integer] Upper bound on total request time
-    def configure_http_client(proxy: {}, timeout: {})
-      @watson_service.configure_http_client(proxy: proxy, timeout: timeout)
-    end
-    # :nocov:
     #########################
     # Analyze
     #########################
@@ -218,18 +144,29 @@ module IBMWatson
     #   \"Leonardo DiCaprio won an Oscar\" returns \"/art and entertainment/movies and
     #   tv/movies\" as the most confident classification.
     # @param features [Features] Specific features to analyze the document for.
-    # @param text [String] The plain text to analyze.
-    # @param html [String] The HTML file to analyze.
-    # @param url [String] The web page to analyze.
+    # @param text [String] The plain text to analyze. One of the `text`, `html`, or `url` parameters is
+    #   required.
+    # @param html [String] The HTML file to analyze. One of the `text`, `html`, or `url` parameters is
+    #   required.
+    # @param url [String] The web page to analyze. One of the `text`, `html`, or `url` parameters is
+    #   required.
     # @param clean [Boolean] Remove website elements, such as links, ads, etc.
-    # @param xpath [String] XPath query for targeting nodes in HTML.
+    # @param xpath [String] An [XPath query](https://www.w3.org/TR/xpath/) to perform on `html` or `url`
+    #   input. Results of the query will be appended to the cleaned webpage text before it
+    #   is analyzed. To analyze only the results of the XPath query, set the `clean`
+    #   parameter to `false`.
     # @param fallback_to_raw [Boolean] Whether to use raw HTML content if text cleaning fails.
     # @param return_analyzed_text [Boolean] Whether or not to return the analyzed text.
-    # @param language [String] ISO 639-1 code indicating the language to use in the analysis.
+    # @param language [String] ISO 639-1 code that specifies the language of your text. This overrides automatic
+    #   language detection. Language support differs depending on the features you include
+    #   in your analysis. See [Language
+    #   support](https://www.bluemix.net/docs/services/natural-language-understanding/language-support.html)
+    #   for more information.
     # @param limit_text_characters [Fixnum] Sets the maximum number of characters that are processed by the service.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def analyze(features:, text: nil, html: nil, url: nil, clean: nil, xpath: nil, fallback_to_raw: nil, return_analyzed_text: nil, language: nil, limit_text_characters: nil)
       raise ArgumentError("features must be provided") if features.nil?
+
       headers = {
       }
       params = {
@@ -294,6 +231,7 @@ module IBMWatson
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def delete_model(model_id:)
       raise ArgumentError("model_id must be provided") if model_id.nil?
+
       headers = {
       }
       params = {