NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #4459 most downloaded on PyPI
A Python docstring linter that checks arguments, returns, yields, and raises sections
Last release 2 days ago
02 Oct 2026
Release timing varies
gaps range from 1 weeks to 6 months
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
3 years old
96 releases · first in 2023
One column per quarter.
Support checking stub (.pyi) files by @jsh9 in #310
--include-stub-files (shortform: -isf, default:
False), so that scanning a folder also checks stub (.pyi) files (#303)DOC403 and DOC502 violations in stub (.pyi) files,
whose function bodies are placeholders, in both the native mode and
flake8 (#303). DOC403 is still reported in stub files when the return
annotation isn't a Generator/Iterator/Iterable (or is missing), because
then the function can't yield anythingDOC105 and DOC605 violations in stub files when
--check-arg-defaults is True: an argument or class attribute whose
default is the ... placeholder can now be documented with any default
value or noneDOC201 violations for abstract methods and stub functions
annotated with Iterator[...] or Iterable[...] whose docstrings have a
"Yields" section (and no "return" statements in the body). Their bodies are
placeholders, so the "Yields" section is what shows that they yield, and
they don't need a "Returns" sectionDOC203 violations for abstract methods and stub functions
annotated with Generator[YieldType, SendType, ReturnType] whose "Returns"
section documents ReturnType, as for a generator that both yields and
returnsDOC202 violations for abstract methods and stub functions
that have a "Returns" section but no return annotation. (DOC203 still
reports the missing annotation when return types are checked.)IndexError) when --check-arg-defaults is True and
positional-only arguments (the ones before /) have default values. When
it didn't crash, the defaults of positional-only arguments were ignoredRewrite README and restructure docs by @jsh9 in #307
Full Changelog: 0.10.0...0.10.1
DOC103/DOC603 docs linkdocs/llms.txt and a pre-commit check for orphan docs and broken linksitertools.product with stacked @pytest.mark.parametrize
decorators in tests/test_main.pyUse external changelog diff checking hook by @jsh9 in #297
Full Changelog: 0.9.1...0.10.0
--ignore-underscore-only-args (-iuoa, default: True)--ignore-special-dunder-args (-isda, default: False)--ignore-private-class-attributes (-ipca, default: True)--ignore-underscore-only-class-attributes (-iuoca, default: True)--ignore-special-dunder-class-attributes (-isdca, default: True)_: dataclasses.KW_ONLY, to be ignored independently of private class
attributes (#302). This is a name-based fix, so a KW_ONLY pseudo-field
whose name is not underscore-only is still treated like any other attributefalse),
so the lowercase values shown in migration messages work in Flake8 config
files* or **, so
*_ and **__ are ignored by --ignore-underscore-only-args, and
*_args is ignored by --ignore-private-args--skip-checking-private-functions now also skips functions named __ or
___ (it already skipped _); special dunder methods such as __init__
are still checked--ignore-private-args no longer controls special dunder arguments (such
as __value__). If you set --ignore-private-args=True and want them to
stay ignored, also set --ignore-special-dunder-args=TrueVisitor keyword arguments from ignoreUnderscoreArgs and
shouldDocumentPrivateClassAttributes to ignoreUnderscoreOnlyArgs,
ignoreSpecialDunderArgs, ignorePrivateClassAttributes,
ignoreUnderscoreOnlyClassAttributes, and
ignoreSpecialDunderClassAttributes; this is a breaking change for code
that uses Visitor directly--ignore-underscore-args; using it now fails with guidance to
delete it when it has the new default value or replace it with
--ignore-underscore-only-args--should-document-private-class-attributes; using it now fails
with guidance to delete it when it has the new defaults or set
--ignore-private-class-attributes,
--ignore-underscore-only-class-attributes, and
--ignore-special-dunder-class-attributes to the inverse valuepre-commit-changelog-full-diff-check and updated this repo to consume it
as an external hooktox -e muff-lint a non-mutating check that fails instead of
rewriting filesFix numpy default checks for breaking changes in docstring_parser_fork by @jsh9 in #296
docstring_parser_fork==0.0.16, which preserves raw parameter and
attribute type declarations while still exposing normalized type/default
fieldsmypy with ty and fixed the surfaced
typing issues with explicit type narrowingtox -e pydoclint self-check against the local package instead of
the latest published pydoclint release0.15.20 and added a pre-commit hook to keep the
tox Muff pins in sync with the muff-pre-commit revisionHandle PEP 696 defaults for Generator annotations by @gaoflow in #293
Full Changelog: 0.8.7...0.9.0
DOC404 false positive for single-argument Generator[YieldType]
annotations, where pydoclint compared the docstring yield type with the
whole annotation instead of the generator yield typeGenerator[...]
annotations so omitted return types default to None per PEP-696Fix DOC404 false positive on functions with both return and yield by @StressTestor in #291
Full Changelog: 0.8.6...0.8.7
DOC404 false positive on a function with both a return and a yield
whose return annotation is a parametrized iterator (e.g.
Iterator[Dict[str, Any]]): the yield type was extracted twice, producing
(str, Any) instead of Dict[str, Any]Report unsupported docstring headers (numpy) as DOC001 by @jsh9 in #290
Full Changelog: 0.8.5...0.8.6
DOC001 did not intercept unsupported numpy docstring section
headers such as Inputs, Outputs, and non-ASCII names, and as a result
pydoclint would report confusing cascading violationsUpdate linter and formatter versions by @jsh9 in #286
Full Changelog: 0.8.4...0.8.5
DOC001 parsing errorsAdd config option and logic to accommodate PEP257-style inline class attribute documentation by @mpyuglgwkxcmodyrpo in #278
Full Changelog: 0.8.3...0.8.4
DOC606 and DOC607, and
introduce --require-inline-class-var-docs in native and flake8 modes--skip-checking-private-functions (shortform:
-scpf) to allow docstrings in private methods not to be checkedFix baseline renegeration bug by @jsh9 in #275
--omit-stars-when-documenting-varargs (shortform:
-oswdv) so docstrings may describe varargs without the leading *
characters (https://github.com/jsh9/pydoclint/issues/268)--auto-regenerate-baseline removes entries of files that have
not yet been fixed (https://github.com/jsh9/pydoclint/issues/274)Add ability to partially match violation codes by @jsh9 in #272
Full Changelog: 0.8.1...0.8.2
noqa in the native
mode (which flake8 already supports)__init__() in a class (overloaded),
the first __init__() is incorrectly recognized as the "right" one. (The
last __init__() should be considered the right one.)Change logic to detect docstring style mismatch by @jsh9 in #271
Full Changelog: 0.8.0...0.8.1
New functionality: _pydoclint_ native mode can parse "noqa" comments and thus users can suppress violations in the native mode.
Updated linter and auto-formatter configurations
Fixed the logic to statically detect whether a method is a property or an abstract method
Validation of invalid config file path
[tool.pydoclint] section in the config fileFixed comment handling in type hints to properly ignore inline comments when comparing type annotations between function signatures and docstrings
A bug where false positive arg names are reported in the violation message
Support for --check-arg-default for Google style
--check-arg-default for Google styleA new config option --check-arg-default (default: False) to check consistency of argument defaults (between docstring and function signature)
--check-arg-default (default: False) to check
consistency of argument defaults (between docstring and function signature)Prettier with: yamlfix,
mdformat, and
pretty-format-jsonA bug where short docstring is incorrectly detected
Removed deprecated setup.cfg and setup.py files
Fixed output formatting bug where blank lines between files would appear at the end when redirecting output to a file instead of between each file
Enhanced numpy-style docstring detection with pattern-based recognition
Returns\n-------) before falling back to size-based comparisonA bug where double quotes in function signature type hints are not treated as interchangeable as double quotes in the docstring
--quiet from False to TrueA typo in the default config value of --ignore-private-args
--ignore-private-argsshouldDeclareAssertErrorIfAssertStatementExists is FalseA bug with tuple decomposition in docstrings
Added DOC504 and a config option --should-declare-assert-error-if-assert-statement-exists. If this option is True and a function has an assert stateme
DOC504 and a config option
--should-declare-assert-error-if-assert-statement-exists. If this option
is True and a function has an assert statement, an AssertError
declaration is required in the docstring. Otherwise DOC504 is raised.
(This changes the behavior introduced in v0.6.1.)--ignore-private-args (default to False)LN002 violation in flake8 config in toxAn issue where no error was thrown when the user does not supply a path
--only-attrs-with-ClassVar-are-treated-as-class-attrs is not
properly passed to the visitor in the flake8 modeNow if a function as an assert statement, an AssertError declaration is by default required in the docstring's "Asserts" section (if relevant config o
assert statement, an AssertError declaration is
by default required in the docstring's "Asserts" section (if relevant
config options to check raises/assertions are turned on)A new violation code, DOC003, to detect docstring style mismatch (when docstrings are written in the style different from specified)
DOC003, to detect docstring style mismatch (when
docstrings are written in the style different from specified)False positive DOC405 and DOC201 when we have bare return statements together with yield statements
yield statements--should-document-star-arguments (if False, star
arguments such as *args and **kwargs should not be documented in the
docstring)An issue where custom exceptions such as a.b.c.MyException.from_str cannot be properly parsed and compared
a.b.c.MyException.from_str
cannot be properly parsed and comparedA new config option --auto-regenerate-baseline to automatically regenerate the baseline file for every successful _pydoclint_ run
--auto-regenerate-baseline to automatically
regenerate the baseline file for every successful pydoclint runA pre-commit hook for using _pydoclint_ as a flake8 plugin
Changed to using v0.0.10 of docstring_parser_fork, which now throws a ParseError when a non-empty docstring section cannot be parsed (in Numpy style).
ParseError when a non-empty docstring section cannot be parsed (in Numpy
style). This ParseError would lead to DOC001.Added DOC002 (syntax error) to handle cases where there are syntax errors in the Python file
DOC002 (syntax error) to handle cases where there are syntax errors
in the Python fileFixed a bug where assigning a dict value (such as abc['something'] = 123) would result in EdgeCaseError
abc['something'] = 123)
would result in EdgeCaseErrorUse "modern" type annotation, such as list and str | None
list and str | Nonemypy--only-attrs-with-ClassVar-are-treated-as-class-attrsFixed a bug where pydoclint uses variable names instead of the exception itself
Command line message about loading config file is now hidden with config option --quiet
--quietunparseAnnotation() into unparseNode()EdgeCaseError into EdgeCaseErrorFixed an edge case where type annotations are very long
Fixed the logic of handling exceptions namespaces (a.b.c.MyException)
a.b.c.MyException)A new violation code, DOC503, which checks that exceptions in the function body match those in the "Raises" section of the docstring
DOC503, which checks that exceptions in the
function body match those in the "Raises" section of the docstringFixed a bug where _pydoclint_ treats folders whose names end with .py as files
.py as
filesFixed a bug where a = b = c = 1 style cannot be properly parsed
a = b = c = 1 style cannot be properly parsed
(https://github.com/jsh9/pydoclint/issues/151)--treat-property-methods-as-class-attributes to
False to restore backward compatibilityAn option --should-document-private-class-attributes (if False, private class attributes should not appear in the docstring)
--should-document-private-class-attributes (if False, private
class attributes should not appear in the docstring)--treat-property-methods-as-class-attributes (if True,
@property methods are treated like class attributes and need to be
documented in the class docstring)https://github.com/jsh9/pydoclint/compare/0.5.2...0.5.3
Pinned to a higher version (0.0.9) of docstring_parser_fork
--skip-checking-short-docstrings) is set to True, no DOC6xx
violations will be reportedFixed a bug in unparsing annotations when checking class attributes
Added checks for class attributes
--check-class-attributes (or -cca),
which defaults to True. Therefore, this breaks backward compatibility.--check-class-attributes to
False--check-arg-order, --arg-type-hints-in-signature, and
--arg-type-hints-in-docstring are still effective in checking class
attributesImproved the violation message of DOC403 to remind users to add a return annotation
A bug where using double quotes in Literal type (such as Literal["foo"] could produce a false positive DOC203 violation.
Literal["foo"]
could produce a false positive DOC203 violation.--srcImproved the violation message of DOC105: the arguments with inconsistent type hints are now shown in the violation message to make violation correcti
A new config option --show-filenames-in-every-violation-message (or -sfn), which makes it more convenient to jump to the corresponding line in IDEs by
--show-filenames-in-every-violation-message (or
-sfn), which makes it more convenient to jump to the corresponding line
in IDEs by clicking on the violation message in the terminalFalse positive violation DOC203 when there is no docstring return section for methods with @property decorator
DOC203 when there is no docstring return section
for methods with @property decoratorA bug in handling prepended escape characters in docstrings
Disabled parallel mode for pre-commit
Updated dependency (docstring_parser_fork) to 0.0.5 to fix issues when parsing Google-style return section
When checking for consistency betwene the docstring arguments and the arguments in the function signature, ignore underscore arguments (_, __, ___, ..
_,
__, ___, ...) in the arguments in the function signatureYour coding agent can read these notes before it upgrades. Set up the MCP server →