gcloud 0.8.2 → 0.9.0

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

@@ -28,20 +28,20 @@ module Gcloud
       # Many common Array methods will return a new Array instance.
       #
       # @example
-      #   entities = dataset.find_all key1, key2, key3
-      #   entities.size #=> 3
-      #   entities.deferred #=> []
-      #   entities.missing #=> []
+      #   tasks = datastore.find_all task_key1, task_key2, task_key3
+      #   tasks.size #=> 3
+      #   tasks.deferred #=> []
+      #   tasks.missing #=> []
       #
       # @example Caution, many Array methods will return a new Array instance:
-      #   entities = dataset.find_all key1, key2, key3
-      #   entities.size #=> 3
-      #   entities.deferred #=> []
-      #   entities.missing #=> []
-      #   names = entities.map { |e| e["name"] }
-      #   names.size #=> 3
-      #   names.deferred #=> NoMethodError
-      #   names.missing #=> NoMethodError
+      #   tasks = datastore.find_all task_key1, task_key2, task_key3
+      #   tasks.size #=> 3
+      #   tasks.deferred #=> []
+      #   tasks.missing #=> []
+      #   descriptions = tasks.map { |task| task["description"] }
+      #   descriptions.size #=> 3
+      #   descriptions.deferred #=> NoMethodError
+      #   descriptions.missing #=> NoMethodError
       #
       class LookupResults < DelegateClass(::Array)
         ##

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

@@ -28,21 +28,23 @@ module Gcloud
       # Many common Array methods will return a new Array instance.
       #
       # @example
-      #   entities = dataset.run query
-      #   entities.size #=> 3
-      #   entities.cursor #=> "c3VwZXJhd2Vzb21lIQ"
+      #   tasks = datastore.run query
+      #   tasks.size #=> 3
+      #   tasks.cursor #=> Gcloud::Datastore::Cursor(c3VwZXJhd2Vzb21lIQ)
       #
       # @example Caution, many Array methods will return a new Array instance:
-      #   entities = dataset.run query
-      #   entities.size #=> 3
-      #   entities.end_cursor #=> "c3VwZXJhd2Vzb21lIQ"
-      #   names = entities.map { |e| e.name }
-      #   names.size #=> 3
-      #   names.cursor #=> NoMethodError
+      #   tasks = datastore.run query
+      #   tasks.size #=> 3
+      #   tasks.end_cursor #=> Gcloud::Datastore::Cursor(c3VwZXJhd2Vzb21lIQ)
+      #   descriptions = tasks.map { |task| task["description"] }
+      #   descriptions.size #=> 3
+      #   descriptions.cursor #=> NoMethodError
       #
       class QueryResults < DelegateClass(::Array)
         ##
         # The end_cursor of the QueryResults.
+        #
+        # @return [Gcloud::Datastore::Cursor]
         attr_reader :end_cursor
         alias_method :cursor, :end_cursor
 
@@ -51,41 +53,129 @@ module Gcloud
         #
         # Expected values are:
         #
-        # "MORE_RESULTS_AFTER_LIMIT":
-        # "NOT_FINISHED":
-        # "NO_MORE_RESULTS":
+        # * `:NOT_FINISHED`
+        # * `:MORE_RESULTS_AFTER_LIMIT`
+        # * `:MORE_RESULTS_AFTER_CURSOR`
+        # * `:NO_MORE_RESULTS`
         attr_reader :more_results
 
         ##
-        # Convenience method for determining id the more_results value
-        # is "NOT_FINISHED"
+        # @private
+        attr_accessor :service, :namespace, :query
+
+        ##
+        # @private
+        attr_writer :end_cursor, :more_results
+
+        ##
+        # Convenience method for determining if the `more_results` value
+        # is `:NOT_FINISHED`
         def not_finished?
-          more_results == Proto.to_more_results_string(
-            Proto::QueryResultBatch::MoreResultsType::NOT_FINISHED)
+          more_results == :NOT_FINISHED
         end
 
         ##
-        # Convenience method for determining id the more_results value
-        # is "MORE_RESULTS_AFTER_LIMIT"
+        # Convenience method for determining if the `more_results` value
+        # is `:MORE_RESULTS_AFTER_LIMIT`
         def more_after_limit?
-          more_results == Proto.to_more_results_string(
-            Proto::QueryResultBatch::MoreResultsType::MORE_RESULTS_AFTER_LIMIT)
+          more_results == :MORE_RESULTS_AFTER_LIMIT
+        end
+
+        ##
+        # Convenience method for determining if the `more_results` value
+        # is `:MORE_RESULTS_AFTER_CURSOR`
+        def more_after_cursor?
+          more_results == :MORE_RESULTS_AFTER_CURSOR
         end
 
         ##
-        # Convenience method for determining id the more_results value
-        # is "NO_MORE_RESULTS"
+        # Convenience method for determining if the `more_results` value
+        # is `:NO_MORE_RESULTS`
         def no_more?
-          more_results == Proto.to_more_results_string(
-            Proto::QueryResultBatch::MoreResultsType::NO_MORE_RESULTS)
+          more_results == :NO_MORE_RESULTS
         end
 
         ##
         # Create a new QueryResults with an array of values.
-        def initialize arr = [], end_cursor = nil, more_results = nil
+        def initialize arr = []
           super arr
-          @end_cursor = end_cursor
-          @more_results = more_results
+        end
+
+        ##
+        # Whether there are more results available.
+        def next?
+          !no_more?
+        end
+
+        ##
+        # Retrieve the next page of results.
+        def next
+          return nil unless next?
+          return nil if end_cursor.nil?
+          ensure_service!
+          query.start_cursor = cursor.to_grpc # should always be a Cursor...
+          query_res = service.run_query query, namespace
+          self.class.from_grpc query_res, service, namespace, query
+        rescue GRPC::BadStatus => e
+          raise Gcloud::Error.from_error(e)
+        end
+
+        ##
+        # Retrieves all log entries by repeatedly loading {#next} until
+        # {#next?} returns `false`. Returns the list instance for method
+        # chaining.
+        #
+        # This method may make several API calls until all log entries are
+        # retrieved. Be sure to use as narrow a search criteria as possible.
+        # Please use with caution.
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   hour_ago = (Time.now - 60*60).utc.strftime('%FT%TZ')
+        #   recent_errors = "timestamp >= \"#{hour_ago}\" severity >= ERROR"
+        #   entries = logging.entries(filter: recent_errors).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
+          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|
+            qr.end_cursor = Cursor.from_grpc query_res.batch.end_cursor
+            qr.more_results = query_res.batch.more_results
+            qr.service = service
+            qr.namespace = namespace
+            qr.query = query_res.query || query
+          end
+        end
+
+        protected
+
+        ##
+        # @private Raise an error unless an active connection to the service is
+        # available.
+        def ensure_service!
+          msg = "Must have active connection to datastore service to get next"
+          fail msg if @service.nil? || @query.nil?
         end
       end
     end

data/lib/gcloud/datastore/entity.rb

@@ -15,7 +15,6 @@
 
 require "gcloud/datastore/key"
 require "gcloud/datastore/properties"
-require "gcloud/datastore/proto"
 
 module Gcloud
   module Datastore
@@ -25,10 +24,35 @@ module Gcloud
     # Entity represents a Datastore record.
     # Every Entity has a {Key}, and a list of properties.
     #
-    # @example
-    #   entity = Gcloud::Datastore::Entity.new
-    #   entity.key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
-    #   entity["name"] = "Heidi Henderson"
+    # Entities in Datastore form a hierarchically structured space similar to
+    # the directory structure of a file system. When you create an entity, you
+    # can optionally designate another entity as its parent; the new entity is a
+    # child of the parent entity.
+    #
+    # @see https://cloud.google.com/datastore/docs/concepts/entities Entities,
+    #   Properties, and Keys
+    #
+    # @example Create a new entity using a block:
+    #   task = datastore.entity "Task", "sampleTask" do |t|
+    #     t["type"] = "Personal"
+    #     t["created"] = Time.now
+    #     t["done"] = false
+    #     t["priority"] = 4
+    #     t["percent_complete"] = 10.0
+    #     t["description"] = "Learn Cloud Datastore"
+    #   end
+    #
+    # @example Create a new entity belonging to an existing parent entity:
+    #   task_key = datastore.key "Task", "sampleTask"
+    #   task_key.parent = datastore.key "TaskList", "default"
+    #
+    #   task = Gcloud::Datastore::Entity.new
+    #   task.key = task_key
+    #
+    #   task["type"] = "Personal"
+    #   task["done"] = false
+    #   task["priority"] = 4
+    #   task["description"] = "Learn Cloud Datastore"
     #
     class Entity
       ##
@@ -48,6 +72,8 @@ module Gcloud
       #
       # Property values are converted from the Datastore value type
       # automatically. Blob properties are returned as StringIO objects.
+      # Location properties are returned as a Hash with `:longitude` and
+      # `:latitude` keys.
       #
       # @param [String, Symbol] prop_name The name of the property.
       #
@@ -57,28 +83,45 @@ module Gcloud
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   user = dataset.find "User", "heidi@example.com"
-      #   user["name"] #=> "Heidi Henderson"
+      #   datastore = gcloud.datastore
+      #   task = datastore.find "Task", "sampleTask"
+      #   task["description"] #=> "Learn Cloud Datastore"
       #
       # @example Or with a symbol name:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   user = dataset.find "User", "heidi@example.com"
-      #   user[:name] #=> "Heidi Henderson"
+      #   datastore = gcloud.datastore
+      #   task = datastore.find "Task", "sampleTask"
+      #   task[:description] #=> "Learn Cloud Datastore"
+      #
+      # @example Getting a blob value returns a StringIO object:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   datastore = gcloud.datastore
+      #   user = datastore.find "User", "alice"
+      #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
+      #
+      # @example Getting a geo point value returns a Hash:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   datastore = gcloud.datastore
+      #   user = datastore.find "User", "alice"
+      #   user["location"] #=> { longitude: -122.0862462,
+      #                    #     latitude: 37.4220041 }
       #
       # @example Getting a blob value returns a StringIO object:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   user = dataset.find "User", "heidi@example.com"
+      #   datastore = gcloud.datastore
+      #   user = datastore.find "User", "alice"
       #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
       #
       def [] prop_name
-        @properties[prop_name]
+        properties[prop_name]
       end
 
       ##
@@ -88,7 +131,8 @@ module Gcloud
       # automatically. Use an IO-compatible object (File, StringIO, Tempfile) to
       # indicate the property value should be stored as a Datastore `blob`.
       # IO-compatible objects are converted to StringIO objects when they are
-      # set.
+      # set. Use a Hash with `:longitude` and `:latitude` keys to indicate the
+      # property value should be stored as a Geo Point/LatLng.
       #
       # @param [String, Symbol] prop_name The name of the property.
       # @param [Object] prop_value The value of the property.
@@ -97,29 +141,48 @@ module Gcloud
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   user = dataset.find "User", "heidi@example.com"
-      #   user["name"] = "Heidi H. Henderson"
+      #   datastore = gcloud.datastore
+      #   task = datastore.find "Task", "sampleTask"
+      #   task["description"] = "Learn Cloud Datastore"
+      #   task["tags"] = ["fun", "programming"]
       #
       # @example Or with a symbol name:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   user = dataset.find "User", "heidi@example.com"
-      #   user[:name] = "Heidi H. Henderson"
+      #   datastore = gcloud.datastore
+      #   task = datastore.find "Task", "sampleTask"
+      #   task[:description] = "Learn Cloud Datastore"
+      #   task[:tags] = ["fun", "programming"]
       #
       # @example Setting a blob value using an IO:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   user = dataset.find "User", "heidi@example.com"
-      #   user["avatar"] = File.open "/avatars/heidi.png"
+      #   datastore = gcloud.datastore
+      #   user = datastore.find "User", "alice"
+      #   user["avatar"] = File.open "/avatars/alice.png"
+      #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
+      #
+      # @example Setting a geo point value using a Hash:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   datastore = gcloud.datastore
+      #   user = datastore.find "User", "alice"
+      #   user["location"] = { longitude: -122.0862462, latitude: 37.4220041 }
+      #
+      # @example Setting a blob value using an IO:
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   datastore = gcloud.datastore
+      #   user = datastore.find "User", "alice"
+      #   user["avatar"] = File.open "/avatars/alice.png"
       #   user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")
       #
       def []= prop_name, prop_value
-        @properties[prop_name] = prop_value
+        properties[prop_name] = prop_value
       end
 
       ##
@@ -129,52 +192,52 @@ module Gcloud
       # @return [Gcloud::Datastore::Properties]
       #
       # @example
-      #   entity.properties[:name] = "Heidi H. Henderson"
-      #   entity.properties["name"] #=> "Heidi H. Henderson"
+      #   task.properties[:description] = "Learn Cloud Datastore"
+      #   task.properties["description"] #=> "Learn Cloud Datastore"
       #
-      #   entity.properties.each do |name, value|
+      #   task.properties.each do |name, value|
       #     puts "property #{name} has a value of #{value}"
       #   end
       #
       # @example A property's existence can be determined by calling `exist?`:
-      #   entity.properties.exist? :name #=> true
-      #   entity.properties.exist? "name" #=> true
-      #   entity.properties.exist? :expiration #=> false
+      #   task.properties.exist? :description #=> true
+      #   task.properties.exist? "description" #=> true
+      #   task.properties.exist? :expiration #=> false
       #
       # @example A property can be removed from the entity:
-      #   entity.properties.delete :name
-      #   entity.save
+      #   task.properties.delete :description
+      #   task.save
       #
       # @example The properties can be converted to a hash:
-      #   prop_hash = entity.properties.to_h
+      #   prop_hash = task.properties.to_h
       #
       attr_reader :properties
 
       ##
-      # Sets the Key that identifies the entity.
+      # Sets the {Gcloud::Datastore::Key} that identifies the entity.
       #
       # Once the entity is saved, the key is frozen and immutable. Trying to set
       # a key when immutable will raise a `RuntimeError`.
       #
-      # @example The Key can be set before the entity is saved:
+      # @example The key can be set before the entity is saved:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   entity = Gcloud::Datastore::Entity.new
-      #   entity.key = Gcloud::Datastore::Key.new "User"
-      #   dataset.save entity
+      #   datastore = gcloud.datastore
+      #   task = Gcloud::Datastore::Entity.new
+      #   task.key = datastore.key "Task"
+      #   datastore.save task
       #
       # @example Once the entity is saved, the key is frozen and immutable:
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
-      #   entity = dataset.find "User", "heidi@example.com"
-      #   entity.persisted? #=> true
-      #   entity.key = Gcloud::Datastore::Key.new "User" #=> RuntimeError
-      #   entity.key.frozen? #=> true
-      #   entity.key.id = 9876543221 #=> RuntimeError
+      #   datastore = gcloud.datastore
+      #   task = datastore.find "Task", "sampleTask"
+      #   task.persisted? #=> true
+      #   task.key = datastore.key "Task" #=> RuntimeError
+      #   task.key.frozen? #=> true
+      #   task.key.id = 9876543221 #=> RuntimeError
       #
       def key= new_key
         fail "This entity's key is immutable." if persisted?
@@ -188,13 +251,13 @@ module Gcloud
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
+      #   datastore = gcloud.datastore
       #
-      #   new_entity = Gcloud::Datastore::Entity.new
-      #   new_entity.persisted? #=> false
+      #   task = Gcloud::Datastore::Entity.new
+      #   task.persisted? #=> false
       #
-      #   found_entity = dataset.find "User", "heidi@example.com"
-      #   found_entity.persisted? #=> true
+      #   task = datastore.find "Task", "sampleTask"
+      #   task.persisted? #=> true
       #
       def persisted?
         @key && @key.frozen?
@@ -217,14 +280,14 @@ module Gcloud
       #   Unindexed properties
       #
       # @example Single property values will return a single flag setting:
-      #   entity["age"] = 21
-      #   entity.exclude_from_indexes? "age" #=> false
+      #   task["priority"] = 4
+      #   task.exclude_from_indexes? "priority" #=> false
       #
       # @example A multi-valued property will return an array of flag settings:
-      #   entity["tags"] = ["ruby", "code"]
-      #   entity.exclude_from_indexes! "tags", [true, false]
+      #   task["tags"] = ["fun", "programming"]
+      #   task.exclude_from_indexes! "tags", [true, false]
       #
-      #   entity.exclude_from_indexes? "tags" #=> [true, false]
+      #   task.exclude_from_indexes? "tags" #=> [true, false]
       #
       def exclude_from_indexes? name
         value = self[name]
@@ -260,21 +323,21 @@ module Gcloud
       #   Unindexed properties
       #
       # @example
-      #   entity["age"] = 21
-      #   entity.exclude_from_indexes! "age", true
+      #   entity["priority"] = 4
+      #   entity.exclude_from_indexes! "priority", true
       #
       # @example Multi-valued properties can be given multiple exclude flags:
-      #   entity["tags"] = ["ruby", "code"]
+      #   entity["tags"] = ["fun", "programming"]
       #   entity.exclude_from_indexes! "tags", [true, false]
       #
       # @example Or, a single flag can be applied to all values in a property:
-      #   entity["tags"] = ["ruby", "code"]
+      #   entity["tags"] = ["fun", "programming"]
       #   entity.exclude_from_indexes! "tags", true
       #
       # @example Flags can also be set with a block:
-      #   entity["age"] = 21
-      #   entity.exclude_from_indexes! "age" do |age|
-      #     age > 18
+      #   entity["priority"] = 4
+      #   entity.exclude_from_indexes! "priority" do |priority|
+      #     priority > 4
       #   end
       #
       def exclude_from_indexes! name, flag = nil, &block
@@ -288,30 +351,34 @@ module Gcloud
       end
 
       ##
-      # @private Convert the Entity to a protocol buffer object.
-      def to_proto
-        entity = Proto::Entity.new.tap do |e|
-          e.key = @key.to_proto
-          e.property = Proto.to_proto_properties @properties.to_h
-        end
-        update_properties_indexed! entity
-        entity
+      # @private Convert the Entity to a Google::Datastore::V1beta3::Entity
+      # object.
+      def to_grpc
+        grpc = Google::Datastore::V1beta3::Entity.new(
+          key: @key.to_grpc,
+          properties: @properties.to_grpc
+        )
+        update_properties_indexed! grpc.properties
+        grpc
       end
 
       ##
-      # @private Create a new Entity from a protocol buffer object.
-      def self.from_proto proto
+      # @private Create a new Entity from a Google::Datastore::V1beta3::Key
+      # object.
+      def self.from_grpc grpc
         entity = Entity.new
-        entity.key = Key.from_proto proto.key
-        Array(proto.property).each do |p|
-          entity[p.name] = Proto.from_proto_value p.value
-        end
-        entity.send :update_exclude_indexes!, proto
+        entity.key = Key.from_grpc grpc.key
+        entity.send :properties=, Properties.from_grpc(grpc.properties)
+        entity.send :update_exclude_indexes!, grpc.properties
         entity
       end
 
       protected
 
+      ##
+      # @private Allow friendly objects to set Properties object.
+      attr_writer :properties
+
       # rubocop:disable all
       # Disabled rubocop because this is intentionally complex.
 
@@ -342,31 +409,30 @@ module Gcloud
 
       ##
       # @private Update the exclude data after a new object is created.
-      def update_exclude_indexes! entity
+      def update_exclude_indexes! grpc_map
         @_exclude_indexes = {}
-        Array(entity.property).each do |property|
-          @_exclude_indexes[property.name] = !property.value.indexed
-          unless property.value.list_value.nil?
-            exclude = Array(property.value.list_value).map{|v| !v.indexed}
-            @_exclude_indexes[property.name] = exclude
+        grpc_map.each do |name, value|
+          next if value.nil?
+          @_exclude_indexes[name] = value.exclude_from_indexes
+          unless value.array_value.nil?
+            exclude = value.array_value.values.map &:exclude_from_indexes
+            @_exclude_indexes[name] = exclude
           end
         end
       end
 
       ##
       # @private Update the indexed values before the object is saved.
-      def update_properties_indexed! entity
-        Array(entity.property).each do |property|
-          excluded = exclude_from_indexes? property.name
+      def update_properties_indexed! grpc_map
+        grpc_map.each do |name, value|
+          next if value.nil?
+          excluded = exclude_from_indexes? name
           if excluded.is_a? Array
-            # Lists must not set indexed, or this error will happen:
-            # "A Value containing a list_value cannot specify indexed."
-            property.value.indexed = nil
-            property.value.list_value.each_with_index do |value, index|
-              value.indexed = !excluded[index]
+            value.array_value.values.each_with_index do |v, i|
+              v.exclude_from_indexes = excluded[i]
             end
           else
-            property.value.indexed = !excluded
+            value.exclude_from_indexes = excluded
           end
         end
       end