jenkins2-api 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ce596bcac88f03c2226d88a297f7922760a599f7
-  data.tar.gz: 143eb32b438a562b5066f028264f5c68164799de
+  metadata.gz: d6bfbc056dbe1bc9f82b4f9178e5f7892e06eee8
+  data.tar.gz: 6c8d9cc4ebb65a8ce2b0498734858b2dfd0b7740
 SHA512:
-  metadata.gz: 455bb82a3071c90be0c389484027642d0559ab6f57cf98ee45cbd990e0e3eab8451298a792ad2f885dc427fcb278f96445ec8bbde8a33fccf85fa266b69c8b52
-  data.tar.gz: b6604ce550b178f1837ca48cc2cda2557dcdb01998cfe3eaff05d73d80b16045f7911ddf9490e38b948d71bfe2b19d8a0e5f4447db4fdaca500182e537d59845
+  metadata.gz: 627027afdbe1cb6d91f7b2a0818d2b272cf375f14ee54ef94bf2ed50481dd7c49f879efa5dbe57e77bc92d417b9ab01cc4c454b5934126a5e787b7f2ee51c067
+  data.tar.gz: 00e6d6f5c358c5664d05556224f6cdb1d208791609d15a6f63f1466924a44f4f035a836170a6a1cfe0c81e0f768a42cfbd187c3cadd3a5c57930c232d256a9e9

data/bin/jenkins2api

@@ -4,11 +4,14 @@ require 'thor'
 require 'jenkins2-api'
 
 module Jenkins2API
+  # CLI wrapper under Jenkins2API
   module CLI
+    # Base class for Thor with registered modules and version info
     class Jenkins2 < Thor
       map %w[--version -v] => :__print_version
 
       desc "--version, -v", "print the version"
+      # Prints the current version number
       def __print_version
         puts Jenkins2API::VERSION
       end

data/lib/client.rb

@@ -6,8 +6,18 @@ require_relative './endpoints/build'
 require_relative './endpoints/job'
 require_relative './endpoints/node'
 
+# Jenkins2API codebase wrapper
 module Jenkins2API
+  # Basically the only public class to call Jenkins2 API nedpoints
   class Client
+    # Save Jenkins credentials and server path
+    #
+    # ==== Options:
+    # +server+:: Server path (e.g.: https://jenkins.example.com/)
+    # +username+:: Username for Jenkins
+    # +password+:: Password or API Token for Jenkins
+    # Throws an +ArgumentError+ if username is specified
+    # but password is empty
     def initialize(**options)
       @server   = options[:server]    || 'http://127.0.0.1/'
       @username = options[:username]
@@ -18,22 +28,33 @@ module Jenkins2API
       end
     end
 
+    # Job related endpoints. Creates new +Jenkins2API::Job+ instance
     def job
       @job ||= Job.new(self)
     end
 
+    # Build related endpoints. Creates new +Jenkins2API::Build+ instance
     def build
       @build ||= Build.new(self)
     end
 
+    # Artifact related endpoints. Creates new +Jenkins2API::Artifact+ instance
     def artifact
       @artifact ||= Artifact.new(self)
     end
 
+    # Node/Computer related endpoints. Creates new +Jenkins2API::Node+ instance
     def node
       @node ||= Node.new(self)
     end
 
+    # Creates and calls an API endpoint.
+    #
+    # ==== Params:
+    # +method+:: +:post+ or +:get+
+    # +path+:: Path to the Jenkins resource (e.g.: +/job/my-job/+)
+    # +response_type+:: +:json+ or +:raw+
+    # +opts+:: sym options to pass to the endpoint. Applicable only if +:post+
     def api_request(method, path, response_type = :json, **opts)
       response_type = :json unless [:json, :raw].include?(response_type)
 

data/lib/commands/build.rb

@@ -1,10 +1,13 @@
 require 'thor'
 
 module Jenkins2API
+  # Command module wraps all the cli commands
   module Command
+    # Contains all the commands under +build+ namespace
     class Build < Jenkins2API::ThorCommand
       desc 'slave-name JOB_NAME BUILD_ID', 'Get Node name where a specific build was running'
       method_option :ec2id, :default => false, :type => :boolean
+      # Displays the name of the slave where the build was executed
       def slave_name(name, build_id)
         slave_name = client.build.slave_name(name, build_id)
         slave_name = slave_name.match(/(i-[0-9a-zA-Z]+)/).captures.first if options[:ec2id]

data/lib/commands/job.rb

@@ -1,7 +1,9 @@
 require 'thor'
 
 module Jenkins2API
+  # Command module wraps all the cli commands
   module Command
+    # Contains all the commands under +job+ namespace
     class Job < Jenkins2API::ThorCommand
     end
   end

data/lib/commands/node.rb

@@ -1,9 +1,13 @@
 require 'thor'
 
 module Jenkins2API
+  # Command module wraps all the cli commands
   module Command
+    # Contains all the commands under +node+ namespace
     class Node < Jenkins2API::ThorCommand
+
       desc :all, "List all nodes"
+      # List all available nodes
       def all
         nodes = client.node.all
         nodes['computer'].each do |computer|
@@ -14,6 +18,7 @@ module Jenkins2API
       end
 
       desc :slaves, "List all slave nodes"
+      # List all avilable slaves
       def slaves
         nodes = client.node.all
         nodes['computer'].each do |computer|

data/lib/endpoint.rb

@@ -0,0 +1,9 @@
+module Jenkins2API
+  # General methods for endpoints
+  class Endpoint
+    # Stores the Jenkins2API::Client instance
+    def initialize(client)
+      @client = client
+    end
+  end
+end

data/lib/endpoints/artifact.rb

@@ -1,13 +1,26 @@
-module Jenkins2API
-  class Artifact
-    def initialize(client)
-      @client = client
-    end
+require_relative '../endpoint'
 
+module Jenkins2API
+  # This class contains all the calls to reach
+  # Jenkins2 and obtain Artifact data
+  class Artifact < Endpoint
+    # Returns a list of all artifacts for a specific build
+    #
+    # Params:
+    # +name+:: Job name
+    # +build_id+:: ID of the build
     def all(name, build_id)
       @client.build.get(name)['artifacts']
     end
 
+    # Download a specific artifact.
+    #
+    # Params:
+    # +name+:: Job name
+    # +build_id+:: ID of the build
+    # +artifact+:: artifact +Hash+. this function uses only the +relativePath+ property
+    #
+    # Returns with the content of the artifact
     def get(name, build_id, artifact)
       @client.api_request(:get, "/job/#{name}/#{build_id}/artifact/#{artifact['relativePath']}", :raw)
     end

data/lib/endpoints/build.rb

@@ -1,25 +1,52 @@
-module Jenkins2API
-  class Build
-    def initialize(client)
-      @client = client
-    end
+require_relative '../endpoint'
 
+module Jenkins2API
+  # This class contains all the calls to reach
+  # Jenkins2 and obtain Build data
+  class Build < Endpoint
+    # Get a specific build
+    #
+    # ==== Params:
+    # +job_name+:: Name of the Job
+    # +build_id+:: ID of the build
     def get(job_name, build_id)
       @client.api_request(:get, "/job/#{job_name}/#{build_id}")
     end
 
+    # Get the latest build
+    #
+    # ==== Params:
+    # +job_name+:: Name of the Job
     def latest(name)
       @client.api_request(:get, "/job/#{name}/lastBuild")
     end
 
+    # Get test report for a specific build
+    #
+    # ==== Params:
+    # +name+:: Name of the Job
+    # +build_id+:: ID of the build
     def test_results(name, build_id)
       @client.api_request(:get, "/job/#{name}/#{build_id}/testReport")
     end
 
+    # Get +console log+ for a specific build as text
+    #
+    # ==== Params:
+    # +job_name+:: Name of the Job
+    # +build_id+:: ID of the build
+    #
+    # Return an array of strings.
+    # Each item in that array is a line from the log
     def logtext_lines(name, build_id)
       @client.api_request(:get, "/job/#{name}/#{build_id}/logText/progressiveText", :raw).split("\r\n")
     end
 
+    # Get the name of the slave where the build was executed
+    #
+    # ==== Params:
+    # +name+:: Name of the Job
+    # +build_id+:: ID of the build
     def slave_name(name, build_id)
       log = logtext_lines(name, build_id)
       relevant_line = log.select { |line| line.match(/^Running on /) }.first

data/lib/endpoints/job.rb

@@ -1,13 +1,20 @@
-module Jenkins2API
-  class Job
-    def initialize(client)
-      @client = client
-    end
+require_relative '../endpoint'
 
+module Jenkins2API
+  # This class contains all the calls to reach
+  # Jenkins2 and obtain Build data
+  class Job < Endpoint
+    # Lists all available jobs
     def list
       @client.api_request(:get, "")['jobs']
     end
 
+    # Get all available builds for a specific job
+    #
+    # ==== Params:
+    # +name+:: Name of the Job
+    #
+    # Returns with an array of builds
     def builds(name)
       @client.api_request(:get, "/job/#{name}")['builds']
     end

data/lib/endpoints/node.rb

@@ -1,9 +1,12 @@
-module Jenkins2API
-  class Node
-    def initialize(client)
-      @client = client
-    end
+require_relative '../endpoint'
 
+module Jenkins2API
+  # This class contains all the calls to reach
+  # Jenkins2 and obtain Computer data
+  class Node < Endpoint
+    # List all available Computer
+    #
+    # Returns with slaves and masters also
     def all
       @client.api_request(:get, "/computer")
     end

data/lib/thor_command.rb

@@ -1,12 +1,16 @@
 require 'thor'
 
+# Jenkins2API codebase wrapper
 module Jenkins2API
+  # Wrapper class for commands. Checks if credentials are passed or not
+  # and creates a new +Jenkins2API::Client+ instance for commands.
   class ThorCommand < Thor
     class_option :password, :desc => "Password", :aliases => "-p", :required => false
     class_option :username, :desc => "Username", :aliases => "-u", :required => false
     class_option :server, :desc => "Server path", :aliases => "-s", :required => false
 
     private
+    # Get or create a new client
     def client
       check_option(:server, 'JENKINS_SERVER')
       check_option(:username, 'JENKINS_USERNAME')
@@ -19,6 +23,7 @@ module Jenkins2API
       )
     end
 
+    # Check option or environment variable content
     def check_option(name, env_name)
       options[name] ||= ENV.fetch(env_name, '')
 

data/lib/version.rb

@@ -1,4 +1,6 @@
 module Jenkins2API
-  VERSION = '1.0.1'
+  # Current version to publish
+  # Gemspec also uses this constant
+  VERSION = '1.0.2'
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jenkins2-api
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Balazs Nadasdi
@@ -38,6 +38,7 @@ files:
 - lib/commands/build.rb
 - lib/commands/job.rb
 - lib/commands/node.rb
+- lib/endpoint.rb
 - lib/endpoints/artifact.rb
 - lib/endpoints/build.rb
 - lib/endpoints/job.rb
@@ -65,7 +66,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: API client for Jenkins 2.