python-contract-docstrings

Analyze each function's guard clauses, assertions, and implicit assumptions to identify preconditions, then document them in a Contract section of a Google-style docstring. Include what exception is raised when each precondition is violated, whether explicit or implicit.

Trace the function's code paths and its callees to find every exception that can propagate, then list them in a Raises section with the triggering condition. Distinguish explicit guard-clause errors from implicit failures like TypeError or KeyError.

A regular docstring describes what a function does, while a contract docstring describes what it demands and guarantees. It documents input invariants, errors raised on violation, errors from external state, and silenced exceptions.

No, the process only adds or replaces docstrings and never refactors code. The workflow explicitly forbids behavior changes and recommends running the test suite and type checker afterward to verify nothing broke.

Skip trivial functions such as one-liners, simple property accessors, and __repr__ methods where the contract is self-evident. Also omit any contract detail you cannot verify by reading the code, since accuracy takes priority over completeness.