The TeamscaleClient

The TeamscaleClient#

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

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

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

Parameters:
TEAMSCALE_API_VERSION = 'v8.0.0'#

The Teamscale API Version for which the current implementation is designed

add_baseline(baseline: Baseline) Response[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

Creates a new Teamscale client from a TeamscaleClientConfig object.

Parameters:
get(url: str, **kwargs) Response[source]#

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][source]#

Returns the paths of all architecture in the project.

Returns:

The architecture names.

get_baselines() List[Baseline][source]#

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[source]#

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)[source]#

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][source]#

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], ...][source]#

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[source]#

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][source]#

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][source]#

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[source]#

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[source]#

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[source]#

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[source]#

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

update_findings_schema()[source]#

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[source]#
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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#
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='')[source]#

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)[source]#

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()[source]#

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)[source]#
overwrite_with(other)[source]#

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.