octokit 4.2.0 → 9.2.0

data/lib/octokit/client/source_import.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Octokit
+  class Client
+    # Methods for the Source Import API
+    #
+    # @see https://developer.github.com/v3/migration/source_imports
+    module SourceImport
+      # Start a source import to a GitHub repository using GitHub Importer.
+      #
+      # @overload start_source_import(repo, vcs, vcs_url, options = {})
+      #   @deprecated
+      #   @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      #   @param vcs [String] The originating VCS type. Can be one of "subversion", "git", "mercurial", or "tfvc".
+      #   @param vcs_url [String] The URL of the originating repository.
+      #   @param options [Hash]
+      #   @option options [String] :vcs_username If authentication is required, the username to provide to vcs_url.
+      #   @option options [String] :vcs_password If authentication is required, the password to provide to vcs_url.
+      #   @option options [String] :tfvc_project For a tfvc import, the name of the project that is being imported.
+      # @overload start_source_import(repo, vcs_url, options = {})
+      #   @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      #   @param vcs_url [String] The URL of the originating repository.
+      #   @param options [Hash]
+      #   @param options [String] :vcs The originating VCS type. Can be one of "subversion", "git", "mercurial", or "tfvc".
+      #   @option options [String] :vcs_username If authentication is required, the username to provide to vcs_url.
+      #   @option options [String] :vcs_password If authentication is required, the password to provide to vcs_url.
+      #   @option options [String] :tfvc_project For a tfvc import, the name of the project that is being imported.
+      # @return [Sawyer::Resource] Hash representing the repository import
+      # @see https://developer.github.com/v3/migration/source_imports/#start-an-import
+      #
+      # @example
+      #   @client.start_source_import("octokit/octokit.rb", "http://svn.mycompany.com/svn/myproject", {
+      #    :vcs           => "subversion",
+      #    :vcs_username" => "octocat",
+      #    :vcs_password  => "secret"
+      #   })
+      def start_source_import(*args)
+        arguments = Octokit::RepoArguments.new(args)
+        vcs_url = arguments.pop
+        vcs = arguments.pop
+        if vcs
+          octokit_warn 'Octokit#start_source_import vcs parameter is now an option, please update your call before the next major Octokit version update.'
+          arguments.options.merge!(vcs: vcs)
+        end
+        options = arguments.options.merge(vcs_url: vcs_url)
+        put "#{Repository.path arguments.repo}/import", options
+      end
+
+      # View the progress of an import.
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @return [Sawyer::Resource] Hash representing the progress of the import
+      # @see https://developer.github.com/v3/migration/source_imports/#get-import-progress
+      #
+      # @example
+      #   @client.source_import_progress("octokit/octokit.rb")
+      def source_import_progress(repo, options = {})
+        get "#{Repository.path repo}/import", options
+      end
+
+      # Update source import with authentication or project choice
+      # Restart source import if no options are passed
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @return [Sawyer::Resource] Hash representing the repository import
+      # @see https://developer.github.com/v3/migration/source_imports/#update-existing-import
+      # @option options [String] :vcs_username If authentication is required, the username to provide to vcs_url.
+      # @option options [String] :vcs_password If authentication is required, the password to provide to vcs_url.
+      # @option options [String] To update project choice, please refer to the project_choice array from the progress return hash for the exact attributes.
+      # https://developer.github.com/v3/migration/source_imports/#update-existing-import
+      #
+      # @example
+      #   @client.update_source_import("octokit/octokit.rb", {
+      #    :vcs_username" => "octocat",
+      #    :vcs_password  => "secret"
+      #   })
+      def update_source_import(repo, options = {})
+        patch "#{Repository.path repo}/import", options
+      end
+
+      # List source import commit authors
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @param options [Hash]
+      # @option options [String] :since Only authors found after this id are returned.
+      # @return [Array<Sawyer::Resource>] Array of hashes representing commit_authors.
+      # @see https://developer.github.com/v3/migration/source_imports/#get-commit-authors
+      #
+      # @example
+      #   @client.source_import_commit_authors("octokit/octokit.rb")
+      def source_import_commit_authors(repo, options = {})
+        get "#{Repository.path repo}/import/authors", options
+      end
+
+      # Update an author's identity for the import.
+      #
+      # @param author_url [String] The source import API url for the commit author
+      # @param values [Hash] The updated author attributes
+      # @option values [String] :email The new Git author email.
+      # @option values [String] :name The new Git author name.
+      # @return [Sawyer::Resource] Hash representing the updated commit author
+      # @see https://developer.github.com/v3/migration/source_imports/#map-a-commit-author
+      #
+      # @example
+      #   author_url = "https://api.github.com/repos/octokit/octokit.rb/import/authors/1"
+      #   @client.map_source_import_commit_author(author_url, {
+      #     :email => "hubot@github.com",
+      #     :name => "Hubot the Robot"
+      #   })
+      def map_source_import_commit_author(author_url, values, options = {})
+        options = options.merge(values)
+        patch author_url, options
+      end
+
+      # Stop an import for a repository.
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @return [Boolean] True if the import has been cancelled, false otherwise.
+      # @see https://developer.github.com/v3/migration/source_imports/#cancel-an-import
+      #
+      # @example
+      #   @client.cancel_source_import("octokit/octokit.rb")
+      def cancel_source_import(repo, options = {})
+        boolean_from_response :delete, "#{Repository.path repo}/import", options
+      end
+
+      # List source import large files
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @param options [Hash]
+      # @option options [Integer] :page Page of paginated results
+      # @return [Array<Sawyer::Resource>] Array of hashes representing files over 100MB.
+      # @see https://developer.github.com/v3/migration/source_imports/#get-large-files
+      #
+      # @example
+      #   @client.source_import_large_files("octokit/octokit.rb")
+      def source_import_large_files(repo, options = {})
+        get "#{Repository.path repo}/import/large_files", options
+      end
+
+      # Set preference for using Git LFS to import files over 100MB
+      #
+      # @param repo [Integer, String, Hash, Repository] A GitHub repository.
+      # @param use_lfs [String] Preference for using Git LFS to import large files. Can be one of "opt_in" or "opt_out"
+      # @return [Sawyer::Resource] Hash representing the repository import
+      # @see https://developer.github.com/v3/migration/source_imports/#set-git-lfs-preference
+      #
+      # @example
+      #   @client.opt_in_source_import_lfs("octokit/octokit.rb", "opt_in")
+      def set_source_import_lfs_preference(repo, use_lfs, options = {})
+        options = options.merge(use_lfs: use_lfs)
+        patch "#{Repository.path repo}/import/lfs", options
+      end
+    end
+  end
+end

data/lib/octokit/client/stats.rb

@@ -1,73 +1,83 @@
+# frozen_string_literal: true
+
 module Octokit
   class Client
-
     # Methods for the Repository Statistics API
     #
     # @see https://developer.github.com/v3/repos/statistics/
     module Stats
-
       # Get contributors list with additions, deletions, and commit counts
       #
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @option retry_timeout [Number] How long Octokit should keep trying to get stats (in seconds)
+      # @option retry_wait [Number] How long Octokit should wait between retries.
       # @return [Array<Sawyer::Resource>] Array of contributor stats
-      # @see https://developer.github.com/v3/repos/statistics/#contributors
+      # @see https://developer.github.com/v3/repos/statistics/#get-contributors-list-with-additions-deletions-and-commit-counts
       # @example Get contributor stats for octokit
       #   @client.contributors_stats('octokit/octokit.rb')
       def contributors_stats(repo, options = {})
-        get_stats(repo, "contributors", options)
+        get_stats(repo, 'contributors', options)
       end
-      alias :contributor_stats :contributors_stats
+      alias contributor_stats contributors_stats
 
       # Get the last year of commit activity data
       #
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @option retry_timeout [Number] How long Octokit should keep trying to get stats (in seconds)
+      # @option retry_wait [Number] How long Octokit should wait between retries.
       # @return [Array<Sawyer::Resource>] The last year of commit activity grouped by
       #   week. The days array is a group of commits per day, starting on Sunday.
-      # @see https://developer.github.com/v3/repos/statistics/#commit-activity
+      # @see https://developer.github.com/v3/repos/statistics/#get-the-last-year-of-commit-activity-data
       # @example Get commit activity for octokit
       #   @client.commit_activity_stats('octokit/octokit.rb')
       def commit_activity_stats(repo, options = {})
-        get_stats(repo, "commit_activity", options)
+        get_stats(repo, 'commit_activity', options)
       end
 
       # Get the number of additions and deletions per week
       #
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @option retry_timeout [Number] How long Octokit should keep trying to get stats (in seconds)
+      # @option retry_wait [Number] How long Octokit should wait between retries.
       # @return [Array<Sawyer::Resource>] Weekly aggregate of the number of additions
       #   and deletions pushed to a repository.
-      # @see https://developer.github.com/v3/repos/statistics/#code-frequency
+      # @see https://developer.github.com/v3/repos/statistics/#get-the-number-of-additions-and-deletions-per-week
       # @example Get code frequency stats for octokit
       #   @client.code_frequency_stats('octokit/octokit.rb')
       def code_frequency_stats(repo, options = {})
-        get_stats(repo, "code_frequency", options)
+        get_stats(repo, 'code_frequency', options)
       end
 
       # Get the weekly commit count for the repo owner and everyone else
       #
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @option retry_timeout [Number] How long Octokit should keep trying to get stats (in seconds)
+      # @option retry_wait [Number] How long Octokit should wait between retries.
       # @return [Sawyer::Resource] Total commit counts for the owner and total commit
       #   counts in all. all is everyone combined, including the owner in the last
       #   52 weeks. If you’d like to get the commit counts for non-owners, you can
       #   subtract all from owner.
-      # @see https://developer.github.com/v3/repos/statistics/#participation
+      # @see https://developer.github.com/v3/repos/statistics/#get-the-weekly-commit-count-for-the-repository-owner-and-everyone-else
       # @example Get weekly commit counts for octokit
       #   @client.participation_stats("octokit/octokit.rb")
       def participation_stats(repo, options = {})
-        get_stats(repo, "participation", options)
+        get_stats(repo, 'participation', options)
       end
 
       # Get the number of commits per hour in each day
       #
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
+      # @option retry_timeout [Number] How long Octokit should keep trying to get stats (in seconds)
+      # @option retry_wait [Number] How long Octokit should wait between retries.
       # @return [Array<Array>] Arrays containing the day number, hour number, and
       #   number of commits
-      # @see https://developer.github.com/v3/repos/statistics/#punch-card
+      # @see https://developer.github.com/v3/repos/statistics/#get-the-number-of-commits-per-hour-in-each-day
       # @example Get octokit punch card
       #   @octokit.punch_card_stats
       def punch_card_stats(repo, options = {})
-        get_stats(repo, "punch_card", options)
+        get_stats(repo, 'punch_card', options)
       end
-      alias :punch_card :punch_card_stats
+      alias punch_card punch_card_stats
 
       private
 
@@ -75,11 +85,23 @@ module Octokit
       #
       # @param repo [Integer, String, Hash, Repository] A GitHub repository
       # @param metric [String] The metrics you are looking for
-      # @return [Array<Sawyer::Resource>] Magical unicorn stats
+      # @return [Array<Sawyer::Resource> or nil] Stats in metric-specific format, or nil if not yet calculated.
+      # @see https://developer.github.com/v3/repos/statistics/
       def get_stats(repo, metric, options = {})
-        data = get("#{Repository.path repo}/stats/#{metric}", options)
+        options = options.dup
+        if retry_timeout = options.delete(:retry_timeout)
+          retry_wait = options.delete(:retry_wait) || 0.5
+          timeout = Time.now + retry_timeout
+        end
+        loop do
+          data = get("#{Repository.path repo}/stats/#{metric}", options)
+          return data if last_response.status == 200
+          return [] if last_response.status == 204
+          return nil unless retry_timeout
+          return nil if Time.now >= timeout
 
-        last_response.status == 202 ? nil : data
+          sleep retry_wait if retry_wait
+        end
       end
     end
   end

data/lib/octokit/client/statuses.rb

@@ -1,11 +1,11 @@
+# frozen_string_literal: true
+
 module Octokit
   class Client
-
     # Methods for the Commit Statuses API
     #
     # @see https://developer.github.com/v3/repos/statuses/
     module Statuses
-
       # List all statuses for a given commit
       #
       # @param repo [Integer, String, Repository, Hash] A GitHub repository
@@ -13,9 +13,9 @@ module Octokit
       # @return [Array<Sawyer::Resource>] A list of statuses
       # @see https://developer.github.com/v3/repos/statuses/#list-statuses-for-a-specific-ref
       def statuses(repo, sha, options = {})
-        get "#{Repository.path repo}/statuses/#{sha}", options
+        paginate "#{Repository.path repo}/statuses/#{sha}", options
       end
-      alias :list_statuses :statuses
+      alias list_statuses statuses
 
       # Get the combined status for a ref
       #
@@ -26,7 +26,7 @@ module Octokit
       def combined_status(repo, ref, options = {})
         get "#{Repository.path repo}/commits/#{ref}/status", options
       end
-      alias :status :combined_status
+      alias status combined_status
 
       # Create status for a commit
       #
@@ -39,7 +39,7 @@ module Octokit
       # @return [Sawyer::Resource] A status
       # @see https://developer.github.com/v3/repos/statuses/#create-a-status
       def create_status(repo, sha, state, options = {})
-        options.merge!(:state => state)
+        options = options.merge(state: state)
         post "#{Repository.path repo}/statuses/#{sha}", options
       end
     end

data/lib/octokit/client/tokens.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Octokit
+  class Client
+    # Method to check scopes
+    #
+    # @see https://developer.github.com/v3/oauth_authorizations/#oauth-authorizations-api
+    module Tokens
+      # Check scopes for a token
+      #
+      # @param token [String] GitHub OAuth token
+      # @param options [Hash] Header params for request
+      # @return [Array<String>] OAuth scopes
+      # @see https://developer.github.com/v3/oauth/#scopes
+      def scopes(token = @access_token, options = {})
+        options = options.dup
+        raise ArgumentError, 'Access token required' if token.nil?
+
+        auth = { 'Authorization' => "token #{token}" }
+        headers = (options.delete(:headers) || {}).merge(auth)
+
+        agent.call(:get, 'user', headers: headers)
+             .headers['X-OAuth-Scopes']
+             .to_s
+             .split(',')
+             .map(&:strip)
+             .sort
+      end
+    end
+  end
+end

data/lib/octokit/client/traffic.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Octokit
+  class Client
+    # Methods for the Traffic API
+    #
+    # @see https://developer.github.com/v3/repos/traffic/
+    module Traffic
+      # Get the top 10 referrers over the last 14 days
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub repository
+      # @return [Array<Sawyer::Resource>] List of referrers and stats
+      # @see https://developer.github.com/v3/repos/traffic/#list-referrers
+      # @example
+      #   @client.top_referrers('octokit/octokit.rb')
+      def top_referrers(repo, options = {})
+        get "#{Repository.path repo}/traffic/popular/referrers", options
+      end
+
+      # Get the top 10 popular contents over the last 14 days
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub repository
+      # @return [Array<Sawyer::Resource>] List of popular contents
+      # @see https://developer.github.com/v3/repos/traffic/#list-paths
+      # @example
+      #   @client.top_paths('octokit/octokit.rb')
+      def top_paths(repo, options = {})
+        get "#{Repository.path repo}/traffic/popular/paths", options
+      end
+
+      # Get the total number of views and breakdown per day or week for the
+      # last 14 days
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub Repository
+      # @option options [String] :per ('day') Views per. <tt>day</tt> or
+      #   <tt>week</tt>
+      # @return [Sawyer::Resource] Breakdown of view stats
+      # @see https://developer.github.com/v3/repos/traffic/#views
+      # @example Views per day
+      #   @client.views('octokit/octokit.rb')
+      # @example Views per week
+      #   @client.views('octokit/octokit.rb', per: 'week')
+      def views(repo, options = {})
+        get "#{Repository.path repo}/traffic/views", options
+      end
+
+      # Get the total number of clones and breakdown per day or week for the
+      # last 14 days
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub Repository
+      # @option options [String] :per ('day') Views per. <tt>day</tt> or
+      #   <tt>week</tt>
+      # @return [Sawyer::Resource] Breakdown of clone stats
+      # @see https://developer.github.com/v3/repos/traffic/#clones
+      # @example Clones per day
+      #   @client.clones('octokit/octokit.rb')
+      # @example Clones per week
+      #   @client.clones('octokit/octokit.rb', per: 'week')
+      def clones(repo, options = {})
+        get "#{Repository.path repo}/traffic/clones", options
+      end
+    end
+  end
+end