covdefaults

Warnings

• gotcha Overriding default options in coverage.py configuration files (e.g., `pyproject.toml`, `.coveragerc`) behaves differently for various settings. Some options, like `run:source` and `report:fail_under`, will entirely prevent `covdefaults` from applying its default if you set them manually. Other options, like `run:omit` and `report:exclude_lines`, will extend the defaults provided by `covdefaults` rather than overwriting them.
  Fix: Always consult the `covdefaults` documentation or source for the exact behavior of specific settings when overriding. Test your coverage configuration thoroughly to ensure the desired defaults are applied or overridden correctly.
• gotcha The `[covdefaults] subtract_omit` option, when used in your configuration, removes specific patterns from `covdefaults`'s default `omit` list. Users sometimes mistakenly believe it adds to the `omit` list, leading to files being included in coverage that they intended to exclude.
  Fix: Use `[covdefaults] subtract_omit` only when you explicitly want to un-omit a file that `covdefaults` would normally omit. To add new patterns to the `omit` list, use the standard `[run] omit` option in your coverage configuration.
• gotcha When using `pytest-cov`, its command-line options (e.g., `--cov=something`, `--cov-branch`) can override the `source` and `branch` settings provided by `coverage.py` or `covdefaults`. This can lead to unexpected coverage behavior if not managed carefully.
  Fix: For consistent coverage behavior, prefer to define your `coverage.py` configuration (including `covdefaults` activation and overrides) in a configuration file (like `pyproject.toml`) rather than relying heavily on `pytest-cov` command-line arguments that duplicate configuration file settings. This ensures a single source of truth for your coverage setup.
• gotcha Coverage.py, and by extension `covdefaults`, respects a specific order of precedence for configuration files: `.coveragerc`, `.coveragerc.toml`, `setup.cfg`, `tox.ini`, and `pyproject.toml`. If multiple files are present, only the first one found that contains `coverage.py` settings will be used. This can cause confusion if you expect settings from one file to be merged or to override settings in another.
  Fix: Consolidate your coverage configuration into a single file, preferably `pyproject.toml`, to avoid ambiguity. If using multiple files is unavoidable, be mindful of the precedence order and clearly document where your primary coverage settings reside.

Install

• pip install covdefaults Install covdefaults

Imports

• covdefaults

  This library is a coverage.py plugin and is configured via coverage's configuration files (e.g., pyproject.toml, .coveragerc), not directly imported into Python code.

  covdefaults is enabled by adding its name to the `plugins` list under the `[run]` section of your coverage configuration.

Quickstart

To enable covdefaults, add it to the `plugins` list in your `pyproject.toml` (or `.coveragerc`, `setup.cfg`, `tox.ini`). This example assumes a Poetry project with pytest and coverage installed. covdefaults will then apply its default settings for coverage measurement and reporting. You can override specific defaults by explicitly setting them in your coverage configuration.

pyproject.toml

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = ">=3.7,<4.0"
coverage = {extras = ["toml"], version = ">=6.0.2"}

[tool.poetry.group.dev.dependencies]
pip = "*"
pytest = "*"
covdefaults = "*"

[tool.coverage.run]
plugins = ["covdefaults"]

# Optional: Customize or override specific defaults
# source = ["."]
# omit = [".venv/*"]

# Optional: Customize reporting
# [tool.coverage.report]
# fail_under = 90