question: should changing a parameter default from a constant to None be flagged as breaking?

[RonnyPfannschmidt]

Context

While fixing pypa/setuptools-scm#1434, we wanted to change a deprecated parameter's default from a module-level constant to None, with the function resolving None to the same constant internally. This is a common pattern for deprecation: stop eagerly providing the default so you can distinguish "caller didn't pass this" from "caller explicitly passed the old default".

Reproducer

# src/mylib/__init__.py — v1.0.0 (before)
import re
from re import Pattern

DEFAULT_PATTERN: Pattern[str] = re.compile(r"v(?P<version>.+)")

def get_version(
    root: str = ".",
    tag_regex: str | Pattern[str] = DEFAULT_PATTERN,
) -> str:
    """Get the version."""
    return "1.0.0"

# src/mylib/__init__.py — v1.1.0 (after)
import re
from re import Pattern

DEFAULT_PATTERN: Pattern[str] = re.compile(r"v(?P<version>.+)")

def get_version(
    root: str = ".",
    tag_regex: str | Pattern[str] | None = None,
) -> str:
    """Get the version."""
    if tag_regex is None:
        tag_regex = DEFAULT_PATTERN
    return "1.0.0"

$ griffe check mylib -ssrc --against v1.0.0
src/mylib/__init__.py:9: get_version(tag_regex):
Parameter default was changed:
  Old: DEFAULT_PATTERN
  New: None

Question

This is flagged as a breaking change, but from a caller's perspective:

• get_version() (no args) behaves identically before and after
• get_version(tag_regex="custom") also behaves identically
• The only observable difference is via introspection (inspect.signature), where the default representation changes

Is this level of strictness intentional? The "default changed" check makes sense for cases where the actual behavior changes (e.g. timeout=30 → timeout=60), but the CONSTANT → None pattern is specifically used to preserve behavior while enabling the function to detect whether the caller explicitly provided a value.

This relates to #399 (suppression configuration) — in the meantime, we worked around this by keeping the original default and using tag_regex is DEFAULT_PATTERN identity checks instead. But the None-default pattern is idiomatic Python for deprecations and optional parameters, so it'd be nice to understand if griffe considers this a genuine API break or if there's room for a more nuanced check here.

[RonnyPfannschmidt]

Reproducer repository

I've set up a standalone reproducer repo with a GitHub Actions workflow:

Repo: https://github.com/RonnyPfannschmidt/griffe-reproducer-469

• v1.0.0 tag — baseline with tag_regex: str | Pattern[str] = DEFAULT_PATTERN
• main branch — changed to tag_regex: str | Pattern[str] | None = None with internal resolution
• Failing CI run: https://github.com/RonnyPfannschmidt/griffe-reproducer-469/actions/runs/28015080881

The workflow runs griffe check --verbose mylib -ssrc --against v1.0.0 and demonstrates the failure.

[pawamoy]

Hey @RonnyPfannschmidt, thanks for the question 🙂 The breaking change checker is far from perfect yet, so yes, this is an edge-case that isn't well supported. Ideally we'd scan the function body to understand what is done to/with parameters and their default value, but you can imagine this is a different beast to wrestle with. So I agree with you, this shouldn't trigger a breaking change, I'm just not sure how to make the change possible.

Also, instead of None I would even use a sentinel like _sentinel = object() (or use the actual sentinel() function introduced in 3.15) 😄

[pawamoy]

I hope I can find some time to work on a suppression system as described in #399 🙂

[pawamoy]

Also, in the meantime, you can customize how the data is loaded with a Griffe extension. The extension would simply replace the None default with the value assigned in the body (or the opposite), so that the change goes unnoticed.

[RonnyPfannschmidt]

Is there some documentation i should follow

[pawamoy]

It's all here: https://mkdocstrings.github.io/griffe/guide/users/extending/. We also provide a few how-to which could help you, for example https://mkdocstrings.github.io/griffe/guide/users/how-to/support-decorators/.