gcloud 0.1.0 → 0.1.1

data/lib/gcloud/datastore/connection.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -87,8 +88,9 @@ module Gcloud
       # Commit a transaction, optionally creating, deleting or modifying
       # some entities.
       def commit mutation, transaction = nil
-        mode = transaction ? Proto::CommitRequest::Mode::TRANSACTIONAL :
-                             Proto::CommitRequest::Mode::NON_TRANSACTIONAL
+        mode = Proto::CommitRequest::Mode::NON_TRANSACTIONAL
+        mode = Proto::CommitRequest::Mode::TRANSACTIONAL if transaction
+
         commit = Proto::CommitRequest.new.tap do |c|
           c.mutation = mutation
           c.mode = mode

data/lib/gcloud/datastore/credentials.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -25,7 +26,8 @@ module Gcloud
     class Credentials < Gcloud::Credentials #:nodoc:
       SCOPE = ["https://www.googleapis.com/auth/datastore",
                "https://www.googleapis.com/auth/userinfo.email"]
-      ENV_VARS = ["DATASTORE_KEYFILE"]
+      PATH_ENV_VARS = %w(DATASTORE_KEYFILE GOOGLE_CLOUD_KEYFILE)
+      JSON_ENV_VARS = %w(DATASTORE_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON)
 
       ##
       # Sign Oauth2 API calls.

data/lib/gcloud/datastore/dataset.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -23,6 +24,8 @@ 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.
     #
@@ -30,8 +33,9 @@ module Gcloud
     # Google Datastore. Gcloud::Datastore::Entity objects are created,
     # read, updated, and deleted by Gcloud::Datastore::Dataset.
     #
-    #   dataset = Gcloud.datastore "my-todo-project",
-    #                              "/path/to/keyfile.json"
+    #   require "gcloud/datastore"
+    #
+    #   dataset = Gcloud.datastore
     #
     #   query = Gcloud::Datastore::Query.new.kind("Task").
     #     where("completed", "=", true)
@@ -51,17 +55,46 @@ module Gcloud
       end
 
       ##
-      # The project connected to.
+      # The Datastore project connected to.
+      #
+      # === Example
+      #
+      #   require "gcloud/datastore"
+      #
+      #   dataset = Gcloud.datastore "my-todo-project",
+      #                              "/path/to/keyfile.json"
+      #
+      #   dataset.project #=> "my-todo-project"
+      #
       def project
         connection.dataset_id
       end
 
+      ##
+      # Default project.
+      def self.default_project #:nodoc:
+        ENV["DATASTORE_PROJECT"] || ENV["GOOGLE_CLOUD_PROJECT"]
+      end
+
       ##
       # Generate IDs for a Key before creating an entity.
       #
-      #   dataset = Gcloud.datastore
+      # === Parameters
+      #
+      # +incomplete_key+::
+      #   A Key without +id+ or +name+ set. (+Key+)
+      # +count+::
+      #   The number of new key IDs to create. (+Integer+)
+      #
+      # === Returns
+      #
+      # Array of Gcloud::Datastore::Key
+      #
+      # === Example
+      #
       #   empty_key = Gcloud::Datastore::Key.new "Task"
       #   task_keys = dataset.allocate_ids empty_key, 5
+      #
       def allocate_ids incomplete_key, count = 1
         if incomplete_key.complete?
           fail Gcloud::Datastore::Error, "An incomplete key must be provided."
@@ -75,10 +108,22 @@ module Gcloud
       end
 
       ##
-      # Persist entities to the Datastore.
+      # Persist one or more entities to the Datastore.
+      #
+      # === Parameters
+      #
+      # +entities+::
+      #   One or more entity objects to be saved without +id+ or +name+ set.
+      #   (+Entity+)
+      #
+      # === Returns
+      #
+      # Array of Gcloud::Datastore::Entity
+      #
+      # === Example
       #
-      #   dataset = Gcloud.datastore
       #   dataset.save task1, task2
+      #
       def save *entities
         mutation = Proto.new_mutation
         save_entities_to_mutation entities, mutation
@@ -89,14 +134,30 @@ module Gcloud
 
       ##
       # Retrieve an entity by providing key information.
-      # Either a Key object or kind and id/name can be provided.
       #
-      #   dataset = Gcloud.datastore
+      # === Parameters
+      #
+      # +key_or_kind+::
+      #   A Key object or +kind+ string value. (+Key+ or +String+)
+      # +key_or_kind+::
+      #   The Key's +id+ or +name+ value if a +kind+ was provided in the first
+      #   parameter. (+Integer+ or +String+ or +nil+)
+      #
+      # === Returns
+      #
+      # Gcloud::Datastore::Entity or +nil+
+      #
+      # === Example
+      #
+      # Finding an entity with a key:
+      #
       #   key = Gcloud::Datastore::Key.new "Task", 123456
       #   task = dataset.find key
       #
-      #   dataset = Gcloud.datastore
+      # Finding an entity with a +kind+ and +id+/+name+:
+      #
       #   task = dataset.find "Task", 123456
+      #
       def find key_or_kind, id_or_name = nil
         key = key_or_kind
         key = Key.new key_or_kind, id_or_name unless key_or_kind.is_a? Key
@@ -107,13 +168,22 @@ module Gcloud
       ##
       # Retrieve the entities for the provided keys.
       #
+      # === Parameters
+      #
+      # +keys+::
+      #   One or more Key objects to find records for. (+Key+)
+      #
+      # === Returns
+      #
+      # Gcloud::Datastore::Dataset::LookupResults
+      #
+      # === Example
+      #
       #   dataset = Gcloud.datastore
       #   key1 = Gcloud::Datastore::Key.new "Task", 123456
       #   key2 = Gcloud::Datastore::Key.new "Task", 987654
       #   tasks = dataset.find_all key1, key2
       #
-      # The entities returned from the lookup are returned in a
-      # Dataset::LookupResults object.
       def find_all *keys
         response = connection.lookup(*keys.map(&:to_proto))
         entities = to_gcloud_entities response.found
@@ -125,10 +195,21 @@ module Gcloud
 
       ##
       # Remove entities from the Datastore.
-      # Accepts Entity and Key objects.
+      #
+      # === Parameters
+      #
+      # +entities_or_keys+::
+      #   One or more Entity or Key objects to remove. (+Entity+ or +Key+)
+      #
+      # === Returns
+      #
+      # +true+ if successful
+      #
+      # === Example
       #
       #   dataset = Gcloud.datastore
-      #   dataset.delete task1, task2
+      #   dataset.delete entity1, entity2
+      #
       def delete *entities_or_keys
         keys = entities_or_keys.map do |e_or_k|
           e_or_k.respond_to?(:key) ? e_or_k.key.to_proto : e_or_k.to_proto
@@ -143,12 +224,21 @@ module Gcloud
       ##
       # Retrieve entities specified by a Query.
       #
+      # === Parameters
+      #
+      # +query+::
+      #   The Query object with the search criteria. (+Query+)
+      #
+      # === Returns
+      #
+      # Gcloud::Datastore::Dataset::QueryResults
+      #
+      # === Example
+      #
       #   query = Gcloud::Datastore::Query.new.kind("Task").
       #     where("completed", "=", true)
       #   tasks = dataset.run query
       #
-      # The entities returned from the query are returned in a
-      # Dataset::QueryResults object.
       def run query
         response = connection.run_query query.to_proto
         entities = to_gcloud_entities response.batch.entity_result
@@ -159,13 +249,22 @@ module Gcloud
       alias_method :run_query, :run
 
       ##
-      # Runs the given block in a database transaction.
-      # If no block is given the transaction object is returned.
+      # Creates a Datastore Transaction.
+      #
+      # === Example
+      #
+      # Runs the given block in a database transaction:
+      #
+      #   require "gcloud/datastore"
+      #
+      #   dataset = Gcloud.datastore
+      #
+      #   key = Gcloud::Datastore::Key.new "User", "heidi"
       #
       #   user = Gcloud::Datastore::Entity.new
-      #   user.key = Gcloud::Datastore::Key.new "User", "username"
-      #   user["name"] = "Test"
-      #   user["email"] = "test@example.net"
+      #   user.key = key
+      #   user["name"] = "Heidi Henderson"
+      #   user["email"] = "heidi@example.net"
       #
       #   dataset.transaction do |tx|
       #     if tx.find(user.key).nil?
@@ -173,13 +272,18 @@ module Gcloud
       #     end
       #   end
       #
-      # Alternatively, you can manually commit or rollback by
-      # using the returned transaction object.
+      # Alternatively, if no block is given a Transaction object is returned:
+      #
+      #   require "gcloud/datastore"
+      #
+      #   dataset = Gcloud.datastore
+      #
+      #   key = Gcloud::Datastore::Key.new "User", "heidi"
       #
       #   user = Gcloud::Datastore::Entity.new
-      #   user.key = Gcloud::Datastore::Key.new "User", "username"
-      #   user["name"] = "Test"
-      #   user["email"] = "test@example.net"
+      #   user.key = key
+      #   user["name"] = "Heidi Henderson"
+      #   user["email"] = "heidi@example.net"
       #
       #   tx = dataset.transaction
       #   begin
@@ -190,6 +294,7 @@ module Gcloud
       #   rescue
       #     tx.rollback
       #   end
+      #
       def transaction
         tx = Transaction.new connection
         return tx unless block_given?

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

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");

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

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -30,15 +31,16 @@ module Gcloud
       #
       #   entities = dataset.run query
       #   entities.size #=> 3
-      #   entities.cursor #=> "c3VwZXJhd2Vzb21lIQ"
+      #   entities.end_cursor #=> "c3VwZXJhd2Vzb21lIQ"
       #   names = entities.map { |e| e.name }
       #   names.size #=> 3
       #   names.cursor #=> NoMethodError
       #
       class QueryResults < DelegateClass(::Array)
         ##
-        # The cursor of the QueryResults.
-        attr_reader :cursor
+        # The end_cursor of the QueryResults.
+        attr_reader :end_cursor
+        alias_method :cursor, :end_cursor
 
         ##
         # The state of the query after the current batch.
@@ -76,9 +78,9 @@ module Gcloud
 
         ##
         # Create a new QueryResults with an array of values.
-        def initialize arr = [], cursor = nil, more_results = nil
+        def initialize arr = [], end_cursor = nil, more_results = nil
           super arr
-          @cursor = cursor
+          @end_cursor = end_cursor
           @more_results = more_results
         end
       end

data/lib/gcloud/datastore/entity.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -19,7 +20,9 @@ require "gcloud/datastore/proto"
 module Gcloud
   module Datastore
     ##
-    # Entity represents the Datastore record.
+    # = Entity
+    #
+    # Entity represents a Datastore record.
     # Every Entity has a Key, and a list of properties.
     #
     #   entity = Gcloud::Datastore::Entity.new
@@ -40,19 +43,67 @@ module Gcloud
       end
 
       ##
-      # Retrieve a property value.
+      # Retrieve a property value by providing the name.
+      #
+      # === Parameters
+      #
+      # +prop_name+::
+      #   The name of the property. (+String+ or +Symbol+)
+      #
+      # === Returns
+      #
+      # Object if the property exists, +nil+ if the property doesn't exist
+      #
+      # === Example
+      #
+      # Properties can be retrieved with a string name:
+      #
+      #   require "gcloud/datastore"
+      #
+      #   dataset = Gcloud.datastore
+      #   user = datastore.find "User", "heidi"
+      #   user["name"] #=> "Heidi Henderson"
       #
-      #   puts entity["name"]
+      # Or with a symbol name:
+      #
+      #   require "gcloud/datastore"
+      #
+      #   dataset = Gcloud.datastore
+      #   user = datastore.find "User", "heidi"
+      #   user[:name] #=> "Heidi Henderson"
       #
-      # If a property doesn't exist then nil will be returned.
       def [] prop_name
         @properties[prop_name]
       end
 
       ##
-      # Set a property value.
+      # Set a property value by name.
+      #
+      # === Parameters
+      #
+      # +prop_name+::
+      #   The name of the property. (+String+ or +Symbol+)
+      # +prop_value+::
+      #   The value of the property. (+Object+)
+      #
+      # === Example
+      #
+      # Properties can be set with a string name:
+      #
+      #   require "gcloud/datastore"
+      #
+      #   dataset = Gcloud.datastore
+      #   user = datastore.find "User", "heidi"
+      #   user["name"] = "Heidi H. Henderson"
+      #
+      # Or with a symbol name:
+      #
+      #   require "gcloud/datastore"
+      #
+      #   dataset = Gcloud.datastore
+      #   user = datastore.find "User", "heidi"
+      #   user[:name] = "Heidi H. Henderson"
       #
-      #   entity["name"] = "User McUser"
       def []= prop_name, prop_value
         @properties[prop_name] = prop_value
       end
@@ -61,6 +112,12 @@ module Gcloud
       # Retrieve properties in a hash-like structure.
       # Properties can be accessed or set by string or symbol.
       #
+      # === Returns
+      #
+      # Gcloud::Datastore::Properties
+      #
+      # === Example
+      #
       #   entity.properties[:name] = "User McUser"
       #   entity.properties["name"] #=> "User McUser"
       #
@@ -83,29 +140,54 @@ module Gcloud
       #
       #   prop_hash = entity.properties.to_h
       #
-      # See Gcloud::Datastore::Properties for more.
       attr_reader :properties
 
       ##
       # Sets the Key that identifies the entity.
-      # This can only be set before the entity is saved.
+      #
+      # === Example
+      #
+      # The Key can be set before the entity is saved.
+      #
+      #   require "glcoud/datastore"
+      #
+      #   dataset = Gcloud.datastore
+      #   entity = Gcloud::Datastore::Entity.new
+      #   entity.key = Gcloud::Datastore::Key.new "User"
+      #   dataset.save entity
+      #
       # Once the entity is saved, the key is frozen and immutable.
+      # Trying to set a key when immutable will raise a +RuntimeError+.
+      #
+      #   require "gcloud/datastore"
       #
-      # Trying to set a key when immutable will raise a RuntimeError.
+      #   dataset = Gcloud.datastore
+      #   entity = dataset.find "User", "heidi"
+      #   entity.persisted? #=> true
+      #   entity.key = Gcloud::Datastore::Key.new "User" #=> RuntimeError
+      #   entity.key.frozen? #=> true
+      #   entity.key.id = 9876543221 #=> RuntimeError
       #
-      #   task = dataset.find "Task", 123456
-      #   task.persisted? #=> true
-      #   task.key = Gcloud::Datastore::Key.new "Task", 456789 #=> RuntimeError
-      #   task.key.frozen? #=> true
-      #   task.key.id = 456789 #=> RuntimeError
       def key= new_key
         fail "This entity's key is immutable." if persisted?
         @key = new_key
       end
 
       ##
-      # Returns true if the record is persisted to the datastore.
-      # Otherwise returns false.
+      # Indicates if the record is persisted. Default is false.
+      #
+      # === Example
+      #
+      #   require "gcloud/datastore"
+      #
+      #   dataset = Gcloud.datastore
+      #
+      #   new_entity = Gcloud::Datastore::Entity.new
+      #   new_entity.persisted? #=> false
+      #
+      #   found_entity = dataset.find "User", "heidi"
+      #   found_entity.persisted? #=> true
+      #
       def persisted?
         @key && @key.frozen?
       end
@@ -122,7 +204,7 @@ module Gcloud
       # Array property values will return an array of flag settings.
       #
       #   entity["tags"] = ["ruby", "code"]
-      #   entity.exclude_from_indexes? "tags" #=> true [false, false]
+      #   entity.exclude_from_indexes? "tags" #=> [false, false]
       def exclude_from_indexes? name
         value = self[name]
         flag = @_exclude_indexes[name.to_s]