td-client 0.8.68 → 0.8.69

data/lib/td/client/api/server_status.rb

@@ -6,6 +6,7 @@ module ServerStatus
   ##
 
   # => status:String
+  # @return [String] HTTP status code
   def server_status
     code, body, res = get('/v3/system/server_status')
     if code != "200"

data/lib/td/client/api/table.rb

@@ -5,7 +5,8 @@ module Table
   ## Table API
   ##
 
-  # => {name:String => [type:Symbol, count:Integer]}
+  # @param [String] db
+  # @return [Array]
   def list_tables(db)
     code, body, res = get("/v3/table/list/#{e db}")
     if code != "200"
@@ -31,6 +32,10 @@ module Table
     return result
   end
 
+  # @param [String] db
+  # @param [String] table
+  # @param [String] type
+  # @return [true]
   def create_log_or_item_table(db, table, type)
     code, body, res = post("/v3/table/create/#{e db}/#{e table}/#{type}")
     if code != "200"
@@ -40,17 +45,28 @@ module Table
   end
   private :create_log_or_item_table
 
-  # => true
+  # @param [String] db
+  # @param [String] table
+  # @return [true]
   def create_log_table(db, table)
     create_table(db, table, :log)
   end
 
-  # => true
+  # @param [String] db
+  # @param [String] table
+  # @param [String] primary_key
+  # @param [String] primary_key_type
+  # @return [true]
   def create_item_table(db, table, primary_key, primary_key_type)
     params = {'primary_key' => primary_key, 'primary_key_type' => primary_key_type}
     create_table(db, table, :item, params)
   end
 
+  # @param [String] db
+  # @param [String] table
+  # @param [String] type
+  # @param [Hash] params
+  # @return [true]
   def create_table(db, table, type, params={})
     schema = schema.to_s
     code, body, res = post("/v3/table/create/#{e db}/#{e table}/#{type}", params)
@@ -61,7 +77,10 @@ module Table
   end
   private :create_table
 
-  # => true
+  # @param [String] db
+  # @param [String] table1
+  # @param [String] table2
+  # @return [true]
   def swap_table(db, table1, table2)
     code, body, res = post("/v3/table/swap/#{e db}/#{e table1}/#{e table2}")
     if code != "200"
@@ -70,7 +89,10 @@ module Table
     return true
   end
 
-  # => true
+  # @param [String] db
+  # @param [String] table
+  # @param [String] schema_json
+  # @return [true]
   def update_schema(db, table, schema_json)
     code, body, res = post("/v3/table/update-schema/#{e db}/#{e table}", {'schema'=>schema_json})
     if code != "200"
@@ -79,6 +101,10 @@ module Table
     return true
   end
 
+  # @param [String] db
+  # @param [String] table
+  # @param [Fixnum] expire_days
+  # @return [true]
   def update_expire(db, table, expire_days)
     code, body, res = post("/v3/table/update/#{e db}/#{e table}", {'expire_days'=>expire_days})
     if code != "200"
@@ -87,7 +113,9 @@ module Table
     return true
   end
 
-  # => type:Symbol
+  # @param [String] db
+  # @param [String] table
+  # @return [Symbol]
   def delete_table(db, table)
     code, body, res = post("/v3/table/delete/#{e db}/#{e table}")
     if code != "200"
@@ -98,6 +126,13 @@ module Table
     return type
   end
 
+  # @param [String] db
+  # @param [String] table
+  # @param [Fixnum] count
+  # @param [Fixnum] to
+  # @param [Fixnum] from
+  # @param [Proc] block
+  # @return [Array, nil]
   def tail(db, table, count, to, from, &block)
     params = {'format' => 'msgpack'}
     params['count'] = count.to_s if count

data/lib/td/client/api/to_hash_struct.rb

@@ -0,0 +1,82 @@
+class TreasureData::API
+  class ToHashStruct < Struct
+    module ClassModule
+      def parse_json(body)
+        begin
+          js = JSON.load(body)
+        rescue
+          raise "Unexpected API response: #{$!}"
+        end
+        unless js.is_a?(Hash)
+          raise "Unexpected API response: #{body}"
+        end
+        js
+      end
+
+      def from_json(json)
+        from_hash(parse_json(json))
+      end
+
+      def from_hash(hash)
+        return new if hash.nil?
+        new(*members.map { |sym|
+          v = hash[sym] || hash[sym.to_s]
+          model.key?(sym) ? model[sym].from_hash(v) : v
+        })
+      end
+
+      def model_property(key, klass)
+        model[key.to_sym] = klass
+      end
+
+      def model
+        @model ||= {}
+      end
+    end
+    extend ClassModule
+
+    def to_h
+      self.class.members.inject({}) { |r, e|
+        v = obj_to_h(self[e])
+        r[e.to_s] = v unless v.nil?
+        r
+      }
+    end
+
+    def to_json
+      to_h.to_json
+    end
+
+    def validate
+      validate_self
+      values.each do |v|
+        v.validate if v.is_a?(ToHashStruct)
+      end
+      self
+    end
+
+    def validate_self
+      # define as required
+    end
+
+  private
+
+    def validate_presence_of(key)
+      unless self.send(key)
+        raise ArgumentError.new("#{key} required")
+      end
+    end
+
+    def obj_to_h(obj)
+      if obj.nil?
+        nil
+      elsif Array === obj
+        obj.map { |e| obj_to_h(e) }
+      elsif obj.respond_to?(:to_h)
+        obj.to_h
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/td/client/api/user.rb

@@ -5,7 +5,9 @@ module User
   ## User API
   ##
 
-  # apikey:String
+  # @param [String] user
+  # @param [String] password
+  # @return [String] API key
   def authenticate(user, password)
     code, body, res = post("/v3/user/authenticate", {'user'=>user, 'password'=>password})
     if code != "200"
@@ -20,7 +22,7 @@ module User
     return apikey
   end
 
-  # => [[name:String,organization:String,[user:String]]
+  # @return [Array]
   def list_users
     code, body, res = get("/v3/user/list")
     if code != "200"
@@ -35,7 +37,11 @@ module User
     return result
   end
 
-  # => true
+  # @param [String] name
+  # @param [String] org
+  # @param [String] email
+  # @param [String] password
+  # @return [true]
   def add_user(name, org, email, password)
     params = {'organization'=>org, :email=>email, :password=>password}
     code, body, res = post("/v3/user/add/#{e name}", params)
@@ -45,7 +51,8 @@ module User
     return true
   end
 
-  # => true
+  # @param [String] user
+  # @return [true]
   def remove_user(user)
     code, body, res = post("/v3/user/remove/#{e user}")
     if code != "200"
@@ -54,7 +61,9 @@ module User
     return true
   end
 
-  # => true
+  # @param [String] user
+  # @param [String] email
+  # @return [true]
   def change_email(user, email)
     params = {'email' => email}
     code, body, res = post("/v3/user/email/change/#{e user}", params)
@@ -64,7 +73,8 @@ module User
     return true
   end
 
-  # => [apikey:String]
+  # @param [String] user
+  # @return [Array<String>] API keys as array
   def list_apikeys(user)
     code, body, res = get("/v3/user/apikey/list/#{e user}")
     if code != "200"
@@ -74,7 +84,8 @@ module User
     return js['apikeys']
   end
 
-  # => true
+  # @param [String] user
+  # @return [true]
   def add_apikey(user)
     code, body, res = post("/v3/user/apikey/add/#{e user}")
     if code != "200"
@@ -83,7 +94,9 @@ module User
     return true
   end
 
-  # => true
+  # @param [String] user
+  # @param [String] apikey
+  # @return [true]
   def remove_apikey(user, apikey)
     params = {'apikey' => apikey}
     code, body, res = post("/v3/user/apikey/remove/#{e user}", params)
@@ -93,7 +106,9 @@ module User
     return true
   end
 
-  # => true
+  # @param [String] user
+  # @param [String] password
+  # @return [true]
   def change_password(user, password)
     params = {'password' => password}
     code, body, res = post("/v3/user/password/change/#{e user}", params)
@@ -103,7 +118,9 @@ module User
     return true
   end
 
-  # => true
+  # @param [String] old_password
+  # @param [String] password
+  # @return [true]
   def change_my_password(old_password, password)
     params = {'old_password' => old_password, 'password' => password}
     code, body, res = post("/v3/user/password/change", params)

data/lib/td/client/compat_gzip_reader.rb

@@ -2,6 +2,9 @@
 methods = Zlib::GzipReader.public_instance_methods
 if !methods.include?(:readpartial) && !methods.include?('readpartial')
   class Zlib::GzipReader
+    # @param [Fixnum] size
+    # @param [IO] out
+    # @return [String]
     def readpartial(size, out=nil)
       o = read(size)
       if o

data/lib/td/client/model.rb

@@ -3,14 +3,24 @@ module TreasureData
 
 
 class Model
+  # @param [TreasureData::Client] client
   def initialize(client)
     @client = client
   end
 
+  # @!attribute [r] client
+  # @return [TreasureData::Client] client
   attr_reader :client
 end
 
 class Account < Model
+  # @param [TreasureData::Client] client
+  # @param [String] account_id
+  # @param [Fixnum] plan
+  # @param [Fixnum] storage_size
+  # @param [Fixnum] guaranteed_cores
+  # @param [Fixnum] maximum_cores
+  # @param [String] created_at
   def initialize(client, account_id, plan, storage_size=nil, guaranteed_cores=nil, maximum_cores=nil, created_at=nil)
     super(client)
     @account_id = account_id
@@ -21,12 +31,19 @@ class Account < Model
     @created_at = created_at
   end
 
+  # @!attribute [r] account_id
+  # @!attribute [r] plan
+  # @!attribute [r] storage_size
+  # @!attribute [r] guaranteed_cores
+  # @!attribute [r] maximum_cores
   attr_reader :account_id, :plan, :storage_size, :guaranteed_cores, :maximum_cores
 
+  # @return <Time, nil>
   def created_at
     @created_at && !@created_at.empty? ? Time.parse(@created_at) : nil
   end
 
+  # @return <String>
   def storage_size_string
     if @storage_size <= 1024 * 1024
       return "0.0 GB"
@@ -44,6 +61,14 @@ class Database < Model
   PERMISSIONS = [:administrator, :full_access, :import_only, :query_only]
   PERMISSION_LIST_TABLES = [:administrator, :full_access]
 
+  # @param [TreasureData::Client] client
+  # @param [String] db_name
+  # @param [Array<Table>] tables
+  # @param [Fixnum] count
+  # @param [String] created_at
+  # @param [String] updated_at
+  # @param [String] org_name
+  # @param [String] permission
   def initialize(client, db_name, tables=nil, count=nil, created_at=nil, updated_at=nil, org_name=nil, permission=nil)
     super(client)
     @db_name = db_name
@@ -54,45 +79,62 @@ class Database < Model
     @permission = permission.to_sym
   end
 
+  # @!attribute [r] org_name
+  # @!attribute [r] permission
+  # @!attribute [r] count
   attr_reader :org_name, :permission, :count
 
+  # @return [String] db_name
   def name
     @db_name
   end
 
+  # @return [Array<Table>]
   def tables
     update_tables! unless @tables
     @tables
   end
 
+  # @param [String] name
+  # @return [true]
   def create_log_table(name)
     @client.create_log_table(@db_name, name)
   end
 
+  # @param [String] name
+  # @return [true]
   def create_item_table(name)
     @client.create_item_table(@db_name, name)
   end
 
+  # @param [String] table_name
+  # @return [Table]
   def table(table_name)
     @client.table(@db_name, table_name)
   end
 
+  # @return [Symbol]
   def delete
     @client.delete_database(@db_name)
   end
 
+  # @param [String] q
+  # @return [Job]
   def query(q)
     @client.query(@db_name, q)
   end
 
+  # @return [Time, nil]
   def created_at
     @created_at && !@created_at.empty? ? Time.parse(@created_at) : nil
   end
 
+  # @return [Time, nil]
   def updated_at
     @updated_at && !@updated_at.empty? ? Time.parse(@updated_at) : nil
   end
 
+  # @return [nil]
   def update_tables!
     @tables = @client.tables(@db_name)
     # provide Table objects with a reference to the parent Database to avoid
@@ -105,6 +147,20 @@ class Database < Model
 end
 
 class Table < Model
+  # @param [TreasureData::Client] client
+  # @param [String] db_name
+  # @param [String] table_name
+  # @param [String] type
+  # @param [String] schema
+  # @param [Fixnum] count
+  # @param [String] created_at
+  # @param [String] updated_at
+  # @param [Fixnum] estimated_storage_size
+  # @param [String] last_import
+  # @param [String] last_log_timestamp
+  # @param [Fixnum, String] expire_days
+  # @param [String] primary_key
+  # @param [String] primary_key_type
   def initialize(client, db_name, table_name, type, schema, count, created_at=nil, updated_at=nil, estimated_storage_size=nil, last_import=nil, last_log_timestamp=nil, expire_days=nil, primary_key=nil, primary_key_type=nil)
     super(client)
     @database = nil
@@ -123,65 +179,95 @@ class Table < Model
     @primary_key_type = primary_key_type
   end
 
+  # @!attribute [r] type
+  # @!attribute [r] db_name
+  # @!attribute [r] table_name
+  # @!attribute [r] schema
+  # @!attribute [r] count
+  # @!attribute [r] estimated_storage_size
+  # @!attribute [r] primary_key
+  # @!attribute [r] primary_key_type
   attr_reader :type, :db_name, :table_name, :schema, :count, :estimated_storage_size, :primary_key, :primary_key_type
 
   alias database_name db_name
   alias name table_name
 
+  # @param [String] database
   def database=(database)
     @database = database if database.instance_of?(Database)
   end
 
+  # @return [Time, nil]
   def created_at
     @created_at && !@created_at.empty? ? Time.parse(@created_at) : nil
   end
 
+  # @return [Time, nil]
   def updated_at
     @updated_at && !@updated_at.empty? ? Time.parse(@updated_at) : nil
   end
 
+  # @return [Time, nil]
   def last_import
     @last_import && !@last_import.empty? ? Time.parse(@last_import) : nil
   end
 
+  # @return [Time, nil]
   def last_log_timestamp
     @last_log_timestamp && !@last_log_timestamp.empty? ? Time.parse(@last_log_timestamp) : nil
   end
 
+  # @return [Fixnum, nil]
   def expire_days
     @expire_days ? @expire_days.to_i : nil
   end
 
+  # @return [Database]
   def database
     update_database! unless @database
     @database
   end
 
   # get the database's permission as if they were the table's
+  # @return [String]
   def permission
     database.permission
   end
 
+  # @return [String]
   def identifier
     "#{@db_name}.#{@table_name}"
   end
 
+  # @return [Symbol]
   def delete
     @client.delete_table(@db_name, @table_name)
   end
 
+  # @param [Fixnum] count
+  # @param [Fixnum] to
+  # @param [Fixnum] from
+  # @return [Array, nil]
   def tail(count, to=nil, from=nil)
     @client.tail(@db_name, @table_name, count, to, from)
   end
 
+  # @param [String] format
+  # @param [String, StringIO] stream
+  # @param [Fixnum] size
+  # @return [Float]
   def import(format, stream, size)
     @client.import(@db_name, @table_name, format, stream, size)
   end
 
+  # @param [String] storage_type
+  # @param [Hash] opts
+  # @return [Job]
   def export(storage_type, opts={})
     @client.export(@db_name, @table_name, storage_type, opts)
   end
 
+  # @return [String]
   def estimated_storage_size_string
     if @estimated_storage_size <= 1024*1024
       return "0.0 GB"
@@ -201,14 +287,21 @@ end
 
 class Schema
   class Field
+    # @param [String] name
+    # @param [String] type
     def initialize(name, type)
       @name = name
       @type = type
     end
+
+    # @!attribute [r] name
+    # @!attribute [r] type
     attr_reader :name
     attr_reader :type
   end
 
+  # @param [String] cols
+  # @return [Schema]
   def self.parse(cols)
     fields = cols.split(',').map {|col|
       name, type, *_ = col.split(':')
@@ -217,16 +310,23 @@ class Schema
     Schema.new(fields)
   end
 
+  # @param [Array] fields
   def initialize(fields=[])
     @fields = fields
   end
 
+  # @!attribute [r] fields
   attr_reader :fields
 
+  # @param [String] name
+  # @param [String] type
+  # @return [Array]
   def add_field(name, type)
     @fields << Field.new(name, type)
   end
 
+  # @param [Schema] schema
+  # @return [Schema]
   def merge(schema)
     nf = @fields.dup
     schema.fields.each {|f|
@@ -239,10 +339,13 @@ class Schema
     Schema.new(nf)
   end
 
+  # @return [Array<Field>]
   def to_json(*args)
     @fields.map {|f| [f.name, f.type] }.to_json(*args)
   end
 
+  # @param [Object] obj
+  # @return [self]
   def from_json(obj)
     @fields = obj.map {|f|
       Field.new(f[0], f[1])
@@ -260,6 +363,24 @@ class Job < Model
   STATUS_KILLED = "killed"
   FINISHED_STATUS = [STATUS_SUCCESS, STATUS_ERROR, STATUS_KILLED]
 
+  # @param [TreasureData::Client] client
+  # @param [String] job_id
+  # @param [String] type
+  # @param [String] query
+  # @param [Fixnum] status
+  # @param [String] url
+  # @param [Boolean] debug
+  # @param [String] start_at
+  # @param [String] end_at
+  # @param [String] cpu_time
+  # @param [String] result_size
+  # @param [Array] result
+  # @param [String] result_url
+  # @param [Array] hive_result_schema
+  # @param [Fixnum] priority
+  # @param [Fixnum] retry_limit
+  # @param [String] org_name
+  # @param [String] db_name
   def initialize(client, job_id, type, query, status=nil, url=nil, debug=nil, start_at=nil, end_at=nil, cpu_time=nil,
                  result_size=nil, result=nil, result_url=nil, hive_result_schema=nil, priority=nil, retry_limit=nil,
                  org_name=nil, db_name=nil)
@@ -282,6 +403,13 @@ class Job < Model
     @db_name = db_name
   end
 
+  # @!attribute [r] job_id
+  # @!attribute [r] type
+  # @!attribute [r] result_url
+  # @!attribute [r] priority
+  # @!attribute [r] retry_limit
+  # @!attribute [r] org_name
+  # @!attribute [r] db_name
   attr_reader :job_id, :type, :result_url
   attr_reader :priority, :retry_limit, :org_name, :db_name
 
@@ -293,51 +421,61 @@ class Job < Model
     # TODO
   end
 
+  # @return [String]
   def query
     update_status! unless @query || finished?
     @query
   end
 
+  # @return [String]
   def status
     update_status! unless @status || finished?
     @status
   end
 
+  # @return [String]
   def url
     update_status! unless @url || finished?
     @url
   end
 
+  # @return [Boolean]
   def debug
     update_status! unless @debug || finished?
     @debug
   end
 
+  # @return [Time, nil]
   def start_at
     update_status! unless @start_at || finished?
     @start_at && !@start_at.empty? ? Time.parse(@start_at) : nil
   end
 
+  # @return [Time, nil]
   def end_at
     update_status! unless @end_at || finished?
     @end_at && !@end_at.empty? ? Time.parse(@end_at) : nil
   end
 
+  # @return [String]
   def cpu_time
     update_status! unless @cpu_time || finished?
     @cpu_time
   end
 
+  # @return [Array]
   def hive_result_schema
     update_status! unless @hive_result_schema.instance_of? Array || finished?
     @hive_result_schema
   end
 
+  # @return [String]
   def result_size
     update_status! unless @result_size || finished?
     @result_size
   end
 
+  # @return [Array]
   def result
     unless @result
       return nil unless finished?
@@ -346,11 +484,17 @@ class Job < Model
     @result
   end
 
+  # @param [String] format
+  # @param [IO] io
+  # @param [Proc] block
+  # @return [nil, String]
   def result_format(format, io=nil, &block)
     return nil unless finished?
     @client.job_result_format(@job_id, format, io, &block)
   end
 
+  # @yield [result]
+  # @return [nil]
   def result_each_with_compr_size(&block)
     if @result
       @result.each(&block)
@@ -360,6 +504,8 @@ class Job < Model
     nil
   end
 
+  # @yield [result]
+  # @return [nil]
   def result_each(&block)
     if @result
       @result.each(&block)
@@ -369,31 +515,37 @@ class Job < Model
     nil
   end
 
+  # @return [Boolean]
   def finished?
     update_progress! unless @status
     FINISHED_STATUS.include?(@status)
   end
 
+  # @return [Boolean]
   def success?
     update_progress! unless @status
     @status == STATUS_SUCCESS
   end
 
+  # @return [Boolean]
   def error?
     update_progress! unless @status
     @status == STATUS_ERROR
   end
 
+  # @return [Boolean]
   def killed?
     update_progress! unless @status
     @status == STATUS_KILLED
   end
 
+  # @return [Boolean]
   def queued?
     update_progress! unless @status
     @status == STATUS_QUEUED
   end
 
+  # @return [Boolean]
   def running?
     update_progress! unless @status
     @status == STATUS_RUNNING
@@ -428,6 +580,9 @@ end
 class ScheduledJob < Job
   attr_reader :scheduled_at
 
+  # @param [TreasureData::Client] client
+  # @param [String] scheduled_at
+  # @param [...] args for Job#initialize
   def initialize(client, scheduled_at, *super_args)
     super(client, *super_args)
     if scheduled_at.to_s.empty?
@@ -440,6 +595,18 @@ end
 
 
 class Schedule < Model
+  # @param [TreasureData::Client] client
+  # @param [String] name
+  # @param [String] cron
+  # @param [String] query
+  # @param [Fixnum] database
+  # @param [String] result_url
+  # @param [String] timezone
+  # @param [String] delay
+  # @param [String] next_time
+  # @param [String] priority
+  # @param [String] retry_limit
+  # @param [String] org_name
   def initialize(client, name, cron, query, database=nil, result_url=nil, timezone=nil, delay=nil, next_time=nil,
                  priority=nil, retry_limit=nil, org_name=nil)
     super(client)
@@ -455,12 +622,25 @@ class Schedule < Model
     @retry_limit = retry_limit
   end
 
+  # @!attribute [r] name
+  # @!attribute [r] cron
+  # @!attribute [r] query
+  # @!attribute [r] database
+  # @!attribute [r] result_url
+  # @!attribute [r] delay
+  # @!attribute [r] priority
+  # @!attribute [r] retry_limit
+  # @!attribute [r] org_name
   attr_reader :name, :cron, :query, :database, :result_url, :timezone, :delay, :priority, :retry_limit, :org_name
 
+  # @return [Time, nil]
   def next_time
     @next_time ? Time.parse(@next_time) : nil
   end
 
+  # @param [String] time
+  # @param [Fixnum] num
+  # @return [Array]
   def run(time, num)
     @client.run_schedule(time, num)
   end
@@ -468,17 +648,26 @@ end
 
 
 class Result < Model
+  # @param [TreasureData::Client] client
+  # @param [String] name
+  # @param [String] url
+  # @param [String] org_name
   def initialize(client, name, url, org_name)
     super(client)
     @name = name
     @url = url
   end
 
+  # @!attribute [r] name
+  # @!attribute [r] url
+  # @!attribute [r] org_name
   attr_reader :name, :url, :org_name
 end
 
 
 class BulkImport < Model
+  # @param [TreasureData::Client] client
+  # @param [Hash] data
   def initialize(client, data={})
     super(client)
     @name = data['name']
@@ -493,6 +682,16 @@ class BulkImport < Model
     @error_parts = data['error_parts']
   end
 
+  # @!attribute [r] name
+  # @!attribute [r] database
+  # @!attribute [r] table
+  # @!attribute [r] status
+  # @!attribute [r] job_id
+  # @!attribute [r] valid_records
+  # @!attribute [r] error_records
+  # @!attribute [r] valid_parts
+  # @!attribute [r] error_parts
+  # @!attribute [r] org_name
   attr_reader :name
   attr_reader :database
   attr_reader :table
@@ -504,6 +703,7 @@ class BulkImport < Model
   attr_reader :error_parts
   attr_reader :org_name
 
+  # @return [Boolean]
   def upload_frozen?
     @upload_frozen
   end
@@ -522,6 +722,11 @@ end
 
 
 class AccessControl < Model
+  # @param [TreasureData::Client] client
+  # @param [String] subject
+  # @param [String] action
+  # @param [String] scope
+  # @param [Array] grant_option
   def initialize(client, subject, action, scope, grant_option)
     super(client)
     @subject = subject
@@ -530,6 +735,10 @@ class AccessControl < Model
     @grant_option = grant_option
   end
 
+  # @!attribute [r] subject
+  # @!attribute [r] action
+  # @!attribute [r] scope
+  # @!attribute [r] grant_option
   attr_reader :subject, :action, :scope, :grant_option
 end