New in version 4.0.
Coverage.py’s behavior can be extended with third-party 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.
To use a coverage.py plugin, you install it, and configure it. For this
example, let’s say there’s a Python package called
something that provides a
coverage.py plugin called
Install the plugin’s package as you would any other Python package:
pip install something
Configure coverage.py to use the plugin. You do this by editing (or creating) your .coveragerc file, as described in Configuration files. The
pluginssetting indicates your plugin. It’s a list of importable module names of plugins:
[run] plugins = something.plugin
If the plugin needs its own configuration, you can add those settings in the .coveragerc file in a section named for the plugin:
[something.plugin] option1 = True option2 = abc.foo
Check the documentation for the plugin to see if it takes any options, and what they are.
Run your tests as you usually would.
Base class for coverage.py plugins.
To write a coverage.py plugin, create a module with a subclass of
CoveragePlugin. You can 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, with attributes starting 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())
The reg.add_file_tracer method takes an instance of your plugin. If your plugin takes options, the options argument is a dictionary of your plugin’s options from the .coveragerc file.
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.
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
FileTracerobject. 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.
FileTracerobject to use to trace filename, or None if this plugin cannot trace this file.
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).
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.
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
Returns the source filename for this frame, or None if this frame shouldn’t be measured.
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
Returns true if
dynamic_source_filename()should be called to get dynamic source filenames.
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.
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.
Support needed for files during the reporting phase.
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.
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.
Return the source for the code, a Unicode string.
Return the ‘tokenized’ text for the code.