aviator 0.0.5 → 0.0.6

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MWFjN2RhZjk0MjY3Yjc3MzI4YzM2ZTAyZGUxYTY1YTdiN2FjNmY2NA==
+    ODAxM2VmMWQ3YzJmNWE1ZTdkODQ5Yzc4NGI2NDljNTdhODA1ZGM3NQ==
   data.tar.gz: !binary |-
-    MzE0YzgxYjE3YTU5ZTg0ZTNlM2NmYTExM2NmMWU4Nzk1MjAxNDNmNQ==
+    Y2RjMzE0NmU2ZmRjMTdmYTE5MzhkODFmNDM1OWY4YWJkNDJmMWM1Mg==
 SHA512:
   metadata.gz: !binary |-
-    MmM2MWJlMGExNjU0OWNjOWUyZDY2ZmU4ZWEyMzE2Y2U0ODVkY2QxN2Y1MjU3
-    MjQ3NTgzYWI2MzEzYmI0N2YzZTZlN2I2NmJhZWMzMTMxNWJjMGZkZTNkMTQ1
-    NTkyZTU2YTZhYTc5OWIzNGFkYTQxZjE3YjA1ZGJhNDhlNjE2NmU=
+    YWQ3MDE0MGIzNWZhMzlkNzEzNGRjYjc0OGQ0NzRhNWY4MmU4NjMzMGRhNjgz
+    ODUwZDQ0MDI0MzdhMTcxZWRmNzViZTQ3MDgzNTc3NzU1YThjNzY1NDE0Yzcw
+    YmVjNmJmMjJlZTQ0NmEyYzkxNDZiOGM0NjAyMDUzMThhYTkyOGE=
   data.tar.gz: !binary |-
-    YjMxYTgwYzI1MDM2NDdkNzg5NWYxMTY5MjljMDE5OTI4Y2M2OWViYTE5M2Jk
-    OWJmMTNmODdiYmFmYjg4Mzc0MmZjMTI0NzA4MDQ2ZTJiMDIwZjI4NGRiMjQz
-    MzlmM2YxY2Q1OTk4ZDA2YjU5MzczMWIxNWUxOWQ4NWZjNDQzNmI=
+    ZDBjY2EwMjhlYTBiYTcxMTc0ZjZjNzkzNDA1Y2UwYTRkNWZiODZiN2E5Zjk0
+    MTdiZjc4Mzk1MmNmMmExNTEyNWVmYjExZWVhODE3ZjRiMTM3OTEwMGNlNzc5
+    NDlmMWQ4ODQyMzRiNzc3NWQwMjhhNjEwMTU1OTg5YTg0MDVjZjA=

data/README.md

@@ -1,8 +1,6 @@
 ![Aviator](https://raw.github.com/aviator/www/gh-pages/images/logo-small.png)
 <br/>A lightweight library for communicating with the OpenStack API.
 
-## Project Stats
-
 [![Build Status](https://travis-ci.org/aviator/aviator.png?branch=master)](https://travis-ci.org/aviator/aviator)
 [![Coverage Status](https://coveralls.io/repos/aviator/aviator/badge.png?branch=master)](https://coveralls.io/r/aviator/aviator?branch=master)
 [![Code Climate](https://codeclimate.com/github/aviator/aviator.png)](https://codeclimate.com/github/aviator/aviator)
@@ -10,205 +8,4 @@
 [![Dependency Status](https://gemnasium.com/aviator/aviator.png)](https://gemnasium.com/aviator/aviator)
 
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'aviator'
-
-Or if you want to live on the edge:
-
-    gem 'aviator', :git => 'git@github.com:aviator/aviator.git', :branch => 'develop'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install aviator
-
-## Usage
-
-```ruby
-require 'aviator'
-
-# Create a new session. See 'Configuration' below for the config file format.
-session = Aviator::Session.new(
-            config_file: 'path/to/aviator.yml',
-            environment: :production,
-            log_file:    'path/to/aviator.log'
-          )
-
-# Authenticate against the auth service specified in :config_file. If no 
-# credentials are available in the config file, this line will throw an error.
-session.authenticate
-
-# You can re-authenticate anytime. Note that this creates a new token in the 
-# underlying environment while the old token is discarded by the Session object.
-# Be aware of this fact as it might unnecessarily generate too many tokens.
-#
-# Notice how you can override the credentials in the config file. Also note that
-# the keys used below (:username, :password, :tenantName) match the name as 
-# indicated in the official OpenStack documentation.
-session.authenticate do |credentials|
-  credentials[:username]   = myusername
-  credentials[:password]   = mypassword
-  credentials[:tenantName] = tenantName
-end
-
-# Serialize the session information for caching. The output is in plaintext JSON which
-# contains sensitive information. You are responsible for securing that.
-str = session.dump
-
-# Create a new Session object from a session dump. This DOES NOT create a new token. 
-# If you employed any form of encryption on the string, make sure to decrypt it first!
-session = Aviator::Session.load(str)
-
-# In some instances, Session::load is inefficient because it creates a new session object
-# each time. In a web app environment, for instance, having to destroy and recreate the
-# session object can take its toll on performance. In such a scenario, use Session#load
-# (instance method, as opposed to class method). This will 'infect' an already existing
-# session object with the supplied session dump and return itself instead of creating
-# a brand new session object.
-session.load(other_session_dump)
-
-# Depending on how old the loaded session dump is, its session data may already be expired. 
-# Check if it's still current by calling Session#validate and reauthenticate as needed.
-#
-# IMPORTANT: The validator must be defined in the config file and it must refer to the
-# name of a request that is known to Aviator. See 'Configuration' below for examples
-session.authenticate unless session.validate
-
-# If you want the newly created session to log its output, make sure to indicate it on load
-session = Aviator::Session.load(str, log_file: 'path/to/aviator.log')
-
-# Get a handle to the Identity Service.
-keystone = session.identity_service
-
-# Create a new tenant
-response = keystone.request(:create_tenant) do |params|
-  params[:name]        = 'Project'
-  params[:description] = 'My Project'
-  params[:enabled]     = true
-end
-
-# Aviator uses parameter names as defined in the official OpenStack API doc. You can 
-# also access the params via dot notation (e.g. params.description) or by using a string
-# for a hash key (e.g. params['description']). However, keep in mind that OpenStack
-# parameters that have dashes and other characters that are not valid for method names
-# and symbols can only be expressed as strings. E.g. params['changes-since']
-
-
-# Be explicit about the endpoint type. Useful in those rare instances when
-# the same request name means differently depending on the endpoint type.
-# For example, in OpenStack, :list_tenants will return only the tenants the
-# user is a member of in the public endpoint whereas the admin endpoint will
-# return all tenants in the system.
-response = keystone.request(:list_tenants, endpoint_type: 'admin')
-```
-
-## Configuration
-
-The configuration file is a simple YAML file that can have one or more environment definitions.
-
-```
-production:
-  provider: openstack
-  auth_service:
-    name:        identity
-    host_uri:    http://my.openstackenv.org:5000
-    request:     create_token
-    validator:   list_tenants   # Request to make for validating the session
-    api_version: v2             # Optional if version is indicated in host_uri
-  auth_credentials:
-    username:   admin
-    password:   mypassword
-    tenantName: myproject
-
-development_1:
-  provider: openstack
-  auth_service:
-    name:      identity
-    host_uri:  http://devstack:5000/v2.0
-    request:   create_token
-    validator: list_tenants
-  auth_credentials:
-    tokenId:    2c963f5512d067b24fdc312707c80c7a6d3d261b
-    tenantName: admin
-
-development_2:
-  provider: openstack
-  auth_service:
-    name:      identity
-    host_uri:  http://devstack:5000/v2.0
-    request:   create_token
-    validator: list_tenants
-  auth_credentials:
-    username: admin
-    password: mypassword
-    tenantName: myproject
-```
-
-A note on the validator: it can be any request as long as
-
-1. It is defined in Aviator
-1. Does not require any parameters
-1. It returns an HTTP status 200 or 203 to indicate auth info validity.
-1. It returns any other HTTP status to indicate that the auth info is invalid.
-
-## CLI tools
-
-List available providers. Includes only OpenStack for now.
-
-```bash
-$ aviator describe
-```
-
-List available services for OpenStack.
-
-```bash
-$ aviator describe openstack
-```
-
-List available requests for Keystone
-
-```bash
-$ aviator describe openstack identity
-```
-
-Describe Keystone's create_tenant request
-
-```bash
-$ aviator describe openstack identity v2 admin create_tenant
-```
-
-The last command above will display:
-
-```bash
-Request: create_tenant
-
-Parameters:
-  (required) description
-  (required) enabled
-  (required) name
-
-Sample Code:
-  session.identity_service.request(:create_tenant, endpoint_type: 'admin') do |params|
-     params['name'] = value
-     params['description'] = value
-     params['enabled'] = value
-  end
-
-Links:
-  documentation:
-    http://docs.openstack.org/api/openstack-identity-service/2.0/content/
-```
-  
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+<a href="http://aviator.github.io/www/">Usage and Installation</a>

data/aviator.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.email         = ["mmaglana@gmail.com"]
   spec.description   = %q{ A lightweight Ruby library for the OpenStack API }
   spec.summary       = %q{ A lightweight Ruby library for the OpenStack API }
-  spec.homepage      = "https://github.com/aviator/aviator"
+  spec.homepage      = "http://aviator.github.io/www/"
   spec.license       = "MIT"
 
   spec.files         = `git ls-files`.split($/)
@@ -21,7 +21,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'faraday', '~> 0.8.0'
   spec.add_dependency 'activesupport', '>= 3.2.8'
   spec.add_dependency 'thor', '~> 0.18.1'
-  
+  spec.add_dependency 'terminal-table', '>= 1.4.5'
+
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
   spec.add_development_dependency 'rb-fsevent', '~> 0.9.0'

data/lib/aviator/core/cli/describer.rb

@@ -1,37 +1,25 @@
 module Aviator
-  
-  module Describer
 
-    def self.describe_aviator
-      provider_names = Pathname.new(__FILE__)
-                        .join('..', '..', '..')
-                        .children
-                        .select{|c| c.directory? && c.basename.to_s != 'core' }
-                        .map{|c| c.basename.to_s }
+  class Describer
 
+    def self.describe_aviator
       str = "Available providers:\n"
 
       provider_names.each do |provider_name|
         str << "  #{ provider_name }\n"
       end
-      
+
       str
     end
 
 
     def self.describe_provider(provider_name)
-      service_names = Pathname.new(__FILE__)
-                        .join('..', '..', '..', provider_name)
-                        .children
-                        .select{|c| c.directory? }
-                        .map{|c| c.basename.to_s }
-
       str = "Available services for #{ provider_name }:\n"
 
-      service_names.each do |service_name|
+      service_names(provider_name).each do |service_name|
         str << "  #{ service_name }\n"
       end
-      
+
       str
     end
 
@@ -40,56 +28,119 @@ module Aviator
       service = Aviator::Service.new provider: provider_name, service: service_name
       request_class = "Aviator::#{ provider_name.camelize }::#{ service_name.camelize }::"\
                       "#{ api_version.camelize }::#{ endpoint_type.camelize }::#{ request_name.camelize }".constantize
-                      
-      str = "Request: #{ request_name }\n\n"
-      
-      str << "Parameters:\n"
-
-      params = request_class.optional_params.map{|p| [p, :optional]} + 
-               request_class.required_params.map{|p| [p, :required]}
-      
-      params.sort{|a,b| a[0].to_s <=> b[0].to_s }.each do |param|
-        str << "  (#{ param[1].to_s }) #{ param[0] }\n"
+
+      display = "Request: #{ request_name }\n"
+
+
+      # Build the parameters
+      params = request_class.optional_params.map{|p| [p, false]} +
+               request_class.required_params.map{|p| [p, true]}
+
+      aliases = request_class.param_aliases
+
+      if params.length > 0
+        display << "\n"
+
+        headings = ['NAME', 'REQUIRED']
+
+        headings << 'ALIAS' if aliases.length > 0
+
+        rows = []
+        params.sort{|a,b| a[0].to_s <=> b[0].to_s }.each do |param|
+          row = [ param[0], param[1] ? 'Y' : 'N' ]
+
+          if aliases.length > 0
+            row << (aliases.find{|a,p| p == param[0] } || [''])[0]
+          end
+
+          rows << row
+        end
+
+        widths = [
+          rows.map{|row| row[0].length }.max,
+          rows.map{|row| row[1].length }.max
+        ]
+
+        widths << rows.map{|row| row[2].length }.max if aliases.length > 0
+
+        table = Terminal::Table.new(headings: headings, rows: rows)
+
+        table.align_column(1, :center)
+
+        display << "Parameters:\n"
+        display << " " + table.to_s.split("\n").join("\n ")
+        display << "\n"
       end
-      
-      str << "\nSample Code:\n"
 
-      str << "  session.#{ service_name }_service.request(:#{ request_name }, endpoint_type: '#{ request_class.endpoint_type }')"
-      if params
-        str << " do |params|\n"
+
+      # Build the sample code
+      display << "\nSample Code:\n"
+
+      display << "  session.#{ service_name }_service.request(:#{ request_name })"
+
+      if params && params.length > 0
+        display << " do |params|\n"
         params.each do |pair|
-          str << "     params['#{ pair[0] }'] = value\n"
+          display << "    params.#{ (aliases.find{|a,p| p == pair[0] } || pair)[0] } = value\n"
         end
-        str << "  end\n"
+        display << "  end"
       end
-      
-      if request_class.links
-        str << "\nLinks:\n"
-        
+
+      display << "\n"
+
+
+      # Build the links
+      if request_class.links && request_class.links.length > 0
+        display << "\nLinks:\n"
+
         request_class.links.each do |link|
-          str << "  #{ link[:rel] }:\n"
-          str << "    #{ link[:href] }\n"
+          display << "  #{ link[:rel] }:\n"
+          display << "    #{ link[:href] }\n"
         end
       end
-      
-      str
+
+      display
     end
 
 
     def self.describe_service(provider_name, service_name)
-      service = Aviator::Service.new(provider: provider_name, service: service_name)
-      klasses = service.request_classes
-      
       str = "Available requests for #{ provider_name } #{ service_name }_service:\n"
 
-      klasses.each do |klass|
+      request_classes(provider_name, service_name).each do |klass|
         str << "  #{ klass.api_version } #{ klass.endpoint_type } #{ klass.name.split('::').last.underscore }\n"
       end
-      
+
       str
     end
 
 
+    class <<self
+      private
+
+      def provider_names
+        Pathname.new(__FILE__)
+          .join('..', '..', '..')
+          .children
+          .select{|c| c.directory? && c.basename.to_s != 'core' }
+          .map{|c| c.basename.to_s }
+      end
+
+
+      def request_classes(provider_name, service_name)
+        service = Aviator::Service.new(provider: provider_name, service: service_name)
+        service.request_classes
+      end
+
+
+      def service_names(provider_name)
+        Pathname.new(__FILE__)
+          .join('..', '..', '..', provider_name)
+          .children
+          .select{|c| c.directory? }
+          .map{|c| c.basename.to_s }
+      end
+    end
+
   end
-  
+
 end

data/lib/aviator/core/cli.rb

@@ -1 +1,2 @@
+require "terminal-table"
 require "aviator/core/cli/describer"

data/lib/aviator/core/request.rb

@@ -53,7 +53,7 @@ module Aviator
     def links
       self.class.links
     end
-    
+
 
     def optional_params
       self.class.optional_params
@@ -83,7 +83,7 @@ module Aviator
     def querystring?
       self.class.querystring?
     end
-    
+
 
     def url?
       self.class.url?
@@ -121,18 +121,23 @@ module Aviator
       def headers?
         instance_methods.include? :headers
       end
-            
-      
+
+
       def links
         @links ||= []
       end
 
 
+      def param_aliases
+        @param_aliases ||= {}
+      end
+
+
       def params_class
         all_params = required_params + optional_params
 
-        if all_params.length > 0
-          @params_class ||= Struct.new(*all_params)
+        if all_params.length > 0 && @params_class.nil?
+          @params_class = build_params_class(all_params, self.param_aliases)
         end
 
         @params_class
@@ -147,12 +152,12 @@ module Aviator
       def querystring?
         instance_methods.include? :querystring
       end
-      
+
 
       def required_params
         @required_params ||= []
       end
-      
+
 
       def url?
         instance_methods.include? :url
@@ -162,6 +167,34 @@ module Aviator
       private
 
 
+      def build_params_class(all_params, param_aliases)
+        Struct.new(*all_params) do
+          alias :param_getter :[]
+          alias :param_setter :[]=
+
+          define_method :[] do |key|
+            key = param_aliases[key.to_sym] if param_aliases.keys.include? key.to_sym
+            param_getter(key)
+          end
+
+          define_method :[]= do |key, value|
+            key = param_aliases[key.to_sym] if param_aliases.keys.include? key.to_sym
+            param_setter(key, value)
+          end
+
+          param_aliases.each do |param_alias, param_name|
+            define_method param_alias do
+              param_getter(param_name)
+            end
+
+            define_method "#{ param_alias }=" do |value|
+              param_setter(param_name, value)
+            end
+          end
+        end
+      end
+
+
       def link(rel, href)
         links << { rel: rel, href: href }
       end
@@ -176,12 +209,16 @@ module Aviator
           self.class.send(attr_name)
         end
       end
-      
+
 
       def param(param_name, opts={})
         opts  = opts.with_indifferent_access
         list  = (opts[:required] == false ? optional_params : required_params)
         list << param_name unless optional_params.include?(param_name)
+
+        if opts[:alias]
+          self.param_aliases[opts[:alias]] = param_name
+        end
       end
 
     end

data/lib/aviator/core/request_builder.rb

@@ -1,37 +1,89 @@
 module Aviator
 
-  class << self
-    
-    def define_request(request_name, &block)
-      class_obj = Class.new(Request, &block)
-      
-      set_class_name(
-        Aviator,
-        class_obj,
-        
-        class_obj.provider,
-        class_obj.service,
-        class_obj.api_version,
-        class_obj.endpoint_type,
-        request_name
-      )
+  class BaseRequestNotFoundError < StandardError
+    attr_reader :base_request_hierarchy
+
+    def initialize(base_hierarchy)
+      @base_request_hierarchy = base_hierarchy
+      super("#{ base_request_hierarchy } could not be found!")
     end
-    
-    
-    private    
-    
-    def set_class_name(base, obj, *hierarchy)
-      const_name = hierarchy.shift.to_s.camelize
-
-      const = if base.const_defined?(const_name, false)
-                base.const_get(const_name, false)
-              else
-                base.const_set(const_name, (hierarchy.empty? ? obj : Module.new))
-              end
-      
-      hierarchy.empty? ? const : set_class_name(const, obj, *hierarchy)
+  end
+
+
+  class RequestAlreadyDefinedError < StandardError
+    attr_reader :namespace,
+                :request_name
+
+    def initialize(namespace, request_name)
+      @namespace = namespace
+      @request_name = request_name
+      super("#{ namespace }::#{ request_name } is already defined")
     end
-    
+  end
+
+
+  class RequestBuilder
+
+    class << self
+
+      def define_request(root_namespace, request_name, options, &block)
+        base_klass = get_request_class(root_namespace, options[:inherit])
+
+        klass = Class.new(base_klass, &block)
+
+        namespace_arr = [
+          klass.provider,
+          klass.service,
+          klass.api_version,
+          klass.endpoint_type
+        ]
+
+        namespace = namespace_arr.inject(root_namespace) do |namespace, sym|
+          const_name = sym.to_s.camelize
+          namespace.const_set(const_name, Module.new) unless namespace.const_defined?(const_name, false)
+          namespace.const_get(const_name, false)
+        end
+
+        klassname = request_name.to_s.camelize
+
+        if namespace.const_defined?(klassname, false)
+          raise RequestAlreadyDefinedError.new(namespace, klassname)
+        end
+
+        namespace.const_set(klassname, klass)
+      end
+
+
+      def get_request_class(root_namespace, request_class_arr)
+        request_class_arr.inject(root_namespace) do |namespace, sym|
+          namespace.const_get(sym.to_s.camelize, false)
+        end
+      rescue NameError => e
+        arr = ['..', '..'] + request_class_arr
+        arr[-1,1] = arr.last.to_s + '.rb'
+        path = Pathname.new(__FILE__).join(*arr.map{|i| i.to_s }).expand_path
+
+        if path.exist?
+          require path
+          request_class_arr.inject(root_namespace) do |namespace, sym|
+            namespace.const_get(sym.to_s.camelize, false)
+          end
+        else
+          raise BaseRequestNotFoundError.new(request_class_arr)
+        end
+      end
+
+    end
+
+  end
+
+
+  class << self
+
+    def define_request(request_name, options={ inherit: [:request] }, &block)
+      RequestBuilder.define_request self, request_name, options, &block
+    end
+
   end # class << self
 
 end