eric: comparison eric6/DebugClients/Python/coverage/plugin.py

-:f99d60d6b59b
+:2602857055c5
+# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+# For details: https://bitbucket.org/ned/coveragepy/src/default/NOTICE.txt
+"""
+.. versionadded:: 4.0
+Plug-in interfaces for coverage.py.
+Coverage.py supports a few different kinds of plug-ins that change its
+behavior:
+* File tracers implement tracing of non-Python file types.
+* Configurers add custom configuration, using Python code to change the
+configuration.
+To write a coverage.py plug-in, create a module with a subclass of
+:class:`~coverage.CoveragePlugin`.  You will override methods in your class to
+participate in various aspects of coverage.py's processing.
+Different types of plug-ins have to override different methods.
+Any plug-in can optionally implement :meth:`~coverage.CoveragePlugin.sys_info`
+to provide debugging information about their operation.
+Your module must also contain a ``coverage_init`` function that registers an
+instance of your plug-in class::
+import coverage
+class MyPlugin(coverage.CoveragePlugin):
+...
+def coverage_init(reg, options):
+reg.add_file_tracer(MyPlugin())
+You use the `reg` parameter passed to your ``coverage_init`` function to
+register your plug-in object.  The registration method you call depends on
+what kind of plug-in it is.
+If your plug-in takes options, the `options` parameter is a dictionary of your
+plug-in's options from the coverage.py configuration file.  Use them however
+you want to configure your object before registering it.
+Coverage.py will store its own information on your plug-in object, using
+attributes whose names start with ``_coverage_``.  Don't be startled.
+.. warning::
+Plug-ins are imported by coverage.py before it begins measuring code.
+If you write a plugin in your own project, it might import your product
+code before coverage.py can start measuring.  This can result in your
+own code being reported as missing.
+One solution is to put your plugins in your project tree, but not in
+your importable Python package.
+File Tracers
+============
+File tracers implement measurement support for non-Python files.  File tracers
+implement the :meth:`~coverage.CoveragePlugin.file_tracer` method to claim
+files and the :meth:`~coverage.CoveragePlugin.file_reporter` method to report
+on those files.
+In your ``coverage_init`` function, use the ``add_file_tracer`` method to
+register your file tracer.
+Configurers
+===========
+.. versionadded:: 4.5
+Configurers modify the configuration of coverage.py during start-up.
+Configurers implement the :meth:`~coverage.CoveragePlugin.configure` method to
+change the configuration.
+In your ``coverage_init`` function, use the ``add_configurer`` method to
+register your configurer.
+"""
+from coverage import files
+from coverage.misc import contract, _needs_to_implement
+class CoveragePlugin(object):
+"""Base class for coverage.py plug-ins."""
+def file_tracer(self, filename):        # pylint: disable=unused-argument
+"""Get a :class:`FileTracer` object for a file.
+Plug-in type: file tracer.
+Every Python source file is offered to your plug-in to give it a chance
+to take responsibility for tracing the file.  If your plug-in can
+handle the file, then return a :class:`FileTracer` object.  Otherwise
+return None.
+There is no way to register your plug-in for particular files.
+Instead, this method is invoked for all files, and the plug-in 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 plug-in.
+The file name will be a Python file being executed.  There are two
+broad categories of behavior for a plug-in, depending on the kind of
+files your plug-in supports:
+* Static file names: each of your original source files has been
+converted into a distinct Python file.  Your plug-in 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 plug-in implements
+:meth:`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 :class:`FileTracer` object to use to trace `filename`, or
+None if this plug-in cannot trace this file.
+"""
+return None
+def file_reporter(self, filename):      # pylint: disable=unused-argument
+"""Get the :class:`FileReporter` class to use for a file.
+Plug-in type: file tracer.
+This will only be invoked if `filename` returns non-None from
+:meth:`file_tracer`.  It's an error to return None from this method.
+Returns a :class:`FileReporter` object to use to report on `filename`.
+"""
+_needs_to_implement(self, "file_reporter")
+def find_executable_files(self, src_dir):       # pylint: disable=unused-argument
+"""Yield all of the executable files in `src_dir`, recursively.
+Plug-in type: file tracer.
+Executability is a plug-in-specific property, but generally means files
+which would have been considered for coverage analysis, had they been
+included automatically.
+Returns or yields a sequence of strings, the paths to files that could
+have been executed, including files that had been executed.
+"""
+return []
+def configure(self, config):
+"""Modify the configuration of coverage.py.
+Plug-in type: configurer.
+This method is called during coverage.py start-up, to give your plug-in
+a chance to change the configuration.  The `config` parameter is an
+object with :meth:`~coverage.Coverage.get_option` and
+:meth:`~coverage.Coverage.set_option` methods.  Do not call any other
+methods on the `config` object.
+"""
+pass
+def sys_info(self):
+"""Get a list of information useful for debugging.
+Plug-in type: any.
+This method will be invoked for ``--debug=sys``.  Your
+plug-in can return any information it wants to be displayed.
+Returns a list of pairs: `[(name, value), ...]`.
+"""
+return []
+class FileTracer(object):
+"""Support needed for files during the execution phase.
+File tracer plug-ins implement subclasses of FileTracer to return from
+their :meth:`~CoveragePlugin.file_tracer` method.
+You may construct this object from :meth:`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
+:meth:`CoveragePlugin.file_tracer` method.
+See :ref:`howitworks` for details of the different coverage.py phases.
+"""
+def source_filename(self):
+"""The source file name for this file.
+This may be any file name you like.  A key responsibility of a plug-in
+is to own the mapping from Python execution back to whatever source
+file name was originally the source of the code.
+See :meth:`CoveragePlugin.file_tracer` for details about static and
+dynamic file names.
+Returns the file name to credit with this execution.
+"""
+_needs_to_implement(self, "source_filename")
+def has_dynamic_source_filename(self):
+"""Does this FileTracer have dynamic source file names?
+FileTracers can provide dynamically determined file names by
+implementing :meth:`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
+:meth:`dynamic_source_filename`.
+See :meth:`CoveragePlugin.file_tracer` for details about static and
+dynamic file names.
+Returns True if :meth:`dynamic_source_filename` should be called to get
+dynamic source file names.
+"""
+return False
+def dynamic_source_filename(self, filename, frame):     # pylint: disable=unused-argument
+"""Get a dynamically computed source file name.
+Some plug-ins need to compute the source file name dynamically for each
+frame.
+This function will not be invoked if
+:meth:`has_dynamic_source_filename` returns False.
+Returns the source file name for this frame, or None if this frame
+shouldn't be measured.
+"""
+return None
+def line_number_range(self, 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.
+"""
+lineno = frame.f_lineno
+return lineno, lineno
+class FileReporter(object):
+"""Support needed for files during the analysis and reporting phases.
+File tracer plug-ins implement a subclass of `FileReporter`, and return
+instances from their :meth:`CoveragePlugin.file_reporter` method.
+There are many methods here, but only :meth:`lines` is required, to provide
+the set of executable lines in the file.
+See :ref:`howitworks` for details of the different coverage.py phases.
+"""
+def __init__(self, filename):
+"""Simple initialization of a `FileReporter`.
+The `filename` argument is the path to the file being reported.  This
+will be available as the `.filename` attribute on the object.  Other
+method implementations on this base class rely on this attribute.
+"""
+self.filename = filename
+def __repr__(self):
+return "<{0.__class__.__name__} filename={0.filename!r}>".format(self)
+def relative_filename(self):
+"""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.
+"""
+return files.relative_filename(self.filename)
+@contract(returns='unicode')
+def source(self):
+"""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.
+"""
+with open(self.filename, "rb") as f:
+return f.read().decode("utf8")
+def lines(self):
+"""Get the executable lines in this file.
+Your plug-in 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.
+"""
+_needs_to_implement(self, "lines")
+def excluded_lines(self):
+"""Get the excluded executable lines in this file.
+Your plug-in 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.
+"""
+return set()
+def translate_lines(self, 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 plug-in 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.
+"""
+return set(lines)
+def arcs(self):
+"""Get the executable arcs in this file.
+To support branch coverage, your plug-in 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.
+"""
+return set()
+def no_branch_lines(self):
+"""Get the lines excused from branch coverage in this file.
+Your plug-in 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.
+"""
+return set()
+def translate_arcs(self, arcs):
+"""Translate recorded arcs into reported arcs.
+Similar to :meth:`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.
+"""
+return arcs
+def exit_counts(self):
+"""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 plug-in...
+"""
+return {}
+def missing_arc_description(self, start, end, executed_arcs=None):     # pylint: disable=unused-argument
+"""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}".
+"""
+return "Line {start} didn't jump to line {end}".format(start=start, end=end)
+def source_token_lines(self):
+"""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'``.
+"""
+for line in self.source().splitlines():
+yield [('txt', line)]
+# Annoying comparison operators. Py3k wants __lt__ etc, and Py2k needs all
+# of them defined.
+def __eq__(self, other):
+return isinstance(other, FileReporter) and self.filename == other.filename
+def __ne__(self, other):
+return not (self == other)
+def __lt__(self, other):
+return self.filename < other.filename
+def __le__(self, other):
+return self.filename <= other.filename
+def __gt__(self, other):
+return self.filename > other.filename
+def __ge__(self, other):
+return self.filename >= other.filename
+__hash__ = None     # This object doesn't need to be hashed.

Mercurial Repositories > eric / file comparison

comparison: eric6/DebugClients/Python/coverage/plugin.py

eric6/DebugClients/Python/coverage/plugin.py