Universal Python client for Jenkins

Python client for Jenkins which supports both sync and async syntax with same interface.

Comparison to other packages
Name	Sync	Async	Python
ujenkins	YES	YES	3.6+
aiojenkins	NO	YES	3.5+
python-jenkins	YES	NO	3.4+
jenkinsapi	YES	NO	3.4+

Installation

Latest release from PyPI

pip3 install ujenkins

Or latest developing version

pip3 install git+https://github.com/pbelskiy/ujenkins

Usage

Get Jenkins version using sync client:

from ujenkins import JenkinsClient

def example():
    client = JenkinsClient('http://server', 'user', 'password')
    version = client.system.get_version()
    print(version)

example()

With async client (be careful AsyncJenkinsClient must be called inside async function):

import asyncio
from ujenkins import AsyncJenkinsClient

async def example():
    client = AsyncJenkinsClient('http://server', 'user', 'password')
    version = await client.system.get_version()
    print(version)
    await client.close()

asyncio.run(example())

Examples

In all code examples below client instance is created by:

from ujenkins import JenkinsClient
client = JenkinsClient('http://server', 'user', 'password')

Get timestamp of latest build

client.builds.get_info('job', 'lastBuild')['timestamp']

Get url of started build

Be careful, JenkinsNotFoundError could be raise in case build with same arg already enqueued.

item_id = client.builds.start('my_job')
while True:
    time.sleep(5)
    try:
        info = client.queue.get_info(item_id)
        print(info['executable']['url'])
        break
    except (KeyError, TypeError):
        pass  # wait for build will be started

Get all jobs

Basically client.jobs.get() returns jobs from root (depth = 0), in case you want receive all the jobs, there are few approaches for it.

Set needed depth, experimentally 10 is enough.

jobs = client.jobs.get(depth=10)

Output:

{'folder': {'_class': 'com.cloudbees.hudson.plugins.folder.Folder',
            'jobs': [{'_class': 'hudson.model.FreeStyleProject',
                    'color': 'notbuilt',
                    'name': 'job_in_folder1',
                    'url': 'http://localhost:8080/job/folder/job/job_in_folder1/'},
                    {'_class': 'com.cloudbees.hudson.plugins.folder.Folder',
                    'jobs': [{'_class': 'hudson.model.FreeStyleProject',
                                'color': 'notbuilt',
                                'name': 'sub_job_in_subfolder',
                                'url': 'http://localhost:8080/job/folder/job/subfolder/job/sub_job_in_subfolder/'}],
                    'name': 'subfolder',
                    'url': 'http://localhost:8080/job/folder/job/subfolder/'}],
            'name': 'folder',
            'url': 'http://localhost:8080/job/folder/'},
'job': {'_class': 'hudson.model.FreeStyleProject',
        'color': 'blue',
        'name': 'job',
        'url': 'http://localhost:8080/job/job/'}}

Or just write your code to recursively form it, example is below.

def get_all_jobs(url: str = '', parent: str = '') -> Dict[str, dict]:
    jobs = {}

    for name, prop in client.jobs.get(url).items():
        jobs[parent + name] = prop
        if 'Folder' in prop.get('_class', ''):
            jobs.update(get_all_jobs(prop['url'], parent + name + '/'))

    return jobs

all_jobs = get_all_jobs()

Working with build artifacts

# get content of artifact (bytes)
content = client.builds.get_artifact('my_job', 31, 'photo.jpg')
with open('/tmp/photo.jpg', 'wb') as f:
    w.write(content)

# enumerate artifacts
artifacts = client.builds.get_list_artifacts('my_job', 31)
for artifact in artifacts:
    # get content and manually save it
    content = client.builds.get_artifact('my_job', 31, artifact['path'])

    # or absolute url could be used for external download
    print(artifact['url'])
    # >> 'http://server/job/my_job/31/artifact/photo.jpg'

Documentation

Read the Docs

Testing

Prerequisites: tox

Then just run tox, all dependencies and checks will run automatically

tox

Contributing

Any contributions are welcome!

stevemuskiewicz/ujenkins