Parsing¶

Concourse Tools contains a number of simple functions for mapping between Python and the Concourse resource type paradigm.

JSON Parsing¶

The following functions are responsible for parsing Concourse JSON payloads and returning Python objects.

concoursetools.parsing.parse_check_payload(raw_json)[source]¶

Parse raw input JSON for a check payload.

Parameters:: raw_json (str) – A JSON string of the following form:

{
    "source": {
        "uri": "git://some-uri",
        "branch": "develop",
        "private_key": "..."
    },
    "version": { "ref": "61cbef" }
}

Return type:: tuple[dict[str, Any], dict[str, str] | None]
Returns:: The source and version configuration (if it exists).

Note

If the version has not been passed, then None will be returned, and not an empty dict.

concoursetools.parsing.parse_in_payload(raw_json)[source]¶

Parse raw input JSON for an in payload.

Parameters:: raw_json (str) – A JSON string of the following form:

{
    "source": {
        "uri": "git://some-uri",
        "branch": "develop",
        "private_key": "..."
    },
    "version": { "ref": "61cbef" },
    "params": { "skip_download": true }
}

Return type:: tuple[dict[str, Any], dict[str, str], dict[str, Any]]
Returns:: The source and version configuration, and parameters passed to the get step.

concoursetools.parsing.parse_out_payload(raw_json)[source]¶

Parse raw input JSON for an out payload.

Parameters:: raw_json (str) – A JSON string of the following form:

{
    "params": {
        "branch": "develop",
        "repo": "some-repo"
    },
    "source": {
        "uri": "git@...",
        "private_key": "..."
    }
}

Return type:: tuple[dict[str, Any], dict[str, Any]]
Returns:: The source configuration, and parameters passed to the put step.

concoursetools.parsing.parse_metadata(metadata_pairs)[source]¶

Convert key-value pairs toa key-value mapping.

Parameters:: metadata_pairs (list[MetadataPair]) – A list of key-value pairs for processing in Concourse.
Return type:: dict[str, str]
Returns:: A key-value mapping representing metadata.

JSON Formatting¶

The following functions are responsible for formatting Concourse JSON payloads from Python objects.

concoursetools.parsing.format_check_output(version_configs, **json_kwargs)[source]¶

Format check output as a JSON string.

Parameters:

version_configs (list[dict[str, str]]) – A list of version configurations.
json_kwargs (Any) – Additional keyword arguments to pass to json.dumps().

Return type:

str

Returns:

A formatted JSON string to pass to Concourse, in the following form:

[
    { "ref": "61cbef" },
    { "ref": "d74e01" },
    { "ref": "7154fe" }
]

concoursetools.parsing.format_in_out_output(version_config, metadata, **json_kwargs)[source]¶

Format in output or out output as a JSON string.

Parameters:

version_config (dict[str, str]) – A version configuration.
metadata (dict[str, str]) – A key-value mapping of metadata.
json_kwargs (Any) – Additional keyword arguments to pass to json.dumps().

Return type:

str

Returns:

A formatted JSON string to pass to Concourse, in the following form:

{
    "version": { "ref": "61cbef" },
    "metadata": [
        { "name": "commit", "value": "61cbef" },
        { "name": "author", "value": "Hulk Hogan" }
    ]
}

concoursetools.parsing.format_metadata(metadata)[source]¶

Convert a key-value mapping to key-value pairs.

Parameters:: metadata (dict[str, str]) – A key-value mapping representing metadata. Keys and values should both be strings.
Return type:: list[MetadataPair]
Returns:: A list of key-value pairs for processing in Concourse.