The TeamscaleClient

class TeamscaleClient(url: str, username: str, access_token: str, project: str, sslverify: bool = True, timeout: float = 30.0, branch: str | None = None)

Basic Python service client to access Teamscale’s REST Api.

Request handling done with: https://docs.python-requests.org/en/latest/

Parameters:

• url – The url to Teamscale (including the port)

• username – The username to use for authentication

• access_token – The IDE access token to use for authentication

• project – The id of the project on which to work

• sslverify – See requests’ verify parameter in https://docs.python-requests.org/en/latest/user/advanced/#ssl-cert-verification

• timeout – TTFB timeout in seconds, see https://docs.python-requests.org/en/master/user/quickstart/#timeouts

• branch – The branch name for which to upload/retrieve data

TEAMSCALE_API_VERSION = 'v8.0.0'

The Teamscale API Version for which the current implementation is designed

add_baseline(baseline: Baseline) → Response

Adds a baseline to the currently active project. Re-adding an existing baseline will update the original baseline.

Parameters:

baseline – The baseline that is to be added (or updated)

Returns:

object generated by the upload request

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

add_finding_descriptions(descriptions: List[FindingDescription]) → Response

Adds descriptions of findings.

Parameters:

descriptions – List of FindingDescription to add to Teamscale.

Returns:

request’s response

Return type:

requests.Response

add_findings_group(name: str, mapping_pattern: str) → Response

Adds group of findings.

Parameters:

• name – Name of group.

• mapping_pattern – Regular expression to match a finding’s typeid in order to belong to this group.

Returns:

request’s response

Return type:

requests.Response

add_issue_metric(name: str, issue_query: str) → Response

Adds group of findings.

Parameters:

• name – Name of issue metric

• issue_query – The issue query to add

Returns:

request’s response

Return type:

requests.Response

add_metric_descriptions(metric_descriptions: List[MetricDescription]) → Response

Uploads metric definitions to Teamscale.

Parameters:

metric_descriptions – List of metric descriptions to add to Teamscale.

Returns:

object generated by the request

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

add_task_comment(task_id: str, comment: str) → Response

Adds a comment to a task.

Parameters:

• task_id – the task id to which to add the comment

• comment – the comment to add

Returns:

object generated by the request

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

Warning

Uses Teamscale’s internal API and not the versioned API!

check_api_version() → None

Verifies the server’s api version and connectivity.

Raises:

ServiceError – If the version does not match or the server cannot be found.

create_dashboard(dashboard_descriptor: str) → Response

Adds a new dashboard from the given template.

Parameters:

dashboard_descriptor (str) – The dashboard descriptor that should be uploaded

Returns:

request’s response

Return type:

requests.Response

create_project(project_configuration: ProjectConfiguration, skip_project_validation: bool = False) → Response

Creates a project with the specified configuration in Teamscale. The parameter skip_project_validation specifies, whether to skip the validation of the project.

Parameters:

• project_configuration – The configuration for the project to be created.

• skip_project_validation – Whether to skip validation of the project.

Returns:

object generated by the upload request.

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong.

delete(url: str, **kwargs) → Response

Sends a DELETE request to the given service url.

Parameters:

• url – The URL for which to execute a DELETE request

• **kwargs – passed to requests library (examples see below)

Keyword Arguments:

params – parameters to attach to the url

Returns:

request’s response

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

delete_baseline(baseline_name: str) → Response

Deletes a baseline from the currently active project.

Parameters:

baseline_name – The baseline that is to be removed.

Returns:

object generated by the upload request

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

static from_client_config(config: TeamscaleClientConfig, sslverify: bool = True, timeout: float = 30.0, branch: str | None = None) → TeamscaleClient

Creates a new Teamscale client from a TeamscaleClientConfig object.

Parameters:

• config – The client configuration to use.

• sslverify – See requests’ verify parameter in https://docs.python-requests.org/en/latest/user/advanced/#ssl-cert-verification

• timeout – TTFB timeout in seconds, see https://docs.python-requests.org/en/master/user/quickstart/#timeouts

• branch – The branch name for which to upload/retrieve data

get(url: str, **kwargs) → Response

Sends a GET request to the given service url.

Parameters:

• url – The URL for which to execute a GET request

• **kwargs – passed to requests library (examples see below)

Keyword Arguments:

params – parameters to attach to the url

Returns:

request’s response

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

get_architectures() → List[str]

Returns the paths of all architecture in the project.

Returns:

The architecture names.

get_baselines() → List[Baseline]

Retrieves a list of baselines from the server for the currently active project.

Returns:

The list of baselines.

Return type:

List[data.Baseline])

Raises:

ServiceError – If anything goes wrong

get_commit_for_revision(revision_id: str) → str

Retrieves the Teamscale commit corresponding to a revision, raising an error if the commit is not known to Teamscale.

Parameters:

revision_id – The revision ID (e.g., commit SHA)

Returns:

The teamscale commit

Return type:

str

get_finding_by_id(finding_id, branch=None, timestamp=None)

Retrieves the finding with the given id.

Parameters:

• finding_id (str) – The id of the finding to retrieve.

• branch (str) – The branch from which the finding should be retrieved.

• timestamp (datetime.datetime) – The timestamp (unix format) for which to receive the finding.

Returns:

The retrieved finding.

Return type:

Finding

Raises:

ServiceError – If anything goes wrong

get_findings(uniform_path: str, timestamp: datetime, revision_id: str | None = None, filter: FileFindings | None = None, invert: bool = False, assessment_filters: List[Assessment] | None = None) → List[Finding]

Retrieves the list of findings in the currently active project for the given uniform path at the provided timestamp on the given branch.

Parameters:

• uniform_path – The uniform path to get findings for.

• timestamp – timestamp (unix format) for which to upload the data

• revision_id – If provided, the client will first resolve the ID (e.g., commit hash) to a Teamscale commit and retrieve the findings for the corresponding branch.

• filter – The finding category, group, and type filters. Every string must be either a single category, a combination category/group, or a type ID. If a category or group is given, all matching findings will be filtered out and not included in the result.

• invert – Whether to invert the category, group, type filters, i.e. including the elements given in the filters instead of excluding them.

• assessment_filters – The assessment filter. All mentioned assessment colors will be filtered out and not included in the result.

Returns:

The list of findings.

Return type:

List[data.Finding])

Raises:

ServiceError – If anything goes wrong

get_precommit_analysis_results() → Tuple[List[Finding], ...]

Gets precommit analysis results.

Returns:

added findings, findings in changed code, and removed findings.

Return type:

A tuple consisting of three lists

get_project_configuration(project_id: str) → Dict

Returns the configuration for a given project.

Parameters:

project_id – The id for which the project configuration should be retrieved

Returns:

The project configuration as json dictionary

Return type:

dict

get_projects() → List[ProjectInfo]

Retrieves a list of projects from the server.

Returns:

The list of projects.

Return type:

List[data.ProjectInfo])

Raises:

ServiceError – If anything goes wrong

get_tasks(status: TaskStatus = TaskStatus.OPEN, details: bool = True, start: int = 0, max: int = 300) → List[Task]

Retrieves the tasks for the client’s project from the server.

Parameters:

• status – The status to retrieve tickets for

• details – Whether to retrieve details together with the tasks

• start – From which task number to start listing tasks

• max – Maximum number of tasks to return

Returns:

The list of tasks.

Return type:

List[data.Task])

Raises:

ServiceError – If anything goes wrong

Warning

Uses Teamscale’s internal API and not the versioned API!

post(url: str, **kwargs) → Response

Sends a POST request to the given service url with the json payload as content.

Parameters:

• url – The URL for which to execute a POST request

• **kwargs – passed to requests library (examples see below)

Keyword Arguments:

• json – The Object to attach as content, will be serialized to json (only for object that can be serialized by default)

• params – parameters to attach to the url

• data – The data object to be attached to the request

Returns:

request’s response

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

put(url: str, **kwargs) → Response

Sends a PUT request to the given service url with the json payload as content.

Parameters:

• url – The URL for which to execute a PUT request

• **kwargs – passed to requests library (examples see below)

Keyword Arguments:

• json – The Object to attach as content, will be serialized to json (only for object that can be serialized by default)

• params – parameters to attach to the url

• data – The data object to be attached to the request

Returns:

request’s response

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

classmethod read_json_from_file(file_path: str) → Any

Reads JSON content from a file and parses it to ensure basic integrity.

Parameters:

file_path – File from which to read the JSON content.

Returns:

The parsed JSON data.

set_project(project: str) → None

Sets the project id for subsequent calls made using the client.

update_findings_schema()

Triggers refresh of finding groups in analysis profiles.

Warning

Uses Teamscale’s internal API and not the versioned API!

update_project(project_configuration: ProjectConfiguration, skip_project_validation: bool = False) → Response

Updates an existing project in Teamscale with the given configuration. This may trigger a reanalysis of the

project if the changes require it. The id of the existing project is taken from the configuration. The parameter skip_project_validation specifies, whether to skip the validation of the project.

Parameters:

• project_configuration – The configuration for the project to be updated.

• skip_project_validation – Whether to skip validation of the project.

Returns:

object generated by the upload request.

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong.

upload_architectures(architectures: Dict, message: str, architecture_format: ArchitectureFormats = ArchitectureFormats.FILE_LIST, **kwargs) → Response

Upload architectures to Teamscale. It is expected that the given architectures can be read from the filesystem.

Parameters:

• architectures – mapping of teamscale paths to architecture files that should be uploaded. Files must be readable.

• message – The message to use for the generated upload commit

• architecture_format – the architecture file format

• **kwargs – one of timestamp (datetime.datetime) or revision (str), optionally repository (str) if revision is passed, template for architecture (str)

Returns:

object generated by the request

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

upload_coverage_data(coverage_files: List[str], coverage_format: CoverageFormats, message: str, partition: str, **kwargs) → Response

Upload coverage reports to Teamscale. It is expected that the given coverage report files can be read from the filesystem.

Parameters:

• coverage_files – list of coverage filenames (strings!) that should be uploaded. Files must be readable.

• coverage_format – the format to use

• message – The message to use for the generated upload commit

• partition – The partition’s name into which the data should be added (See also: FAQ - Partitions).

• **kwargs – timestamp (datetime.datetime) or revision (str), optionally repository (str) if revision is passed

Returns:

object generated by the request

Return type:

requests.Response

Notes

This is basically a wrapper method for upload_report(..)

Raises:

ServiceError – If anything goes wrong

upload_files_for_precommit_analysis(timestamp: datetime, precommit_data: Dict) → Response

Uploads the provided files for precommit analysis.

Parameters:

• timestamp – The timestamp of the parent commit.

• precommit_data – The content and paths of added, modified and removed files. The dictionary should contain a key “deletedUniformPaths” mapping to str and “uniformPathToContentMap” mapping to an object

upload_findings(findings: List[FileFindings], message: str, partition: str, **kwargs) → Response

Uploads a list of findings

Parameters:

• findings – the findings data

• message – The message to use for the generated upload commit

• partition – The partition’s names into which the findings should be added (See also: FAQ - Partitions).

• **kwargs – timestamp (datetime.datetime) or revision (str), optionally repository (str) if revision is passed

Returns:

object generated by the request

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

upload_metrics(metrics: List[MetricEntry], message: str, partition: str, **kwargs) → Response

Uploads a list of metrics

Parameters:

• metrics – metrics data

• message – The message to use for the generated upload commit

• partition – The partition’s name into which the metrics should be added (See also: FAQ - Partitions).

• **kwargs – timestamp (datetime.datetime) or revision (str), optionally repository (str) if revision is passed

Returns:

object generated by the upload request

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

upload_non_code_metrics(metrics: List[NonCodeMetricEntry], message: str, partition: str, **kwargs) → Response

Uploads a list of non-code metrics

Parameters:

• metrics – metrics data

• message – The message to use for the generated upload commit

• partition – The partition’s name into which the metrics should be added (See also: FAQ - Partitions).

• **kwargs – timestamp (datetime.datetime) or revision (str), optionally repository (str) if revision is passed

Returns:

object generated by the upload request

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

upload_report(report_files: List[str], report_format: ReportFormats | CoverageFormats | UnitTestReportFormats, message: str, partition: str, **kwargs) → Response

Upload reports from external tools to Teamscale. It is expected that the given report files can be read from

the filesystem.

Parameters:

• report_files – list of filenames (strings!) that should be uploaded. Files must be readable.

• report_format – the format to use

• message – The message to use for the generated upload commit

• partition – The partition’s name into which the data should be added (See also: FAQ - Partitions).

• **kwargs – see below, one of the following is required: timestamp or revision

Keyword Arguments:

• timestamp (datetime.datetime) – timestamp (unix format) for which to upload the data

• revision (str) – a revision, can be given instead of a timestamp

• repository (str) – When using the revision parameter, this parameter allows to pass a repository name which is used to identify the correct commit in situations where the same revision exists in multiple repositories.

• movetolastcommit (bool) – True to automatically adjust this commit to be the latest otherwise False. Default is True

Returns:

object generated by the request

Return type:

requests.Response

Raises:

ServiceError – If anything goes wrong

class TeamscaleClientConfig(url, username, access_token, project='')

Configuration parameters for connections to Teamscale

In order to configure a Teamscale client, the config file must at least provide the following entries: * url: The url of the Teamscale server. * username: The username to use to perform API calls * access_token: The access token to use.

The config file can also specify a project id. If no project id is specified, ‘’ is used in case project_required is False. A TeamscaleClient created using a configuration without project id will only perform global calls.

static from_config_file(config_file)

Reads a Teamscale client configuration from the specified file.

Parameters:

config_file (str) – Path of the client configuration to use.

static from_config_file_in_home_dir()

Reads a Teamscale client configuration from the user home dir. The configuration file must be named as in TEAMSCALE_CLIENT_CONFIG_FILENAME.

is_sufficient(require_project_id=False)

overwrite_with(other)

Overwrites values in this configuration with values from the other configuration. This is useful to combine multiple configurations from different files, e.g. the home dir and the repository root.