jenkinsflow.flow module

class jenkinsflow.flow.Checking

Bases: jenkinsflow.ordered_enum.OrderedEnum

An enumeration.

class jenkinsflow.flow.KillType

Bases: enum.Enum

An enumeration.

class jenkinsflow.flow.Propagation

Bases: jenkinsflow.ordered_enum.OrderedEnum

An enumeration.

class jenkinsflow.flow.parallel(jenkins_api, timeout, securitytoken=None, username=None, password=None, job_name_prefix='', max_tries=1, propagation=<Propagation.NORMAL: 0>, report_interval=5, poll_interval=0.5, secret_params=re.compile('.*passw.*|.*PASSW.*'), allow_missing_jobs=False, json_dir=None, json_indent=None, json_strip_top_level_prefix=True, direct_url=None, require_idle=True, just_dump=False, params_display_order=(), kill_all=False, description=None)

Bases: jenkinsflow.flow._Parallel, jenkinsflow.flow._TopLevelControllerMixin

Defines a parallel flow where nested jobs or flows are executed simultaneously.

See serial and _Flow.parallel() for a description.

class jenkinsflow.flow.serial(jenkins_api, timeout, securitytoken=None, username=None, password=None, job_name_prefix='', max_tries=1, propagation=<Propagation.NORMAL: 0>, report_interval=5, poll_interval=0.5, secret_params=re.compile('.*passw.*|.*PASSW.*'), allow_missing_jobs=False, json_dir=None, json_indent=None, json_strip_top_level_prefix=True, direct_url=None, require_idle=True, just_dump=False, params_display_order=(), kill_all=False, description=None)

Bases: jenkinsflow.flow._Serial, jenkinsflow.flow._TopLevelControllerMixin

Defines a serial flow where nested jobs or flows are executed in order.

Only differences to _Flow.serial() are described.

Parameters:
  • jenkins_api (jenkins_api.Jenkins or script_api.Jenkins) – Jenkins Api instance used for accessing jenkins. If jenkins_api is instantiated with username/password you do not need to specify username/password to the flow (see below).
  • securitytoken (str) – Token to use on security enabled Jenkins instead of username/password. The Jenkins job must have the token configured.
  • username (str) – Name of user authorized to run Jenkins ‘cli’ and change job status.
  • password (str) – Password of user. The username/password here is are not used for running the jobs. See jenkins_api for that. If username/password is specified for jenkins_api, they will be used unless they are also specified on the flow.
  • job_name_prefix (str) – All jobs defined in flow will automatically be prefixed with this string before invoking Jenkins job.
  • poll_interval (float) – The interval in seconds between polling the status of unfinished Jenkins jobs.
  • allow_missing_jobs (boolean) – If true it is not considered an error if Jenkins jobs are missing when the flow starts. It is assumed that the missing jobs are created by other jobs in the flow
  • json_dir (str) – Directory in which to generate flow graph json file. If None, no flow graph is generated.
  • json_indent (int) – If not None json graph file is pretty printed with this indentation level.
  • json_strip_top_level_prefix (boolean) – If True, the job_name_prefix will be stripped from job names when generating json graph file
  • direct_url (str) – Non proxied url for accessing Jenkins Propagation.WARNING requires this, as it uses the Jenkins cli, which will not work through a proxy, to set the build result.
  • require_idle (boolean) – If True it is considered an error if any of the jobs in the flow are running when the flow starts.
  • just_dump (boolean) – If True, the flow is just printed, no jobs are invoked.
  • params_display_order (list) – List of job parameter names used for ordering the parameters in the output. The format is [first1, ..., firstN, ‘*’, last1, ..., lastN], where first..., last... are names that will be matched against the invoke **param names. Any of first..., ‘*’, last... may be omitted Any parameters that are not matched will be displayes at the place of the ‘*’, if specified, otherwise they will be displayed last.
  • kill_all (boolean) – If True, all running builds for jobs defined in the flow will be aborted, regardless which flow invocation started the build. Note: It also possible to send SIGTERM to an already running flow to make the flow abort all builds started by the current invocation of the flow, but not builds started by other invocations of the same flow.
Returns:

serial flow object
Raises:

JobControlException
class jenkinsflow.flow._Flow
invoke(job_name, **params)

Define a Jenkins job invocation that will be invoked under control of the surrounding flow.

This does not create the job in Jenkins. It defines how the job will be invoked by jenkinsflow.

Parameters:
  • job_name (str) – The last part of the name of the job in jenkins. If the surrounding flow sets the job_name_prefix the actual name of the invoked job will be the parent flow job_name_prefix + job_name.
  • **params (str, int, boolean) – Arguments passed to Jenkins when invoking the job. Strings are passed as they are, booleans are automatically converted to strings and lowercased, integers are automatically converted to strings.
invoke_unchecked(job_name, **params)

Define a Jenkins job invocation that will be invoked under control of the surrounding flow, but will never cause the flow to fail.

The job is always run in parallel with other jobs in the flow, even when invoked in a serial flow. It is not started out of order, but following jobs will be started immediately after this is started. The job will be monitored and reported on, only as long as regular “checked” jobs are still running. If it fails, it may be retried (depending on surrounding flows max_tries option), but only as long as regular jobs are still running. If the job is still running when all normal jobs are finished, the flow will exit, and the job is left running.

See invoke() for parameter description.

parallel(timeout=0, securitytoken=None, job_name_prefix='', max_tries=1, propagation=<Propagation.NORMAL: 0>, report_interval=None, secret_params=None, allow_missing_jobs=None)

Defines a parallel flow where nested jobs or flows are executed simultaneously.

Only differences to serial() are described.

Parameters:max_tries (int) –

Maximum number of times to invoke the jobs in the flow. Default is 1, meaning no retry will be attempted in case jobs fails. If a job fails it is immediately retried:

with parallel(..., max_tries=3) as sf:
    sf.invoke('a', ...)
    sf.invoke('b', ...)  # fail -> restart job 'b'
    sf.invoke('c', ...)
Returns:parallel flow object
serial(timeout=0, securitytoken=None, job_name_prefix='', max_tries=1, propagation=<Propagation.NORMAL: 0>, report_interval=None, secret_params=None, allow_missing_jobs=None)

Defines a serial flow where nested jobs or flows are executed in order.

Parameters:
  • timeout (float) – Maximum time in seconds to wait for flow jobs to finish. 0 means infinite, however, this flow can not run longer than the minimum timeout of any parent flows. Note that jenkins jobs are NOT terminated when the flow times out.
  • securitytoken (str) – Token to use on security enabled Jenkins instead of username/password. The Jenkins job must have the token configured. If None, the parent flow securitytoken is used.
  • job_name_prefix (str) – All jobs defined in flow will automatically be prefixed with the parent flow job_name_prefix + this job_name_prefix before invoking Jenkins job. To reset prefixing (i.e. don’t use parent flow prefix either), set the value to None
  • max_tries (int) –

    Maximum number of times to invoke the flow. Default is 1, meaning no retry will be attempted in case a job fails. If a job fails, jobs are retried from start of the parallel flow:

    with serial(..., max_tries=3) as sf:
    sf.invoke('a', ...)
    sf.invoke('b', ...)  # fail -> restart flow from job 'a'
    sf.invoke('c', ...)

    Retries may be nested:

    with parallel(..., max_tries=2) as sf:
    with sf.serial(..., max_tries=3) as sf:
        sf.invoke('a', ...)  # If a fails it could be invoked up to 6 times
  • propagation (Propagation) – How to propagate errors from failed Jenkins jobs. This will not change the result of the failed job itself, but only the result of the Jenkins job running the flow (if it is being run from a Jenkins job).
  • report_interval (float) – The interval in seconds between reporting the status of polled Jenkins jobs. If None the parent flow report_interval is used.
  • secret_params (re.RegexObject) – Regex of Jenkins job invocation parameter names, for which the value will be masked out with ‘**‘ when parameters are printed. If None the parent flow secret_params is used.
  • allow_missing_jobs (boolean) – If true it is not considered an error if Jenkins jobs are missing when the flow starts. It is assumed that the missing jobs are created by jobs in the flow, prior to the missing jobs being invoked. If None the parent flow allow_missing_jobs is used.
Returns:

serial flow object
Raises:

JobControlException
class jenkinsflow.flow._JobControl
message(msg)

Define a message that will be printed before the invocation of the job or flow on which it is defined.

Parameters:msg (object) – The message that will be printed.