Documentation for static contexts

Author: nedbat

CHANGES.rst

@@ -17,6 +17,11 @@ Change history for Coverage.py
 Unreleased
 ----------
 
+- Context support: static contexts let you specify a label for a coverage run,
+  which is recorded in the data, and retained when you combine files.  See
+  :ref:`contexts` for more information.  Currently, only static contexts are
+  supported, with no reporting features.
+
 - Environment variable substitution in configuration files now supports two
   syntaxes for controlling the behavior of undefined variables: if ``VARNAME``
   is not defined, ``${VARNAME?}`` will raise an error, and ``${VARNAME-default

README.rst

@@ -19,7 +19,8 @@ library to determine which lines are executable, and which have been executed.
 
 Coverage.py runs on many versions of Python:
 
-* CPython 2.7 and 3.4 through 3.7.
+* CPython 2.7.
+* CPython 3.4 through 3.7.
 * PyPy2 6.0 and PyPy3 6.0.
 * Jython 2.7.1, though not for reporting.
 * IronPython 2.7.7, though not for reporting.
@@ -31,7 +32,8 @@ Documentation is on `Read the Docs`_.  Code repository and issue tracker are on
 .. _GitHub: https://github.com/nedbat/coveragepy
 
 
-**New in 5.0:** SQLite data storage, dropped support for Python 2.6 and 3.3.
+**New in 5.0:** SQLite data storage, contexts, dropped support for Python 2.6
+and 3.3.
 
 New in 4.5: Configurator plug-ins.
 

doc/cmd.rst

@@ -69,7 +69,7 @@ control, and can provide options that other invocation techniques (like test
 runner plugins) may not offer. See :ref:`config` for more details.
 
 
-.. _cmd_execution:
+.. _cmd_run:
 
 Execution
 ---------
@@ -118,6 +118,10 @@ configuration file for all options.
 .. _gevent: http://www.gevent.org/
 .. _eventlet: http://eventlet.net/
 
+You can specify a :ref:`static context <contexts>` for a coverage run with
+``--context``.  This can be any label you want, and will be recorded with the
+data.  See :ref:`contexts` for more information.
+
 By default, coverage.py does not measure code installed with the Python
 interpreter, for example, the standard library. If you want to measure that
 code as well as your own, add the ``-L`` (or ``--pylib``) flag.

doc/config.rst

@@ -132,6 +132,11 @@ Before version 4.2, this option only accepted a single string.
 
 .. versionadded:: 4.0
 
+``context`` (string): the static context to record for this coverage run. See
+:ref:`contexts` for more information
+
+.. versionadded:: 5.0
+
 ``data_file`` (string, default ".coverage"): the name of the data file to use
 for storing or reporting coverage. This value can include a path to another
 directory.

doc/contexts.rst

@@ -0,0 +1,51 @@
+.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
+
+.. _contexts:
+
+====================
+Measurement Contexts
+====================
+
+.. :history: 20180921T085400, new for 5.0
+
+.. versionadded:: 5.0
+
+Coverage.py measures whether code was run, but it can also record the context
+in which it was run.  This can provide more information to help you understand
+the behavior of your tests.
+
+There are two kinds of context: static and dynamic.  Static contexts are fixed
+for an entire run, and are set explicitly with an option.
+
+Dynamic contexts are coming soon.
+
+
+Static contexts
+---------------
+
+A static context is set by an option when you run coverage.py.  The value is
+fixed for the duration of a run.  They can be any text you like, for example,
+"python3" or "with_numpy".  The context is recorded with the data.
+
+When you :ref:`combine multiple data files <cmd_combining>` together, they can
+have differing contexts.  All of the information is retained, so that the
+different contexts are correctly recorded in the combined file.
+
+A static context is specified with the ``--context=CONTEXT`` option to
+:ref:`coverage run <cmd_run>`.
+
+
+Dynamic contexts
+----------------
+
+Not implemented yet.
+
+
+Context reporting
+-----------------
+
+There is currently no support for using contexts during reporting.  I'm
+interested to `hear your ideas`__ for what would be useful.
+
+__  https://nedbatchelder.com/site/aboutned.html

doc/index.rst

@@ -206,6 +206,7 @@ More information
     excluding
     branch
     subprocess
+    contexts
     api
     howitworks
     plugins