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.
- summary(*, issue)¶
Return a summary description (preferably a single line of text representation) of
issue
.Raises
NotImplementedError
by default.
- class fuzzinator.formatter.FormatterDecorator¶
Base class for
Formatter
decorators.- __call__(formatter_class)¶
Return a decorated version of
formatter_class
. Create a subclass offormatter_class
that transfers control toinit
,call
, orsummary
when its__init__
,__call__
, orsummary
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 typecls
. 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 bysuper().call(cls, obj, issue=issue)
(which will call this method, and then transitively the original__call__
) or bysuper(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 typecls
. 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 bysuper().init(cls, obj, **kwargs)
(which will call this method, and then transitively the original__init__
) or bysuper(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
ofobj
of typecls
. The default operation is to call thesummary
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 originalsummary
at some point, which can be performed either bysuper().summary(cls, obj, issue=issue)
(which will call this method, and then transitively the originalsummary
) or bysuper(cls, obj).summary(issue=issue)
(which calls the originalsummary
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
norlong
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 (enableextra
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 ofstring.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 byFormatter.__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 theshort
andlong
parameters) or by a file containing such a string content (through theshort_file
andlong_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 oftemplate
.Raises
NotImplementedError
by default.