7.2.2.1. Module axivion.dashboard¶

A thin wrapper around the Dashboard HTTP JSON API.

This wrapper might not be as powerful as directly using the API, but it certainly should be easier to use.

You can use this API in multiple ways:

Use it against an existing Dashboard that is already up and running by directly calling :py:class:`axivion.dashboard.Dashboard`
Create and start your own Dashboard instance first using the module :py:mod:`axivion.dashboard.setup_helper`
Or use a completely transparent Dashboard, see :py:func:`axivion.dashboard.create_project_from_dbfile`.

Note

All functionality in this module requires a Dashboard version of at least 6.5.0 if not specified otherwise. It is recommended to use matching versions of the Dashboard and this API implementation, however the API implementation should also be backwards compatible, i.e. a newer API implementation usually will work with an older Dashboard.

Classes¶

`ApiToken`	Wraps a Dashboard API authentication token string as a credential to authenticate with the Dashboard.
`CustomNamedFilter`(dashboard, user_name, key)	Encapsulates methods related to a custom Named Filter
`Dashboard`(dashboard_url[, auth, verify, ...])	Encapsulates logic to talk to a Dashboard server.
`DbToken`	Wraps a database uid string as a credential to authenticate with the Dashboard.
`GlobalNamedFilter`(dashboard, key)	Encapsulates methods related to a global Named Filter
`NamedFilterVisibility`(*[, groups])	Represents possible visibility restrictions of a global named filter
`Project`(dashboard, name)	Encapsulates an analysis project.
`User`(dashboard, user_name)	Encapsulates a Dashboard user.

ApiToken¶

class axivion.dashboard.ApiToken¶

Bases: str

Wraps a Dashboard API authentication token string as a credential to authenticate with the Dashboard.

It depends entirely on the token itself what access permissions are associated with it. Usually the permissions are very limited so don’t expect the python functions of this module to work as they would when authenticating with username and password.

Parameters:: token (str) – the token

CustomNamedFilter¶

class axivion.dashboard.CustomNamedFilter(dashboard, user_name, key)¶

Bases: object

Encapsulates methods related to a custom Named Filter

Note

Requires a Dashboard version >= 7.3.0

Parameters:

dashboard (axivion.dashboard.Dashboard)
user_name (str)
key (str)

get()¶

Get the bare named-filter data.

Wraps GET /api/users/{user}/named_filters/{id}.

Note

Requires a Dashboard version >= 7.3.0

Return type:: typing.Mapping[str, typing.Any]
Returns:: a dict of the form NamedFilterInfo

update(*, name=None, filters=None, sorters=None)¶

Update an existing named filter.

If one of the keyword arguments is not given, that part of the named filter will be left untouched.

Wraps PATCH /api/users/{user}/named_filters/{id}.

Note

Requires a Dashboard version >= 7.3.0

Keyword Arguments:

name – if given, the named filter will be renamed also resulting in a changed key and url
filters – a dict of str->str where the key is the column key and the value the filter string
sorters – a list of 2-tuples (key,direction) where key is the column key and direction either ‘ASC’ or ‘DESC’.

Parameters:

name (typing.Optional[str])
filters (typing.Optional[typing.Mapping[str, str]])
sorters (typing.Optional[typing.List[typing.Union[typing.Tuple[str, str], typing.Mapping[str, str]]]])

Return type:

None

delete()¶

Deletes an existing named filter.

Wraps DELETE /api/users/{user}/named_filters/{id}. :rtype: None

Note

Requires a Dashboard version >= 7.3.0

Dashboard¶

class axivion.dashboard.Dashboard(dashboard_url, auth=None, verify=True, timeout=300, *, logger=None)¶

Bases: object

Encapsulates logic to talk to a Dashboard server.

It is good practice to use this like a resource object, so the underlying session is closed and pooled connections get freed properly, e.g.:

with Dashboard('http://localhost:9090/axivion/', auth=('username','password')) as dashboard:
    for project in dashboard.projects():
      ...

alternatively you may simply call close() when done using this object.

Parameters:

dashboard_url (str) – The HTTP root URL of your Dashboard, e.g. http://example.com:9090/axivion/
auth (typing.Union[axivion.dashboard.ApiToken, typing.Tuple[str, str], axivion.dashboard.DbToken, None]) – credentials used to authenticate the requests
verify (typing.Union[axivion.dashboard.certificate_verification.CertificateVerification, bool]) – when connecting via HTTPS specifies, level of the verification of the server certificate; true == LAX, false == NO
timeout (int) – timeout in seconds for HTTP communication requests to the Dashboard
logger (typing.Optional[logging.Logger])

property version: Tuple[int, ...]¶

get_dashboard_url()¶

The absolute base URL used by this object and all its HTTP requests.

Returns:

the url that was used when creating this: :py:class:`axivion.dashboard.Dashboard` instance

Return type:

str

get_main_url()¶

The absolute base URL for creating dashboard self-references.

If configured, returns the Dashboard’s self-reference URL, otherwise a guessed URL.

Note

Since 7.4.0 If the underlying Dashboard is older than 7.4.0 this will fall back to using get_dashboard_url()

Returns:: base URL for browser links
Return type:: str

get_api_url()¶

The host-relative primary API endpoint URL.

Note

Since 7.4.0

Returns:: the primary dashboard API endpoint
Return type:: str

set_password(current_password, new_password)¶

Sets/Changes the password for the authenticating user.

If username-password-auth was used and the password was successfully changed on the server, the password supplied on construction will be updated to the new one, so no new Dashboard instance needs to be created.

Wraps POST /api/user_profile/set_password.

Note

Requires a Dashboard version >= 6.9.7

Parameters:

current_password (str) – the current password
new_password (str) – the new password

Return type:

None

get_current_api_token()¶

Gets the API token the request is authenticated with.

Wraps GET /api/user_profile/current_token :rtype: typing.Mapping[str, typing.Any]

Note

Requires a Dashboard version >= 7.1.0

delete_current_api_token()¶

Deletes the API token the request is authenticated with.

Wraps DELETE /api/user_profile/current_token :rtype: None

Note

Requires a Dashboard version >= 7.1.0

create_api_token(username, password, token_type, description, *, max_age=datetime.timedelta(0))¶

Creates an ApiToken for the given user.

Wraps POST /api/users/{user}/tokens.

Note

Requires a Dashboard version >= 7.1.0

Parameters:

username (str) – the user to create the token for
password (str) – the password of the user that is requesting the token creation
token_type (str) – type of the token, see ApiTokenType
description (str) – describe the purpose of the token (important for later identification)
max_age (datetime.timedelta)

Keyword Arguments:

max_age – how long the token should be valid. Use empty timedelta to let the implementation choose a default.

Return type:

typing.Mapping[str, typing.Any]

Returns:

python dict of the form ApiTokenInfo

get_api_tokens(username)¶

Get existing ApiTokens of the given user.

Wraps GET /api/users/{user}/tokens.

Parameters:: username (str) – the user whose tokens to get

Note

Requires a Dashboard version >= 7.1.0

Return type:: typing.List[typing.Mapping[str, typing.Any]]
Returns:: python list with elements of the form ApiTokenInfo

get_api_token(token_id)¶

Get information about a token.

Wraps GET /api/tokens/{id}.

Note

Requires a Dashboard version >= 7.1.0

Return type:: typing.Mapping[str, typing.Any]
Returns:: python dict of the form ApiTokenInfo
Parameters:: token_id (str)

delete_api_token(token_id)¶

Deletes an ApiToken of the authenticated user.

Wraps DELETE /api/tokens/{id}

Note

Requires a Dashboard version >= 7.1.0

Parameters:: token_id (str) – the token id
Return type:: None

delete_api_tokens(token_ids)¶

Bulk-deletes multiple ApiTokens.

Wraps DELETE /api/tokens

Tokens that do not exist or that the caller is not allowed to delete are silently skipped.

Note

Requires a Dashboard version >= 7.12.0

Parameters:: token_ids (typing.Sequence[str]) – the ids of the tokens to delete
Return type:: None

global_named_filters(*, kind=None)¶

Gets the global named filters.

Wraps GET /api/named_filters.

Note

Requires a Dashboard version >= 7.3.0

Keyword Arguments:: kind – one of ‘AV’, ‘CL’, ‘DE’, ‘CY’, ‘MV’, ‘SV’ to get only named filters compatible with the given kind or None to get all
Return type:: typing.List[axivion.dashboard.GlobalNamedFilter]
Returns:: the global named issue-list filters
Parameters:: kind (typing.Optional[str])

create_global_named_filter(display_name, kind, *, filters=None, sorters=None, visibility=None)¶

Creates a new global named filter.

Wraps POST /api/named_filters.

Note

Requires a Dashboard version >= 7.3.0

Parameters:

display_name (str) – the name to use for UI display of the named filter
kind (str) – one of ‘AV’, ‘CL’, ‘DE’, ‘CY’, ‘MV’, ‘SV’, ‘UNIVERSAL’.
filters (typing.Optional[typing.Mapping[str, str]])
sorters (typing.Optional[typing.List[typing.Union[typing.Tuple[str, str], typing.Mapping[str, str]]]])
visibility (typing.Optional[axivion.dashboard.NamedFilterVisibility])

Keyword Arguments:

filters – a dict of str->str where the key is the column key and the value the filter string
sorters – a list of 2-tuples (key,direction) where key is the column key and direction either ‘ASC’ or ‘DESC’.
visibility – the visibility configuration of the named filter

Return type:

axivion.dashboard.GlobalNamedFilter

Returns:

an object for operating on the created named filter

install_project(dbfile, name=None, altername=False, installifnotfound=False)¶

Allows admins to install a project from a database file.

Wraps POST /api/project_databases/install_project.

Note

Requires a Dashboard version >= 6.9.7

Parameters:

dbfile (str) – the server side path of the database file. If it is relative it will be interpreted relative to the Dashboard server configuration directory.
name (str) – the name to give the new project.
altername (bool) – whether the Dashboard shall choose a different name if the specified one cannot be used for some reason.
installifnotfound (bool) – install the project as specified even if no file is found at the given path.

Returns:

the name of the created project

Return type:

str

uninstall_project(name)¶

Allows admins to uninstall a project.

Wraps POST /api/project_databases/uninstall_project.

Note

Requires a Dashboard version >= 6.9.7

Parameters:: name (str) – the name of the project to uninstall
Return type:: None

projects()¶

Gets the project list.

Yields:: Project – an iterator over the projects you can see with the credentials provided
Return type:: typing.Iterable[axivion.dashboard.Project]

Note

Although some credentials grant you access to a certain project they might not grant you the permission to list projects or when listing them always return an empty list. Especially when authenticating via dbToken you cannot use this method and should instead use project()

project(name)¶

Provides a proxy object giving access to several project-specific API.

Note

Depending on the authentication method used, it might not be possible to determine at this point, whether the given project actually exists. In this case a “dead proxy” will be returned leading to errors only when using the object.

Returns:: a project referring to the Dashboard project with the given name or None if no project with the given name is found.
Return type:: Project
Parameters:: name (str) – the name identifying the project

create_project_from_backup(name, path)¶

Create a new Dashboard Project by restoring artifacts from a backup

Wraps POST /api/create_project_from_backup.

Parameters:

name (str)
path (typing.Union[str, os.PathLike[str]])

Return type:

axivion.dashboard.Project

get_analysis_sessions(project_name=None)¶

Returns a sequence of active analysis sessions.

Wraps GET /api/analysis_session.

Parameters:

projectName – (optional) Name of the project to be filtered
project_name (typing.Optional[str])

Return type:

typing.Sequence[typing.Mapping[str, typing.Union[typing.List[typing.Union[typing.List[JsonVal], typing.MutableMapping[str, JsonVal], str, int, float, bool, None]], typing.MutableMapping[str, typing.Union[typing.List[JsonVal], typing.MutableMapping[str, JsonVal], str, int, float, bool, None]], str, int, float, bool, None]]]

close()¶

Closes the underlying Dashboard HTTP connections if any are left open.

Afterwards the object cannot be used any more. Leaving a resource block for an instance of this class has the same effect as calling this method.

DbToken¶

class axivion.dashboard.DbToken¶

Bases: str

Wraps a database uid string as a credential to authenticate with the Dashboard.

The credential provides Dashboard access limited to view the data of exactly one project, namely the project having the same uid stored in its metadata table.

It can be obtained using the command line tool cidbman:

> cidbman metadata list path/to/project.db

Parameters:: dbUid (str) – the databases uid

GlobalNamedFilter¶

class axivion.dashboard.GlobalNamedFilter(dashboard, key)¶

Bases: object

Encapsulates methods related to a global Named Filter

Note

Requires a Dashboard version >= 7.3.0

Parameters:

dashboard (axivion.dashboard.Dashboard)
key (str)

get()¶

Get the bare named-filter data.

Wraps GET /api/named_filters/{id}.

Note

Requires a Dashboard version >= 7.3.0

Return type:: typing.Mapping[str, typing.Any]
Returns:: a dict of the form NamedFilterInfo

update(*, name=None, filters=None, sorters=None, visibility=None)¶

Update an existing named filter.

If one of the keyword arguments is not given, that part of the named filter will be left untouched.

Wraps PATCH /api/named_filters/{id}.

Note

Requires a Dashboard version >= 7.3.0

Keyword Arguments:

name – if given, the named filter will be renamed also resulting in a changed key and url
filters – a dict of str->str where the key is the column key and the value the filter string
sorters – a list of 2-tuples (key,direction) where key is the column key and direction either ‘ASC’ or ‘DESC’.
visibility – the visibility configuration of the named filter

Parameters:

name (typing.Optional[str])
filters (typing.Optional[typing.Mapping[str, str]])
sorters (typing.Optional[typing.List[typing.Union[typing.Tuple[str, str], typing.Mapping[str, str]]]])
visibility (typing.Optional[axivion.dashboard.NamedFilterVisibility])

Return type:

None

delete()¶

Deletes an existing named filter.

Wraps DELETE /api/named_filters/{id}. :rtype: None

Note

Requires a Dashboard version >= 7.3.0

NamedFilterVisibility¶

class axivion.dashboard.NamedFilterVisibility(*, groups=None)¶

Bases: object

Represents possible visibility restrictions of a global named filter

Keyword Arguments:: groups – if given, the named filter will be resricted to be used only by direct and indirect members of the given groups
Parameters:: groups (typing.Optional[typing.List[str]])

get_groups()¶

Return type:: typing.Optional[typing.List[str]]

Project¶

class axivion.dashboard.Project(dashboard, name)¶

Bases: object

Encapsulates an analysis project.

Parameters:

dashboard (axivion.dashboard.Dashboard)
name (str)

close()¶

name()¶

Returns:: the project’s name as used in the dashboard
Return type:: str

info()¶

Gets info about the project.

Contains the info gotten via users(), versions() and issuekinds() and some other data describing the project.

Wraps GET /api/projects/{projectName}.

Returns:: a dict containing project info of the form ProjectInfo
Return type:: dict

users()¶

Gets the users associated with the project.

Returns:

a list containing dicts of the form UserRef each: representing a user known to the project

Return type:

list

See also

The same data can also be gotten using info()

versions()¶

Gets the available analysis versions of the project.

Returns:

a list containing dicts of the form AnalysisVersion: each representing an analysis version of the project in chronologically ascending order

Return type:

list

See also

The same data can also be gotten using info()

issuekinds()¶

Gets a list of the issue kinds available in the project.

Returns:

a list containing dicts of the form IssueKindInfo each: representing an issue kind

Return type:

list

See also

The same data can also be gotten using info()

query_version(version)¶

Queries version details for a version string.

Wraps GET /api/projects/{projectName}/queryVersion.

Requires a Dashboard version of at least 6.9.2

Parameters:: version (str) – a version query string
Returns:: the resulting version info in form of a dict
Return type:: AnalysisVersion

get_issue_table_info(kind)¶

Gets Issue Table Meta-Data including Named Filters.

Wraps GET /api/projects/{projectName}/issues_meta.

Parameters:: kind (str) – one of ‘AV’, ‘CL’, ‘DE’, ‘CY’, ‘MV’, ‘SV’
Returns:: an issue table info json object in form of a dict
Return type:: TableInfo

class TableFormat(value)¶

Bases: Enum

Is used to specify an output-format for fetched issue-lists.

For further processing of the fetched data it is recommended to use ‘Json’ to receive a python-dict. When Using ‘Csv’, the csv-string has the same format than the downloaded csv-file from the web-ui.

Json = 1¶

Csv = 2¶

create_file_view_url(filename, *, version=None)¶

Create a file URL to be used by the Dashboard.

Parameters:

filename (str) – name of file to create the URL for
version (typing.Optional[str])

Keyword Arguments:

version (str) – a version query string that can be used to request a specific file version

Returns:

a path relative to the Dashboard’s basepath

create_issue_table_url(kind, *, start=None, end=None, user=None, column_filters=None, column_sorters=None, columns=None, named_filter=None, state=None, limit=None, offset=None, compute_total_row_count=False)¶

Create an issue table URL to be used by the Dashboard.

Parameters:

kind (str) – one of ‘AV’, ‘CL’, ‘DE’, ‘CY’, ‘MV’, ‘SV’
start (typing.Optional[str])
end (typing.Optional[str])
user (typing.Optional[str])
column_filters (typing.Optional[typing.Mapping[str, str]])
column_sorters (typing.Optional[typing.Sequence[typing.Union[typing.Tuple[str, str], typing.Mapping[str, str]]]])
columns (typing.Optional[typing.Sequence[str]])
named_filter (typing.Optional[str])
state (typing.Optional[str])
limit (typing.Optional[int])
offset (typing.Optional[int])
compute_total_row_count (bool)

Keyword Arguments:

start (str) – a version query string that can be used to request an issue diff
end – (str): a version query string that is either the version to fetch issues from or the second diff version
user – (str): a user name as gotten from users() [i][‘name’]
column_filters – a dict of str->str where the key is the column key and the value the filter string (since 6.9.0).
column_sorters – a list of 2-tuples (key,direction) where key is the column key and direction either ‘ASC’ or ‘DESC’.
columns – (list): If you want a specific set of columns in the result, you can specify the column keys here.
named_filter – (str): the id of a named filter e.g. ‘p_show_all’
state – Whether to return only added issues, only removed issues or both groups of issues, i.e. changed issues. (since 7.4.0)
limit – maximum number of issues to return. Return all if unspecified. (since 7.4.0)
offset – number of issues to skip in the returned result. (since 7.4.0)
compute_total_row_count – enables computation of the total number of issues. This parameter is only supported in combination with the Json output format. (since 7.4.0)

Return type:

str

Returns:

a path relative to the Dashboard’s basepath

fetch_issues(kind, start='0', end='latest', user='anybody', column_filters=None, column_sorters=None, columns=None, *, result_format=TableFormat.Json, named_filter=None, state='changed', limit=None, offset=None, compute_total_row_count=False)¶

Queries tabular data of issues very similar to what the issue table in the web-dashboard displays.

The path-filter is a special column filter with the key ‘any path’.

If you want to use a pre-defined Named-Filter you can do the following:

sv_meta = prj.get_issue_table_info(kind='SV')
my_named_filter = next(x for x in sv_meta['filters'] if x['displayName'] == 'My Filter')
prj.fetch_issues(kind='SV', named_filter=my_named_filter['key'])

Wraps GET /api/projects/{projectName}/issues.

Parameters:

kind (str) – one of ‘AV’, ‘CL’, ‘DE’, ‘CY’, ‘MV’, ‘SV’
start (str) – a version query string that can be used to request an issue diff
end – (str): a version query string that is either the version to fetch issues from or the second diff version
user – (str): a user name as gotten from users() [i][‘name’]
column_filters (typing.Optional[typing.Mapping[str, str]]) – a dict of str->str where the key is the column key and the value the filter string (since 6.9.0).
column_sorters (typing.Optional[typing.Sequence[typing.Union[typing.Tuple[str, str], typing.Mapping[str, str]]]]) – a list of 2-tuples (key,direction) where key is the column key and direction either ‘ASC’ or ‘DESC’.
columns (typing.Optional[typing.Sequence[str]]) – (list): If you want a specific set of columns in the result, you can specify the column keys here.

Keyword Arguments:

result_format – (TableFormat): An enum that determines if the return-type is a csv-formatted string or a python-dict.
named_filter – (str): the id of a named filter e.g. ‘p_show_all’
state – Whether to return only added issues, only removed issues or both groups of issues, i.e. changed issues. (since 7.4.0)
limit – maximum number of issues to return. Return all if unspecified. (since 7.4.0)
offset – number of issues to skip in the returned result. (since 7.4.0)
compute_total_row_count – enables computation of the total number of issues. This parameter is only supported in combination with the Json output format. (since 7.4.0)

Return type:

typing.Union[typing.Mapping[str, typing.Any], str]

Returns:

an issue table json object or a csv-formatted string depending on the chosen result_format

See also

count_issues() which accepts similar parameters but returns the count results only
The issue table column description

Parameters:

named_filter (typing.Optional[str])
state (str)
limit (typing.Optional[int])
offset (typing.Optional[int])
compute_total_row_count (bool)

count_issues(kind, start='0', end='latest', user='anybody', column_filters=None)¶

Queries counts of issues very similar to the counts available in the web-dashboard issue-table.

Note

Deprecated. Use fetch_issues() with limit=0 and computeTotalRowCount=True instead.

The path-filter is a special column filter with the key ‘any path’.

Parameters:

kind (str) – one of ‘AV’, ‘CL’, ‘DE’, ‘CY’, ‘MV’, ‘SV’
start (str) – a version query string that can be used to request an issue diff
end – (str): a version query string that is either the version to fetch issues from or the second diff version
user – (str): a user name as gotten from users() [i][‘name’]
column_filters – (dict): a dict of str->str where the key is the column key and the value the filter string.

Returns:

a dict containing the total issue count or added and removed counts for diff queries

Return type:

dict

get_system_entity(**kwargs)¶

Gets the System Entity.

Wraps GET /api/projects/{projectName}/getSystemEntity.

Examples

See List available System Metrics

Keyword Arguments:: version (str) – The optional version query string for the entity properties. If not specified, versioned entity attributes will not be included in the result. If it is specified, entities not available in that version will not be included in the result.
Returns:: the system entity will be the only element
Return type:: EntityList

get_entities(*, version=None, metric=None)¶

Gets a list of available entities.

The entity IDs can be used with fetch_metric_value_range().

Wraps GET /api/projects/{projectName}/getEntities.

Examples

See List available Entities

Keyword Arguments:

version (str) – the optional version query string for the entity properties. If not specified, versioned entity attributes will not be included in the result. If it is specified entities not available in that version will not be included in the result.
metric (str) – if specified, only entities having the associated Metric will be returned.

Returns:

the requested version and the list of entities

Return type:

EntityList

Parameters:

version (typing.Optional[str])
metric (typing.Optional[str])

get_metrics(*, version=None, entity=None)¶

Gets a list of available metrics.

The metric IDs can be used with fetch_metric_value_range().

Wraps GET /api/projects/{projectName}/getMetrics.

Examples

See List available System Metrics

Keyword Arguments:

version (str) – the optional version query string for the metric properties. If not specified, versioned metric attributes will not be included in the result. If it is specified metrics not available in that version will not be included in the result.
entity (str) – if specified, only metrics associated with the given Entity ID will be returned.

Returns:

the requested version and the list of metrics

Return type:

MetricList

Parameters:

version (typing.Optional[str])
entity (typing.Optional[str])

fetch_metric_value_range(**kwargs)¶

Fetches values for the given entity, metric and version range.

If you want to fetch values of multiple entities and metrics at once it is better to use fetch_entity_metric_values().

The values are returned as a list, with one entry for each version. The range of the list can be limited if desired. Note, that individual values for some analysis version may not be available which will result in a None entry in the value array.

Use get_metrics() for a list of available metrics and get_entities() for a list of available entities.

Wraps GET /api/projects/{projectName}/queryMetricValueRange.

Examples

See Getting Style Violations per Lines of Code

Keyword Arguments:

start (str) – the optional version query string defining the start version of the result range. Defaults to 1.
end (str) – the optional version query string defining the end version of the result range. Defaults to latest.
entity (str) – The Entity ID to fetch the values for.
metric (str) – The Metric ID to fetch the values for.

Returns:

the requested range of metric values

Return type:

MetricValueRange

fetch_entity_metric_values(**kwargs)¶

Fetches tabular data of metric values for a given version.

In order to query a whole range of metric values over time, it is much more efficient to use fetch_metric_value_range().

The usefulness of this method depends on your metrics configuration. By default only metric values related with metric violations are imported into the analysis database in order to keep it small. If you intend to do further metric value processing based on this method please refer to the documentation of the metrics framework in the reference guide.

Wraps GET /api/projects/{projectName}/queryMetricValueTable.

Keyword Arguments:

version (str) – a version query string to specify the analysis version, defaults to ‘latest’.
force_strings (bool) – Deprecated. Restores pre-6.9.2 behaviour, i.e. return all entity-fields as strings.

Returns:

the requested entity metric value table.

Return type:

MetricValueTable

fetch_files(**kwargs)¶

Fetches tabular data of revisions of files in project index.

Parameters:: version (str) – a version query string to specify the analysis version, defaults to ‘latest’.
Returns:: a dict containing the files from project index with their respective revision from VCS.
Return type:: dict

fetch_analyzed_files(version='latest')¶

Gets the list of analyzed files.

Wraps GET /api/projects/{projectName}/analyzed_files.

Parameters:: version (str) – a version query string to specify the analysis version
Returns:: the list of analyzed files
Return type:: AnalyzedFileList

fetch_rules(version='latest')¶

Gets a simple list of rules.

Wraps GET /api/projects/{projectName}/rules.

Parameters:: version (str) – a version query string to specify the analysis version
Returns:: the list of configured rules
Return type:: RuleList

fetch_executed_stylechecks(version='latest')¶: Deprecated. Use fetch_rules() instead.

get_issue_tags(issue_id)¶

Gets the list of tags a given issue is currently tagged with.

Wraps GET /api/projects/{projectName}/issues/{issueIdentifier}/tags.

Note

Requires a Dashboard version >= 6.6.2

Parameters:: issue_id (str) – id of the issue to get the tags from
Returns:: a dict containing a list of tag objects
Return type:: dict

tag_issue(issue_id, tag)¶

Ensures an issue is tagged with a given tag.

Wraps PUT /api/projects/{projectName}/issues/{issueIdentifier}/tags/{tag}.

Note

Requires a Dashboard version >= 6.6.2

Parameters:

issue_id (str) – id of the issue to tag
tag (str) – a string as the tag to be added

Return type:

None

untag_issue(issue_id, tag)¶

Ensures an issue is not tagged with a given tag.

Wraps DELETE /api/projects/{projectName}/issues/{issueIdentifier}/tags/{tag}.

Note

Requires a Dashboard version >= 6.6.2

Parameters:

issue_id (str) – id of the issue to untag
tag (str) – a string as the tag to be removed

Return type:

None

get_issue_comments(issue_id)¶

Gets the list of comments on an issue.

Wraps GET /api/projects/{projectName}/issues/{issueIdentifier}/comments.

Note

Requires a Dashboard version >= 6.6.2

Parameters:: issue_id (str) – id of the issue to get the comments from
Returns:: a dict containing a list of comments that are attached to the issue
Return type:: dict

comment_issue(issue_id, comment)¶

Adds a comment to an issue.

Wraps POST /api/projects/{projectName}/issues/{issueIdentifier}/comments.

Note

Requires a Dashboard version >= 6.6.2

Parameters:

issue_id (str) – id of the issue to comment
comment (str) – a string as the comment to be added

Return type:

None

delete_issue_comment(issue_id, comment_id)¶

Deletes an issue comment.

Wraps DELETE /api/projects/{projectName}/issues/{issueIdentifier}/comments/{id}.

Note

Requires a Dashboard version >= 6.6.2

Parameters:

issue_id (str) – id of the issue to delete the comment from
comment_id (str) – id of the comment to delete gotten via get_issue_comments()

Return type:

None

update_sourcecode_repositories()¶

Updates the SourceCode repositories associated with this project.

Wraps POST /api/projects/{projectName}/update_sourcecode_repositories.

Note

Requires a Dashboard version >= 6.9.15

Returns:: the VCS messages.
Return type:: RepositoryUpdateResponse

delete()¶

Deletes the project as well as all its artifact files.

Warning

If you delete a project this way, there is no way of restoring it unless you have created a backup before via /api/projects/{projectName}/create_backup.

This operation is only allowed for managed projects, i.e., projects that were created or migrated via the managed_upload mode of axivion_ci or branched from such a project.

Wraps DELETE /api/projects/{projectName}.

Note

Requires a Dashboard version >= 7.7.1

Return type:: bool
Returns:: True if the project existed and was successfully deleted. False if the project did not exist and thus was not deleted.

create_branch(*, name, version=None)¶

Creates a new project from an existing one.

No permissions for the newly created project will be assigned automatically, so you will usually want to have assigned project-specific permissions using wildcard patterns.

This operation is only allowed for managed projects, i.e., projects that were created or migrated via the managed_upload mode of axivion_ci or branched from such a project.

This operation becomes a NOOP if a projects with given name already exists and if the origin of this project is this with matching version. The version check can be disabled by passing None.

Wraps POST /api/projects/{projectName}/create_branch_project.

Note

Requires a Dashboard version >= 7.7.1

Keyword Arguments:

name – the name of the branch project to create
version –
a version query string specifying the analysis version to be included in the branch project. The given version will be the only one included in the branched database.

With Dashboard version 7.8.3, this parameter became optional where None defaults to latest. Moreover, None disables the version check for already existing branches, i.e., if a project with given name already exists, only the origin check is applied; the version check is skipped.

Returns:

the newly created project.

Return type:

:py:class:`axivion.dashboard.Project`

Parameters:

name (str)
version (typing.Optional[str])

export_backup(*, directory=None, filename=None)¶

Download project artifacts as a single, restorable file.

This operation is only allowed for managed projects, i.e. projects that were created or migrated via the managed_upload mode of axivion_ci or branched from such a project.

Wraps GET /api/projects/{projectName}/export_backup.

Keyword Arguments:

directory – path to write the zip-file to. Defaults to the current working directory.
filename – name of the downloaded file. Follows suggestion from server if none is given.

Returns:

The path of the resulting backup file

Return type:

Path

Parameters:

directory (typing.Union[str, os.PathLike[str], None])
filename (typing.Optional[str])

download_ir(*, directory=None, filename=None)¶

Download project IR if available.

Wraps GET /api/projects/{projectName}/ir.

Keyword Arguments:

directory – path to write the IR file to. Defaults to the current working directory.
filename – name of the IR file. Follows suggestion from server if none is given.

Returns:

The path of the resulting IR file or None if the project does not have an IR.

Return type:

Optional[Path]

Parameters:

directory (typing.Union[str, os.PathLike[str], None])
filename (typing.Optional[str])

download_rfg(directory=None, filename=None)¶

Download project RFG if available.

Wraps GET /api/projects/{projectName}/rfg.

Keyword Arguments:

directory – path to write the RFG file to. Defaults to the current working directory.
filename – name of the RFG file. Follows suggestion from server if none is given.

Returns:

The path of the resulting RFG file or None if the project does not have an RFG.

Return type:

Optional[Path]

Parameters:

directory (typing.Union[str, os.PathLike[str], None])
filename (typing.Optional[str])

User¶

class axivion.dashboard.User(dashboard, user_name)¶

Bases: object

Encapsulates a Dashboard user.

Parameters:

dashboard (axivion.dashboard.Dashboard)
user_name (str)

named_filters(*, kind=None)¶

Returns the named issue-list filters owned by this user.

Wraps GET /api/users/{user}/named_filters.

Note

Requires a Dashboard version >= 7.3.0

Keyword Arguments:: kind – one of ‘AV’, ‘CL’, ‘DE’, ‘CY’, ‘MV’, ‘SV’ to get only named filters compatible with the given kind or None to get all
Return type:: typing.List[axivion.dashboard.CustomNamedFilter]
Returns:: the custom named issue-list filters owned by this user
Parameters:: kind (typing.Optional[str])

create_custom_named_filter(display_name, kind, *, filters=None, sorters=None)¶

Creates a new custom named filter owned by this user.

Wraps POST /api/users/{user}/named_filters.

Note

Requires a Dashboard version >= 7.3.0

Parameters:

display_name (str) – the name to use for UI display of the named filter
kind (str) – one of ‘AV’, ‘CL’, ‘DE’, ‘CY’, ‘MV’, ‘SV’, ‘UNIVERSAL’.
filters (typing.Optional[typing.Mapping[str, str]])
sorters (typing.Optional[typing.List[typing.Union[typing.Tuple[str, str], typing.Mapping[str, str]]]])

Keyword Arguments:

filters – a dict of str->str where the key is the column key and the value the filter string
sorters – a list of 2-tuples (key,direction) where key is the column key and direction either ‘ASC’ or ‘DESC’.

Return type:

axivion.dashboard.CustomNamedFilter

Returns:

an object for operating on the created named filter

Functions¶

`create_project_from_dbfile`(path_to_dbfile, ...)	Use this in order to query data directly from a database-file.
`escape_column_filter`(filter_string)	Escapes a string to be used inside quotes in a column filter string.

create_project_from_dbfile¶

dashboard.create_project_from_dbfile(**kwargs)¶

Use this in order to query data directly from a database-file.

This method returns a closeable resource object. Preferably use the python resource idiom:

with create_project_from_dbfile('path/to/analysis.db') as project:
    project.fetch_issues(kind='SV')
    ...

Parameters:: path_to_dbfile (str) – the filesystem path to a axivion_ci result file that usually has the suffix .db
Returns:: python resource object providing access on the project data
Return type:: Project

escape_column_filter¶

dashboard.escape_column_filter()¶

Escapes a string to be used inside quotes in a column filter string.

The characters “ ? * [ are escaped. Some use cases require that only part of the quoted substring gets escaped. For example when creating an issue column filter with a rule name prefix like f’”{escape_column_filter(prefix)}*”’, only the prefix has to be escaped and * and “ have to be left verbatim to retain their meaning.

Parameters:: filter_string (str) – The column filter
Return type:: str
Returns:: The escaped string.

Axivion Suite 7.12.0

Navigation

7.2.2.1. Module axivion.dashboard¶

Classes¶

ApiToken¶

CustomNamedFilter¶

Dashboard¶

DbToken¶

GlobalNamedFilter¶

NamedFilterVisibility¶

Project¶

User¶

Functions¶

create_project_from_dbfile¶

escape_column_filter¶