Plugins

Coverage.py’s behavior can be extended by writing plugins. A plugin is a separately installed Python class that you register in your .coveragerc. Plugins can be used to implement coverage measurement for non-Python files.

Using plugins

To use a coverage.py plugin, you install it, and configure it. For this example, let’s say you want to use one called fred_plugin.

1. Install the plugin as you would any other Python package:

   pip install fred_plugin
   

2. Configure coverage.py to use the plugin. You do this by editing (or creating) your .coveragerc file, as described in Configuration files. The plugins setting indicates your plugin:

   [run]
   plugins =
       fred_plugin
   

3. If the plugin needs its own configuration, you can add those settings in the .coveragerc file in a section named for the plugin:

   [fred_plugin]
   option1 = True
   option2 = abc.foo
   

   Check the documentation for the plugin to see if it takes any options, and what they are.

4. Run your tests as you usually would.

Plugin API

class coverage.plugin.CoveragePlugin

Base class for coverage.py plugins.

To write a coverage.py plugin, create a subclass of CoveragePlugin. You can override methods here 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.

file_reporter(filename)

Return the FileReporter class to use for filename.

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

file_tracer(filename)

Return a FileTracer object for a file.

Every 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 can decide 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.

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.

sys_info()

Return 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.

The return value is a list of pairs: (name, value).

class coverage.plugin.FileTracer

Support needed for files during the tracing phase.

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

dynamic_source_filename(filename, frame)

Returns a dynamically computed source filename.

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

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

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

has_dynamic_source_filename()

Does this FileTracer have dynamic source filenames?

FileTracers can provide dynamically determined filenames 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().

Returns true if dynamic_source_filename() should be called to get dynamic source filenames.

line_number_range(frame)

Return 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.

source_filename()

The source filename for this file.

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

Returns the filename to credit with this execution.

class coverage.plugin.FileReporter(filename)

Support needed for files during the reporting phase.

flat_rootname()

A base for a flat filename to correspond to this file.

Useful for writing files about the code where you want all the files in the same directory, but need to differentiate same-named files from different directories.

For example, the file a/b/c.py will return ‘a_b_c_py’

You should not need to override this method.

should_be_python()

Does it seem like this file should contain Python?

This is used to decide if a file reported as part of the execution of a program was really likely to have contained Python in the first place.

source()

Return the source for the code, a Unicode string.

source_token_lines()

Return the ‘tokenized’ text for the code.