doc/source.rst

   1 .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
   2 .. For details: https://bitbucket.org/ned/coveragepy/src/default/NOTICE.txt
   3
   4 .. _source:
   5
   6 =======================
   7 Specifying source files
   8 =======================
   9
  10 .. :history: 20100725T172000, new in 3.4
  11
  12
  13 When coverage.py is running your program and measuring its execution, it needs
  14 to know what code to measure and what code not to.  Measurement imposes a speed
  15 penalty, and the collected data must be stored in memory and then on disk.
  16 More importantly, when reviewing your coverage reports, you don't want to be
  17 distracted with modules that aren't your concern.
  18
  19 Coverage.py has a number of ways you can focus it in on the code you care
  20 about.
  21
  22
  23 .. _source_execution:
  24
  25 Execution
  26 ---------
  27
  28 When running your code, the ``coverage run`` command will by default measure
  29 all code, unless it is part of the Python standard library.
  30
  31 You can specify source to measure with the ``--source`` command-line switch, or
  32 the ``[run] source`` configuration value.  The value is a comma- or
  33 newline-separated list of directories or package names.  If specified, only
  34 source inside these directories or packages will be measured.  Specifying the
  35 source option also enables coverage.py to report on unexecuted files, since it
  36 can search the source tree for files that haven't been measured at all.  Only
  37 importable files (ones at the root of the tree, or in directories with a
  38 ``__init__.py`` file) will be considered, and files with unusual punctuation in
  39 their names will be skipped (they are assumed to be scratch files written by
  40 text editors).
  41
  42 You can further fine-tune coverage.py's attention with the ``--include`` and
  43 ``--omit`` switches (or ``[run] include`` and ``[run] omit`` configuration
  44 values). ``--include`` is a list of file name patterns. If specified, only
  45 files matching those patterns will be measured. ``--omit`` is also a list of
  46 file name patterns, specifying files not to measure.  If both ``include`` and
  47 ``omit`` are specified, first the set of files is reduced to only those that
  48 match the include patterns, then any files that match the omit pattern are
  49 removed from the set.
  50
  51 The ``include`` and ``omit`` file name patterns follow typical shell syntax:
  52 ``*`` matches any number of characters and ``?`` matches a single character.
  53 Patterns that start with a wildcard character are used as-is, other patterns
  54 are interpreted relative to the current directory::
  55
  56     [run]
  57     omit =
  58         # omit anything in a .local directory anywhere
  59         */.local/*
  60         # omit everything in /usr
  61         /usr/*
  62         # omit this single file
  63         utils/tirefire.py
  64
  65 The ``source``, ``include``, and ``omit`` values all work together to determine
  66 the source that will be measured.
  67
  68
  69 .. _source_reporting:
  70
  71 Reporting
  72 ---------
  73
  74 Once your program is measured, you can specify the source files you want
  75 reported.  Usually you want to see all the code that was measured, but if you
  76 are measuring a large project, you may want to get reports for just certain
  77 parts.
  78
  79 The report commands (``report``, ``html``, ``annotate``, and ``xml``) all take
  80 optional ``modules`` arguments, and ``--include`` and ``--omit`` switches. The
  81 ``modules`` arguments specify particular modules to report on.  The ``include``
  82 and ``omit`` values are lists of file name patterns, just as with the ``run``
  83 command.
  84
  85 Remember that the reporting commands can only report on the data that has been
  86 collected, so the data you're looking for may not be in the data available for
  87 reporting.
  88
  89 Note that these are ways of specifying files to measure.  You can also exclude
  90 individual source lines.  See :ref:`excluding` for details.