Coverage Conditional Plugin

Common errors

• coverage.plugin.PluginConfigError: Plugin 'coverage_conditional_plugin' could not be loaded

  cause The `coverage-conditional-plugin` is not correctly registered within your `coverage.py` configuration, or there's an installation issue.
  fix Ensure the plugin is correctly listed in the `plugins` section of your `coverage.py` configuration. For `pyproject.toml`, add `plugins = ["coverage_conditional_plugin"]` under `[tool.coverage.run]`.

• RuntimeWarning: For coverage-conditional-plugin, the current version of coverage is X.Y.Z, but this plugin expects coverage >=7.0.0.

  cause Your installed `coverage.py` version is incompatible with the `coverage-conditional-plugin` version you are using (often seen when the plugin expects 7.x but 6.x is installed).
  fix Upgrade `coverage.py` to version 7.x (`pip install "coverage>=7.0,<8.0"`) or downgrade `coverage-conditional-plugin` to a version compatible with your current `coverage.py`.

• SyntaxError: invalid syntax (or similar Python version-related error during plugin loading)

  cause You are attempting to use `coverage-conditional-plugin` on a Python version it no longer supports (e.g., Python 3.6 with plugin version >=0.6.0).
  fix Upgrade your Python environment to 3.7 or newer, or install an older version of the plugin compatible with your Python version (e.g., `pip install coverage-conditional-plugin==0.5.0` for Python 3.6).

Warnings

• breaking Version 0.9.0 and newer of the plugin officially support only `coverage.py` version 7.x. Using plugin versions >=0.8.0 with `coverage.py` 6.x or older versions may lead to compatibility issues or errors.
  Fix: Ensure your `coverage.py` version matches the plugin's requirements. For `coverage-conditional-plugin>=0.8.0`, upgrade `coverage.py` to `7.x` (`pip install "coverage>=7.0,<8.0"`). For older plugin versions, consider pinning `coverage.py` 6.x or upgrading the plugin.
• breaking Support for Python 3.6 was dropped in version 0.6.0. If you are using Python 3.6, you must use an older version of the plugin.
  Fix: Upgrade your Python environment to 3.7 or newer, or if you must remain on Python 3.6, pin `coverage-conditional-plugin<0.6.0`.
• gotcha The ability to configure the plugin via `pyproject.toml` (under `[tool.coverage.coverage_conditional_plugin]`) was introduced in version 0.3.0. Older versions (<0.3.0) exclusively supported configuration through `.coveragerc`.
  Fix: For modern projects, use `pyproject.toml` for configuration. If working with an older plugin version, ensure your configuration is correctly placed in a `.coveragerc` file.
• gotcha The `omit` feature, which allows you to omit entire modules from coverage directly via the configuration file (e.g., `[tool.coverage.coverage_conditional_plugin.omit]`), was added in version 0.9.0.
  Fix: Upgrade to `coverage-conditional-plugin>=0.9.0` to utilize the module-level `omit` configuration section.

Install

• pip install coverage-conditional-plugin coverage Install with Coverage.py

Imports

• get_env_info

  from coverage_conditional_plugin.plugin import get_env_info

  This function allows programmatic inspection of the plugin's environment and rules, primarily for debugging or advanced integration, not for standard configuration.

Quickstart

To use the plugin, you must configure it within your `coverage.py` settings, typically in `pyproject.toml` or `.coveragerc`. Define `rules` as Python expressions that determine when lines or blocks of code should be omitted from coverage reports. These rules can reference `os.getenv`, `sys.version_info`, and other global Python context variables.

import os
import sys
from coverage_conditional_plugin.plugin import get_env_info

# --- Example of programmatic usage (less common, for debugging) ---
print("\n--- Plugin Environment Info ---")
print(get_env_info())
print("--------------------------------\n")

# --- Typical usage: configure via pyproject.toml or .coveragerc ---
# Create a `pyproject.toml` file in your project root with this content:
#
# [tool.coverage.run]
# plugins = ["coverage_conditional_plugin"]
#
# [tool.coverage.coverage_conditional_plugin]
# # Example rule 1: omit lines if Python version is below 3.8
# rules = [
#   "if sys.version_info < (3, 8): omit",
#   # Example rule 2: omit lines starting with 'def debug_feature' if env var is 'true'
#   "if os.getenv('SKIP_DEBUG_FEATURES', 'false') == 'true': exclude_lines_starting_with('def debug_feature')",
# ]
#
# Create a dummy Python file (e.g., `my_app.py`) to demonstrate:
# def standard_feature():
#     print("This is always covered.")
#
# def debug_feature():
#     print("This is a debug-only function.") # Will be excluded if SKIP_DEBUG_FEATURES is 'true'
#
# if sys.version_info >= (3, 8):
#     print("Running on Python 3.8 or newer.") # This line would be omitted if Python < 3.8
# else:
#     print("Running on Python older than 3.8.")
#
# standard_feature()
# debug_feature()

# --- To run this example from your terminal ---
# 1. Make sure you have `pyproject.toml` and `my_app.py` in your current directory.
# 2. Run coverage normally (all lines covered, assuming Python >= 3.8):
#    $ coverage run my_app.py
#    $ coverage report -m
#
# 3. Run coverage with an environment variable rule activated:
#    $ SKIP_DEBUG_FEATURES=true coverage run my_app.py
#    $ coverage report -m
#    (Expected: `debug_feature` lines are now marked as omitted/excluded)

# Note: The Python code in this block is for demonstration and `get_env_info()` execution.
# The primary interaction is via `coverage.py` configuration and shell commands.