1.1. GNAThub package

1.1.1. Module contents

This module defines the core components of GNAThub plugin mechanism.

It declares module routines and classes implemented in Ada and exported to Python.

In particular the GNAThub.Plugin is the base class to use for writing plug-ins.

class GNAThub.Console[source]

Bases: object

Provide several helper routines implemented in Ada.

static error(message, prefix=None)[source]

Print an error message.

Always activated.

Parameters:
  • message (str) – the message to display

  • prefix (str) – optional prefix to the message

static info(message, prefix=None)[source]

Print an informative message.

Activated at default verbosity.

Parameters:
  • message (str) – the message to display

  • prefix (str) – optional prefix to the message

static ko(message, columns=79)

Display a KO message.

Execution step …………………………. [FAILED]

Parameters:
  • message (str) – the message to display

  • columns (int) – optional maximum column to use for display (default to 79)

static ok(message, columns=79)

Display an OK message.

Execution step …………………………. [PASSED]

Parameters:
  • message (str) – the message to display

  • columns (int) – optional maximum column to use for display (default to 79)

static progress(current, total, new_line=False)[source]

Print a progress message.

Activated at default verbosity level. If new_line is True, then terminates the line with a n character.

Parameters:
  • current (int) – the current value

  • total (int) – the total value

  • new_line (bool) – whether to terminate with a new line

static set_failure(message, prefix=None)[source]

Used to set a global run failure.

This is done when one or more plugins have failed during GNAThub run.

Parameters:
  • message (str) – the message to display

  • prefix (str) – optional prefix to the message

static warn(message, prefix=None)[source]

Print a warning message.

Activated at default verbosity output.

Parameters:
  • message (str) – the message to display

  • prefix (str) – optional prefix to the message

class GNAThub.Entity(name, kind, line, col_begin, col_end, resource)[source]

Bases: object

An Entity object, representing an entity in the database.

__init__(name, kind, line, col_begin, col_end, resource)[source]

Return the entity of the given properties, creating it if necessary.

Parameters:
  • name (str) – the name of the entity

  • resource (GNAThub.Resource) – the resource that contains entity

add_messages(messages)[source]

Add multiple messages to the given entity.

Prefer this function when there are many messages to insert, for efficiency.

Parameters:

messages (collections.Iterable) – the messages to add

col_begin
col_end
id
kind
line
static list()[source]

Return all the entities stored in the database.

Returns:

the list of all GNAThub.Entity

Return type:

collections.Iterable[GNAThub.Entity]

list_messages()[source]

List all messages associated with this entity.

Returns:

a list of GNAThub.Message

Return type:

collections.Iterable[GNAThub.Message]

name
resource_id
exception GNAThub.Error[source]

Bases: Exception

Base class for exceptions in this module.

class GNAThub.Logger(name)[source]

Bases: object

A logger object. Fully implemented in Ada.

__init__(name)[source]

Create a new Ada logger object.

From GNAThub plug-ins, prefer the use of logging instead of this logger class. A custom logging.Handler is automatically installed to use logging as logging front-end and GNAThub.Logger as logging back-end.

Parameters:

name (str) – the name of the logger

log(message)[source]

Log a message.

Parameters:

message (str) – the message to log

class GNAThub.Message(rule, message, ranking=1, tool_msg_id=0, properties=None)[source]

Bases: object

A Message object, representing one message in the database.

__init__(rule, message, ranking=1, tool_msg_id=0, properties=None)[source]

Return the message matching the given properties.

Parameters:
  • rule (GNAThub.Rule) – the rule to which this message belongs

  • message (str) – the data to associate to the message: this should be a numeric value if the rule is of METRIC_KIND

  • tool_msg_id (int) – the tool original message id

  • properties (collections.Iterable[GNAThub.Property] or None) – one or more properties

col_begin
col_end
data
id
line
static list()[source]

Return all messages stored in the database.

Returns:

the list of all GNAThub.Message

Return type:

collections.Iterable[GNAThub.Message]

ranking
rule_id
tool_msg_id
class GNAThub.Plugin[source]

Bases: object

GNAThub plugin interface.

A plugin is a Python class that describe how to configure, run and collect data output by an external tool.

Each plugin should be dedicated to only one tool.

To implement a now plugin, simply creates a new Python class inheriting from this (GNAThub.Plugin) abstract base class.

All plugins are collected using the inheritance mechanism, i.e. the GNAThub driver will automatically find all classes implementing the GNAThub.Plugin interface. No manual registration needed.

__init__()[source]

Initialize instance properties.

error(message, *args)[source]

Display an error message, prefixed with the plug-in name.

Parameters:
  • message (str) – the message to display

  • args (collections.Iterable) – format string arguments

property exec_status

Return the execution status for the tool.

Can be one of the following:

  • GNAThub.NOT_EXECUTED: plugin did not run yet

  • GNAThub.EXEC_FAILURE: an error occurred during the plugin execution

  • GNAThub.EXEC_SUCCESS: the plugin execution completed successfully

Returns:

the exit code

Return type:

int

info(message, *args)[source]

Display an informative message, prefixed with the plug-in name.

Parameters:
  • message (str) – the message to display

  • args (collections.Iterable) – format string arguments

property name

Return the name of the tool.

Returns:

the tool name

Return type:

str

setup()[source]

Called prior to a call to Plugin.execute().

This is where environment setup should be done to ensure a correct execution of the tool.

teardown()[source]

Called after a call to Plugin.execute().

This is where environment cleanup should be done to ensure a consistent state for a future execution.

warn(message, *args)[source]

Display a warning message, prefixed with the plug-in name.

Parameters:
  • message (str) – the message to display

  • args (collections.Iterable) – format string arguments

class GNAThub.Project[source]

Bases: object

A project namespace, fully implemented in Ada.

__init__()[source]

Instance constructor.

Do not use directly.

static artifacts_dir()[source]

Return the full path to the root project artifacts directory if defined as IDE attribute in IDE mode, the object directory if is defined, project directory if any of the previous value is set.

Return type:

str

static name()[source]

Return the name of the root project.

Return type:

str

static object_dir()[source]

Return the full path to the root project object directory.

Return type:

str

static object_dirs()[source]

Return the list of object directories in the project tree.

Returns:

the list of object directories for the current project

Return type:

dict[str, list[str]]

static path()[source]

Return the full path to the root project.

Return type:

str

static property_as_list(key, package=None)[source]

Return a project property.

Returns the list of string representation of the project property from the package GNATdashboard.

Parameters:
  • key (str) – the property name

  • package (str) – the package name (default to GNATdashboard package)

Returns:

the property value

Return type:

list[str]

static property_as_string(key, package=None)[source]

Return a project property.

Returns the string representation of the project property from the package GNATdashboard.

Parameters:
  • key (str) – the property name

  • package (str) – the package name (default to GNATdashboard package)

Returns:

the property value

Return type:

str

static runtime()[source]

Return the runtime of the root project.

This concerns only the runtime for Ada.

Return type:

str

static scenario_switches()[source]

Return the scenario as a list of switches of the form -Xvar=value.

Returns:

the list of scenario switches passed to GNAThub

Return type:

collections.Iterable[str]

static source_dirs()[source]

Return the list of source directories for each project.

Returns:

the list of all sources directories per project

Return type:

dict[str, list[str]]

static source_file(name)[source]

Create a new file.

This will automatically try to solve name to an absolute path if it currently is a base name. If name is an absolute path, it is returned as is. Otherwise, only the base name is used (i.e. we remove any directory information from name).

Parameters:

name (str) – the source file basename

Returns:

the full path to the source file

Return type:

str

static source_files()[source]

Return the list of source files for each project.

Returns:

the list of all sources files per project

Return type:

list[str]

static source_suffixes(language)[source]

Return a list of Ada source file suffixes.

The list is used by the project manager to find Ada source files, ie. both specifications and implementations.

Parameters:

language (str) – the language of the sources

Returns:

the list of valid Ada source file extensions

Return type:

collections.Iterable[str]

static target()[source]

Return the target of the root project.

Return type:

str

class GNAThub.Property(identifier, name)[source]

Bases: object

A Property object, corresponding to a message property.

__init__(identifier, name)[source]

Return a Property, creating it if necessary.

Parameters:
  • identifier (str) – the unique identifier of the property

  • name (str) – the display name of the property

id
identifier
static list()[source]

Return all properties stored in the database.

Returns:

the list of all GNAThub.Property

Return type:

collections.Iterable[GNAThub.Property]

name
class GNAThub.Reporter[source]

Bases: object

Plugin extension point for reporter tools.

abstract report()[source]

Abstract method. Needs custom implementation by derived classes.

Collect the results produced by the external tool. This method is called after setup() and before teardown().

Returns:

GNAThub.EXEC_SUCCESS on success, GNAThub.EXEC_FAILURE otherwise

Return type:

int

class GNAThub.Resource(name, kind)[source]

Bases: object

A Resource object, corresponding to a resource in the database.

A resource represents either a file, a directory, or a project.

__init__(name, kind)[source]

Return a Resource, creating it if necessary.

Parameters:
  • name (str) – the name of the resource. For files and directories, this should be a normalized full path: the full path with all links resolved, and with the original filesystem casing. For a project, this is the cased name of the project

  • kind (int) – PROJECT_KIND, DIRECTORY_KIND, FILE_KIND for projects, directories, and files, respectively

add_message(message, line=0, col_begin=1, col_end=None)[source]

Add a message to the given resource.

Parameters:
  • message (GNAThub.Message) – the Message to add

  • line (int) – the line to associate the message to, if the resource is a file. Use 0 to indicate a message which should be associated to the resource but not to a specific line

  • col_begin (int) – the begin column of the message

  • col_end (int) – the end column of the message. None means that the end column should be the same as the begin column.

add_messages(messages)[source]

Add multiple messages to the given resource.

Prefer this function when there are many messages to insert, for efficiency. messages is a list, each entry being a list of the form:

[message, line, col_begin, col_end]

message is the GNAThub.Message to add. line, col_begin, col_end: int, see add_message().

Example:

resource.add_messages([
    [ message, 1, 2, 2 ],
    [ message, 2, 1, 1 ],
    [ message, 0, 1, 1 ],
    [ message, 10002, 1, 1 ],
    [ message, 10003, 1, 1 ],
    [ message, 10005, 1, 1 ],
])
Parameters:

messages (collections.Iterable) – the messages to add

static get(name)[source]

Return the GNAThub.Resource with the given name.

Do not create it if it doesn’t exist.

Parameters:

name (str) – the name of the resource to get

Returns:

the GNAThub.Resource of that name

Return type:

GNAThub.Resource

id
kind
static list()[source]

List all resources stored in the database.

Returns:

the list of all GNAThub.Resource

Return type:

collections.Iterable[GNAThub.Resource]

list_entities_messages()[source]

List all entities messages associated with this resource.

Returns:

a list of GNAThub.Message

Return type:

collections.Iterable[GNAThub.Message]

list_messages()[source]

List all messages associated with this resource.

Returns:

a list of GNAThub.Message

Return type:

collections.Iterable[GNAThub.Message]

name
class GNAThub.Rule(name, identifier, kind, tool)[source]

Bases: object

A Rule object, representing a rule in the database.

__init__(name, identifier, kind, tool)[source]

Return the rule of the given properties, creating it if necessary.

Parameters:
  • name (str) – the name of the rule

  • identifier (str) – an unique identifier for this rule (typically, the same as name)

  • kind (int) – RULE_KIND to indicate a rule where messages are given without a numeric value, or METRIC_KIND to indicate a rule where messages correspond to a numeric value

  • tool (GNAThub.Tool) – the tool that defines this rule

id
identifier
kind
static list()[source]

Return all the rules stored in the database.

Returns:

the list of all GNAThub.Rule

Return type:

collections.Iterable[GNAThub.Rule]

name
tool_id
class GNAThub.Run(name, argv, env=None, workdir=None, out=None, capture_stderr=True, append_out=False)[source]

Bases: object

Class to handle processes.

__init__(name, argv, env=None, workdir=None, out=None, capture_stderr=True, append_out=False)[source]

Spawn the process.

Use subprocess.Popen to spawn a process and returns its exit code.

Parameters:
  • name (str) – the name of the executable

  • argv (collections.Iterable[str]) – the argument array

  • env (dict[str, str]) – Map containing the environment to pass through to the process. If None, os.environ is used.

  • workdir (str) – the directory in which to execute the process. If None, use the current directory.

  • out (str) – the log file to use

  • append_out (bool) – whether to use ‘a’ or ‘w’ flag to open log file

  • capture_stderr (bool) – whether to capture the standard error in the log file

cmdline_image()[source]

Return a string image of the given command.

Returns:

the command line image

Return type:

str

static expand_argv(name, argv)[source]

TODO(delay)

Parameters:
  • name (str) – the name of the executable

  • argv (collections.Iterable[str]) – the argument array

output()[source]

Return the path to the output file.

Returns:

the full path to the file

Return type:

str

static quote(arg)[source]

Return the quoted version of the given argument.

Parameters:

arg (str) – the argument to quote

Returns:

the quoted argument

Return type:

str

wait()[source]

Wait until process ends and returns its status.

class GNAThub.Runner[source]

Bases: object

Plugin extension point for analyser tools.

abstract run()[source]

Abstract method. Needs custom implementation by derived classes.

Execute the external tool. This method is called after setup() and before teardown().

Returns:

GNAThub.EXEC_SUCCESS on success, GNAThub.EXEC_FAILURE otherwise

Return type:

int

class GNAThub.Tool(name)[source]

Bases: object

A Tool object, mapping to a Tool entry in the database.

__init__(name)[source]

Return the tool of the given name, creating it if necessary.

Parameters:

name (str) – the name of the tool to create or retrieve

add_messages(resources_messages, entities_messages)[source]

Add resources and entities (if any) messages to the given tool.

Prefer this function when there are many messages to insert, for efficiency. resources_messages is a list, each entry being a list of the form:

[resource, message_data]

where message_data is a list and each entry is of the form

[message, line, col_begin, col_end]

message is the GNAThub.Message to add. line, col_begin, col_end: int.

Example:

tool.add_messages(
        [[resource1, [[ message, 1, 2, 2 ],
                     [ message, 2, 1, 1 ],
                     [ message, 0, 1, 1 ]]],
         [resource2, [[ message, 10002, 1, 1 ],
                     [ message, 10003, 1, 1 ],
                     [ message, 10005, 1, 1 ]]]],
        [[entity1, [[message, 1, 2, 2]]],
         [entity2, [[ message, 1, 2, 2 ],
                    [ message, 2, 1, 1 ]]]])
Parameters:

messages (collections.Iterable) – the messages to add

static clear_references(tool)[source]

Clear all references to a tool in the database.

Parameters:

tool (str) – the name of the tool

id
static list()[source]

List all the tools stored in the database.

Returns:

the list of all tools

Return type:

collections.Iterable[GNAThub.Tool]

name
class GNAThub.ToolArgsPlaceholder(tool_name)[source]

Bases: object

Placeholder for tool-specific arguments.

By default tool-specific arguments (see tool_args()) are automatically appended to the end of the command line by Run. In some cases this is not flexible enough (eg. when used in combination of the -output-msg[-only] switches of :prog:`codepeer`. For such cases, this placeholder object should be inserted at the correct position in the command line so that it can be substituted by the appropriate list of arguments.

__init__(tool_name)[source]
GNAThub.database()[source]

Return the path to the GNAThub SQLite database.

Usually <project_object_dir>/gnathub/gnathub.db.

Returns:

the full path to the local serialized SQLite database

Return type:

str

GNAThub.db_dir()[source]

Return the Codepeer DB repository

Returns:

the repository path

Return type:

str

GNAThub.dry_run()[source]

Whether to run in “check mode” or not.

Returns:

whether the dry-run flag is enabled or not

Return type:

bool

GNAThub.dry_run_without_project()[source]

Return true if –dry-run mode without project file.

Returns:

bool

GNAThub.gnatcheck_hide_exempted()[source]

Whether the gnatcheck-hide-exempted switch was passed to the GNAThub driver or not.

Returns:

whether the gnatcheck-hide-exempted switch is passed or not

Return type:

bool

GNAThub.html_data()[source]

Return the path to the GNAThub-specific directory for HTML report data.

Usually <project_object_dir>/gnathub/html-report/data.

Returns:

the full path to the log directory

Return type:

str

GNAThub.incremental()[source]

Whether the incremental switch was passed to the GNAThub driver or not.

Returns:

whether the incremental switch is passed or not

Return type:

bool

GNAThub.jobs()[source]

Return the number of parallel jobs to execute.

This is the equivalent to using -j on the command-line.

Returns:

the maximum number of separate processes to spawn

Return type:

int

GNAThub.logs()[source]

Return the path to the GNAThub-specific directory for logs.

Usually <project_object_dir>/gnathub/logs.

Returns:

the full path to the log directory

Return type:

str

GNAThub.output_dir()[source]

Return the Codepeer output repository

Returns:

the repository path

Return type:

str

GNAThub.plugins()[source]

Return the list of comma-separated plug-in names.

This is the list of plug-ins as specified on the command-line with the --plugins switch.

Returns:

the list of plug-in name

Return type:

collections.Iterable[str]

GNAThub.port()[source]

Return the port number provided with the switch.

This is the equivalent to using :–port switch on the command-line.

Returns:

the port number

Return type:

int

GNAThub.quiet()[source]

Whether the quiet flag was passed to the GNAThub driver or not.

Returns:

whether the quiet flag is enabled or not

Return type:

bool

GNAThub.repositories()[source]

Return the list of available repositories.

The dictionary contains 3 keys:

  • system

  • global

  • local

These repositories correspond respectively to the [core] and [extra] directories from the GNAThub installation, and the Local_Repository the user can specify in its project file.

Returns:

the available repositories details

Return type:

dict[str, str]

GNAThub.root()[source]

Return the path to the GNAThub-specific root directory.

Usually <project_object_dir>/gnathub.

Returns:

the full path to the directory

Return type:

str

GNAThub.sonar_work_dir()[source]

Return the sonar scanner work dir used by SonarQube provided by the switch.

This is the equivalent to using --sonar-cache-dir on the command-line.

Returns:

the path of the new sonar sources cache

Return type:

str

GNAThub.subdirs()[source]

Return the name of the new object directory provided with the switch.

This is the equivalent to using --subdirs on the command-line.

Returns:

the name of the new object directory

Return type:

str

GNAThub.tool_args(tool_name)[source]

Return the list of extra switches to pass to an inferior tool.

This is the concatenation of switches for the tool tool_name as provided on the command-line with the -targs: switch.

Parameters:

tool_name (str) – the name of the tool

Returns:

the list of extra switches for tool_name

Return type:

collections.Iterable[str]

GNAThub.u_process_all()[source]

Whether the -U switch was passed to the GNAThub driver or not.

Returns:

whether -U switch is enabled or not

Return type:

bool

GNAThub.verbose()[source]

Whether the verbose flag was passed to the GNAThub driver or not.

Returns:

whether the verbosity flag is enabled or not

Return type:

bool