A Python API for interacting with Go Continuous Delivery

Coverage Status Build Status Documentation Status Latest Version Downloads Python versions Package status

The reason for this project is to provide a wrapper to easily perform operations against Go. I’ve been writing a lot of shell scripts to interact with Go using curl, but when going a little further than the most basic interactions I’ve always started to feel the need for doing all of this in a proper programming language. I.e. something that is beyond bash.

I’ve chosen to use Python and version 2.6.6 and newer as my target platform, with no external dependencies, to make it really straightforward to install/run on RHEL6 and other similar stable distributions.

This library was created to support a Go CLI, to handle some common scenarios you as an admin or advanced user would do.

API documentation available on read the docs.

Usage

The main interaction point for this library is the Server class, it contains helpers to instantiate the different API endpoints.

An example interaction:

>>> from gocd import Server
>>> server = Server('http://localhost:8153', user='ba', password='secret')
>>> pipeline = server.pipeline('Example-Pipeline')
>>> response = pipeline.history()
>>> bool(response)
True
>>> response.status_code
200
>>> response.content_type
'application/json'
>>> response.is_ok
True
>>> response.body
{"pagination":{"offset":0,"total":1,"page_size":10},"pipelines":[...]"}

Style

This project aims to follow the Google Python Style Guide and particularly the section on commenting the code.

Versioning

Semantic versioning is used.

License

MIT License.

API

class gocd.server.Server(host, user=None, password=None)[source]

Interacting with the Go server

If user and password is supplied the client will try to login using HTTP Basic Auth on each request.

The intention is to use this class as a jumping off point to the nicer API wrappers in the gocd.api package.

Example of intended interaction with this class:

>>> import gocd
>>> go_server = gocd.Server('http://localhost:8153', 'admin', 'badger')
>>> pipeline = go_server.pipeline('up42')
>>> response = pipeline.pause('Admin says no work for you.')
>>> response.is_ok
True
Parameters:
  • host (str) – The base URL for your go server. Example: http://go.example.com/
  • user (str) – The username to login as
  • password (str) – The password for this user
add_logged_in_session(response=None)[source]

Make the request appear to be coming from a browser

This is to interact with older parts of Go that doesn’t have a proper API call to be made. What will be done:

  1. If no response passed in a call to go/api/pipelines.xml is made to get a valid session
  2. JSESSIONID will be populated from this request
  3. A request to go/pipelines will be so the authenticity_token (CSRF) can be extracted. It will then silently be injected into post_args on any POST calls that doesn’t start with go/api from this point.
Parameters:

response – a Response object from a previously successful API call. So we won’t have to query go/api/pipelines.xml unnecessarily.
Raises:
  • HTTPError – when the HTTP request fails.
  • AuthenticationFailed – when failing to get the session_id or the authenticity_token.
get(path)[source]

Performs a HTTP GET request to the Go server

Parameters:path (str) – The full path on the Go server to request. This includes any query string attributes.
Raises:HTTPError – when the HTTP request fails.
Returns:
The response from a
urllib2.urlopen() call
Return type:file like object
pipeline(name)[source]

Instantiates a Pipeline with the given name.

Parameters:name – The name of the pipeline you want to interact with
Returns:an instantiated Pipeline.
Return type:Pipeline
pipeline_groups()[source]

Returns an instance of PipelineGroups

Returns:an instantiated PipelineGroups.
Return type:PipelineGroups
post(path, **post_args)[source]

Performs a HTTP POST request to the Go server

Parameters:
  • path (str) – The full path on the Go server to request. This includes any query string attributes.
  • **post_args – Any POST arguments that should be sent to the server
Raises:

HTTPError – when the HTTP request fails.
Returns:

The response from a

urllib2.urlopen() call
Return type:

file like object
request(path, data=None, headers=None, method=None)[source]

Performs a HTTP request to the Go server

Parameters:
  • path (str) – The full path on the Go server to request. This includes any query string attributes.
  • data (str, dict, bool, optional) – If any data is present this request will become a POST request.
  • headers (dict, optional) – Headers to set for this particular request
Raises:

HTTPError – when the HTTP request fails.
Returns:

The response from a

urllib2.urlopen() call
Return type:

file like object
request_debug_level = 0

Sets the debug level for the urllib2 HTTP(s) handlers

stage(pipeline_name, stage_name, pipeline_counter=None)[source]

Returns an instance of Stage

Parameters:
  • pipeline_name (str) – Name of the pipeline the stage belongs to
  • stage_name (str) – Name of the stage to act on
  • pipeline_counter (int) – The pipeline instance the stage is for.
Returns:

an instantiated Stage.
Return type:

Stage
exception gocd.server.AuthenticationFailed[source]

Indices and tables