google-cloud-datastore 0.20.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a4bddcc3297345aebef09ee9da78db5455115d08
-  data.tar.gz: 2628c35a3a5a2bdcc77b0c7fc3e8bbe8ed654363
+  metadata.gz: dd3f4b10ef20aa3a1a65d9f8a20b58ba4a3ffd96
+  data.tar.gz: 554c68061d31f3b04479919f479c9246b784d064
 SHA512:
-  metadata.gz: c48dbe7686219d007b4222d032aeea6aac9fc86dd84bc5184a9e109862c9a3e617b6e4d1257d730de04b17e3a376a09701f7331e1200f53936b9c71162983b6d
-  data.tar.gz: 806a531e980a912e677bd576987927dfddea753a5aeefdeb0f6b5b78b2ad47ea375a4e38d009cfa59502655547d5c58ce26fe5b068c3f7c3ee213064886427a4
+  metadata.gz: fa1a4af3be5c459603cd02213345995ffc36d518dcc731fd4dcb9d53f9e85c30b9e6bef26f798789a8829ca16952956c3bbddb79a3d3720665fe98e32f554473
+  data.tar.gz: b985b7b68d29f2604c350380cd3e8e4926800aae54b1351e5e5811e7d807d2f67c85ba95da06cb835412a7eb502e22008d7e500699a1f02cc743c02b1651711a

data/lib/google-cloud-datastore.rb

@@ -38,9 +38,9 @@ module Google
     #   The default scope is:
     #
     #   * `https://www.googleapis.com/auth/datastore`
-    # @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. See Google::Gax::CallSettings. Optional.
     #
     # @return [Google::Cloud::Datastore::Dataset]
     #
@@ -66,10 +66,10 @@ module Google
     #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
     #   datastore = gcloud.datastore scope: platform_scope
     #
-    def datastore scope: nil, retries: nil, timeout: nil
+    def datastore scope: nil, timeout: nil, client_config: nil
       Google::Cloud.datastore @project, @keyfile,
-                              scope: scope, retries: (retries || @retries),
-                              timeout: (timeout || @timeout)
+                              scope: scope, timeout: (timeout || @timeout),
+                              client_config: client_config
     end
 
     ##
@@ -91,14 +91,14 @@ module Google
     #   The default scope is:
     #
     #   * `https://www.googleapis.com/auth/datastore`
-    # @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. See Google::Gax::CallSettings. Optional.
     #
     # @return [Google::Cloud::Datastore::Dataset]
     #
     # @example
-    #   require "google/cloud/datastore"
+    #   require "google/cloud"
     #
     #   datastore = Google::Cloud.datastore "my-todo-project",
     #                              "/path/to/keyfile.json"
@@ -108,34 +108,16 @@ module Google
     #     t["done"] = false
     #     t["priority"] = 4
     #     t["description"] = "Learn Cloud Datastore"
-    #   end
+    #   end                                                                  ``
     #
     #   datastore.save task
     #
-    def self.datastore project = nil, keyfile = nil, scope: nil, retries: nil,
-                       timeout: nil
+    def self.datastore project = nil, keyfile = nil, scope: nil, timeout: nil,
+                       client_config: nil
       require "google/cloud/datastore"
-      project ||= Google::Cloud::Datastore::Dataset.default_project
-      project = project.to_s # Always cast to a string
-      fail ArgumentError, "project is missing" if project.empty?
-
-      if ENV["DATASTORE_EMULATOR_HOST"]
-        return Google::Cloud::Datastore::Dataset.new(
-          Google::Cloud::Datastore::Service.new(
-            project, :this_channel_is_insecure,
-            host: ENV["DATASTORE_EMULATOR_HOST"], retries: retries))
-      end
-
-      if keyfile.nil?
-        credentials = Google::Cloud::Datastore::Credentials.default scope: scope
-      else
-        credentials = Google::Cloud::Datastore::Credentials.new(
-          keyfile, scope: scope)
-      end
-
-      Google::Cloud::Datastore::Dataset.new(
-        Google::Cloud::Datastore::Service.new(
-          project, credentials, retries: retries, timeout: timeout))
+      Google::Cloud::Datastore.new project: project, keyfile: keyfile,
+                                   scope: scope, timeout: timeout,
+                                   client_config: client_config
     end
   end
 end

data/lib/google/cloud/datastore.rb

@@ -36,11 +36,12 @@ module Google
     # is taken care of for you.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new "my-todo-project",
-    #                     "/path/to/keyfile.json"
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new(
+    #   project: "my-todo-project",
+    #   keyfile: "/path/to/keyfile.json"
+    # )
     #
     # task = datastore.find "Task", "sampleTask"
     # task["priority"] = 5
@@ -65,10 +66,9 @@ module Google
     # {Google::Cloud::Datastore::Dataset#find} and passing the parts of the key:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task = datastore.find "Task", "sampleTask"
     # ```
@@ -77,10 +77,9 @@ module Google
     # object:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task_key = datastore.key "Task", 123456
     # task = datastore.find task_key
@@ -94,10 +93,9 @@ module Google
     # (See {Google::Cloud::Datastore::Query#where})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # query = datastore.query("Task").
     #   where("done", "=", false)
@@ -108,10 +106,9 @@ module Google
     # Records can also be ordered. (See {Google::Cloud::Datastore::Query#order})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # query = datastore.query("Task").
     #   order("created")
@@ -123,10 +120,9 @@ module Google
     # (See {Google::Cloud::Datastore::Query#limit})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # query = datastore.query("Task").
     #   limit(5)
@@ -138,10 +134,9 @@ module Google
     # (See {Google::Cloud::Datastore::Query#ancestor})
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task_list_key = datastore.key "TaskList", "default"
     #
@@ -160,10 +155,9 @@ module Google
     # Datastore to return them all.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # query = datastore.query("Task")
     # tasks = datastore.run query
@@ -182,10 +176,9 @@ module Google
     # saved. If the key is incomplete then it will be completed when saved.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task = datastore.entity "Task" do |t|
     #   t["type"] = "Personal"
@@ -201,10 +194,9 @@ module Google
     # Multiple new entities may be created in a batch.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task1 = datastore.entity "Task" do |t|
     #   t["type"] = "Personal"
@@ -251,10 +243,9 @@ module Google
     # {Google::Cloud::Datastore::Dataset#save}.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task = datastore.find "Task", "sampleTask"
     # # Read the priority property
@@ -268,10 +259,9 @@ module Google
     # Array properties can be used to store more than one value.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task = datastore.entity "Task", "sampleTask" do |t|
     #   t["tags"] = ["fun", "programming"]
@@ -286,10 +276,9 @@ module Google
     # or the entity's key object.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task = datastore.find "Task", "sampleTask"
     # datastore.delete task
@@ -298,10 +287,9 @@ module Google
     # Multiple entities may be deleted in a batch.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task_key1 = datastore.key "Task", "sampleTask1"
     # task_key2 = datastore.key "Task", "sampleTask2"
@@ -316,10 +304,9 @@ module Google
     # block completes.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task_key = datastore.key "Task", "sampleTask"
     #
@@ -340,10 +327,9 @@ module Google
     # allowing you to commit or rollback manually.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new
     #
     # task_key = datastore.key "Task", "sampleTask"
     #
@@ -458,30 +444,16 @@ module Google
     # end
     # ```
     #
-    # ## 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/datastore"
     #
-    # gcloud = Google::Cloud.new
-    # datastore = gcloud.datastore retries: 10, timeout: 120
+    # datastore = Google::Cloud::Datastore.new timeout: 120
     # ```
     #
-    # See the [Datastore error
-    # codes](https://cloud.google.com/datastore/docs/concepts/errors#error_codes)
-    # for a list of error conditions.
-    #
     # ## The Cloud Datastore Emulator
     #
     # As of this release, the Cloud Datastore emulator that is part of the
@@ -508,13 +480,12 @@ module Google
     # environment variable:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/datastore"
     #
     # # Make Datastore use the emulator
     # ENV["DATASTORE_EMULATOR_HOST"] = "localhost:8978"
     #
-    # gcloud = Google::Cloud.new "emulator-project-id"
-    # datastore = gcloud.datastore
+    # datastore = Google::Cloud::Datastore.new project: "emulator-project-id"
     #
     # task = datastore.entity "Task", "emulatorTask" do |t|
     #   t["type"] = "Testing"
@@ -527,6 +498,78 @@ module Google
     # ```
     #
     module Datastore
+      ##
+      # Creates a new object for connecting to the Datastore service.
+      # Each call creates a new connection.
+      #
+      # 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 Dataset identifier for the Datastore 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/datastore`
+      # @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. See Google::Gax::CallSettings. Optional.
+      #
+      # @return [Google::Cloud::Datastore::Dataset]
+      #
+      # @example
+      #   require "google/cloud/datastore"
+      #
+      #   datastore = Google::Cloud::Datastore.new(
+      #     project: "my-todo-project",
+      #     keyfile: "/path/to/keyfile.json"
+      #   )
+      #
+      #   task = datastore.entity "Task", "sampleTask" do |t|
+      #     t["type"] = "Personal"
+      #     t["done"] = false
+      #     t["priority"] = 4
+      #     t["description"] = "Learn Cloud Datastore"
+      #   end
+      #
+      #   datastore.save task
+      #
+      def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
+                   client_config: nil
+        project ||= Google::Cloud::Datastore::Dataset.default_project
+        project = project.to_s # Always cast to a string
+        fail ArgumentError, "project is missing" if project.empty?
+
+        if ENV["DATASTORE_EMULATOR_HOST"]
+          return Google::Cloud::Datastore::Dataset.new(
+            Google::Cloud::Datastore::Service.new(
+              project, :this_channel_is_insecure,
+              host: ENV["DATASTORE_EMULATOR_HOST"],
+              client_config: client_config))
+        end
+        credentials = credentials_with_scope keyfile, scope
+        Google::Cloud::Datastore::Dataset.new(
+          Google::Cloud::Datastore::Service.new(
+            project, credentials, timeout: timeout,
+                                  client_config: client_config))
+      end
+
+      ##
+      # @private
+      def self.credentials_with_scope keyfile, scope
+        if keyfile.nil?
+          Google::Cloud::Datastore::Credentials.default(scope: scope)
+        else
+          Google::Cloud::Datastore::Credentials.new(keyfile, scope: scope)
+        end
+      end
     end
   end
 end

data/lib/google/cloud/datastore/commit.rb

@@ -23,8 +23,7 @@ module Google
       # made in a single commit.
       #
       # @example
-      #   gcloud = Google::Cloud.new
-      #   datastore = gcloud.datastore
+      #   datastore = Google::Cloud::Datastore.new
       #   datastore.commit do |c|
       #     c.save task1, task2
       #     c.delete entity1, entity2
@@ -48,8 +47,7 @@ module Google
         # @param [Entity] entities One or more Entity objects to save.
         #
         # @example
-        #   gcloud = Google::Cloud.new
-        #   datastore = gcloud.datastore
+        #   datastore = Google::Cloud::Datastore.new
         #   datastore.commit do |c|
         #     c.save task1, task2
         #   end
@@ -68,8 +66,7 @@ module Google
         # @param [Entity] entities One or more Entity objects to insert.
         #
         # @example
-        #   gcloud = Google::Cloud.new
-        #   datastore = gcloud.datastore
+        #   datastore = Google::Cloud::Datastore.new
         #   datastore.commit do |c|
         #     c.insert task1, task2
         #   end
@@ -87,8 +84,7 @@ module Google
         # @param [Entity] entities One or more Entity objects to update.
         #
         # @example
-        #   gcloud = Google::Cloud.new
-        #   datastore = gcloud.datastore
+        #   datastore = Google::Cloud::Datastore.new
         #   datastore.commit do |c|
         #     c.update task1, task2
         #   end
@@ -107,8 +103,7 @@ module Google
         #   objects to remove.
         #
         # @example
-        #   gcloud = Google::Cloud.new
-        #   datastore = gcloud.datastore
+        #   datastore = Google::Cloud::Datastore.new
         #   datastore.commit do |c|
         #     c.delete task1, task2
         #   end