Plugin classes

New in version 4.0.

The CoveragePlugin class

class coverage.CoveragePlugin

Base class for coverage.py plugins.

To write a coverage.py plugin, create a module with a subclass of CoveragePlugin. You will override methods in your class to participate in various aspects of coverage.py’s processing.

Currently the only plugin type is a file tracer, for implementing measurement support for non-Python files. File tracer plugins implement the file_tracer() method to claim files and the file_reporter() method to report on those files.

Any plugin can optionally implement sys_info() to provide debugging information about their operation.

Coverage.py will store its own information on your plugin object, using attributes whose names start with _coverage_. Don’t be startled.

To register your plugin, define a function called coverage_init in your module:

def coverage_init(reg, options):
    reg.add_file_tracer(MyPlugin())

You use the reg parameter passed to your coverage_init function to register your plugin object. It has one method, add_file_tracer, which takes a newly created instance of your plugin.

If your plugin takes options, the options parameter is a dictionary of your plugin’s options from the coverage.py configuration file. Use them however you want to configure your object before registering it.

file_tracer(filename)

Get a FileTracer object for a file.

Every Python source file is offered to the plugin to give it a chance to take responsibility for tracing the file. If your plugin can handle the file, then return a FileTracer object. Otherwise return None.

There is no way to register your plugin for particular files. Instead, this method is invoked for all files, and the plugin decides whether it can trace the file or not. Be prepared for filename to refer to all kinds of files that have nothing to do with your plugin.

The file name will be a Python file being executed. There are two broad categories of behavior for a plugin, depending on the kind of files your plugin supports:

  • Static file names: each of your original source files has been converted into a distinct Python file. Your plugin is invoked with the Python file name, and it maps it back to its original source file.
  • Dynamic file names: all of your source files are executed by the same Python file. In this case, your plugin implements FileTracer.dynamic_source_filename() to provide the actual source file for each execution frame.

filename is a string, the path to the file being considered. This is the absolute real path to the file. If you are comparing to other paths, be sure to take this into account.

Returns a FileTracer object to use to trace filename, or None if this plugin cannot trace this file.

file_reporter(filename)

Get the FileReporter class to use for a file.

This will only be invoked if filename returns non-None from file_tracer(). It’s an error to return None from this method.

Returns a FileReporter object to use to report on filename.

sys_info()

Get a list of information useful for debugging.

This method will be invoked for --debug=sys. Your plugin can return any information it wants to be displayed.

Returns a list of pairs: [(name, value), ...].

The FileTracer class

class coverage.FileTracer

Support needed for files during the execution phase.

You may construct this object from CoveragePlugin.file_tracer() any way you like. A natural choice would be to pass the file name given to file_tracer.

FileTracer objects should only be created in the CoveragePlugin.file_tracer() method.

See How Coverage.py works for details of the different coverage.py phases.

source_filename()

The source file name for this file.

This may be any file name you like. A key responsibility of a plugin is to own the mapping from Python execution back to whatever source file name was originally the source of the code.

See CoveragePlugin.file_tracer() for details about static and dynamic file names.

Returns the file name to credit with this execution.

has_dynamic_source_filename()

Does this FileTracer have dynamic source file names?

FileTracers can provide dynamically determined file names by implementing dynamic_source_filename(). Invoking that function is expensive. To determine whether to invoke it, coverage.py uses the result of this function to know if it needs to bother invoking dynamic_source_filename().

See CoveragePlugin.file_tracer() for details about static and dynamic file names.

Returns True if dynamic_source_filename() should be called to get dynamic source file names.

dynamic_source_filename(filename, frame)

Get a dynamically computed source file name.

Some plugins need to compute the source file name dynamically for each frame.

This function will not be invoked if has_dynamic_source_filename() returns False.

Returns the source file name for this frame, or None if this frame shouldn’t be measured.

line_number_range(frame)

Get the range of source line numbers for a given a call frame.

The call frame is examined, and the source line number in the original file is returned. The return value is a pair of numbers, the starting line number and the ending line number, both inclusive. For example, returning (5, 7) means that lines 5, 6, and 7 should be considered executed.

This function might decide that the frame doesn’t indicate any lines from the source file were executed. Return (-1, -1) in this case to tell coverage.py that no lines should be recorded for this frame.

The FileReporter class

class coverage.FileReporter(filename)

Support needed for files during the analysis and reporting phases.

See How Coverage.py works for details of the different coverage.py phases.

FileReporter objects should only be created in the CoveragePlugin.file_reporter() method.

There are many methods here, but only lines() is required, to provide the set of executable lines in the file.

relative_filename()

Get the relative file name for this file.

This file path will be displayed in reports. The default implementation will supply the actual project-relative file path. You only need to supply this method if you have an unusual syntax for file paths.

source()

Get the source for the file.

Returns a Unicode string.

The base implementation simply reads the self.filename file and decodes it as UTF8. Override this method if your file isn’t readable as a text file, or if you need other encoding support.

lines()

Get the executable lines in this file.

Your plugin must determine which lines in the file were possibly executable. This method returns a set of those line numbers.

Returns a set of line numbers.

excluded_lines()

Get the excluded executable lines in this file.

Your plugin can use any method it likes to allow the user to exclude executable lines from consideration.

Returns a set of line numbers.

The base implementation returns the empty set.

translate_lines(lines)

Translate recorded lines into reported lines.

Some file formats will want to report lines slightly differently than they are recorded. For example, Python records the last line of a multi-line statement, but reports are nicer if they mention the first line.

Your plugin can optionally define this method to perform these kinds of adjustment.

lines is a sequence of integers, the recorded line numbers.

Returns a set of integers, the adjusted line numbers.

The base implementation returns the numbers unchanged.

arcs()

Get the executable arcs in this file.

To support branch coverage, your plugin needs to be able to indicate possible execution paths, as a set of line number pairs. Each pair is a (prev, next) pair indicating that execution can transition from the prev line number to the next line number.

Returns a set of pairs of line numbers. The default implementation returns an empty set.

no_branch_lines()

Get the lines excused from branch coverage in this file.

Your plugin can use any method it likes to allow the user to exclude lines from consideration of branch coverage.

Returns a set of line numbers.

The base implementation returns the empty set.

translate_arcs(arcs)

Translate recorded arcs into reported arcs.

Similar to translate_lines(), but for arcs. arcs is a set of line number pairs.

Returns a set of line number pairs.

The default implementation returns arcs unchanged.

exit_counts()

Get a count of exits from that each line.

To determine which lines are branches, coverage.py looks for lines that have more than one exit. This function creates a dict mapping each executable line number to a count of how many exits it has.

To be honest, this feels wrong, and should be refactored. Let me know if you attempt to implement this method in your plugin...

missing_arc_description(start, end, executed_arcs=None)

Provide an English sentence describing a missing arc.

The start and end arguments are the line numbers of the missing arc. Negative numbers indicate entering or exiting code objects.

The executed_arcs argument is a set of line number pairs, the arcs that were executed in this file.

By default, this simply returns the string “Line {start} didn’t jump to {end}”.

source_token_lines()

Generate a series of tokenized lines, one for each line in source.

These tokens are used for syntax-colored reports.

Each line is a list of pairs, each pair is a token:

[('key', 'def'), ('ws', ' '), ('nam', 'hello'), ('op', '('), ... ]

Each pair has a token class, and the token text. The token classes are:

  • 'com': a comment
  • 'key': a keyword
  • 'nam': a name, or identifier
  • 'num': a number
  • 'op': an operator
  • 'str': a string literal
  • 'txt': some other kind of text

If you concatenate all the token texts, and then join them with newlines, you should have your original source back.

The default implementation simply returns each line tagged as 'txt'.