7.2.3.1. Module axivion.dashboard.report¶

Main Module of the Dashboard Reporting API.

See Reporting Framework on how to use this.

Classes¶

`Context`()	Base class for the Module context in the visualization/reporting frameworks
`Option`()	Declares a single option of a report-module identified by name.
`Report`()	Report writing context
`ReportApiVersion`(major, minor)	Defines a Report API Version
`ReportRunner`()	Represents the Reporting Framework used to create and execute the module.
`ReportWriter`()	Base class to implement by report scripts in the reporting framework.
`Writer`()	Common methods to be implemented by Reporting/Visualization modules.

Context¶

class axivion.dashboard.report.Context¶

Bases: ABC

Base class for the Module context in the visualization/reporting frameworks

abstract get_project()¶

Returns a handle to access project-related analysis data.

Return type:: axivion.dashboard.Project

abstract get_option_value(key)¶

Returns the option value for the given option name.

Parameters:: key (str)
Return type:: typing.Any

abstract get_dashboard()¶

Returns the Dashboard used to fetch the report data.

This is only available when a Dashboard is configured as datasource. Will raise ValueError otherwise. :rtype: axivion.dashboard.Dashboard

Note

Since ReportApiVersion 2.2 Since VisualizationApi 1.0

abstract get_dashboard_user()¶

Returns the name of the dashboard user used to fetch the report data.

This is only available when a Dashboard is configured as datasource. Will raise ValueError otherwise.

Return type:: str

abstract get_logger()¶

Returns a preconfigured logger defaulting to LogLevel INFO.

Return type:: logging.Logger

Since:: ReportApiVersion 2.1 VisualizationApiVersion 1.0

Intended for nicely tuneable report module logging. Feel free to adjust the loglevel to your needs e.g. by exposing a module option:

Option.select(
    name='loglevel',
    description='One of ERROR,WARNING,INFO,DEBUG',
    choices=('ERROR', 'WARNING', 'INFO', 'DEBUG'),
    default='INFO',
),

and then doing:

logger = context.get_logger()
logger.setLevel(report.get_option_value('loglevel'))
logger.debug('Logging initialized')
logger.info('Beginning Report Creation...')

abstract query_version(version, *, project=None)¶

Queries version info for a given version-string.

Parameters:

version (str) – the version-string
project (typing.Optional[axivion.dashboard.Project]) – the project to query the version info for

Returns:

the resulting version info in form of a dict

Return type:

AnalysisVersion

Since:: ReportApiVersion 3.0 VisualizationApiVersion 1.0

To ensure a consistent interpretation of the version-string, the string should be resolved once and the resulting version info reused in all relevant queries:

version = context.query_version('latest')
# and then in follow-up data-queries
project.fetch_issues(kind='SV', version=version['date'])
project.fetch_files(version=version['date'])
# and somewhere label the gadget with the version-name
output.write(version['name'])

Option¶

class axivion.dashboard.report.Option¶

Bases: ABC

Declares a single option of a report-module identified by name.

classmethod text(*, name, default='', description=None)¶

Expect an arbitrary text

Parameters:

name (str)
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod boolean(*, name, default=False, description=None)¶

Expect either True or False

Parameters:

name (str)
default (bool)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod integer(*, name, default=0, min_value=None, max_value=None, description=None)¶

Expect an integer value

Parameters:

name (str)
default (int)
min_value (typing.Optional[int])
max_value (typing.Optional[int])
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod select(*, name, choices, default, description=None)¶

Expect exactly one item out of a definable list of choices

Parameters:

name (str)
choices (typing.Sequence[str])
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod multi_select(*, name, choices, defaults, description=None)¶

Expect one or more items out of a definable list of choices

Parameters:

name (str)
choices (typing.Sequence[str])
defaults (typing.Sequence[str])
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod list(*, name, element_type, min_length=0, description=None)¶

Expect a list of option values of the same type.

It is possible to specify a list option by giving multiple command-line values of the element_type name.

Since:: ReportApiVersion 2.2

Keyword Arguments:

name – the option name that ideally is a plural ending in s
element_type – option type that the list elements must have
min_length – Specify to require a minimum number of list elements
description – the option description

Parameters:

name (str)
element_type (axivion.dashboard.report.Option)
min_length (int)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod version(*, name, default='latest', description=None)¶

Expect an analysis version string as accepted by the Dashboard API

Parameters:

name (str)
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod named_filter(*, name, default='p_show_all', description=None)¶

Expect the key of an issue-kind agnostic Named Filter as used by the Dashboard API

Parameters:

name (str)
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod named_filter_av(*, name, default='p_show_all', description=None)¶

Expect the key of an Architecture Violation compatible Named Filter as used by the Dashboard API

Parameters:

name (str)
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod named_filter_cl(*, name, default='p_show_all', description=None)¶

Expect the key of a Clone compatible Named Filter as used by the Dashboard API

Parameters:

name (str)
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod named_filter_cy(*, name, default='p_show_all', description=None)¶

Expect the key of a Cycle compatible Named Filter as used by the Dashboard API

Parameters:

name (str)
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod named_filter_de(*, name, default='p_show_all', description=None)¶

Expect the key of a Dead Entity compatible Named Filter as used by the Dashboard API

Parameters:

name (str)
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod named_filter_mv(*, name, default='p_show_all', description=None)¶

Expect the key of an Metric Violation compatible Named Filter as used by the Dashboard API

Parameters:

name (str)
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

classmethod named_filter_sv(*, name, default='p_show_all', description=None)¶

Expect the key of an Style Violation compatible Named Filter as used by the Dashboard API

Parameters:

name (str)
default (str)
description (typing.Optional[str])

Return type:

axivion.dashboard.report.Option

Report¶

class axivion.dashboard.report.Report¶

Bases: Context

Report writing context

This provides you with 2 ways of providing the report data created by your module:

get a filename where you should write the report to

get a sink where you should write the bytes of the report to

abstract get_report_output_path(file_name)¶

Gets a filesystem path for manually opening and writing a report to

If you use this, you must not use get_sink().

May only be called once.

Parameters:: file_name (str) – the file name (without directory) to use for the report
Return type:: pathlib.Path
Returns:: filesystem path to write to

abstract get_sink(file_name, *, allow_overwrite=True)¶

Indicates that the report data shall be streamed as raw bytes

If you use this, you must not use get_report_output_path().

May only be called once. You may, but do not have to close the sink when done writing.

Parameters:

file_name (str) – the file name (without directory) to use for the report
allow_overwrite (bool)

Keyword Arguments:

allow_overwrite – Since ReportApiVersion 2.0. Whether to overwrite a file potentially existing at the target location

Return type:

typing.BinaryIO

Returns:

The binary sink to write the report to

ReportApiVersion¶

class axivion.dashboard.report.ReportApiVersion(major, minor)¶

Bases: object

Defines a Report API Version

Changes in the major version indicate incompatible API changes where scripts usually will need to be adjusted in order to target the newer version.

Changes in the minor version indicate pure API additions where you don’t need to adjust your module code and can still increase the target framework version.

The framework implementation is backwards compatible unless stated otherwise and usually this only happens for new major versions. This means that e.g. framework version 2.0 can run modules targeting 1.0 but framework version 3.0 cannot run modules programmed against older frameworks as it explicitly states so below.

Version History:

1.0: (Axivion Suite 7.2.0)

Initial Version

2.0: (Axivion Suite 7.3.0)

remove implicit output file existence check from Report.get_report_output_path(). Callers must do the check themselves on the result path they get if they want to prevent accidental overwriting of an existing file at the target location.
remove implicit output file existence check from Report.get_sink(). The method now has a new keyword argument allow_overwrite defaulting to True that can be used to choose the desired behavior.

2.1: (Axivion Suite 7.3.1)

add Context.get_logger()

2.2: (Axivion Suite 7.4.0)

add Option.list()
add Option.integer()
add Context.get_dashboard()

3.0: (Axivion Suite 7.5.0)

require local python imports to be relative
backwards compatibility reset. Minimum required module version is now 3.0
add Context.query_version()

Parameters:

major (int)
minor (int)

major: int¶

minor: int¶

ReportRunner¶

class axivion.dashboard.report.ReportRunner¶

Bases: ABC

Represents the Reporting Framework used to create and execute the module.

An instance of this class is passed in the factory method used for creating a module.

abstract version()¶

Returns the Framework version which is the same as the Axivion Suite Version.

Return type:: typing.Tuple[int, ...]

ReportWriter¶

class axivion.dashboard.report.ReportWriter¶

Bases: Writer

Base class to implement by report scripts in the reporting framework.

abstract report_api_version()¶

The API version the module is programmed against.

You can find out the version of the API you are programming against by calling get_current_reporting_api_version(). Note, that you should not simply call get_current_reporting_api_version() in the report_api_version() implementation.

Return type:: axivion.dashboard.report.ReportApiVersion

abstract write_report(context)¶

Write the report.

Parameters:: context (axivion.dashboard.report.Report)
Return type:: None

Writer¶

class axivion.dashboard.report.Writer¶

Bases: ABC

Common methods to be implemented by Reporting/Visualization modules.

abstract get_description()¶

Textual description of what this module does.

Return type:: str

abstract get_options()¶

Get the list of options required by this module.

Return type:: typing.Tuple[axivion.dashboard.report.Option, ...]

Functions¶

get_current_reporting_api_version()

The current version of the reporting api

get_current_reporting_api_version¶

report.get_current_reporting_api_version()¶

The current version of the reporting api

Be sure to hard-code the report API version you want to program against in your ReportWriter implementation like this:

def report_api_version(self) -> ReportApiVersion:
    return ReportApiVersion(3, 0)

Also be sure to have read the documentation of ReportApiVersion before increasing the target api version of your module.

Return type:: axivion.dashboard.report.ReportApiVersion

Axivion Suite 7.12.0

Navigation

7.2.3.1. Module axivion.dashboard.report¶

Classes¶

Context¶

Option¶

Report¶

ReportApiVersion¶

ReportRunner¶

ReportWriter¶

Writer¶

Functions¶

get_current_reporting_api_version¶