gcloud 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 2c07dde26f3ab2dbf9dbce909a969db730629657
-  data.tar.gz: 0e50cf1e089b60017063d4f87ddc409c56765829
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YWUyNTJhOGZkZDNmY2E2NTFlOWJkNjRjZTEyNzhmYzkyMjVlY2RlMA==
+  data.tar.gz: !binary |-
+    MGNhMjVhNjE5Njc5ZmM5NTU4MDlkYjJiYjA0OGQ1MmJjM2M0NDAyNA==
 SHA512:
-  metadata.gz: d6eae53e0075282ade550b8d7729aa1ab0b4c293ff507490ec1881fd1948fbdbdd188211ff3521b68761bc51dc6c09395a227c7fee1b5ea3428299a790b44fe9
-  data.tar.gz: 707dbeca9fe9c0411bade51f832fb26dfdb865d421f0fc57543cae66f2678b1f3a6ef658dd5d91ccf1d81c32b51bc00fcc0556d3cae768d73b36b27de6501d3f
+  metadata.gz: !binary |-
+    YzUzYTQ3NWRkMDI1N2U1YTVkMWJkZDZjM2VjYTAxZjYxZGMxMWRlMmRjY2Vi
+    MmU2MGFlNDI4YTE1NmIzZjg2ODYzOGU3NWUzMDE3YmNmMzU4Y2JiMjMwOGUz
+    NGU3ZTdmMzM4ZGU2YjAyZmFiOTg4OGZiOGNmMWEwM2Y3YzA4MjA=
+  data.tar.gz: !binary |-
+    ZGEwM2NmNTQ0ZjExNjQ4NzhlZGFmODg5NjkwZjhkNjVmMjBmMzJlM2QzZTg5
+    YTFmOTc5NGVhMzdjZWNjMTY1OTY3OWE0OGE0MGQwM2UzNmY5N2IyZDI1MmQy
+    NDhjNmZkYzQ3YTUwYWIxZTA1MTk0NGIwZDNiMjMyMDAzZmNiMTY=

data/AUTHENTICATION.md

@@ -0,0 +1,71 @@
+# Authentication
+
+## Creating a Service Account
+
+Gcloud aims to make authentication as simple as possible. Google Cloud requires a **Project ID** and **Service Account Credentials** to connect to the APIs. To create a service account:
+
+1. Visit the [Google Developers Console](https://console.developers.google.com/project).
+2. Create a new project or click on an existing project.
+3. Navigate to **APIs & auth** > **APIs section** and turn on the following APIs (you may need to enable billing in order to use these services):
+  * Google Cloud Datastore API
+  * Google Cloud Storage
+  * Google Cloud Storage JSON API
+4. Navigate to **APIs & auth** > **Credentials** and then:
+  * If you want to use a new service account, click on **Create new Client ID** and select **Service account**. After the account is created, you will be prompted to download the JSON key file that the library uses to authorize your requests.
+  * If you want to generate a new key for an existing service account, click on **Generate new JSON key** and download the JSON key file.
+
+You will use the **Project ID** and **JSON file** to connect to services with gcloud.
+
+## Project and Credential Lookup
+
+Gcloud aims to make authentication as simple as possible, and provides several mechanisms to configure your system without providing **Project ID** and **Service Account Credentials** directly in code.
+
+**Project ID** is discovered in the following order:
+
+1. Specify project ID in code
+2. Discover project ID in environment variables
+3. Discover GCE project ID
+
+**Credentials** are discovered in the following order:
+
+1. Specify credentials in code
+2. Discover credentials path in environment variables
+3. Discover credentials JSON in environment variables
+4. Discover credentials file in the Cloud SDK's path
+5. Discover GCE credentials
+
+### Compute Engine
+
+While running on Google Compute Engine no extra work is needed. The **Project ID** and **Credentials** and are discovered automatically. Code should be written as if already authenticated.
+
+### Environment Variables
+
+The **Project ID** and **Credentials JSON** can be placed in environment variables instead of declaring them directly in code. Each service has its own environment variable, allowing for different service accounts to be used for different services. The path to the **Credentials JSON** file can be stored in the environment variable, or the **Credentials JSON** itself can be stored for environments such as Docker containers where writing files is difficult or not encouraged.
+
+Here are the environment variables that Datastore checks for project ID:
+
+1. DATASTORE_PROJECT
+2. GOOGLE_CLOUD_PROJECT
+
+Here are the environment variables that Datastore checks for credentials:
+
+1. DATASTORE_KEYFILE - Path to JSON file
+2. GOOGLE_CLOUD_KEYFILE - Path to JSON file
+3. DATASTORE_KEYFILE_JSON - JSON contents
+4. GOOGLE_CLOUD_KEYFILE_JSON - JSON contents
+
+### Cloud SDK
+
+This option allows for an easy way to authenticate during development. If credentials are not provided in code or in environment variables, then Cloud SDK credentials are discovered.
+
+To configure your system for this, simply:
+
+1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
+2. Authenticate using OAuth2 `$ gcloud auth login`
+3. Write code as if already authenticated.
+
+**NOTE:** This is _not_ recommended for running in production. The Cloud SDK should only be used during development.
+
+## Troubleshooting
+
+If you're having trouble authenticating open a [Github Issue](https://github.com/GoogleCloudPlatform/gcloud-ruby/issues/new?title=Authentication+question) to get help.  Also consider searching or asking [questions](http://stackoverflow.com/questions/tagged/gcloud-ruby) on [StackOverflow](http://stackoverflow.com).

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History
 
+### 0.1.1 / 2015-06-16
+
+* Storage downloads files in binary mode (premist).
+* Updated documentation.
+
 ### 0.1.0 / 2015-03-31
 
 Initial release supporting Datastore and Storage services.

data/README.md

@@ -4,6 +4,7 @@ Idiomatic Ruby client for [Google Cloud Platform](https://cloud.google.com/) ser
 
 [![Travis Build Status](https://travis-ci.org/GoogleCloudPlatform/gcloud-ruby.svg)](https://travis-ci.org/GoogleCloudPlatform/gcloud-ruby/)
 [![Coverage Status](https://img.shields.io/coveralls/GoogleCloudPlatform/gcloud-ruby.svg)](https://coveralls.io/r/GoogleCloudPlatform/gcloud-ruby?branch=master)
+[![Gem Version](https://badge.fury.io/rb/gcloud.svg)](http://badge.fury.io/rb/gcloud)
 
 * [Homepage](http://googlecloudplatform.github.io/gcloud-ruby/)
 * [API Documentation](http://googlecloudplatform.github.io/gcloud-ruby/docs/master/)
@@ -13,7 +14,7 @@ Idiomatic Ruby client for [Google Cloud Platform](https://cloud.google.com/) ser
 This client supports the following Google Cloud Platform services:
 
 * [Google Cloud Datastore](https://cloud.google.com/datastore/) ([docs](https://cloud.google.com/datastore/docs))
-* [Google Cloud Storage](https://cloud.google.com/storage/) ([docs](https://cloud.google.com/datastore/docs))
+* [Google Cloud Storage](https://cloud.google.com/storage/) ([docs](https://cloud.google.com/storage/docs/json_api/))
 
 If you need support for other Google APIs, check out the [Google API Ruby Client library](https://github.com/google/google-api-ruby-client).
 
@@ -23,21 +24,11 @@ If you need support for other Google APIs, check out the [Google API Ruby Client
 $ gem install gcloud
 ```
 
-### Authorization
+### Authentication
 
-You need a Google Developers service account to use the Google Cloud services. To create a service account:
+Gcloud uses Service Account credentials to connect to Google Cloud services. When running on Compute Engine the credentials will be discovered automatically. When running on other environments the Service Account credentials can be specified by providing the path to the JSON file, or the JSON itself, in environment variables. Additionally, Cloud SDK credentials can also be discovered automatically, but this is only recommended during development.
 
-1. Visit the [Google Developers Console](https://console.developers.google.com/project).
-2. Create a new project or click on an existing project.
-3. Navigate to **APIs & auth** > **APIs section** and turn on the following APIs (you may need to enable billing in order to use these services):
-  * Google Cloud Datastore API
-  * Google Cloud Storage
-  * Google Cloud Storage JSON API
-4. Navigate to **APIs & auth** > **Credentials** and then:
-  * If you want to use a new service account, click on **Create new Client ID** and select **Service account**. After the account is created, you will be prompted to download the JSON key file that the library uses to authorize your requests.
-  * If you want to generate a new key for an existing service account, click on **Generate new JSON key** and download the JSON key file.
-
-You will use the **Project ID** and **JSON file** to connect to services with gcloud.
+Instructions and configuration options are covered in the [Authentication guide](AUTHENTICATION.md). The examples in Quick Start will demonstrate providing the **Project ID** and **Credentials JSON file path** in code.
 
 ### Datastore
 
@@ -48,6 +39,8 @@ Follow the [activation instructions](https://cloud.google.com/datastore/docs/act
 See the [gcloud-ruby Datastore API documentation](http://googlecloudplatform.github.io/gcloud-ruby/docs/master/Gcloud/Storage.html) to learn how to interact with the Cloud Datastore using this library.
 
 ```ruby
+require 'gcloud/datastore'
+
 dataset = Gcloud.datastore "my-todo-project-id",
                            "/path/to/keyfile.json"
 
@@ -68,11 +61,13 @@ completed_tasks = dataset.run query
 
 ### Storage
 
-[Google Cloud Storage](https://cloud.google.com/storage/) ([docs](https://cloud.google.com/datastore/docs)) allows you to store data on Google infrastructure with very high reliability, performance and availability, and can be used to distribute large data objects to users via direct download.
+[Google Cloud Storage](https://cloud.google.com/storage/) ([docs](https://cloud.google.com/storage/docs/json_api/)) allows you to store data on Google infrastructure with very high reliability, performance and availability, and can be used to distribute large data objects to users via direct download.
 
 See the [gcloud-ruby Storage API documentation](http://googlecloudplatform.github.io/gcloud-ruby/docs/master/Gcloud/Storage.html) to learn how to connect to Cloud Storage using this library.
 
 ```ruby
+require 'gcloud/storage'
+
 storage = Gcloud.storage "my-todo-project-id",
                          "/path/to/keyfile.json"
 

data/lib/gcloud.rb

@@ -1,5 +1,35 @@
+#--
+# Copyright 2015 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/version"
 
+##
+# = Google Cloud
+#
+# Gcloud is the official library for interacting with the Google Cloud Platform.
+# Google Cloud Platform is a set of modular cloud-based services that allow
+# you to create anything from simple websites to complex applications.
+#
+# Gcloud's goal is to provide a API that is familiar and comfortable to
+# Rubyists. Authentication is handled by providing project and credential
+# information, or if you are running on Google Compute Engine this configuration
+# is taken care of for you.
+#
+# You can learn more about various options for connection on the
+# {Authentication Guide}[AUTHENTICATION.md].
+#
 module Gcloud
   ##
   # Base Gcloud exception class.

data/lib/gcloud/backoff.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,6 +13,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+#--
+# Google Cloud Backoff
 module Gcloud
   ##
   # Backoff allows users to control how Google API calls are retried.

data/lib/gcloud/credentials.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,6 +18,8 @@ require "signet/oauth_2/client"
 require "forwardable"
 require "googleauth"
 
+#--
+# Google Cloud Credentials
 module Gcloud
   ##
   # Represents the Oauth2 signing logic.
@@ -26,7 +29,9 @@ module Gcloud
     TOKEN_CREDENTIAL_URI = "https://accounts.google.com/o/oauth2/token"
     AUDIENCE = "https://accounts.google.com/o/oauth2/token"
     SCOPE = []
-    ENV_VARS = ["GOOGLE_CLOUD_KEYFILE"]
+    PATH_ENV_VARS = ["GOOGLE_CLOUD_KEYFILE"]
+    JSON_ENV_VARS = ["GOOGLE_CLOUD_KEYFILE_JSON"]
+    DEFAULT_PATHS = ["~/.config/gcloud/application_default_credentials.json"]
 
     attr_accessor :client
 
@@ -38,59 +43,71 @@ module Gcloud
                    :scope, :issuer, :signing_key
 
     def initialize keyfile, options = {}
+      verify_keyfile_provided! keyfile
       if keyfile.is_a? Signet::OAuth2::Client
         @client = keyfile
-      else
+      elsif keyfile.is_a? Hash
         @client = init_client keyfile, options
+      else
+        verify_keyfile_exists! keyfile
+        @client = init_client JSON.parse(::File.read(keyfile)), options
       end
       @client.fetch_access_token!
     end
 
+    # rubocop:disable all
+    # Disabled rubocop because this is intentionally complex.
+
     ##
     # Returns the default credentials.
     #
-    def self.default
-      self::ENV_VARS.each do |env_var|
-        keyfile = ENV[env_var].to_s
-        return new keyfile if ::File.file? keyfile
+    def self.default options = {}
+      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, options
+      end
+      # Second try to find keyfile json from environment variables.
+      self::JSON_ENV_VARS.map(&json).reject(&:nil?).each do |hash|
+        return new hash, options
       end
-      return new sdk_default_creds if ::File.file? sdk_default_creds
-      client = Google::Auth.get_application_default self::SCOPE
+      # Third try to find keyfile file from known file paths.
+      self::DEFAULT_PATHS.select(&path).each do |file|
+        return new file, options
+      end
+      # Finally get instantiated client from Google::Auth.
+      scope = options[:scope] || options["scope"] || self::SCOPE
+      client = Google::Auth.get_application_default scope
       new client
     end
 
+    # rubocop:enable all
+
+    protected
+
     ##
-    # The filepath of the default application credentials used by
-    # the gcloud SDK.
-    #
-    # This file is created when running <tt>gcloud auth login</tt>
-    def self.sdk_default_creds #:nodoc:
-      # This method will likely be moved once we gain better
-      # support for running in a GCE environment.
-      sdk_creds = "~/.config/gcloud/application_default_credentials.json"
-      File.expand_path sdk_creds
+    # 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
 
-    protected
+    ##
+    # 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, options
-      verify_keyfile! keyfile
       client_opts = client_options keyfile, options
       Signet::OAuth2::Client.new client_opts
     end
 
-    ##
-    # Initializes the Signet client.
-    def verify_keyfile! keyfile
-      if keyfile.nil?
-        fail "You must provide a keyfile to connect with."
-      elsif !::File.file?(keyfile)
-        fail "The keyfile '#{keyfile}' is not a valid file."
-      end
-    end
-
     ##
     # returns a new Hash with string keys instead of symbol keys.
     def stringify_hash_keys hash
@@ -111,7 +128,7 @@ module Gcloud
       # Constructor options override default options
       options = default_options.merge options
       # Keyfile options override everything
-      options = options.merge JSON.parse(::File.read(keyfile))
+      options = options.merge keyfile
 
       # client options for initializing signet client
       { token_credential_uri: options["token_credential_uri"],

data/lib/gcloud/datastore.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -18,30 +19,41 @@ require "gcloud/datastore/dataset"
 require "gcloud/datastore/transaction"
 require "gcloud/datastore/credentials"
 
-##
+#--
 # Google Cloud Datastore
 module Gcloud
   ##
-  # Create a new Gcloud::Datastore::Dataset.
+  # Creates a new object for connecting to the Datastore service.
+  # Each call creates a new connection.
+  #
+  # === Parameters
+  #
+  # +project+::
+  #   Dataset identifier for the Datastore you are connecting to. (+String+)
+  # +keyfile+::
+  #   Keyfile downloaded from Google Cloud. If file path the file must be
+  #   readable. (+String+ or +Hash+)
+  #
+  # === Returns
+  #
+  # Gcloud::Datastore::Dataset
+  #
+  # === Example
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore "my-todo-project",
+  #                              "/path/to/keyfile.json"
   #
   #   entity = Gcloud::Datastore::Entity.new
   #   entity.key = Gcloud::Datastore::Key.new "Task"
   #   entity["description"] = "Get started with Google Cloud"
   #   entity["completed"] = false
   #
-  #   dataset = Gcloud.datastore "my-todo-project",
-  #                              "/path/to/keyfile.json"
   #   dataset.save entity
   #
-  # @param dataset_id [String] the dataset identifier for the Datastore
-  # you are connecting to.
-  # @param keyfile [String] the path to the keyfile you downloaded from
-  # Google Cloud. The file must readable.
-  # @return [Gcloud::Datastore::Dataset] new dataset.
-  #
-  # See Gcloud::Datastore::Dataset
-  def self.datastore project = ENV["DATASTORE_PROJECT"],
-                     keyfile = nil
+  def self.datastore project = nil, keyfile = nil
+    project ||= Gcloud::Datastore::Dataset.default_project
     if keyfile.nil?
       credentials = Gcloud::Datastore::Credentials.default
     else
@@ -51,7 +63,20 @@ module Gcloud
   end
 
   ##
-  # Google Cloud Datastore
+  # = Google Cloud Datastore
+  #
+  # Google Cloud Datastore is a fully managed, schemaless database for storing
+  # non-relational data. You should feel at home if you are familiar with
+  # relational databases, but there are some key differences to be aware of to
+  # make the most of using Datastore.
+  #
+  # Gcloud's goal is to provide a API that is familiar and comfortable to
+  # Rubyists. Authentication is handled by Gcloud.datastore. You can provide
+  # the project and credential information to connect to the Datastore service,
+  # or if you are running on Google Compute Engine this configuration is taken
+  # care of for you.
+  #
+  #   require "glcoud/datastore"
   #
   #   dataset = Gcloud.datastore "my-todo-project",
   #                              "/path/to/keyfile.json"
@@ -59,8 +84,214 @@ module Gcloud
   #   entity["completed"] = true
   #   dataset.save entity
   #
+  # You can learn more about various options for connection on the
+  # {Authentication Guide}[link:AUTHENTICATION.md].
+  #
+  # To learn more about Datastore, read the
+  # {Google Cloud Datastore Concepts Overview
+  # }[https://cloud.google.com/datastore/docs/concepts/overview].
+  #
+  # == Retrieving Records
+  #
+  # Records, called "entities" in Datastore, are retrieved by using a Key.
+  # The Key is more than a numeric identifier, it is a complex data structure
+  # that can be used to model relationships. The simplest Key has a string
+  # <tt>kind</tt> value, and either a numeric <tt>id</tt> value, or a string
+  # <tt>name</tt> value. A single record can be retrieved by calling
+  # Gcloud::Datastore::Dataset#find and passing the parts of the key:
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #   entity = dataset.find "Task", "start"
+  #
+  # Optionally, Gcloud::Datastore::Dataset#find can be given a Key object:
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #   key = Gcloud::Datastore::Key.new "Task", 12345
+  #   entity = dataset.find key
+  #
+  # See Gcloud::Datastore::Dataset#find
+  #
+  # == Querying Records
+  #
+  # Multiple records can be found that match criteria.
+  # (See Gcloud::Datastore::Query#where)
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #   query = Gcloud::Datastore::Query.new
+  #   query.kind("List").
+  #     where("active", "=", true)
+  #   active_lists = dataset.run query
+  #
+  # Records can also be ordered. (See Gcloud::Datastore::Query#order)
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #   query = Gcloud::Datastore::Query.new
+  #   query.kind("List").
+  #     where("active", "=", true).
+  #     order("name")
+  #   active_lists = dataset.run query
+  #
+  # The number of records returned can be specified.
+  # (See Gcloud::Datastore::Query#limit)
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #   query = Gcloud::Datastore::Query.new
+  #   query.kind("List").
+  #     where("active", "=", true).
+  #     order("name").
+  #     limit(5)
+  #   active_lists = dataset.run query
+  #
+  # Records' Key structures can also be queried.
+  # (See Gcloud::Datastore::Query#ancestor)
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #
+  #   list = dataset.find "List", "todos"
+  #   query = Gcloud::Datastore::Query.new
+  #   query.kind("Task").
+  #     ancestor(list.key)
+  #   items = dataset.run query
+  #
+  # See Gcloud::Datastore::Query and Gcloud::Datastore::Dataset#run
+  #
+  # == Paginating Records
+  #
+  # All Records may not return at once, requiring multiple calls to Datastore
+  # to return them all. The returned records will have a <tt>cursor</tt> if
+  # there are more available.
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #
+  #   list = dataset.find "List", "todos"
+  #   query = Gcloud::Datastore::Query.new
+  #   query.kind("Task").
+  #     ancestor(list.key)
+  #   all_tasks = []
+  #   tmp_tasks = dataset.run query
+  #   while tmp_tasks.any? do
+  #     tmp_tasks.each do |task|
+  #       all_tasks << task
+  #     end
+  #     # break loop if no more tasks available
+  #     break if tmp_tasks.cursor.nil?
+  #     # set cursor on the query
+  #     query = query.cursor tmp_tasks.cursor
+  #     # query for more records
+  #     tmp_tasks = dataset.run query
+  #   end
+  #
+  # See Gcloud::Datastore::Dataset::LookupResults and
+  # Gcloud::Datastore::Dataset::QueryResults
+  #
+  # == Creating Records
+  #
+  # New entities can be created and persisted buy calling Dataset#save.
+  # The entity must have a Key to be saved. If the Key is incomplete then
+  # it will be completed when saved.
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #   entity = Gcloud::Datastore::Entity.new
+  #   entity.key = Gcloud::Datastore::Key.new "User"
+  #   entity["name"] = "Heidi Henderson"
+  #   entity.key.id #=> nil
+  #   dataset.save entity
+  #   entity.key.id #=> 123456789
+  #
+  # == Updating Records
+  #
+  # Entities hold properties. A property has a name that is a string or symbol,
+  # and a value that is an object. Most value objects are supported, including
+  # String, Integer, Date, Time, and even other Entity or Key objects. Changes
+  # to the Entity's properties are persisted by calling Dataset#save.
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #   entity = datastore.find "User", "heidi"
+  #   # Read the status property
+  #   entity["status"] #=> "inactive"
+  #   # Write the status property
+  #   entity["status"] = "active"
+  #   # Persist the changes
+  #   dataset.save entity
+  #
+  # == Deleting Records
+  #
+  # Entities can be removed from Datastore by calling Dataset#delete and passing
+  # the Entity object or the entity's Key object.
+  #
+  #   require "glcoud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #   entity = datastore.find "User", "heidi"
+  #   dataset.delete entity
+  #
+  # == Transactions
+  #
+  # Complex logic can be wrapped in a Transaction. All queries and updates
+  # within the Dataset#transaction block are run within the transaction scope,
+  # and will be automatically committed when the block completes.
+  #
+  #   require "gcloud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #
+  #   key = Gcloud::Datastore::Key.new "User", "heidi"
+  #
+  #   user = Gcloud::Datastore::Entity.new
+  #   user.key = key
+  #   user["name"] = "Heidi Henderson"
+  #   user["email"] = "heidi@example.net"
+  #
+  #   dataset.transaction do |tx|
+  #     if tx.find(user.key).nil?
+  #       tx.save user
+  #     end
+  #   end
+  #
+  # Alternatively, if no block is given the transaction object is returned
+  # allowing you to commit or rollback manually.
+  #
+  #   require "gcloud/datastore"
+  #
+  #   dataset = Gcloud.datastore
+  #
+  #   key = Gcloud::Datastore::Key.new "User", "heidi"
+  #
+  #   user = Gcloud::Datastore::Entity.new
+  #   user.key = key
+  #   user["name"] = "Heidi Henderson"
+  #   user["email"] = "heidi@example.net"
+  #
+  #   tx = dataset.transaction
+  #   begin
+  #     if tx.find(user.key).nil?
+  #       tx.save user
+  #     end
+  #     tx.commit
+  #   rescue
+  #     tx.rollback
+  #   end
   #
-  # See Gcloud::Datastore::Dataset
+  # See Gcloud::Datastore::Transaction and
+  # Gcloud::Datastore::Dataset#transaction
   module Datastore
   end
 end