google-cloud-language 0.27.1 → 0.28.0

data/lib/google/cloud/language/credentials.rb

@@ -1,4 +1,4 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2017, Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,20 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
-require "google/cloud/credentials"
-require "google/cloud/language/v1"
+require "googleauth"
 
 module Google
   module Cloud
     module Language
-      ##
-      # @private Represents the OAuth 2.0 signing logic for Language.
-      class Credentials < Google::Cloud::Credentials
-        SCOPE = V1::LanguageServiceClient::ALL_SCOPES
-        PATH_ENV_VARS = %w(LANGUAGE_KEYFILE GOOGLE_CLOUD_KEYFILE GCLOUD_KEYFILE)
-        JSON_ENV_VARS = %w(LANGUAGE_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON
-                           GCLOUD_KEYFILE_JSON)
+      class Credentials < Google::Auth::Credentials
+        SCOPE = [
+          "https://www.googleapis.com/auth/cloud-platform"
+        ].freeze
+        PATH_ENV_VARS = %w(LANGUAGE_KEYFILE, GOOGLE_CLOUD_KEYFILE, GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(LANGUAGE_KEYFILE_JSON, GOOGLE_CLOUD_KEYFILE_JSON, GCLOUD_KEYFILE_JSON)
+        DEFAULT_PATHS = ["~/.config/gcloud/application_default_credentials.json"]
       end
     end
   end

data/lib/google/cloud/language/v1.rb

@@ -1,4 +1,5 @@
 # Copyright 2017, Google Inc. All rights reserved.
+#
 # 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,3 +13,109 @@
 # limitations under the License.
 
 require "google/cloud/language/v1/language_service_client"
+
+module Google
+  module Cloud
+    # rubocop:disable LineLength
+
+    ##
+    # # Ruby Client for Google Cloud Natural Language API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
+    #
+    # [Google Cloud Natural Language API][Product Documentation]:
+    # Google Cloud Natural Language API provides natural language understanding
+    # technologies to developers. Examples include sentiment analysis, entity
+    # recognition, and text annotations.
+    # - [Product Documentation][]
+    #
+    # ## Quick Start
+    # In order to use this library, you first need to go through the following
+    # steps:
+    #
+    # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+    # 2. [Enable the Google Cloud Natural Language API.](https://console.cloud.google.com/apis/api/language)
+    # 3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
+    #
+    # ### Preview
+    # #### LanguageServiceClient
+    # ```rb
+    # require "google/cloud/language/v1"
+    #
+    # language_service_client = Google::Cloud::Language::V1.new
+    # content = "Hello, world!"
+    # type = :PLAIN_TEXT
+    # document = { content: content, type: type }
+    # response = language_service_client.analyze_sentiment(document)
+    # ```
+    #
+    # ### Next Steps
+    # - Read the [Google Cloud Natural Language API Product documentation][Product Documentation]
+    #   to learn more about the product and see How-to Guides.
+    # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
+    #   to see the full list of Cloud APIs that we cover.
+    #
+    # [Product Documentation]: https://cloud.google.com/language
+    #
+    #
+    module Language
+      module V1
+        # rubocop:enable LineLength
+
+        ##
+        # Provides text analysis operations such as sentiment analysis and entity
+        # recognition.
+        #
+        # @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.
+        def self.new \
+            service_path: nil,
+            port: nil,
+            channel: nil,
+            chan_creds: nil,
+            updater_proc: nil,
+            credentials: nil,
+            scopes: nil,
+            client_config: nil,
+            timeout: nil,
+            lib_name: nil,
+            lib_version: nil
+          kwargs = {
+            service_path: service_path,
+            port: port,
+            channel: channel,
+            chan_creds: chan_creds,
+            updater_proc: updater_proc,
+            credentials: credentials,
+            scopes: scopes,
+            client_config: client_config,
+            timeout: timeout,
+            lib_name: lib_name,
+            lib_version: lib_version
+          }.select { |_, v| v != nil }
+          Google::Cloud::Language::V1::LanguageServiceClient.new(**kwargs)
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/language/v1/doc/google/cloud/language/v1/language_service.rb

@@ -1,4 +1,4 @@
-# Copyright 2017, Google Inc. All rights reserved.
+# Copyright 2017, Google LLC All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -15,6 +15,17 @@
 module Google
   module Cloud
     module Language
+      ##
+      # # Google Cloud Natural Language API Contents
+      #
+      # | Class | Description |
+      # | ----- | ----------- |
+      # | [LanguageServiceClient][] | Google Cloud Natural Language API provides natural language understanding technologies to developers. Examples include sentiment analysis, entity recognition, and text annotations. |
+      # | [Data Types][] | Data types for Google::Cloud::Language::V1 |
+      #
+      # [LanguageServiceClient]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-language/latest/google/cloud/language/v1/languageserviceclient
+      # [Data Types]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-language/latest/google/cloud/language/v1/datatypes
+      #
       module V1
         # ================================================================ #
         #
@@ -37,9 +48,8 @@ module Google
         #     The language of the document (if not specified, the language is
         #     automatically detected). Both ISO and BCP-47 language codes are
         #     accepted.<br>
-        #     **Current Language Restrictions:**
-        #
-        #      * Only English, Spanish, and Japanese textual content are supported.
+        #     [Language Support](https://cloud.google.com/natural-language/docs/languages)
+        #     lists currently supported languages for each API method.
         #     If the language (either specified by the caller or automatically detected)
         #     is not supported by the called API method, an +INVALID_ARGUMENT+ error
         #     is returned.
@@ -63,8 +73,8 @@ module Google
         #     The sentence text.
         # @!attribute [rw] sentiment
         #   @return [Google::Cloud::Language::V1::Sentiment]
-        #     For calls to AnalyzeSentiment or if
-        #     AnnotateTextRequest::Features#extract_document_sentiment is set to
+        #     For calls to {AnalyzeSentiment} or if
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_document_sentiment AnnotateTextRequest::Features#extract_document_sentiment} is set to
         #     true, this field will contain the sentiment for the sentence.
         class Sentence; end
 
@@ -95,6 +105,12 @@ module Google
         #   @return [Array<Google::Cloud::Language::V1::EntityMention>]
         #     The mentions of this entity in the input document. The API currently
         #     supports proper noun mentions.
+        # @!attribute [rw] sentiment
+        #   @return [Google::Cloud::Language::V1::Sentiment]
+        #     For calls to {AnalyzeEntitySentiment} or if
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment} is set to
+        #     true, this field will contain the aggregate sentiment expressed for this
+        #     entity in the provided document.
         class Entity
           # The type of the entity.
           module Type
@@ -136,7 +152,7 @@ module Google
         #     Dependency tree parse for this token.
         # @!attribute [rw] lemma
         #   @return [String]
-        #     {Lemma}[https://en.wikipedia.org/wiki/Lemma_%28morphology%29] of the token.
+        #     [Lemma](https://en.wikipedia.org/wiki/Lemma_%28morphology%29) of the token.
         class Token; end
 
         # Represents the feeling associated with the entire text or entities in
@@ -728,6 +744,24 @@ module Google
 
             # Dislocated relation (for fronted/topicalized elements)
             DISLOCATED = 76
+
+            # Aspect marker
+            ASP = 77
+
+            # Genitive modifier
+            GMOD = 78
+
+            # Genitive object
+            GOBJ = 79
+
+            # Infinitival modifier
+            INFMOD = 80
+
+            # Measure
+            MES = 81
+
+            # Nominal complement of a noun
+            NCOMP = 82
           end
         end
 
@@ -739,6 +773,12 @@ module Google
         # @!attribute [rw] type
         #   @return [Google::Cloud::Language::V1::EntityMention::Type]
         #     The type of the entity mention.
+        # @!attribute [rw] sentiment
+        #   @return [Google::Cloud::Language::V1::Sentiment]
+        #     For calls to {AnalyzeEntitySentiment} or if
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entity_sentiment AnnotateTextRequest::Features#extract_entity_sentiment} is set to
+        #     true, this field will contain the sentiment expressed for this mention of
+        #     the entity in the provided document.
         class EntityMention
           # The supported types of mentions.
           module Type
@@ -760,14 +800,23 @@ module Google
         # @!attribute [rw] begin_offset
         #   @return [Integer]
         #     The API calculates the beginning offset of the content in the original
-        #     document according to the EncodingType specified in the API request.
+        #     document according to the {Google::Cloud::Language::V1::EncodingType EncodingType} specified in the API request.
         class TextSpan; end
 
+        # Represents a category returned from the text classifier.
+        # @!attribute [rw] name
+        #   @return [String]
+        #     The name of the category representing the document.
+        # @!attribute [rw] confidence
+        #   @return [Float]
+        #     The classifier's confidence of the category. Number represents how certain
+        #     the classifier is that this category represents the given text.
+        class ClassificationCategory; end
+
         # The sentiment analysis request message.
         # @!attribute [rw] document
         #   @return [Google::Cloud::Language::V1::Document]
-        #     Input document. Currently, +analyzeSentiment+ only supports English text
-        #     (Document#language="EN").
+        #     Input document.
         # @!attribute [rw] encoding_type
         #   @return [Google::Cloud::Language::V1::EncodingType]
         #     The encoding type used by the API to calculate sentence offsets.
@@ -781,12 +830,32 @@ module Google
         #   @return [String]
         #     The language of the text, which will be the same as the language specified
         #     in the request or, if not specified, the automatically-detected language.
-        #     See +Document.language+ field for more details.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
         # @!attribute [rw] sentences
         #   @return [Array<Google::Cloud::Language::V1::Sentence>]
         #     The sentiment for all the sentences in the document.
         class AnalyzeSentimentResponse; end
 
+        # The entity-level sentiment analysis request message.
+        # @!attribute [rw] document
+        #   @return [Google::Cloud::Language::V1::Document]
+        #     Input document.
+        # @!attribute [rw] encoding_type
+        #   @return [Google::Cloud::Language::V1::EncodingType]
+        #     The encoding type used by the API to calculate offsets.
+        class AnalyzeEntitySentimentRequest; end
+
+        # The entity-level sentiment analysis response message.
+        # @!attribute [rw] entities
+        #   @return [Array<Google::Cloud::Language::V1::Entity>]
+        #     The recognized entities in the input document with associated sentiments.
+        # @!attribute [rw] language
+        #   @return [String]
+        #     The language of the text, which will be the same as the language specified
+        #     in the request or, if not specified, the automatically-detected language.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
+        class AnalyzeEntitySentimentResponse; end
+
         # The entity analysis request message.
         # @!attribute [rw] document
         #   @return [Google::Cloud::Language::V1::Document]
@@ -804,7 +873,7 @@ module Google
         #   @return [String]
         #     The language of the text, which will be the same as the language specified
         #     in the request or, if not specified, the automatically-detected language.
-        #     See +Document.language+ field for more details.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
         class AnalyzeEntitiesResponse; end
 
         # The syntax analysis request message.
@@ -827,9 +896,21 @@ module Google
         #   @return [String]
         #     The language of the text, which will be the same as the language specified
         #     in the request or, if not specified, the automatically-detected language.
-        #     See +Document.language+ field for more details.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
         class AnalyzeSyntaxResponse; end
 
+        # The document classification request message.
+        # @!attribute [rw] document
+        #   @return [Google::Cloud::Language::V1::Document]
+        #     Input document.
+        class ClassifyTextRequest; end
+
+        # The document classification response message.
+        # @!attribute [rw] categories
+        #   @return [Array<Google::Cloud::Language::V1::ClassificationCategory>]
+        #     Categories representing the input document.
+        class ClassifyTextResponse; end
+
         # The request message for the text annotation API, which can perform multiple
         # analysis types (sentiment, entities, and syntax) in one call.
         # @!attribute [rw] document
@@ -853,6 +934,12 @@ module Google
           # @!attribute [rw] extract_document_sentiment
           #   @return [true, false]
           #     Extract document-level sentiment.
+          # @!attribute [rw] extract_entity_sentiment
+          #   @return [true, false]
+          #     Extract entities and their associated sentiment.
+          # @!attribute [rw] classify_text
+          #   @return [true, false]
+          #     Classify the full document into categories.
           class Features; end
         end
 
@@ -860,26 +947,29 @@ module Google
         # @!attribute [rw] sentences
         #   @return [Array<Google::Cloud::Language::V1::Sentence>]
         #     Sentences in the input document. Populated if the user enables
-        #     AnnotateTextRequest::Features#extract_syntax.
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_syntax AnnotateTextRequest::Features#extract_syntax}.
         # @!attribute [rw] tokens
         #   @return [Array<Google::Cloud::Language::V1::Token>]
         #     Tokens, along with their syntactic information, in the input document.
         #     Populated if the user enables
-        #     AnnotateTextRequest::Features#extract_syntax.
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_syntax AnnotateTextRequest::Features#extract_syntax}.
         # @!attribute [rw] entities
         #   @return [Array<Google::Cloud::Language::V1::Entity>]
         #     Entities, along with their semantic information, in the input document.
         #     Populated if the user enables
-        #     AnnotateTextRequest::Features#extract_entities.
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_entities AnnotateTextRequest::Features#extract_entities}.
         # @!attribute [rw] document_sentiment
         #   @return [Google::Cloud::Language::V1::Sentiment]
         #     The overall sentiment for the document. Populated if the user enables
-        #     AnnotateTextRequest::Features#extract_document_sentiment.
+        #     {Google::Cloud::Language::V1::AnnotateTextRequest::Features#extract_document_sentiment AnnotateTextRequest::Features#extract_document_sentiment}.
         # @!attribute [rw] language
         #   @return [String]
         #     The language of the text, which will be the same as the language specified
         #     in the request or, if not specified, the automatically-detected language.
-        #     See +Document.language+ field for more details.
+        #     See {Google::Cloud::Language::V1::Document#language Document#language} field for more details.
+        # @!attribute [rw] categories
+        #   @return [Array<Google::Cloud::Language::V1::ClassificationCategory>]
+        #     Categories identified in the input document.
         class AnnotateTextResponse; end
 
         # Represents the text encoding that the caller uses to process the output.

data/lib/google/cloud/language/v1/doc/overview.rb

@@ -0,0 +1,67 @@
+# Copyright 2017, Google LLC All rights reserved.
+#
+# 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
+#
+#     http://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 Google
+  module Cloud
+    # rubocop:disable LineLength
+
+    ##
+    # # Ruby Client for Google Cloud Natural Language API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
+    #
+    # [Google Cloud Natural Language API][Product Documentation]:
+    # Google Cloud Natural Language API provides natural language understanding
+    # technologies to developers. Examples include sentiment analysis, entity
+    # recognition, and text annotations.
+    # - [Product Documentation][]
+    #
+    # ## Quick Start
+    # In order to use this library, you first need to go through the following
+    # steps:
+    #
+    # 1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+    # 2. [Enable the Google Cloud Natural Language API.](https://console.cloud.google.com/apis/api/language)
+    # 3. [Setup Authentication.](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud/master/guides/authentication)
+    #
+    # ### Installation
+    # ```
+    # $ gem install google-cloud-language
+    # ```
+    #
+    # ### Preview
+    # #### LanguageServiceClient
+    # ```rb
+    # require "google/cloud/language"
+    #
+    # language_service_client = Google::Cloud::Language.new
+    # content = "Hello, world!"
+    # type = :PLAIN_TEXT
+    # document = { content: content, type: type }
+    # response = language_service_client.analyze_sentiment(document)
+    # ```
+    #
+    # ### Next Steps
+    # - Read the [Google Cloud Natural Language API Product documentation][Product Documentation]
+    #   to learn more about the product and see How-to Guides.
+    # - View this [repository's main README](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/README.md)
+    #   to see the full list of Cloud APIs that we cover.
+    #
+    # [Product Documentation]: https://cloud.google.com/language
+    #
+    #
+    module Language
+      module V1
+      end
+    end
+  end
+end