gcloud 0.12.2 → 0.20.0

data/lib/gcloud/credentials.rb

@@ -1,129 +0,0 @@
-# Copyright 2014 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
-#
-#     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.
-
-
-require "json"
-require "signet/oauth_2/client"
-require "forwardable"
-require "googleauth"
-
-module Gcloud
-  ##
-  # @private
-  # Represents the OAuth 2.0 signing logic.
-  # This class is intended to be inherited by API-specific classes
-  # which overrides the SCOPE constant.
-  class Credentials
-    TOKEN_CREDENTIAL_URI = "https://accounts.google.com/o/oauth2/token"
-    AUDIENCE = "https://accounts.google.com/o/oauth2/token"
-    SCOPE = []
-    PATH_ENV_VARS = %w(GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)
-    JSON_ENV_VARS = %w(GCLOUD_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON)
-    DEFAULT_PATHS = ["~/.config/gcloud/application_default_credentials.json"]
-
-    attr_accessor :client
-
-    ##
-    # Delegate client methods to the client object.
-    extend Forwardable
-    def_delegators :@client,
-                   :token_credential_uri, :audience,
-                   :scope, :issuer, :signing_key
-
-    def initialize keyfile, scope: nil
-      verify_keyfile_provided! keyfile
-      if keyfile.is_a? Signet::OAuth2::Client
-        @client = keyfile
-      elsif keyfile.is_a? Hash
-        hash = stringify_hash_keys keyfile
-        hash["scope"] ||= scope
-        @client = init_client hash
-      else
-        verify_keyfile_exists! keyfile
-        json = JSON.parse ::File.read(keyfile)
-        json["scope"] ||= scope
-        @client = init_client json
-      end
-      @client.fetch_access_token!
-    end
-
-    ##
-    # Returns the default credentials.
-    #
-    def self.default scope: nil
-      env  = ->(v) { ENV[v] }
-      json = ->(v) { JSON.parse ENV[v] rescue nil unless ENV[v].nil? }
-      path = ->(p) { ::File.file? p }
-
-      # First try to find keyfile file from environment variables.
-      self::PATH_ENV_VARS.map(&env).reject(&:nil?).select(&path).each do |file|
-        return new file, scope: scope
-      end
-      # Second try to find keyfile json from environment variables.
-      self::JSON_ENV_VARS.map(&json).reject(&:nil?).each do |hash|
-        return new hash, scope: scope
-      end
-      # Third try to find keyfile file from known file paths.
-      self::DEFAULT_PATHS.select(&path).each do |file|
-        return new file, scope: scope
-      end
-      # Finally get instantiated client from Google::Auth.
-      scope ||= self::SCOPE
-      client = Google::Auth.get_application_default scope
-      new client
-    end
-
-    protected
-
-    ##
-    # Verify that the keyfile argument is provided.
-    def verify_keyfile_provided! keyfile
-      fail "You must provide a keyfile to connect with." if keyfile.nil?
-    end
-
-    ##
-    # Verify that the keyfile argument is a file.
-    def verify_keyfile_exists! keyfile
-      exists = ::File.file? keyfile
-      fail "The keyfile '#{keyfile}' is not a valid file." unless exists
-    end
-
-    ##
-    # Initializes the Signet client.
-    def init_client keyfile
-      client_opts = client_options keyfile
-      Signet::OAuth2::Client.new client_opts
-    end
-
-    ##
-    # returns a new Hash with string keys instead of symbol keys.
-    def stringify_hash_keys hash
-      Hash[hash.map { |(k, v)| [k.to_s, v] }]
-    end
-
-    def client_options options
-      # Keyfile options have higher priority over constructor defaults
-      options["token_credential_uri"] ||= self.class::TOKEN_CREDENTIAL_URI
-      options["audience"]             ||= self.class::AUDIENCE
-      options["scope"]                ||= self.class::SCOPE
-
-      # client options for initializing signet client
-      { token_credential_uri: options["token_credential_uri"],
-        audience: options["audience"],
-        scope: Array(options["scope"]),
-        issuer: options["client_email"],
-        signing_key: OpenSSL::PKey::RSA.new(options["private_key"]) }
-    end
-  end
-end

data/lib/gcloud/datastore/commit.rb

@@ -1,148 +0,0 @@
-# Copyright 2016 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
-#
-#     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 Gcloud
-  module Datastore
-    ##
-    # # Commit
-    #
-    # Object yielded from `commit` methods to allow multiple changes to be made
-    # in a single commit.
-    #
-    # @example
-    #   gcloud = Gcloud.new
-    #   datastore = gcloud.datastore
-    #   datastore.commit do |c|
-    #     c.save task1, task2
-    #     c.delete entity1, entity2
-    #   end
-    #
-    # See {Gcloud::Datastore::Dataset#commit} and
-    # {Gcloud::Datastore::Transaction#commit}.
-    class Commit
-      ##
-      # @private Create a new Commit object.
-      def initialize
-        @shared_upserts = []
-        @shared_inserts = []
-        @shared_updates = []
-        @shared_deletes = []
-      end
-
-      ##
-      # Saves entities to the Datastore.
-      #
-      # @param [Entity] entities One or more Entity objects to save.
-      #
-      # @example
-      #   gcloud = Gcloud.new
-      #   datastore = gcloud.datastore
-      #   datastore.commit do |c|
-      #     c.save task1, task2
-      #   end
-      #
-      def save *entities
-        entities = Array(entities).flatten
-        @shared_upserts += entities unless entities.empty?
-        # Do not save yet
-        entities
-      end
-      alias_method :upsert, :save
-
-      ##
-      # Inserts entities to the Datastore.
-      #
-      # @param [Entity] entities One or more Entity objects to insert.
-      #
-      # @example
-      #   gcloud = Gcloud.new
-      #   datastore = gcloud.datastore
-      #   datastore.commit do |c|
-      #     c.insert task1, task2
-      #   end
-      #
-      def insert *entities
-        entities = Array(entities).flatten
-        @shared_inserts += entities unless entities.empty?
-        # Do not insert yet
-        entities
-      end
-
-      ##
-      # Updates entities to the Datastore.
-      #
-      # @param [Entity] entities One or more Entity objects to update.
-      #
-      # @example
-      #   gcloud = Gcloud.new
-      #   datastore = gcloud.datastore
-      #   datastore.commit do |c|
-      #     c.update task1, task2
-      #   end
-      #
-      def update *entities
-        entities = Array(entities).flatten
-        @shared_updates += entities unless entities.empty?
-        # Do not update yet
-        entities
-      end
-
-      ##
-      # Remove entities from the Datastore.
-      #
-      # @param [Entity, Key] entities_or_keys One or more Entity or Key
-      #   objects to remove.
-      #
-      # @example
-      #   gcloud = Gcloud.new
-      #   datastore = gcloud.datastore
-      #   datastore.commit do |c|
-      #     c.delete task1, task2
-      #   end
-      #
-      def delete *entities_or_keys
-        keys = Array(entities_or_keys).flatten.map do |e_or_k|
-          e_or_k.respond_to?(:key) ? e_or_k.key : e_or_k
-        end
-        @shared_deletes += keys unless keys.empty?
-        # Do not delete yet
-        true
-      end
-
-      # @private Mutations object to be committed.
-      def mutations
-        mutations = []
-        mutations += @shared_upserts.map do |entity|
-          Google::Datastore::V1beta3::Mutation.new upsert: entity.to_grpc
-        end
-        mutations += @shared_inserts.map do |entity|
-          Google::Datastore::V1beta3::Mutation.new insert: entity.to_grpc
-        end
-        mutations += @shared_updates.map do |entity|
-          Google::Datastore::V1beta3::Mutation.new update: entity.to_grpc
-        end
-        mutations += @shared_deletes.map do |key|
-          Google::Datastore::V1beta3::Mutation.new delete: key.to_grpc
-        end
-        mutations
-      end
-
-      # @private All entities saved in the commit.
-      def entities
-        @shared_upserts + @shared_inserts + @shared_updates
-      end
-    end
-  end
-end

data/lib/gcloud/datastore/credentials.rb

@@ -1,35 +0,0 @@
-# Copyright 2014 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
-#
-#     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.
-
-
-require "gcloud/credentials"
-
-module Gcloud
-  module Datastore
-    ##
-    # @private
-    #
-    # Authentication credentials to Google Cloud.
-    # The most common way to create this object is to provide the path
-    # to the JSON keyfile downloaded from Google Cloud.
-    #
-    # @see https://developers.google.com/accounts/docs/application-default-credentials
-    class Credentials < Gcloud::Credentials
-      SCOPE = ["https://www.googleapis.com/auth/datastore"]
-      PATH_ENV_VARS = %w(DATASTORE_KEYFILE GCLOUD_KEYFILE GOOGLE_CLOUD_KEYFILE)
-      JSON_ENV_VARS = %w(DATASTORE_KEYFILE_JSON GCLOUD_KEYFILE_JSON
-                         GOOGLE_CLOUD_KEYFILE_JSON)
-    end
-  end
-end

data/lib/gcloud/datastore/cursor.rb

@@ -1,76 +0,0 @@
-# Copyright 2016 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
-#
-#     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 Gcloud
-  module Datastore
-    ##
-    # # Cursor
-    #
-    # Cursor is a point in query results. Cursors are returned in QueryResults.
-    #
-    # @example
-    #   require "gcloud"
-    #
-    #   gcloud = Gcloud.new
-    #   datastore = gcloud.datastore
-    #
-    #   query = datastore.query("Task").
-    #     where("done", "=", false)
-    #
-    #   tasks = datastore.run query
-    #   tasks.cursor #=> Cursor
-    #
-    class Cursor
-      # Base64 encoded array of bytes
-      def initialize cursor
-        @cursor = cursor
-      end
-
-      # Base64 encoded array of bytes
-      def to_s
-        @cursor
-      end
-
-      # @private
-      def inspect
-        "#{self.class}(#{@cursor})"
-      end
-
-      # @private
-      def == other
-        return false unless other.is_a? Cursor
-        @cursor == other.to_s
-      end
-
-      # @private
-      def <=> other
-        return -1 unless other.is_a? Cursor
-        @cursor <=> other.to_s
-      end
-
-      # @private byte array as a string
-      def to_grpc
-        GRPCUtils.decode_bytes(@cursor)
-      end
-
-      # @private byte array as a string
-      def self.from_grpc grpc
-        grpc = String grpc
-        return nil if grpc.empty?
-        new GRPCUtils.encode_bytes(grpc)
-      end
-    end
-  end
-end

data/lib/gcloud/datastore/dataset.rb

@@ -1,660 +0,0 @@
-# Copyright 2014 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
-#
-#     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.
-
-
-require "gcloud/gce"
-require "gcloud/datastore/grpc_utils"
-require "gcloud/datastore/credentials"
-require "gcloud/datastore/service"
-require "gcloud/datastore/commit"
-require "gcloud/datastore/entity"
-require "gcloud/datastore/key"
-require "gcloud/datastore/query"
-require "gcloud/datastore/gql_query"
-require "gcloud/datastore/cursor"
-require "gcloud/datastore/dataset/lookup_results"
-require "gcloud/datastore/dataset/query_results"
-
-module Gcloud
-  module Datastore
-    ##
-    # # Dataset
-    #
-    # Dataset is the data saved in a project's Datastore.
-    # Dataset is analogous to a database in relational database world.
-    #
-    # Gcloud::Datastore::Dataset is the main object for interacting with
-    # Google Datastore. {Gcloud::Datastore::Entity} objects are created,
-    # read, updated, and deleted by Gcloud::Datastore::Dataset.
-    #
-    # See {Gcloud#datastore}
-    #
-    # @example
-    #   require "gcloud"
-    #
-    #   gcloud = Gcloud.new
-    #   datastore = gcloud.datastore
-    #
-    #   query = datastore.query("Task").
-    #     where("done", "=", false)
-    #
-    #   tasks = datastore.run query
-    #
-    class Dataset
-      ##
-      # @private The gRPC Service object.
-      attr_accessor :service
-
-      ##
-      # @private Creates a new Dataset instance.
-      #
-      # See {Gcloud#datastore}
-      def initialize service
-        @service = service
-      end
-
-      ##
-      # The Datastore project connected to.
-      #
-      # @example
-      #   require "gcloud"
-      #
-      #   gcloud = Gcloud.new "my-todo-project",
-      #                       "/path/to/keyfile.json"
-      #
-      #   datastore = gcloud.datastore
-      #   datastore.project #=> "my-todo-project"
-      #
-      def project
-        service.project
-      end
-
-      ##
-      # @private Default project.
-      def self.default_project
-        ENV["DATASTORE_DATASET"] ||
-          ENV["DATASTORE_PROJECT"] ||
-          ENV["GCLOUD_PROJECT"] ||
-          ENV["GOOGLE_CLOUD_PROJECT"] ||
-          Gcloud::GCE.project_id
-      end
-
-      ##
-      # Generate IDs for a Key before creating an entity.
-      #
-      # @param [Key] incomplete_key A Key without `id` or `name` set.
-      # @param [String] count The number of new key IDs to create.
-      #
-      # @return [Array<Gcloud::Datastore::Key>]
-      #
-      # @example
-      #   task_key = datastore.key "Task"
-      #   task_keys = datastore.allocate_ids task_key, 5
-      #
-      def allocate_ids incomplete_key, count = 1
-        if incomplete_key.complete?
-          fail Gcloud::Datastore::KeyError,
-               "An incomplete key must be provided."
-        end
-
-        ensure_service!
-        incomplete_keys = count.times.map { incomplete_key.to_grpc }
-        allocate_res = service.allocate_ids(*incomplete_keys)
-        allocate_res.keys.map { |key| Key.from_grpc key }
-      end
-
-      ##
-      # Persist one or more entities to the Datastore.
-      #
-      # @param [Entity] entities One or more entity objects to be saved.
-      #
-      # @return [Array<Gcloud::Datastore::Entity>]
-      #
-      # @example Insert a new entity:
-      #   task = datastore.entity "Task" do |t|
-      #     t["type"] = "Personal"
-      #     t["done"] = false
-      #     t["priority"] = 4
-      #     t["description"] = "Learn Cloud Datastore"
-      #   end
-      #   task.key.id #=> nil
-      #   datastore.save task
-      #   task.key.id #=> 123456
-      #
-      # @example Insert multiple new entities in a batch:
-      #   task1 = datastore.entity "Task" do |t|
-      #     t["type"] = "Personal"
-      #     t["done"] = false
-      #     t["priority"] = 4
-      #     t["description"] = "Learn Cloud Datastore"
-      #   end
-      #
-      #   task2 = datastore.entity "Task" do |t|
-      #     t["type"] = "Personal"
-      #     t["done"] = false
-      #     t["priority"] = 5
-      #     t["description"] = "Integrate Cloud Datastore"
-      #   end
-      #
-      #   task_key1, task_key2 = datastore.save(task1, task2).map(&:key)
-      #
-      # @example Update an existing entity:
-      #   task = datastore.find "Task", "sampleTask"
-      #   task["priority"] = 5
-      #   datastore.save task
-      #
-      def save *entities
-        commit { |c| c.save(*entities) }
-      end
-      alias_method :upsert, :save
-
-      ##
-      # Insert one or more entities to the Datastore. An InvalidArgumentError
-      # will raised if the entities cannot be inserted.
-      #
-      # @param [Entity] entities One or more entity objects to be inserted.
-      #
-      # @return [Array<Gcloud::Datastore::Entity>]
-      #
-      # @example Insert a new entity:
-      #   task = datastore.entity "Task" do |t|
-      #     t["type"] = "Personal"
-      #     t["done"] = false
-      #     t["priority"] = 4
-      #     t["description"] = "Learn Cloud Datastore"
-      #   end
-      #   task.key.id #=> nil
-      #   datastore.insert task
-      #   task.key.id #=> 123456
-      #
-      # @example Insert multiple new entities in a batch:
-      #   task1 = datastore.entity "Task" do |t|
-      #     t["type"] = "Personal"
-      #     t["done"] = false
-      #     t["priority"] = 4
-      #     t["description"] = "Learn Cloud Datastore"
-      #   end
-      #
-      #   task2 = datastore.entity "Task" do |t|
-      #     t["type"] = "Personal"
-      #     t["done"] = false
-      #     t["priority"] = 5
-      #     t["description"] = "Integrate Cloud Datastore"
-      #   end
-      #
-      #   task_key1, task_key2 = datastore.insert(task1, task2).map(&:key)
-      #
-      def insert *entities
-        commit { |c| c.insert(*entities) }
-      end
-
-      ##
-      # Update one or more entities to the Datastore. An InvalidArgumentError
-      # will raised if the entities cannot be updated.
-      #
-      # @param [Entity] entities One or more entity objects to be updated.
-      #
-      # @return [Array<Gcloud::Datastore::Entity>]
-      #
-      # @example Update an existing entity:
-      #   task = datastore.find "Task", "sampleTask"
-      #   task["done"] = true
-      #   datastore.save task
-      #
-      # @example update multiple new entities in a batch:
-      #   query = datastore.query("Task").where("done", "=", false)
-      #   tasks = datastore.run query
-      #   tasks.each { |t| t["done"] = true }
-      #   datastore.update tasks
-      #
-      def update *entities
-        commit { |c| c.update(*entities) }
-      end
-
-      ##
-      # Remove entities from the Datastore.
-      #
-      # @param [Entity, Key] entities_or_keys One or more Entity or Key objects
-      #   to remove.
-      #
-      # @return [Boolean] Returns `true` if successful
-      #
-      # @example
-      #   gcloud = Gcloud.new
-      #   datastore = gcloud.datastore
-      #   datastore.delete task1, task2
-      #
-      def delete *entities_or_keys
-        commit { |c| c.delete(*entities_or_keys) }
-        true
-      end
-
-      ##
-      # Make multiple changes in a single commit.
-      #
-      # @yield [commit] a block for making changes
-      # @yieldparam [Commit] commit The object that changes are made on
-      #
-      # @return [Array<Gcloud::Datastore::Entity>] The entities that were
-      #   persisted.
-      #
-      # @example
-      #   gcloud = Gcloud.new
-      #   datastore = gcloud.datastore
-      #   datastore.commit do |c|
-      #     c.save task3, task4
-      #     c.delete task1, task2
-      #   end
-      #
-      def commit
-        return unless block_given?
-        c = Commit.new
-        yield c
-
-        ensure_service!
-        commit_res = service.commit c.mutations
-        entities = c.entities
-        returned_keys = commit_res.mutation_results.map(&:key)
-        returned_keys.each_with_index do |key, index|
-          next if entities[index].nil?
-          entities[index].key = Key.from_grpc(key) unless key.nil?
-        end
-        entities.each { |e| e.key.freeze unless e.persisted? }
-        entities
-      end
-
-      ##
-      # Retrieve an entity by key.
-      #
-      # @param [Key, String] key_or_kind A Key object or `kind` string value.
-      # @param [Integer, String, nil] id_or_name The Key's `id` or `name` value
-      #   if a `kind` was provided in the first parameter.
-      # @param [Symbol] consistency The non-transactional read consistency to
-      #   use. Cannot be set to `:strong` for global queries. Accepted values
-      #   are `:eventual` and `:strong`.
-      #
-      #   The default consistency depends on the type of lookup used. See
-      #   [Eventual Consistency in Google Cloud
-      #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
-      #   for more information.
-      #
-      # @return [Gcloud::Datastore::Entity, nil]
-      #
-      # @example Finding an entity with a key:
-      #   task_key = datastore.key "Task", "sampleTask"
-      #   task = datastore.find task_key
-      #
-      # @example Finding an entity with a `kind` and `id`/`name`:
-      #   task = datastore.find "Task", "sampleTask"
-      #
-      def find key_or_kind, id_or_name = nil, consistency: nil
-        key = key_or_kind
-        unless key.is_a? Gcloud::Datastore::Key
-          key = Key.new key_or_kind, id_or_name
-        end
-        find_all(key, consistency: consistency).first
-      end
-      alias_method :get, :find
-
-      ##
-      # Retrieve the entities for the provided keys. The order of results is
-      # undefined and has no relation to the order of `keys` arguments.
-      #
-      # @param [Key] keys One or more Key objects to find records for.
-      # @param [Symbol] consistency The non-transactional read consistency to
-      #   use. Cannot be set to `:strong` for global queries. Accepted values
-      #   are `:eventual` and `:strong`.
-      #
-      #   The default consistency depends on the type of lookup used. See
-      #   [Eventual Consistency in Google Cloud
-      #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
-      #   for more information.
-      #
-      # @return [Gcloud::Datastore::Dataset::LookupResults]
-      #
-      # @example
-      #   gcloud = Gcloud.new
-      #   datastore = gcloud.datastore
-      #
-      #   task_key1 = datastore.key "Task", "sampleTask1"
-      #   task_key2 = datastore.key "Task", "sampleTask2"
-      #   tasks = datastore.find_all task_key1, task_key2
-      #
-      def find_all *keys, consistency: nil
-        ensure_service!
-        check_consistency! consistency
-        lookup_res = service.lookup(*Array(keys).flatten.map(&:to_grpc),
-                                    consistency: consistency)
-        LookupResults.from_grpc lookup_res, service, consistency
-      end
-      alias_method :lookup, :find_all
-
-      ##
-      # Retrieve entities specified by a Query.
-      #
-      # @param [Query, GqlQuery] query The object with the search criteria.
-      # @param [String] namespace The namespace the query is to run within.
-      # @param [Symbol] consistency The non-transactional read consistency to
-      #   use. Cannot be set to `:strong` for global queries. Accepted values
-      #   are `:eventual` and `:strong`.
-      #
-      #   The default consistency depends on the type of query used. See
-      #   [Eventual Consistency in Google Cloud
-      #   Datastore](https://cloud.google.com/datastore/docs/articles/balancing-strong-and-eventual-consistency-with-google-cloud-datastore/#h.tf76fya5nqk8)
-      #   for more information.
-      #
-      # @return [Gcloud::Datastore::Dataset::QueryResults]
-      #
-      # @example
-      #   query = datastore.query("Task").
-      #     where("done", "=", false)
-      #   tasks = datastore.run query
-      #
-      # @example Run an ancestor query with eventual consistency:
-      #   task_list_key = datastore.key "TaskList", "default"
-      #   query.kind("Task").
-      #     ancestor(task_list_key)
-      #
-      #   tasks = datastore.run query, consistency: :eventual
-      #
-      # @example Run the query within a namespace with the `namespace` option:
-      #   query = datastore.query("Task").
-      #     where("done", "=", false)
-      #   tasks = datastore.run query, namespace: "ns~todo-project"
-      #
-      # @example Run the query with a GQL string.
-      #   gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
-      #                             done: false
-      #   tasks = datastore.run gql_query
-      #
-      # @example Run the GQL query within a namespace with `namespace` option:
-      #   gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
-      #                             done: false
-      #   tasks = datastore.run gql_query, namespace: "ns~todo-project"
-      #
-      def run query, namespace: nil, consistency: nil
-        ensure_service!
-        unless query.is_a?(Query) || query.is_a?(GqlQuery)
-          fail ArgumentError, "Cannot run a #{query.class} object."
-        end
-        check_consistency! consistency
-        query_res = service.run_query query.to_grpc, namespace,
-                                      consistency: consistency
-        QueryResults.from_grpc query_res, service, namespace, query.to_grpc.dup
-      end
-      alias_method :run_query, :run
-
-      ##
-      # Creates a Datastore Transaction.
-      #
-      # @yield [tx] a block yielding a new transaction
-      # @yieldparam [Transaction] tx the transaction object
-      #
-      # @example Runs the given block in a database transaction:
-      #   require "gcloud"
-      #
-      #   gcloud = Gcloud.new
-      #   datastore = gcloud.datastore
-      #
-      #   task = datastore.entity "Task", "sampleTask" do |t|
-      #     t["type"] = "Personal"
-      #     t["done"] = false
-      #     t["priority"] = 4
-      #     t["description"] = "Learn Cloud Datastore"
-      #   end
-      #
-      #   datastore.transaction do |tx|
-      #     if tx.find(task.key).nil?
-      #       tx.save task
-      #     end
-      #   end
-      #
-      # @example If no block is given, a Transaction object is returned:
-      #   require "gcloud"
-      #
-      #   gcloud = Gcloud.new
-      #   datastore = gcloud.datastore
-      #
-      #   task = datastore.entity "Task", "sampleTask" do |t|
-      #     t["type"] = "Personal"
-      #     t["done"] = false
-      #     t["priority"] = 4
-      #     t["description"] = "Learn Cloud Datastore"
-      #   end
-      #
-      #   tx = datastore.transaction
-      #   begin
-      #     if tx.find(task.key).nil?
-      #       tx.save task
-      #     end
-      #     tx.commit
-      #   rescue
-      #     tx.rollback
-      #   end
-      #
-      def transaction
-        tx = Transaction.new service
-        return tx unless block_given?
-
-        begin
-          yield tx
-          tx.commit
-        rescue
-          begin
-            tx.rollback
-          rescue
-            raise TransactionError, "Transaction failed to commit and rollback."
-          end
-          raise TransactionError, "Transaction failed to commit."
-        end
-      end
-
-      ##
-      # Create a new Query instance. This is a convenience method to make the
-      # creation of Query objects easier.
-      #
-      # @param [String] kinds The kind of entities to query. This is optional.
-      #
-      # @return [Gcloud::Datastore::Query]
-      #
-      # @example
-      #   query = datastore.query("Task").
-      #     where("done", "=", false)
-      #   tasks = datastore.run query
-      #
-      # @example The previous example is equivalent to:
-      #   query = Gcloud::Datastore::Query.new.
-      #     kind("Task").
-      #     where("done", "=", false)
-      #   tasks = datastore.run query
-      #
-      def query *kinds
-        query = Query.new
-        query.kind(*kinds) unless kinds.empty?
-        query
-      end
-
-      ##
-      # Create a new GqlQuery instance. This is a convenience method to make the
-      # creation of GqlQuery objects easier.
-      #
-      # @param [String] query The GQL query string.
-      # @param [Hash] bindings Named bindings for the GQL query string, each
-      #   key must match regex `[A-Za-z_$][A-Za-z_$0-9]*`, must not match regex
-      #   `__.*__`, and must not be `""`. The value must be an `Object` that can
-      #   be stored as an Entity property value, or a `Cursor`.
-      #
-      # @return [Gcloud::Datastore::GqlQuery]
-      #
-      # @example
-      #   gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
-      #                             done: false
-      #   tasks = datastore.run gql_query
-      #
-      # @example The previous example is equivalent to:
-      #   gql_query = Gcloud::Datastore::GqlQuery.new
-      #   gql_query.query_string = "SELECT * FROM Task WHERE done = @done"
-      #   gql_query.named_bindings = {done: false}
-      #   tasks = datastore.run gql_query
-      #
-      def gql query, bindings = {}
-        gql = GqlQuery.new
-        gql.query_string = query
-        gql.named_bindings = bindings unless bindings.empty?
-        gql
-      end
-
-      ##
-      # Create a new Key instance. This is a convenience method to make the
-      # creation of Key objects easier.
-      #
-      # @param [Array<Array(String,(String|Integer|nil))>] path An optional list
-      #   of pairs for the key's path. Each pair may include the key's kind
-      #   (String) and an id (Integer) or name (String). This is optional.
-      # @param [String] project The project of the Key. This is optional.
-      # @param [String] namespace namespace kind of the Key. This is optional.
-      #
-      # @return [Gcloud::Datastore::Key]
-      #
-      # @example
-      #   task_key = datastore.key "Task", "sampleTask"
-      #
-      # @example The previous example is equivalent to:
-      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
-      #
-      # @example Create an empty key:
-      #   key = datastore.key
-      #
-      # @example Create an incomplete key:
-      #   key = datastore.key "User"
-      #
-      # @example Create a key with a parent:
-      #   key = datastore.key [["TaskList", "default"], ["Task", "sampleTask"]]
-      #   key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]
-      #
-      # @example Create a key with multi-level ancestry:
-      #   key = datastore.key([
-      #     ["User", "alice"],
-      #     ["TaskList", "default"],
-      #     ["Task", "sampleTask"]
-      #   ])
-      #   key.path #=> [["User", "alice"], ["TaskList", "default"], [ ... ]]
-      #
-      # @example Create an incomplete key with a parent:
-      #   key = datastore.key "TaskList", "default", "Task"
-      #   key.path #=> [["TaskList", "default"], ["Task", nil]]
-      #
-      # @example Create a key with a project and namespace:
-      #   key = datastore.key ["TaskList", "default"], ["Task", "sampleTask"],
-      #                       project: "my-todo-project",
-      #                       namespace: "ns~todo-project"
-      #   key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]
-      #   key.project #=> "my-todo-project",
-      #   key.namespace #=> "ns~todo-project"
-      #
-      def key *path, project: nil, namespace: nil
-        path = path.flatten.each_slice(2).to_a # group in pairs
-        kind, id_or_name = path.pop
-        Key.new(kind, id_or_name).tap do |k|
-          k.project = project
-          k.namespace = namespace
-          unless path.empty?
-            k.parent = key path, project: project, namespace: namespace
-          end
-        end
-      end
-
-      ##
-      # Create a new empty Entity instance. This is a convenience method to make
-      # the creation of Entity objects easier.
-      #
-      # @param [Key, Array<Array(String,(String|Integer|nil))>] key_or_path An
-      #   optional list of pairs for the key's path. Each pair may include the #
-      #   key's kind (String) and an id (Integer) or name (String). This is #
-      #   optional.
-      # @param [String] project The project of the Key. This is optional.
-      # @param [String] namespace namespace kind of the Key. This is optional.
-      # @yield [entity] a block yielding a new entity
-      # @yieldparam [Entity] entity the newly created entity object
-      #
-      # @return [Gcloud::Datastore::Entity]
-      #
-      # @example
-      #   task = datastore.entity
-      #
-      # @example The previous example is equivalent to:
-      #   task = Gcloud::Datastore::Entity.new
-      #
-      # @example The key can also be passed in as an object:
-      #   task_key = datastore.key "Task", "sampleTask"
-      #   task = datastore.entity task_key
-      #
-      # @example Or the key values can be passed in as parameters:
-      #   task = datastore.entity "Task", "sampleTask"
-      #
-      # @example The previous example is equivalent to:
-      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
-      #   task = Gcloud::Datastore::Entity.new
-      #   task.key = task_key
-      #
-      # @example The newly created entity can also be configured using a block:
-      #   task = datastore.entity "Task", "sampleTask" do |t|
-      #     t["type"] = "Personal"
-      #     t["done"] = false
-      #     t["priority"] = 4
-      #     t["description"] = "Learn Cloud Datastore"
-      #   end
-      #
-      # @example The previous example is equivalent to:
-      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
-      #   task = Gcloud::Datastore::Entity.new
-      #   task.key = task_key
-      #   task["type"] = "Personal"
-      #   task["done"] = false
-      #   task["priority"] = 4
-      #   task["description"] = "Learn Cloud Datastore"
-      #
-      def entity *key_or_path, project: nil, namespace: nil
-        entity = Entity.new
-
-        # Set the key
-        if key_or_path.flatten.first.is_a? Gcloud::Datastore::Key
-          entity.key = key_or_path.flatten.first
-        else
-          entity.key = key key_or_path, project: project, namespace: namespace
-        end
-
-        yield entity if block_given?
-
-        entity
-      end
-
-      protected
-
-      ##
-      # @private Raise an error unless an active connection to the service is
-      # available.
-      def ensure_service!
-        fail "Must have active connection to service" unless service
-      end
-
-      def check_consistency! consistency
-        fail(ArgumentError,
-             format("Consistency must be :eventual or :strong, not %s.",
-                    consistency.inspect)
-            ) unless [:eventual, :strong, nil].include? consistency
-      end
-    end
-  end
-end