Add support for generating coverage reports for different Python versions and platforms

Author: domdfcoding

coverage_pyver_pragma/grammar.py

@@ -119,6 +119,7 @@
 #
 
 # stdlib
+import os
 import platform
 import sys
 
@@ -160,10 +161,14 @@
 # This ensures coverage.py records the correct coverage for these modules
 # when they are under test
 
-for module in [m for m in sys.modules if m.startswith("domdf_python_tools")]:
+for module in [m for m in sys.modules if m.startswith("domdf_python_tools")]:  # pragma: no cover (macOS)
 	if module in sys.modules:
 		del sys.modules[module]
 
+PYTHON_VERSION = os.environ.get("COV_PYTHON_VERSION", '.'.join(platform.python_version_tuple()[:2]))
+PLATFORM = os.environ.get("COV_PLATFORM", platform.system()).casefold()
+PYTHON_IMPLEMENTATION = os.environ.get("COV_PYTHON_IMPLEMENTATION", platform.python_implementation()).casefold()
+
 
 @prettify_docstrings
 class VersionTag(packaging.specifiers.SpecifierSet):
@@ -208,8 +213,7 @@ def __repr__(self) -> str:  # pragma: no cover
 		return f"<{self.__class__.__name__}({str(self)!r})>"
 
 	def __bool__(self) -> bool:
-		current_version = '.'.join(platform.python_version_tuple()[:2])
-		return current_version in self
+		return PYTHON_VERSION in self
 
 
 @prettify_docstrings
@@ -243,12 +247,10 @@ def __repr__(self) -> str:  # pragma: no cover
 		return f"<{self.__class__.__name__}({str(self)!r})>"
 
 	def __bool__(self) -> bool:
-		current_platform = platform.system().casefold()
-
-		if not current_platform:  # pragma: no cover
+		if not PLATFORM:  # pragma: no cover
 			return True
 
-		return current_platform == self.casefold()
+		return PLATFORM == self.casefold()
 
 
 @prettify_docstrings
@@ -280,7 +282,7 @@ def __repr__(self) -> str:  # pragma: no cover
 		return f"<{self.__class__.__name__}({str(self)!r})>"
 
 	def __bool__(self) -> bool:
-		return platform.python_implementation().casefold() == self.casefold()
+		return PYTHON_IMPLEMENTATION == self.casefold()
 
 
 @prettify_docstrings

doc-source/installation.rst

@@ -25,3 +25,64 @@ Alternatively you can put the configuration in the ``setup.cfg`` or ``tox.ini``
 	[coverage:run]
 	plugins =
 	    coverage_pyver_pragma
+
+
+Configuration
+-----------------
+
+.. versionadded:: 0.3.0
+
+When using Coverage.py's `reporting commands <https://coverage.readthedocs.io/en/coverage-5.5/cmd.html?highlight=report#coverage-summary-coverage-report>`_
+it may be desirable to generate a report for a different Python version / implementation / platform to the current one.
+For instance, you are generating a report from a .coverage file produced on PyPy 3.6 on Windows, but you are running CPython 3.8 on Linux.
+
+``coverage_pyver_pragma`` provides three environment variables which can be used to set the target version and platform.
+
+.. envvar:: COV_PYTHON_VERSION
+
+	Sets the Python version. Must be in the form :file:`{<major>}.{<minor>}`.
+
+	Defaults to the output of ``'.'.join(platform.python_version_tuple()[:2])``.
+
+	**Example:**
+
+	.. code-block:: bash
+
+		COV_PYTHON_VERSION=3.6 coverage report
+
+.. envvar:: COV_PLATFORM
+
+	Sets the Python platform. Must be a string which matches the output of :func:`platform.system`.
+
+	Defaults to the output of :func:`platform.system`.
+
+	**Example:**
+
+	.. code-block:: bash
+
+		COV_PLATFORM=Windows coverage report
+
+.. envvar:: COV_PYTHON_IMPLEMENTATION
+
+	Sets the Python implementation.
+	Must be a string which matches the output of :func:`platform.python_implementation`.
+
+	Defaults to the output of :func:`platform.python_implementation`.
+
+	**Example:**
+
+	.. code-block:: bash
+
+		COV_PYTHON_IMPLEMENTATION=PyPy coverage report
+
+If you generate your coverage reports through `tox <https://tox.readthedocs.io/en/latest/>`_
+you should configure `passenv <https://tox.readthedocs.io/en/latest/config.html?highlight=setenv#conf-passenv>`_
+to ensure the environment variables are passed through:
+
+.. code-block:: ini
+
+	[testenv]
+	passenv =
+	    COV_PYTHON_VERSION
+	    COV_PLATFORM
+	    COV_PYTHON_IMPLEMENTATION