githu3 0.0.3 → 0.0.4

data/README.md

@@ -1,5 +1,7 @@
 # githu3 [![Build Status](http://travis-ci.org/sbellity/githu3.png)](http://travis-ci.org/sbellity/githu3)
 
+githu3 is a ruby wrapper for github's v3 api.
+
 
 ## Installation
 
@@ -7,7 +9,184 @@
     
 ## Usage
   
+### Authentication
+
+There are two ways to authenticate
+
+Basic Authentication:
+
+    client = Githu3::Client.new('username', 'password')
+
+OAuth2 Token (send in a header): 
+
+    client = Githu3::Client.new('myawesomelyverylongoauth2token')
+    
+Or you can use the lib as an un-authenticated client to access only public Github resources...
   
+    client = Githu3::Client.new
+
+### Getting the basics
+
+The Githu3::Client instance can directly access github's top-level resources : orgs, repos, teams and users
+
+to get them : 
+    
+    c = Githu3::Client.new
+
+    # Org
+    rails_org = c.org 'rails' # -> 'rails' organization wrapped in a Gihu3::Org object
+    
+    # Repo
+    rails_repo = c.repo 'rails/rails' # -> That's Rails !
+    
+    # User
+    sbellity = c.user 'sbellity' # -> That's me !
+
+    # Team
+    a_team = c.team 123 # -> well... team number '123' if you have access to it
+    
+
+### Getting your stuff
+
+When authenticated, your Githu3::Client instance can give you direct access to your top-level stuff... 
+
+    me = Githu3::Client.new 'myawesomelyverylongoauth2token'
+    
+    # Orgs
+    # returns a paginable Githu3::ResourceCollection stuffed with YOUR organizations
+    # more on this Githu3::ResourceCollection thing later...
+    my_orgs = me.orgs
+    
+    # Repos
+    my_repos = me.repos
+    
+    # Me
+    me = me.me                # -> well, you get the point...
+
+    # Followers
+    me.following              # -> returns a list a the Githu3::User, that you follow
+    me.followers              # -> returns a list a the Githu3::User, that follow you
+    me.following?("rails")    # -> true if you follow 'rails', false otherwise
+    
+
+### Getting deeper inside the API with Githu3::Resource Objects
+
+All the calls to the API either return Githu3::Resource objects (ex. Githu3::User, Githu3::Repo, Githu3::Org...) et Githu3::ResourceCollection objects that wrap... Githu3::Resource objects
+    
+#### Attributes
+
+All the member attributes are accessible directly via their names. If you try to access an attribute that does not exist... you'll get `nil`
+
+Examples: 
+
+    c = Githu3::Client.new
+    
+    rails_org = c.org 'rails'
+    rails_org.login           # -> 'rails'
+    rails_org.html_url        # -> 'https://github.com/rails'
+    rails_org.public_repos    # -> 44
+    rails_org.foo             # -> nil
+
+
+#### Relations
+
+Relations between the Resources follow the nesting of the Github's REST Api. For example, you can get the list of an org's repos directly from the Githu3::Org object. 
+
+    c = Githu3::Client.new
+    rails_org = c.org "rails"
+    rails_org.repos # -> the list of rails' repos
+
+You can even do this !
+
+    rails_org.repos.first.issues # -> latest issues from rails' first repo
+
+
+#### Embedding
+
+Github often embeds objects inside others. For example, rails Repo has an owner object, that is a Githu3::User object... which let you do this: 
+
+    rails_repo = c.repo "rails/rails"
+    rails_repo.owner  # -> rails org wrapped in a Githu3::User object
+    
+
+
+### Getting lots of stuff with Githu3::ResourceCollection Objects
+
+#### Acts as Enumerable
+
+Most results from the Api calls are collections of stuff. Those collections are wrapped in Githu3::ResourceCollection objects that primarily act as Arrays. Meaning that you can safely call the usual `length`, `first`, `last`, `each`, `map`, `select`... an so on... on them.
+
+#### Pagination
+
+_Warning !... this Pagination api is very alpha-ish... and very susceptible to change_
+
+In fact, Github's api generally returns [paginated results](http://developer.github.com/v3/#pagination). Github::ResourceCollection have a pagination api built right in, that lets you do those kinds of stuff : 
+
+    rails_repo = c.repo "rails/rails"
+    rails_issues = rails_repo.issues(:per_page => 10, :page => 4) # -> :per_page defaults to 30, :page defaults to 1
+    
+    rails_issues.current_page               # -> 4
+    rails_issues.length                     # -> 10
+    
+    next_issues = rails_issues.fetch_next   # -> next_issues is a plain Array here... 
+                                            # new records are added to your original collection
+    rails_issues.current_page               # -> 5
+    rails_issues.length                     # -> 20
+
+
+#### Filtering & Sorting
+
+Github Api provides filter options for most collection calls. To use a filter on your Githu3::ResourceCollection object, you can do 
+
+    repo  = c.repo "sbellity/githu3"
+    open_issues = repo.issues :state => "open"
+    bugs        = repo.issues :tag => "bug"
+    my_issues   = repo.issues :assignee => "sbellity"
+    
+    # You can also combine and sort them
+    my_open_bugs = repo.issues  :assignee => "sbellity", 
+                                :tag => "bug", 
+                                :state => "open", 
+                                :sort => "updated", 
+                                :direction => "desc"
+
+
+
+### Rate limiting
+
+Your app may generate a LOT of requests to Github's API... By default, you are rate-limitted to 5000 requests per day. You can check anytime the status of your allowance via the method "rate_limit" on your Githu3::Client instance.
+
+    c = Githu3::Client.new
+    ...
+    c.rate_limit  # -> {:limit=>"5000", :remaining=>"4969"}
+
+
+### Caching results
+
+Githu3 provides a very basic cache mechanism to avoid making duplicate requests too often. Basically what it does is just record HTTP request results in a store with an expiration timeout and attempts to retrieve the results back from this store before hitting Github's servers. The different clients private data... should be safe, the request headers (that contain auth info) are used to generate the hash. 2 stores are provided by default : Redis and Disk.
+
+To use them (these are the default options):
+
+    disk_cached_client = Githu3::Client.new('myawesomelyverylongoauth2token', :cache => :disk, :cache_options => {
+      :path       => "/tmp/githu3", 
+      :namespace  => "cache",       # or "myawesomelyverylongoauth2token" if you are paranoid...
+      :expiration => 120            # in seconds
+    })
+
+    redis_cached_client = Githu3::Client.new('myawesomelyverylongoauth2token', :cache => :redis, :cache_options => {
+      :host       => "localhost",     # defaults to localhost
+      :port       => 6379             # defaults to 6379
+      :namespace  => "githu3",        # or "githu3:myawesomelyverylongoauth2token" if you are paranoid...
+      :expiration => 120              # in seconds
+    })
+
+
+## Limitations / Known issues
+
+* The current version (0.1.x branch) only supports read (GET) operations on Github... support for CREATE / UPDATE operations should show up in the the 0.2.x branch.
+* Github's api is still in beta, so this lib could break anytime if they change something, stay tuned for new versions and please report any issue on the project issue tracker.
+* Some calls (ex. `c.repo('rails/rails').issues` -> 2 HTTP GET) make unnecessary calls to github, we will try to find a way to avoid this overhead in a future version.
+* This lib is VERY young, please be kind and help me improve it
 
 
 ## Contributing to githu3

data/bin/githu3

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path("../../lib", __FILE__)
+
+require "githu3/cli"
+
+Githu3::CLI.start

data/lib/faraday/response/parse_json.rb

@@ -0,0 +1,22 @@
+require 'faraday'
+
+module Faraday
+  class Response::ParseJson < Response::Middleware
+    dependency 'multi_json'
+
+    def parse(body)
+      case body
+      when nil
+        nil
+      when ''
+        nil
+      when 'true'
+        true
+      when 'false'
+        false
+      else
+        ::MultiJson.decode(body)
+      end
+    end
+  end
+end

data/lib/githu3/cache/disk.rb

@@ -0,0 +1,43 @@
+require 'fileutils'
+
+module Githu3
+  module Cache
+    class Disk
+      attr_reader :config, :store
+      
+      DEFAULTS = { 
+        :path       => '/tmp/githu3',
+        :namespace  => 'cache',
+        :expire     => 120
+      } unless defined?(DEFAULTS)
+      
+      def initialize opts={}
+        @config = DEFAULTS.merge(opts || {})
+        @path = ::File.expand_path(::File.join(@config[:path], @config[:namespace]))
+        FileUtils.mkdir_p @path
+      end
+      
+      def get k
+        val = nil
+        file_path = ::File.join(@path, k)
+        if ::File.exists?(file_path)
+          if (Time.now - ::File.atime(file_path)) < @config[:expire]
+            val = Marshal.load(::File.read(file_path))
+          else
+            FileUtils.rm(file_path)
+          end
+        else
+        end
+        val
+      end
+      
+      def set k, val, opts={}
+        file_path = ::File.join(@path, k)
+        f = open(file_path, 'wb')
+        f.write(Marshal.dump(val))
+        f.close
+      end
+      
+    end
+  end
+end

data/lib/githu3/cache/redis.rb

@@ -0,0 +1,35 @@
+require 'redis'
+require 'redis/namespace'
+
+module Githu3
+  module Cache
+    class Redis
+      attr_reader :config, :store
+      
+      DEFAULTS = { 
+        :host       => 'localhost', 
+        :port       => 6379, 
+        :namespace  => :githu3,
+        :expire     => 120
+      } unless defined?(DEFAULTS)
+      
+      def initialize opts={}
+        @config = DEFAULTS.merge(opts || {})
+        redis = ::Redis.new :host => @config[:host], :port => @config[:port]
+        @store = ::Redis::Namespace.new(@config[:namespace].to_sym, :redis => redis)
+      end
+      
+      def get k
+        val = @store[k.to_s]
+        val = Marshal.load val unless val.nil?
+        val
+      end
+      
+      def set k, val, opts={}
+        @store[k.to_s] = Marshal.dump(val)
+        @store.expire k.to_s, (opts[:expire] || @config[:expire]).to_i
+      end
+      
+    end
+  end
+end

data/lib/githu3/cache.rb

@@ -0,0 +1,8 @@
+module Githu3
+  
+  module Cache
+    autoload :Redis,  "githu3/cache/redis"
+    autoload :Disk,   "githu3/cache/disk"
+  end
+  
+end

data/lib/githu3/cli.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'githu3'
+require 'thor'
+require 'yaml'
+
+module Githu3
+  
+  class CLI < Thor
+    
+    desc "issues", "get the latest issues from a repo"
+    def issues repo_name
+      client = Githu3::Client.new
+      begin
+        repo = client.repo(repo_name)
+        repo.issues.map do |issue|
+          puts [issue.number.to_s.ljust(5), issue.assignee.to_s.ljust(25), issue.title.to_s].join("\t|\t")
+        end
+      rescue => err
+        puts "Error: #{err.class.name}"
+      end
+    end
+    
+  end
+  
+end

data/lib/githu3/client.rb

@@ -1,48 +1,46 @@
 require 'faraday'
-require 'faraday_middleware'
 require 'faraday/response/raise_githu3_error'
+require 'faraday/response/parse_json'
 require 'uri'
+require 'forwardable'
 require 'active_support/core_ext/hash'
 
 module Githu3
 
   class Client
     
+    extend Forwardable
+    
     BaseUrl = "https://api.github.com"
     
-    attr_reader :conn, :rate_limit
+    def_delegator :conn, :rate_limit
+    
+    attr_reader :conn, :auth
   
-    def initialize(oauth_token=nil)
-      headers = {}
-      headers["Authorization"] = "token #{oauth_token}" if oauth_token
-      @conn = Faraday.new({
-        :url => Githu3::Client::BaseUrl, 
-        :headers => headers
-      })
-      
-      @conn.use Faraday::Response::ParseJson
-      @conn.use Faraday::Response::RaiseGithu3Error
-      
-      @rate_limit = {}
-      @conn
+    def initialize(*args)
+      opts = args.extract_options!
+      @conn = Githu3::Connection.new opts do |c|
+        case args.length
+        when 1
+          @auth = :token
+          c.headers["Authorization"] = "token #{args.first}"
+        when 2
+          @auth = :basic
+          c.basic_auth(*args)
+        end
+      end
     end
-  
+    
+    def authenticated?
+      !!@auth
+    end
+    
     def get *args
       opts = args.extract_options!
       uri = URI.parse(args.shift)
-      uri_params = (opts[:params] || {}).stringify_keys
-      unless uri.query.nil?
-        uri_params.merge(uri.query.split("&").inject({}) { |m,p| k,v=p.split("=", 2); m.merge(k => v)  } )
-      end
-      args.unshift uri.path
-      res = @conn.get(*args) do |req|
-        req.params = uri_params
-        if opts[:params].is_a?(Hash)
-          opts[:params].each { |k,v| req.params[k.to_s] = v.to_s }
-        end
-      end
-      @rate_limit[:limit] = res.headers["x-ratelimit-limit"]
-      @rate_limit[:remaining] = res.headers["x-ratelimit-remaining"]
+      uri.query = (opts[:params] || {}).stringify_keys.merge(Hash.from_url_params(uri.query || "")).to_url_params
+      
+      res = @conn.get(uri, opts[:headers])
       res
     end
     
@@ -56,33 +54,51 @@ module Githu3
     # My stuf...
 
     def me
+      require_auth
       Githu3::User.new "/user", self
     end
     
     def orgs params={}
+      require_auth
       Githu3::ResourceCollection.new(self, Githu3::Org, "/user/orgs", params)
     end
     
     def repos params={}
+      require_auth
       Githu3::ResourceCollection.new(self, Githu3::Repo, "/user/repos", params)
     end
   
+    def teams
+      require_auth
+      Githu3::ResourceCollection.new(self, Githu3::Team, "/user/teams")
+    end
+  
     def followers params={}
+      require_auth
       Githu3::ResourceCollection.new(self, Githu3::User, "/user/followers", params)
     end
   
     def following params={}
+      require_auth
       Githu3::ResourceCollection.new(self, Githu3::User, "/user/following", params)
     end
     
     def following?(other_user)
+      require_auth
       begin
         get("/user/following/#{other_user}").status == 204
       rescue Githu3::NotFound
         false
       end
     end
-  
+    
+    protected
+    
+    def require_auth
+      raise Githu3::Unauthorized, "You must me logged in to use this method" unless authenticated?
+      yield if block_given?
+    end
+    
   end
 
 end

data/lib/githu3/comment.rb

@@ -1,5 +1,20 @@
 module Githu3
   class Comment < Githu3::Resource
     
+    embeds_one :user
+    
+    def _type
+      m = url.match(/(issues|gists|pulls)\/comments\/[0-9]+$/)
+      if m.nil? || m[1].nil?
+        "commitcomment"
+      else
+        "#{m[1].singularize}comment"
+      end
+    end
+    
+    def _mime_type mt
+      "application/vnd.github-#{_type}.#{mt}+json"
+    end
+    
   end
 end

data/lib/githu3/commit.rb

@@ -0,0 +1,13 @@
+module Githu3
+  class Commit < Githu3::Resource
+    
+    embeds_one :committer,  :class_name => :user
+    embeds_one :author,     :class_name => :user
+    embeds_one :commit,     :class_name => :git_commit
+    
+    def message
+      _attributes.message || commit.message rescue nil
+    end
+
+  end
+end

data/lib/githu3/connection.rb

@@ -0,0 +1,47 @@
+require 'digest/sha1'
+
+module Githu3
+  
+  class Connection
+    
+    attr_reader :rate_limit, :cache, :conn
+    
+    
+    
+    def initialize opts={}
+      @conn = Faraday.new({ :url => Githu3::Client::BaseUrl })
+      
+      @conn.adapter opts[:adapter] if opts[:adapter]
+      @conn.use Faraday::Response::ParseJson
+      @conn.use Faraday::Response::RaiseGithu3Error
+      
+      if opts[:cache]
+        cache_klass = Githu3::Cache.const_get(opts[:cache].to_s.camelize)
+        @cache = cache_klass.new(opts[:cache_config])
+      end
+      
+      yield @conn if block_given?
+      
+      @rate_limit = {}
+    end
+    
+    def get url, headers={}, opts={}
+      use_cache = !@cache.nil? && !opts[:bypass_cache]
+      if use_cache
+        ref = Digest::SHA1.hexdigest [url, headers.to_s].join("")
+        res = @cache.get ref
+        return res unless res.nil?
+      end
+      res = @conn.get(url, headers)
+      if use_cache
+        @cache.set(ref, res) if res.status < 400
+      else
+        @rate_limit[:limit] = res.headers["x-ratelimit-limit"]
+        @rate_limit[:remaining] = res.headers["x-ratelimit-remaining"]
+      end
+      res
+    end
+    
+  end
+  
+end

data/lib/githu3/core_ext/hash.rb

@@ -0,0 +1,18 @@
+class Hash
+  def to_url_params
+    elements = []
+    keys.size.times do |i|
+      elements << "#{keys[i]}=#{values[i]}"
+    end
+    elements.join('&')
+  end
+
+  def self.from_url_params(url_params="")
+    result = {}
+    url_params.split('&').each do |element|
+      element = element.split('=')
+      result[element[0]] = element[1]
+    end
+    result
+  end
+end

data/lib/githu3/download.rb

@@ -0,0 +1,4 @@
+module Githu3
+  class Download < Githu3::Resource
+  end  
+end

data/lib/githu3/event.rb

@@ -1,5 +1,11 @@
 module Githu3
   class Event < Githu3::Resource
     
+    embeds_one :issue
+    
+    def to_s
+      "#{date}: #{actor['login']} #{event} #{issue.title}"
+    end
+   
   end
 end

data/lib/githu3/git_commit.rb

@@ -0,0 +1,5 @@
+module Githu3
+  class GitCommit < Githu3::Resource
+    
+  end
+end

data/lib/githu3/issue.rb

@@ -3,7 +3,16 @@ module Githu3
     
     has_many :events
     has_many :comments
-    has_many :labels
     
+    # members
+    embeds_many :labels
+    embeds_one  :user
+    embeds_one  :milestone
+    embeds_one  :assignee, :class_name => :user
+    
+    def _mime_type mt
+      "application/vnd.github-issue.#{mt}+json"
+    end
+        
   end
 end

data/lib/githu3/org.rb

@@ -5,7 +5,7 @@ module Githu3
     
     has_many :repos
     has_many :teams
-    has_many :members, :class_name => :user
+    has_many :members,        :class_name => :user
     has_many :public_members, :class_name => :user
     
     def member?(user_login)

data/lib/githu3/pull.rb

@@ -0,0 +1,9 @@
+module Githu3
+  class Pull < Githu3::Resource
+    
+    def to_s
+      url || html_url
+    end
+    
+  end
+end

data/lib/githu3/ref.rb

@@ -0,0 +1,9 @@
+module Githu3
+  class Ref < Githu3::Resource
+    
+    def to_s
+      url || html_url
+    end
+    
+  end
+end

data/lib/githu3/relations.rb

@@ -1,6 +1,26 @@
 module Githu3
 
   module Relations
+    
+    def embeds_one m, opts={}
+      opts[:class_name] ||= m.to_s
+      define_method(m) do
+        klass = Githu3.const_get(opts[:class_name].to_s.camelize)
+        data = self._attributes.send(m)
+        klass.new(data, @client) unless data.nil?
+      end
+    end
+    
+    def embeds_many m, opts={}
+      opts[:class_name] ||= m.to_s.singularize
+      define_method(m) do 
+        klass = Githu3.const_get(opts[:class_name].to_s.camelize)
+        data = self._attributes.send(m)
+        data.map { |o| klass.new(o, @client) } unless data.nil?
+      end
+    end
+    
+    
     def has_many m, opts={}
       opts[:class_name] ||= m.to_s.singularize
       define_method(m) do |*args|
@@ -8,9 +28,9 @@ module Githu3
         klass = Githu3.const_get(opts[:class_name].to_s.camelize)
         _resource_path = [opts[:nested_in], m].compact.join("/")
         if args.length == 1
-          klass.new([path, _resource_path, args.first].join("/"), @client)
+          klass.new([_path, _resource_path, args.first].join("/"), @client)
         else
-          Githu3::ResourceCollection.new(@client, klass, [path, _resource_path].join("/"), params)
+          Githu3::ResourceCollection.new(@client, klass, [_path, _resource_path].join("/"), params)
         end
       end
     end