github_api 0.11.3 → 0.12.0

data/lib/github_api/client/repos/collaborators.rb

@@ -0,0 +1,83 @@
+# encoding: utf-8
+
+module Github
+  class Client::Repos::Collaborators < API
+    # List collaborators
+    #
+    # When authenticating as an organization owner of an
+    # organization-owned repository, all organization owners are included
+    # in the list of collaborators. Otherwise, only users with access to the
+    # repository are returned in the collaborators list.
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.collaborators.list 'user-name', 'repo-name'
+    #
+    # @example
+    #  github.repos.collaborators.list 'user-name', 'repo-name' { |cbr| .. }
+    #
+    # @return [Array]
+    #
+    # @api public
+    def list(*args)
+      arguments(args, required: [:user, :repo])
+      params = arguments.params
+
+      response = get_request("/repos/#{arguments.user}/#{arguments.repo}/collaborators", arguments.params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :all :list
+
+    # Add collaborator
+    #
+    # @example
+    #  github = Github.new
+    #  github.collaborators.add 'user', 'repo', 'username'
+    #
+    # @example
+    #  collaborators = Github::Repos::Collaborators.new
+    #  collaborators.add 'user', 'repo', 'username'
+    #
+    # @api public
+    def add(*args)
+      arguments(args, required: [:user, :repo, :username])
+
+      put_request("/repos/#{arguments.user}/#{arguments.repo}/collaborators/#{arguments.username}", arguments.params)
+    end
+    alias :<< :add
+
+    # Checks if user is a collaborator for a given repository
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.collaborators.collaborator?('user', 'repo', 'username')
+    #
+    # @example
+    #  github = Github.new user: 'user-name', repo: 'repo-name'
+    #  github.collaborators.collaborator? username: 'collaborator'
+    #
+    # @api public
+    def collaborator?(*args)
+      arguments(args, required: [:user, :repo, :username])
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/collaborators/#{arguments.username}", arguments.params)
+      true
+    rescue Github::Error::NotFound
+      false
+    end
+
+    # Removes collaborator
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.collaborators.remove 'user', 'repo', 'username'
+    #
+    # @api public
+    def remove(*args)
+      arguments(args, required: [:user, :repo, :username])
+
+      delete_request("/repos/#{arguments.user}/#{arguments.repo}/collaborators/#{arguments.username}", arguments.params)
+    end
+  end # Client::Repos::Collaborators
+end # Github

data/lib/github_api/client/repos/comments.rb

@@ -0,0 +1,124 @@
+# encoding: utf-8
+
+module Github
+  class Client::Repos::Comments < API
+
+    REQUIRED_COMMENT_OPTIONS = %w[ body ].freeze
+
+    VALID_COMMENT_OPTIONS = %w[
+      body
+      line
+      path
+      position
+    ].freeze
+
+    # List commit comments for a repository
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.comments.list 'user-name', 'repo-name'
+    #
+    # @example
+    #  github.repos.comments.list 'user-name', 'repo-name' { |com| ... }
+    #
+    # List comments for a single commit
+    #
+    # @example
+    #  github.repos.comments.list 'user-name', 'repo-name',
+    #   sha: '6dcb09b5b57875f334f61aebed695e2e4193db5e'
+    #
+    # @api public
+    def list(*args)
+      arguments(args, required: [:user, :repo])
+      params = arguments.params
+      user   = arguments.user
+      repo   = arguments.repo
+
+      response = if (sha = params.delete('sha'))
+        get_request("/repos/#{user}/#{repo}/commits/#{sha}/comments", params)
+      else
+        get_request("/repos/#{user}/#{repo}/comments", params)
+      end
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :all :list
+
+    # Gets a single commit comment
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.comments.get 'user-name', 'repo-name', 'id'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :id])
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/comments/#{arguments.id}", arguments.params)
+    end
+    alias :find :get
+
+    # Creates a commit comment
+    #
+    # @param [Hash] params
+    # @option params [String] :body
+    #   Required. The contents of the comment.
+    # @option params [String] :path
+    #   Required. Relative path of the file to comment on.
+    # @option params [Number] :position
+    #   Required number - Line index in the diff to comment on.
+    # @option params [Number] :line
+    #   Required number - Line number in the file to comment on.
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.comments.create 'user-name', 'repo-name', 'sha-key',
+    #    body: "Nice change",
+    #    position: 4,
+    #    line: 1,
+    #    path: "file1.txt"
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo, :sha]) do
+        permit VALID_COMMENT_OPTIONS
+        assert_required REQUIRED_COMMENT_OPTIONS
+      end
+
+      post_request("/repos/#{arguments.user}/#{arguments.repo}/commits/#{arguments.sha}/comments", arguments.params)
+    end
+
+    # Update a commit comment
+    #
+    # @param [Hash] params
+    # @option params [String] :body
+    #   Required. The contents of the comment.
+    #
+    # @example
+    #   github = Github.new
+    #   github.repos.comments.update 'user-name', 'repo-name', 'id',
+    #     body: "Nice change"
+    #
+    # @api public
+    def update(*args)
+      arguments(args, required: [:user, :repo, :id]) do
+        assert_required REQUIRED_COMMENT_OPTIONS
+      end
+
+      patch_request("/repos/#{arguments.user}/#{arguments.repo}/comments/#{arguments.id}", arguments.params)
+    end
+
+    # Deletes a commit comment
+    #
+    # @example
+    #   github = Github.new
+    #   github.repos.comments.delete 'user-name', 'repo-name', 'id'
+    #
+    # @api public
+    def delete(*args)
+      arguments(args, required: [:user, :repo, :id])
+
+      delete_request("/repos/#{arguments.user}/#{arguments.repo}/comments/#{arguments.id}", arguments.params)
+    end
+  end # Client::Repos::Comments
+end # Github

data/lib/github_api/client/repos/commits.rb

@@ -0,0 +1,78 @@
+# encoding: utf-8
+
+module Github
+  class Client::Repos::Commits < API
+
+    VALID_COMMITS_OPTIONS = %w[
+      sha
+      path
+      author
+      since
+      until
+    ].freeze
+
+    # List commits on a repository
+    #
+    # @param [Hash] params
+    # @option params [String] :sha
+    #   Sha or branch to start listing commits from.
+    # @option params [String] :path
+    #   Only commits containing this file path will be returned.
+    # @option params [String] :author
+    #   GitHub login, name, or email by which to filter by commit author.
+    # @option params [String] :since
+    #   Only commits after this date will be returned. This is a timestamp
+    #   in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
+    # @option params [String] :until
+    #   Only commits before this date will be returned. This is a timestamp
+    #   in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.commits.list 'user-name', 'repo-name', sha: '...'
+    #  github.repos.commits.list 'user-name', 'repo-name', sha: '...' { |commit| ... }
+    #
+    # @api public
+    def list(*args)
+      arguments(args, required: [:user, :repo]) do
+        permit VALID_COMMITS_OPTIONS
+      end
+
+      response = get_request("/repos/#{arguments.user}/#{arguments.repo}/commits", arguments.params)
+      return response unless block_given?
+      response.each { |el| yield el }
+    end
+    alias :all :list
+
+    # Gets a single commit
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.commits.get 'user-name', 'repo-name', '6dcb09b5b57875f334f61aebed6')
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :sha])
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/commits/#{arguments.sha}", arguments.params)
+    end
+    alias :find :get
+
+    # Compares two commits
+    #
+    # @note Both :base and :head can be either branch names in :repo or
+    # branch names in other repositories in the same network as :repo.
+    # For the latter case, use the format user:branch:
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.commits.compare 'user-name', 'repo-name', 'v0.4.8', 'master'
+    #
+    # @api public
+    def compare(*args)
+      arguments(args, required: [:user, :repo, :base, :head])
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/compare/#{arguments.base}...#{arguments.head}", arguments.params)
+    end
+  end # Client::Repos::Commits
+end # Github

data/lib/github_api/client/repos/contents.rb

@@ -0,0 +1,240 @@
+# encoding: utf-8
+
+module Github
+  # These API methods let you retrieve the contents of files within a repository
+  # as Base64 encoded content.
+  class Client::Repos::Contents < API
+
+    REQUIRED_CONTENT_OPTIONS = %w[ path message content ]
+
+    # Get the README
+    #
+    # This method returns the preferred README for a repository.
+    #
+    # @param [Hash] params
+    # @option params [String] :ref
+    #   The name of the commit/branch/tag.
+    #   Default: the repository’s default branch (usually master)
+    #
+    # @example
+    #   github = Github.new
+    #   github.repos.contents.readme 'user-name', 'repo-name'
+    #
+    #   content = Github::Repos;:Contents.new user: 'user-name', 'repo-name'
+    #   content.readme
+    #
+    # @api public
+    def readme(*args)
+      arguments(args, required: [:user, :repo])
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/readme", arguments.params)
+    end
+
+    # Get contents
+    #
+    # This method returns the contents of any file or directory in a repository.
+    #
+    # @param [Hash] params
+    # @option params [String] :path
+    #   The content path.
+    # @option params [String] :ref
+    #   The name of the commit/branch/tag.
+    #   Default: the repository’s default branch (usually master)
+    #
+    # @example
+    #   github = Github.new
+    #   github.repos.contents.get 'user-name', 'repo-name', 'path'
+    #
+    # @example
+    #   github = Github.new user: 'user-name', repo: 'repo-name'
+    #   github.repos.contents.get path: 'README.md'
+    #
+    # @api public
+    def get(*args)
+      arguments(args, required: [:user, :repo, :path])
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/contents/#{arguments.path}", arguments.params)
+    end
+    alias :find :get
+
+    # Create a file
+    #
+    # This method creates a new file in a repository
+    #
+    # @param [Hash] params
+    # @option params [String] :path
+    #   Requried string. The content path
+    # @option params [String]
+    # @option params [String] :message
+    #   Requried string. The commit message.
+    # @option params [String] :content
+    #   Requried string. The new file content, which will be Base64 encoded
+    # @option params [String] :branch
+    #   The branch name. If not provided, uses the repository’s
+    #   default branch (usually master)
+    #
+    # Optional Parameters
+    #
+    # The :author section is optional and is filled in with the
+    # :committer information if omitted. If the :committer
+    # information is omitted, the authenticated user’s information is used.
+    #
+    # You must provide values for both :name and :email, whether
+    # you choose to use :author or :committer. Otherwise, you’ll
+    # receive a 500 status code.
+    #
+    # Both the author and commiter parameters have the same keys:
+    #
+    # @option params [String] :name
+    #   The name of the author (or commiter) of the commit
+    # @option params [String] :email
+    #   The email of the author (or commiter) of the commit
+    #
+    # @example
+    #   github = Github.new
+    #   github.repos.contents.create 'user-name', 'repo-name', 'path',
+    #     path: 'hello.rb',
+    #     content: "puts 'hello ruby'",
+    #     message: "my commit message"
+    #
+    # @api public
+    def create(*args)
+      arguments(args, required: [:user, :repo, :path]) do
+        assert_required REQUIRED_CONTENT_OPTIONS
+      end
+      params = arguments.params
+      params.strict_encode64('content')
+
+      put_request("/repos/#{arguments.user}/#{arguments.repo}/contents/#{arguments.path}", params)
+    end
+
+    # Update a file
+    #
+    # This method updates a file in a repository
+    #
+    # @param [Hash] params
+    # @option params [String] :path
+    #   Requried string. The content path
+    # @option params [String]
+    # @option params [String] :message
+    #   Requried string. The commit message.
+    # @option params [String] :content
+    #   Requried string. The new file content, which will be Base64 encoded
+    # @option params [String] :sha
+    #   Required string. The blob SHA of the file being replaced.
+    # @option params [String] :branch
+    #   The branch name. If not provided, uses the repository’s
+    #   default branch (usually master)
+    #
+    # Optional Parameters
+    #
+    # The :author section is optional and is filled in with the
+    # :committer information if omitted. If the :committer
+    # information is omitted, the authenticated user’s information is used.
+    #
+    # You must provide values for both :name and :email, whether
+    # you choose to use :author or :committer. Otherwise, you’ll
+    # receive a 500 status code.
+    #
+    # Both the author and commiter parameters have the same keys:
+    #
+    # @option params [String] :name
+    #   The name of the author (or commiter) of the commit
+    # @option params [String] :email
+    #   The email of the author (or commiter) of the commit
+    #
+    # @example
+    #   github = Github.new
+    #   github.repos.contents.update 'user-name', 'repo-name', 'path',
+    #     path: 'hello.rb',
+    #     content: "puts 'hello ruby again'",
+    #     message: "my commit message",
+    #     sha: "25b0bef9e404bd2e3233de26b7ef8cbd86d0e913"
+    #
+    # @api public
+    def update(*args)
+      create(*args)
+    end
+
+    # Delete a file
+    #
+    # This method deletes a file in a repository
+    #
+    # @param [Hash] params
+    # @option params [String] :path
+    #   Requried string. The content path
+    # @option params [String]
+    # @option params [String] :message
+    #   Requried string. The commit message.
+    # @option params [String] :sha
+    #   Required string. The blob SHA of the file being replaced.
+    # @option params [String] :branch
+    #   The branch name. If not provided, uses the repository’s
+    #   default branch (usually master)
+    #
+    # Optional Parameters
+    #
+    # The :author section is optional and is filled in with the
+    # :committer information if omitted. If the :committer
+    # information is omitted, the authenticated user’s information is used.
+    #
+    # You must provide values for both :name and :email, whether
+    # you choose to use :author or :committer. Otherwise, you’ll
+    # receive a 500 status code.
+    #
+    # Both the author and commiter parameters have the same keys:
+    #
+    # @option params [String] :name
+    #   The name of the author (or commiter) of the commit
+    # @option params [String] :email
+    #   The email of the author (or commiter) of the commit
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.contents.delete 'user-name', 'repo-name', 'path',
+    #    path: 'hello.rb',
+    #    message: "delete hello.rb file",
+    #    sha: "329688480d39049927147c162b9d2deaf885005f"
+    #
+    def delete(*args)
+      arguments(args, required: [:user, :repo, :path]) do
+        assert_required %w[ path message sha ]
+      end
+
+      delete_request("/repos/#{arguments.user}/#{arguments.repo}/contents/#{arguments.path}", arguments.params)
+    end
+
+    # Get archive link
+    #
+    # This method will return a 302 to a URL to download a tarball or zipball
+    # archive for a repository. Please make sure your HTTP framework is configured
+    # to follow redirects or you will need to use the Location header to make
+    # a second GET request.
+    #
+    # @note
+    #   For private repositories, these links are temporary and expire quickly.
+    #
+    # @param [Hash] params
+    # @input params [String] :archive_format
+    #   Required string. Either tarball or zipball. Default: tarball
+    # @input params [String] :ref
+    #   Optional string. A valid Git reference.
+    #   Default: the repository’s default branch (usually master)
+    #
+    # @example
+    #  github = Github.new
+    #  github.repos.contents.archive 'user-name', 'repo-name',
+    #    archive_format: "tarball",
+    #    ref: "master"
+    #
+    # @api public
+    def archive(*args)
+      arguments(args, required: [:user, :repo])
+      params         = arguments.params
+      archive_format = params.delete('archive_format') || 'tarball'
+      ref            = params.delete('ref') || 'master'
+
+      get_request("/repos/#{arguments.user}/#{arguments.repo}/#{archive_format}/#{ref}", params)
+    end
+  end # Client::Repos::Contents
+end # Github