jaypore_ci package



jaypore_ci.changelog module

jaypore_ci.clean module


Clean a given name so that it can be used inside of JCI.

jaypore_ci.config module

class jaypore_ci.config.Const(expected_version, version)[source]

Bases: NamedTuple

expected_version: Version

Alias for field number 0

version: Version

Alias for field number 1

class jaypore_ci.config.Version(major, minor, patch, trail)[source]

Bases: NamedTuple

major: int

Alias for field number 0

minor: int

Alias for field number 1

classmethod parse(inp: str) Version[source]
patch: int

Alias for field number 2

trail: str

Alias for field number 3

jaypore_ci.config.get_version() Version[source]

jaypore_ci.exceptions module

exception jaypore_ci.exceptions.BadConfig[source]

Bases: Exception

Raised when a given configuration for a pipeline will cause errors / unexpected behaviour if it is allowed to run.

jaypore_ci.interfaces module

Defines interfaces for remotes and executors.

Currently only gitea and docker are supported as remote and executor respectively.

class jaypore_ci.interfaces.Executor[source]

Bases: object

An executor is something used to run a job. It could be docker / podman / shell etc.

get_status(run_id: str) JobStatus[source]

Returns the status of a given run.

run(job: Job) str[source]

Run a job and return it’s ID

set_pipeline(pipeline: Pipeline) None[source]

Set the current pipeline to the given one.

setup() None[source]

This function is meant to perform any work that should be done before running any jobs.

teardown() None[source]

On exit the executor must clean up any pending / stuck / zombie jobs that are still there.

class jaypore_ci.interfaces.JobStatus(is_running, exit_code, logs, started_at, finished_at)[source]

Bases: NamedTuple

exit_code: int

Alias for field number 1

finished_at: str

Alias for field number 4

is_running: bool

Alias for field number 0

logs: str

Alias for field number 2

started_at: str

Alias for field number 3

class jaypore_ci.interfaces.Remote(*, sha, branch)[source]

Bases: object

Something that allows us to show other people the status of the CI job. It could be gitea / github / gitlab / email system.

classmethod from_env(*, repo: Repo)[source]

This function should create a Remote instance from the given environment. It can read git information / look at environment variables etc.

publish(report: str, status: str)[source]

Publish this report somewhere.

setup() None[source]

This function is meant to perform any work that should be done before running any jobs.

teardown() None[source]

This function will be called once the pipeline is finished.

exception jaypore_ci.interfaces.RemoteApiFailed[source]

Bases: Exception

Failure while working with a remote

class jaypore_ci.interfaces.RemoteInfo(netloc: str, owner: str, repo: str, original: str)[source]

Bases: NamedTuple

Holds information about the remote irrespective of if the remote was ssh or https.

netloc: str

Alias for field number 0

original: str

Alias for field number 3

owner: str

Alias for field number 1

classmethod parse(remote: str) RemoteInfo[source]

Given a git remote url string, parses and breaks down information contained in the url.

Works with the following formats:

repo: str

Alias for field number 2

class jaypore_ci.interfaces.Repo(sha: str, branch: str, remote: str, commit_message: str)[source]

Bases: object

Contains information about the current VCS repo.

files_changed(target: str) List[str][source]

Returns list of file paths that have changed between current sha and target.

classmethod from_env() Repo[source]

Creates a Repo instance from the environment and git repo on disk.

class jaypore_ci.interfaces.Reporter[source]

Bases: object

Something that generates the status of a pipeline.

It can be used to generate reports in markdown, plaintext, html, pdf etc.

render(pipeline: Pipeline) str[source]

Render a report for the pipeline.

class jaypore_ci.interfaces.Status(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Each pipeline can ONLY be in any one of these statuses

exception jaypore_ci.interfaces.TriggerFailed[source]

Bases: Exception

Failure to trigger a job

jaypore_ci.jci module

The code submodule for Jaypore CI.

class jaypore_ci.jci.Job(name: str, command: Union[str, Callable], pipeline: Pipeline, *, status: str = None, children: List[Job] = None, parents: List[Job] = None, is_service: bool = False, stage: str = None, image: str = None, timeout: int = None, env: dict = None, executor_kwargs: dict = None)[source]

Bases: object

This is the fundamental building block for running jobs. Each job goes through a lifecycle defined by Status.

A job is run by an Executor as part of a Pipeline.

It is never created manually. The correct way to create a job is to use job().

  • name – The name for the job. Names must be unique across jobs and stages.

  • command – The command that we need to run for the job. It can be set to None when is_service is True.

  • is_service – Is this job a service or not? Service jobs are assumed to be PASSED as long as they start. They are shut down when the entire pipeline has finished executing.

  • pipeline – The pipeline this job is associated with.

  • status – The Status of this job.

  • image – What docker image to use for this job.

  • timeout – Defines how long a job is allowed to run before being killed and marked as class:~jaypore_ci.interfaces.Status.FAILED.

  • env – A dictionary of environment variables to pass to the docker run command.

  • children – Defines which jobs depend on this job’s output status.

  • parents – Defines which jobs need to pass before this job can be run.

  • stage – What stage the job belongs to. This stage name must exist so that we can assign jobs to it.

  • executor_kwargs – A dictionary of keyword arguments that the executor can use when running a job. Different executors may use this in different ways, for example with the Docker executor this may be used to run jobs with –add-host or –device .

check_job(*, with_update_report=True)[source]

This will check the status of the job. If with_update_report is False, it will not push an update to the remote.


Gets the environment variables for a given job. Order of precedence for setting values is:

  1. Pipeline

  2. Stage

  3. Job

is_complete() bool[source]

Is this job complete? It could have passed/ failed etc. We no longer need to check for updates in a complete job.


Returns a logging instance that has job specific information bound to it.


Trigger the job via the pipeline’s executor. This will immediately return and will not wait for the job to finish.

It is also idempotent. Calling this multiple times will only trigger the job once.

update_report() str[source]

Update the status report. Usually called when a job changes some of it’s internal state like when logs are updated or when status has changed.

class jaypore_ci.jci.Pipeline(*, repo: Repo = None, remote: Remote = None, executor: Executor = None, reporter: Reporter = None, poll_interval: int = 10, **kwargs)[source]

Bases: object

A pipeline acts as a controlling/organizing mechanism for multiple jobs.

  • repo – Provides information about the codebase.

  • reporter – Provides reports based on the state of the pipeline.

  • remote – Allows us to publish reports to somewhere like gitea/email.

  • executor – Runs the specified jobs.

  • poll_interval – Defines how frequently (in seconds) to check the pipeline status and publish a report.

classmethod env_matrix(**kwargs)[source]

Return a cartesian product of all the provided kwargs.

get_status() Status[source]

Calculates a pipeline’s status based on the status of it’s jobs.

get_status_dot() str[source]

Get’s the status dot for the pipeline.

job(name: str, command: str, *, depends_on: List[str] = None, **kwargs) Job[source]

Creates a Job instance based on the pipeline/stage that it is being defined in. See Job for details on what parameters can be passed to the job.


Return a logger with information about the current pipeline bound to it.

property pipe_id

Run the pipeline. This is always called automatically when the context of the pipeline declaration finishes and so unless you are doing something fancy you don’t need to call this manually.

stage(name, **kwargs)[source]

A stage in a pipeline.

Any kwargs passed to this stage are supplied to jobs created within this stage.

jaypore_ci.logging module

The basic logging module.

class jaypore_ci.logging.JayporeLogger[source]

Bases: object

This is mainly used to collect logs into a single global variable so that the logs of the CI runner itself can also be posted as part of the CI report.

critical(message: str) None
debug(message: str) None
err(message: str) None
error(message: str) None
exception(message: str) None
failure(message: str) None
fatal(message: str) None
info(message: str) None
log(message: str) None
msg(message: str) None[source]
warn(message: str) None
warning(message: str) None
class jaypore_ci.logging.JayporeLoggerFactory[source]

Bases: object

Module contents