fcoury-octopi 0.0.5 → 0.0.6

data/README.rdoc

@@ -2,7 +2,53 @@
 
 Octopi is a Ruby interface to GitHub API v2 (http://develop.github.com). It's under early but active development and already works.
 
-== Example
+== Authenticated Usage
+
+The following examples requires a valid user authenticated with GitHub using login and API token. This information can be found on our profile (the link is inside the "badge" that is displayed on the upper right corner when you're logged in).
+
+Once you found your login and token you can run authenticated commands using:
+
+  authenticated_with "mylogin", "mytoken" do |g|
+    repo = g.repository("api-labrat")
+    issue = repo.open_issue :title => "Sample issue", 
+      :body => "This issue was opened using GitHub API and Octopi"
+    puts issue.number
+  end
+  
+You can also create a YAML file with your information, with the following format:
+
+  #
+  # Octopi GitHub API configuration file
+  #
+
+  # GitHub user login and token
+  login: github-username
+  token: github-token
+
+  # Trace level
+  # Possible values:
+  #   false - no tracing, same as if the param is ommited
+  #   true  - will output each POST or GET operation to the stdout
+  #   curl  - same as true, but in addition will output the curl equivalent of each command (for debugging)
+  trace: curl
+  
+And change the way you connect to:
+
+  authenticated_with :config => "github.yml" do |g|
+    (...)
+  end
+
+This way you can benefit from better debugging when something goes wrong. If you choose curl tracing, the curl command equivalent to each command sent to GitHub will be output to the stdout, like this example:
+
+  => Trace on: curl
+  POST: /issues/open/webbynode/api-labrat params: body=This issue was opened using GitHub API and Octopi, title=Sample issue
+  ===== curl version
+  curl -F 'body=This issue was opened using GitHub API and Octopi' -F 'login=mylogin' -F 'token=mytoken' -F 'title=Sample issue' http://github.com/api/v2/issues/open/webbynode/api-labrat
+  ==================
+
+== Anonymous Usage
+
+This reflects the usage of the API to retrieve information, on a read-only mode where the user doesn't have to be authenticated.
 
 === Users API
 
@@ -44,6 +90,10 @@ Issues API integrated into the Repository object:
   issue = repo.issues.first
   puts "First open issue: #{issue.number} - #{issue.title} - Created at: #{issue.created_at}"
 
+Single issue information:
+
+  issue = repo.issue(11)
+
 Commits API information from a Repository object:
 
   first_commit = repo.commits.first

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:major: 0
 :minor: 0
-:patch: 5
+:patch: 6
+:major: 0

data/lib/octopi.rb

@@ -1,13 +1,30 @@
 require 'rubygems'
 require 'httparty'
+require 'yaml'
 require 'pp'
 
 module Octopi
   class Api; end
   ANONYMOUS_API = Api.new
   
-  def connect(login, token, &block)
-    yield Api.new(login, token)
+  def authenticated_with(*args, &block)
+    opts = args.last.is_a?(Hash) ? args.last : {}
+    if opts[:config]
+      config = File.open(opts[:config]) { |yf| YAML::load(yf) }
+      raise "Missing config #{opts[:config]}" unless config
+      
+      login = config["login"]
+      token = config["token"]
+      trace = config["trace"]
+    else
+      login, token = *args
+    end
+    
+    puts "=> Trace on: #{trace}" if trace
+    
+    api = Api.new(login, token)
+    api.trace = trace if trace
+    yield api
   end
   
   class Api
@@ -19,11 +36,17 @@ module Octopi
     }  
     base_uri "http://github.com/api/v2"
   
-    attr_accessor :format
+    attr_accessor :format, :login, :token, :trace, :read_only
   
-    def initialize(login = nil, token = nil, format = "xml")
-      self.class.default_params(:login => login, :token => token) if login
+    def initialize(login = nil, token = nil, format = "yaml")
       @format = format
+      @read_only = true
+      
+      if login
+        @login = login
+        @token = token
+        @read_only = false
+      end
     end
   
     %w[keys emails].each do |action|
@@ -33,11 +56,22 @@ module Octopi
     end
 
     def user
-      user_data = get("/user/show/#{self.class.default_params[:login]}")
+      user_data = get("/user/show/#{login}")
       raise "Unexpected response for user command" unless user_data and user_data['user']
       User.new(self, user_data['user'])
     end
     
+    def open_issue(user, repo, params)
+      Issue.open(user, repo, params, self)
+    end
+    
+    def repository(name)
+      repo = Repository.find(login, name)
+      repo.api = self
+      repo
+    end
+    alias_method :repo, :repository
+    
     def save(resource_path, data)
       traslate resource_path, data
       #still can't figure out on what format values are expected
@@ -55,39 +89,61 @@ module Octopi
     def get_raw(path, params)
      get(path, params, 'plain')
     end
+    
+    def post(path, params = {}, format = "yaml")
+      trace "POST", path, params
+      submit(path, params, format) do |path, params, format|
+        resp = self.class.post "/#{format}#{path}", :query => params
+        resp
+      end
+    end
 
     private
-    def get(path, params = {}, format = "yaml")
-      params.each_pair do |k,v|
-        path = path.gsub(":#{k.to_s}", v)
+    def submit(path, params = {}, format = "yaml", &block)
+      params.each_pair { |k,v| path = path.gsub(":#{k.to_s}", v) }
+      query = login ? { :login => login, :token => token } : {}
+      query.merge!(params)
+      
+      if @trace
+        case @trace
+          when "curl"
+            query_trace = []
+            query.each_pair { |k,v| query_trace << "-F '#{k}=#{v}'" }
+            puts "===== [curl version]"
+            puts "curl #{query_trace.join(" ")} #{self.class.base_uri}#{path}"
+            puts "==================="
+        end
       end
-      resp = self.class.get("/#{format}#{path}")
+      
+      resp = yield(path, query, format)
+      raise APIError, 
+        "GitHub returned status #{resp.code}" unless resp.code.to_i == 200
       # FIXME: This fails for showing raw Git data because that call returns
       # text/html as the content type. This issue has been reported.
       ctype = resp.headers['content-type'].first
       raise FormatError, [ctype, format] unless 
         ctype.match(/^#{CONTENT_TYPE[format]};/)
-      raise APIError, 
-        "GitHub returned status #{resp.code}" unless resp.code.to_i == 200
       if format == 'yaml' && resp['error']
         raise APIError, resp['error'].first['error']
       end  
       resp
     end
+    
+    def get(path, params = {}, format = "yaml")
+      trace "GET", path, params
+      submit(path, params, format) do |path, params, format|
+        self.class.get "/#{format}#{path}"
+      end
+    end
+    
+    def trace(oper, url, params)
+      return unless @trace
+      par_str = " params: " + params.map { |p| "#{p[0]}=#{p[1]}" }.join(", ") if params and !params.empty?
+      puts "#{oper}: #{url}#{par_str}"
+    end
   end
-  
-  %w{base resource user tag repository issue file_object blob commit}.
-    each{|f| require "#{File.dirname(__FILE__)}/octopi/#{f}"} 
     
-  class FormatError < StandardError
-   def initialize(f)
-     $stderr.puts "Got unexpected format (got #{f.first} for #{f.last})"
-   end
-  end 
-  
-  class APIError < StandardError
-   def initialize(m)
-     $stderr.puts m 
-   end
-  end 
+  %w{error base resource user tag repository issue file_object blob commit}.
+    each{|f| require "#{File.dirname(__FILE__)}/octopi/#{f}"} 
+
 end

data/lib/octopi/base.rb

@@ -1,5 +1,29 @@
+class String
+  def camel_case
+    self.gsub(/(^|_)(.)/) { $2.upcase }
+  end
+end  
 module Octopi
   class Base
+    VALID = {
+      :repo => {
+        # FIXME: API currently chokes on repository names containing periods,
+        # but presumably this will be fixed.
+        :pat => /^[a-z0-9_\.-]+$/,
+        :msg => "%s is an invalid repository name"},
+      :user => {
+        :pat => /^[A-Za-z0-9_\.-]+$/,
+        :msg => "%s is an invalid username"},
+      :file => {
+        :pat => /^[^ \/]+$/,
+        :msg => "%s is an invalid filename"},
+      :sha => {
+        :pat => /^[a-f0-9]{40}$/,
+        :msg => "%s is an invalid SHA hash"}
+    }  
+    
+    attr_accessor :api
+    
     def initialize(api, hash)
       @api = api
       @keys = []
@@ -36,7 +60,8 @@ module Octopi
     def self.extract_user_repository(*args)
       opts = args.last.is_a?(Hash) ? args.pop : {}
       if opts.empty?
-        user, repo = *args
+        user, repo = *args if args.length > 1
+        repo ||= args.first
       else
         opts[:repo] = opts[:repository] if opts[:repository]
         repo = args.pop || opts[:repo]
@@ -61,5 +86,17 @@ module Octopi
         v
       end
     end
+
+    def self.validate_args(spec)
+      m = caller[0].match(/\/([a-z0-9_]+)\.rb:\d+:in `([a-z_0-9]+)'/)
+      meth = m ? "#{m[1].camel_case}.#{m[2]}" : 'method'
+      raise ArgumentError, "Invalid spec" unless 
+        spec.values.all? { |s| VALID.key? s }
+      errors = spec.reject{|arg, spec| arg.nil?}.
+                    reject{|arg, spec| arg.to_s.match(VALID[spec][:pat])}.
+                    map   {|arg, spec| "Invalid argument '%s' for %s (%s)" % 
+                      [arg, meth, VALID[spec][:msg] % arg]} 
+      raise ArgumentError, "\n" + errors.join("\n") unless errors.empty?
+    end  
   end
-end
+end

data/lib/octopi/blob.rb

@@ -8,6 +8,7 @@ module Octopi
     def self.find(user, repo, sha, path=nil)
       user = user.login if user.is_a? User
       repo = repo.name if repo.is_a? Repository
+      self.class.validate_args(sha => :sha, user => :user, path => :file)
       if path
         super [user,repo,sha,path]
       else
@@ -17,4 +18,4 @@ module Octopi
       end  
     end  
   end
-end
+end

data/lib/octopi/commit.rb

@@ -24,6 +24,7 @@ module Octopi
       repo = args.first
       user ||= repo.owner if repo.is_a? Repository
       user, repo_name, opts = extract_user_repository(*args)
+      self.validate_args(user => :user, repo_name => :repo)
       branch = opts[:branch] || "master"
       
       commits = super user, repo_name, branch
@@ -40,6 +41,7 @@ module Octopi
         user, name, sha = *args
         user = user.login if user.is_a? User
         name = repo.name  if name.is_a? Repository
+        self.validate_args(user => :user, name => :repo, sha => :sha)
         super [user, name, sha]
       end
     end
@@ -59,4 +61,4 @@ module Octopi
       parts.join('/')
     end
   end
-end
+end

data/lib/octopi/error.rb

@@ -0,0 +1,15 @@
+module Octopi
+
+  class FormatError < StandardError
+   def initialize(f)
+     $stderr.puts "Got unexpected format (got #{f.first} for #{f.last})"
+   end
+  end 
+
+  class APIError < StandardError
+   def initialize(m)
+     $stderr.puts m 
+   end
+  end
+
+end

data/lib/octopi/file_object.rb

@@ -8,7 +8,8 @@ module Octopi
     def self.find(user, repo, sha)
       user = user.login if user.is_a? User
       repo = repo.name if repo.is_a? Repository
+      self.validate_args(sha => :sha, user => :user, repo => :repo)
       super [user,repo,sha] 
     end  
   end
-end
+end

data/lib/octopi/issue.rb

@@ -3,7 +3,7 @@ module Octopi
     include Resource
     
     find_path "/issues/list/:query"
-    resource_path "/user/show/:id"
+    resource_path "/issues/show/:id"
     
     attr_accessor :repository
     
@@ -24,6 +24,7 @@ module Octopi
     def self.find_all(*args)
       repo = args.first
       user, repo_name, opts = extract_user_repository(*args)
+      validate_args(user => :user, repo_name => :repo)
       state = opts[:state] || "open"
       state.downcase! if state
       
@@ -36,15 +37,63 @@ module Octopi
   
     # TODO: Make find use hashes like find_all
     def self.find(*args)
-      if args.last.is_a?(Issue)
-        commit = args.pop
-        super "#{issue.number}"
+      if args.length < 2
+        raise "Issue.find needs user, repository and issue number"
+      end
+      
+      number = args.pop.to_i if args.last.respond_to?(:to_i)
+      number = args.pop if args.last.is_a?(Integer)
+      
+      raise "Issue.find needs issue number as the last argument" unless number
+      
+      if args.length > 1
+        user, repo = *args
       else
-        user, name, number = *args
-        user = user.login if user.is_a? User
-        name = repo.name  if name.is_a? Repository
-        super user, name, number
+        repo = args.pop
+        raise "Issue.find needs at least a Repository object and issue number" unless repo.is_a? Repository
+        user, repo = repo.owner, repo.name
+      end
+      
+      user, repo = extract_names(user, repo)
+      validate_args(user => :user, repo => :repo)
+      super user, repo, number
+    end
+    
+    def self.open(user, repo, params, api = ANONYMOUS_API)
+      user, repo_name = extract_names(user, repo)
+      data = api.post("/issues/open/#{user}/#{repo_name}", params)
+      issue = new(api, data['issue'])
+      issue.repository = repo if repo.is_a? Repository
+      issue
+    end
+    
+    def reopen(*args)
+      data = @api.post(command_path("reopen"))
+    end
+    
+    def close(*args)
+      data = @api.post(command_path("close"))
+    end
+    
+    def save
+      data = @api.post(command_path("edit"), { :title => self.title, :body => self.body })
+    end
+    
+    %[add remove].each do |oper|
+      define_method("#{oper}_label") do |*labels|
+        labels.each do |label|
+          @api.post("#{prefix("label/#{oper}")}/#{label}/#{number}")
+        end
       end
     end
+    
+    private
+    def prefix(command)
+      "/issues/#{command}/#{repository.owner}/#{repository.name}"
+    end
+    
+    def command_path(command)
+      "#{prefix(command)}/#{number}"
+    end
   end
-end
+end

data/lib/octopi/repository.rb

@@ -18,13 +18,15 @@ module Octopi
 
     def self.find_by_user(user)
       user = user.login if user.is_a? User
+      self.validate_args(user => :user)
       find_plural(user, :resource)
     end
 
     def self.find(user, name)
       user = user.login if user.is_a? User
       name = repo.name if name.is_a? Repository
-      super [user,name]
+      self.validate_args(user => :user, name => :repo)
+      super [user, name]
     end
 
     def self.find_all(*args)
@@ -33,6 +35,14 @@ module Octopi
       super args.join(" ").gsub(/ /,'+')
     end
     
+    def self.open_issue(args)
+      Issue.open(args[:user], args[:repo], args)
+    end
+    
+    def open_issue(args)
+      Issue.open(self.owner, self, args, @api)
+    end
+    
     def commits(branch = "master")
       Commit.find_all(self, :branch => branch)
     end
@@ -40,5 +50,9 @@ module Octopi
     def issues(state = "open")
       Issue.find_all(self, :state => state)
     end
+    
+    def issue(number)
+      Issue.find(self, number)
+    end
   end
 end

data/lib/octopi/resource.rb

@@ -28,7 +28,7 @@ module Octopi
         (@path_spec||={})[:resource] = path
       end
     
-      def find(s)
+      def find(*s)
         s = s.join('/') if s.is_a? Array
         result = ANONYMOUS_API.find(path_for(:resource), @resource_name[:singular], s)
         key = result.keys.first

data/lib/octopi/tag.rb

@@ -8,9 +8,10 @@ module Octopi
     def self.find(user, repo)
       user = user.login if user.is_a? User
       repo = repo.name if repo.is_a? Repository
+      self.validate_args(user => :user, repo => :repo)
       find_plural([user,repo,'tags'], :resource){
         |i| {:name => i.first, :hash => i.last }
       }
     end
   end
-end
+end

data/lib/octopi/user.rb

@@ -5,11 +5,22 @@ module Octopi
     find_path "/user/search/:query"
     resource_path "/user/show/:id"
     
+    def self.find(username)
+      self.validate_args(username => :user)
+      super username
+    end
+
+    def self.find_all(username)
+      self.validate_args(username => :user)
+      super username
+    end
+
     def repositories
       Repository.find_by_user(login)
     end
     
     def repository(name)
+      self.class.validate_args(name => :repo)
       Repository.find(login, name)
     end
     
@@ -35,4 +46,4 @@ module Octopi
       users
     end
   end
-end
+end

data/test/octopi_test.rb

@@ -1,7 +1,46 @@
 require 'test_helper'
 
 class OctopiTest < Test::Unit::TestCase
-  should "probably rename this file and start testing for real" do
-    flunk "hey buddy, you should probably rename this file and start testing for real"
+  include Octopi
+  
+  # TODO: Those tests are obviously brittle. Need to stub/mock it.
+  
+  def assert_find_all(cls, check_method, repo, user)
+    repo_method = cls.resource_name(:plural)
+    
+    item1 = cls.find_all(user.login, repo.name).first
+    item2 = cls.find_all(repo).first
+    item3 = repo.send(repo_method).first
+    
+    assert_equal item1.send(check_method), item2.send(check_method)
+    assert_equal item1.send(check_method), item3.send(check_method)
+  end
+  
+  def setup
+    @user = User.find("fcoury")
+    @repo = @user.repository("octopi")
+    @issue = @repo.issues.first
+  end
+  
+  context Issue do
+    should "return the correct issue by number" do
+      assert_equal @issue.number, Issue.find(@repo, @issue.number).number
+      assert_equal @issue.number, Issue.find(@user, @repo, @issue.number).number
+      assert_equal @issue.number, Issue.find(@repo.owner, @repo.name, @issue.number).number
+    end
+
+    should "return the correct issue by using repo.issue number" do
+      assert_equal @issue.number, @repo.issue(@issue.number).number
+    end
+    
+    should "fetch the same issue using different but equivalent find_all params" do
+      assert_find_all Issue, :number, @repo, @user
+    end
+  end
+
+  context Commit do
+    should "fetch the same commit using different but equivalent find_all params" do
+      assert_find_all Commit, :id, @repo, @user
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: fcoury-octopi
 version: !ruby/object:Gem::Version 
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors: 
 - Felipe Coury
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-20 00:00:00 -07:00
+date: 2009-04-21 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -29,6 +29,7 @@ files:
 - lib/octopi/base.rb
 - lib/octopi/blob.rb
 - lib/octopi/commit.rb
+- lib/octopi/error.rb
 - lib/octopi/file_object.rb
 - lib/octopi/issue.rb
 - lib/octopi/repository.rb
@@ -64,7 +65,7 @@ requirements: []
 rubyforge_project: 
 rubygems_version: 1.2.0
 signing_key: 
-specification_version: 3
+specification_version: 2
 summary: A Ruby interface to GitHub API v2
 test_files: []