gcloud 0.10.0 → 0.11.0

data/lib/gcloud/datastore/dataset/query_results.rb

@@ -28,12 +28,26 @@ module Gcloud
       # Many common Array methods will return a new Array instance.
       #
       # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   datastore = gcloud.datastore
+      #
+      #   query = datastore.query("Task")
       #   tasks = datastore.run query
+      #
       #   tasks.size #=> 3
       #   tasks.cursor #=> Gcloud::Datastore::Cursor(c3VwZXJhd2Vzb21lIQ)
       #
       # @example Caution, many Array methods will return a new Array instance:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   datastore = gcloud.datastore
+      #
+      #   query = datastore.query("Task")
       #   tasks = datastore.run query
+      #
       #   tasks.size #=> 3
       #   tasks.end_cursor #=> Gcloud::Datastore::Cursor(c3VwZXJhd2Vzb21lIQ)
       #   descriptions = tasks.map { |task| task["description"] }
@@ -61,7 +75,7 @@ module Gcloud
 
         ##
         # @private
-        attr_accessor :service, :namespace, :query
+        attr_accessor :service, :namespace, :cursors, :query
 
         ##
         # @private
@@ -96,19 +110,49 @@ module Gcloud
         end
 
         ##
-        # Create a new QueryResults with an array of values.
+        # @private Create a new QueryResults with an array of values.
         def initialize arr = []
           super arr
         end
 
         ##
         # Whether there are more results available.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   datastore = gcloud.datastore
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #
+        #   if tasks.next?
+        #     next_tasks = tasks.next
+        #   end
+        #
         def next?
           !no_more?
         end
 
         ##
         # Retrieve the next page of results.
+        #
+        # @return [QueryResults]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   datastore = gcloud.datastore
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #
+        #   if tasks.next?
+        #     next_tasks = tasks.next
+        #   end
+        #
         def next
           return nil unless next?
           return nil if end_cursor.nil?
@@ -120,45 +164,207 @@ module Gcloud
           raise Gcloud::Error.from_error(e)
         end
 
+        ##
+        # Retrieve the {Cursor} for the provided result.
+        #
+        # @param [Entity] result The entity object to get a cursor for.
+        #
+        # @return [Cursor]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   datastore = gcloud.datastore
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #
+        #   first_task = tasks.first
+        #   first_cursor = tasks.cursor_for first_task
+        #
+        def cursor_for result
+          cursor_index = index result
+          return nil if cursor_index.nil?
+          cursors[cursor_index]
+        end
+
+        ##
+        # Calls the given block once for each result and cursor combination,
+        # which are passed as parameters.
+        #
+        # An Enumerator is returned if no block is given.
+        #
+        # @yield [result, cursor] The block for accessing each query result and
+        #   cursor.
+        # @yieldparam [Entity] result The query result object.
+        # @yieldparam [Cursor] cursor The cursor object.
+        #
+        # @return [Enumerator]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   datastore = gcloud.datastore
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #   tasks.each_with_cursor do |task, cursor|
+        #     puts "Task #{task.key.id} (#cursor)"
+        #   end
+        #
+        def each_with_cursor
+          return enum_for(:each_with_cursor) unless block_given?
+          zip(cursors).each { |r, c| yield [r, c] }
+        end
+
         ##
         # Retrieves all query results by repeatedly loading {#next} until
-        # {#next?} returns `false`. Returns the list instance for method
-        # chaining.
+        # {#next?} returns `false`. Calls the given block once for each query
+        # result, which is passed as the parameter.
+        #
+        # An Enumerator is returned if no block is given.
         #
         # This method may make several API calls until all query results are
         # retrieved. Be sure to use as narrow a search criteria as possible.
         # Please use with caution.
         #
-        # @example
+        # @param [Integer] request_limit The upper limit of API requests to make
+        #   to load all query results. Default is no limit.
+        # @yield [result] The block for accessing each query result.
+        # @yieldparam [Entity] result The query result object.
+        #
+        # @return [Enumerator]
+        #
+        # @example Iterating each query result by passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   datastore = gcloud.datastore
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #   tasks.all do |task|
+        #     puts "Task #{task.key.id} (#cursor)"
+        #   end
+        #
+        # @example Using the enumerator by not passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   datastore = gcloud.datastore
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #   tasks.all.map(&:key).each do |key|
+        #     puts "Key #{key.id}"
+        #   end
+        #
+        # @example Limit the number of API calls made:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   datastore = gcloud.datastore
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #   tasks.all(request_limit: 10) do |task|
+        #     puts "Task #{task.key.id} (#cursor)"
+        #   end
+        #
+        def all request_limit: nil
+          request_limit = request_limit.to_i if request_limit
+          unless block_given?
+            return enum_for(:all, request_limit: request_limit)
+          end
+          results = self
+          loop do
+            results.each { |r| yield r }
+            if request_limit
+              request_limit -= 1
+              break if request_limit < 0
+            end
+            break unless results.next?
+            results = results.next
+          end
+        end
+
+        ##
+        # Retrieves all query results and cursors by repeatedly loading {#next}
+        # until {#next?} returns `false`. Calls the given block once for each
+        # result and cursor combination, which are passed as parameters.
+        #
+        # An Enumerator is returned if no block is given.
+        #
+        # This method may make several API calls until all query results are
+        # retrieved. Be sure to use as narrow a search criteria as possible.
+        # Please use with caution.
+        #
+        # @param [Integer] request_limit The upper limit of API requests to make
+        #   to load all tables. Default is no limit.
+        # @yield [result, cursor] The block for accessing each query result and
+        #   cursor.
+        # @yieldparam [Entity] result The query result object.
+        # @yieldparam [Cursor] cursor The cursor object.
+        #
+        # @return [Enumerator]
+        #
+        # @example Iterating all results and cursors by passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   datastore = gcloud.datastore
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #   tasks.all_with_cursor do |task, cursor|
+        #     puts "Task #{task.key.id} (#cursor)"
+        #   end
+        #
+        # @example Using the enumerator by not passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   datastore = gcloud.datastore
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #   tasks.all_with_cursor.count #=> number of result/cursor pairs
+        #
+        # @example Limit the number of API calls made:
         #   require "gcloud"
         #
         #   gcloud = Gcloud.new
         #   datastore = gcloud.datastore
-        #   query = datastore.query("Tasks")
-        #   all_tasks = datastore.run(query).all
-        #
-        def all
-          while next?
-            next_records = self.next
-            push(*next_records)
-            self.end_cursor = next_records.end_cursor
-            self.more_results = next_records.more_results
-            self.service = next_records.service
-            self.namespace = next_records.namespace
-            self.query = next_records.query
+        #   query = datastore.query "Task"
+        #   tasks = datastore.run query
+        #   tasks.all_with_cursor(request_limit: 10) do |task, cursor|
+        #     puts "Task #{task.key.id} (#cursor)"
+        #   end
+        #
+        def all_with_cursor request_limit: nil
+          request_limit = request_limit.to_i if request_limit
+          unless block_given?
+            return enum_for(:all_with_cursor, request_limit: request_limit)
+          end
+          results = self
+
+          loop do
+            results.zip(results.cursors).each { |r, c| yield r, c }
+            if request_limit
+              request_limit -= 1
+              break if request_limit < 0
+            end
+            break unless results.next?
+            results = results.next
           end
-          self
         end
 
         ##
         # @private New Dataset::QueryResults from a
         # Google::Dataset::V1beta3::RunQueryResponse object.
         def self.from_grpc query_res, service, namespace, query
-          entities = Array(query_res.batch.entity_results).map do |result|
-            # TODO: Make this return an EntityResult with cursor...
-            Entity.from_grpc result.entity
-          end
-          new(entities).tap do |qr|
+          r, c = Array(query_res.batch.entity_results).map do |result|
+            [Entity.from_grpc(result.entity), Cursor.from_grpc(result.cursor)]
+          end.transpose
+          r ||= []
+          c ||= []
+          new(r).tap do |qr|
+            qr.cursors = c
             qr.end_cursor = Cursor.from_grpc query_res.batch.end_cursor
             qr.more_results = query_res.batch.more_results
             qr.service = service

data/lib/gcloud/datastore/transaction.rb

@@ -198,12 +198,9 @@ module Gcloud
       #
       def find_all *keys
         ensure_service!
-        lookup_res = service.lookup(*keys.map(&:to_grpc),
+        lookup_res = service.lookup(*Array(keys).flatten.map(&:to_grpc),
                                     transaction: @id)
-        entities = to_gcloud_entities lookup_res.found
-        deferred = to_gcloud_keys lookup_res.deferred
-        missing  = to_gcloud_entities lookup_res.missing
-        LookupResults.new entities, deferred, missing
+        LookupResults.from_grpc lookup_res, service, nil, @id
       rescue GRPC::BadStatus => e
         raise Gcloud::Error.from_error(e)
       end

data/lib/gcloud/dns.rb

@@ -301,6 +301,26 @@ module Gcloud
   # zone.export "path/to/db.example.com"
   # ```
   #
+  # ## Configuring Backoff
+  #
+  # The {Gcloud::Backoff} class allows users to globally configure how Cloud API
+  # requests are automatically retried in the case of some errors, such as a
+  # `500` or `503` status code, or a specific internal error code such as
+  # `rateLimitExceeded`.
+  #
+  # If an API call fails, the response will be inspected to see if the call
+  # should be retried. If the response matches the criteria, then the request
+  # will be retried after a delay. If another error occurs, the delay will be
+  # increased incrementally before a subsequent attempt. The first retry will be
+  # delayed one second, the second retry two seconds, and so on.
+  #
+  # ```ruby
+  # require "gcloud"
+  # require "gcloud/backoff"
+  #
+  # Gcloud::Backoff.retries = 5 # Raise the maximum number of retries from 3
+  # ```
+  #
   module Dns
   end
 end

data/lib/gcloud/dns/change/list.rb

@@ -22,38 +22,141 @@ module Gcloud
       # Change::List is a special case Array with additional values.
       class List < DelegateClass(::Array)
         ##
-        # If not empty, indicates that there are more records that match
+        # If not empty, indicates that there are more changes that match
         # the request and this value should be passed to continue.
         attr_accessor :token
 
         ##
-        # Create a new Change::List with an array of Change instances.
+        # @private Create a new Change::List with an array of Change instances.
         def initialize arr = []
           super arr
         end
 
         ##
-        # Whether there a next page of zones.
+        # Whether there a next page of changes.
+        #
+        # @return [Boolean]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   dns = gcloud.dns
+        #   zone = dns.zone "example-com"
+        #
+        #   changes = zone.changes
+        #   if changes.next?
+        #     next_changes = changes.next
+        #   end
+        #
         def next?
           !token.nil?
         end
 
         ##
-        # Retrieve the next page of zones.
+        # Retrieve the next page of changes.
+        #
+        # @return [Change::List]
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   dns = gcloud.dns
+        #   zone = dns.zone "example-com"
+        #
+        #   changes = zone.changes
+        #   if changes.next?
+        #     next_changes = changes.next
+        #   end
+        #
         def next
           return nil unless next?
           ensure_zone!
-          @zone.changes token: token
+          @zone.changes token: token, max: @max, order: @order
+        end
+
+        ##
+        # Retrieves all changes by repeatedly loading {#next} until {#next?}
+        # returns `false`. Calls the given block once for each change, which is
+        # passed as the parameter.
+        #
+        # An Enumerator is returned if no block is given.
+        #
+        # This method may make several API calls until all changes are
+        # retrieved. Be sure to use as narrow a search criteria as possible.
+        # Please use with caution.
+        #
+        # @param [Integer] request_limit The upper limit of API requests to make
+        #   to load all changes. Default is no limit.
+        # @yield [change] The block for accessing each change.
+        # @yieldparam [Change] change The change object.
+        #
+        # @return [Enumerator]
+        #
+        # @example Iterating each change by passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   dns = gcloud.dns
+        #   zone = dns.zone "example-com"
+        #   changes = zone.changes
+        #
+        #   changes.all do |change|
+        #     puts change.name
+        #   end
+        #
+        # @example Using the enumerator by not passing a block:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   dns = gcloud.dns
+        #   zone = dns.zone "example-com"
+        #   changes = zone.changes
+        #
+        #   all_names = changes.all.map do |change|
+        #     change.name
+        #   end
+        #
+        # @example Limit the number of API calls made:
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   dns = gcloud.dns
+        #   zone = dns.zone "example-com"
+        #   changes = zone.changes
+        #
+        #   changes.all(request_limit: 10) do |change|
+        #     puts change.name
+        #   end
+        #
+        def all request_limit: nil
+          request_limit = request_limit.to_i if request_limit
+          unless block_given?
+            return enum_for(:all, request_limit: request_limit)
+          end
+          results = self
+          loop do
+            results.each { |r| yield r }
+            if request_limit
+              request_limit -= 1
+              break if request_limit < 0
+            end
+            break unless results.next?
+            results = results.next
+          end
         end
 
         ##
         # @private New Changes::List from a response object.
-        def self.from_response resp, zone
+        def self.from_response resp, zone, max = nil, order = nil
           changes = new(Array(resp.data["changes"]).map do |gapi_object|
             Change.from_gapi gapi_object, zone
           end)
           changes.instance_variable_set "@token", resp.data["nextPageToken"]
           changes.instance_variable_set "@zone",  zone
+          changes.instance_variable_set "@max",   max
+          changes.instance_variable_set "@order", order
           changes
         end