pyEDAA.Reports.CLI

Tools to extract data from UCDB files.

Usage

First export/convert the Aldec Coverage Database (ACDB) into UCDB (Universal Coverage Database) format. The helper program acdb2xml (part of Active-HDL or Riviera-PRO installation) can be used.

acdb2xml -i aggregate.acdb -o ucdb.xml

At next use this layer’s service program to convert from UCDB to Cobertura format.

pyedaa-ucis export --ucdb ucdb.xml --cobertura cobertura.xml

Submodules

Functions

main(): Entrypoint to start program execution.

Classes

Application: Program class to implement the command line interface (CLI) using commands and options.

Functions

pyEDAA.Reports.CLI.main()[source]

Entrypoint to start program execution.

This function should be called either from:

if __name__ == "__main__": or
console_scripts entry point configured via setuptools in setup.py.

This function creates an instance of Program in a try ... except environment. Any exception caught is formatted and printed before the program returns with a non-zero exit code.

Return type:: NoReturn

Classes

class pyEDAA.Reports.CLI.Application[source]

Program class to implement the command line interface (CLI) using commands and options.

Inheritance

HEADLINE: ClassVar[str] = 'Report Service Program': Headline of the application, printed by _PrintHeadline().

ISSUE_TRACKER_URL: ClassVar[str] = 'https://GitHub.com/edaa-org/pyEDAA.Reports/issues': URL to the issue tracker for reporting bugs.

__init__()[source]

Initializer of a line-based terminal interface.

Parameters:: mode – Optional, defines what output (normal, error, data) to write where. Default: a linear flow all to STDOUT.
Return type:: None

Run()[source]

Parse the command line arguments and call the handler method the command selects.

Parameters:: enableAutoComplete – Optional, if True, register the parser with argcomplete, if that package is installed.
Return type:: None

HandleDefault(_)[source]

Handle program calls without any command.

Return type:: None
Parameters:: _ (Namespace)

HandleHelp(args)[source]

Handle program calls with command help.

Return type:: None
Parameters:: args (Namespace)

HandleVersion(_)[source]

Handle program calls with command version.

Return type:: None
Parameters:: _ (Namespace)

_PrintVersion()[source]

Helper function to print the version information.

Return type:: None

_PrintHelp(command=None)[source]

Helper function to print the command line parsers help page(s).

Return type:: None
Parameters:: command (str | None)

_mainParser: The main argument parser of the application.

_formatter: Help page formatter class used by every parser.

_subParser: The sub-parser action the sub-commands are registered at.

_subParsers: Sub-command name to its argument parser.

property BaseIndent: int

Property to access the base indentation level of written messages (_baseIndent).

The assigned level is added to every message’s own indentation.

Returns:: Base indentation level.

Configure(*, verbose=False, debug=False, silent=False, quiet=False, writeToStdOut=True)

Configure the verbosity of the application, usually from the command line switches.

The resulting LogLevel is the minimum severity a message needs to be written: Severity.Debug in debug mode, Severity.Verbose in verbose mode, Severity.Silent in silent mode, Severity.Quiet in quiet mode, otherwise Severity.Normal. Debug mode implies verbose mode.

Parameters:

verbose (bool) – Optional, write verbose messages. Default: False.
debug (bool) – Optional, write debug messages, implying verbose messages. Default: False.
silent (bool) – Optional, reduce the messages to warnings and higher severities. Default: False.
quiet (bool) – Optional, reduce the messages to errors and always visible messages. Default: False.
writeToStdOut (bool) – Optional, write to STDOUT. Default: True.

Return type:

None

property CriticalWarningCount: int

Read-only property to access the number of counted critical warnings.

Returns:: Number of critical warnings.

property Debug: bool

Check if debug messages are enabled.

Returns:: True, if debug messages are written.

property ErrorCount: int

Read-only property to access the number of counted errors.

Returns:: Number of errors.

Exit(returnCode=0)

Exit the terminal application by uninitializing color support and returning an Exit code.

Parameters:: returnCode (int) – Optional, return code for application exit.
Return type:: NoReturn

ExitOnPreviousCriticalWarnings(includeErrors=True)

Exit application if error or critical warnings have been printed.

Parameters:: includeErrors (bool) – Optional, if True, count previous errors as well as critical warnings.
Return type:: None

ExitOnPreviousErrors()

Exit application if errors have been printed.

Return type:: None

ExitOnPreviousWarnings(includeCriticalWarnings=True, includeErrors=True)

Exit application if error or (critical) warnings have been printed.

Parameters:

includeCriticalWarnings (bool) – Optional, if True, count previous critical warnings as well as warnings.
includeErrors (bool) – Optional, if True, count previous errors as well.

Return type:

None

FATAL_EXIT_CODE = 255: Return code for fatal exits.

FOREGROUND = {'BLUE': '\x1b[94m', 'CYAN': '\x1b[96m', 'DARK_BLUE': '\x1b[34m', 'DARK_CYAN': '\x1b[36m', 'DARK_GRAY': '\x1b[90m', 'DARK_GREEN': '\x1b[32m', 'DARK_RED': '\x1b[31m', 'DARK_YELLOW': '\x1b[33m', 'ERROR': '\x1b[91m', 'GRAY': '\x1b[37m', 'GREEN': '\x1b[92m', 'HEADLINE': '\x1b[95m', 'MAGENTA': '\x1b[95m', 'NOCOLOR': '\x1b[39m', 'RED': '\x1b[91m', 'WARNING': '\x1b[93m', 'WHITE': '\x1b[97m', 'YELLOW': '\x1b[93m'}: Terminal colors

FatalExit(returnCode=0)

Exit the terminal application by uninitializing color support and returning a fatal Exit code.

Parameters:: returnCode (int) – Optional, return code for application exit.
Return type:: NoReturn

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:

ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.
ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

static GetTerminalSize()

Returns the terminal size as tuple (width, height) for Windows, macOS (Darwin), Linux, cygwin (Windows), MinGW32/64 (Windows).

Return type:: tuple[int, int]
Returns:: A tuple containing width and height of the terminal’s size in characters.
Raises:: PlatformNotSupportedError – When a platform is not yet supported.

HandleCoverage(args)

Handle program calls with command coverage.

Return type:: None
Parameters:: args (Namespace)

HandleUnittest(args)

Handle program calls with command unittest.

Return type:: None
Parameters:: args (Namespace)

property Height: int

Read-only property to access the terminal’s height.

Returns:: The terminal window’s height in characters.

INDENT = ' ': Indentation. Default: " " (2 spaces)

InitializeColors()

Initialize the terminal for color support by colorama.

Return type:: bool
Returns:: True, if ‘colorama’ package could be imported and initialized.

property Lines: list[Line]

Read-only property to access the list of printed lines (messages).

Returns:: List of lines.

property LogLevel: Severity

Property to access the minimal severity level a message needs to be written (_writeLevel).

Assigning a level replaces what Configure() computed from the verbosity switches.

Returns:: The current minimal severity level.

MISSING_DEPENDENCY_EXIT_CODE = 242: Return code (242), if an optional dependency is missing; the value lives on the exception - see PrintMissingDependencyError().

property MainParser: ArgumentParser

Read-only property to access the main argument parser (_mainParser).

Returns:: The main argument parser.

NOT_IMPLEMENTED_EXCEPTION_EXIT_CODE = 240: Return code, if unimplemented methods or code sections were called.

PrintException(ex)

Prints an exception of type Exception and its traceback.

If the exception as a nested action, the cause is printed as well.

If ISSUE_TRACKER_URL is configured, a URL to the issue tracker is added.

Parameters:: ex (Exception) – The exception to print.
Return type:: NoReturn

PrintExceptionBase(ex)

Prints an exception of type ExceptionBase and its traceback.

If the exception as a nested action, the cause is printed as well.

If ISSUE_TRACKER_URL is configured, a URL to the issue tracker is added.

Parameters:: ex (Exception) – The exception to print.
Return type:: NoReturn

PrintMissingDependencyError(ex)

Print a missing optional dependency and the command lines installing it.

Unlike the other printers, this one does not report a bug: there is no traceback, and no invitation to open an issue, because nothing is wrong with the program - a package it can use is not installed. The message names the missing package and every installation option the exception carries (InstallCommands).

Attention

A dependency missing while a module is imported raises before an application object exists, so this method cannot report that case. An application that wants to survive it catches the exception around its own imports and prints the commands directly:

from pyTooling.Exceptions import MissingDependencyError

try:
  from myPackage.Plotting import Plot
except MissingDependencyError as ex:
  print(f"{ex}\n" + "\n".join(f"  {command}" for command in ex.InstallCommands))
  raise SystemExit(MissingDependencyError.EXIT_CODE) from ex

Parameters:: ex (MissingDependencyError) – The exception to print.
Return type:: NoReturn
Returns:: Never - the method exits the application with MISSING_DEPENDENCY_EXIT_CODE.

See also

PrintException(): → Print an unhandled exception and its traceback.
PrintNotImplementedError(): → Print a call to an unimplemented function or abstract method.

PrintNotImplementedError(ex)

Prints a not-implemented exception of type NotImplementedError.

If ISSUE_TRACKER_URL is configured, a URL to the issue tracker is added.

Parameters:: ex (NotImplementedError) – The exception to print.
Return type:: NoReturn

property Quiet: bool

Check if quiet mode is enabled.

Returns:: True, if quiet mode is enabled.

property Silent: bool

Check if silent mode is enabled.

Returns:: True, if silent mode is enabled.

property SubParsers: dict[str, ArgumentParser]

Read-only property to access the sub-parsers (_subParser).

Returns:: Dictionary of command names and their sub-parsers.

TryWriteLine(line)

Check if a line object of a certain severity would be written.

Parameters:: line – Line object to check.
Return type:: bool
Returns:: True, if line would be written.

UNHANDLED_EXCEPTION_EXIT_CODE = 241: Return code, if an unhandled exception reached the topmost exception handler.

UninitializeColors()

Uninitialize the terminal for color support by colorama.

Return type:: bool
Returns:: True, if ‘colorama’ package could be imported and uninitialized.

property Verbose: bool

Check if verbose messages are enabled.

Returns:: True, if verbose messages are written.

property WarningCount: int

Read-only property to access the number of counted warnings.

Returns:: Number of warnings.

property Width: int

Read-only property to access the terminal’s width.

Returns:: The terminal window’s width in characters.

WriteCritical(message, *, indent=0, appendLinebreak=True)

Write a critical message.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteCriticalNote(message, *, indent=0, appendLinebreak=True)

Write a critical note.

Depending on internal settings and rules, a note might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the note.
appendLinebreak (bool) – Optional, append a linebreak after the note. Default: True

Return type:

bool

Returns:

True, if note was actually written.

WriteDebug(message, *, indent=0, appendLinebreak=True)

Write a debug message.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteDryRun(message, *, indent=0, appendLinebreak=True)

Write a dry-run message message.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteError(message, *, indent=0, appendLinebreak=True)

Write an error message.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteErrorNote(message, *, indent=0, appendLinebreak=True)

Write a note belonging to an error, which is where the advice for fixing it goes.

Depending on internal settings and rules, a note might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the note.
appendLinebreak (bool) – Optional, append a linebreak after the note. Default: True

Return type:

bool

Returns:

True, if note was actually written.

WriteFatal(message, *, indent=0, appendLinebreak=True, exitCode=0, immediateExit=True)

Write a fatal message and exit.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True
exitCode (int) – Optional, exit application with this exit code. Default: 0
If 0, use FATAL_EXIT_CODE as exit code.
immediateExit (bool) – Optional, exit application immediately. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteInfo(message, *, indent=0, appendLinebreak=True)

Write an info message.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteLine(line)

Print a formatted line to the underlying terminal/console offered by the operating system.

The message is indented by INDENT repeated Line.Indent times. The indentation is applied to the message, not to the whole line, so the severity markers stay in one column.

Parameters:: line (Line) – Line object to indent, format and print.
Return type:: bool
Returns:: True, if line was actually written.

WriteLineToStdErr(message, end='\n')

Low-level method for writing to STDERR.

Parameters:

message (str) – Message to write to STDERR.
end (str) – Optional, use newline character. Default: \n.

Return type:

int

Returns:

Number of written characters.

WriteLineToStdOut(message, end='\n')

Low-level method for writing to STDOUT.

Parameters:

message (str) – Message to write to STDOUT.
end (str) – Optional, use newline character. Default: \n.

Return type:

int

Returns:

Number of written characters.

WriteNormal(message, *, indent=0, appendLinebreak=True)

Write a normal message.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteQuiet(message, *, indent=0, appendLinebreak=True)

Write an always visible message.

This message is even visible in quiet mode.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteToStdErr(message)

Low-level method for writing to STDERR.

Parameters:: message (str) – Message to write to STDERR.
Return type:: int
Returns:: Number of written characters.

WriteToStdOut(message)

Low-level method for writing to STDOUT.

Parameters:: message (str) – Message to write to STDOUT.
Return type:: int
Returns:: Number of written characters.

WriteVerbose(message, *, indent=0, appendLinebreak=True)

Write a verbose message.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteWarning(message, *, indent=0, appendLinebreak=True)

Write a warning message.

Depending on internal settings and rules, a message might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the message.
appendLinebreak (bool) – Optional, append a linebreak after the message. Default: True

Return type:

bool

Returns:

True, if message was actually written.

WriteWarningNote(message, *, indent=0, appendLinebreak=True)

Write a warning note.

Depending on internal settings and rules, a note might be skipped.

Parameters:

message (str) – Message to write.
indent (int) – Optional, indentation level of the note.
appendLinebreak (bool) – Optional, append a linebreak after the note. Default: True

Return type:

bool

Returns:

True, if note was actually written.

_EnabledAutoComplete()

Register the main parser with argcomplete for shell completion.

The package is optional: when it isn’t installed, completion is silently unavailable.

Return type:: None

static _FindFiles(globPattern)

Find the files matching a file pattern, relative to the current directory or absolute.

Parameters:: globPattern (str) – The file pattern, e.g. report/unit/*.xml.
Return type:: Tuple[Path, ...]
Returns:: The matching files.

_GetLatestVersion(packageName, timeout=1)

Query PyPI for the latest released version of a package.

Every error - an unreachable index, a timeout, an unknown package - is answered with None, because a version check must not fail the application it is printing the version of.

Parameters:

packageName (str) – Name of the package on PyPI.
timeout (int) – Optional, timeout in seconds for the request. Default: 1.

Return type:

str | None

Returns:

The latest version as a string, or None, if it couldn’t be determined.

_LOG_LEVEL_ROUTING__: Message routing rules.

_LOG_MESSAGE_FORMAT__ = {Severity.Debug: '{DARK_GRAY}{message}{NOCOLOR}', Severity.Verbose: '{GRAY}{message}{NOCOLOR}', Severity.DryRun: '{DARK_CYAN}[DRY] {message}{NOCOLOR}', Severity.Normal: '{WHITE}{message}{NOCOLOR}', Severity.Info: '{WHITE}{message}{NOCOLOR}', Severity.WarningNote: '{DARK_YELLOW} > {message}{NOCOLOR}', Severity.Warning: '{YELLOW}[WARNING] {message}{NOCOLOR}', Severity.CriticalNote: '{DARK_YELLOW} > {message}{NOCOLOR}', Severity.Critical: '{DARK_YELLOW}[CRITICAL] {message}{NOCOLOR}', Severity.Quiet: '{WHITE}{message}{NOCOLOR}', Severity.ErrorNote: '{DARK_RED} > {message}{NOCOLOR}', Severity.Error: '{RED}[ERROR] {message}{NOCOLOR}', Severity.Fatal: '{DARK_RED}[FATAL] {message}{NOCOLOR}', Severity.ExceptionNote: '{DARK_RED} > {message}{NOCOLOR}', Severity.Exception: '{RED}[EXCEPTION] {message}{NOCOLOR}'}: Message formatting rules.

_ParseArguments()

Parse the command line arguments and route them to the selected handler method.

Return type:: None

_PrintHeadline(width=80)

Helper method to print the program headline.

Parameters:: width (int) – Optional, number of characters for horizontal lines.
Return type:: None

Generated output

=========================
    centered headline
=========================

_ReadCoverage(task)

Read a code coverage report and convert it to the common model.

Parameters:

task (str) – The option’s value: [<Format>:]<File>, e.g. Gcov-JSON:main.gcov.json.gz.

Return type:

CoverageSummary

Returns:

The report’s summary in the common model.

Raises:

CodeCoverageError – If the format isn’t supported.
The exception notes the supported formats.
CodeCoverageError – If the report can’t be read.

_RouteToHandler(args)

Call the handler method the parsed arguments select.

The handler is stored as an unbound function, so it is called with the application object as first parameter.

Parameters:: args (Namespace) – The parsed command line arguments.
Return type:: None

_SplitTask(task, formats, direction)

Split an option’s value <Format>:<FilePattern> into the format and the file pattern.

The value is split at its first : only, so the file pattern may contain colons, like a Windows drive letter.

Parameters:

task (str) – The option’s value, e.g. pyTest-JUnit:report/unit/*.xml.
formats (Type[Format]) – The formats the option accepts.
direction (str) – input or output, for the error message.

Return type:

Tuple[Format, str]

Returns:

The format and the file pattern.

Raises:

UnittestError – If the value names a format the option doesn’t accept.
The exception notes the supported formats and the default format.

_WriteCoverage(summary, task)

Write the common model as a code coverage report.

Parameters:

summary (CoverageSummary) – The summary to write.
task (str) – The option’s value: [<Format>:]<File>, e.g. Cobertura:coverage.xml.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:: dict[str, Any]
Returns:: Dictionary of slot names and their values.
Raises:: ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:: state (dict[str, Any]) – Dictionary of slot names and their values.
Raises:: ExtendedTypeError – If the given state misses a slot or carries an unexpected one.
Return type:: None

_baseIndent: Indentation level added to every message’s own indentation.

_criticalWarningCount: Number of critical warnings written so far.

_debug: True, if debug messages are written.

_errorCount: Number of errors written so far.

_height: Terminal height in characters

_lines: Every message written so far, in the order it was written.

_quiet: True, if only errors and quiet messages are written.

_silent: True, if no messages are written at all.

_stderr: STDERR

_stdin: STDIN

_stdout: STDOUT

_verbose: True, if verbose messages are written.

_warningCount: Number of warnings written so far.

_width: Terminal width in characters

_writeLevel: Minimal severity a message needs to be written.

_writeToStdOut: True, if messages are written to STDOUT instead of STDERR.