Add support for .slipcoverrc

Adds a coverage.py-style INI config file alongside the existing
[tool.slipcover] table in pyproject.toml.

Keys are read from [run] and [report] and merged into one flat set; the
split mirrors coverage.py's but isn't enforced, since SlipCover's options
don't divide cleanly between collection and reporting. Keys may be spelled
with hyphens or underscores. Booleans accept configparser's usual states,
and source/omit accept either a comma-separated string or one entry per
line. Values are read without interpolation, so a literal % needs no
escaping. Only [run] and [report] are read; any other section, [DEFAULT]
included, warns and is ignored.

Both files are read when both exist and settings merge key by key: a key
set in .slipcoverrc overrides the same key in [tool.slipcover], while keys
it doesn't mention keep their pyproject.toml values. Letting one file
replace the other wholesale would mean an rc file setting a single key
silently discarded the rest of the configuration. Command-line arguments
continue to take precedence over both.

--rcfile PATH selects a specific file instead of searching for one; a path
that doesn't exist is an error rather than a silent fallback. Discovery
otherwise reuses the walk pyproject.toml already used, so the two files
are found independently.

Diagnostics name the file actually in play and the key at fault, which
matters more here than for TOML: every INI value arrives as a string, so a
mistyped number is the ordinary failure mode rather than an unusual one.
Malformed files produce a clean error rather than a traceback.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: ronaldorcampos

README.md

@@ -116,11 +116,54 @@ xml-package-depth = 3
 
 Most command-line flags have a matching key (use hyphens, as shown above);
 `source` and `omit` also accept a TOML array instead of a single
-comma-separated string. `--merge`, `-m`/module, the script argument, `--version`,
-and `--help` are per-invocation choices rather than settings, so they aren't
-configurable this way. Command-line arguments always take precedence over
+comma-separated string. `--merge`, `-m`/module, the script argument, `--rcfile`,
+`--version`, and `--help` are per-invocation choices rather than settings, so
+they aren't configurable this way. Command-line arguments always take precedence over
 values in `pyproject.toml`, so you can override any setting on a per-run basis.
 
+### Configuration via `.slipcoverrc`
+If you prefer coverage.py's INI style, you can instead put the same settings in
+a `.slipcoverrc` file, which SlipCover discovers the same way it discovers
+`pyproject.toml`.
+
+```ini
+[run]
+branch = true
+source = src
+    lib
+omit = tests/*
+immediate = false
+threshold = 75
+
+[report]
+fail-under = 80.0
+json = true
+xml = false
+pretty-print = true
+skip-covered = true
+out = coverage.json
+missing-width = 120
+xml-package-depth = 3
+```
+
+Keys may be written with either hyphens or underscores (`fail-under` and
+`fail_under` both work), though giving the same key both spellings within one
+section is an error. Keys may appear in either section — the split between
+`[run]` and `[report]` mirrors coverage.py's, but SlipCover doesn't enforce it.
+Only those two sections are read; any other, including `[DEFAULT]`, is reported
+as unknown and ignored.
+Booleans accept `true`/`false`, `yes`/`no`, `on`/`off` and `1`/`0`; `source` and
+`omit` accept either a comma-separated string or one entry per line.
+
+Use `--rcfile PATH` to point at a specific file instead of searching for one.
+
+Both files are read when both exist, and settings are merged key by key: a key
+set in `.slipcoverrc` overrides the same key in `[tool.slipcover]`, while keys
+the rc file doesn't mention keep their `pyproject.toml` values. Command-line
+arguments still take precedence over both. The two files are searched for
+independently, so a `.slipcoverrc` found further up the directory tree still
+overrides a `pyproject.toml` in the current directory.
+
 ## Usage example
 ```console
 $ python3 -m slipcover -m pytest

src/slipcover/__main__.py

@@ -187,7 +187,8 @@ def __call__(self, parser, namespace, values, option_string=None):
 
 def main():
     import argparse
-    from slipcover.config import read_config, apply_config
+    import configparser
+    from slipcover.config import find_pyproject, find_rcfile, read_config, read_rcfile, apply_config
 
     #
     # The intended usage is:
@@ -219,6 +220,8 @@ def main():
     ap.add_argument('--threshold', type=int, default=50, metavar="T",
                     help="threshold for de-instrumentation (if not immediate)")
     ap.add_argument('--missing-width', type=int, default=80, metavar="WIDTH", help="maximum width for `missing' column")
+    ap.add_argument('--rcfile', type=Path, metavar="PATH",
+                    help="read configuration from this file instead of searching for .slipcoverrc")
 
     # intended for slipcover development only
     ap.add_argument('--silent', action='store_true', help=argparse.SUPPRESS)
@@ -251,13 +254,31 @@ def main():
     else:
         args = ap.parse_args(sys.argv[1:])
 
-    # Apply [tool.slipcover] from pyproject.toml; CLI flags take precedence
+    # Apply [tool.slipcover] from pyproject.toml, then .slipcoverrc on top, so
+    # that a key set in both is taken from the rc file; CLI flags beat either.
+    # Applying per key rather than letting one file replace the other keeps an
+    # rc file that sets a single key from discarding the rest of pyproject.toml.
+    if args.rcfile is not None and not args.rcfile.is_file():
+        print(f"slipcover: no such file: {args.rcfile}", file=sys.stderr)
+        return 1
+
+    rcfile = args.rcfile if args.rcfile is not None else find_rcfile()
+    pyproject = find_pyproject()
+
+    config_file = pyproject
     try:
-        config = read_config()
-        if config:
-            apply_config(config, args, explicit_args)
-    except (ValueError, TypeError) as e:
-        print(f"slipcover: error in pyproject.toml configuration: {e}", file=sys.stderr)
+        if pyproject is not None:
+            config = read_config(pyproject)
+            if config:
+                apply_config(config, args, explicit_args, source="[tool.slipcover]")
+
+        if rcfile is not None:
+            config_file = rcfile
+            config = read_rcfile(rcfile)
+            if config:
+                apply_config(config, args, explicit_args, source=str(rcfile))
+    except (ValueError, TypeError, configparser.Error) as e:
+        print(f"slipcover: error in {config_file} configuration: {e}", file=sys.stderr)
         return 1
 
 

src/slipcover/config.py

@@ -1,5 +1,6 @@
-"""Read and apply [tool.slipcover] configuration from pyproject.toml."""
+"""Read and apply slipcover configuration from .slipcoverrc or pyproject.toml."""
 
+import configparser
 from pathlib import Path
 
 try:
@@ -14,9 +15,15 @@
 # Maximum number of parent directories to walk up from the start.
 _MAX_WALK = 3
 
+_RCFILE_NAME = ".slipcoverrc"
+
+# coverage.py splits its settings between these two sections, and users
+# reasonably guess either one; both are read, and neither is enforced.
+_RCFILE_SECTIONS = ("run", "report")
 
-def find_pyproject(start=None):
-    """Walks up from 'start' (default cwd) looking for pyproject.toml.
+
+def _find_upwards(filename, start):
+    """Walks up from 'start' (default cwd) looking for 'filename'.
 
     The search stops and returns None when any of these boundaries is
     reached without finding the file:
@@ -33,7 +40,7 @@ def find_pyproject(start=None):
     home = Path.home()
 
     for depth, directory in enumerate((start, *start.parents)):
-        candidate = directory / "pyproject.toml"
+        candidate = directory / filename
         if candidate.is_file():
             return candidate
 
@@ -47,6 +54,22 @@ def find_pyproject(start=None):
     return None
 
 
+def find_pyproject(start=None):
+    """Walks up from 'start' (default cwd) looking for pyproject.toml.
+
+    See _find_upwards() for the boundaries that stop the search.
+    """
+    return _find_upwards("pyproject.toml", start)
+
+
+def find_rcfile(start=None):
+    """Walks up from 'start' (default cwd) looking for .slipcoverrc.
+
+    Uses the same boundaries as find_pyproject().
+    """
+    return _find_upwards(_RCFILE_NAME, start)
+
+
 def read_config(path=None):
     """Returns the [tool.slipcover] table from a pyproject.toml.
 
@@ -89,13 +112,102 @@ def read_config(path=None):
 }
 
 
-def apply_config(config, parsed_args, explicit_args=None):
+def _parse_rcfile_bool(key, value):
+    try:
+        return configparser.ConfigParser.BOOLEAN_STATES[value.strip().lower()]
+    except KeyError:
+        raise ValueError(
+            f"key '{key}' must be a boolean, got '{value}'"
+        ) from None
+
+
+def read_rcfile(path=None):
+    """Returns the slipcover settings held in a .slipcoverrc (INI) file.
+
+    If 'path' is None, find_rcfile() is used to locate the file.
+    The [run] and [report] sections are merged into a single dict shaped
+    like read_config()'s, ready to hand to apply_config().
+    Returns an empty dict when no file is found.
+    """
+    if path is None:
+        path = find_rcfile()
+
+    if path is None:
+        return {}
+
+    # No interpolation: a literal '%' in a value (an omit pattern, an
+    # output name) is a plain character, not syntax to escape.
+    # The default section is renamed out of the way so [DEFAULT] is read as
+    # an ordinary -- and thus unknown -- section, rather than seeding every
+    # other section's options and colliding with the duplicate check below.
+    parser = configparser.ConfigParser(interpolation=None,
+                                       default_section="__slipcover_no_default__")
+    # utf-8-sig also accepts the BOM Notepad and PowerShell 5.1 write; it
+    # is plain utf-8 otherwise.
+    with open(path, encoding="utf-8-sig") as f:
+        parser.read_file(f)
+
+    for section in parser.sections():
+        if section not in _RCFILE_SECTIONS:
+            import warnings
+            warnings.warn(f"Unknown {path} section: '[{section}]'")
+
+    config = {}
+
+    # A key repeated across the two sections is a legitimate override --
+    # [report] is read last and wins -- so only same-section duplicates
+    # are checked below.
+    for section in _RCFILE_SECTIONS:
+        if not parser.has_section(section):
+            continue
+
+        spellings = {}
+
+        for name, value in parser.items(section):
+            # configparser lowercases names; accept coverage.py's
+            # underscores as well as slipcover's own hyphens.
+            key = name.replace("_", "-")
+
+            # configparser keeps 'fail-under' and 'fail_under' as distinct
+            # options, so normalizing would let the second silently win;
+            # an identically-spelled duplicate is a DuplicateOptionError.
+            if key in spellings:
+                raise ValueError(
+                    f"[{section}] key '{key}' given twice, "
+                    f"as '{spellings[key]}' and '{name}'"
+                )
+            spellings[key] = name
+
+            if key in _BOOL_KEYS:
+                # apply_config() requires a real bool, and INI has no types.
+                config[key] = _parse_rcfile_bool(key, value)
+            elif key in ("source", "omit"):
+                # coverage.py writes these one per line; the CLI wants them
+                # comma-separated.
+                config[key] = ",".join(
+                    item
+                    for line in value.splitlines()
+                    for item in (part.strip() for part in line.split(","))
+                    if item
+                )
+            else:
+                # Left as a string: apply_config() coerces known keys and
+                # warns about the rest.
+                config[key] = value
+
+    return config
+
+
+def apply_config(config, parsed_args, explicit_args=None,
+                 source="[tool.slipcover]"):
     """Merges config values into parsed_args.
 
     Keys whose dest name appears in 'explicit_args' are skipped so that
     command-line flags always take precedence over the config file.
+    'source' names where the config came from, for diagnostics.
 
-    Raises TypeError if a boolean key has a non-boolean value.
+    Raises TypeError if a value's type is wrong for its key, and
+    ValueError if a value can't be coerced to the key's type.
     Emits a UserWarning for unrecognised keys.
     """
     if explicit_args is None:
@@ -111,7 +223,7 @@ def apply_config(config, parsed_args, explicit_args=None):
         if key in _BOOL_KEYS:
             if not isinstance(value, bool):
                 raise TypeError(
-                    f"[tool.slipcover] key '{key}' must be a boolean, got {type(value).__name__}"
+                    f"{source} key '{key}' must be a boolean, got {type(value).__name__}"
                 )
             setattr(parsed_args, dest, value)
 
@@ -121,8 +233,16 @@ def apply_config(config, parsed_args, explicit_args=None):
             # expects, rather than stringifying the Python list itself.
             if key in ("source", "omit") and isinstance(value, list):
                 value = ",".join(str(v) for v in value)
-            setattr(parsed_args, dest, _VALUE_KEYS[key](value))
+            # Path("") is Path('.'), so an empty 'out' would only surface much
+            # later, as an IsADirectoryError while writing the report.
+            if key == "out" and isinstance(value, str) and not value.strip():
+                raise ValueError(f"key '{key}': must not be empty")
+            try:
+                coerced = _VALUE_KEYS[key](value)
+            except (ValueError, TypeError) as e:
+                raise type(e)(f"key '{key}': {e}") from None
+            setattr(parsed_args, dest, coerced)
 
         else:
             import warnings
-            warnings.warn(f"Unknown [tool.slipcover] key: '{key}'")
+            warnings.warn(f"Unknown {source} key: '{key}'")