jaypore_ci package

Subpackages

• jaypore_ci.executors package
  • Submodules
  • jaypore_ci.executors.docker module
    • Docker
      • Docker.create_network()
      • Docker.delete_all_jobs()
      • Docker.delete_network()
      • Docker.delete_old_containers()
      • Docker.get_execution_order()
      • Docker.get_job_name()
      • Docker.get_net()
      • Docker.get_status()
      • Docker.logging()
      • Docker.run()
      • Docker.set_pipeline()
      • Docker.setup()
      • Docker.teardown()
  • Module contents
• jaypore_ci.remotes package
  • Submodules
  • jaypore_ci.remotes.email module
    • Email
      • Email.from_env()
      • Email.logging()
      • Email.publish()
      • Email.smtp
  • jaypore_ci.remotes.git module
    • GitRemote
      • GitRemote.from_env()
      • GitRemote.logging()
      • GitRemote.publish()
  • jaypore_ci.remotes.gitea module
    • Gitea
      • Gitea.from_env()
      • Gitea.get_pr_id()
      • Gitea.logging()
      • Gitea.publish()
  • jaypore_ci.remotes.github module
    • Github
      • Github.from_env()
      • Github.get_pr_id()
      • Github.logging()
      • Github.publish()
  • jaypore_ci.remotes.mock module
    • Mock
      • Mock.from_env()
      • Mock.get_pr_id()
      • Mock.logging()
      • Mock.publish()
  • Module contents
• jaypore_ci.reporters package
  • Submodules
  • jaypore_ci.reporters.common module
    • clean_logs()
  • jaypore_ci.reporters.markdown module
    • Markdown
      • Markdown.render()
  • jaypore_ci.reporters.text module
    • Text
      • Text.render()
    • get_job_report()
  • Module contents
• jaypore_ci.repos package
  • Submodules
  • jaypore_ci.repos.git module
    • Git
      • Git.files_changed()
      • Git.from_env()
  • Module contents

Submodules

jaypore_ci.changelog module

jaypore_ci.clean module

jaypore_ci.clean.name(given)

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)

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)

Bases: NamedTuple

major: int

Alias for field number 0

minor: int

Alias for field number 1

classmethod parse(inp: str) → Version

patch: int

Alias for field number 2

trail: str

Alias for field number 3

jaypore_ci.config.get_version() → Version

jaypore_ci.exceptions module

exception jaypore_ci.exceptions.BadConfig

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

Bases: object

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

get_status(run_id: str) → JobStatus

Returns the status of a given run.

run(job: Job) → str

Run a job and return it’s ID

set_pipeline(pipeline: Pipeline) → None

Set the current pipeline to the given one.

setup() → None

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

teardown() → None

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)

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)

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)

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)

Publish this report somewhere.

setup() → None

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

teardown() → None

This function will be called once the pipeline is finished.

exception jaypore_ci.interfaces.RemoteApiFailed

Bases: Exception

Failure while working with a remote

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

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

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

Works with the following formats:

ssh://git@gitea.arjoonn.com:arjoonn/jaypore_ci.git ssh+git://git@gitea.arjoonn.com:arjoonn/jaypore_ci.git

git@gitea.arjoonn.com:arjoonn/jaypore_ci.git git@gitea.arjoonn.com:arjoonn/jaypore_ci.git

https://gitea.arjoonn.com/midpath/jaypore_ci.git http://gitea.arjoonn.com/midpath/jaypore_ci.git

repo: str

Alias for field number 2

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

Bases: object

Contains information about the current VCS repo.

files_changed(target: str) → List[str]

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

classmethod from_env() → Repo

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

class jaypore_ci.interfaces.Reporter

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

Render a report for the pipeline.

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

Bases: Enum

Each pipeline can ONLY be in any one of these statuses

FAILED = 40

PASSED = 50

PENDING = 10

RUNNING = 30

SKIPPED = 70

TIMEOUT = 60

exception jaypore_ci.interfaces.TriggerFailed

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)

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().

Parameters:

• 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)

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

get_env()

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

1. Pipeline

2. Stage

3. Job

is_complete() → bool

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

logging()

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

trigger()

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

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)

Bases: object

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

Parameters:

• 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)

Return a cartesian product of all the provided kwargs.

get_status() → Status

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

get_status_dot() → str

Get’s the status dot for the pipeline.

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

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.

logging()

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

property pipe_id

run()

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)

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

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

warn(message: str) → None

warning(message: str) → None

class jaypore_ci.logging.JayporeLoggerFactory

Bases: object

Module contents