octokit 1.25.0 → 2.0.0.pre

data/lib/octokit/client/legacy_search.rb

@@ -0,0 +1,78 @@
+module Octokit
+  class Client
+
+    # Methods for the Legacy Search API
+    #
+    # @see http://developer.github.com/v3/search/
+    module LegacySearch
+
+      # Legacy repository search
+      #
+      # @see http://developer.github.com/v3/search/#search-repositories
+      # @param q [String] Search keyword
+      # @return [Array<Sawyer::Resource>] List of repositories found
+      def legacy_search_repositories(q, options={})
+        get("legacy/repos/search/#{q}", options)['repositories']
+      end
+
+      # Legacy repository search
+      #
+      # @deprecated Use {#legacy_search_repositories} instead
+      # @see http://developer.github.com/v3/search/#search-repositories
+      # @param q [String] Search keyword
+      # @return [Array<Sawyer::Resource>] List of repositories found
+      def search_repositories(q, options = {})
+        legacy_search_repositories(q, options)
+      end
+      alias :search_repos :search_repositories
+
+      # Legacy search issues within a repository
+      #
+      # @param repo [String, Repository, Hash] A GitHub repository
+      # @param search_term [String] The term to search for
+      # @param state [String] :state (open) <tt>open</tt> or <tt>closed</tt>.
+      # @return [Array<Sawyer::Resource>] A list of issues matching the search term and state
+      # @example Search for 'test' in the open issues for sferik/rails_admin
+      #   Octokit.search_issues("sferik/rails_admin", 'test', 'open')
+      def legacy_search_issues(repo, search_term, state='open', options={})
+        get("legacy/issues/search/#{Repository.new(repo)}/#{state}/#{search_term}", options)['issues']
+      end
+
+      # Legacy search issues within a repository
+      #
+      # @deprecated Use {#legacy_search_issues} instead
+      # @param repo [String, Repository, Hash] A GitHub repository
+      # @param search_term [String] The term to search for
+      # @param state [String] :state (open) <tt>open</tt> or <tt>closed</tt>.
+      # @return [Array<Sawyer::Resource>] A list of issues matching the search term and state
+      # @example Search for 'test' in the open issues for sferik/rails_admin
+      #   Octokit.search_issues("sferik/rails_admin", 'test', 'open')
+      def search_issues(repo, search_term, state = 'open', options = {})
+        legacy_search_issues(repo, search_term, state, options)
+      end
+
+      # Search for user.
+      #
+      # @param search [String] User to search for.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing users.
+      # @see http://developer.github.com/v3/search/#search-users
+      # @example
+      #   Octokit.search_users('pengwynn')
+      def legacy_search_users(search, options={})
+        get("legacy/user/search/#{search}", options)['users']
+      end
+
+      # Search for user.
+      #
+      # @deprecated Use {#legacy_search_users} instead
+      # @param search [String] User to search for.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing users.
+      # @see http://developer.github.com/v3/search/#search-users
+      # @example
+      #   Octokit.search_users('pengwynn')
+      def search_users(search, options = {})
+        legacy_search_users(search, options = {})
+      end
+    end
+  end
+end

data/lib/octokit/client/markdown.rb

@@ -1,5 +1,9 @@
 module Octokit
   class Client
+
+    # Methods for the Markdown API
+    #
+    # @see http://developer.github.com/v3/markdown/
     module Markdown
 
       # Render an arbitrary Markdown document
@@ -15,7 +19,8 @@ module Octokit
         options[:text] = text
         options[:repo] = Repository.new(options[:repo]) if options[:repo]
         options[:accept] = 'application/vnd.github.raw'
-        request(:post, "markdown", options).body
+
+        post "markdown", options
       end
 
     end

data/lib/octokit/client/meta.rb

@@ -0,0 +1,21 @@
+module Octokit
+  class Client
+
+    # Methods for the Meta API
+    #
+    # @see http://developer.github.com/v3/meta/
+    module Meta
+
+      # Get meta information about GitHub.com, the service.
+      # @see http://developer.github.com/v3/meta/
+      # @return [Sawyer::Resource] Hash with meta information.
+      # @example Get GitHub meta information
+      #   @client.github_meta
+      def meta(options={})
+        get "meta", options
+      end
+      alias :github_meta :meta
+
+    end
+  end
+end

data/lib/octokit/client/milestones.rb

@@ -1,5 +1,9 @@
 module Octokit
   class Client
+
+    # Methods for the Issues Milestones API
+    #
+    # @see http://developer.github.com/v3/issues/milestones/
     module Milestones
 
       # List milestones for a repository
@@ -10,12 +14,12 @@ module Octokit
       # @option options [String] :state (open) State: <tt>open</tt> or <tt>closed</tt>.
       # @option options [String] :sort (created) Sort: <tt>created</tt>, <tt>updated</tt>, or <tt>comments</tt>.
       # @option options [String] :direction (desc) Direction: <tt>asc</tt> or <tt>desc</tt>.
-      # @return [Array] A list of milestones for a repository.
+      # @return [Array<Sawyer::Resource>] A list of milestones for a repository.
       # @see http://developer.github.com/v3/issues/milestones/#List-Milestones-for-an-Issue
       # @example List milestones for a repository
       #   Octokit.list_milestones("pengwynn/octokit")
       def list_milestones(repository, options={})
-        get("repos/#{Repository.new(repository)}/milestones", options)
+        paginate "repos/#{Repository.new(repository)}/milestones", options
       end
       alias :milestones :list_milestones
 
@@ -27,12 +31,12 @@ module Octokit
       # @option options [String] :state (open) State: <tt>open</tt> or <tt>closed</tt>.
       # @option options [String] :sort (created) Sort: <tt>created</tt>, <tt>updated</tt>, or <tt>comments</tt>.
       # @option options [String] :direction (desc) Direction: <tt>asc</tt> or <tt>desc</tt>.
-      # @return [Milestone] A single milestone from a repository.
+      # @return [Sawyer::Resource] A single milestone from a repository.
       # @see http://developer.github.com/v3/issues/milestones/#get-a-single-milestone
       # @example Get a single milestone for a repository
       #   Octokit.milestone("pengwynn/octokit", 1)
       def milestone(repository, number, options={})
-        get("repos/#{Repository.new(repository)}/milestones/#{number}", options)
+        get "repos/#{Repository.new(repository)}/milestones/#{number}", options
       end
 
       # Create a milestone for a repository
@@ -43,12 +47,12 @@ module Octokit
       # @option options [String] :state (open) State: <tt>open</tt> or <tt>closed</tt>.
       # @option options [String] :description A meaningful description
       # @option options [Time] :due_on Set if the milestone has a due date
-      # @return [Milestone] A single milestone object
+      # @return [Sawyer::Resource] A single milestone object
       # @see http://developer.github.com/v3/issues/milestones/#create-a-milestone
       # @example Create a milestone for a repository
       #   Octokit.create_milestone("pengwynn/octokit", "0.7.0", {:description => 'Add support for v3 of Github API'})
       def create_milestone(repository, title, options={})
-        post("repos/#{Repository.new(repository)}/milestones", options.merge({:title => title}))
+        post "repos/#{Repository.new(repository)}/milestones", options.merge({:title => title})
       end
 
       # Update a milestone for a repository
@@ -60,12 +64,12 @@ module Octokit
       # @option options [String] :state (open) State: <tt>open</tt> or <tt>closed</tt>.
       # @option options [String] :description A meaningful description
       # @option options [Time] :due_on Set if the milestone has a due date
-      # @return [Milestone] A single milestone object
+      # @return [Sawyer::Resource] A single milestone object
       # @see http://developer.github.com/v3/issues/milestones/#update-a-milestone
       # @example Update a milestone for a repository
       #   Octokit.update_milestone("pengwynn/octokit", 1, {:description => 'Add support for v3 of Github API'})
       def update_milestone(repository, number, options={})
-        patch("repos/#{Repository.new(repository)}/milestones/#{number}", options)
+        patch "repos/#{Repository.new(repository)}/milestones/#{number}", options
       end
       alias :edit_milestone :update_milestone
 
@@ -79,7 +83,7 @@ module Octokit
       # @example Delete a single milestone from a repository
       #   Octokit.delete_milestone("pengwynn/octokit", 1)
       def delete_milestone(repository, number, options={})
-        boolean_from_response(:delete, "repos/#{Repository.new(repository)}/milestones/#{number}", options)
+        boolean_from_response :delete, "repos/#{Repository.new(repository)}/milestones/#{number}", options
       end
 
     end

data/lib/octokit/client/notifications.rb

@@ -1,167 +1,136 @@
 module Octokit
   class Client
+
+    # Methods for the Notifications API
+    #
+    # @see http://developer.github.com/v3/activity/notifications/
     module Notifications
 
       # List your notifications
       #
       # @param options [Hash] Optional parameters
-      #
       # @option options [Boolean] :all 'true' to show notifications marked as
       #   read.
-      #
       # @option options [Boolean] :participating 'true' to show only
       #   notifications in which the user is directly participating or
       #   mentioned.
-      #
       # @option options [String] :since Time filters out any notifications
       #   updated before the given time. The time should be passed in as UTC in
       #   the ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Ex. '2012-10-09T23:39:01Z'
-      #
-      # @return [Array<Hashie::Mash>] Array of notifications.
-      #
+      # @return [Array<Sawyer::Resource>] Array of notifications.
       # @see http://developer.github.com/v3/activity/notifications/#list-your-notifications
-      #
       # @example Get users notifications
       #   @client.notifications
-      #
       # @example Get all notifications since a certain time.
       #   @client.notifications({all: true, since: '2012-10-09T23:39:01Z'})
       def notifications(options={})
-        get("notifications", options)
+        paginate "notifications", options
       end
 
       # List your notifications in a repository
       #
       # @param repo [String, Hash, Repository] A GitHub repository
       # @param options [Hash] Optional parameters
-      #
       # @option options [Boolean] :all 'true' to show notifications marked as
       #   read.
-      #
       # @option options [Boolean] :participating 'true' to show only
       #   notifications in which the user is directly participating or
       #   mentioned.
-      #
       # @option options [String] :since Time filters out any notifications
       #   updated before the given time. The time should be passed in as UTC in
       #   the ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Ex. '2012-10-09T23:39:01Z'
-      #
-      # @return [Array<Hashie::Mash>] Array of notifications.
-      #
+      # @return [Array<Sawyer::Resource>] Array of notifications.
       # @see http://developer.github.com/v3/activity/notifications/#list-your-notifications-in-a-repository
-      #
       # @example Get your notifications for pengwynn/octokit
       #   @client.repository_notifications('pengwynn/octokit')
-      #
       # @example Get your notifications for pengwynn/octokit since a time.
       #   @client.repository_notifications({since: '2012-10-09T23:39:01Z'})
       def repository_notifications(repo, options={})
-        get("repos/#{Repository.new repo}/notifications", options)
+        paginate "repos/#{Repository.new repo}/notifications", options
       end
       alias :repo_notifications :repository_notifications
 
       # Mark notifications as read
       #
       # @param options [Hash] Optional parameters
-      #
       # @option options [Boolean] :unread Changes the unread status of the
       #   threads.
-      #
       # @option options [Boolean] :read Inverse of 'unread'.
-      #
       # @option options [String] :last_read_at ('Now') Describes the last point
       #   that notifications were checked. Anything updated since this time
       #   will not be updated. The time should be passed in as UTC in the
       #   ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Ex. '2012-10-09T23:39:01Z'
-      #
       # @return [Boolean] True if marked as read, false otherwise
-      #
       # @see http://developer.github.com/v3/activity/notifications/#mark-as-read
       #
       # @example
       #   @client.mark_notifications_as_read
       def mark_notifications_as_read(options={})
-        request(:put, "notifications", options).status == 205
-      rescue Octokit::Error
-        false
+        request :put, "notifications", options
+
+        last_response.status == 205
       end
 
       # Mark notifications from a specific repository as read
       #
       # @param repo [String, Hash, Repository] A GitHub repository
       # @param options [Hash] Optional parameters
-      #
       # @option options [Boolean] :unread Changes the unread status of the
       #   threads.
-      #
       # @option options [Boolean] :read Inverse of 'unread'.
-      #
       # @option options [String] :last_read_at ('Now') Describes the last point
       #   that notifications were checked. Anything updated since this time
       #   will not be updated. The time should be passed in as UTC in the
       #   ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ. Ex. '2012-10-09T23:39:01Z'
-      #
       # @return [Boolean] True if marked as read, false otherwise
-      #
       # @see http://developer.github.com/v3/activity/notifications/#mark-notifications-as-read-in-a-repository
-      #
       # @example
       #   @client.mark_notifications_as_read("pengwynn/octokit")
       def mark_repository_notifications_as_read(repo, options={})
-        request(:put, "repos/#{Repository.new repo}/notifications", options).status == 205
-      rescue Octokit::Error
-        false
+        request :put, "repos/#{Repository.new repo}/notifications", options
+
+        last_response.status == 205
       end
       alias :mark_repo_notifications_as_read :mark_repository_notifications_as_read
 
       # List notifications for a specific thread
       #
       # @param thread_id [Integer] Id of the thread.
-      #
-      # @return [Array<Hashie::Mashie>] Array of notifications.
-      #
+      # @return [Array<Sawyer::Resource>] Array of notifications.
       # @see http://developer.github.com/v3/activity/notifications/#view-a-single-thread
       #
       # @example
       #   @client.notification_thread(1000)
       def thread_notifications(thread_id, options={})
-        get("notifications/threads/#{thread_id}", options)
+        get "notifications/threads/#{thread_id}", options
       end
 
       # Mark thread as read
       #
       # @param thread_id [Integer] Id of the thread to update.
       # @param options [Hash] Optional parameters.
-      #
       # @option options [Boolean] :unread Changes the unread status of the
       #   threads.
-      #
       # @option options [Boolean] :read Inverse of 'unread'.
-      #
       # @return [Boolean] True if updated, false otherwise.
-      #
       # @see http://developer.github.com/v3/activity/notifications/#mark-a-thread-as-read
-      #
       # @example
       #   @client.mark_thread_as_ready(1, :read => false)
       def mark_thread_as_read(thread_id, options={})
-        request(:patch, "notifications/threads/#{thread_id}", options).status == 205
-      rescue Octokit::Error
-        false
+        request :patch, "notifications/threads/#{thread_id}", options
+
+        last_response.status == 205
       end
 
       # Get thread subscription
       #
       # @param thread_id [Integer] Id of the thread.
-      #
-      # @return [Hashie::Mash] Subscription.
-      #
+      # @return [Sawyer::Resource] Subscription.
       # @see http://developer.github.com/v3/activity/notifications/#get-a-thread-subscription
-      #
       # @example
       #   @client.thread_subscription(1)
       def thread_subscription(thread_id, options={})
-        get("notifications/threads/#{thread_id}/subscription", options)
+        get "notifications/threads/#{thread_id}/subscription", options
       end
 
       # Update thread subscription
@@ -173,38 +142,29 @@ module Octokit
       #
       # @param thread_id [Integer] Id of the thread.
       # @param options
-      #
       # @option options [Boolean] :subscribed Determines if notifications
       #   should be received from this repository.
-      #
       # @option options [Boolean] :ignored Deterimines if all notifications
       #   should be blocked from this repository.
-      #
-      # @return [Hashie::Mash] Updated subscription.
-      #
+      # @return [Sawyer::Resource] Updated subscription.
       # @see http://developer.github.com/v3/activity/notifications/#set-a-thread-subscription
-      #
       # @example Subscribe to notifications
       #   @client.update_thread_subscription(1, :subscribed => true)
-      #
       # @example Ignore notifications from a repo
       #   @client.update_thread_subscription(1, :ignored => true)
       def update_thread_subscription(thread_id, options={})
-        put("notifications/threads/#{thread_id}/subscription", options)
+        put "notifications/threads/#{thread_id}/subscription", options
       end
 
       # Delete a thread subscription
       #
       # @param thread_id [Integer] Id of the thread.
-      #
       # @return [Boolean] True if delete successful, false otherwise.
-      #
       # @see http://developer.github.com/v3/activity/notifications/#delete-a-thread-subscription
-      #
       # @example
       #   @client.delete_thread_subscription(1)
       def delete_thread_subscription(thread_id, options={})
-        boolean_from_response(:delete, "notifications/threads/#{thread_id}", options)
+        boolean_from_response :delete, "notifications/threads/#{thread_id}/subscription", options
       end
 
     end

data/lib/octokit/client/objects.rb

@@ -1,5 +1,9 @@
 module Octokit
   class Client
+
+    # Methods for the Git Data API
+    #
+    # @see http://developer.github.com/v3/git/
     module Objects
       # Get a single tree, fetching information about its root-level objects
       #
@@ -7,7 +11,7 @@ module Octokit
       #
       # @param repo [String, Hash, Repository] A GitHub repository
       # @param tree_sha [String] The SHA of the tree to fetch
-      # @return [Hashie::Mash] A hash representing the fetched tree
+      # @return [Sawyer::Resource] A hash representing the fetched tree
       # @see http://developer.github.com/v3/git/trees/
       # @example Fetch a tree and inspect the path of one of its files
       #   tree = Octokit.tree("octocat/Hello-World", "9fb037999f264ba9a7fc6274d15fa3ae2ab98312")
@@ -16,7 +20,7 @@ module Octokit
       #   tree = Octokit.tree("octocat/Hello-World", "fc6274d15fa3ae2ab983129fb037999f264ba9a7")
       #   tree.tree.first.path # => "subdir/file.txt"
       def tree(repo, tree_sha, options={})
-        get("repos/#{Repository.new(repo)}/git/trees/#{tree_sha}", options)
+        get "repos/#{Repository.new(repo)}/git/trees/#{tree_sha}", options
       end
 
       # Create a tree
@@ -25,7 +29,7 @@ module Octokit
       #
       # @param repo [String, Hash, Repository] A GitHub repository
       # @param tree [Array] An array of hashes representing a tree structure
-      # @return [Hashie::Mash] A hash representing the new tree
+      # @return [Sawyer::Resource] A hash representing the new tree
       # @see http://developer.github.com/v3/git/trees/
       # @example Create a tree containing one file
       #   tree = Octokit.create_tree("octocat/Hello-World", [ { :path => "file.rb", :mode => "100644", :type => "blob", :sha => "44b4fc6d56897b048c772eb4087f854f46256132" } ])
@@ -33,14 +37,14 @@ module Octokit
       #   tree.tree.first.path # => "file.rb"
       def create_tree(repo, tree, options={})
         parameters = { :tree => tree }
-        post("repos/#{Repository.new(repo)}/git/trees", options.merge(parameters))
+        post "repos/#{Repository.new(repo)}/git/trees", options.merge(parameters)
       end
 
       # Get a single blob, fetching its content and encoding
       #
       # @param repo [String, Hash, Repository] A GitHub repository
       # @param blob_sha [String] The SHA of the blob to fetch
-      # @return [Hashie::Mash] A hash representing the fetched blob
+      # @return [Sawyer::Resource] A hash representing the fetched blob
       # @see http://developer.github.com/v3/git/blobs/
       # @example Fetch a blob and inspect its contents
       #   blob = Octokit.blob("octocat/Hello-World", "827efc6d56897b048c772eb4087f854f46256132")
@@ -53,7 +57,7 @@ module Octokit
       #   blob.content # => "Rm9vIGJhciBiYXo="
       #   Base64.decode64(blob.content) # => "Foo bar baz"
       def blob(repo, blob_sha, options={})
-        get("repos/#{Repository.new(repo)}/git/blobs/#{blob_sha}", options)
+        get "repos/#{Repository.new(repo)}/git/blobs/#{blob_sha}", options
       end
 
       # Create a blob
@@ -73,19 +77,21 @@ module Octokit
           :content => content,
           :encoding => encoding
         }
-        post("repos/#{Repository.new(repo)}/git/blobs", options.merge(parameters)).sha
+        blob = post "repos/#{Repository.new(repo)}/git/blobs", options.merge(parameters)
+
+        blob.sha
       end
 
       # Get a tag
       #
       # @param repo [String, Hash, Repository] A GitHub repository.
       # @param tag_sha [String] The SHA of the tag to fetch.
-      # @return [Hashie::Mash] Hash representing the tag.
+      # @return [Sawyer::Resource] Hash representing the tag.
       # @see http://developer.github.com/v3/git/tags/#get-a-tag
       # @example Fetch a tag
       #   Octokit.tag('pengwynn/octokit', '23aad20633f4d2981b1c7209a800db3014774e96')
       def tag(repo, tag_sha, options={})
-        get("repos/#{Repository.new repo}/git/tags/#{tag_sha}", options)
+        get "repos/#{Repository.new repo}/git/tags/#{tag_sha}", options
       end
 
       # Create a tag
@@ -101,8 +107,7 @@ module Octokit
       # @param tagger_name [String] Name of the author of the tag.
       # @param tagger_email [String] Email of the author of the tag.
       # @param tagger_date [string] Timestamp of when this object was tagged.
-      # @return [Hashie::Mash] Hash representing new tag.
-      # @see Octokit::Client
+      # @return [Sawyer::Resource] Hash representing new tag.
       # @see http://developer.github.com/v3/git/tags/#create-a-tag-object
       # @example
       #   @client.create_tag(
@@ -127,7 +132,7 @@ module Octokit
             :date => tagger_date
           }
         )
-        post("repos/#{Repository.new repo}/git/tags", options)
+        post "repos/#{Repository.new repo}/git/tags", options
       end
     end
   end