yagocd.resources package

Submodules

yagocd.resources.agent module

class yagocd.resources.agent.AgentEntity(session, data, etag=None)

Bases: yagocd.resources.Base

class yagocd.resources.agent.AgentManager(session)

Bases: yagocd.resources.BaseManager

The agents API allows users with administrator role to manage agents.

Official documentation.

Versionadded:15.2.0. Warning:Please note that this API requires using v4 of the API using Accept: application/vnd.go.cd.v4+json

ACCEPT_HEADER = 'application/vnd.go.cd.v4+json'

RESOURCE_PATH = '{base_api}/agents'

VERSION_TO_ACCEPT_HEADER = {'16.7.0': 'application/vnd.go.cd.v2+json', '16.9.0': 'application/vnd.go.cd.v3+json', '16.1.0': 'application/vnd.go.cd.v1+json'}

delete(*args, **kwargs)

Deletes an agent.

Versionadded:15.2.0. Parameters:uuid – uuid of the agent. Returns:a message confirmation if the agent was deleted.

dict(*args, **kwargs)

Wrapper for list() method, that transforms founded agents to dictionary by uuid key.

Returns:dictionary of agents with uuid as a key and agent as a value. Return type:dict[str, yagocd.resources.agent.AgentEntity]

get(*args, **kwargs)

Gets an agent by its unique identifier (uuid).

Versionadded:15.2.0. Parameters:uuid – uuid of the agent Returns:Agent entity. Return type:yagocd.resources.agent.AgentEntity

job_history(*args, **kwargs)

Lists the jobs that have executed on an agent.

Versionadded:

14.3.0.

Parameters:

• uuid – uuid of the agent.
• offset – number of jobs to be skipped.

Returns:

an array of yagocd.resources.job.JobInstance along with the job transitions.

Return type:

list of yagocd.resources.job.JobInstance

list(*args, **kwargs)

Lists all available agents, these are agents that are present in the <agents/> tag inside cruise-config.xml and also agents that are in Pending state awaiting registration.

Versionadded:15.2.0. Returns:an array of agents. Return type:list of yagocd.resources.agent.AgentEntity

update(*args, **kwargs)

Update some attributes of an agent.

Versionadded:

15.2.0.

Parameters:

• uuid – uuid of the agent
• config – dictionary of parameters for update

Returns:

Agent entity.

Return type:

yagocd.resources.agent.AgentEntity

yagocd.resources.artifact module

class yagocd.resources.artifact.Artifact(session, data)

Bases: yagocd.resources.Base

Class, representing artifact of the build.

It could be one of file or folder.

PART_COUNT = 5

SEP = '/'

fetch()

Method for getting artifact’s content. Could only be applicable for file type.

Returns:content of the artifact.

job_name

path

pipeline_counter

pipeline_name

stage_counter

stage_name

walk(topdown=True)

Artifact tree generator - analogue of os.walk.

Parameters:topdown – if is True or not specified, directories are scanned

from top-down. If topdown is set to False, directories are scanned from bottom-up. :rtype: collections.Iterator[

(str, list[yagocd.resources.artifact.Artifact], list[yagocd.resources.artifact.Artifact])

]

class yagocd.resources.artifact.ArtifactManager(session, pipeline_name=None, pipeline_counter=None, stage_name=None, stage_counter=None, job_name=None)

Bases: yagocd.resources.BaseManager, yagocd.util.RequireParamMixin

The artifacts API allows users to query and create artifacts of a job.

Official documentation.

Versionadded:14.3.0.

FILES_FIELD = 'files'

FILE_TYPE = 'file'

FOLDER_TYPE = 'folder'

NAME_FIELD = 'name'

PATH_PARAMETERS = ['pipeline_name', 'pipeline_counter', 'stage_name', 'stage_counter', 'job_name']

RESOURCE_PATH = '{base_api}/files/{pipeline_name}/{pipeline_counter}/{stage_name}/{stage_counter}/{job_name}'

TYPE_FIELD = 'type'

append(*args, **kwargs)

Appends a local file to an existing artifact.

Versionadded:

14.3.0.

Parameters:

• path – path to the file within job directory.
• filename – the contents file to be uploaded.
• pipeline_name – name of the pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of the stage.
• stage_counter – stage counter.
• job_name – name of the job.

Returns:

an acknowledgement that the file was created.

create(*args, **kwargs)

Uploads a local file as an artifact.

Versionadded:

14.3.0.

Parameters:

• path – path to the file within job directory.
• filename – the contents file to be uploaded.
• pipeline_name – name of the pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of the stage.
• stage_counter – stage counter.
• job_name – name of the job.

Returns:

an acknowledgement that the file was created.

directory(*args, **kwargs)

Gets an artifact directory by its path.

Versionadded:

14.3.0.

Note:

The path can be a nested directory for e.g. target/dist.zip

Warning:

Since it may take an undetermined amount of time to compress a directory, the server may return a 202 Accepted code to indicate that it is compressing the requested directory. Users are expected to poll the url every few seconds to check if the directory is available.

Parameters:

• path – path to directory.
• pipeline_name – name of the pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of the stage.
• stage_counter – stage counter.
• job_name – name of the job.

Returns:

• A status code 202 Accepted to acknowledge your request to compress the contents of the requested directory.
• The requested directory contents in the form of a zip file.

directory_wait(*args, **kwargs)

Gets an artifact directory by its path. This method wraps original directory method, adding timeout to wait for directory to be available.

Versionadded:

14.3.0.

Parameters:

• path – path to directory.
• timeout – timeout in seconds to wait for directory.
• backoff – backoff value.
• max_wait – maximum wait amount.
• pipeline_name – name of the pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of the stage.
• stage_counter – stage counter.
• job_name – name of the job.

Returns:

The requested directory contents in the form of a zip file.

file(*args, **kwargs)

Gets an artifact file by its path.

Versionadded:

14.3.0.

Note:

The path_to_file can be a nested file for e.g. dist/foobar-widgets-1.2.0.jar.

Parameters:

• path – path to the file.
• pipeline_name – name of the pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of the stage.
• stage_counter – stage counter.
• job_name – name of the job.

Returns:

the contents of the file you requested.

list(*args, **kwargs)

Lists all available artifacts in a job.

Versionadded:

14.3.0.

Parameters:

• pipeline_name – name of the pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of the stage.
• stage_counter – stage counter.
• job_name – name of the job.

Returns:

An array of yagocd.resources.artifact.Artifact.

Return type:

list of yagocd.resources.artifact.Artifact

walk(*args, **kwargs)

Artifact tree generator - analogue of os.walk.

Parameters:

• top – root path, from which traversal would be started.
• topdown – if is True or not specified, directories are scanned

from top-down. If topdown is set to False, directories are scanned from bottom-up. :param pipeline_name: name of the pipeline. :param pipeline_counter: pipeline counter. :param stage_name: name of the stage. :param stage_counter: stage counter. :param job_name: name of the job. :rtype: collections.Iterator[

(str, list[yagocd.resources.artifact.Artifact], list[yagocd.resources.artifact.Artifact])

]

yagocd.resources.configuration module

class yagocd.resources.configuration.ConfigurationManager(session)

Bases: yagocd.resources.BaseManager

The configuration API allows users with administration role to view and manage configuration.

Official documentation.

Versionadded:14.3.0.

ADMIN_RESOURCE_PATH = '{base_api}/admin/config'

RESOURCE_PATH = '{base_api}/config'

config(*args, **kwargs)

Gets the current configuration file.

Versionadded:14.3.0. Parameters:md5 – md5 sum of config to get. If not given, current will be returned. Returns:the contents of the configuration file.

diff(*args, **kwargs)

Gets the diff between two config repository modifications.

Versionadded:

14.3.0.

Parameters:

• start – starting SHA commit.
• end – ending SHA commit.

Returns:

the diff between two config repo modifications.

modifications(*args, **kwargs)

Lists the config repository modifications.

Versionadded:14.3.0. Returns:An array of repository modifications.

yagocd.resources.environment module

class yagocd.resources.environment.EnvironmentConfig(session, data, etag=None)

Bases: yagocd.resources.Base

class yagocd.resources.environment.EnvironmentManager(session)

Bases: yagocd.resources.BaseManager

The environment config API allows users with administrator role to manage environment config.

Official documentation.

Versionadded:16.7.0.

RESOURCE_PATH = '{base_api}/admin/environments'

create(*args, **kwargs)

Creates an environment.

Parameters:config – new environment configuration. Return type:yagocd.resources.environment.EnvironmentConfig

delete(*args, **kwargs)

Deletes an environment.

Parameters:name – name of the environment to delete. Returns:A message confirmation if the environment was deleted. Return type:str

get(*args, **kwargs)

Gets environment by the given name.

Parameters:name – name of the environment to fetch. Return type:yagocd.resources.environment.EnvironmentConfig

list(*args, **kwargs)

Lists all available environments.

Return type:list of yagocd.resources.environment.EnvironmentConfig

update(*args, **kwargs)

Update some attributes of an environment.

Parameters:

• name – name of environment to update.
• config – updated environment configuration.
• etag – etag value from current environment resource.

Return type:

yagocd.resources.environment.EnvironmentConfig

yagocd.resources.feed module

class yagocd.resources.feed.FeedManager(session, pipeline_name=None, pipeline_counter=None, stage_name=None, stage_counter=None)

Bases: yagocd.resources.BaseManager, yagocd.util.RequireParamMixin

The feed API allows users to view feed information.

Official documentation.

Versionadded:14.3.0.

PIPELINES_RESOURCE_PATH = '{base_api}/pipelines'

STAGES_RESOURCE_PATH = '{base_api}/stages'

job_by_id(*args, **kwargs)

Gets XML representation of job.

Versionadded:14.3.0. Parameters:job_id – id of job. Note: this is not a counter. Returns:a job object in XML format.

pipeline_by_id(*args, **kwargs)

Gets XML representation of pipeline.

Versionadded:14.3.0. Parameters:pipeline_id – id of pipeline. Note: this is not a counter. Returns:a pipeline object in XML format.

pipelines(*args, **kwargs)

Lists all pipelines.

Versionadded:14.3.0. Returns:an array of pipelines in XML format.

stage(*args, **kwargs)

Gets XML representation of stage.

Versionadded:

14.3.0.

Parameters:

• pipeline_name – name of pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of stage.
• stage_counter – stage counter.

Returns:

a stage object in XML format.

stage_by_id(*args, **kwargs)

Gets XML representation of stage.

Versionadded:14.3.0. Parameters:stage_id – id of stage. Note: this is not a counter. Returns:a stage object in XML format.

stages(*args, **kwargs)

Gets feed of all stages for the specified pipeline with links to the pipeline and stage details.

Versionadded:14.3.0. Parameters:pipeline_name – name of pipeline, for which to list stages Returns:an array of feed of stages in XML format.

yagocd.resources.info module

class yagocd.resources.info.AboutPageTableParser

Bases: HTMLParser.HTMLParser

handle_data(data)

handle_endtag(tag)

handle_starttag(tag, attrs)

class yagocd.resources.info.InfoManager(session)

Bases: yagocd.resources.BaseManager

Class for getting general information about GoCD server. Mostly this class returns some system information about the server and not assumed to be used often.

Versionadded:14.3.0.

Right now this class just parses /about page, for more robust approach you can use yagocd.resources.version.VersionManager class.

ARTIFACT_FREE_SPACE_RE = <_sre.SRE_Pattern object at 0x2692240>

DB_SCHEMA_VERSION_RE = <_sre.SRE_Pattern object>

JVM_VERSION_RE = <_sre.SRE_Pattern object>

OS_INFO_RE = <_sre.SRE_Pattern object>

SERVER_VERSION_RE = <_sre.SRE_Pattern object>

VERSION_NUMBER_RE = <_sre.SRE_Pattern object>

artifact_free_space

db_schema_version

jvm_version

os_info

process_list(*args, **kwargs)

Method for getting processes, executed by server.

support(*args, **kwargs)

Method for getting different server support information.

version

yagocd.resources.job module

class yagocd.resources.job.JobInstance(session, data, stage)

Bases: yagocd.resources.Base

Class representing specific job.

Instances of this class can get different information about the job:

• get pipeline name/counter
• get stage name/counter
• list available artifacts
• list available properties

As this class is a container for multiple entities like artifacts, properties, so it doesn’t have magic methods __iter__ or __getitem__, as they would be ambiguous about their operands. This class gives access to those entities through the python properties, and each entity could implement those magic methods as needed.

artifacts

Property for accessing artifact manager of the current job.

Returns:instance of yagocd.resources.artifact.ArtifactManager Return type:yagocd.resources.artifact.ArtifactManager

pipeline_counter

Get pipeline counter of current job instance.

Because instantiating job instance could be performed in different ways and those return different results, we have to check where from to get counter of the pipeline.

Returns:pipeline counter.

pipeline_name

Get pipeline name of current job instance.

Because instantiating job instance could be performed in different ways and those return different results, we have to check where from to get name of the pipeline.

Returns:pipeline name.

properties

Property for accessing property (doh!) manager of the current job.

Returns:instance of yagocd.resources.property.PropertyManager Return type:yagocd.resources.property.PropertyManager

stage

stage_counter

Get stage counter of current job instance.

Because instantiating job instance could be performed in different ways and those return different results, we have to check where from to get counter of the stage.

Returns:stage counter.

stage_name

Get stage name of current job instance.

Because instantiating job instance could be performed in different ways and those return different results, we have to check where from to get name of the stage.

Returns:stage name.

url

Returns url for accessing job instance.

class yagocd.resources.job.JobManager(session, pipeline_name=None, stage_name=None, job_name=None)

Bases: yagocd.resources.BaseManager, yagocd.util.RequireParamMixin

The jobs API allows users to view job information.

Official documentation.

Versionadded:14.3.0.

RESOURCE_PATH = '{base_api}/jobs'

history(*args, **kwargs)

The job history allows users to list job instances of specified job. Supports pagination using offset which tells the API how many instances to skip.

Versionadded:14.3.0. Returns:an array of jobs instances.

scheduled(*args, **kwargs)

Lists all the current job instances which are scheduled but not yet assigned to any agent.

Versionadded:14.3.0. Returns:an array of scheduled job instances in XML format.

yagocd.resources.material module

class yagocd.resources.material.MaterialEntity(session, data, etag=None)

Bases: yagocd.resources.Base

class yagocd.resources.material.MaterialManager(session)

Bases: yagocd.resources.BaseManager

The materials API allows users to query and notify materials in the Go configuration.

Official documentation.

Versionadded:14.3.0.

list(*args, **kwargs)

Lists all available materials, these are materials that are present in the in cruise-config.xml.

Versionadded:14.3.0. Returns:An array of yagocd.resources.material.MaterialEntity. Return type:list of yagocd.resources.material.MaterialEntity

modifications(*args, **kwargs)

Get modifications of specific material.

Versionadded:

14.3.0.

Parameters:

• fingerprint – fingerprint of material.
• offset – number of modifications to be skipped.

Returns:

A list of modification objects yagocd.resources.material.ModificationEntity.

Return type:

list of yagocd.resources.material.ModificationEntity

notify_git(*args, **kwargs)

APIs that notify Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.

Versionadded:14.3.0. Warning:When using this feature, uncheck Poll for new changes or set autoUpdate flag in cruise configuration to false for the relevant material. Otherwise you will get: requests.exceptions.HTTPError: 404 Client Error: Not Found for url: http://localhost:8153/go/api/material/notify/git Parameters:url – The git repository url as defined in cruise-config.xml. Returns:A text confirmation.

notify_hg(*args, **kwargs)

APIs that notify Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.

Versionadded:14.3.0. Warning:When using this feature, uncheck Poll for new changes or set autoUpdate flag in cruise configuration to false for the relevant material. Otherwise you will get: requests.exceptions.HTTPError: 404 Client Error: Not Found for url: http://localhost:8153/go/api/material/notify/hg Parameters:url – The git repository url as defined in cruise-config.xml. Returns:A text confirmation.

notify_svn(*args, **kwargs)

APIs that notify Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.

Versionadded:14.3.0. Warning:When using this feature, uncheck Poll for new changes or set autoUpdate flag in cruise configuration to false for the relevant material. Otherwise you will get: requests.exceptions.HTTPError: 404 Client Error: Not Found for url: http://localhost:8153/go/api/material/notify/svn Parameters:uuid – The subversion repository UUID. Returns:A text confirmation.

class yagocd.resources.material.ModificationEntity(session, data)

Bases: yagocd.resources.BaseNode

yagocd.resources.pipeline module

class yagocd.resources.pipeline.PipelineEntity(session, data, group=None)

Bases: yagocd.resources.BaseNode

Class for the pipeline entity, which describes pipeline itself. Executing history will return pipeline instances.

config

Property for accessing pipeline configuration.

Return type:yagocd.resources.pipeline_config.PipelineConfigManager

full_history()

Method for accessing full history of specific pipeline.

It yields each instance and after one chunk is over moves to the next one. :return: an array of pipeline instances yagocd.resources.pipeline.PipelineInstance. :rtype: list of yagocd.resources.pipeline.PipelineInstance

get(counter)

Gets pipeline instance object.

Parameters:pipeline counter (counter) – Returns:A pipeline instance object yagocd.resources.pipeline.PipelineInstance. Return type:yagocd.resources.pipeline.PipelineInstance

static get_url(server_url, pipeline_name)

Returns url for accessing pipeline entity.

group

Name of the group pipeline belongs to. :return: group name.

history(offset=0)

The pipeline history allows users to list pipeline instances.

Parameters:offset – number of pipeline instances to be skipped. Returns:an array of pipeline instances yagocd.resources.pipeline.PipelineInstance. Return type:list of yagocd.resources.pipeline.PipelineInstance

last()

Get last pipeline instance.

Return type:yagocd.resources.pipeline.PipelineInstance

pause(cause)

Pause the current pipeline.

Parameters:cause – reason for pausing the pipeline.

release_lock()

Release a lock on a pipeline so that you can start up a new instance without having to wait for the earlier instance to finish.

Returns:a text confirmation.

schedule(materials=None, variables=None, secure_variables=None)

Scheduling allows user to trigger a specific pipeline.

Parameters:

• materials – material revisions to use.
• variables – environment variables to set.
• secure_variables – secure environment variables to set.

Returns:

a text confirmation.

schedule_with_instance(materials=None, variables=None, secure_variables=None, backoff=0.5, max_tries=20)

Schedule pipeline and return instance. Credits of implementation comes to gaqzi: https://github.com/gaqzi/py-gocd/blob/master/gocd/api/pipeline.py#L122

Warning:

Replace this with whatever is the official way as soon as gocd#990 is fixed. https://github.com/gocd/gocd/issues/990

Parameters:

• materials – material revisions to use.
• variables – environment variables to set.
• secure_variables – secure environment variables to set.
• backoff – time to wait before checking for new instance.
• max_tries – maximum tries to do.

Returns:

possible triggered instance of pipeline.

Return type:

yagocd.resources.pipeline.PipelineInstance

status()

The pipeline status allows users to check if the pipeline is paused, locked and schedulable.

Returns:JSON containing information about pipeline state, wrapped in EasyDict class.

unpause()

Unpause the specified pipeline.

url

Returns url for accessing pipeline entity.

value_stream_map(counter)

class yagocd.resources.pipeline.PipelineInstance(session, data)

Bases: yagocd.resources.BaseNode

Pipeline instance represents concrete execution of specific pipeline.

config

Property for accessing pipeline configuration.

Return type:yagocd.resources.pipeline_config.PipelineConfigManager

pipeline_url

Returns url for accessing pipeline entity.

stage(name)

Method for searching specific stage by it’s name.

Parameters:name – name of the stage to search. Returns:found stage or None. Return type:yagocd.resources.stage.StageInstance

stages()

Method for getting stages from pipeline instance.

Returns:arrays of stages Return type:list of yagocd.resources.stage.StageInstance

url

Returns url for accessing pipeline instance.

value_stream_map()

class yagocd.resources.pipeline.PipelineManager(session)

Bases: yagocd.resources.BaseManager

The pipelines API allows users to view pipeline information and operate on it.

Official documentation.

Pipeline groups documentation.

Versionadded:14.3.0.

GROUPS_RESOURCE_PATH = '{base_api}/config/pipeline_groups'

RESOURCE_PATH = '{base_api}/pipelines/{name}'

VSM_RESOURCE_PATH = '{base_api}/pipelines/value_stream_map/{name}'

find(*args, **kwargs)

Finds pipeline by it’s name.

Versionadded:14.3.0. Parameters:name – name of required pipeline. Returns:if found - pipeline yagocd.resources.pipeline.PipelineEntity, otherwise None. Return type:yagocd.resources.pipeline.PipelineEntity

full_history(*args, **kwargs)

Method for accessing full history of specific pipeline.

Versionadded:14.3.0.

It yields each instance and after one chunk is over moves to the next one. :param name: name of the pipeline. :return: an array of pipeline instances yagocd.resources.pipeline.PipelineInstance. :rtype: list of yagocd.resources.pipeline.PipelineInstance

get(*args, **kwargs)

Gets pipeline instance object.

Versionadded:

14.3.0.

Parameters:

• name – name of the pipeline.
• counter – pipeline counter.

Returns:

A pipeline instance object yagocd.resources.pipeline.PipelineInstance.

Return type:

yagocd.resources.pipeline.PipelineInstance

history(*args, **kwargs)

The pipeline history allows users to list pipeline instances. Supports pagination using offset which tells the API how many instances to skip.

Versionadded:

14.3.0.

Parameters:

• name – name of the pipeline.
• offset – number of pipeline instances to be skipped.

Returns:

an array of pipeline instances yagocd.resources.pipeline.PipelineInstance.

Return type:

list of yagocd.resources.pipeline.PipelineInstance

last(*args, **kwargs)

Get last pipeline instance.

Versionadded:14.3.0. Parameters:name – name of the pipeline. Return type:yagocd.resources.pipeline.PipelineInstance

list(*args, **kwargs)

List all available pipelines.

Versionadded:14.3.0.

This method uses pipeline_groups API method call to list available pipelines. It also links them together, so later it’s possible to refer to pipeline’s descendants. :return: array of pipelines :rtype: list of yagocd.resources.pipeline.PipelineEntity

pause(*args, **kwargs)

Pause the specified pipeline.

Versionadded:

14.3.0.

Parameters:

• name – name of the pipeline.
• cause – reason for pausing the pipeline.

release_lock(*args, **kwargs)

Release a lock on a pipeline so that you can start up a new instance without having to wait for the earlier instance to finish.

Versionadded:14.3.0. Parameters:name – name of the pipeline. Returns:a text confirmation.

schedule(*args, **kwargs)

Scheduling allows user to trigger a specific pipeline.

Versionadded:

14.3.0.

Parameters:

• name – name of the pipeline.
• materials – material revisions to use.
• variables – environment variables to set.
• secure_variables – secure environment variables to set.

Returns:

a text confirmation.

schedule_with_instance(*args, **kwargs)

Schedule pipeline and return instance. Credits of implementation comes to gaqzi: https://github.com/gaqzi/py-gocd/blob/master/gocd/api/pipeline.py#L122

Versionadded:

14.3.0.

Warning:

Replace this with whatever is the official way as soon as gocd#990 is fixed. https://github.com/gocd/gocd/issues/990

Parameters:

• name – name of the pipeline.
• materials – material revisions to use.
• variables – environment variables to set.
• secure_variables – secure environment variables to set.
• backoff – time to wait before checking for new instance.
• max_tries – maximum tries to do.

Returns:

possible triggered instance of pipeline.

Return type:

yagocd.resources.pipeline.PipelineInstance

status(*args, **kwargs)

The pipeline status allows users to check if the pipeline is paused, locked and schedulable.

Versionadded:14.3.0. Parameters:name – name of the pipeline. Returns:JSON containing information about pipeline state, wrapped in EasyDict class.

unpause(*args, **kwargs)

Unpause the specified pipeline.

Versionadded:14.3.0. Parameters:name – name of the pipeline.

value_stream_map(*args, **kwargs)

Method builds pipeline instance dependency graph.

Parameters:

• name – name of the pipeline.
• counter – pipeline counter.

yagocd.resources.pipeline_config module

class yagocd.resources.pipeline_config.PipelineConfig(session, data, etag=None)

Bases: yagocd.resources.Base

class yagocd.resources.pipeline_config.PipelineConfigManager(session, pipeline_name=None)

Bases: yagocd.resources.BaseManager, yagocd.util.RequireParamMixin

The pipeline config API allows users with administrator role to manage pipeline config.

Official documentation.

Versionadded:15.3.0.

ACCEPT_HEADER = 'application/vnd.go.cd.v3+json'

RESOURCE_PATH = '{base_api}/admin/pipelines'

VERSION_TO_ACCEPT_HEADER = {'16.12.0': 'application/vnd.go.cd.v2+json', '16.6.0': 'application/vnd.go.cd.v1+json'}

create(*args, **kwargs)

Creates new pipeline.

Versionadded:15.3.0. Parameters:config – configuration data. Returns:created pipeline config object. Return type:yagocd.resources.pipeline_config.PipelineConfig

delete(*args, **kwargs)

Deletes a pipeline.

Versionadded:16.6.0. Parameters:pipeline_name – name of pipeline to delete Returns:A message confirmation if the pipeline was deleted. Return type:str

edit(*args, **kwargs)

Update pipeline config for specified pipeline name.

Versionadded:

15.3.0.

Parameters:

• config – dictionary containing new configuration for a given pipeline.
• etag – etag value from current configuration resource.
• pipeline_name – name of the pipeline. Could be skipped if name was configured from constructor.

Returns:

updated pipeline config object.

Return type:

yagocd.resources.pipeline_config.PipelineConfig

get(*args, **kwargs)

Gets pipeline config for specified pipeline name.

Versionadded:15.3.0. Parameters:pipeline_name – name of the pipeline. Could be skipped if name was configured from constructor. Returns:pipeline config object. Return type:yagocd.resources.pipeline_config.PipelineConfig

yagocd.resources.plugin_info module

class yagocd.resources.plugin_info.PluginInfo(session, data, etag=None)

Bases: yagocd.resources.Base

class yagocd.resources.plugin_info.PluginInfoManager(session)

Bases: yagocd.resources.BaseManager

The plugin info API allows users with administrator role to fetch information about installed plugins.

Official documentation.

Versionadded:16.7.0.

ACCEPT_HEADER = 'application/vnd.go.cd.v2+json'

RESOURCE_PATH = '{base_api}/admin/plugin_info'

VERSION_TO_ACCEPT_HEADER = {'16.11.0': 'application/vnd.go.cd.v1+json'}

get(*args, **kwargs)

Gets plugin info for a specified plugin id.

Parameters:name – id or name of the plugin to get the info. Return type:yagocd.resources.plugin_info.PluginInfo

list(*args, **kwargs)

Lists all available plugin info.

Return type:list of yagocd.resources.plugin_info.PluginInfo

yagocd.resources.property module

class yagocd.resources.property.PropertyManager(session, pipeline_name=None, pipeline_counter=None, stage_name=None, stage_counter=None, job_name=None)

Bases: yagocd.resources.BaseManager, yagocd.util.RequireParamMixin

The properties API allows managing of job properties.

Official documentation.

Versionadded:14.3.0.

This class implements dictionary like methods for similar use.

PATH_PARAMETERS = ['pipeline_name', 'pipeline_counter', 'stage_name', 'stage_counter', 'job_name']

RESOURCE_PATH = '{base_api}/properties/{pipeline_name}/{pipeline_counter}/{stage_name}/{stage_counter}/{job_name}'

create(*args, **kwargs)

Defines a property on a specific job instance.

Versionadded:

14.3.0.

Parameters:

• name – name of property.
• value – value of property.
• pipeline_name – name of the pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of the stage.
• stage_counter – stage counter.
• job_name – name of the job.

Returns:

an acknowledgement that the property was created.

get(*args, **kwargs)

Gets a property value by it’s name. :info: You can use keyword latest as a pipeline counter or a stage counter.

Versionadded:

14.3.0.

Parameters:

• name – name of property to get.
• pipeline_name – name of the pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of the stage.
• stage_counter – stage counter.
• job_name – name of the job.

Returns:

value of requested property.

historical(*args, **kwargs)

Get historical properties. :info: limitPipeline and limitCount are optional parameters. The default value of limitPipeline is latest pipeline instance’s counter. The default value of limitCount is 100.

Versionadded:

14.3.0.

Parameters:

• pipeline_name – name of the pipeline.
• stage_name – name of the stage.
• job_name – name of the job.
• limit_pipeline – pipeline limit for returned properties.
• limit_count – count limit for returned properties.

Returns:

list of dictionaries as historical values.

items(*args, **kwargs)

keys(*args, **kwargs)

list(*args, **kwargs)

Lists all job properties.

Versionadded:

14.3.0.

Parameters:

• pipeline_name – name of the pipeline.
• pipeline_counter – pipeline counter.
• stage_name – name of the stage.
• stage_counter – stage counter.
• job_name – name of the job.

Returns:

dictionary of properties.

Return type:

dict[str, str]

values(*args, **kwargs)

yagocd.resources.scm module

class yagocd.resources.scm.SCMManager(session)

Bases: yagocd.resources.BaseManager

The pluggable SCM API allows users to view, create and update the SCM object.

Official documentation.

Note:Please keep in mind that this API works with pluggable SCM materials, which means that you have to install specific SCM plugin to the GoCD server in order to work with it. Versionadded:16.7.0.

RESOURCE_PATH = '{base_api}/admin/scms'

create(*args, **kwargs)

Create a global SCM object.

Parameters:config – new SCM configuration. Return type:yagocd.resources.scm.SCMMaterial

get(*args, **kwargs)

Gets pluggable scm material for a specified scm name.

Parameters:name – scm material name. Return type:yagocd.resources.scm.SCMMaterial

list(*args, **kwargs)

Lists all available pluggable scm materials, these are materials that are present in the in cruise-config.xml.

Return type:list of yagocd.resources.scm.SCMMaterial

update(*args, **kwargs)

Update some attributes of SCM material.

Parameters:

• name – name of SCM material to update.
• config – updated SCM material configuration.
• etag – etag value from current SCM material.

Return type:

yagocd.resources.scm.SCMMaterial

class yagocd.resources.scm.SCMMaterial(session, data, etag=None)

Bases: yagocd.resources.Base

yagocd.resources.stage module

class yagocd.resources.stage.StageInstance(session, data, pipeline)

Bases: yagocd.resources.Base

Class representing instance of specific stage.

cancel()

Cancel an active stage of a specified stage.

Returns:a text confirmation.

job(name)

Method for searching specific job by it’s name.

Parameters:name – name of the job to search. Returns:found job or None. Return type:yagocd.resources.job.JobInstance

jobs()

Method for getting jobs from stage instance.

Returns:arrays of jobs. Return type:list of yagocd.resources.job.JobInstance

pipeline

pipeline_counter

Get pipeline counter of current stage instance.

Because instantiating stage instance could be performed in different ways and those return different results, we have to check where from to get counter of the pipeline.

Returns:pipeline counter.

pipeline_name

Get pipeline name of current stage instance.

Because instantiating stage instance could be performed in different ways and those return different results, we have to check where from to get name of the pipeline.

Returns:pipeline name.

stage_counter

Get stage counter of current instance.

This method is to be inline with others.

Returns:stage counter.

stage_name

Get stage name of current instance.

This method is to be inline with others.

Returns:stage name.

url

Returns url for accessing stage instance.

class yagocd.resources.stage.StageManager(session, pipeline_name=None, pipeline_counter=None, stage_name=None, stage_counter=None)

Bases: yagocd.resources.BaseManager, yagocd.util.RequireParamMixin

The stages API allows users to view stage information and operate on it.

Official documentation.

Versionadded:14.3.0.

RESOURCE_PATH = '{base_api}/stages/{pipeline_name}/{stage_name}'

RUN_RESOURCE_PATH = '{base_api}/run/{pipeline_name}/{pipeline_counter}/{stage_name}'

cancel(*args, **kwargs)

Cancel an active stage of a specified stage.

Versionadded:

14.3.0.

Parameters:

• pipeline_name – pipeline name.
• stage_name – stage name.

Returns:

a text confirmation.

full_history(*args, **kwargs)

The stage history allows users to list stage instances of specified stage.

This method uses generator to get full stage history. :param pipeline_name: pipeline name. :param stage_name: stage name. :return: an array of stage instances yagocd.resources.stage.StageInstance. :rtype: list of yagocd.resources.stage.StageInstance

get(*args, **kwargs)

Gets stage instance object.

Versionadded:

15.1.0.

Parameters:

• pipeline_name – pipeline name.
• stage_name – stage name.
• pipeline_counter – pipeline counter.
• stage_counter – stage counter.

Returns:

a stage instance object yagocd.resources.stage.StageInstance.

Return type:

yagocd.resources.stage.StageInstance

history(*args, **kwargs)

The stage history allows users to list stage instances of specified stage. Supports pagination using offset which tells the API how many instances to skip.

Versionadded:

14.3.0.

Parameters:

• pipeline_name – pipeline name.
• stage_name – stage name.
• offset – how many instances to skip.

Returns:

an array of stage instances yagocd.resources.stage.StageInstance.

Return type:

list of yagocd.resources.stage.StageInstance

last(*args, **kwargs)

Get last stage instance.

Parameters:

• pipeline_name – name of the pipeline.
• stage_name – name of the stage.

Return type:

yagocd.resources.pipeline.PipelineInstance

run(*args, **kwargs)

Run stage, configured for manual trigger.

Versionadded:

14.3.0.

Parameters:

• pipeline_name – pipeline name.
• stage_name – stage name.
• pipeline_counter – pipeline counter.

Returns:

Nothing.

class yagocd.resources.stage.StageResult

Bases: object

Enumeration of the Stage results.

These values are used to represent real status of a Stage. Looks like they’re calculated as aggregated value of each Job’s status.

Url:https://github.com/gocd/gocd/blob/master/domain/src/com/thoughtworks/go/domain/StageResult.java

Cancelled = 'Cancelled'

Failed = 'Failed'

Passed = 'Passed'

Unknown = 'Unknown'

class yagocd.resources.stage.StageState

Bases: object

Enumeration of the Stage statuses.

These statuses are used to determine general status of a given Stage from the status of it’s Jobs. The values from this enum are used in Jobs state parameter.

Url:https://github.com/gocd/gocd/blob/master/domain/src/com/thoughtworks/go/domain/StageState.java

Building = 'Building'

Cancelled = 'Cancelled'

Failed = 'Failed'

Failing = 'Failing'

Passed = 'Passed'

StateToResult = {'Building': 'Unknown', 'Unknown': 'Unknown', 'Failing': 'Failed', 'Failed': 'Failed', 'Passed': 'Passed', 'Cancelled': 'Cancelled'}

Unknown = 'Unknown'

yagocd.resources.template module

class yagocd.resources.template.TemplateConfig(session, data, etag=None)

Bases: yagocd.resources.Base

class yagocd.resources.template.TemplateManager(session)

Bases: yagocd.resources.BaseManager

The template config API allows users with administrator role to manage template config.

Official documentation.

Versionadded:16.10.0.

ACCEPT_HEADER = 'application/vnd.go.cd.v3+json'

RESOURCE_PATH = '{base_api}/admin/templates'

VERSION_TO_ACCEPT_HEADER = {'16.10.0': 'application/vnd.go.cd.v1+json', '16.11.0': 'application/vnd.go.cd.v2+json'}

create(*args, **kwargs)

Creates a template config object.

Parameters:config – new template configuration. Return type:yagocd.resources.template.TemplateConfig

delete(*args, **kwargs)

Deletes a template from the config XML if it is not associated with any pipeline.

Parameters:name – name of template to delete Returns:A message confirmation if the template was deleted. Return type:str

get(*args, **kwargs)

Gets template config for specified template name.

Parameters:name – name of the template. Return type:yagocd.resources.template.TemplateConfig

list(*args, **kwargs)

Lists all available templates with the associated pipelines’ names.

Return type:list of yagocd.resources.template.TemplateConfig

update(*args, **kwargs)

Update template config for specified template name.

Parameters:

• name – name of the template to update.
• config – updated template configuration.
• etag – etag value from current template object.

Return type:

yagocd.resources.template.TemplateConfig

yagocd.resources.user module

class yagocd.resources.user.UserEntity(session, data, etag=None)

Bases: yagocd.resources.Base

The user object.

class yagocd.resources.user.UserManager(session)

Bases: yagocd.resources.BaseManager

The users API allows users with administrator role to manage users.

Official documentation.

Versionadded:15.2.0.

CURRENT_USER_PATH = '{base_api}/current_user'

RESOURCE_PATH = '{base_api}/users'

create(*args, **kwargs)

Creates a user.

Versionadded:15.3.0.

TODO: can’t make this one work: returns 404 all the time.

Parameters:options – dictionary of parameters for creating a user. Returns:a user object yagocd.resources.user.UserEntity. Return type:yagocd.resources.user.UserEntity

current(*args, **kwargs)

Gets the current user.

Versionadded:17.5.0. Returns:a current user object yagocd.resources.user.UserEntity. Return type:yagocd.resources.user.UserEntity

delete(*args, **kwargs)

Deletes a user.

Versionadded:15.2.0. Parameters:login – login name. Returns:a message confirmation if the user was deleted.

get(*args, **kwargs)

Gets a user by its login name.

Versionadded:15.2.0. Parameters:login – login name. Returns:a user object yagocd.resources.user.UserEntity. Return type:yagocd.resources.user.UserEntity

list(*args, **kwargs)

Lists all available users.

Versionadded:15.2.0. Returns:an array of user objects yagocd.resources.user.UserEntity. Return type:list of yagocd.resources.user.UserEntity

update(*args, **kwargs)

Update some attributes of a user.

Versionadded:

15.2.0.

Parameters:

• login – login name.
• options – dictionary of parameters for updating a user.

Returns:

the updated user object yagocd.resources.user.UserEntity.

Return type:

yagocd.resources.user.UserEntity

update_current(*args, **kwargs)

Update some attributes of the current user.

Versionadded:17.5.0. Parameters:options – Returns:

yagocd.resources.version module

class yagocd.resources.version.VersionManager(session)

Bases: yagocd.resources.BaseManager

The Version API allows users to get the GoCD server version details.

Official documentation.

Versionadded:16.6.0.

get(*args, **kwargs)

Module contents

class yagocd.resources.Base(session, data, etag=None)

Bases: object

data

etag

class yagocd.resources.BaseManager(session)

Bases: object

ACCEPT_HEADER = 'application/vnd.go.cd.v1+json'

VERSION_TO_ACCEPT_HEADER = None

class yagocd.resources.BaseNode(session, data)

Bases: yagocd.resources.Base

descendants

Property for getting descendants (children) of current pipeline. It’s calculated by yagocd.resources.pipeline.PipelineManager#tie_descendants() method during listing of all pipelines.

Returns:list of yagocd.resources.pipeline.PipelineEntity. Return type:list of yagocd.resources.pipeline.PipelineEntity

get_descendants(transitive=False)

Property for getting descendants (children) of current pipeline. It’s calculated by yagocd.resources.pipeline.PipelineManager#tie_descendants() method during listing of all pipelines.

Returns:list of yagocd.resources.pipeline.PipelineEntity. Return type:list of yagocd.resources.pipeline.PipelineEntity

get_predecessors(transitive=False)

Property for getting predecessors (parents) of current pipeline. This property automatically populates from API call

Returns:list of yagocd.resources.pipeline.PipelineEntity. Return type:list of yagocd.resources.pipeline.PipelineEntity

predecessors

Property for getting predecessors (parents) of current pipeline. This property automatically populates from API call

Returns:list of yagocd.resources.pipeline.PipelineEntity. Return type:list of yagocd.resources.pipeline.PipelineEntity

set_descendants(value)

set_predecessors(value)