API

Folders

RootFolderBase

class jenni.models.RootFolderBase(url: str, **kwargs)[source]

Represents the pre-existing root folder in Jenkins below which jobs/folders are created. Has an empty name.

__init__(url: str, **kwargs)[source]
Parameters

  • url -- URL to the (possibly toplevel) Folder on the Jenkins server that this class represents.

  • kwargs -- optional arguments. Passed through to jenni.models.FolderBase __init__().

abstract pythonpipelinejob_inside_node_wrapper(job: jenni.models.pythonpipelinejobbase.PythonPipelineJobBase, groovy_code: str) → str[source]

Ensures appropriate code is executed around all code inside the node step. :param job: :param groovy_code: :return: groovy_code with preamble and postamble code

pythonpipelinejob_main_wrapper(job: jenni.models.pythonpipelinejobbase.PythonPipelineJobBase, groovy_code: str) → str[source]
write_jobdsl(fp: _io.TextIOWrapper)[source]

Root folder already exists on the Jenkins server, so this is a no-op.

FolderBase

class jenni.models.FolderBase(description: str = '', name: str = '', title: str = '', skip_seed: bool = False, url: str = '')[source]
add_new_folder(sub_folder: jenni.models.folderbase.FolderBase)[source]

Called after a sub-folder has been added to this folder. The sub-folder can be customised by overriding this method. Note yield_items() is not yet called on this job.

add_new_job(job: jenni.models.jobbase.JobBase)[source]

Called after a job has been added to this folder. The job can be customised by overriding this method.

sub_item_completed_handler(sub_item: jenni.models.itembase.ItemBase)[source]

Called after a sub-item has been added to this folder and all yielding has completed for it. The item can be customised by overriding this method.

write_jobdsl(fp: _io.TextIOWrapper)[source]
yield_items(module_name_to_load: str = '')[source]

Yield this folder and any items generated by python files below this folder. Overwrite in subclasses to dynamically generate items, but always insert this: yield from super().yield_items(module_name_to_load)

yield_items_post_sub_item(sub_item: jenni.models.itembase.ItemBase)[source]

Called after sub_item.yield_items() has been called. :param sub_item: the sub-item of this folder, just after calling yield_items on it.

yield_items_pre_sub_item(sub_item: jenni.models.itembase.ItemBase)[source]

Called before sub_item.yield_items() is called. :param sub_item: the sub-item of this folder, just before calling yield_items on it.

Jobs

GroovyJobBase

class jenni.models.GroovyJobBase(**kwargs)[source]

Baseclass for jobs that are implemented using Groovy pipeline scripts (https://www.jenkins.io/doc/book/pipeline/#scripted-pipeline-fundamentals).

__init__(**kwargs)[source]
Parameters

kwargs -- optional arguments. Passed through to PipelineJobBase __init__().

code(code: str)[source]

Include the specified text (normally Groovy scripted pipeline code) into the job.

See include() for {python('''<code>''')} replacements.

Parameters

code -- literal text to be inserted into the job pipeline script.

get_file_contents(filename: str) → str[source]

Return the contents of the file.

No replacements are done like in the include() method.

Parameters

filename -- See lookup_relative_filename() for how the file may be found.

include(filename: str)[source]

Include the specified file (normally Groovy scripted pipeline code) into the job.

Contents is checked for occurances of {python('''<code>''')} strings, and replaced with the result of executing <code>. Instead of 3 single quotes, 3 double, or 1 single/double quote can be used.

Parameters

filename -- See lookup_relative_filename() for how a file may be found.

include_first(filenames: List[str])[source]

Include the first found amongst the specified files (normally Groovy scripted pipeline code) into the job.

See include() for {python('''<code>''')} replacements.

Parameters

filenames -- See lookup_relative_filename() for how each file may be found.

Job Parameters

BooleanParam

class jenni.models.params.BooleanParam(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: bool = False)[source]
__init__(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: bool = False)[source]

Initialize self. See help(type(self)) for accurate signature.

property value
write_jobdsl(jobdsl: List[str])[source]

IntParam

class jenni.models.params.IntParam(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: int = 0)[source]
__init__(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: int = 0)[source]

Initialize self. See help(type(self)) for accurate signature.

property value
write_jobdsl(jobdsl: List[str])[source]

StringParam

class jenni.models.params.StringParam(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: str = '')[source]
__init__(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: str = '')[source]

Initialize self. See help(type(self)) for accurate signature.

property value
write_jobdsl(jobdsl: List[str])[source]

ValidatingStringParam

class jenni.models.params.ValidatingStringParam(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: str = '', regex: str = '', validation_message: str = '')[source]
__init__(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: str = '', regex: str = '', validation_message: str = '')[source]

Initialize self. See help(type(self)) for accurate signature.

property value
write_jobdsl(jobdsl: List[str])[source]

TextParam

class jenni.models.params.TextParam(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: str = '')[source]
__init__(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, default: str = '')[source]

Initialize self. See help(type(self)) for accurate signature.

property value
write_jobdsl(jobdsl: List[str])[source]

ChoiceParam

class jenni.models.params.ChoiceParam(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, options: List[str] = [])[source]
__init__(job: jenni.models.jobbase.JobBase, name: str, description: str, order: int = 50, options: List[str] = [])[source]

Initialize self. See help(type(self)) for accurate signature.

property value
write_jobdsl(jobdsl: List[str])[source]

jenni.utils

jenni.utils.bool2groovy(b: bool) → str[source]
jenni.utils.groovy_string_list(l: List[str]) → str[source]
jenni.utils.quote1or3xs(s: str) → str[source]

Groovy formatted string (single or triple quoted as necessary) :param s: string :return: single or triple quoted string

jenni.utils.quote1s(s: str) → str[source]

Groovy formatted single quoted string :param s: string to return as single-quoted, IE like '<s>' :return: single-quoted string

jenni.utils.quote3xs(s: str) → str[source]

Groovy formatted triple quoted string :param s: string to return as triple-single-quoted, IE like '''<s>''' :return: triple-single-quoted string

jenni.utils.quote_list(list_of_str: List[str]) → str[source]

Groovy formatted list of strings :param list_of_str: list of strings :return:

jenni.utils.tidy_text(s: str) → str[source]

Strips and un-indents the text

Other Classes

JobBase

class jenni.models.JobBase(description: str = '', name: str = '', title: str = '', skip_seed: bool = False, url: str = '')[source]

Base class for all types of jobs.

get_parameter(name: str, exception_if_not_found=True) → jenni.models.params.ParamBase[source]
Returns

ParamBase instance, or None (if exception_if_not_found is False)

has_parameter(name: str) → bool[source]
Returns

True if job has specified parameter.

property parameters

list of ParamBase instances

Type

return

PipelineJobBase

class jenni.models.PipelineJobBase(github_project_url: str = '', logrotator_spec: str = '', quiet_period: int = 0, throttleconcurrentbuilds_spec: str = '', trigger_cron_spec: str = '', trigger_on_github_push: bool = False, **kwargs)[source]
abstract __init__(github_project_url: str = '', logrotator_spec: str = '', quiet_period: int = 0, throttleconcurrentbuilds_spec: str = '', trigger_cron_spec: str = '', trigger_on_github_push: bool = False, **kwargs)[source]
Parameters
write_jobdsl(fp: _io.TextIOWrapper)[source]

PythonPipelineJobBase

class jenni.models.PythonPipelineJobBase(**kwargs)[source]

Baseclass for jobs that are implemented using Python code. This is still very much a work in progress.

Warning

Please see Security for security concerns about the current implementation.

__init__(**kwargs)[source]
Parameters
abstract run()[source]

To be implemented by subclass

workflow = <jenni.steps.Step object>

Provides access to Jenkins workflow (aka pipeline) steps.

All Modules

itembase

class jenni.models.itembase.ItemBase(description: str = '', name: str = '', title: str = '', skip_seed: bool = False, url: str = '')[source]
abstract __init__(description: str = '', name: str = '', title: str = '', skip_seed: bool = False, url: str = '')[source]
Parameters

  • description -- descriptive text shown in Jenkins for this item

  • name -- defaults to the name of the file or folder

  • title -- optional title of the item (defaults to the name of the item)

  • skip_seed -- if set to True, then do not seed this item in Jenkins

  • url -- URL to the job/folder. Must end with slash. Normally auto-calculated, unless it is the root folder.

configure()[source]

Optional, can be overridden in subclass.

get_root_folder() → jenni.models.rootfolderbase.RootFolderBase[source]
get_sub_item(sub_item_path: str) → jenni.models.itembase.ItemBase[source]
lookup_relative_filename(filename: str) → str[source]

Return path to file.

  • If the filename starts with "/", it is relative to the config directory of the jenni seed command.

  • Otherwise the filename is relative to the directory containing the file defining the calling Job or Folder.

Parameters

filename -- filename spec

Returns

full path to the file.

post_yield_handler()[source]

Called bottom-up after all items have been yielded

abstract write_jobdsl(fp: _io.TextIOWrapper)[source]
yield_items(module_name_to_load: str = '')[source]
yield_sub_item(name, base_class, filename=None, parent=None, **kwargs)[source]

Use this to dynamically create a Job or Folder instance. Specifically, it:

  • creates a new module containing a new class (named Job or Folder)

  • instances this class

  • calls yield_items on the instance.

Example usage: yield from self.yield_sub_item("fast_track", MyTrack)

Parameters

  • name -- the name of the module, relative to its parent.

  • base_class -- the base class of the created class

  • filename -- defaults to the filename of the calling function.

  • parent -- defaults to self.

  • kwargs -- additional arguments for base_class constructor

Returns

nothing. It uses yield instead.

jenni.models.itembase.reset()[source]

jobbase

class jenni.models.jobbase.JobBase(description: str = '', name: str = '', title: str = '', skip_seed: bool = False, url: str = '')[source]

Base class for all types of jobs.

get_parameter(name: str, exception_if_not_found=True) → jenni.models.params.ParamBase[source]
Returns

ParamBase instance, or None (if exception_if_not_found is False)

has_parameter(name: str) → bool[source]
Returns

True if job has specified parameter.

property parameters

list of ParamBase instances

Type

return

folderbase

class jenni.models.folderbase.FolderBase(description: str = '', name: str = '', title: str = '', skip_seed: bool = False, url: str = '')[source]
add_new_folder(sub_folder: jenni.models.folderbase.FolderBase)[source]

Called after a sub-folder has been added to this folder. The sub-folder can be customised by overriding this method. Note yield_items() is not yet called on this job.

add_new_job(job: jenni.models.jobbase.JobBase)[source]

Called after a job has been added to this folder. The job can be customised by overriding this method.

sub_item_completed_handler(sub_item: jenni.models.itembase.ItemBase)[source]

Called after a sub-item has been added to this folder and all yielding has completed for it. The item can be customised by overriding this method.

write_jobdsl(fp: _io.TextIOWrapper)[source]
yield_items(module_name_to_load: str = '')[source]

Yield this folder and any items generated by python files below this folder. Overwrite in subclasses to dynamically generate items, but always insert this: yield from super().yield_items(module_name_to_load)

yield_items_post_sub_item(sub_item: jenni.models.itembase.ItemBase)[source]

Called after sub_item.yield_items() has been called. :param sub_item: the sub-item of this folder, just after calling yield_items on it.

yield_items_pre_sub_item(sub_item: jenni.models.itembase.ItemBase)[source]

Called before sub_item.yield_items() is called. :param sub_item: the sub-item of this folder, just before calling yield_items on it.

rootfolderbase

class jenni.models.rootfolderbase.RootFolderBase(url: str, **kwargs)[source]

Represents the pre-existing root folder in Jenkins below which jobs/folders are created. Has an empty name.

__init__(url: str, **kwargs)[source]
Parameters

  • url -- URL to the (possibly toplevel) Folder on the Jenkins server that this class represents.

  • kwargs -- optional arguments. Passed through to jenni.models.FolderBase __init__().

abstract pythonpipelinejob_inside_node_wrapper(job: jenni.models.pythonpipelinejobbase.PythonPipelineJobBase, groovy_code: str) → str[source]

Ensures appropriate code is executed around all code inside the node step. :param job: :param groovy_code: :return: groovy_code with preamble and postamble code

pythonpipelinejob_main_wrapper(job: jenni.models.pythonpipelinejobbase.PythonPipelineJobBase, groovy_code: str) → str[source]
write_jobdsl(fp: _io.TextIOWrapper)[source]

Root folder already exists on the Jenkins server, so this is a no-op.

pipelinejobbase

class jenni.models.pipelinejobbase.PipelineJobBase(github_project_url: str = '', logrotator_spec: str = '', quiet_period: int = 0, throttleconcurrentbuilds_spec: str = '', trigger_cron_spec: str = '', trigger_on_github_push: bool = False, **kwargs)[source]
abstract __init__(github_project_url: str = '', logrotator_spec: str = '', quiet_period: int = 0, throttleconcurrentbuilds_spec: str = '', trigger_cron_spec: str = '', trigger_on_github_push: bool = False, **kwargs)[source]
Parameters
write_jobdsl(fp: _io.TextIOWrapper)[source]

pythonpipelinejobbase

class jenni.models.pythonpipelinejobbase.PythonPipelineJobBase(**kwargs)[source]

Baseclass for jobs that are implemented using Python code. This is still very much a work in progress.

Warning

Please see Security for security concerns about the current implementation.

__init__(**kwargs)[source]
Parameters
children: List['ItemBase']
description: str
jenkins_path: str
logrotator_spec: str
parent: Optional['jenni.models.FolderBase']
quiet_period: int
abstract run()[source]

To be implemented by subclass

title: str
trigger_cron_spec: str
trigger_on_github_push: bool
workflow = <jenni.steps.Step object>

Provides access to Jenkins workflow (aka pipeline) steps.

groovyjobbase

class jenni.models.groovyjobbase.GroovyJobBase(**kwargs)[source]

Baseclass for jobs that are implemented using Groovy pipeline scripts (https://www.jenkins.io/doc/book/pipeline/#scripted-pipeline-fundamentals).

__init__(**kwargs)[source]
Parameters

kwargs -- optional arguments. Passed through to PipelineJobBase __init__().

code(code: str)[source]

Include the specified text (normally Groovy scripted pipeline code) into the job.

See include() for {python('''<code>''')} replacements.

Parameters

code -- literal text to be inserted into the job pipeline script.

get_file_contents(filename: str) → str[source]

Return the contents of the file.

No replacements are done like in the include() method.

Parameters

filename -- See lookup_relative_filename() for how the file may be found.

include(filename: str)[source]

Include the specified file (normally Groovy scripted pipeline code) into the job.

Contents is checked for occurances of {python('''<code>''')} strings, and replaced with the result of executing <code>. Instead of 3 single quotes, 3 double, or 1 single/double quote can be used.

Parameters

filename -- See lookup_relative_filename() for how a file may be found.

include_first(filenames: List[str])[source]

Include the first found amongst the specified files (normally Groovy scripted pipeline code) into the job.

See include() for {python('''<code>''')} replacements.

Parameters

filenames -- See lookup_relative_filename() for how each file may be found.

Pipeline Execution Steps

steps.archiveArtifacts

class jenni.steps.archiveArtifacts.Step[source]

https://www.jenkins.io/doc/pipeline/steps/core/#archiveartifacts-archive-the-artifacts

archiveArtifacts(artifacts: Union[str, List[str]], allowEmptyArchive=False, caseSensitive=True, defaultExcludes=True, excludes='', fingerprint=True, onlyIfSuccessful=False)[source]

steps.build

class jenni.steps.build.Step[source]
CLASS_MAP = {'bool': 'BooleanParameterValue', 'string': 'StringParameterValue', 'text': 'TextParameterValue'}
build(job: str, parameters: Optional[List] = None, propagate: bool = True, wait: bool = True) → Union[None, dict][source]
Parameters

  • job -- Name of a downstream job to build. May be another Pipeline job, but more commonly a freestyle or other project. Use a simple name if the job is in the same folder as this upstream Pipeline job; otherwise can use relative paths like ../sister-folder/downstream or absolute paths like /top-level-folder/nested-folder/downstream

  • parameters --

    list of [type, name, value].

    Name and value are obvious; type is one of the types listed in https://www.jenkins.io/doc/pipeline/steps/pipeline-build-step/#build-build-a-job EG:

    • "booleanParam"

    • "string"

    • "text"

  • propagate -- If enabled (default state), then the result of this step is that of the downstream build (e.g., success, unstable, failure, not built, or aborted). If disabled, then this step succeeds even if the downstream build is unstable, failed, etc.; use the result property of the return value as needed.

  • wait -- Wait for the job to complete. Defaults to True.

Returns

You may ask that this Pipeline build wait for completion of the downstream build. In that case the return value of the step is an object on which you can obtain the following read-only properties: so you can inspect its .result and so on.

getBuildCauses

Returns a JSON array of build causes for the current build

EXPERIMENTAL - MAY CHANGE getBuildCauses(String causeClass)

Takes a string representing the fully qualified Cause class and returns a JSON array of build causes filtered by that type for the current build, or an empty JSON array if no causes of the specified type apply to the current build

number

build number (integer)

result

typically SUCCESS, UNSTABLE, or FAILURE (may be null for an ongoing build)

currentResult

typically SUCCESS, UNSTABLE, or FAILURE. Will never be null.

resultIsBetterOrEqualTo(String)

Compares the current build result to the provided result string (SUCCESS, UNSTABLE, or FAILURE) and returns true if the current build result is better than or equal to the provided result.

resultIsWorseOrEqualTo(String)

Compares the current build result to the provided result string (SUCCESS, UNSTABLE, or FAILURE) and returns true if the current build result is worse than or equal to the provided result.

displayName

normally #123 but sometimes set to, e.g., an SCM commit identifier.

fullDisplayName

normally folder1 » folder2 » foo #123.

projectName

Name of the project of this build, such as foo.

fullProjectName

Full name of the project of this build, including folders such as folder1/folder2/foo.

description

additional information about the build

id

normally number as a string

timeInMillis

time since the epoch when the build was scheduled

startTimeInMillis

time since the epoch when the build started running

duration

duration of the build in milliseconds

durationString

a human-readable representation of the build duration

previousBuild

another similar object, or null

nextBuild

similarly

absoluteUrl

URL of build index page

buildVariables

for a non-Pipeline downstream build, offers access to a map of defined build variables; for a Pipeline downstream build, any variables set globally on env at the time the build ends. Child Pipeline jobs can use this to report additional information to the parent job by setting variables in env. Note that build parameters are not shown in buildVariables.

changeSets

a list of changesets coming from distinct SCM checkouts; each has a kind and is a list of commits; each commit has a commitId, timestamp, msg, author, and affectedFiles each of which has an editType and path; the value will not generally be Serializable so you may only access it inside a method marked @NonCPS

upstreamBuilds

a list of upstream builds. These are the builds of the upstream projects whose artifacts feed into this build.

rawBuild

a hudson.model.Run with further APIs, only for trusted libraries or administrator-approved scripts outside the sandbox; the value will not be Serializable so you may only access it inside a method marked @NonCPS

keepLog

true if the log file for this build should be kept and not deleted.

If you do not wait, this step succeeds so long as the downstream build can be added to the queue (it will not even have been started). In that case there is currently no return value.

steps.sh

class jenni.steps.sh.Step[source]
sh(script: str, returnStatus: bool = False, returnStdout: bool = False) → Union[None, int, str][source]

Runs sh workflow step. @see https://www.jenkins.io/doc/pipeline/steps/workflow-durable-task-step/#sh-shell-script :param script: Runs a Bourne shell script, typically on a Unix node. Multiple lines are accepted. An interpreter selector may be used, for example: #!/usr/bin/perl Otherwise the system default shell will be run, using the -xe flags (you can specify set +e and/or set +x to disable those). :param returnStatus: Normally, a script which exits with a nonzero status code will cause the step to fail with an exception. If this option is checked, the return value of the step will instead be the status code. You may then compare it to zero, for example. :param returnStdout: If checked, standard output from the task is returned as the step value as a String, rather than being printed to the build log. (Standard error, if any, will still be printed to the log.) You will often want to call .trim() on the result to strip off a trailing newline. :return:

steps.stashing

class jenni.steps.stashing.Step[source]
stash(name: str, includes: str)[source]
unstash(name: str)[source]