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. NOTE: You will see a warning when coverage starts:

    Coverage.py warning: Setting timid=True to support plugins.
    

    This means that coverage will run slower than it usually would. This limitation is part of the initial alpha release, it will be gone in the final version.

Plugin API

class coverage.plugin.CoveragePlugin(options)

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.

When the plugin is constructed, it will be passed a dictionary of plugin-specific options read from the .coveragerc configuration file. The base class stores these on the self.options attribute.

Parameters:options (dict) – The plugin-specific options read from the .coveragerc configuration file.
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.

Parameters:filename (str) – 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:the FileTracer object to use to trace filename, or None if this plugin cannot trace this file.
Return type:FileTracer
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.
Return type:boolean
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.

Parameters:frame – the call frame to examine.
Returns:a pair of line numbers, the start and end lines executed in the source, inclusive.
Return type:int, int
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’

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.