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
- 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
- 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 customlogging.Handler
is automatically installed to uselogging
as logging front-end andGNAThub.Logger
as logging back-end.- Parameters:
name (str) – the name of the logger
- 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.- 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.
- class GNAThub.Project[source]
Bases:
object
A project namespace, fully implemented in Ada.
- 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 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 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. Ifname
is an absolute path, it is returned as is. Otherwise, only the base name is used (i.e. we remove any directory information fromname
).- 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]
- 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.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 linecol_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 theGNAThub.Message
to add.line
,col_begin
,col_end
: int, seeadd_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:
- 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
- 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 theGNAThub.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 byRun
. 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.
- 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]