API package

API Wrapper classes

class gocd.api.Pipeline(server, name)

Bases: gocd.api.endpoint.Endpoint

artifact(counter, stage, job, stage_counter=1)

Helper to instantiate an gocd.api.artifact.Artifact object

Parameters:

• counter (int) – The pipeline counter to get the artifact for
• stage – Stage name
• job – Job name
• stage_counter – Defaults to 1

Returns:

gocd.api.artifact.Artifact object

Return type:

Artifact

base_path = 'go/api/pipelines/{id}'

console_output(instance=None)

Yields the output and metadata from all jobs in the pipeline

Parameters:

instance – The result of a instance() call, if not supplied the latest of the pipeline will be used.

Yields:

tuple – (metadata (dict), output (str)).

metadata contains:

• pipeline
• pipeline_counter
• stage
• stage_counter
• job
• job_result

final_results = ['Passed', 'Failed']

history(offset=0)

Lists previous instances/runs of the pipeline

See the `Go pipeline history documentation`__ for example responses.

Parameters:offset (int, optional) – How many instances to skip for this response. Returns:gocd.api.response.Response object Return type:Response

id = 'name'

instance(counter=None)

Returns all the information regarding a specific pipeline run

See the `Go pipeline instance documentation`__ for examples.

Parameters:counter (int) – The pipeline instance to fetch. If falsey returns the latest pipeline instance from history(). Returns:gocd.api.response.Response object Return type:Response

pause(reason='')

Pauses the current pipeline

See the `Go pipeline pause documentation`__ for example responses.

Parameters:reason (str, optional) – The reason the pipeline is being paused. Returns:gocd.api.response.Response object Return type:Response

release()

Releases a previously locked pipeline

See the `Go pipeline release lock documentation`__ for example responses.

Returns:gocd.api.response.Response object Return type:Response

run(variables=None, secure_variables=None, materials=None, return_new_instance=False, backoff_time=1.0)

Schedule a pipeline run

Aliased as run(), schedule(), and trigger().

Parameters:

• variables (dict, optional) – Variables to set/override
• secure_variables (dict, optional) – Secure variables to set/override
• materials (dict, optional) – Material revisions to be used for this pipeline run. The exact format for this is a bit iffy, have a look at the official `Go pipeline scheduling documentation`__ or inspect a call from triggering manually in the UI.
• return_new_instance (bool) – Returns a history() compatible response for the newly scheduled instance. This is primarily so users easily can get the new instance number. Note: This is done in a very naive way, it just checks that the instance number is higher than before the pipeline was triggered.
• backoff_time () – How long between each check for :arg:`return_new_instance`.

Returns:

gocd.api.response.Response object

Return type:

Response

schedule(variables=None, secure_variables=None, materials=None, return_new_instance=False, backoff_time=1.0)

Schedule a pipeline run

Aliased as run(), schedule(), and trigger().

Parameters:

• variables (dict, optional) – Variables to set/override
• secure_variables (dict, optional) – Secure variables to set/override
• materials (dict, optional) – Material revisions to be used for this pipeline run. The exact format for this is a bit iffy, have a look at the official `Go pipeline scheduling documentation`__ or inspect a call from triggering manually in the UI.
• return_new_instance (bool) – Returns a history() compatible response for the newly scheduled instance. This is primarily so users easily can get the new instance number. Note: This is done in a very naive way, it just checks that the instance number is higher than before the pipeline was triggered.
• backoff_time () – How long between each check for :arg:`return_new_instance`.

Returns:

gocd.api.response.Response object

Return type:

Response

stage(name, pipeline_counter=None)

Helper to instantiate a gocd.api.stage.Stage object

Parameters:

• name – The name of the stage
• pipeline_counter –

Returns:

status()

Returns the current status of this pipeline

See the `Go pipeline status documentation`__ for example responses.

Returns:gocd.api.response.Response object Return type:Response

trigger(variables=None, secure_variables=None, materials=None, return_new_instance=False, backoff_time=1.0)

Schedule a pipeline run

Aliased as run(), schedule(), and trigger().

Parameters:

• variables (dict, optional) – Variables to set/override
• secure_variables (dict, optional) – Secure variables to set/override
• materials (dict, optional) – Material revisions to be used for this pipeline run. The exact format for this is a bit iffy, have a look at the official `Go pipeline scheduling documentation`__ or inspect a call from triggering manually in the UI.
• return_new_instance (bool) – Returns a history() compatible response for the newly scheduled instance. This is primarily so users easily can get the new instance number. Note: This is done in a very naive way, it just checks that the instance number is higher than before the pipeline was triggered.
• backoff_time () – How long between each check for :arg:`return_new_instance`.

Returns:

gocd.api.response.Response object

Return type:

Response

unlock()

Releases a previously locked pipeline

See the `Go pipeline release lock documentation`__ for example responses.

Returns:gocd.api.response.Response object Return type:Response

unpause()

Unpauses the pipeline

See the `Go pipeline unpause documentation`__ for example responses.

Returns:gocd.api.response.Response object Return type:Response

class gocd.api.PipelineGroups(server)

Bases: gocd.api.endpoint.Endpoint

base_path = 'go/api/config'

get_pipeline_groups()

Makes a call to the Go server to fetch the pipeline groups.

Saves the response to response.

Returns:an instance of gocd.api.Response Return type:Response

pipelines

Returns a set of all pipelines from the last response

Returns:

Response success: all the pipelines available in the response

Response failure: an empty set

Return type:set

response

Returns the last response from fetching the pipeline groups from Go

If there is no response then one will be fetched and returned.

Returns:an instance of gocd.api.Response Return type:Response

class gocd.api.Artifact(server, pipeline, counter, stage, job, stage_counter=1)

Bases: gocd.api.endpoint.Endpoint

base_path = 'go/files/{pipeline}/{counter}/{stage}/{stage_counter}/{job}'

get(path_to_file)

Gets an artifact directory by its path.

See the `Go artifact file documentation`__ for example responses.

Parameters:path_to_file (str) – The path to file to get. It can be nested eg dist/foobar-widgets-1.2.0.jar Returns:gocd.api.response.Response object Return type:Response

get_directory(path_to_directory, timeout=30, backoff=0.4, max_wait=4)

Gets an artifact directory by its path.

See the `Go artifact directory documentation`__ for example responses.

Note

Getting a directory relies on Go creating a zip file of the directory in question. Because of this Go will zip the file in the background and return a 202 Accepted response. It’s then up to the client to check again later and get the final file.

To work with normal assumptions this get_directory() will retry itself up to timeout seconds to get a 200 response to return. At that point it will then return the response as is, no matter whether it’s still 202 or 200. The retry is done with an exponential backoff with a max value between retries. See the backoff and max_wait variables.

If you want to handle the retry logic yourself then use get() and add ‘.zip’ as a suffix on the directory.

Parameters:

• path_to_directory (str) – The path to the directory to get. It can be nested eg target/dist.zip
• timeout (int) – How many seconds we will wait in total for a successful response from Go when we’re receiving 202
• backoff (float) – The initial value used for backoff, raises exponentially until it reaches max_wait
• max_wait (int) – The max time between retries

Returns:

gocd.api.response.Response object

A successful response is a zip-file.

Return type:

Response

list()

Lists all available artifacts in this job.

See the `Go artifact list documentation`__ for example responses.

Returns:gocd.api.response.Response object Return type:Response

class gocd.api.Stage(server, pipeline_name, stage_name, pipeline_counter=None)

Bases: gocd.api.endpoint.Endpoint

base_path = 'go/api/stages/{id}'

cancel()

Cancels a currently running stage

Returns:gocd.api.response.Response object Return type:Response

get_id()

history(offset=0)

Lists previous instances/runs of the stage

See the `Go stage history documentation`__ for example responses.

Parameters:offset (int, optional) – How many instances to skip for this response. Returns:gocd.api.response.Response object Return type:Response

instance(counter=None, pipeline_counter=None)

Returns all the information regarding a specific stage run

See the `Go stage instance documentation`__ for examples.

Parameters:

• counter (int) – The stage instance to fetch. If falsey returns the latest stage instance from history().
• pipeline_counter (int) – The pipeline instance for which to fetch the stage. If falsey returns the latest pipeline instance.

Returns:

gocd.api.response.Response object

Return type:

Response

class gocd.api.PipelineConfig(server, name, api_version=4)

Bases: gocd.api.endpoint.Endpoint

base_path = 'go/api/admin/pipelines'

create(config)

Update pipeline config for specified pipeline name.

Returns:gocd.api.response.Response object Return type:Response

edit(config, etag)

Update pipeline config for specified pipeline name.

Returns:gocd.api.response.Response object Return type:Response

final_results = ['Passed', 'Failed']

get()

Gets pipeline config for specified pipeline name.

See `The pipeline config object`__ for example responses.

Returns:gocd.api.response.Response object Return type:Response

id = 'name'

class gocd.api.PluggableSCM(server, name='')

Bases: gocd.api.endpoint.Endpoint

base_path = 'go/api/admin/scms'

create(config)

Create a global SCM object

Returns:gocd.api.response.Response object Return type:Response

edit(config, etag)

Update SCM material for specified material name.

Returns:gocd.api.response.Response object Return type:Response

get()

Gets SCM material for specified material name

See `The global scm config object`__ for example responses.

Returns:gocd.api.response.Response object Return type:Response

id = 'name'

list()

Lists all available pluggable scm materials,

these are materials that are present in the in cruise-config.xml.

See the `Go pluggable SCM documentation`__ for example responses.

Returns:gocd.api.response.Response object Return type:Response

class gocd.api.TemplateConfig(server, name, api_version=2)

Bases: gocd.api.endpoint.Endpoint

base_path = 'go/api/admin/templates'

create(config)

Create template config for specified template name.

Returns:gocd.api.response.Response object Return type:Response

delete()

Delete template config for specified template name.

Returns:gocd.api.response.Response object Return type:Response

edit(config, etag)

Update template config for specified template name.

Returns:gocd.api.response.Response object Return type:Response

get()

Get template config for specified template name.

See `The template config object`__ for example responses.

Returns:gocd.api.response.Response object Return type:Response

id = 'name'

API Response class

class gocd.api.response.Response(status_code, body, headers=None, ok_status=200)

Bases: object

A nicely wrapped HTTP Response

This class will be instantiated from API calls and is not intended to be used in any other way.

Special handling of the responses:

1. A response has a boolean value that corresponds with is_ok():

   >>> bool(Response(404, 'Not found'))
   False
   >>> bool(Response(200, 'OK'))
   True
   

2. If the payload is json you can access the json object through the response as if it was a dict:

   >>> response = Response(200, '{"hello": "there"}',
                           {'Content-Type': 'application/json'})
   >>> response['hello']
   "there"
   

3. If the payload is json you can look if a key is part of the payload as you would with a dict:

   >>> response = Response(200, '{"hello": "there"}',
                           {'Content-Type': 'application/json'})
   >>> 'hello' in response
   True
   

Parameters:

• status_code (int) – The HTTP status of this response
• body (str, fp) – The HTTP response body/payload of this response
• headers (dict, optional) – The headers supplied by this response
• ok_status (int, optional) – If the status_code is this then this response is successful. Default: 200

body

Alias for payload()

etag

fp

Returns a file-like object if the class was instantiated with one

Returns:If :attribute:`_body` responds to read else None Return type:None, file-like object

is_json

**Returns* – bool* – True if content_type is application/json

is_ok

Whether this response is considered successful

Returns

bool: True if status_code is ok_status

payload

Returns – str when not json. dict when json.