Recognise a few special functions

[oliversheridanmethven]

There are a few "special" functions which are known to return, no-return, raise, yield, warn, etc., and it would be good to have pydoclint acknowledge these.

For example, sys.exit, as per the docs:

sys.exit([arg])
Raise a SystemExit exception, signaling an intention to exit the interpreter.

So I would like to be able to write:

import sys

def panic() -> None:
    """
    ...

    Raises
    ------
    SystemExit
        Unable to deal with the situation.
    """
    sys.exit(1)

Other examples include e.g. warnings.warn.

I appreciate that this starts to encroach on "should our documentation be transitive" and do we have to re-describe all the exceptions that the dependencies could themselves raise, but I think these few special cases merit specific handling.

[oliversheridanmethven]

The current way to appease pydoclint is something alone the lines of:

def panic() -> None:
    """
    ...

    Raises
    ------
    SystemExit
        Unable to deal with the situation.
    """
    try:
        sys.exit(1)
    except SystemExit:
        raise

but this is much less pleasing...

[jsh9]

Thanks for raising this issue. This is a good suggestion.

Below is an implementation plan generated by AI. If you're interested in making a contribution, it's be greatly appreciated. Otherwise, I can implement this myself maybe within the next few weeks.

---

Implementation Plan: Recognise Special Functions as Implicit Raises (Issue #280)

Background

pydoclint currently detects raise-related violations (DOC501, DOC502, DOC503) by
scanning the function body for ast.Raise nodes. However, some stdlib functions like
sys.exit() and warnings.warn() are semantically equivalent to raise statements, but
since they are call expressions (not ast.Raise nodes), pydoclint incorrectly flags
DOC502 when a developer documents SystemExit in the Raises section of a function that
calls sys.exit().

---

Proposed Changes

1. New file: pydoclint/utils/special_functions.py (or extend the existing one)

Note: There is already a file named
special_methods.py
for detecting things like @property. A new file special_functions.py is recommended
to keep concerns separate.

Add a hardcoded mapping of well-known stdlib call expressions to the exception(s) they
implicitly raise:

# Maps (module_or_None, function_name) -> list of implicitly raised exception names
IMPLICIT_RAISES: dict[tuple[str | None, str], list[str]] = {
    ("sys", "exit"):        ["SystemExit"],
    ("os", "_exit"):        ["SystemExit"],
    ("warnings", "warn"):   ["Warning"],
}

Also add a helper:

def getImplicitRaisesFromCall(node: ast.Call) -> list[str]:
    """
    Given an ast.Call node, return any implicitly raised exception names
    if the function being called is in IMPLICIT_RAISES.
    """
    ...

The function matches:

• sys.exit(1) → ast.Attribute with attr="exit", value.id="sys"
• Plain exit(1) (no module prefix) → ast.Name with id="exit" (optional/stretch goal)

---

2. Modify pydoclint/utils/return_yield_raise.py

a) hasRaiseStatements() — extend to also return True when the function body
contains a call to any function in IMPLICIT_RAISES:

def hasRaiseStatements(node: FuncOrAsyncFuncDef) -> bool:
    """Check whether the function node has any raise statements or implicit raises"""
    ...
    # After existing ast.Raise check, also check for implicit raises via ast.Call

b) _getRaisedExceptions() — extend the DFS walk to also yield exception names from
implicit-raise calls (so DOC503 type-matching works correctly too):

# Inside the walk loop, in addition to `isinstance(child, ast.Raise)`:
if isinstance(child, ast.Expr) and isinstance(child.value, ast.Call):
    yield from getImplicitRaisesFromCall(child.value)

---

3. Optionally add a new CLI option in pydoclint/main.py and pydoclint/flake8_entry.py

--extra-raises-functions  (shortform: -erf, default: [])

This allows users to add their own module.function entries treated as implicit raises:

[tool.pydoclint]
extra-raises-functions = ["mylib.panic", "mylib.abort"]

The mapping to exception names for user-supplied functions is not automatic (unlike stdlib
where we know what they raise); instead, users must declare the exception in their docstring
and pydoclint will simply not flag DOC502 for those calls.

This option can be deferred to a follow-up issue if scope needs to be kept small.

---

Files Changed Summary

File	Change
pydoclint/utils/special_functions.py	[NEW] Hardcoded IMPLICIT_RAISES map + getImplicitRaisesFromCall() helper
pydoclint/utils/return_yield_raise.py	[MODIFY] Extend hasRaiseStatements() and _getRaisedExceptions() to handle implicit raises
pydoclint/main.py	[MODIFY] Add --extra-raises-functions CLI option (optional)
pydoclint/flake8_entry.py	[MODIFY] Wire up --extra-raises-functions for flake8 mode (optional)
pydoclint/parse_config.py	[MODIFY] Parse new config option (optional)

---

Testing Plan

Unit tests in tests/utils/test_returns_yields_raise.py

Add new test cases for hasRaiseStatements() and getRaisedExceptions():

src_sys_exit = """
import sys
def panic() -> None:
    sys.exit(1)
"""
# hasRaiseStatements(panic) -> True
# getRaisedExceptions(panic) -> ["SystemExit"]

src_warnings_warn = """
import warnings
def warn_user() -> None:
    warnings.warn("something", UserWarning)
"""
# hasRaiseStatements(warn_user) -> True
# getRaisedExceptions(warn_user) -> ["Warning"]

src_no_implicit = """
def fine() -> None:
    print("hello")
"""
# hasRaiseStatements(fine) -> False
# getRaisedExceptions(fine) -> []

End-to-end test fixtures

Add new cases to
tests/test_data/numpy/raises/cases.py
(and the google/ and sphinx/ equivalents):

import sys
import warnings

def func_sys_exit() -> None:
    """
    Should NOT raise DOC502 (sys.exit is an implicit raise).

    Raises
    ------
    SystemExit
        When something goes wrong.
    """
    sys.exit(1)

def func_sys_exit_no_doc() -> None:
    """
    Should raise DOC501 (raise not documented).
    """
    sys.exit(1)

def func_warnings_warn() -> None:
    """
    Should NOT raise DOC502.

    Raises
    ------
    Warning
        Always.
    """
    warnings.warn("heads up")

Add corresponding expected violation assertions in tests/test_end_to_end.py.

Manual smoke test

# should produce no DOC502
echo "
import sys
def panic() -> None:
    '''
    Raises
    ------
    SystemExit
        Always.
    '''
    sys.exit(1)
" | pydoclint --style=numpy -