octocat_herder 0.0.2 → 0.1.0

data/lib/octocat_herder/pull_request.rb

@@ -6,13 +6,27 @@ require 'octocat_herder/user'
 require 'octocat_herder/pull_request/repo'
 
 class OctocatHerder
-  class PullRequest < Base
+  # Interface to the GitHub v3 API for interacting with pull requests.
+  #
+  # Currently, this only supports retrieval of information about the
+  # pull request itself, not the comments, or any updating/creation.
+  class PullRequest
+    include OctocatHerder::Base
+
+    # Query either the open or closed pull requests for a given
+    # repository.
+    #
+    # @since 0.0.1
+    # @param [String] owner_login The login name of the repository owner.
+    # @param [String] repository_name The name of the repository itself.
+    # @param ['open', 'closed'] status Defaults to querying open pull requests.
+    # @param [OctocatHerder::Connection] conn Defaults to unauthenticated requests.
+    # @return [Array<OctocatHerder::PullRequest>] An array of found pull requests.
     def self.find_for_repository(owner_login, repository_name, status = 'open', conn = OctocatHerder::Connection.new)
       raise ArgumentError.new("Unknown PullRequest status '#{status}'.  Must be one of ['open', 'closed'].") unless
         ['open', 'closed'].include? status
 
-      pull_requests = raw_get(
-        conn,
+      pull_requests = conn.get(
         "/repos/#{CGI.escape(owner_login.to_s)}/#{CGI.escape(repository_name.to_s)}/pulls",
         :paginated => true,
         :params    => { :state => status },
@@ -24,17 +38,38 @@ class OctocatHerder
       end
     end
 
+    # Query the open pull requests for a given repository.
+    #
+    # @since 0.0.1
+    # @param [String] owner_login The login name of the repository owner.
+    # @param [String] repository_name The name of the repository itself.
+    # @param [OctocatHerder::Connection] conn Defaults to unauthenticated requests.
+    # @return [Array<OctocatHerder::PullRequest>] An array of found pull requests.
     def self.find_open_for_repository(owner_login, repository_name, conn = OctocatHerder::Connection.new)
       OctocatHerder::PullRequest.find_for_repository(owner_login, repository_name, 'open', conn)
     end
 
+    # Query the closed pull requests for a given repository.
+    #
+    # @since 0.0.1
+    # @param [String] owner_login The login name of the repository owner.
+    # @param [String] repository_name The name of the repository itself.
+    # @param [OctocatHerder::Connection] conn Defaults to unauthenticated requests.
+    # @return [Array<OctocatHerder::PullRequest>] An array of found pull requests.
     def self.find_closed_for_repository(owner_login, repository_name, conn = OctocatHerder::Connection.new)
       OctocatHerder::PullRequest.find_for_repository(owner_login, repository_name, 'closed', conn)
     end
 
+    # Query information about a specific pull request.
+    #
+    # @since 0.0.1
+    # @param [String] owner_login The login name of the repository owner.
+    # @param [String] repository_name The name of the repository itself.
+    # @param [String, Integer] pull_request_number The pull request to retrieve.
+    # @param [OctocatHerder::Connection] conn Defaults to unauthenticated requests.
+    # @return [OctocatHerder::PullRequest]
     def self.fetch(owner_login, repository_name, pull_request_number, conn = OctocatHerder::Connection.new)
-      request = raw_get(
-        conn,
+      request = conn.get(
         "/repos/#{CGI.escape(owner_login.to_s)}/#{CGI.escape(repository_name.to_s)}/pulls/#{CGI.escape(pull_request_number.to_s)}",
         :headers   => { 'Accept' => 'application/vnd.github-pull.full+json' }
       )
@@ -42,15 +77,29 @@ class OctocatHerder
       new(nil, request, conn)
     end
 
+    # @api private
+    # @since 0.0.1
+    # @param [Hash] raw_hash The 'overview' information retrieved from the pull request listing API.
+    # @param [Hash] raw_detail_hash The full information available by querying information about a specific pull request.
+    # @param [OctocatHerder::Connection] conn Defaults to unauthenticated requests.
     def initialize(raw_hash, raw_detail_hash = nil, conn = OctocatHerder::Connection.new)
       super raw_hash, conn
       @raw_detail_hash = raw_detail_hash
     end
 
+    # Get the full pull request details.  When retrieved from
+    # .find_for_repository, .find_open_for_repository, or
+    # .find_closed_for_repository not all of the details of the pull
+    # request are available since GitHub doesn't return them in the
+    # listing.  This will query information about the specific pull
+    # request, which will get us all of the available details.
+    #
+    # @since 0.0.1
+    # @return [self]
     def get_detail
       return if @raw_detail_hash
 
-      @raw_detail_hash = raw_get(
+      @raw_detail_hash = connection.get(
         url,
         :headers => { 'Accept' => 'application/vnd.github-pull.full+json' }
       )
@@ -58,6 +107,12 @@ class OctocatHerder
       self
     end
 
+    # Check the "normal" place first for the information returned by
+    # the GitHub API, then check +@raw_detail_hash+ (populating it if
+    # needed).
+    #
+    # @since 0.0.1
+    # @return [String]
     def method_missing(id, *args)
       super
     rescue NoMethodError => e
@@ -67,105 +122,212 @@ class OctocatHerder
       raise e
     end
 
-    # Nested data from the "overview" data.
+    # The URL to the avatar image of the person that opened the pull request.
+    #
+    # @note Since this is returned by the pull request API itself, this can be used without making an additional API request.
+    #
+    # @since 0.0.1
+    # @return [String] Avatar URL
     def user_avatar_url
       return @raw['user']['avatar_url'] if @raw
       @raw_detail_hash['user']['avatar_url']
     end
 
+    # The URL of the person that opened the pull request.
+    #
+    # @note Since this is returned by the pull request API itself, this can be used without making an additional API request.
+    #
+    # @since 0.0.1
+    # @return [String] User URL
     def user_url
       return @raw['user']['url'] if @raw
       @raw_detail_hash['user']['url']
     end
 
+    # The ID number of the person that opened the pull request.
+    #
+    # @note Since this is returned by the pull request API itself, this can be used without making an additional API request.
+    #
+    # @since 0.0.1
+    # @return [Integer] User ID
     def user_id
       return @raw['user']['id'] if @raw
       @raw_detail_hash['user']['id']
     end
 
+    # The login name of the person that opened the pull request.
+    #
+    # @note Since this is returned by the pull request API itself, this can be used without making an additional API request.
+    #
+    # @since 0.0.1
+    # @return [String] User login name
     def user_login
       return @raw['user']['login'] if @raw
       @raw_detail_hash['user']['login']
     end
 
-    # Return a real user, instead of a hash with the nested data.
+    # The user that opened the pull request.
+    #
+    # @note This is cached locally to the individual pull request, but will make an additional API request to populate it initially.
+    #
+    # @since 0.0.1
+    # @return [OctocatHerder::User]
     def user
       @user ||= OctocatHerder::User.fetch(user_login, connection)
     end
 
-    # Nested data from the "detail" data.
+    # The login name of the person that merged the pull request, or
+    # +nil+ if it has not been merged yet.
+    #
+    # @since 0.0.1
+    # @return [String, nil]
     def merged_by_login
-      get_detail
+      return nil unless merged
 
+      get_detail
       @raw_detail_hash['merged_by']['login']
     end
 
+    # The ID number of the person that merged the pull request, or
+    # +nil+ if it has not been merged yet.
+    #
+    # @since 0.0.1
+    # @return [String, nil]
     def merged_by_id
-      get_detail
+      return nil unless merged
 
+      get_detail
       @raw_detail_hash['merged_by']['id']
     end
 
+    # The URL to the avatar image of the person that merged the pull
+    # request, or +nil+ if it has not been merged yet.
+    #
+    # @since 0.0.1
+    # @return [String, nil]
     def merged_by_avatar_url
-      get_detail
+      return nil unless merged
 
+      get_detail
       @raw_detail_hash['merged_by']['avatar_url']
     end
 
+    # The URL of the person that merged the pull request, or +nil+ if
+    # it has not been merged yet.
+    #
+    # @since 0.0.1
+    # @return [String, nil]
     def merged_by_url
-      get_detail
+      return nil unless merged
 
+      get_detail
       @raw_detail_hash['merged_by']['url']
     end
 
-    # Return a real user, instead of a hash with the nested data.
+    # The user that merged the pull request, or +nil+ if it has not
+    # been merged yet.
+    #
+    # @note This is cached locally to the individual pull request, but will make an additional API request to populate it initially.
+    #
+    # @since 0.0.1
+    # @return [OctocatHerder::User, nil]
     def merged_by
-      get_detail
+      return nil unless merged
 
       @merged_by ||= OctocatHerder::User.fetch(merged_by_login, connection)
     end
 
-    # Convert a few things to more Ruby friendly Objects
+    # When the pull request was first created.
+    #
+    # @since 0.0.1
+    # @return [Time]
     def created_at
       parse_date_time(@raw_detail_hash['created_at'])
     end
 
+    # When the pull request was last updated.
+    #
+    # @since 0.0.1
+    # @return [Time]
     def updated_at
       parse_date_time(@raw_detail_hash['updated_at'])
     end
 
+    # When the pull request was closed, or +nil+ if it is still open.
+    #
+    # @since 0.0.1
+    # @return [Time, nil]
     def closed_at
       parse_date_time(@raw_detail_hash['closed_at'])
     end
 
+    # When the pull request was merged, or +nil+ if it hasn't been merged.
+    #
+    # @since 0.0.1
+    # @return [Time, nil]
     def merged_at
       parse_date_time(@raw_detail_hash['merged_at'])
     end
 
+    # Information about what is being asked to be merged in the pull
+    # request.
+    #
+    # @since 0.0.1
+    # @return [OctocatHerder::PullRequest::Repo]
     def head
       get_detail
 
       @head_repo ||= OctocatHerder::PullRequest::Repo.new(@raw_detail_hash['head'], connection)
     end
 
+    # Information about what the pull request was based on in the pull
+    # request.
+    #
+    # @since 0.0.1
+    # @return [OctocatHerder::PullRequest::Repo]
     def base
       get_detail
 
       @base_repo ||= OctocatHerder::PullRequest::Repo.new(@raw_detail_hash['base'], connection)
     end
 
-    def additional_attributes
-      attrs = ['user_avatar_url', 'user_url', 'user_id', 'user_login']
-
-      attrs += @raw_detail_hash.keys if @raw_detail_hash
-      attrs += ['merged_by_login', 'merged_by_id', 'merged_by_avatar_url', 'merged_by_url']
-    end
-
+    # A Hash representation of the pull request.  Combines +@raw+, and
+    # +@raw_detail_hash+ into a single hash.
+    #
+    # @since 0.0.2
+    # @return [Hash]
     def to_hash
       raw = @raw || {}
       detail = @raw_detail_hash || {}
 
-      raw.merge(detail)
+      ret = raw.merge(detail)
+      ret['patch_text'] = patch_text
+      ret['diff_text']  = diff_text
+
+      ret
+    end
+
+    def patch_text
+      @patch_text ||= connection.raw_get(patch_url).body
+    end
+
+    def diff_text
+      @diff_text ||= connection.raw_get(diff_url).body
+    end
+
+    private
+
+    # Give a full listing of the available information, since we
+    # define some of our own methods, and don't have everything in
+    # +@raw+.
+    #
+    # @api private
+    # @since 0.0.1
+    def additional_attributes
+      attrs = ['user_avatar_url', 'user_url', 'user_id', 'user_login', 'patch_text', 'diff_text']
+
+      attrs += @raw_detail_hash.keys if @raw_detail_hash
+      attrs += ['merged_by_login', 'merged_by_id', 'merged_by_avatar_url', 'merged_by_url']
     end
   end
 end

data/lib/octocat_herder/repository.rb

@@ -5,11 +5,42 @@ require 'octocat_herder/connection'
 require 'octocat_herder/user'
 
 class OctocatHerder
-  class Repository < Base
+  # Interface to the GitHub v3 API for interacting with repositories.
+  #
+  # Currently, this only supports retrieval of information about the
+  # repository itself, not any updating/creation.
+  class Repository
+    include OctocatHerder::Base
+
+    # @overload list_all(login_name, account_type, conn = OctocatHerder::Connection.new)
+    # @overload list_private(login_name, account_type, conn)
+    # @overload list_public(login_name, account_type, conn = OctocatHerder::Connection.new)
+    # @overload list_member(login_name, account_type, conn = OctocatHerder::Connection.new)
+    #
+    # Fetch all, private, public, or member repositories for the specified user.
+    #
+    # @since 0.0.1
+    #
+    # @raise [ArgumentError] If no conn is not provided when listing
+    #   private repositories.
+    #
+    # @param [String] login_name The login name of the user.
+    #
+    # @param ['User', 'Organization'] Whether login_name is for a user
+    #   or organization.
+    #
+    # @param [OctocatHerder::Connection] conn Defaults to
+    #   unauthenticated requests.
+    #
+    # @return [Array<OctocatHerder::Repository>]
     def self.method_missing(id, *args)
       if id.id2name =~ /list_(.+)/
         repository_type = Regexp.last_match(1)
         if ['all', 'private', 'public', 'member'].include? repository_type
+          if repository_type == 'private' and args[2].nil?
+            raise ArgumentError.new("Must specify a connection when listing private repositories.")
+          end
+
           arguments = [args[0], args[1], repository_type]
           arguments << args[2] unless args[2].nil?
 
@@ -20,42 +51,108 @@ class OctocatHerder
       raise NoMethodError.new("undefined method #{id.id2name} for #{self}:#{self.class}")
     end
 
+    # The login name of the owner of the repository.
+    #
+    # @since 0.0.1
+    # @return [String]
     def owner_login
       @raw['owner']['login']
     end
 
+    # The ID number of the owner of the repository.
+    #
+    # @since 0.0.1
+    # @return [Integer]
     def owner_id
       @raw['owner']['id']
     end
 
+    # The URL to the avatar image of the owner of the repository.
+    #
+    # @since 0.0.1
+    # @return [String]
     def owner_avatar_url
       @raw['owner']['avatar_url']
     end
 
+    # The URL of the owner of the repository.
+    #
+    # @since 0.0.1
+    # @return [String]
     def owner_url
       @raw['owner']['url']
     end
 
+    # The owner of the repository.
+    #
+    # @note This is cached locally to the instance of
+    #   {OctocatHerder::Repository}, but will make an additional API
+    #   request to populate it initially.
+    #
+    # @since 0.0.1
+    # @return [OctocatHerder::User]
     def owner
-      OctocatHerder::User.fetch(owner_login, connection)
+      @owner ||= OctocatHerder::User.fetch(owner_login, connection)
     end
 
+    # The open pull requests for the repository.
+    #
+    # @note This is _not_ cached, and will make at least one API
+    #   request every time it is called.
+    #
+    # @since 0.0.1
+    # @return [Array<OctocatHerder::PullRequest>]
     def open_pull_requests
-      OctocatHerder::PullRequest.find_for_repository(owner_login, name, 'open')
+      OctocatHerder::PullRequest.find_open_for_repository(owner_login, name, connection)
     end
 
+    # The closed pull requests for the repository.
+    #
+    # @note This is _not_ cached, and will make at least one API
+    #   request every time it is called.
+    #
+    # @since 0.0.1
+    # @return [Array<OctocatHerder::PullRequest>]
     def closed_pull_requests
-      OctocatHerder::PullRequest.find_for_repository(owner_login, name, 'closed')
+      OctocatHerder::PullRequest.find_closed_for_repository(owner_login, name, connection)
     end
 
+    # The source repository that this one was forked from, or +nil+ if
+    # this repository is not a fork.
+    #
+    # @since 0.0.1
+    # @return [OctocatHerder::Repository, nil]
     def source
-      return unless @raw['source']
+      return nil unless @raw['source']
 
       OctocatHerder::Repository.new(@raw['source'], connection)
     end
 
-    private
-
+    # Fetch repositories of the specified type, owned by the given login
+    #
+    # @since 0.0.1
+    #
+    # @raise [ArgumentError] If provided an unauthenticated
+    #   OctocatHerder::Connection and repository_type is 'private'.
+    #
+    # @raise [ArgumentError] If account_type is not one of the strings
+    #   'User', or 'Organization'.
+    #
+    # @raise [ArgumentError] If repository_type is not one of the
+    #   strings 'all', 'private', 'public', or 'member'.
+    #
+    # @param [String] login Login name of the account.
+    #
+    # @param ['User', 'Organization'] account_type Type of the
+    #   specified login.
+    #
+    # @param ['all', 'private', 'public', 'member'] repository_type
+    #   Which set of repositories to list.
+    #
+    # @param [OctocatHerder::Connection] conn Default to
+    #   unauthenticated requests.
+    #
+    # @return [Array<OctocatHerder::Repository>]
     def self.list(login, account_type, repository_type, conn = OctocatHerder::Connection.new)
       url_base = case account_type
                    when "User"         then "users"
@@ -64,8 +161,15 @@ class OctocatHerder
                    raise ArgumentError.new("Unknown account type: #{account_type}")
                  end
 
-      repositories = raw_get(
-        conn,
+      raise ArgumentError.new(
+        "Unknown repository type: #{repository_type}"
+      ) unless ['all', 'private', 'public', 'member'].include?(repository_type)
+
+      raise ArgumentError.new(
+        "Must provide an authenticated OctocatHerder::Connection when listing private repositories."
+      ) if !conn.authenticated_requests? && repository_type == 'private'
+
+      repositories = conn.get(
         "/#{url_base}/#{CGI.escape(login)}/repos",
         :paginated => true,
         :params    => { :type => repository_type }
@@ -76,15 +180,28 @@ class OctocatHerder
       end
     end
 
+    # Fetch a single repository.
+    #
+    # @since 0.0.1
+    #
+    # @param [String] login Login name of the account.
+    #
+    # @param [String] repository_name Name of the repository.
+    #
+    # @param [OctocatHerder::Connection] Default to unauthenticated
+    #   requests.
+    #
+    # @return [OctocatHerder::Repository]
     def self.fetch(login, repository_name, conn = OctocatHerder::Connection.new)
-      repo_data = raw_get(
-        conn,
+      repo_data = conn.get(
         "/repos/#{CGI.escape(login)}/#{CGI.escape(repository_name)}"
       )
 
       new(repo_data, conn)
     end
 
+    private
+
     def additional_attributes
       ['owner_login', 'owner_id', 'owner_avatar_url', 'owner_url']
     end

data/lib/octocat_herder/user.rb

@@ -1,34 +1,133 @@
+require 'cgi'
+
 require 'octocat_herder/base'
 require 'octocat_herder/connection'
 require 'octocat_herder/repository'
 
 class OctocatHerder
-  class User < Base
+  # Interface to the GitHub v3 API for interacting with users.
+  #
+  # Currently, this only supports retrieval of information about the
+  # requested user.
+  class User
+    include OctocatHerder::Base
+
+    # Find a user by login name
+    #
+    # @since 0.0.1
+    # @param [String] user_name The login name of the desired user.
+    #
+    # @param [OctocatHerder::Connection] conn Defaults to
+    #   unauthenticated requests.
+    #
+    # @return [OctocatHerder::User]
     def self.fetch(user_name, conn = OctocatHerder::Connection.new)
-      user = raw_get(conn, "/users/#{user_name}")
+      user = conn.get("/users/#{CGI.escape(user_name)}")
 
-      OctocatHerder::User.new(user, conn)
+      new(user, conn)
     end
 
+    # All repositories owned by the user.
+    #
+    # @note This is cached locally to the {OctocatHerder::User}
+    #   instance, but at least one API request will be made to
+    #   populate it initially.
+    #
+    # @since 0.0.1
+    # @return [Array<OctocatHerder::Repository>]
     def repositories
       @repositories ||= OctocatHerder::Repository.list_all(login, user_type, connection)
     end
 
-    # The user id can't be handled by the method_missing magic from
-    # OctocatHerder::Base, since the id method returns the object id.
+    # The ID number of the user.
+    #
+    # @since 0.0.1
+    # @return [Integer]
     def user_id
+      # The user id can't be handled by the method_missing magic from
+      # OctocatHerder::Base, since the id method returns the object
+      # id.
       @raw['id']
     end
 
-    # The user type can't be handled by the method_missing magic from
-    # OctocatHerder::Base, since 'type' is the deprecated form of the
-    # method 'class'.
+    # The type of account.  Typically one of +'User'+, or
+    # +'Organization'+.
+    #
+    # @since 0.0.1
+    # @return [String]
     def user_type
+      # The user type can't be handled by the method_missing magic
+      # from OctocatHerder::Base, since 'type' is the deprecated form
+      # of the method 'class'.
       @raw['type']
     end
 
+    # List of users following this user.
+    #
+    # @since development
+    # @return [Array<OctocatHerder::User>]
+    def followers
+      result = connection.get(
+        "/users/#{CGI.escape(login)}/followers"
+      )
+
+      result.map do |follower|
+        self.class.new(follower, connection)
+      end
+    end
+
+    # List of users this user is following.
+    #
+    # @since development
+    # @return [Array<OctocatHerder::User>]
+    def following
+      users = connection.get(
+        "/users/#{CGI.escape(login)}/following"
+      )
+
+      users.map do |stalkee|
+        self.class.new(stalkee, connection)
+      end
+    end
+
+    # Check if the user authenticated by the provided
+    # {OctocatHerder::Connection} is following the specified user.
+    #
+    # @since development
+    #
+    # @raise [ArgumentError] If user is not a String or an
+    #   OctocatHerder::User
+    #
+    # @raise [ArgumentError] If the connection will not make
+    #   authenticated requests.
+    #
+    # @param [String, OctocatHerder::User] user
+    #
+    # @param [OctocatHerder::Connection] connection An authenticated connection
+    #
+    # @return [true, false]
+    def self.following?(user, connection)
+      raise ArgumentError.new(
+        "Provided user must be a String, or an OctocatHerder::User."
+      ) unless user.is_a?(String) or user.is_a?(OctocatHerder::User)
+
+      raise ArgumentError.new(
+        "Provided connection must make authenticated requests."
+      ) unless connection.authenticated_requests?
+
+      user_name = user.is_a?(OctocatHerder::User) ? user.login : user
+
+      result = connection.raw_get("/user/following/#{CGI.escape(user_name)}")
+
+      # The GitHub API gives us back a "204 No Content" if we are
+      # following the user.
+      result.response.code == "204"
+    end
+
     private
 
+    # @api private
+    # @since 0.0.1
     def additional_attributes
       ['user_id', 'user_type']
     end