vision.rb in google-cloud-vision-0.28.0

- old
+ new

@@ -13,10 +13,12 @@
 # limitations under the License.
 
 
 require "google-cloud-vision"
 require "google/cloud/vision/project"
+require "google/cloud/config"
+require "google/cloud/env"
 
 module Google
   module Cloud
     ##
     # # Google Cloud Vision
@@ -28,15 +30,16 @@
     #
     # For more information about Cloud Vision, read the [Google Cloud Vision API
     # Documentation](https://cloud.google.com/vision/docs/).
     #
     # The goal of google-cloud is to provide an API that is comfortable to
-    # Rubyists. Authentication is handled by {Google::Cloud#vision}. You can
-    # provide the project and credential information to connect to the Cloud
-    # Vision service, 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
+    # Rubyists. Your authentication credentials are detected automatically in
+    # Google Cloud Platform environments such as Google Compute Engine, Google
+    # App Engine and Google Kubernetes Engine. In other environments you can
+    # configure authentication easily, either directly in your code or via
+    # environment variables. Read more about the options for connecting in the
+    # [Authentication
     # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
     #
     # ## Creating images
     #
     # The Cloud Vision API supports UTF-8, UTF-16, and UTF-32 text encodings.
@@ -224,10 +227,13 @@
         # The default max results to return for facial detection requests. This
         # is used on {Project#annotate} as well as {Image#faces}.
         #
         # The default value is `100`.
         #
+        # This is also available on the configuration as
+        # `Google::Cloud::Vision.configure.default_max_faces`
+        #
         # @example Using the default setting on {Project#annotate}:
         #   require "google/cloud/vision"
         #
         #   vision = Google::Cloud::Vision.new
         #
@@ -271,18 +277,30 @@
         #
         #   faces = vision.image("path/to/faces.jpg").faces
         #   # This is the same as calling
         #   # faces = vision.image("path/to/faces.jpg").faces 5
         #
-        attr_accessor :default_max_faces
+        def default_max_faces= value
+          configure.default_max_faces = value
+        end
 
         ##
+        # The default max results to return for face detection requests.
+        #
+        def default_max_faces
+          configure.default_max_faces
+        end
+
+        ##
         # The default max results to return for landmark detection requests.
         # This is used on {Project#annotate} as well as {Image#landmarks}.
         #
         # The default value is 100.
         #
+        # This is also available on the configuration as
+        # `Google::Cloud::Vision.configure.default_max_landmarks`
+        #
         # @example Using the default setting on {Project#annotate}:
         #   require "google/cloud/vision"
         #
         #   vision = Google::Cloud::Vision.new
         #
@@ -328,18 +346,30 @@
         #
         #   landmarks = vision.image("path/to/landmarks.jpg").landmarks
         #   # This is the same as calling
         #   # landmarks = vision.image("path/to/landmarks.jpg").landmarks 5
         #
-        attr_accessor :default_max_landmarks
+        def default_max_landmarks= value
+          configure.default_max_landmarks = value
+        end
 
         ##
+        # The default max results to return for landmark detection requests.
+        #
+        def default_max_landmarks
+          configure.default_max_landmarks
+        end
+
+        ##
         # The default max results to return for logo detection requests. This is
         # used on {Project#annotate} as well as {Image#logos}.
         #
         # The default value is 100.
         #
+        # This is also available on the configuration as
+        # `Google::Cloud::Vision.configure.default_max_logos`
+        #
         # @example Using the default setting on {Project#annotate}:
         #   require "google/cloud/vision"
         #
         #   vision = Google::Cloud::Vision.new
         #
@@ -383,18 +413,30 @@
         #
         #   logos = vision.image("path/to/logos.jpg").logos
         #   # This is the same as calling
         #   # logos = vision.image("path/to/logos.jpg").logos 5
         #
-        attr_accessor :default_max_logos
+        def default_max_logos= value
+          configure.default_max_logos = value
+        end
 
         ##
+        # The default max results to return for logo detection requests.
+        #
+        def default_max_logos
+          configure.default_max_logos
+        end
+
+        ##
         # The default max results to return for label detection requests. This
         # is used on {Project#annotate} as well as {Image#labels}.
         #
         # The default value is 100.
         #
+        # This is also available on the configuration as
+        # `Google::Cloud::Vision.configure.default_max_labels`
+        #
         # @example Using the default setting on {Project#annotate}:
         #   require "google/cloud/vision"
         #
         #   vision = Google::Cloud::Vision.new
         #
@@ -438,18 +480,30 @@
         #
         #   labels = vision.image("path/to/labels.jpg").labels
         #   # This is the same as calling
         #   # labels = vision.image("path/to/labels.jpg").labels 5
         #
-        attr_accessor :default_max_labels
+        def default_max_labels= value
+          configure.default_max_labels = value
+        end
 
         ##
+        # The default max results to return for label detection requests.
+        #
+        def default_max_labels
+          configure.default_max_labels
+        end
+
+        ##
         # The default max results to return for crop hints detection requests.
         # This is used on {Project#annotate} as well as {Image#crop_hints}.
         #
         # The default value is 100.
         #
+        # This is also available on the configuration as
+        # `Google::Cloud::Vision.configure.default_max_crop_hints`
+        #
         # @example Using the default setting on {Project#annotate}:
         #   require "google/cloud/vision"
         #
         #   vision = Google::Cloud::Vision.new
         #
@@ -495,18 +549,30 @@
         #
         #   crop_hints = vision.image("path/to/landmarks.jpg").crop_hints
         #   # This is the same as calling
         #   # crop_hints = vision.image("path/to/landmarks.jpg").crop_hints 5
         #
-        attr_accessor :default_max_crop_hints
+        def default_max_crop_hints= value
+          configure.default_max_crop_hints = value
+        end
 
         ##
+        # The default max results to return for crop hints detection requests.
+        #
+        def default_max_crop_hints
+          configure.default_max_crop_hints
+        end
+
+        ##
         # The default max results to return for web detection requests.
         # This is used on {Project#annotate} as well as {Image#web}.
         #
         # The default value is 100.
         #
+        # This is also available on the configuration as
+        # `Google::Cloud::Vision.configure.default_max_web`
+        #
         # @example Using the default setting on {Project#annotate}:
         #   require "google/cloud/vision"
         #
         #   vision = Google::Cloud::Vision.new
         #
@@ -552,22 +618,22 @@
         #
         #   web = vision.image("path/to/landmarks.jpg").web
         #   # This is the same as calling
         #   # web = vision.image("path/to/landmarks.jpg").web 5
         #
-        attr_accessor :default_max_web
+        def default_max_web= value
+          configure.default_max_web = value
+        end
+
+        ##
+        # The default max results to return for web detection requests.
+        #
+        def default_max_web
+          configure.default_max_web
+        end
       end
 
-      # Set the default values.
-      # Update the comments documentation when these change.
-      self.default_max_faces      = 100
-      self.default_max_landmarks  = 100
-      self.default_max_logos      = 100
-      self.default_max_labels     = 100
-      self.default_max_crop_hints = 100
-      self.default_max_web        = 100
-
       ##
       # Creates a new object for connecting to the Vision service.
       # Each call creates a new connection.
       #
       # @param [String] project_id Project identifier for the Vision service you
@@ -603,22 +669,82 @@
       #   landmark = image.landmark
       #   landmark.description #=> "Mount Rushmore"
       #
       def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
                    client_config: nil, project: nil, keyfile: nil
-        project_id ||= (project || Vision::Project.default_project_id)
+        project_id ||= (project || default_project_id)
         project_id = project_id.to_s # Always cast to a string
-        fail ArgumentError, "project_id is missing" if project_id.empty?
+        raise ArgumentError, "project_id is missing" if project_id.empty?
 
-        credentials ||= (keyfile || Vision::Credentials.default(scope: scope))
+        scope ||= configure.scope
+        timeout ||= configure.timeout
+        client_config ||= configure.client_config
+        credentials ||= (keyfile || default_credentials(scope: scope))
         unless credentials.is_a? Google::Auth::Credentials
           credentials = Vision::Credentials.new credentials, scope: scope
         end
 
         Vision::Project.new(
           Vision::Service.new(
             project_id, credentials, timeout: timeout,
-                                     client_config: client_config))
+                                     client_config: client_config
+          )
+        )
+      end
+
+      ##
+      # Configure the Google Cloud Vision library.
+      #
+      # The following Vision configuration parameters are supported:
+      #
+      # * `project_id` - (String) Identifier for a Vision 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 {Vision::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.
+      # * `timeout` - (Integer) Default timeout to use in requests.
+      # * `client_config` - (Hash) A hash of values to override the default
+      #   behavior of the API client.
+      # * `default_max_faces` - (Integer) The default max results to return for
+      #   facial detection requests. See {Vision.default_max_faces=}.
+      # * `default_max_landmarks` - (Integer) The default max results to return
+      #   for landmark detection requests. See {Vision.default_max_landmarks=}.
+      # * `default_max_logos` - (Integer) The default max results to return for
+      #   logo detection requests. See {Vision.default_max_logos=}.
+      # * `default_max_labels` - (Integer) The default max results to return for
+      #   label detection requests. See {Vision.default_max_labels=}.
+      # * `default_max_crop_hints` - (Integer) The default max results to return
+      #   for crop hints detection requests. See
+      #   {Vision.default_max_crop_hints=}.
+      # * `default_max_web` - (Integer) The default max results to return for
+      #   web detection requests. See {Vision.default_max_faces=}.
+      #
+      # @return [Google::Cloud::Config] The configuration object the
+      #   Google::Cloud::Vision library uses.
+      #
+      def self.configure
+        yield Google::Cloud.configure.vision if block_given?
+
+        Google::Cloud.configure.vision
+      end
+
+      ##
+      # @private Default project.
+      def self.default_project_id
+        Google::Cloud.configure.vision.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.vision.credentials ||
+          Google::Cloud.configure.credentials ||
+          Vision::Credentials.default(scope: scope)
       end
     end
   end
 end