lib/gcloud/resource_manager/project.rb in gcloud-0.6.3 vs lib/gcloud/resource_manager/project.rb in gcloud-0.7.0

- old
+ new

@@ -1,6 +1,5 @@ -#-- # 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 @@ -11,24 +10,26 @@ # 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 "time" require "gcloud/resource_manager/errors" require "gcloud/resource_manager/project/list" require "gcloud/resource_manager/project/updater" module Gcloud module ResourceManager ## - # = Project + # # Project # # Project is a high-level Google Cloud Platform entity. It is a container # for ACLs, APIs, AppEngine Apps, VMs, and other Google Cloud Platform # resources. # + # @example # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -37,20 +38,20 @@ # p.labels["env"] = "production" # end # class Project ## - # The Connection object. - attr_accessor :connection #:nodoc: + # @private The Connection object. + attr_accessor :connection ## - # The Google API Client object. - attr_accessor :gapi #:nodoc: + # @private The Google API Client object. + attr_accessor :gapi ## - # Create an empty Project object. - def initialize #:nodoc: + # @private Create an empty Project object. + def initialize @connection = nil @gapi = {} end ## @@ -81,12 +82,11 @@ # and can remain unset. # # Allowed characters are: lowercase and uppercase letters, numbers, # hyphen, single-quote, double-quote, space, and exclamation point. # - # === Example - # + # @example # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -111,27 +111,25 @@ # # Label values must be between 0 and 63 characters long and must conform # to the regular expression <code>([a-z]([-a-z0-9]*[a-z0-9])?)?</code>. # # No more than 256 labels can be associated with a given resource. - # (+Hash+) + # (`Hash`) # - # === Examples + # @yield [labels] a block for setting labels + # @yieldparam [Hash] labels the hash accepting labels # - # Labels are read-only and cannot be changed by direct assignment. - # + # @example Labels are read-only and cannot be changed: # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" # project.labels["env"] #=> "dev" # read only # project.labels["env"] = "production" # raises error # - # Labels can be updated by passing a block, or by calling the #labels= - # method. - # + # @example Labels can be updated by passing a block, or with {#labels=}: # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -159,14 +157,13 @@ # # Label values must be between 0 and 63 characters long and must conform # to the regular expression <code>([a-z]([-a-z0-9]*[a-z0-9])?)?</code>. # # No more than 256 labels can be associated with a given resource. - # (+Hash+) + # (`Hash`) # - # === Example - # + # @example # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -194,56 +191,59 @@ ## # The project lifecycle state. # # Possible values are: - # * +ACTIVE+ - The normal and active state. - # * +LIFECYCLE_STATE_UNSPECIFIED+ - Unspecified state. This is only + # * `ACTIVE` - The normal and active state. + # * `LIFECYCLE_STATE_UNSPECIFIED` - Unspecified state. This is only # used/useful for distinguishing unset values. - # * +DELETE_REQUESTED+ - The project has been marked for deletion by the + # * `DELETE_REQUESTED` - The project has been marked for deletion by the # user (by invoking DeleteProject) or by the system (Google Cloud # Platform). This can generally be reversed by invoking UndeleteProject. - # * +DELETE_IN_PROGRESS+ - The process of deleting the project has begun. + # * `DELETE_IN_PROGRESS` - The process of deleting the project has begun. # Reversing the deletion is no longer possible. # def state @gapi["lifecycleState"] end ## - # Checks if the state is +ACTIVE+. + # Checks if the state is `ACTIVE`. def active? return false if state.nil? "ACTIVE".casecmp(state).zero? end ## - # Checks if the state is +LIFECYCLE_STATE_UNSPECIFIED+. + # Checks if the state is `LIFECYCLE_STATE_UNSPECIFIED`. def unspecified? return false if state.nil? "LIFECYCLE_STATE_UNSPECIFIED".casecmp(state).zero? end ## - # Checks if the state is +DELETE_REQUESTED+. + # Checks if the state is `DELETE_REQUESTED`. def delete_requested? return false if state.nil? "DELETE_REQUESTED".casecmp(state).zero? end ## - # Checks if the state is +DELETE_IN_PROGRESS+. + # Checks if the state is `DELETE_IN_PROGRESS`. def delete_in_progress? return false if state.nil? "DELETE_IN_PROGRESS".casecmp(state).zero? end ## - # Updates the project in a single API call. See Project::Updater + # Updates the project in a single API call. See {Project::Updater} # - # === Example + # @yield [project] a block yielding a project delegate + # @yieldparam [Project::Updater] project the delegate object for updating + # the project # + # @example # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -265,12 +265,11 @@ ## # Reloads the project (with updated state) from the Google Cloud Resource # Manager service. # - # === Example - # + # @example # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -289,14 +288,14 @@ ## # Marks the project for deletion. This method will only affect the project # if the following criteria are met: # # * The project does not have a billing account associated with it. - # * The project has a lifecycle state of +ACTIVE+. - # * This method changes the project's lifecycle state from +ACTIVE+ to - # +DELETE_REQUESTED+. The deletion starts at an unspecified time, at - # which point the lifecycle state changes to +DELETE_IN_PROGRESS+. + # * The project has a lifecycle state of `ACTIVE`. + # * This method changes the project's lifecycle state from `ACTIVE` to + # `DELETE_REQUESTED`. The deletion starts at an unspecified time, at + # which point the lifecycle state changes to `DELETE_IN_PROGRESS`. # # Until the deletion completes, you can check the lifecycle state by # calling #reload!, or by retrieving the project with Manager#project. The # project remains visible to Manager#project and Manager#projects, but # cannot be updated. @@ -304,12 +303,11 @@ # After the deletion completes, the project is not retrievable by the # Manager#project and Manager#projects methods. # # The caller must have modify permissions for this project. # - # === Example - # + # @example # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -328,18 +326,17 @@ end end ## # Restores the project. You can only use this method for a project that - # has a lifecycle state of +DELETE_REQUESTED+. After deletion starts, as - # indicated by a lifecycle state of +DELETE_IN_PROGRESS+, the project + # has a lifecycle state of `DELETE_REQUESTED`. After deletion starts, as + # indicated by a lifecycle state of `DELETE_IN_PROGRESS`, the project # cannot be restored. # # The caller must have modify permissions for this project. # - # === Example - # + # @example # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -357,40 +354,32 @@ fail ApiError.from_response(resp) end end ## - # Gets the {Cloud IAM}[https://cloud.google.com/iam/] access control - # policy. See {Managing - # Policies}[https://cloud.google.com/iam/docs/managing-policies] - # for more information. + # Gets the [Cloud IAM](https://cloud.google.com/iam/) access control + # policy. Returns a hash that conforms to the following structure: # - # === Parameters - # - # +force+:: - # Force load the latest policy when +true+. Otherwise the policy will be - # memoized to reduce the number of API calls made. The default is - # +false+. (+Boolean+) - # - # === Returns - # - # A hash that conforms to the following structure: - # # { # "bindings" => [{ # "role" => "roles/viewer", # "members" => ["serviceAccount:your-service-account"] # }], # "version" => 0, # "etag" => "CAE=" # } # - # === Examples + # @see https://cloud.google.com/iam/docs/managing-policies Managing + # Policies # - # By default the policy values are memoized to reduce the number of API - # calls made. + # @param [Boolean] force Force load the latest policy when `true`. + # Otherwise the policy will be memoized to reduce the number of API + # calls made. The default is `false`. # + # @return [Hash] See description + # + # @example Policy values are memoized by default: # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -398,20 +387,19 @@ # # puts policy["bindings"] # puts policy["version"] # puts policy["etag"] # - # Use the +force+ option to retrieve the latest policy from the service. - # + # @example Use the `force` option to retrieve the latest policy: # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" # policy = project.policy force: true # - def policy force: nil + def policy force: false @policy = nil if force @policy ||= begin ensure_connection! resp = connection.get_policy project_id fail ApiError.from_response(resp) unless resp.success? @@ -420,29 +408,27 @@ policy end end ## - # Sets the {Cloud IAM}[https://cloud.google.com/iam/] access control - # policy. See {Managing - # Policies}[https://cloud.google.com/iam/docs/managing-policies] - # for more information. + # Sets the [Cloud IAM](https://cloud.google.com/iam/) access control + # policy. # - # === Parameters + # @see https://cloud.google.com/iam/docs/managing-policies Managing + # Policies # - # +new_policy+:: - # A hash that conforms to the following structure: + # @param [String] new_policy A hash that conforms to the following + # structure: # # { # "bindings" => [{ # "role" => "roles/viewer", # "members" => ["serviceAccount:your-service-account"] # }] # } # - # === Example - # + # @example # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -465,28 +451,23 @@ fail ApiError.from_response(resp) end end ## - # Tests the specified permissions against the {Cloud - # IAM}[https://cloud.google.com/iam/] access control policy. See - # {Managing Policies}[https://cloud.google.com/iam/docs/managing-policies] - # for more information. + # Tests the specified permissions against the [Cloud + # IAM](https://cloud.google.com/iam/) access control policy. # - # === Parameters + # @see https://cloud.google.com/iam/docs/managing-policies Managing + # Policies # - # +permissions+:: - # The set of permissions to check access for. Permissions with wildcards - # (such as +*+ or +storage.*+) are not allowed. - # (String or Array of Strings) + # @param [String, Array<String>] permissions The set of permissions to + # check access for. Permissions with wildcards (such as `*` or + # `storage.*`) are not allowed. # - # === Returns + # @return [Array<String>] The permissions that have access # - # The permissions that have access. (Array of Strings) - # - # === Example - # + # @example # require "gcloud" # # gcloud = Gcloud.new # resource_manager = gcloud.resource_manager # project = resource_manager.project "tokyo-rain-123" @@ -505,11 +486,11 @@ fail ApiError.from_response(resp) end end ## - # New Change from a Google API Client object. - def self.from_gapi gapi, connection #:nodoc: + # @private New Change from a Google API Client object. + def self.from_gapi gapi, connection new.tap do |p| p.gapi = gapi p.connection = connection end end