From 99babbfb21a792919e8751c79a9c86a7851e11c6 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Tue, 9 May 2023 04:46:42 -0400 Subject: docs: lean harder on [report] exclude_also. --- doc/config.rst | 31 ++++++++++++++----------------- doc/excluding.rst | 14 ++++++-------- doc/migrating.rst | 7 +++++++ 3 files changed, 27 insertions(+), 25 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index f81d7d00..0100d89e 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -79,10 +79,7 @@ Here's a sample configuration file:: [report] # Regexes for lines to exclude from consideration - exclude_lines = - # Have to re-enable the standard pragma - pragma: no cover - + exclude_also = # Don't complain about missing debug-only code: def __repr__ if self\.debug @@ -375,6 +372,19 @@ See :ref:`cmd_combine_remapping` and :ref:`source_glob` for more information. Settings common to many kinds of reporting. +.. _config_report_exclude_also: + +[report] exclude_also +..................... + +(multi-string) A list of regular expressions. This setting is similar to +:ref:`config_report_exclude_lines`: it specifies patterns for lines to exclude +from reporting. This setting is preferred, because it will preserve the +default exclude patterns instead of overwriting them. + +.. versionadded:: 7.2.0 + + .. _config_report_exclude_lines: [report] exclude_lines @@ -397,19 +407,6 @@ you'll exclude any line with three or more of any character. If you write ``pass``, you'll also exclude the line ``my_pass="foo"``, and so on. -.. _config_report_exclude_also: - -[report] exclude_also -..................... - -(multi-string) A list of regular expressions. This setting is similar to -:ref:`config_report_exclude_lines`: it specifies patterns for lines to exclude -from reporting. The difference is this setting will preserve the default -exclude patterns instead of overwriting them. - -.. versionadded:: 7.2.0 - - .. _config_report_fail_under: [report] fail_under diff --git a/doc/excluding.rst b/doc/excluding.rst index 4651e6bb..e9d28f15 100644 --- a/doc/excluding.rst +++ b/doc/excluding.rst @@ -80,14 +80,13 @@ debugging code, and are uninteresting to test themselves. You could exclude all of them by adding a regex to the exclusion list:: [report] - exclude_lines = + exclude_also = def __repr__ For example, here's a list of exclusions I've used:: [report] - exclude_lines = - pragma: no cover + exclude_also = def __repr__ if self.debug: if settings.DEBUG @@ -99,11 +98,10 @@ For example, here's a list of exclusions I've used:: class .*\bProtocol\): @(abc\.)?abstractmethod -Note that when using the ``exclude_lines`` option in a configuration file, you -are taking control of the entire list of regexes, so you need to re-specify the -default "pragma: no cover" match if you still want it to apply. The -``exclude_also`` option can be used instead to preserve the default -exclusions while adding new ones. +The :ref:`config_report_exclude_also` option adds regexes to the built-in +default list so that you can add your own exclusions. The older +:ref:`config_report_exclude_lines` option completely overwrites the list of +regexes. The regexes only have to match part of a line. Be careful not to over-match. A value of ``...`` will match any line with more than three characters in it. diff --git a/doc/migrating.rst b/doc/migrating.rst index 7a5e65df..996c19cb 100644 --- a/doc/migrating.rst +++ b/doc/migrating.rst @@ -27,3 +27,10 @@ Migrating from 6.x to 7.x - When remapping file paths with ``[paths]``, a path will be remapped only if the resulting path exists. Ensure that remapped ``[paths]`` exist when upgrading as this is now being enforced. + +- The :ref:`config_report_exclude_also` setting is new in 7.2.0. It adds + exclusion regexes while keeping the default built-in set. It's better than + the older :ref:`config_report_exclude_lines` setting, which overwrote the + entire list. Newer versions of coverage.py will be adding to the default set + of exclusions. Using ``exclude_also`` will let you benefit from those + updates. -- cgit v1.2.1