github_api 0.8.11 → 0.9.0

data/README.md

@@ -18,12 +18,13 @@ Supports all the API methods(nearly 200). It's build in a modular way, that is,
 * Modular design allows for working with parts of API.
 * Fully customizable including advanced middleware stack construction.
 * Its comprehensive, you can request all GitHub API resources.
-* Requests pagination.
-* Easy error handling.
+* Requests pagination with convenient DSL.
+* Easy error handling split for client and server type errors.
+* Supports multithreaded environment.
 * Custom mime types specification (Status: TODO)
 * Flexible arguments parsing (Status: In progress).
 * Request results caching (Status: TODO)
-* Fully tested with test coverage above 90% with over 1,300 specs and 700 features.
+* Fully tested with test coverage above 90% with over 1,400 specs and 700 features.
 
 ## Installation
 
@@ -59,7 +60,7 @@ At this stage you can also supply various configuration parameters, such as `:us
 github = Github.new oauth_token: 'token'
 ```
 
-Alternatively, you can configure the Github settings by passing a block, for instance, with custom enteprise endpoint like
+Alternatively, you can configure the Github settings by passing a block, for instance, with custom enterprise endpoint like
 
 ```ruby
 github = Github.new do |config|
@@ -254,7 +255,7 @@ To list the scopes that the particular Github API action checks for do:
 ```ruby
   repos = Github::Repos.new
   res = repos.list :user => 'peter-murach'
-  res.accepted_oauth_scopes    # => ['delete_repo', 'repo', 'public_repo', 'repo:status']
+  res.header.accepted_oauth_scopes    # => ['delete_repo', 'repo', 'public_repo', 'repo:status']
 ```
 
 To understand what each scope means refer to [documentation](http://developer.github.com/v3/oauth/#scopes)
@@ -278,6 +279,9 @@ If your client fails to find CA certs you can pass other SSL options to specify
   }
 ```
 
+For instance, download CA root certificates from Mozilla [cacert](http://curl.haxx.se/ca/cacert.pem) and point ca_file at your certificate bundle location.
+This will allow the client to verify the github.com ssl certificate as authentic.
+
 ## MIME Types
 
 Issues, PullRequests and few other API leverage custom mime types which are <tt>:json</tt>, <tt>:blob</tt>, <tt>:raw</tt>, <tt>:text</tt>, <tt>:html</tt>, <tt>:full</tt>. By default <tt>:raw</tt> is used.
@@ -354,11 +358,12 @@ end
 One can also navigate straight to specific page by:
 
 ```ruby
-res.page 5     # Requests given page if it exists, nil otherwise
-res.first_page
-res.prev_page
-res.next_page
-res.last_page
+res.count_pages  # Number of pages
+res.page 5       # Requests given page if it exists, nil otherwise
+res.first_page   # Get first page
+res.next_page    # Get next page
+res.prev_page    # Get previous page
+res.last_page    # Get last page
 ```
 
 ## Error Handling
@@ -385,10 +390,12 @@ Each response comes packaged with methods allowing for inspection of HTTP start
 
 ```ruby
 res = Github::Repos.new.branches 'peter-murach', 'github'
-res.ratelimit_limit     # "5000"
-res.ratelimit_remainig  # "4999"
-res.status              # "200"
-res.content_type        # "application/json; charset=utf-8"
+res.headers.ratelimit_limit     # "5000"
+res.headers.ratelimit_remainig  # "4999"
+res.headers.status              # "200"
+res.headers.content_type        # "application/json; charset=utf-8"
+res.headers.etag                # "\"2c5dfc54b3fe498779ef3a9ada9a0af9\""
+res.headers.cache_control       # "public, max-age=60, s-maxage=60"
 ```
 
 ## Examples

data/features/activity/notifications.feature

@@ -0,0 +1,15 @@
+Feature: Notifications API
+
+  Background:
+    Given I have "Github::Activity::Notifications" instance
+
+  Scenario: List
+
+    Given I want to list resources
+      And I pass the following request options:
+        | user   | repo          |
+        | wycats | handlebars.js |
+    When I make request within a cassette named "activity/notifications/list_user"
+    Then the response status should be 200
+      And the response type should be JSON
+      And the response should be empty

data/features/cassettes/activity/notifications/list_user.yml

@@ -0,0 +1,54 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://<BASIC_AUTH>@api.github.com/repos/wycats/handlebars.js/notifications?access_token=<TOKEN>
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      Accept:
+      - application/vnd.github.v3.full+json,application/vnd.github.beta.full+json;q=0.7,application/vnd.github+json;q=0.5,application/json;q=0.1
+      Accept-Charset:
+      - utf-8
+      User-Agent:
+      - Github Ruby Gem 0.8.11
+      Content-Type:
+      - application/json
+      Accept-Encoding:
+      - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Server:
+      - GitHub.com
+      Date:
+      - Mon, 18 Feb 2013 22:03:48 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Connection:
+      - keep-alive
+      Status:
+      - 200 OK
+      X-Ratelimit-Limit:
+      - '5000'
+      X-Ratelimit-Remaining:
+      - '4999'
+      X-Github-Media-Type:
+      - github.v3; param=full; format=json
+      X-Content-Type-Options:
+      - nosniff
+      Content-Length:
+      - '2'
+      Etag:
+      - ! '"d751713988987e9331980363e24189ce"'
+      Cache-Control:
+      - max-age=0, private, must-revalidate
+    body:
+      encoding: US-ASCII
+      string: ! '[]'
+    http_version: !!null 
+  recorded_at: Mon, 18 Feb 2013 22:03:48 GMT
+recorded_with: VCR 2.4.0

data/features/step_definitions/common_steps.rb

@@ -30,27 +30,26 @@ end
 Then /^the response should be (.*)$/ do |expected_response|
   expected_response = case expected_response
   when /false/
-    false
+    @response.should be_false
   when /true/
-    true
+    @response.should be_true
   when /\d+/
-    expected_response.to_i
+    @response.should eql expected_response.to_i
   when /empty/
-    []
+    @response.should be_empty
   else
-    expected_response
+    @response.should eql expected_response
   end
-  @response.should eql expected_response
 end
 
 Then /^the response type should be (.*)$/ do |type|
   case type.downcase
   when 'json'
-    @response.content_type.should =~ /application\/json/
+    @response.headers.content_type.should =~ /application\/json/
   when 'html'
-    @response.content_type.should =~ /text\/html/
+    @response.headers.content_type.should =~ /text\/html/
   when 'raw'
-    @response.content_type.should =~ /raw/
+    @response.headers.content_type.should =~ /raw/
   end
 end
 

data/lib/github_api.rb

@@ -13,14 +13,11 @@ module Github
 
   class << self
 
-    # Handle for the client instance
-    attr_accessor :api_client
-
     # Alias for Github::Client.new
     #
     # @return [Github::Client]
     def new(options = {}, &block)
-      @api_client = Github::Client.new(options, &block)
+      Github::Client.new(options, &block)
     end
 
     # Delegate to Github::Client
@@ -66,6 +63,7 @@ module Github
     :Repos           => 'repos',
     :Request         => 'request',
     :Response        => 'response',
+    :ResponseWrapper => 'response_wrapper',
     :Result          => 'result',
     :Error           => 'error',
     :Issues          => 'issues',
@@ -85,6 +83,7 @@ module Github
     :MimeType        => 'mime_type',
     :Authorization   => 'authorization',
     :Authorizations  => 'authorizations',
+    :Pagination      => 'pagination',
     :PageLinks       => 'page_links',
     :PageIterator    => 'page_iterator',
     :PagedRequest    => 'paged_request',

data/lib/github_api/activity.rb

@@ -10,29 +10,24 @@ module Github
       :Starring      => 'starring',
       :Watching      => 'watching'
 
-    # Create new Activity API
-    def initialize(options = {})
-      super(options)
-    end
-
     # Access to Activity::Events API
-    def events(options = {})
-      @events ||= ApiFactory.new 'Activity::Events', options
+    def events(options={}, &block)
+      @events ||= ApiFactory.new('Activity::Events', current_options.merge(options), &block)
     end
 
     # Access to Activity::Notifications API
-    def notifications
-      @notifications ||= ApiFactory.new 'Activity::Notifications'
+    def notifications(options={}, &block)
+      @notifications ||= ApiFactory.new('Activity::Notifications', current_options.merge(options), &block)
     end
 
     # Access to Activity::Starring API
-    def starring
-      @starring ||= ApiFactory.new 'Activity::Starring'
+    def starring(options={}, &block)
+      @starring ||= ApiFactory.new('Activity::Starring', current_options.merge(options), &block)
     end
 
     # Access to Activity::Watching API
-    def watching
-      @watching ||= ApiFactory.new 'Activity::Watching'
+    def watching(options={}, &block)
+      @watching ||= ApiFactory.new('Activity::Watching', current_options.merge(options), &block)
     end
 
   end # Activity

data/lib/github_api/activity/events.rb

@@ -3,11 +3,6 @@
 module Github
   class Activity::Events < API
 
-    # Creates new Activity::Events API
-    def initialize(options = {})
-      super(options)
-    end
-
     # List all public events
     #
     # = Examples

data/lib/github_api/activity/notifications.rb

@@ -3,11 +3,6 @@
 module Github
   class Activity::Notifications < API
 
-    # Creates new Activity::Notifications API
-    def initialize(options = {})
-      super(options)
-    end
-
     # List your notifications
     #
     # List all notifications for the current user, grouped by repository.

data/lib/github_api/api.rb

@@ -21,45 +21,55 @@ module Github
     include Connection
     include Request
     include RateLimit
+    # include Configuration
 
     # TODO consider these optional in a stack
     include Validations
     include ParameterFilter
     include Normalizer
 
-    attr_reader *Configuration::VALID_OPTIONS_KEYS
+    attr_reader *Configuration.keys
 
     attr_accessor *VALID_API_KEYS
 
-    # Callback to update global configuration options
-    class_eval do
-      Configuration::VALID_OPTIONS_KEYS.each do |key|
-        define_method "#{key}=" do |arg|
-          self.instance_variable_set("@#{key}", arg)
-          Github.send("#{key}=", arg)
-        end
-      end
-    end
+    attr_accessor :current_options
+
+    # Callback to update current configuration options
+     class_eval do
+       Configuration.keys.each do |key|
+         define_method "#{key}=" do |arg|
+           self.instance_variable_set("@#{key}", arg)
+           self.current_options.merge!({:"#{key}" => arg})
+         end
+       end
+     end
 
-    # Creates new API
+    # Create new API
+    #
     def initialize(options={}, &block)
-      super()
-      setup options
-      set_api_client
-      client if client_id? && client_secret?
+      setup(options)
+      client(options) if client_id? && client_secret?
+      yield_or_eval(&block) if block_given?
+    end
 
-      self.instance_eval(&block) if block_given?
+    def yield_or_eval(&block)
+      return unless block
+      block.arity > 0 ? yield(self) : self.instance_eval(&block)
     end
 
+    # Configure options and process basic authorization
+    #
     def setup(options={})
       options = Github.options.merge(options)
-      Configuration::VALID_OPTIONS_KEYS.each do |key|
+      self.current_options = options
+      Configuration.keys.each do |key|
         send("#{key}=", options[key])
       end
       process_basic_auth(options[:basic_auth])
     end
 
     # Extract login and password from basic_auth parameter
+    #
     def process_basic_auth(auth)
       case auth
       when String
@@ -70,11 +80,6 @@ module Github
       end
     end
 
-    # Assigns current api class
-    def set_api_client
-      Github.api_client = self
-    end
-
     # Responds to attribute query or attribute clear
     def method_missing(method, *args, &block) # :nodoc:
       case method.to_s

data/lib/github_api/api_factory.rb

@@ -6,25 +6,26 @@ module Github
   class ApiFactory
 
     # Instantiates a new github api object
-    def self.new(klass, options={})
-      return create_instance(klass, options) if klass
-      raise ArgumentError, 'must provied klass to be instantiated'
+    #
+    def self.new(klass, options={}, &block)
+      return create_instance(klass, options, &block) if klass
+      raise ArgumentError, 'must provide API class to be instantiated'
     end
 
     # Passes configuration options to instantiated class
-    def self.create_instance(klass, options)
+    #
+    def self.create_instance(klass, options, &block)
       options.symbolize_keys!
-      instance = convert_to_constant(klass.to_s).new options
-      Github.api_client = instance
-      instance
+      convert_to_constant(klass.to_s).new options, &block
     end
 
+    # Convert name to constant
+    #
     def self.convert_to_constant(classes)
-      constant = Github
-      classes.split('::').each do |klass|
-        constant = constant.const_get klass
+      classes.split('::').inject(Github) do |constant, klass|
+        constant.const_get klass
       end
-      return constant
     end
-  end
+
+  end # ApiFactory
 end # Github

data/lib/github_api/authorizations.rb

@@ -13,11 +13,6 @@ module Github
       client_secret
     ].freeze
 
-    # Creates new OAuth Authorizations API
-    def initialize(options = {})
-      super(options)
-    end
-
     # List authorizations
     #
     # = Examples

data/lib/github_api/client.rb

@@ -6,82 +6,82 @@ module Github
     # Serving up the ‘social’ in Social Coding™, the Activity APIs
     # provide access to notifications, subscriptions, and timelines.
     #
-    def activity(options = {})
-      @activity ||= ApiFactory.new 'Activity', options
+    def activity(options={}, &block)
+      @activity ||= ApiFactory.new('Activity', current_options.merge(options), &block)
     end
 
-    def emojis(options = {})
-      @emojis ||= ApiFactory.new 'Emojis', options
+    def emojis(options={}, &block)
+      @emojis ||= ApiFactory.new('Emojis', current_options.merge(options), &block)
     end
 
-    def gists(options = {})
-      @gists ||= ApiFactory.new 'Gists', options
+    def gists(options={}, &block)
+      @gists ||= ApiFactory.new('Gists', current_options.merge(options), &block)
     end
 
-    def gitignore(options = {})
-      @gitignore ||= ApiFactory.new 'Gitignore', options
+    def gitignore(options={}, &block)
+      @gitignore ||= ApiFactory.new('Gitignore', current_options.merge(options), &block)
     end
     alias :git_ignore :gitignore
 
     # The Git Database API gives you access to read and write raw Git objects
     # to your Git database on GitHub and to list and update your references
     # (branch heads and tags).
-    def git_data(options = {})
-      @git_data ||= ApiFactory.new 'GitData', options
+    def git_data(options={}, &block)
+      @git_data ||= ApiFactory.new('GitData', current_options.merge(options), &block)
     end
     alias :git :git_data
 
-    def issues(options = {})
-      @issues ||= ApiFactory.new 'Issues', options
+    def issues(options={}, &block)
+      @issues ||= ApiFactory.new('Issues', current_options.merge(options), &block)
     end
 
-    def markdown(options = {})
-      @markdown ||= ApiFactory.new 'Markdown', options
+    def markdown(options={}, &block)
+      @markdown ||= ApiFactory.new('Markdown', current_options.merge(options), &block)
     end
 
-    def meta(options = {})
-      @meta ||= ApiFactory.ew 'Meta', options
+    def meta(options={}, &block)
+      @meta ||= ApiFactory.new('Meta', current_options.merge(options), &block)
     end
 
     # An API for users to manage their own tokens. You can only access your own
     # tokens, and only through Basic Authentication.
-    def oauth(options = {})
-      @oauth ||= ApiFactory.new 'Authorizations', options
+    def oauth(options={}, &block)
+      @oauth ||= ApiFactory.new('Authorizations', current_options.merge(options), &block)
     end
     alias :authorizations :oauth
 
-    def orgs(options = {})
-      @orgs ||= ApiFactory.new 'Orgs', options
+    def orgs(options={}, &block)
+      @orgs ||= ApiFactory.new('Orgs', current_options.merge(options), &block)
     end
     alias :organizations :orgs
 
-    def pull_requests(options = {})
-      @pull_requests ||= ApiFactory.new 'PullRequests', options
+    def pull_requests(options={}, &block)
+      @pull_requests ||= ApiFactory.new('PullRequests', current_options.merge(options), &block)
     end
     alias :pulls :pull_requests
 
-    def repos(options = {})
-      @repos ||= ApiFactory.new 'Repos', options
+    def repos(options={}, &block)
+      @repos ||= ApiFactory.new('Repos', current_options.merge(options), &block)
     end
     alias :repositories :repos
 
-    def octocat(options = {})
-      @octocat ||= ApiFactory.new 'Say', options
+    def octocat(options={}, &block)
+      @octocat ||= ApiFactory.new('Say', current_options.merge(options), &block)
     end
 
-    def scopes(options = {})
-      @scopes ||= ApiFactory.new 'Scopes', options
+    def scopes(options={}, &block)
+      @scopes ||= ApiFactory.new('Scopes', current_options.merge(options), &block)
     end
 
-    def search(options = {})
-      @search ||= ApiFactory.new 'Search', options
+    def search(options={}, &block)
+      @search ||= ApiFactory.new('Search', current_options.merge(options), &block)
     end
 
-    # Many of the resources on the users API provide a shortcut for getting 
+    # Many of the resources on the users API provide a shortcut for getting
     # information about the currently authenticated user.
     #
-    def users(options = {})
-      @users ||= ApiFactory.new 'Users', options
+    def users(options={}, &block)
+      @users ||= ApiFactory.new('Users', current_options.merge(options), &block)
     end
 
   end # Client