google-cloud-language 0.27.1 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 640b2b45f1a1c1591831ec87517594559da9089e
-  data.tar.gz: 667181d885dd29cb5bf5638d9671b4e5070bfd75
+SHA256:
+  metadata.gz: 577cf57a9adac4e45b66f535d28a678748bf9b4641ff2f7cc395af122d4c16bb
+  data.tar.gz: 12920a68328d2168090dac303fc7d5ac3a1a46fa79ba91c05111b19a330676ad
 SHA512:
-  metadata.gz: e7466b754816e35ad9da93f510a7666073c5e4852310f4d9ee8b76700ebf51fa4be842eb868fce581fb7a55df349d81c25cddaec3ce12a92b10b4b37de3ce692
-  data.tar.gz: a0dbb87e8d94baadbf8c7e9110775bbf11c007754aa73c49b8da878ba9461809d7ecaaf8be064806b0e8313156340ac1ba9b71d5b3197e1315cc66488acc66b9
+  metadata.gz: eb8130b0e8dc4cc3f5d9a9e0f43f57b403c673d1f60adc06600de84bbd6ddc7214673ae50f3ae8e5a6532669860661e355f8036233bd5e0e385c3c0cf03c5df5
+  data.tar.gz: df63b764ba60e4b7e84f89ba74bf0529918b8794a0ca5c69b339c1c7e2667cdb965b4e4a5f554cbb0f65148ab7947f04d51bffbd4c8a8bee1e93341241890a56

data/.yardopts

@@ -1,10 +1,6 @@
 --no-private
---title=Google Cloud Language
---exclude lib/google/cloud/language/v1.rb
---exclude lib/google/cloud/language/v1/language_service_pb.rb
---exclude lib/google/cloud/language/v1/language_service_services_pb.rb
---exclude lib/google/cloud/language/v1beta2/language_service_pb.rb
---exclude lib/google/cloud/language/v1beta2/language_service_services_pb.rb
+--title=Google Cloud Natural Language API
+--exclude _pb\.rb$
 --markup markdown
 
 ./lib/**/*.rb

data/LICENSE

@@ -1,4 +1,4 @@
-                                 Apache License
+                            Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 

data/README.md

@@ -1,72 +1,48 @@
-# google-cloud-language
+# Ruby Client for Google Cloud Natural Language API ([Beta](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
 
-[Google Cloud Natural Language API](https://cloud.google.com/natural-language/) ([docs](https://cloud.google.com/natural-language/docs)) reveals the structure and meaning of text by offering powerful machine learning models in an easy to use REST API. You can use it to extract information about people, places, events and much more, mentioned in text documents, news articles or blog posts. You can use it to understand sentiment about your product on social media or parse intent from customer conversations happening in a call center or a messaging app. You can analyze text uploaded in your request or integrate with your document storage on Google Cloud Storage.
+[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.
+- [Client Library Documentation][]
+- [Product Documentation][]
 
-The Cloud Natural Language API currently supports English, Spanish, and Japanese for sentiment analysis, entity analysis, and syntax analysis.
-
-- [google-cloud-language API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-language/latest)
-- [google-cloud-language on RubyGems](https://rubygems.org/gems/google-cloud-language)
-- [Google Cloud Natural Language API documentation](https://cloud.google.com/natural-language/docs)
+*This release, 0.28.0, introduces breaking changes relative to the previous
+release, 0.27.1. For more details and instructions to migrate your code, please
+visit the [migration guide](https://cloud.google.com/natural-language/docs/ruby-client-migration).*
 
 ## 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)
 
-```sh
+### Installation
+```
 $ gem install google-cloud-language
 ```
 
-## Authentication
-
-This library uses Service Account credentials to connect to Google Cloud services. When running on Compute Engine the credentials will be discovered automatically. When running on other environments the Service Account credentials can be specified by providing the path to the JSON file, or the JSON itself, in environment variables.
-
-Instructions and configuration options are covered in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-language/guides/authentication).
-
-## Example
-
-```ruby
+### Preview
+#### LanguageServiceClient
+```rb
 require "google/cloud/language"
 
-language = Google::Cloud::Language.new
-
-content = "Star Wars is a great movie. The Death Star is fearsome."
-document = language.document content
-annotation = document.annotate
-
-annotation.entities.count #=> 3
-annotation.sentiment.score #=> 0.10000000149011612
-annotation.sentiment.magnitude #=> 1.100000023841858
-annotation.sentences.count #=> 2
-annotation.tokens.count #=> 13
+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)
 ```
 
-## Supported Ruby Versions
-
-This library is supported on Ruby 2.0+.
-
-## Versioning
-
-This library follows [Semantic Versioning](http://semver.org/).
-
-It is currently in major version zero (0.y.z), which means that anything may change at any time and the public API should not be considered stable.
-
-### Lower-level (GAPIC) API versioning
-
-The lower-level API support contained within this package is versioned separately to match its corresponding Google Cloud Platform service API version.
-
-*Please note that in lower-level API support in this package, version `v1beta2` comes after version `v1`. The API version `v1beta2` contains new features that were not released in `v1`.*
-
-## Contributing
-
-Contributions to this library are always welcome and highly encouraged.
-
-See the [Contributing Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/contributing) for more information on how to get started.
-
-Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See [Code of Conduct](../CODE_OF_CONDUCT.md) for more information.
-
-## License
-
-This library is licensed under Apache 2.0. Full license text is available in [LICENSE](LICENSE).
-
-## Support
+### Next Steps
+- Read the [Client Library Documentation][] for Google Cloud Natural Language API
+  to see other available methods on the client.
+- 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.
 
-Please [report bugs at the project on Github](https://github.com/GoogleCloudPlatform/google-cloud-ruby/issues).
-Don't hesitate to [ask questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby) about the client or APIs on [StackOverflow](http://stackoverflow.com).
+[Client Library Documentation]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-language/latest/google/cloud/language/v1
+[Product Documentation]: https://cloud.google.com/language

data/lib/google/cloud/language.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,255 +12,106 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-
-require "google-cloud-language"
-require "google/cloud/language/project"
+require "google/gax"
+require "pathname"
 
 module Google
   module Cloud
+    # rubocop:disable LineLength
+
     ##
-    # # Google Cloud Natural Language API
-    #
-    # Google Cloud Natural Language API reveals the structure and meaning of
-    # text by offering powerful machine learning models in an easy to use REST
-    # API. You can use it to extract information about people, places, events
-    # and much more, mentioned in text documents, news articles or blog posts.
-    # You can use it to understand sentiment about your product on social media
-    # or parse intent from customer conversations happening in a call center or
-    # a messaging app. You can analyze text uploaded in your request or
-    # integrate with your document storage on Google Cloud Storage. Combine the
-    # API with the Google Cloud Speech API and extract insights from audio
-    # conversations. Use with Vision API OCR to understand scanned documents.
-    # Extract entities and understand sentiments in multiple languages by
-    # translating text first with Cloud Translation API.
-    #
-    # For more information about Cloud Natural Language API, read the [Google
-    # Cloud Natural Language API
-    # Documentation](https://cloud.google.com/natural-language/docs/).
-    #
-    # The goal of google-cloud is to provide an API that is comfortable to
-    # Rubyists. Authentication is handled by {Google::Cloud#language}. You can
-    # provide the project and credential information to connect to the Cloud
-    # Natural Language API, or if you are running on Google Compute Engine this
-    # configuration is taken care of for you. You can read more about the
-    # options for connecting in the [Authentication
-    # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
-    #
-    # ## Creating documents
-    #
-    # Use {Language::Project#document} to create documents for the Cloud Natural
-    # Language service. (The Cloud Natural Language API currently supports
-    # English, Spanish, and Japanese.)
-    #
-    # You can provide text or HTML content as a string:
-    #
-    # ```ruby
-    # require "google/cloud/language"
-    #
-    # language = Google::Cloud::Language.new
-    #
-    # document = language.document "It was the best of times, it was..."
-    # ```
-    #
-    # Or, you can pass a Google Cloud Storage URI for a text or HTML file:
-    #
-    # ```ruby
-    # require "google/cloud/language"
-    #
-    # language = Google::Cloud::Language.new
-    #
-    # document = language.document "gs://bucket-name/path/to/document"
-    # ```
-    #
-    # Or, you can initialize it with a Google Cloud Storage File object:
-    #
-    # ```ruby
-    # require "google/cloud/storage"
-    #
-    # storage = Google::Cloud::Storage.new
-    #
-    # bucket = storage.bucket "bucket-name"
-    # file = bucket.file "path/to/document"
-    #
-    # require "google/cloud/language"
-    #
-    # language = Google::Cloud::Language.new
-    #
-    # document = language.document file
-    # ```
-    #
-    # You can specify the format and language of the content:
-    #
-    # ```ruby
-    # require "google/cloud/language"
-    #
-    # language = Google::Cloud::Language.new
-    #
-    # document = language.document "<p>El viejo y el mar</p>",
-    #                              format: :html, language: "es"
-    # ```
-    #
-    # Creating a Document instance does not perform an API request.
-    #
-    # ## Annotating documents
-    #
-    # The instance methods on {Language::Document} invoke Cloud Natural
-    # Language's detection features individually. Each method call makes an API
-    # request. If you want to run multiple features in a single request, see
-    # the examples for {Language::Document#annotate}, below. Calling `annotate`
-    # with no arguments will perform **all** analysis features. Each feature
-    # is priced separately. See [Pricing](https://cloud.google.com/natural-language/pricing)
-    # for details.
+    # # Ruby Client for Google Cloud Natural Language API ([Alpha](https://github.com/GoogleCloudPlatform/google-cloud-ruby#versioning))
     #
-    # Sentiment analysis inspects the given text and identifies the prevailing
-    # emotional opinion within the text, especially to determine a writer's
-    # attitude as positive, negative, or neutral. Sentiment analysis can be
-    # performed with the {Language::Document#sentiment} method. Currently, only
-    # English is supported for sentiment analysis.
+    # [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][]
     #
-    # ```ruby
-    # require "google/cloud/language"
-    #
-    # language = Google::Cloud::Language.new
-    #
-    # content = "Star Wars is a great movie. The Death Star is fearsome."
-    # document = language.document content
-    # sentiment = document.sentiment # API call
-    #
-    # sentiment.score #=> 0.10000000149011612
-    # sentiment.magnitude #=> 1.100000023841858
-    # ```
+    # ## Quick Start
+    # In order to use this library, you first need to go through the following
+    # steps:
     #
-    # Entity analysis inspects the given text for known entities (proper nouns
-    # such as public figures, landmarks, etc.) and returns information about
-    # those entities. Entity analysis can be performed with the
-    # {Language::Document#entities} method.
+    # 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)
     #
-    # ```ruby
+    # ### Preview
+    # #### LanguageServiceClient
+    # ```rb
     # require "google/cloud/language"
     #
-    # language = Google::Cloud::Language.new
-    #
-    # content = "Star Wars is a great movie. The Death Star is fearsome."
-    # document = language.document content
-    # entities = document.entities # API call
-    #
-    # entities.count #=> 3
-    # entities.first.name #=> "Star Wars"
-    # entities.first.type #=> :WORK_OF_ART
-    # entities.first.mid #=> "/m/06mmr"
-    # entities.first.wikipedia_url #=> "http://en.wikipedia.org/wiki/Star_Wars"
+    # 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)
     # ```
     #
-    # Syntactic analysis extracts linguistic information, breaking up the given
-    # text into a series of sentences and tokens (generally, word boundaries),
-    # providing further analysis on those tokens. Syntactic analysis can be
-    # performed with the {Language::Document#syntax} method.
-    #
-    # ```ruby
-    # require "google/cloud/language"
-    #
-    # language = Google::Cloud::Language.new
+    # ### 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.
     #
-    # content = "Star Wars is a great movie. The Death Star is fearsome."
-    # document = language.document content
-    # syntax = document.syntax # API call
-    #
-    # syntax.sentences.count #=> 2
-    # syntax.tokens.count #=> 13
-    # ```
-    #
-    # To run multiple features on a document in a single request, pass the flag
-    # for each desired feature to {Language::Document#annotate}:
-    #
-    # ```ruby
-    # require "google/cloud/language"
-    #
-    # language = Google::Cloud::Language.new
-    #
-    # content = "Star Wars is a great movie. The Death Star is fearsome."
-    # document = language.document content
-    # annotation = document.annotate entities: true, syntax: true
-    #
-    # annotation.entities.count #=> 3
-    # annotation.sentences.count #=> 2
-    # annotation.tokens.count #=> 13
-    # ```
+    # [Product Documentation]: https://cloud.google.com/language
     #
-    # Or, simply call {Language::Document#annotate} with no arguments to process
-    # the document with **all** features:
-    #
-    # ```ruby
-    # require "google/cloud/language"
-    #
-    # language = Google::Cloud::Language.new
-    #
-    # content = "Star Wars is a great movie. The Death Star is fearsome."
-    # document = language.document content
-    # annotation = document.annotate
-    #
-    # annotation.sentiment.score #=> 0.10000000149011612
-    # annotation.sentiment.magnitude #=> 1.100000023841858
-    # annotation.entities.count #=> 3
-    # annotation.sentences.count #=> 2
-    # annotation.tokens.count #=> 13
-    # ```
     #
     module Language
+      # rubocop:enable LineLength
+
+      FILE_DIR = File.realdirpath(Pathname.new(__FILE__).join("..").join("language"))
+
+      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 the Language service.
-      # Each call creates a new connection.
+      # Provides text analysis operations such as sentiment analysis and entity
+      # recognition.
       #
-      # For more information on connecting to Google Cloud see the
-      # [Authentication
-      # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
-      #
-      # @param [String] project Project identifier for the Language service you
-      #   are connecting to.
-      # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
-      #   file path the file must be readable.
-      # @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.goorequire
-      #   "google/cloud"gle.com/identity/protocols/OAuth2).
-      #
-      #   The default scope is:
-      #
-      #   * `"https://www.googleapis.com/auth/cloud-platform"`
-      # @param [Integer] timeout Default timeout to use in requests. Optional.
-      # @param [Hash] client_config A hash of values to override the default
-      #   behavior of the API client. Optional.
-      #
-      # @return [Google::Cloud::Language::Project]
-      #
-      # @example
-      #   require "google/cloud/language"
-      #
-      #   language = Google::Cloud::Language.new
-      #
-      #   content = "Star Wars is a great movie. The Death Star is fearsome."
-      #   document = language.document content
-      #   annotation = document.annotate
-      #
-      def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
-                   client_config: nil
-        project ||= Google::Cloud::Language::Project.default_project
-        project = project.to_s # Always cast to a string
-        fail ArgumentError, "project is missing" if project.empty?
-
-        if keyfile.nil?
-          credentials = Google::Cloud::Language::Credentials.default(
-            scope: scope)
-        else
-          credentials = Google::Cloud::Language::Credentials.new(
-            keyfile, scope: scope)
+      # @param version [Symbol, String]
+      #   The major version of the service to be used. By default :v1
+      #   is used.
+      # @overload new(version:, credentials:, scopes:, client_config:, timeout:)
+      #   @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(*args, version: :v1, **kwargs)
+        unless AVAILABLE_VERSIONS.include?(version.to_s.downcase)
+          raise "The version: #{version} is not available. The available versions " \
+            "are: [#{AVAILABLE_VERSIONS.join(", ")}]"
         end
 
-        Google::Cloud::Language::Project.new(
-          Google::Cloud::Language::Service.new(
-            project, credentials, timeout: timeout,
-                                  client_config: client_config))
+        require "#{FILE_DIR}/#{version.to_s.downcase}"
+        version_module = Google::Cloud::Language
+          .constants
+          .select {|sym| sym.to_s.downcase == version.to_s.downcase}
+          .first
+        Google::Cloud::Language.const_get(version_module).new(*args, **kwargs)
       end
     end
   end