Issue Formatters: package fuzzinator.formatter

class fuzzinator.formatter.ChevronFormatter(*, short='', short_file=None, long='', long_file=None)

Formatter class following the format of the mustache templating language and using the Chevron module for interpreting it.

The formatter renders both the short and long versions of the issue according to the user-defined templates. If either of the templates is missing, then that version will be presented as an empty string (default).

Optional parameters of the formatter:

  • short: the issue summary template string (default: empty string).

  • short_file: path to a file containing the issue summary template (default: None).

  • long: the detailed issue template string (default: empty string).

  • long_file: path to a file containing the detailed issue template (default: None).

Example configuration snippet:

[sut.foo]
# see fuzzinator.call.*
formatter=fuzzinator.formatter.ChevronFormatter

[sut.foo.formatter]
short={id}
long_file=/path/to/templates/foo.md
class fuzzinator.formatter.DecoderDecorator(*, encoding='utf-8', **kwargs)

Decorator for formatters to stringify the issue dictionary values.

This decorator decodes all the byte values of an issue dictionary to string before calling the formatter (i.e., it modifies its input rather than its output).

Optional parameter of the decorator:

  • encoding: encoding to use to decode byte values ('utf-8' by default).

Example configuration snippet:

[sut.foo]
# see fuzzinator.call.*
formatter=fuzzinator.formatter.StringFormatter
formatter.decorate(0)=fuzzinator.formatter.DecoderDecorator

[sut.foo.formatter]
long_file=/path/to/templates/foo.md

[sut.foo.formatter.decorate(0)]
encoding=utf-8
class fuzzinator.formatter.Formatter

Abstract base class to represent issue formatters.

__call__(*, issue)

Return a string representation of issue, formatted in full.

Raises NotImplementedError by default.

Parameters:

issue (dict[str, Any]) – The issue to be formatted.

Returns:

The string representation of the issue.

Return type:

str

summary(*, issue)

Return a summary description (preferably a single line of text representation) of issue.

Raises NotImplementedError by default.

Parameters:

issue (dict[str, Any]) – The issue to be formatted.

Returns:

The summarized string representation of the issue.

Return type:

str

class fuzzinator.formatter.FormatterDecorator

Base class for Formatter decorators.

__call__(formatter_class)

Return a decorated version of formatter_class. Create a subclass of formatter_class that transfers control to init, call, or summary when its __init__, __call__, or summary methods are invoked.

Parameters:

formatter_class – The issue formatter class to decorate.

Returns:

The decorated version of the issue formatter class.

call(cls, obj, *, issue)

Call obj of type cls. The default operation is to call the __call__ method of the original version of the formatter class and return its result.

Subclasses of FormatterDecorator may override this method if customization of calling the formatter is needed. Usually, the overridden method has to call the original __call__ at some point, which can be performed either by super().call(cls, obj, issue=issue) (which will call this method, and then transitively the original __call__) or by super(cls, obj).__call__(issue=issue) (which calls the original __call__ directly).

Parameters:
  • cls – The decorated version of the formatter class, as returned by __call__.

  • obj – The issue formatter instance to invoke.

  • issue – The issue to be formatted, as defined by Formatter.__call__.

Returns:

The string representation of the issue, as defined by Formatter.__call__.

init(cls, obj, **kwargs)

Initialize obj of type cls. The default operation is to call the __init__ method of the original version of the formatter class.

Subclasses of FormatterDecorator may override this method if customization of the initialization is needed. Usually, the overridden method has to call the original __init__ at some point, which can be performed either by super().init(cls, obj, **kwargs) (which will call this method, and then transitively the original __init__) or by super(cls, obj).__init__(**kwargs) (which calls the original __init__ directly).

Parameters:
  • cls – The decorated version of the formatter class, as returned by __call__.

  • obj – The issue formatter instance to initialize.

summary(cls, obj, *, issue)

Call summary of obj of type cls. The default operation is to call the summary method of the original version of the formatter class and return its result.

Subclasses of FormatterDecorator may override this method if customization of the issue summary is needed. Usually, the overridden method has to call the original summary at some point, which can be performed either by super().summary(cls, obj, issue=issue) (which will call this method, and then transitively the original summary) or by super(cls, obj).summary(issue=issue) (which calls the original summary directly).

Parameters:
  • cls – The decorated version of the formatter class, as returned by __call__.

  • obj – The issue formatter instance to invoke.

  • issue – The issue to be formatted, as defined by Formatter.summary.

Returns:

The summary description of the issue, as defined by Formatter.summary.

class fuzzinator.formatter.JinjaFormatter(*, short='', short_file=None, long='', long_file=None)

Formatter class using the Jinja template engine to render issue dictionaries.

The formatter renders both the short and long versions of the issue according to the user-defined templates. If either of the templates is missing, then that version will be presented as an empty string (default).

Optional parameters of the formatter:

  • short: the issue summary template string (default: empty string).

  • short_file: path to a file containing the issue summary template (default: None).

  • long: the detailed issue template string (default: empty string).

  • long_file: path to a file containing the detailed issue template (default: None).

Example configuration snippet:

[sut.foo]
# see fuzzinator.call.*
formatter=fuzzinator.formatter.JinjaFormatter

[sut.foo.formatter]
short={{id}}
long_file=/path/to/templates/foo.md
class fuzzinator.formatter.JsonFormatter(**kwargs)

A simple JSON-based issue formatter.

This formatter does not take any custom instructions regarding the format, beyond that it’s processed with JSON. The summary description of an issue is its id field, while the full representation is a sorted and 4-space indented JSON dump of the issue.

Because of these defaults, there is no need to define templates for the two versions (i.e., neither short nor long definitions are required).

Example configuration snippet:

[sut.foo]
# see fuzzinator.call.*
formatter=fuzzinator.formatter.JsonFormatter
class fuzzinator.formatter.MarkdownDecorator(*, extensions=None, **kwargs)

Decorator for formatters that produce their output in Markdown format.

This decorator converts the full string representation of an issue to HTML, while the summary remains untouched. The reason is that the summary usually serves as a subject in e-mails or as a title of bug reports. In these cases having an HTML-converted summary isn’t suitable, while the main content, i.e., the long format, is expected to be in HTML.

Optional parameter of the decorator:

  • extensions: array of markdown extensions to enable (enable extra by default).

Example configuration snippet:

[sut.foo]
# see fuzzinator.call.*
formatter=fuzzinator.formatter.StringFormatter
formatter.decorate(0)=fuzzinator.formatter.MarkdownDecorator

[sut.foo.formatter]
long_file=/path/to/templates/foo.md

[sut.foo.formatter.decorate(0)]
extensions=["extra", "codehilite"]
class fuzzinator.formatter.StringFormatter(*, short='', short_file=None, long='', long_file=None)

A simple string-template-based issue formatter.

The formatter renders both the short and long versions of the issue according to the user-defined templates. If either of the templates is missing, then that version will be presented as an empty string (default).

The user-defined templates should follow the syntax expected by the format method of string.Formatter.

Optional parameters of the formatter:

  • short: the issue summary template string (default: empty string).

  • short_file: path to a file containing the issue summary template (default: None).

  • long: the detailed issue template string (default: empty string).

  • long_file: path to a file containing the detailed issue template (default: None).

Example configuration snippet:

[sut.foo]
# see fuzzinator.call.*
formatter=fuzzinator.formatter.StringFormatter

[sut.foo.formatter]
short={id}
long_file=/path/to/templates/foo.md
class fuzzinator.formatter.TemplateFormatter(*, short='', short_file=None, long='', long_file=None)

Abstract base class of template-based formatters.

The concept of formatters is to provide a way of custom issue visualization. Issues can be rendered differently when they are sent via e-mail, displayed in TUI, or inserted into a report for an arbitrary issue tracker.

Every formatter class must support two formats: a short and a long version. The short version (returned by Formatter.summary) acts as a summary of the issue, e.g., the subject of an email, while the long version (returned by Formatter.__call__) can give a detailed description about the failure, e.g., the body of an issue report.

The subclasses of TemplateFormatter can define templates for the two formats either by a plain string in the format expected by the chosen template class (with the short and long parameters) or by a file containing such a string content (through the short_file and long_file options).

Note: if a template is defined both by plain string and through file, then the file content will be used.

render(*, issue, template)

Render the string representation of issue with the help of template.

Raises NotImplementedError by default.

Parameters:
  • issue (dict[str, Any]) – The issue to be formatted.

  • template (str) – The template to use for formatting.

Returns:

The string representation of the issue.

Return type:

str