github_api 0.9.0 → 0.9.1

data/README.md

@@ -18,13 +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.
+* Flexible arguments parsing, you can write expressive and natural queries.
 * 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).
+* Custom mime types specification (Status: In Progess)
 * Request results caching (Status: TODO)
-* Fully tested with test coverage above 90% with over 1,400 specs and 700 features.
+* Fully tested with test coverage above 90% with over 1,500 specs and 700 features.
 
 ## Installation
 
@@ -60,11 +60,12 @@ 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 enterprise endpoint like
+Alternatively, you can configure the Github settings by passing a block, for instance, with custom enterprise endpoint and website like
 
 ```ruby
 github = Github.new do |config|
   config.endpoint    = 'https://github.company.com/api/v3'
+  config.site        = 'https://github.company.com'
   config.oauth_token = 'token'
   config.adapter     = :net_http
   config.ssl         = {:verify => false}
@@ -110,7 +111,51 @@ repos.branches do |branch|
 end
 ```
 
-## Inputs
+## Arguments & Parameters
+
+The library allows for flexible arguments parsing. Therefore arguments can be passed during instance creation:
+
+```ruby
+  issues = Github::Issues.new user: 'peter-murach', repo: 'github'
+  issues.milestones.list state: 'open'
+```
+
+Further, arguments can be passed directly inside method called but then the order of parameters matters and hence please consult the method documentation or GitHub specification. For instance:
+
+```ruby
+  issues = Github::Issues.new
+  issues.milestones.list 'peter-murach', 'github', state: 'open'
+```
+
+Similarly, the arguments for the request can be passed inside the current scope such as:
+
+```ruby
+  issues = Github::Issues.new
+  issues.milestones(user: 'peter-murach', repo: 'github').list
+```
+
+But why limit ourselves? You can mix and match arguments, for example:
+
+```ruby
+  issues = Github::Issues.new user: 'peter-murach'
+  issues.milestones(repo: 'github').list
+  issues.milestones(repo: 'tty').list
+```
+
+Finally, you can use a bit of syntactic sugar common among ruby libraries whereby "username/repository" can be passed as well:
+
+```ruby
+  issues = Github::Issues.new
+  issues.milestones('peter-murach/github').list
+  issues.milestones.list 'peter-murach/github'
+```
+
+Finally, use `with` scope to clearly denote your requests
+
+```ruby
+  issues = Github::Issues.new
+  issues.milestones.with(user:'peter-murach', repo: 'github').list
+```
 
 Some API methods apart from required parameters such as username, repository name
 or organisation name, allow you to switch the way the data is returned to you, for instance

data/features/cassettes/git_data/commits/get.yml

@@ -0,0 +1,69 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://<BASIC_AUTH>@api.github.com/repos/boyan/github/git/commits/aca2a25d442a9545b01f42574c46f59035993b02?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.9.0
+      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:
+      - Tue, 19 Feb 2013 22:32:05 GMT
+      Content-Type:
+      - application/json; charset=utf-8
+      Transfer-Encoding:
+      - chunked
+      Connection:
+      - keep-alive
+      Status:
+      - 200 OK
+      X-Ratelimit-Limit:
+      - '5000'
+      X-Ratelimit-Remaining:
+      - '4999'
+      Vary:
+      - Accept, Authorization, Cookie
+      Cache-Control:
+      - private, max-age=60, s-maxage=60
+      Last-Modified:
+      - Thu, 14 Feb 2013 13:30:02 GMT
+      Etag:
+      - ! '"ebbd81db82247bdc737b6bed8b3a8f14"'
+      X-Github-Media-Type:
+      - github.v3; param=full; format=json
+      X-Content-Type-Options:
+      - nosniff
+      Content-Encoding:
+      - gzip
+    body:
+      encoding: ASCII-8BIT
+      string: !binary |-
+        H4sIAAAAAAAAA7WSwW7cIBRFfwWxapVkDBh7jFdtpar9gK7a6eJhHgbFxhbg
+        NtFo/r04SaMs00hdIb3H5VwdcabJAe0pDCBANEZKAaqRjWbcStEc5SBb2yhW
+        N0rVmgl6Tbc4lYDLeU19VcHqD6PPbtOHYZmriOuSKr3cQ6gex/tRldXsc6r+
+        AQNbdkuk/ZkGmLEQP+2Pko8T3kEwcflVquAMfi/zwPsAz6uDz2VrIO85wXh9
+        w8QNl9943desZ+I7vVzTx04Z/ycjRywVzk+S1WD0YJUWrBlQ1Nx23HDbCoO6
+        xc7KGgDKDN8oeYel6tWQomDGlGDcJa2QElkhO+JDygiGLJakweGMV25J+eph
+        V2YrxISmHKMPkP0SyOTDbTqFU8gOI+p7Yv2dD+PLKz6QLz5/3TT5HIrwNfqE
+        5N1v5yckYclER4TbPeNz4Z9CxHGbID6F3hcfBYshJ9r/eJZpOsWUNkfbSVsf
+        eddJOTSqbg0b2hZFwy3jSvA3yvz7Y9VrMZeflz8/MxWrTQMAAA==
+    http_version: !!null 
+  recorded_at: Tue, 19 Feb 2013 22:32:05 GMT
+recorded_with: VCR 2.4.0

data/features/git_data/commmits.feature

@@ -0,0 +1,14 @@
+Feature: GitData Commits API
+
+  Background:
+    Given I have "Github::GitData::Commits" instance
+
+  Scenario: Gets a single commit
+
+    Given I want to get resource with the following params:
+      | user  | repo   | sha                                      |
+      | boyan | github | aca2a25d442a9545b01f42574c46f59035993b02 |
+    When I make request within a cassette named "git_data/commits/get"
+    Then the response status should be 200
+      And the response type should be JSON
+      And the response should not be empty

data/lib/github_api.rb

@@ -57,6 +57,7 @@ module Github
 
   autoload_all 'github_api',
     :API             => 'api',
+    :Arguments       => 'arguments',
     :Activity        => 'activity',
     :ApiFactory      => 'api_factory',
     :Client          => 'client',

data/lib/github_api/activity/events.rb

@@ -10,10 +10,10 @@ module Github
     #  github.activity.events.public
     #  github.activity.events.public { |event| ... }
     #
-    def public(params={})
-      normalize! params
+    def public(*args)
+      arguments(args)
 
-      response = get_request("/events", params)
+      response = get_request("/events", arguments.params)
       return response unless block_given?
       response.each { |el| yield el }
     end
@@ -28,12 +28,13 @@ module Github
     #  github.activity.events.repository 'user-name', 'repo-name'
     #  github.activity.events.repository 'user-name', 'repo-name' { |event| ... }
     #
-    def repository(user_name, repo_name, params={})
-      set :user => user_name, :repo => repo_name
-      assert_presence_of user, repo
-      normalize! params
+    #  github.events.repository user: 'user-name', repo: 'repo-name'
+    #  github.events.repository user: 'user-name', repo: 'repo-name' {|event| ... }
+    #
+    def repository(*args)
+      arguments(args, :required => [:user, :repo])
 
-      response = get_request("/repos/#{user}/#{repo}/events", params)
+      response = get_request("/repos/#{user}/#{repo}/events", arguments.params)
       return response unless block_given?
       response.each { |el| yield el }
     end
@@ -49,10 +50,12 @@ module Github
     #  github.activity.events.issue 'user-name', 'repo-name'
     #  github.activity.events.issue 'user-name', 'repo-name' { |event| ... }
     #
-    def issue(user_name, repo_name, params={})
-      set :user => user_name, :repo => repo_name
-      assert_presence_of user, repo
-      normalize! params
+    #  github.events.issue user: 'user-name', repo: 'repo-name'
+    #  github.events.issue user: 'user-name', repo: 'repo-name' { |event| ... }
+    #
+    def issue(*args)
+      arguments(args, :required => [:user, :repo])
+      params = arguments.params
 
       response = get_request("/repos/#{user}/#{repo}/issues/events", params)
       return response unless block_given?
@@ -69,12 +72,13 @@ module Github
     #  github.activity.events.network 'user-name', 'repo-name'
     #  github.activity.events.network 'user-name', 'repo-name' { |event| ... }
     #
-    def network(user_name, repo_name, params={})
-      set :user => user_name, :repo => repo_name
-      assert_presence_of user, repo
-      normalize! params
+    #  github.events.network user: 'user-name', repo: 'repo-name'
+    #  github.events.network user: 'user-name', repo: 'repo-name' { |event| ... }
+    #
+    def network(*args)
+      arguments(args, :required => [:user, :repo])
 
-      response = get_request("/networks/#{user}/#{repo}/events", params)
+      response = get_request("/networks/#{user}/#{repo}/events", arguments.params)
       return response unless block_given?
       response.each { |el| yield el }
     end
@@ -90,11 +94,13 @@ module Github
     #  github.activity.events.org 'org-name'
     #  github.activity.events.org 'org-name' { |event| ... }
     #
-    def org(org_name, params={})
-      assert_presence_of org_name
-      normalize! params
+    #  github.events.org org: 'org-name'
+    #  github.events.org org: 'org-name' { |event| ... }
+    #
+    def org(*args)
+      arguments(args, :required => [:org_name])
 
-      response = get_request("/orgs/#{org_name}/events", params)
+      response = get_request("/orgs/#{org_name}/events", arguments.params)
       return response unless block_given?
       response.each { |el| yield el }
     end
@@ -121,16 +127,16 @@ module Github
     #  github.activity.events.received 'user-name', :public => true
     #  github.activity.events.received 'user-name', :public => true { |event| ... }
     #
-    def received(user_name, params={})
-      assert_presence_of user_name
-      normalize! params
+    def received(*args)
+      arguments(args, :required => [:user])
+      params = arguments.params
 
       public_events = if params['public']
         params.delete('public')
         '/public'
       end
 
-      response = get_request("/users/#{user_name}/received_events#{public_events}", params)
+      response = get_request("/users/#{user}/received_events#{public_events}", params)
       return response unless block_given?
       response.each { |el| yield el }
     end
@@ -154,16 +160,16 @@ module Github
     #  github.activity.events.performed 'user-name', :public => true
     #  github.activity.events.performed 'user-name', :public => true { |event| ... }
     #
-    def performed(user_name, params={})
-      assert_presence_of user_name
-      normalize! params
+    def performed(*args)
+      arguments(args, :required => [:user])
+      params = arguments.params
 
       public_events = if params['public']
         params.delete('public')
         '/public'
       end
 
-      response = get_request("/users/#{user_name}/events#{public_events}", params)
+      response = get_request("/users/#{user}/events#{public_events}", params)
       return response unless block_given?
       response.each { |el| yield el }
     end
@@ -180,11 +186,14 @@ module Github
     #  github.activity.events.user_org 'user-name', 'org-name'
     #  github.activity.events.user_org 'user-name', 'org-name' { |event| ... }
     #
-    def user_org(user_name, org_name, params={})
-      assert_presence_of user_name, org_name
-      normalize! params
+    #  github.events.user_org user: 'user-name', org_name: 'org-name'
+    #  github.events.user_org user: 'user-name', org_name: 'org-name' {|event| ...}
+    #
+    def user_org(*args)
+      arguments(args, :required => [:user, :org_name])
+      params = arguments.params
 
-      response = get_request("/users/#{user_name}/events/orgs/#{org_name}", params)
+      response = get_request("/users/#{user}/events/orgs/#{org_name}", params)
       return response unless block_given?
       response.each { |el| yield el }
     end

data/lib/github_api/activity/notifications.rb

@@ -28,9 +28,9 @@ module Github
     #  github.activity.notifications.list user: 'user-name', repo: 'repo-name'
     #
     def list(*args)
-      params = args.extract_options!
-      normalize! params
-      filter! %w[ all participating since user repo], params
+      params = arguments(args) do
+        sift %w[ all participating since user repo]
+      end.params
 
       response = if ( (user_name = params.delete("user")) &&
                       (repo_name = params.delete("repo")) )
@@ -50,10 +50,10 @@ module Github
     #  github.activity.notifications.get 'thread_id'
     #  github.activity.notifications.get 'thread_id' { |thread| ... }
     #
-    def get(thread_id, params={})
-      assert_presence_of thread_id
-      normalize! params
-      response = get_request("/notifications/threads/#{thread_id}", params)
+    def get(*args)
+      arguments(args, :required => [:thread_id])
+
+      response = get_request("/notifications/threads/#{thread_id}", arguments.params)
       return response unless block_given?
       response.each { |el| yield el }
     end
@@ -89,9 +89,9 @@ module Github
     #  github.activity.notifications.mark thread_id: 'id', read: true
     #
     def mark(*args)
-      params = args.extract_options!
-      normalize! params
-      filter! %w[ unread read last_read_at user repo thread_id], params
+      params = arguments(args) do
+        sift %w[ unread read last_read_at user repo thread_id]
+      end.params
 
       if ( (user_name = params.delete("user")) &&
            (repo_name = params.delete("repo")) )
@@ -110,10 +110,10 @@ module Github
     #  github = Github.new oauth_token: 'token'
     #  github.activity.notifications.subscribed? 'thread-id'
     #
-    def subscribed?(thread_id, params={})
-      assert_presence_of thread_id
-      normalize! params
-      get_request("/notifications/threads/#{thread_id}/subscription", params)
+    def subscribed?(*args)
+      arguments(args, :required => [:thread_id])
+
+      get_request("/notifications/threads/#{thread_id}/subscription", arguments.params)
     end
 
     # Create a thread subscription
@@ -134,10 +134,10 @@ module Github
     #    'subscribed': true
     #    'ignored': false
     #
-    def create(thread_id, params={})
-      assert_presence_of thread_id
-      normalize! params
-      put_request("/notifications/threads/#{thread_id}/subscription", params)
+    def create(*args)
+      arguments(args, :required => [:thread_id])
+
+      put_request("/notifications/threads/#{thread_id}/subscription", arguments.params)
     end
 
     # Delete a thread subscription
@@ -146,10 +146,10 @@ module Github
     #  github = Github.new oauth_token: 'token'
     #  github.activity.notifications.delete 'thread_id'
     #
-    def delete(thread_id, params={})
-      assert_presence_of thread_id
-      normalize! params
-      delete_request("/notifications/threads/#{thread_id}/subscription", params)
+    def delete(*args)
+      arguments(args, :required => [:thread_id])
+
+      delete_request("/notifications/threads/#{thread_id}/subscription", arguments.params)
     end
     alias :remove :delete
 

data/lib/github_api/activity/starring.rb

@@ -12,12 +12,10 @@ module Github
     #  github.activity.starring.list
     #  github.activity.starring.list { |star| ... }
     #
-    def list(user_name, repo_name, params={})
-      set :user => user_name, :repo => repo_name
-      assert_presence_of user, repo
-      normalize! params
+    def list(*args)
+      arguments(args, :required => [:user, :repo])
 
-      response = get_request("/repos/#{user}/#{repo}/stargazers", params)
+      response = get_request("/repos/#{user}/#{repo}/stargazers", arguments.params)
       return response unless block_given?
       response.each { |el| yield el }
     end
@@ -36,8 +34,7 @@ module Github
     #  github.activity.starring.starred
     #
     def starred(*args)
-      params = args.extract_options!
-      normalize! params
+      params = arguments(args).params
 
       response = if (user_name = params.delete('user'))
         get_request("/users/#{user_name}/starred", params)
@@ -56,10 +53,10 @@ module Github
     #  github = Github.new
     #  github.activity.starring.starring? 'user-name', 'repo-name'
     #
-    def starring?(user_name, repo_name, params={})
-      assert_presence_of user_name, repo_name
-      normalize! params
-      get_request("/user/starred/#{user_name}/#{repo_name}", params)
+    def starring?(*args)
+      arguments(args, :required => [:user, :repo])
+
+      get_request("/user/starred/#{user}/#{repo}", arguments.params)
       true
     rescue Github::Error::NotFound
       false
@@ -73,11 +70,10 @@ module Github
     #  github = Github.new
     #  github.activity.starring.star 'user-name', 'repo-name'
     #
-    def star(user_name, repo_name, params={})
-      set :user => user_name, :repo => repo_name
-      assert_presence_of user_name, repo_name
-      normalize! params
-      put_request("/user/starred/#{user_name}/#{repo_name}", params)
+    def star(*args)
+      arguments(args, :required => [:user, :repo])
+
+      put_request("/user/starred/#{user}/#{repo}", arguments.params)
     end
 
     # Unstar a repository
@@ -88,11 +84,10 @@ module Github
     #  github = Github.new
     #  github.activity.starring.unstar 'user-name', 'repo-name'
     #
-    def unstar(user_name, repo_name, params={})
-      set :user => user_name, :repo => repo_name
-      assert_presence_of user_name, repo_name
-      normalize! params
-      delete_request("/user/starred/#{user_name}/#{repo_name}", params)
+    def unstar(*args)
+      arguments(args, :required => [:user, :repo])
+
+      delete_request("/user/starred/#{user}/#{repo}", arguments.params)
     end
 
   end # Activity::Starring