gcloud 0.1.1 → 0.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YWUyNTJhOGZkZDNmY2E2NTFlOWJkNjRjZTEyNzhmYzkyMjVlY2RlMA==
+    MmIyMDI3NTljZjg4NGM3YzA2ODY0YmMwMmE5ZDUwOGJmM2I5MmZlMA==
   data.tar.gz: !binary |-
-    MGNhMjVhNjE5Njc5ZmM5NTU4MDlkYjJiYjA0OGQ1MmJjM2M0NDAyNA==
+    ZmY3ZTI0NmQ4MWIzMmYyZmZjY2ViYThkZDRlN2MxZjZiODUzNjhiNg==
 SHA512:
   metadata.gz: !binary |-
-    YzUzYTQ3NWRkMDI1N2U1YTVkMWJkZDZjM2VjYTAxZjYxZGMxMWRlMmRjY2Vi
-    MmU2MGFlNDI4YTE1NmIzZjg2ODYzOGU3NWUzMDE3YmNmMzU4Y2JiMjMwOGUz
-    NGU3ZTdmMzM4ZGU2YjAyZmFiOTg4OGZiOGNmMWEwM2Y3YzA4MjA=
+    ODE0ZTZjNzI4M2I2MDhlMWYyNTNjYjVhMTIwNzc5NTI2ZmE4MmVlY2NiOGEw
+    YjZjMjlkODNjOWNmMWEwZDdlNmMyYWVkNTEzOTgyYzM2NDJiM2YyZWUyOGUy
+    NmFmYzEzMzQwYWUzNjc5N2Q0MWRhOWY0ZDIyNjEyYzRkMTU0ODg=
   data.tar.gz: !binary |-
-    ZGEwM2NmNTQ0ZjExNjQ4NzhlZGFmODg5NjkwZjhkNjVmMjBmMzJlM2QzZTg5
-    YTFmOTc5NGVhMzdjZWNjMTY1OTY3OWE0OGE0MGQwM2UzNmY5N2IyZDI1MmQy
-    NDhjNmZkYzQ3YTUwYWIxZTA1MTk0NGIwZDNiMjMyMDAzZmNiMTY=
+    YzFmZGEzYTExZTI4Y2FjN2E4MmRlMjdmNjI5ZGE3Y2Q2Mjk2ZDUwYzcxOWNj
+    MDVmZDc1NTI5OWEwN2Y2M2RiYmJmYzJiZTQyNjU5MmY0NDFjZWJlNzM4MGZh
+    ZWMzZDkzMDhlMTkzYmU5ZGNkYzUwYmVkY2RlMTEwMWZlYmQ5NzA=

data/AUTHENTICATION.md

@@ -61,7 +61,7 @@ This option allows for an easy way to authenticate during development. If creden
 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`
+2. Authenticate using OAuth 2.0 `$ 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.

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Release History
 
+### 0.2.0 / 2015-07-22
+
+#### Major changes
+
+Add Pub/Sub service
+
+#### Minor changes
+
+* Add top-level `Gcloud` object with instance methods to initialize connections
+  with individual services (e.g. `Gcloud#storage`)
+* Add credential options to `Gcloud::Storage::File#signed_url`
+* Add method aliases to improve usability of Storage API
+* Improve documentation
+
 ### 0.1.1 / 2015-06-16
 
 * Storage downloads files in binary mode (premist).

data/OVERVIEW.md

@@ -0,0 +1,87 @@
+# Getting started
+
+The `gcloud` library is installable through rubygems:
+
+```sh
+$ gem install gcloud
+```
+
+Gcloud aims to make authentication as simple as possible. Google Cloud requires a **Project ID** and **Service Account Credentials** to connect to the APIs. You can learn more about various options for connection on the [Authentication Guide](AUTHENTICATION.md).
+
+# Datastore
+
+[Google Cloud Datastore](https://cloud.google.com/datastore/) ([docs](https://cloud.google.com/datastore/docs)) is a fully managed, schemaless database for storing non-relational data. Cloud Datastore automatically scales with your users and supports ACID transactions, high availability of reads and writes, strong consistency for reads and ancestor queries, and eventual consistency for all other queries.
+
+Follow the [activation instructions](https://cloud.google.com/datastore/docs/activate) to use the Google Cloud Datastore API with your project.
+
+See the [gcloud-ruby Datastore API documentation](rdoc-ref:Gcloud::Datastore) to learn how to interact with the Cloud Datastore using this library.
+
+```ruby
+require "gcloud"
+
+gcloud = Gcloud.new
+dataset = gcloud.datastore
+
+# Create a new task to demo datastore
+demo_task = Gcloud::Datastore::Entity.new
+demo_task.key = Gcloud::Datastore::Key.new "Task", "datastore-demo"
+demo_task[:description] = "Demonstrate Datastore functionality"
+demo_task[:completed] = false
+
+# Save the new task
+dataset.save demo_task
+
+# Run a query for all completed tasks
+query = Gcloud::Datastore::Query.new.kind("Task").
+  where("completed", "=", true)
+completed_tasks = dataset.run query
+```
+
+# Pub/Sub
+
+[Google Cloud Pub/Sub](https://cloud.google.com/pubsub/) ([docs](https://cloud.google.com/pubsub/reference/rest/)) is designed to provide reliable, many-to-many, asynchronous messaging between applications. Publisher applications can send messages to a “topic” and other applications can subscribe to that topic to receive the messages. By decoupling senders and receivers, Google Cloud Pub/Sub allows developers to communicate between independently written applications.
+
+See the [gcloud-ruby Pub/Sub API documentation](rdoc-ref:Gcloud::Pubsub) to learn how to connect to Cloud Pub/Sub using this library.
+
+```ruby
+require "gcloud"
+
+gcloud = Gcloud.new
+pubsub = gcloud.pubsub
+
+# Retrieve a topic
+topic = pubsub.topic "my-topic"
+
+# Publish a new message
+msg = topic.publish "new-message"
+
+# Retrieve a subscription
+sub = pubsub.subscription "my-topic-sub"
+
+# Pull available messages
+msgs = sub.pull
+```
+
+# Storage
+
+[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](rdoc-ref:Gcloud::Storage) to learn how to connect to Cloud Storage using this library.
+
+```ruby
+require "gcloud"
+
+gcloud = Gcloud.new
+storage = gcloud.storage
+
+bucket = storage.bucket "task-attachments"
+
+file = bucket.file "path/to/my-file.ext"
+
+# Download the file to the local file system
+file.download "/tasks/attachments/#{file.name}"
+
+# Copy the file to a backup bucket
+backup = storage.bucket "task-attachment-backups"
+file.copy backup, file.name
+```

data/lib/gcloud.rb

@@ -31,6 +31,112 @@ require "gcloud/version"
 # {Authentication Guide}[AUTHENTICATION.md].
 #
 module Gcloud
+  ##
+  # Creates a new object for connecting to Google Cloud.
+  #
+  # === Parameters
+  #
+  # +project+::
+  #   Project identifier for the Pub/Sub 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
+  #
+  # === Example
+  #
+  #   require "gcloud"
+  #
+  #   gcloud  = Gcloud.new
+  #   dataset = gcloud.datastore
+  #   pubsub  = gcloud.pubsub
+  #   storage = gcloud.storage
+  #
+  def self.new project = nil, keyfile = nil
+    gcloud = Object.new
+    gcloud.instance_eval do
+      @project = project
+      @keyfile = keyfile
+    end
+    gcloud.extend Gcloud
+    gcloud
+  end
+
+  ##
+  # Creates a new object for connecting to the Datastore service.
+  # Each call creates a new connection.
+  #
+  # === Returns
+  #
+  # Gcloud::Datastore::Dataset
+  #
+  # === Example
+  #
+  #   require "gcloud"
+  #
+  #   gcloud  = Gcloud.new
+  #   dataset = gcloud.datastore
+  #
+  #   entity = Gcloud::Datastore::Entity.new
+  #   entity.key = Gcloud::Datastore::Key.new "Task"
+  #   entity["description"] = "Get started with Google Cloud"
+  #   entity["completed"] = false
+  #
+  #   dataset.save entity
+  #
+  def datastore
+    require "gcloud/datastore"
+    Gcloud.datastore @project, @keyfile
+  end
+
+  ##
+  # Creates a new object for connecting to the Storage service.
+  # Each call creates a new connection.
+  #
+  # === Returns
+  #
+  # Gcloud::Storage::Project
+  #
+  # === Example
+  #
+  #   require "gcloud"
+  #
+  #   gcloud  = Gcloud.new
+  #   storage = gcloud.storage
+  #   bucket = storage.bucket "my-bucket"
+  #   file = bucket.file "path/to/my-file.ext"
+  #
+  def storage
+    require "gcloud/storage"
+    Gcloud.storage @project, @keyfile
+  end
+
+  ##
+  # Creates a new object for connecting to the Pub/Sub service.
+  # Each call creates a new connection.
+  #
+  # === Returns
+  #
+  # Gcloud::Pubsub::Project
+  #
+  # === Example
+  #
+  #   require "gcloud"
+  #
+  #   gcloud = Gcloud.new
+  #   pubsub = gcloud.pubsub
+  #   topic = pubsub.topic "my-topic"
+  #   topic.publish "task completed"
+  #
+  def pubsub
+    require "gcloud/pubsub"
+    Gcloud.pubsub @project, @keyfile
+  end
+
   ##
   # Base Gcloud exception class.
   class Error < StandardError

data/lib/gcloud/credentials.rb

@@ -22,7 +22,7 @@ require "googleauth"
 # Google Cloud Credentials
 module Gcloud
   ##
-  # Represents the Oauth2 signing logic.
+  # Represents the OAuth 2.0 signing logic.
   # This class is intended to be inherited by API-specific classes
   # which overrides the SCOPE constant.
   class Credentials #:nodoc:

data/lib/gcloud/datastore.rb

@@ -40,7 +40,7 @@ module Gcloud
   #
   # === Example
   #
-  #   require "glcoud/datastore"
+  #   require "gcloud/datastore"
   #
   #   dataset = Gcloud.datastore "my-todo-project",
   #                              "/path/to/keyfile.json"
@@ -71,15 +71,16 @@ module Gcloud
   # 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
+  # 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"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore "my-todo-project",
-  #                              "/path/to/keyfile.json"
+  #   gcloud = Gcloud.new "my-todo-project",
+  #                       "/path/to/keyfile.json"
+  #   dataset = gcloud.datastore
   #   entity = dataset.find "Task", "start"
   #   entity["completed"] = true
   #   dataset.save entity
@@ -100,16 +101,18 @@ module Gcloud
   # <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"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #   entity = dataset.find "Task", "start"
   #
   # Optionally, Gcloud::Datastore::Dataset#find can be given a Key object:
   #
-  #   require "glcoud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #   key = Gcloud::Datastore::Key.new "Task", 12345
   #   entity = dataset.find key
   #
@@ -120,9 +123,10 @@ module Gcloud
   # Multiple records can be found that match criteria.
   # (See Gcloud::Datastore::Query#where)
   #
-  #   require "glcoud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #   query = Gcloud::Datastore::Query.new
   #   query.kind("List").
   #     where("active", "=", true)
@@ -130,9 +134,10 @@ module Gcloud
   #
   # Records can also be ordered. (See Gcloud::Datastore::Query#order)
   #
-  #   require "glcoud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #   query = Gcloud::Datastore::Query.new
   #   query.kind("List").
   #     where("active", "=", true).
@@ -142,9 +147,10 @@ module Gcloud
   # The number of records returned can be specified.
   # (See Gcloud::Datastore::Query#limit)
   #
-  #   require "glcoud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #   query = Gcloud::Datastore::Query.new
   #   query.kind("List").
   #     where("active", "=", true).
@@ -155,9 +161,10 @@ module Gcloud
   # Records' Key structures can also be queried.
   # (See Gcloud::Datastore::Query#ancestor)
   #
-  #   require "glcoud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #
   #   list = dataset.find "List", "todos"
   #   query = Gcloud::Datastore::Query.new
@@ -173,9 +180,10 @@ module Gcloud
   # to return them all. The returned records will have a <tt>cursor</tt> if
   # there are more available.
   #
-  #   require "glcoud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #
   #   list = dataset.find "List", "todos"
   #   query = Gcloud::Datastore::Query.new
@@ -204,9 +212,10 @@ module Gcloud
   # The entity must have a Key to be saved. If the Key is incomplete then
   # it will be completed when saved.
   #
-  #   require "glcoud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #   entity = Gcloud::Datastore::Entity.new
   #   entity.key = Gcloud::Datastore::Key.new "User"
   #   entity["name"] = "Heidi Henderson"
@@ -221,10 +230,11 @@ module Gcloud
   # 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"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
-  #   entity = datastore.find "User", "heidi"
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
+  #   entity = dataset.find "User", "heidi"
   #   # Read the status property
   #   entity["status"] #=> "inactive"
   #   # Write the status property
@@ -237,10 +247,11 @@ module Gcloud
   # Entities can be removed from Datastore by calling Dataset#delete and passing
   # the Entity object or the entity's Key object.
   #
-  #   require "glcoud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
-  #   entity = datastore.find "User", "heidi"
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
+  #   entity = dataset.find "User", "heidi"
   #   dataset.delete entity
   #
   # == Transactions
@@ -249,9 +260,10 @@ module Gcloud
   # within the Dataset#transaction block are run within the transaction scope,
   # and will be automatically committed when the block completes.
   #
-  #   require "gcloud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #
   #   key = Gcloud::Datastore::Key.new "User", "heidi"
   #
@@ -269,9 +281,10 @@ module Gcloud
   # Alternatively, if no block is given the transaction object is returned
   # allowing you to commit or rollback manually.
   #
-  #   require "gcloud/datastore"
+  #   require "gcloud"
   #
-  #   dataset = Gcloud.datastore
+  #   gcloud = Gcloud.new
+  #   dataset = gcloud.datastore
   #
   #   key = Gcloud::Datastore::Key.new "User", "heidi"
   #

data/lib/gcloud/datastore/credentials.rb

@@ -30,7 +30,7 @@ module Gcloud
       JSON_ENV_VARS = %w(DATASTORE_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON)
 
       ##
-      # Sign Oauth2 API calls.
+      # Sign OAuth 2.0 API calls.
       def sign_http_request request #:nodoc:
         if @client
           @client.fetch_access_token! if @client.expired?