octokit 1.25.0 → 2.0.0.pre

data/lib/octokit/client/contents.rb

@@ -2,18 +2,22 @@ require 'base64'
 
 module Octokit
   class Client
+
+    # Methods for the Repo Contents API
+    #
+    # @see http://developer.github.com/v3/repos/contents/
     module Contents
 
       # Receive the default Readme for a repository
       #
       # @param repo [String, Repository, Hash] A GitHub repository
       # @option options [String] :ref name of the Commit/Branch/Tag. Defaults to “master”.
-      # @return [Hash] The detail of the readme
+      # @return [Sawyer::Resource] The detail of the readme
       # @see http://developer.github.com/v3/repos/contents/
       # @example Get the readme file for a repo
       #   Octokit.readme("pengwynn/octokit")
       def readme(repo, options={})
-        get("repos/#{Repository.new repo}/readme", options)
+        get "repos/#{Repository.new repo}/readme", options
       end
 
       # Receive a listing of a repository folder or the contents of a file
@@ -21,26 +25,27 @@ module Octokit
       # @param repo [String, Repository, Hash] A GitHub repository
       # @option options [String] :path A folder or file path
       # @option options [String] :ref name of the Commit/Branch/Tag. Defaults to “master”.
-      # @return [Hash] The contents of a file or list of the files in the folder
+      # @return [Sawyer::Resource] The contents of a file or list of the files in the folder
       # @see http://developer.github.com/v3/repos/contents/
       # @example List the contents of lib/octokit.rb
       #   Octokit.contents("pengwynn/octokit", :path => 'lib/octokit.rb')
       def contents(repo, options={})
         repo_path = options.delete :path
         url = "repos/#{Repository.new repo}/contents/#{repo_path}"
-        get(url, options)
+        get url, options
       end
       alias :content :contents
 
       # Add content to a repository
       #
-      # @param repo [String, Repository, Hash] A GitHub repository
-      # @param path [String] A path for the new content
-      # @param message [String] A commit message for adding the content
-      # @param optional content [String] The Base64-encoded content for the file
-      # @option options [String] :branch The branch on which to add the content
-      # @option options [String] :file Path or Ruby File object for content
-      # @return [Hash] The contents and commit info for the addition
+      # @overload create_contents(repo, path, message, content = nil, options = {})
+      #   @param repo [String, Repository, Hash] A GitHub repository
+      #   @param path [String] A path for the new content
+      #   @param message [String] A commit message for adding the content
+      #   @param optional content [String] The Base64-encoded content for the file
+      #   @option options [String] :branch The branch on which to add the content
+      #   @option options [String] :file Path or Ruby File object for content
+      # @return [Sawyer::Resource] The contents and commit info for the addition
       # @see http://developer.github.com/v3/repos/contents/#create-a-file
       # @example Add content at lib/octokit.rb
       #   Octokit.create_contents("pengwynn/octokit",
@@ -68,10 +73,10 @@ module Octokit
           end
         end
         raise ArgumentError.new "content or :file option required" if content.nil?
-        options[:content] = Base64.encode64(content).delete("\r\n")
+        options[:content] = Base64.encode64(content)
         options[:message] = message
         url = "repos/#{Repository.new repo}/contents/#{path}"
-        put(url, options)
+        put url, options
       end
       alias :create_content :create_contents
       alias :add_content :create_contents
@@ -79,14 +84,15 @@ module Octokit
 
       # Update content in a repository
       #
-      # @param repo [String, Repository, Hash] A GitHub repository
-      # @param path [String] A path for the content to update
-      # @param message [String] A commit message for updating the content
-      # @param sha [String] The _blob sha_ of the content to update
-      # @param content [String] The Base64-encoded content for the file
-      # @option options [String] :branch The branch on which to update the content
-      # @option options [String] :file Path or Ruby File object for content
-      # @return [Hash] The contents and commit info for the update
+      # @overload update_contents(repo, path, message, sha, content = nil, options = {})
+      #   @param repo [String, Repository, Hash] A GitHub repository
+      #   @param path [String] A path for the content to update
+      #   @param message [String] A commit message for updating the content
+      #   @param sha [String] The _blob sha_ of the content to update
+      #   @param content [String] The Base64-encoded content for the file
+      #   @option options [String] :branch The branch on which to update the content
+      #   @option options [String] :file Path or Ruby File object for content
+      # @return [Sawyer::Resource] The contents and commit info for the update
       # @see http://developer.github.com/v3/repos/contents/#update-a-file
       # @example Update content at lib/octokit.rb
       #   Octokit.update_contents("pengwynn/octokit",
@@ -114,7 +120,7 @@ module Octokit
       # @param message [String] A commit message for deleting the content
       # @param sha [String] The _blob sha_ of the content to delete
       # @option options [String] :branch The branch on which to delete the content
-      # @return [Hash] The commit info for the delete
+      # @return [Sawyer::Resource] The commit info for the delete
       # @see http://developer.github.com/v3/repos/contents/#delete-a-file
       # @example Delete content at lib/octokit.rb
       #   Octokit.delete_contents("pengwynn/octokit",
@@ -126,7 +132,7 @@ module Octokit
         options[:message] = message
         options[:sha] = sha
         url = "repos/#{Repository.new repo}/contents/#{path}"
-        delete(url, options)
+        delete url, options
       end
       alias :delete_content :delete_contents
       alias :remove_content :delete_contents
@@ -145,7 +151,9 @@ module Octokit
         repo_ref = options.delete :ref
         format = (options.delete :format) || 'tarball'
         url = "repos/#{Repository.new repo}/#{format}/#{repo_ref}"
-        request(:head, url, options).env[:url].to_s
+        request :head, url, options
+
+        last_response.headers['Location']
       end
 
     end

data/lib/octokit/client/downloads.rb

@@ -1,5 +1,9 @@
 module Octokit
   class Client
+
+    # Methods for the Repo Downloads API
+    #
+    # @see http://developer.github.com/v3/repos/downloads/
     module Downloads
 
       # List available downloads for a repository
@@ -11,7 +15,7 @@ module Octokit
       # @example List all downloads for Github/Hubot
       #   Octokit.downloads("github/hubot")
       def downloads(repo, options={})
-        get("repos/#{Repository.new(repo)}/downloads", options)
+        get "repos/#{Repository.new(repo)}/downloads", options
       end
       alias :list_downloads :downloads
 
@@ -19,13 +23,13 @@ module Octokit
       #
       # @param repo [String, Repository, Hash] A GitHub repository
       # @param id [Integer] ID of the download
-      # @return [Download] A single download from the repository
+      # @return [Sawyer::Resource] A single download from the repository
       # @deprecated As of December 11th, 2012: https://github.com/blog/1302-goodbye-uploads
       # @see http://developer.github.com/v3/repos/downloads/#get-a-single-download
       # @example Get the "Robawt" download from Github/Hubot
       #   Octokit.download("github/hubot")
       def download(repo, id, options={})
-        get("repos/#{Repository.new(repo)}/downloads/#{id}", options)
+        get "repos/#{Repository.new(repo)}/downloads/#{id}", options
       end
 
       # Create a download in a repository
@@ -34,7 +38,7 @@ module Octokit
       # @param name [String, Repository, Hash] A display name for the download
       # @option options [String] :description The download description
       # @option options [String] :content_type The content type. Defaults to 'text/plain'
-      # @return [Download] A single download from the repository
+      # @return [Sawyer::Resource] A single download from the repository
       # @deprecated As of December 11th, 2012: https://github.com/blog/1302-goodbye-uploads
       # @see http://developer.github.com/v3/repos/downloads/#create-a-new-download-part-1-create-the-resource
       # @example Create the "Robawt" download on Github/Hubot
@@ -56,7 +60,7 @@ module Octokit
           'file' => file
         }
 
-        conn = Faraday.new(resource.s3_url) do |builder|
+        conn = Faraday.new(resource.rels[:s3].href) do |builder|
           builder.request :multipart
           builder.request :url_encoded
           builder.adapter :net_http
@@ -76,12 +80,12 @@ module Octokit
       # @example Get the "Robawt" download from Github/Hubot
       #   Octokit.delete_download("github/hubot", 1234)
       def delete_download(repo, id)
-        boolean_from_response(:delete, "repos/#{Repository.new(repo)}/downloads/#{id}")
+        boolean_from_response :delete, "repos/#{Repository.new(repo)}/downloads/#{id}"
       end
 
       private
       def create_download_resource(repo, name, size, options={})
-        post("repos/#{Repository.new(repo)}/downloads", options.merge({:name => name, :size => size}))
+        post "repos/#{Repository.new(repo)}/downloads", options.merge({:name => name, :size => size})
       end
     end
   end

data/lib/octokit/client/emojis.rb

@@ -1,9 +1,11 @@
 module Octokit
   class Client
+
+    # Methods for the the unpublished Emojis API
     module Emojis
       # List all emojis used on GitHub
       #
-      # @return [Hash] A list of all emojis on GitHub
+      # @return [Sawyer::Resource] A list of all emojis on GitHub
       # @example List all emojis
       #   Octokit.emojis
       def emojis

data/lib/octokit/client/events.rb

@@ -1,77 +1,82 @@
 module Octokit
   class Client
+
+    # Method for the Events API
+    #
+    # @see http://developer.github.com/v3/activity/events/
+    # @see http://developer.github.com/v3/issues/events/
     module Events
       # List all public events for GitHub
       #
-      # @return [Array] A list of all public events from GitHub
+      # @return [Array<Sawyer::Resource>] A list of all public events from GitHub
       # @see http://developer.github.com/v3/activity/events/#list-public-events
       # @example List all pubilc events
       #   Octokit.public_events
       def public_events(options={})
-        get("events", options)
+        paginate "events", options
       end
 
       # List all user events
       #
-      # @return [Array] A list of all user events
+      # @return [Array<Sawyer::Resource>] A list of all user events
       # @see http://developer.github.com/v3/activity/events/#list-events-performed-by-a-user
       # @example List all user events
       #   Octokit.user_events("sferik")
       def user_events(user, options={})
-        get("users/#{user}/events", options)
+        paginate "users/#{user}/events", options
       end
 
       # List public user events
       #
       # @param user [String] GitHub username
-      # @return [Array] A list of public user events
+      # @return [Array<Sawyer::Resource>] A list of public user events
       # @see http://developer.github.com/v3/activity/events/#list-public-events-performed-by-a-user
       # @example List public user events
       #   Octokit.user_events("sferik")
       def user_public_events(user, options={})
-        get("users/#{user}/events/public", options)
+        paginate "users/#{user}/events/public", options
       end
 
       # List events that a user has received
       #
-      # @return [Array] A list of all user received events
+      # @return [Array<Sawyer::Resource>] A list of all user received events
       # @see http://developer.github.com/v3/activity/events/#list-events-that-a-user-has-received
       # @example List all user received events
       #   Octokit.received_events("sferik")
       def received_events(user, options={})
-        get("users/#{user}/received_events", options)
+        paginate "users/#{user}/received_events", options
       end
 
       # List public events a user has received
       #
-      # @return [Array] A list of public user received events
+      # @return [Array<Sawyer::Resource>] A list of public user received events
       # @see http://developer.github.com/v3/activity/events/#list-public-events-that-a-user-has-received
       # @example List public user received events
       #   Octokit.received_public_events("sferik")
       def received_public_events(user, options={})
-        get("users/#{user}/received_events/public", options)
+        paginate "users/#{user}/received_events/public", options
       end
 
       # List events for a repository
       #
       # @param repo [String, Repository, Hash] A GitHub repository
-      # @return [Array] A list of events for a repository
+      # @return [Array<Sawyer::Resource>] A list of events for a repository
       # @see http://developer.github.com/v3/activity/events/#list-repository-events
       # @example List events for a repository
       #   Octokit.repository_events("sferik/rails_admin")
       def repository_events(repo, options={})
-        get("repos/#{Repository.new(repo)}/events", options)
+        paginate "repos/#{Repository.new(repo)}/events", options
       end
 
       # List public events for a repository's network
       #
       # @param repo [String, Repository, Hash] A GitHub repository
-      # @return [Array] A list of events for a repository's network
+      # @return [Array<Sawyer::Resource>] A list of events for a repository's network
       # @see http://developer.github.com/v3/activity/events/#list-public-events-for-a-network-of-repositories
       # @example List events for a repository's network
       #   Octokit.repository_network_events("sferik/rails_admin")
       def repository_network_events(repo, options={})
-        get("networks/#{Repository.new repo}/events", options)
+        paginate "networks/#{Repository.new repo}/events", options
       end
 
       # List all events for an organization
@@ -79,23 +84,62 @@ module Octokit
       # Requires authenticated client.
       #
       # @param org [String] Organization GitHub handle
-      # @return [Array] List of all events from a GitHub organization
+      # @return [Array<Sawyer::Resource>] List of all events from a GitHub organization
       # @see http://developer.github.com/v3/activity/events/#list-events-for-an-organization
       # @example List events for the lostisland organization
       #   @client.organization_events("lostisland")
       def organization_events(org, options={})
-        get("users/#{login}/events/orgs/#{org}", options)
+        paginate "users/#{login}/events/orgs/#{org}", options
       end
 
       # List an organization's public events
       #
       # @param org [String] Organization GitHub username
-      # @return [Array] List of public events from a GitHub organization
+      # @return [Array<Sawyer::Resource>] List of public events from a GitHub organization
       # @see http://developer.github.com/v3/activity/events/#list-public-events-for-an-organization
       # @example List public events for GitHub
       #   Octokit.organization_public_events("GitHub")
       def organization_public_events(org, options={})
-        get("orgs/#{org}/events", options)
+        paginate "orgs/#{org}/events", options
+      end
+
+      # Get all Issue Events for a given Repository
+      #
+      # @param repo [String, Repository, Hash] A GitHub repository
+      #
+      # @return [Array<Sawyer::Resource>] Array of all Issue Events for this Repository
+      # @see http://developer.github.com/v3/issues/events/#list-events-for-a-repository
+      # @example Get all Issue Events for Octokit
+      #   Octokit.repository_issue_events("pengwynn/octokit")
+      def repository_issue_events(repo, options={})
+        paginate "repos/#{Repository.new repo}/issues/events", options
+      end
+      alias :repo_issue_events :repository_issue_events
+
+      # List events for an Issue
+      #
+      # @param repo [String, Repository, Hash] A GitHub repository
+      # @param number [Integer] Issue number
+      #
+      # @return [Array<Sawyer::Resource>] Array of events for that issue
+      # @see http://developer.github.com/v3/issues/events/#list-events-for-an-issue
+      # @example List all issues events for issue #38 on pengwynn/octokit
+      #   Octokit.issue_events("pengwynn/octokit", 38)
+      def issue_events(repo, number, options={})
+        paginate "repos/#{Repository.new(repo)}/issues/#{number}/events", options
+      end
+
+      # Get information on a single Issue Event
+      #
+      # @param repo [String, Repository, Hash] A GitHub repository
+      # @param number [Integer] Event number
+      #
+      # @return [Sawyer::Resource] A single Event for an Issue
+      # @see http://developer.github.com/v3/issues/events/#get-a-single-event
+      # @example Get Event information for ID 3094334 (a pull request was closed)
+      #   Octokit.issue_event("pengwynn/octokit", 3094334)
+      def issue_event(repo, number, options={})
+        paginate "repos/#{Repository.new(repo)}/issues/events/#{number}", options
       end
 
     end

data/lib/octokit/client/gists.rb

@@ -1,11 +1,15 @@
 module Octokit
   class Client
+
+    # Methods for the Gists API
+    #
+    # @see http://developer.github.com/v3/gists/
     module Gists
 
       # List gists for a user or all public gists
       #
-      # @param username [String] An optional user to filter listing 
-      # @return [Array<Hashie::Mash>] A list of gists
+      # @param username [String] An optional user to filter listing
+      # @return [Array<Sawyer::Resource>] A list of gists
       # @example Fetch all gists for defunkt
       #   Octokit.gists('defunkt')
       # @example Fetch all public gists
@@ -13,34 +17,34 @@ module Octokit
       # @see http://developer.github.com/v3/gists/#list-gists
       def gists(username=nil, options={})
         if username.nil?
-          get 'gists', options
+          paginate 'gists', options
         else
-          get "users/#{username}/gists", options
+          paginate "users/#{username}/gists", options
         end
       end
       alias :list_gists :gists
 
       # List public gists
       #
-      # @return [Array<Hashie::Mash>] A list of gists
+      # @return [Array<Sawyer::Resource>] A list of gists
       # @example Fetch all public gists
       #   Octokit.public_gists
       # @see http://developer.github.com/v3/gists/#list-gists
       def public_gists(options={})
-        get 'gists/public', options
+        paginate 'gists/public', options
       end
 
       # List the authenticated user’s starred gists
       #
-      # @return [Array<Hashie::Mash>] A list of gists
+      # @return [Array<Sawyer::Resource>] A list of gists
       def starred_gists(options={})
-        get 'gists/starred', options
+        paginate 'gists/starred', options
       end
 
       # Get a single gist
       #
       # @param gist [String] ID of gist to fetch
-      # @return [Hash::Mash] Gist information
+      # @return [Sawyer::Resource] Gist information
       # @see http://developer.github.com/v3/gists/#get-a-single-gist
       def gist(gist, options={})
         get "gists/#{Gist.new gist}", options
@@ -54,7 +58,7 @@ module Octokit
       # @option options [Array<Hash>] :files Files that make up this gist. Keys
       #   should be the filename, the value a Hash with a :content key with text
       #   content of the Gist.
-      # @return [Hashie::Mash] Newly created gist info
+      # @return [Sawyer::Resource] Newly created gist info
       # @see http://developer.github.com/v3/gists/#create-a-gist
       def create_gist(options={})
         post 'gists', options
@@ -67,13 +71,13 @@ module Octokit
       # @option options [Boolean] :public Sets gist visibility
       # @option options [Hash] :files Files that make up this gist. Keys
       #   should be the filename, the value a Hash with a :content key with text
-      #   content of the Gist. 
+      #   content of the Gist.
       #
       #   NOTE: All files from the previous version of the
       #   gist are carried over by default if not included in the hash. Deletes
-      #   can be performed by including the filename with a null hash.  
+      #   can be performed by including the filename with a null hash.
       # @return
-      #   [Hashie::Mash] Newly created gist info
+      #   [Sawyer::Resource] Newly created gist info
       # @see http://developer.github.com/v3/gists/#edit-a-gist
       # @example Update a gist
       #   @client.edit_gist('some_id', {
@@ -90,7 +94,7 @@ module Octokit
       # @return [Boolean] Indicates if gist is starred successfully
       # @see http://developer.github.com/v3/gists/#star-a-gist
       def star_gist(gist, options={})
-        boolean_from_response(:put, "gists/#{Gist.new gist}/star", options)
+        boolean_from_response :put, "gists/#{Gist.new gist}/star", options
       end
 
       # Unstar a gist
@@ -99,7 +103,7 @@ module Octokit
       # @return [Boolean] Indicates if gist is unstarred successfully
       # @see http://developer.github.com/v3/gists/#unstar-a-gist
       def unstar_gist(gist, options={})
-        boolean_from_response(:delete, "gists/#{Gist.new gist}/star", options)
+        boolean_from_response :delete, "gists/#{Gist.new gist}/star", options
       end
 
       # Check if a gist is starred
@@ -108,13 +112,13 @@ module Octokit
       # @return [Boolean] Indicates if gist is starred
       # @see http://developer.github.com/v3/gists/#check-if-a-gist-is-starred
       def gist_starred?(gist, options={})
-        boolean_from_response(:get, "gists/#{Gist.new gist}/star", options)
+        boolean_from_response :get, "gists/#{Gist.new gist}/star", options
       end
 
       # Fork a gist
       #
       # @param gist [String] Gist ID
-      # @return [Hashie::Mash] Data for the new gist
+      # @return [Sawyer::Resource] Data for the new gist
       # @see http://developer.github.com/v3/gists/#fork-a-gist
       def fork_gist(gist, options={})
         post "gists/#{Gist.new gist}/forks", options
@@ -126,25 +130,25 @@ module Octokit
       # @return [Boolean] Indicating success of deletion
       # @see http://developer.github.com/v3/gists/#delete-a-gist
       def delete_gist(gist, options={})
-        boolean_from_response(:delete, "gists/#{Gist.new gist}", options)
+        boolean_from_response :delete, "gists/#{Gist.new gist}", options
       end
 
       # List gist comments
       #
       # @param gist_id [String] Gist Id.
-      # @return [Array<Hashie::Mash>] Array of hashes representing comments.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing comments.
       # @see http://developer.github.com/v3/gists/comments/#list-comments-on-a-gist
       # @example
       #   Octokit.gist_comments('3528ae645')
       def gist_comments(gist_id, options={})
-        get "gists/#{gist_id}/comments", options
+        paginate "gists/#{gist_id}/comments", options
       end
 
       # Get gist comment
       #
       # @param gist_id [String] Id of the gist.
       # @param gist_comment_id [Integer] Id of the gist comment.
-      # @return [Hashie::Mash] Hash representing gist comment.
+      # @return [Sawyer::Resource] Hash representing gist comment.
       # @see http://developer.github.com/v3/gists/comments/#get-a-single-comment
       # @example
       #   Octokit.gist_comment('208sdaz3', 1451398)
@@ -158,8 +162,7 @@ module Octokit
       #
       # @param gist_id [String] Id of the gist.
       # @param comment [String] Comment contents.
-      # @return [Hashie::Mash] Hash representing the new comment.
-      # @see Octokit::Client
+      # @return [Sawyer::Resource] Hash representing the new comment.
       # @see http://developer.github.com/v3/gists/comments/#create-a-comment
       # @example
       #   @client.create_gist_comment('3528645', 'This is very helpful.')
@@ -175,8 +178,7 @@ module Octokit
       # @param gist_id [String] Id of the gist.
       # @param gist_comment_id [Integer] Id of the gist comment to update.
       # @param comment [String] Updated comment contents.
-      # @return [Hashie::Mash] Hash representing the updated comment.
-      # @see Octokit::Client
+      # @return [Sawyer::Resource] Hash representing the updated comment.
       # @see http://developer.github.com/v3/gists/comments/#edit-a-comment
       # @example
       #   @client.update_gist_comment('208sdaz3', '3528645', ':heart:')
@@ -192,7 +194,6 @@ module Octokit
       # @param gist_id [String] Id of the gist.
       # @param gist_comment_id [Integer] Id of the gist comment to delete.
       # @return [Boolean] True if comment deleted, false otherwise.
-      # @see Octokit::Client
       # @see http://developer.github.com/v3/gists/comments/#delete-a-comment
       # @example
       #   @client.delete_gist_comment('208sdaz3', '586399')