google-cloud-vision 0.20.2 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 759e9d66fc5ac97bb5ae8c503601c9be1c661a31
-  data.tar.gz: 970f2c09c96cbe48ae9c1105a73ce50d16fefe0c
+  metadata.gz: 327b418796e39bd6b63dcc852e5118650cf14894
+  data.tar.gz: 634d89492078f70090e2ef0d90ca956fa56b2a36
 SHA512:
-  metadata.gz: 980170fbb90dd2f6bdcdbb1761418975688d4bfd05c5e618b3949f723d57c30e013cd82fcd811bfe638002c732c28acdf74fb21e850aa89c9a0aa1a6091b9c7e
-  data.tar.gz: 6b69299bdc20150cf0507f8f7a1ac9d0d7da05646fc249d453804e4a40f887b8da101830e5cc02417d329e3a50cac01e20607d181b6837f0230dca53e5895a5b
+  metadata.gz: f5ba3495829c5814c14e77df4896d83b0005bf983ad1ad5f693483c1d7aa18c455a8ad2cf43ac86e0b59353448af90a69057496b771380dc33c6261348043e03
+  data.tar.gz: fe7cbb4adcd8cb72d9b8e382f3c0f57f70c2a1fc52811c01bf2988e4e01c4c8a7ea9ef03d0b0b171dbefdc22ff4949a8a7067242c1069cfa84739df4bec941a2

data/lib/google-cloud-vision.rb

@@ -35,9 +35,9 @@ module Google
     #   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 [Hash] client_config A hash of values to override the default
+    #   behavior of the API client. Optional.
     #
     # @return [Google::Cloud::Vision::Project]
     #
@@ -59,10 +59,10 @@ module Google
     #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
     #   vision = gcloud.vision scope: platform_scope
     #
-    def vision scope: nil, retries: nil, timeout: nil
+    def vision scope: nil, timeout: nil, client_config: nil
       Google::Cloud.vision @project, @keyfile, scope: scope,
-                                               retries: (retries || @retries),
-                                               timeout: (timeout || @timeout)
+                                               timeout: (timeout || @timeout),
+                                               client_config: client_config
     end
 
     ##
@@ -81,40 +81,28 @@ module Google
     #   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 [Hash] client_config A hash of values to override the default
+    #   behavior of the API client. Optional.
     #
     # @return [Google::Cloud::Vision::Project]
     #
     # @example
-    #   require "google/cloud/vision"
+    #   require "google/cloud"
     #
-    #   gcloud = Google::Cloud.new
-    #   vision = gcloud.vision
+    #   vision = Google::Cloud.vision
     #
     #   image = vision.image "path/to/landmark.jpg"
     #
     #   landmark = image.landmark
     #   landmark.description #=> "Mount Rushmore"
     #
-    def self.vision project = nil, keyfile = nil, scope: nil, retries: nil,
-                    timeout: nil
+    def self.vision project = nil, keyfile = nil, scope: nil, timeout: nil,
+                    client_config: nil
       require "google/cloud/vision"
-      project ||= Google::Cloud::Vision::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::Vision::Credentials.default scope: scope
-      else
-        credentials = Google::Cloud::Vision::Credentials.new \
-          keyfile, scope: scope
-      end
-
-      Google::Cloud::Vision::Project.new(
-        Google::Cloud::Vision::Service.new(
-          project, credentials, retries: retries, timeout: timeout))
+      Google::Cloud::Vision.new project: project, keyfile: keyfile,
+                                scope: scope, timeout: timeout,
+                                client_config: client_config
     end
   end
 end

data/lib/google/cloud/vision.rb

@@ -21,10 +21,10 @@ module Google
     ##
     # # Google Cloud Vision
     #
-    # Google Cloud Vision allows easy integration of vision detection features
-    # developer applications, including image labeling, face and landmark
-    # detection, optical character recognition (OCR), and tagging of explicit
-    # content.
+    # Google Cloud Vision allows developers to easily integrate vision
+    # detection features within applications, including image labeling, face
+    # and landmark detection, optical character recognition (OCR), and tagging
+    # of explicit content.
     #
     # For more information about Cloud Vision, read the [Google Cloud Vision API
     # Documentation](https://cloud.google.com/vision/docs/).
@@ -48,17 +48,16 @@ module Google
     # a request. Reducing your file size can significantly improve throughput;
     # however, be careful not to reduce image quality in the process. See [Best
     # Practices - Image
-    # Sizing](https://cloud.google.com/vision/docs/image-best-practices#image_sizing)
+    # Sizing](https://cloud.google.com/vision/docs/best-practices#image_sizing)
     # for current file size limits.
     #
     # Use {Vision::Project#image} to create images for the Cloud Vision service.
     # You can provide a file path:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/vision"
     #
-    # gcloud = Google::Cloud.new
-    # vision = gcloud.vision
+    # vision = Google::Cloud::Vision.new
     #
     # image = vision.image "path/to/landmark.jpg"
     # ```
@@ -66,10 +65,9 @@ module Google
     # Or, you can initialize the image with a Google Cloud Storage URI:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/vision"
     #
-    # gcloud = Google::Cloud.new
-    # vision = gcloud.vision
+    # vision = Google::Cloud::Vision.new
     #
     # image = vision.image "gs://bucket-name/path_to_image_object"
     # ```
@@ -84,10 +82,9 @@ module Google
     # {Vision::Project#annotate}, below.)
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/vision"
     #
-    # gcloud = Google::Cloud.new
-    # vision = gcloud.vision
+    # vision = Google::Cloud::Vision.new
     #
     # image = vision.image "path/to/face.jpg"
     #
@@ -104,10 +101,9 @@ module Google
     # (or a string file path or Storage URI) to {Vision::Project#annotate}:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/vision"
     #
-    # gcloud = Google::Cloud.new
-    # vision = gcloud.vision
+    # vision = Google::Cloud::Vision.new
     #
     # image = vision.image "path/to/face.jpg"
     #
@@ -120,10 +116,9 @@ module Google
     # request:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/vision"
     #
-    # gcloud = Google::Cloud.new
-    # vision = gcloud.vision
+    # vision = Google::Cloud::Vision.new
     #
     # face_image = vision.image "path/to/face.jpg"
     # landmark_image = vision.image "path/to/landmark.jpg"
@@ -147,10 +142,9 @@ module Google
     # request to the Cloud Vision API:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/vision"
     #
-    # gcloud = Google::Cloud.new
-    # vision = gcloud.vision
+    # vision = Google::Cloud::Vision.new
     #
     # face_image = vision.image "path/to/face.jpg"
     # landmark_image = vision.image "path/to/landmark.jpg"
@@ -177,10 +171,9 @@ module Google
     # global defaults, you can update the configuration:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/vision"
     #
-    # gcloud = Google::Cloud.new
-    # vision = gcloud.vision
+    # vision = Google::Cloud::Vision.new
     #
     # Google::Cloud::Vision.default_max_faces = 1
     #
@@ -192,10 +185,9 @@ module Google
     # integer instead of a flag:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/vision"
     #
-    # gcloud = Google::Cloud.new
-    # vision = gcloud.vision
+    # vision = Google::Cloud::Vision.new
     #
     # image = vision.image "path/to/face.jpg"
     #
@@ -205,24 +197,14 @@ module Google
     # annotation = vision.annotate image, faces: 5
     # ```
     #
-    # ## Configuring retries and timeout
+    # ## Configuring timeout
     #
-    # You can configure how many times API requests may be automatically
-    # retried. When an API request fails, the response will be inspected to see
-    # if the request meets criteria indicating that it may succeed on retry,
-    # such as `500` and `503` status codes or a specific internal error code
-    # such as `rateLimitExceeded`. If it meets the criteria, the request will be
-    # retried after a delay. If another error occurs, the delay will be
-    # increased before a subsequent attempt, until the `retries` limit is
-    # reached.
-    #
-    # You can also set the request `timeout` value in seconds.
+    # You can configure the request `timeout` value in seconds.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/vision"
     #
-    # gcloud = Google::Cloud.new
-    # vision = gcloud.vision retries: 10, timeout: 120
+    # vision = Google::Cloud::Vision.new timeout: 120
     # ```
     #
     module Vision
@@ -234,10 +216,9 @@ module Google
         # The default value is `100`.
         #
         # @example Using the default setting on {Project#annotate}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   Google::Cloud::Vision.default_max_faces #=> 100
         #
@@ -246,10 +227,9 @@ module Google
         #   # annotation = vision.annotate "path/to/faces.jpg", faces: 100
         #
         # @example Updating the default setting on {Project#annotate}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   # Set a new default
         #   Google::Cloud::Vision.default_max_faces = 5
@@ -260,10 +240,9 @@ module Google
         #
         #
         # @example Using the default setting on {Image#faces}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   Google::Cloud::Vision.default_max_faces #=> 100
         #
@@ -272,10 +251,9 @@ module Google
         #   # faces = vision.image("path/to/faces.jpg").faces 100
         #
         # @example Updating the default setting on {Image#faces}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   # Set a new default
         #   Google::Cloud::Vision.default_max_faces = 5
@@ -293,10 +271,9 @@ module Google
         # The default value is 100.
         #
         # @example Using the default setting on {Project#annotate}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   Google::Cloud::Vision.default_max_landmarks #=> 100
         #
@@ -306,10 +283,9 @@ module Google
         #   # annotation = vision.annotate img, landmarks: 100
         #
         # @example Updating the default setting on {Project#annotate}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   # Set a new default
         #   Google::Cloud::Vision.default_max_landmarks = 5
@@ -321,10 +297,9 @@ module Google
         #
         #
         # @example Using the default setting on {Image#landmarks}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   Google::Cloud::Vision.default_max_landmarks #=> 100
         #
@@ -333,10 +308,9 @@ module Google
         #   # landmarks = vision.image("path/to/landmarks.jpg").landmarks 100
         #
         # @example Updating the default setting on {Image#landmarks}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   # Set a new default
         #   Google::Cloud::Vision.default_max_landmarks = 5
@@ -354,10 +328,9 @@ module Google
         # The default value is 100.
         #
         # @example Using the default setting on {Project#annotate}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   Google::Cloud::Vision.default_max_logos #=> 100
         #
@@ -366,10 +339,9 @@ module Google
         #   # annotation = vision.annotate "path/to/logos.jpg", logos: 100
         #
         # @example Updating the default setting on {Project#annotate}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   # Set a new default
         #   Google::Cloud::Vision.default_max_logos = 5
@@ -380,10 +352,9 @@ module Google
         #
         #
         # @example Using the default setting on {Image#logos}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   Google::Cloud::Vision.default_max_logos #=> 100
         #
@@ -392,10 +363,9 @@ module Google
         #   # logos = vision.image("path/to/logos.jpg").logos 100
         #
         # @example Updating the default setting on {Image#logos}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   # Set a new default
         #   Google::Cloud::Vision.default_max_logos = 5
@@ -413,10 +383,9 @@ module Google
         # The default value is 100.
         #
         # @example Using the default setting on {Project#annotate}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   Google::Cloud::Vision.default_max_labels #=> 100
         #
@@ -425,10 +394,9 @@ module Google
         #   # annotation = vision.annotate "path/to/labels.jpg", labels: 100
         #
         # @example Updating the default setting on {Project#annotate}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   # Set a new default
         #   Google::Cloud::Vision.default_max_labels = 5
@@ -439,10 +407,9 @@ module Google
         #
         #
         # @example Using the default setting on {Image#labels}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   Google::Cloud::Vision.default_max_labels #=> 100
         #
@@ -451,10 +418,9 @@ module Google
         #   # labels = vision.image("path/to/labels.jpg").labels 100
         #
         # @example Updating the default setting on {Image#labels}:
-        #   require "google/cloud"
+        #   require "google/cloud/vision"
         #
-        #   gcloud = Google::Cloud.new
-        #   vision = gcloud.vision
+        #   vision = Google::Cloud::Vision.new
         #
         #   # Set a new default
         #   Google::Cloud::Vision.default_max_labels = 5
@@ -472,6 +438,57 @@ module Google
       self.default_max_landmarks = 100
       self.default_max_logos     = 100
       self.default_max_labels    = 100
+
+      ##
+      # Creates a new object for connecting to the Vision service.
+      # Each call creates a new connection.
+      #
+      # @param [String] project Project identifier for the Vision 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.google.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::Vision::Project]
+      #
+      # @example
+      #   require "google/cloud/vision"
+      #
+      #   vision = Google::Cloud::Vision.new
+      #
+      #   image = vision.image "path/to/landmark.jpg"
+      #
+      #   landmark = image.landmark
+      #   landmark.description #=> "Mount Rushmore"
+      #
+      def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
+                   client_config: nil
+        project ||= Google::Cloud::Vision::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::Vision::Credentials.default scope: scope
+        else
+          credentials = Google::Cloud::Vision::Credentials.new \
+            keyfile, scope: scope
+        end
+
+        Google::Cloud::Vision::Project.new(
+          Google::Cloud::Vision::Service.new(
+            project, credentials, timeout: timeout,
+                                  client_config: client_config))
+      end
     end
   end
 end