{"id":8910,"library":"coverage-conditional-plugin","title":"Coverage Conditional Plugin","description":"Coverage Conditional Plugin allows defining conditional coverage rules based on any Python expressions or environment variables. It helps to omit specific lines, functions, or entire modules from coverage reports based on custom logic. As of version 0.9.0, it officially supports Python 3.7+ and Coverage.py 7.x, enabling highly customizable control over what gets included in your coverage reports.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/wemake-services/coverage-conditional-plugin","tags":["coverage","testing","development","tooling","ci/cd","code quality","plugin"],"install":[{"cmd":"pip install coverage-conditional-plugin coverage","lang":"bash","label":"Install with Coverage.py"}],"dependencies":[{"reason":"This plugin extends Coverage.py and is strictly dependent on it. Version 7.x is officially supported with plugin version >= 0.8.0.","package":"coverage","optional":false},{"reason":"Used internally for version parsing and compatibility checks (added in 0.3.1).","package":"packaging","optional":false}],"imports":[{"note":"This function allows programmatic inspection of the plugin's environment and rules, primarily for debugging or advanced integration, not for standard configuration.","symbol":"get_env_info","correct":"from coverage_conditional_plugin.plugin import get_env_info"}],"quickstart":{"code":"import os\nimport sys\nfrom coverage_conditional_plugin.plugin import get_env_info\n\n# --- Example of programmatic usage (less common, for debugging) ---\nprint(\"\\n--- Plugin Environment Info ---\")\nprint(get_env_info())\nprint(\"--------------------------------\\n\")\n\n# --- Typical usage: configure via pyproject.toml or .coveragerc ---\n# Create a `pyproject.toml` file in your project root with this content:\n#\n# [tool.coverage.run]\n# plugins = [\"coverage_conditional_plugin\"]\n#\n# [tool.coverage.coverage_conditional_plugin]\n# # Example rule 1: omit lines if Python version is below 3.8\n# rules = [\n#   \"if sys.version_info < (3, 8): omit\",\n#   # Example rule 2: omit lines starting with 'def debug_feature' if env var is 'true'\n#   \"if os.getenv('SKIP_DEBUG_FEATURES', 'false') == 'true': exclude_lines_starting_with('def debug_feature')\",\n# ]\n#\n# Create a dummy Python file (e.g., `my_app.py`) to demonstrate:\n# def standard_feature():\n#     print(\"This is always covered.\")\n#\n# def debug_feature():\n#     print(\"This is a debug-only function.\") # Will be excluded if SKIP_DEBUG_FEATURES is 'true'\n#\n# if sys.version_info >= (3, 8):\n#     print(\"Running on Python 3.8 or newer.\") # This line would be omitted if Python < 3.8\n# else:\n#     print(\"Running on Python older than 3.8.\")\n#\n# standard_feature()\n# debug_feature()\n\n# --- To run this example from your terminal ---\n# 1. Make sure you have `pyproject.toml` and `my_app.py` in your current directory.\n# 2. Run coverage normally (all lines covered, assuming Python >= 3.8):\n#    $ coverage run my_app.py\n#    $ coverage report -m\n#\n# 3. Run coverage with an environment variable rule activated:\n#    $ SKIP_DEBUG_FEATURES=true coverage run my_app.py\n#    $ coverage report -m\n#    (Expected: `debug_feature` lines are now marked as omitted/excluded)\n\n# Note: The Python code in this block is for demonstration and `get_env_info()` execution.\n# The primary interaction is via `coverage.py` configuration and shell commands.","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.8.0"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.6.0"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"<0.3.0"},{"fix":"Upgrade to `coverage-conditional-plugin>=0.9.0` to utilize the module-level `omit` configuration section.","message":"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.","severity":"gotcha","affected_versions":"<0.9.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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]`.","cause":"The `coverage-conditional-plugin` is not correctly registered within your `coverage.py` configuration, or there's an installation issue.","error":"coverage.plugin.PluginConfigError: Plugin 'coverage_conditional_plugin' could not be loaded"},{"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`.","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).","error":"RuntimeWarning: For coverage-conditional-plugin, the current version of coverage is X.Y.Z, but this plugin expects coverage >=7.0.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).","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).","error":"SyntaxError: invalid syntax (or similar Python version-related error during plugin loading)"}]}