gcloud 0.1.0 → 0.1.1

data/lib/gcloud/datastore/errors.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,16 +18,22 @@ require "gcloud"
 module Gcloud
   module Datastore
     ##
+    # = Datastore Error
+    #
     # Base Datastore exception class.
     class Error < Gcloud::Error
     end
 
     ##
+    # = KeyfileError
+    #
     # Raised when a keyfile is not correct.
     class KeyfileError < Gcloud::Datastore::Error
     end
 
     ##
+    # = ApiError
+    #
     # Raised when an API call is not successful.
     class ApiError < Gcloud::Datastore::Error
       ##
@@ -37,7 +44,7 @@ module Gcloud
       # The response object of the failed HTTP request.
       attr_reader :response
 
-      def initialize method, response = nil
+      def initialize method, response = nil #:nodoc:
         super("API call to #{method} was not successful")
         @method = method
         @response = response
@@ -45,18 +52,22 @@ module Gcloud
     end
 
     ##
+    # = PropertyError
+    #
     # Raised when a property is not correct.
     class PropertyError < Gcloud::Datastore::Error
     end
 
     ##
+    # = TransactionError
+    #
     # General error for Transaction problems.
     class TransactionError < Gcloud::Datastore::Error
       ##
       # An error that occurred within the transaction. (optional)
       attr_reader :inner
 
-      def initialize message, inner = nil
+      def initialize message, inner = nil #:nodoc:
         super(message)
         @inner = inner
       end

data/lib/gcloud/datastore/key.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,7 +18,7 @@ require "gcloud/datastore/proto"
 module Gcloud
   module Datastore
     ##
-    # Datastore Key
+    # = Key
     #
     # Every Datastore record has an identifying key, which includes the record's
     # entity kind and a unique identifier. The identifier may be either a key
@@ -28,14 +29,55 @@ module Gcloud
     class Key
       ##
       # The kind of the Key.
+      #
+      # === Returns
+      #
+      # +String+
+      #
+      # === Example
+      #
+      #   key = Gcloud::Datastore::Key.new "User"
+      #   key.kind #=> "User"
+      #   key.kind = "Task"
+      #
       attr_accessor :kind
 
       ##
       # The dataset_id of the Key.
+      #
+      # === Returns
+      #
+      # +String+
+      #
+      # === Example
+      #
+      #   require "glcoud/datastore"
+      #
+      #   dataset = Gcloud.datastore "my-todo-project",
+      #                              "/path/to/keyfile.json"
+      #
+      #   entity = dataset.find "User", "heidi"
+      #   entity.key.dataset_id #=> "my-todo-project"
+      #
       attr_accessor :dataset_id
 
       ##
       # The namespace of the Key.
+      #
+      # === Returns
+      #
+      # +String+ or +nil+
+      #
+      # === Example
+      #
+      #   require "glcoud/datastore"
+      #
+      #   dataset = Gcloud.datastore "my-todo-project",
+      #                              "/path/to/keyfile.json"
+      #
+      #   entity = dataset.find "User", "heidi"
+      #   entity.key.namespace #=> "ns~todo-project"
+      #
       attr_accessor :namespace
 
       def initialize kind = nil, id_or_name = nil
@@ -50,6 +92,20 @@ module Gcloud
       ##
       # Set the id of the Key.
       # If a name is already present it will be removed.
+      #
+      # === Returns
+      #
+      # +Integer+ or +nil+
+      #
+      # === Example
+      #
+      #   key = Gcloud::Datastore::Key.new "User", "heidi"
+      #   key.id #=> nil
+      #   key.name #=> "heidi"
+      #   key.id = 654321
+      #   key.id #=> 654321
+      #   key.name #=> nil
+      #
       def id= new_id #:nodoc:
         @name = nil if new_id
         @id = new_id
@@ -57,11 +113,35 @@ module Gcloud
 
       ##
       # The id of the Key.
+      #
+      # === Returns
+      #
+      # +Integer+ or +nil+
+      #
+      # === Example
+      #
+      #   key = Gcloud::Datastore::Key.new "User", 123456
+      #   key.id #=> 123456
+      #
       attr_reader :id
 
       ##
       # Set the name of the Key.
       # If an id is already present it will be removed.
+      #
+      # === Returns
+      #
+      # +String+ or +nil+
+      #
+      # === Example
+      #
+      #   key = Gcloud::Datastore::Key.new "User", 123456
+      #   key.id #=> 123456
+      #   key.name #=> nil
+      #   key.name = "heidi"
+      #   key.id #=> nil
+      #   key.name #=> "heidi"
+      #
       def name= new_name #:nodoc:
         @id = nil if new_name
         @name = new_name
@@ -69,10 +149,30 @@ module Gcloud
 
       ##
       # The name of the Key.
+      #
+      # === Returns
+      #
+      # +String+ or +nil+
+      #
+      # === Example
+      #
+      #   key = Gcloud::Datastore::Key.new "User", "heidi"
+      #   key.name #=> "heidi"
+      #
       attr_reader :name
 
       ##
       # Set the parent of the Key.
+      #
+      # === Returns
+      #
+      # +Key+ or +nil+
+      #
+      # === Example
+      #
+      #   key = Gcloud::Datastore::Key.new "List", "todos"
+      #   key.parent = Gcloud::Datastore::Key.new "User", "heidi"
+      #
       def parent= new_parent #:nodoc:
         # store key if given an entity
         new_parent = new_parent.key if new_parent.respond_to? :key
@@ -81,6 +181,24 @@ module Gcloud
 
       ##
       # The parent of the Key.
+      #
+      # === Returns
+      #
+      # +Key+ or +nil+
+      #
+      # === Example
+      #
+      #   require "glcoud/datastore"
+      #
+      #   dataset = Gcloud.datastore
+      #
+      #   user = dataset.find "User", "heidi"
+      #   query = Gcloud::Datastore::Query.new
+      #   query.kind("List").
+      #     ancestor(user.key)
+      #   lists = dataset.run query
+      #   lists.first.key.parent #=> Key("User", "heidi")
+      #
       attr_reader :parent
 
       ##
@@ -88,7 +206,16 @@ module Gcloud
       # Each inner array contains two values, the kind and the id or name.
       # If neither an id or name exist then nil will be returned.
       #
-      #   puts key.path #=> [["Person", "username"], ["Task", 123456]]
+      # === Returns
+      #
+      # Array of arrays
+      #
+      # === Example
+      #
+      #   key = Gcloud::Datastore::Key.new "List", "todos"
+      #   key.parent = Gcloud::Datastore::Key.new "User", "heidi"
+      #   key.path #=> [["User", "heidi"], ["List", "todos"]]
+      #
       def path
         new_path = parent ? parent.path : []
         new_path << [kind, (id || name)]
@@ -97,6 +224,8 @@ module Gcloud
       ##
       # Determine if the key is complete.
       # A complete key has either an id or a name.
+      #
+      # Inverse of #incomplete?
       def complete?
         !incomplete?
       end
@@ -104,6 +233,8 @@ module Gcloud
       ##
       # Determine if the key is incomplete.
       # An incomplete key has neither an id nor a name.
+      #
+      # Inverse of #complete?
       def incomplete?
         kind.nil? || (id.nil? && (name.nil? || name.empty?))
       end

data/lib/gcloud/datastore/properties.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,7 +16,11 @@
 module Gcloud
   module Datastore
     ##
-    # Properties
+    # = Properties
+    #
+    # Hash-like data structure for Datastore properties.
+    #
+    # See Entity#properties
     class Properties
       def initialize properties = {}
         @hash = {}

data/lib/gcloud/datastore/proto.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -241,7 +242,7 @@ module Gcloud
         end
       end
 
-      class Key
+      class Key #:nodoc:
         def dup
           proto_request_body = ""
           self.encode proto_request_body

data/lib/gcloud/datastore/query.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
     ##
-    # Query represents a query to be made to the Datastore.
+    # = Query
+    #
+    # Represents the search criteria against a Datastore.
     #
     #   query = Gcloud::Datastore::Query.new
     #   query.kind("Task").
@@ -178,12 +181,9 @@ module Gcloud
         self
       end
 
-      # rubocop:disable Style/TrivialAccessors
       def to_proto #:nodoc:
-        # Disabled rubocop because this implementation will most likely change.
         @_query
       end
-      # rubocop:enable Style/TrivialAccessors
     end
   end
 end

data/lib/gcloud/datastore/transaction.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,6 +16,8 @@
 module Gcloud
   module Datastore
     ##
+    # = Transaction
+    #
     # Special Connection instance for running transactions.
     #
     # See Gcloud::Datastore::Dataset.transaction

data/lib/gcloud/storage.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright 2014 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,26 +16,38 @@
 require "gcloud"
 require "gcloud/storage/project"
 
-##
+#--
 # Google Cloud Storage
 module Gcloud
   ##
-  # Create a new Storage project.
+  # Creates a new object for connecting to the Storage service.
+  # Each call creates a new connection.
+  #
+  # === Parameters
+  #
+  # +project+::
+  #   Project identifier for the Storage service you are connecting to.
+  #   (+String+)
+  # +keyfile+::
+  #   Keyfile downloaded from Google Cloud. If file path the file must be
+  #   readable. (+String+ or +Hash+)
+  #
+  # === Returns
+  #
+  # Gcloud::Storage::Project
+  #
+  # === Example
+  #
+  #   require "glcoud/storage"
   #
   #   storage = Gcloud.storage "my-todo-project",
   #                            "/path/to/keyfile.json"
+  #
   #   bucket = storage.find_bucket "my-bucket"
   #   file = bucket.find_file "path/to/my-file.ext"
   #
-  # @param project [String] the project identifier for the Storage
-  # account you are connecting to.
-  # @param keyfile [String] the path to the keyfile you downloaded from
-  # Google Cloud. The file must readable.
-  # @return [Gcloud::Storage::Project] storage project.
-  #
-  # See Gcloud::Storage::Project
-  def self.storage project = ENV["STORAGE_PROJECT"],
-                   keyfile = nil
+  def self.storage project = nil, keyfile = nil
+    project ||= Gcloud::Storage::Project.default_project
     if keyfile.nil?
       credentials = Gcloud::Storage::Credentials.default
     else
@@ -44,14 +57,268 @@ module Gcloud
   end
 
   ##
-  # Google Cloud Storage
+  # = Google Cloud Storage
+  #
+  # Google Cloud Storage is an Internet service to store data in Google's cloud.
+  # It allows world-wide storage and retrieval of any amount of data and at any
+  # time, taking advantage of Google's own reliable and fast networking
+  # infrastructure to perform data operations in a cost effective manner.
+  #
+  # Gcloud's goal is to provide a API that is familiar and comfortable to
+  # Rubyists. Authentication is handled by Gcloud.storage. You can provide the
+  # project and credential information to connect to the Storage service, or if
+  # you are running on Google Compute Engine this configuration is taken care
+  # of for you.
+  #
+  #   require "glcoud/storage"
   #
   #   storage = Gcloud.storage "my-todo-project",
   #                            "/path/to/keyfile.json"
+  #
   #   bucket = storage.find_bucket "my-bucket"
   #   file = bucket.find_file "path/to/my-file.ext"
   #
-  # See Gcloud::Storage::Project
+  # 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 Storage Overview
+  # }[https://cloud.google.com/storage/docs/overview].
+  #
+  # == Retrieving Buckets
+  #
+  # A Bucket is the container for your data. There is no limit on the number of
+  # buckets that you can create in a project. You can use buckets to organize
+  # and control access to your data. Each bucket has a unique name, which is how
+  # they are retrieved: (See Project#find_bucket)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #
+  # You can also retrieve all buckets on a project: (See Project#buckets)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   all_buckets = storage.buckets
+  #
+  # If you have a significant number of buckets, you may need to paginate
+  # through them: (See Bucket::List#token)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   all_buckets = []
+  #   tmp_buckets = storage.buckets
+  #   while tmp_buckets.any? do
+  #     tmp_buckets.each do |bucket|
+  #       all_buckets << bucket
+  #     end
+  #     # break loop if no more buckets available
+  #     break if tmp_buckets.token.nil?
+  #     # get the next group of buckets
+  #     tmp_buckets = storage.buckets token: tmp_buckets.token
+  #   end
+  #
+  # == Creating a Bucket
+  #
+  # A unique name is all that is needed to create a new bucket:
+  # (See Project#create_bucket)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.create_bucket "my-todo-app-attachments"
+  #
+  # == Retrieving Files
+  #
+  # A File is an individual pieces of data that you store in Google Cloud
+  # Storage. Files contain the data stored as well as metadata describing the
+  # data. Files belong to a bucket and cannot be shared among buckets. There is
+  # no limit on the number of objects that you can create in a bucket.
+  #
+  # Files are retrieved by their name, which is the path of the file in the
+  # bucket: (See Bucket#find_file)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #   file = bucket.find_file "avatars/heidi/400x400.png"
+  #
+  # You can also retrieve all files in a bucket: (See Bucket#files)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #   all_files = bucket.files
+  #
+  # Or you can retrieve all files in a specified path:
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #   avatar_files = bucket.files prefix: "avatars/"
+  #
+  # If you have a significant number of files, you may need to paginate through
+  # them: (See File::List#token)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #
+  #   all_files = []
+  #   tmp_files = bucket.files
+  #   while tmp_files.any? do
+  #     tmp_files.each do |file|
+  #       all_files << file
+  #     end
+  #     # break loop if no more files available
+  #     break if tmp_files.token.nil?
+  #     # get the next group of files
+  #     tmp_files = bucket.files token: tmp_files.token
+  #   end
+  #
+  # == Creating a File
+  #
+  # A new File can be uploaded by specifying the location of a file on the local
+  # file system, and the name/path that the file should be stored in the bucket.
+  # (See Bucket#create_file)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #   bucket.create_file "/var/todo-app/avatars/heidi/400x400.png",
+  #                      "avatars/heidi/400x400.png"
+  #
+  # == Downloading a File
+  #
+  # Files can be downloaded to the local file system. (See File#download)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #   file = bucket.find_file "avatars/heidi/400x400.png"
+  #   file.download "/var/todo-app/avatars/heidi/400x400.png"
+  #
+  # == Using Signed URLs
+  #
+  # Access without authentication can be granted to a File for a specified
+  # period of time. This URL uses a cryptographic signature
+  # of your credentials to access the file. (See File#signed_url)
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #   file = bucket.find_file "avatars/heidi/400x400.png"
+  #   shared_url = file.signed_url method: "GET",
+  #                                expires: 300 # 5 minutes from now
+  #
+  # == Controlling Access to a Bucket
+  #
+  # Access to a bucket is controlled with Bucket#acl. A bucket has owners,
+  # writers, and readers. Permissions can be granted to an individual user's
+  # email address, a group's email address, as well as many predefined lists.
+  # See the
+  # {Access Control guide}[https://cloud.google.com/storage/docs/access-control]
+  # for more.
+  #
+  # Access to a bucket can be granted to a user by appending +"user-"+ to the
+  # email address:
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #
+  #   email = "heidi@example.net"
+  #   bucket.acl.add_reader "user-#{email}"
+  #
+  # Access to a bucket can be granted to a group by appending +"group-"+ to the
+  # email address:
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #
+  #   email = "authors@example.net"
+  #   bucket.acl.add_reader "group-#{email}"
+  #
+  # Access to a bucket can also be granted to a predefined list of permissions:
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #
+  #   bucket.acl.public!
+  #
+  # == Controlling Access to a File
+  #
+  # Access to a file is controlled in two ways, either by the setting the
+  # default permissions to all files in a bucket with Bucket#default_acl, or by
+  # setting permissions to an individual file with File#acl.
+  #
+  # Access to a file can be granted to a user by appending +"user-"+ to the
+  # email address:
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #   file = bucket.find_file "avatars/heidi/400x400.png"
+  #
+  #   email = "heidi@example.net"
+  #   file.acl.add_reader "user-#{email}"
+  #
+  # Access to a file can be granted to a group by appending +"group-"+ to the
+  # email address:
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #   file = bucket.find_file "avatars/heidi/400x400.png"
+  #
+  #   email = "authors@example.net"
+  #   file.acl.add_reader "group-#{email}"
+  #
+  # Access to a file can also be granted to a predefined list of permissions:
+  #
+  #   require "gcloud/storage"
+  #
+  #   storage = Gcloud.storage
+  #
+  #   bucket = storage.find_bucket "my-todo-app"
+  #   file = bucket.find_file "avatars/heidi/400x400.png"
+  #
+  #   file.acl.public!
+  #
   module Storage
     ##
     # Retrieve resumable threshold.