NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #4106 most downloaded on PyPI
A Python docstring linter that checks arguments, returns, yields, and raises sections
Latest stable
0.12.0
Last release 25 days ago
28 Oct 2026
Ships unpredictably
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
4 years old
98 releases · first in 2023
Drag across the ruler to compare, or tap a release to open it.
Recognize qualified generator and iterator annotations by @momooo15 in https://github.com/jsh9/pydoclint/pull/321
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.11.1...0.12.0
typing.Generator[...],
collections.abc.Iterator[...], and t.Iterable[...] are recognized too
(#317)IterableDataset are no longer treated as iteratorsIterator[int] | None or
Iterator[int] | list[int], are no longer recognized as iterator or
generator annotationsnp.random.Generator is treated like
typing.Generator, and renamed imports such as
from typing import Iterator as It are still not recognized0.12.0 Latest
Latest
Compare
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Fix empty exclude pattern excluding all files instead of none by @jsh9 in https://github.com/jsh9/pydoclint/pull/319
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.11.0...0.11.1
--exclude pattern (such as --exclude='' or exclude = '' in
the config file) excluded every file, so nothing was checked and the run
passed. Now an empty pattern means "don't exclude any files", so every file
gets checked (#311)--exclude value that isn't a valid regular expression is now rejected
with a clear error message instead of a tracebackSupport checking stub (.pyi) files by @jsh9 in https://github.com/jsh9/pydoclint/pull/310
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.10.1...0.11.0
--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 https://github.com/jsh9/pydoclint/pull/307
Full Changelog: https://github.com/jsh9/pydoclint/compare/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 https://github.com/jsh9/pydoclint/pull/297
Full Changelog: https://github.com/jsh9/pydoclint/compare/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 https://github.com/jsh9/pydoclint/pull/296
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.9.0...0.9.1
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 https://github.com/jsh9/pydoclint/pull/293
Full Changelog: https://github.com/jsh9/pydoclint/compare/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 https://github.com/jsh9/pydoclint/pull/291
Full Changelog: https://github.com/jsh9/pydoclint/compare/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 https://github.com/jsh9/pydoclint/pull/290
Full Changelog: https://github.com/jsh9/pydoclint/compare/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 https://github.com/jsh9/pydoclint/pull/286
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.8.4...0.8.5
DOC001 parsing errorsAdd config option and logic to accommodate PEP257-style inline class attribute documentation by @mpyuglgwkxcmodyrpo in https://github.com/jsh9/pydocli
Full Changelog: https://github.com/jsh9/pydoclint/compare/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 https://github.com/jsh9/pydoclint/pull/275
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.8.2...0.8.3
--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 https://github.com/jsh9/pydoclint/pull/272
Full Changelog: https://github.com/jsh9/pydoclint/compare/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 https://github.com/jsh9/pydoclint/pull/271
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.8.0...0.8.1
Add inline violation suppression for native mode by @jsh9 in https://github.com/jsh9/pydoclint/pull/270
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.7.6...0.8.0
Refresh linters & formatters by @jsh9 in https://github.com/jsh9/pydoclint/pull/269
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.7.5...0.7.6
Support @property + @abstractmethod without a Returns: section by @barometz in https://github.com/jsh9/pydoclint/pull/261
@property + @abstractmethod without a Returns: section by @barometz in https://github.com/jsh9/pydoclint/pull/261Full Changelog: https://github.com/jsh9/pydoclint/compare/0.7.4...0.7.5
Fixed README typo by @akleeman in https://github.com/jsh9/pydoclint/pull/266
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.7.3...0.7.4
[tool.pydoclint] section in the config fileProperly ignore in-line comments in doc type hints by @jsh9 in https://github.com/jsh9/pydoclint/pull/260
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.7.2...0.7.3
Fix comment handling in type hints by @jsh9 in https://github.com/jsh9/pydoclint/pull/259
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.7.1...0.7.2
Add check-arg-defaults support for Google style by @jsh9 in https://github.com/jsh9/pydoclint/pull/258
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.7.0...0.7.1
--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)
A 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-jsonFix bug in isShortDocstring by @jsh9 in https://github.com/jsh9/pydoclint/pull/256
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.10...0.6.11
Migrate from setup.cfg/py to pyproject.toml by @jsh9 in https://github.com/jsh9/pydoclint/pull/251
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.9...0.6.10
Fix output formatting bug with blank lines during redirection by @jsh9 in https://github.com/jsh9/pydoclint/pull/250
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.8...0.6.9
Enhance numpy-style docstring detection and update documentation by @jsh9 in https://github.com/jsh9/pydoclint/pull/249
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.7...0.6.8
Returns\n-------) before falling back to size-based comparisonFix bug with double quotes; change "--quiet" default by @jsh9 in https://github.com/jsh9/pydoclint/pull/236
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.5...0.6.6
--quiet from False to TrueFix typo in config option default value by @jsh9 in https://github.com/jsh9/pydoclint/pull/229
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.4...0.6.5
--ignore-private-argsshouldDeclareAssertErrorIfAssertStatementExists is FalseFix a bug in decomposing tuples in docstrings by @jsh9 in https://github.com/jsh9/pydoclint/pull/227
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.3...0.6.4
New violation code D504 by @jsh9 in https://github.com/jsh9/pydoclint/pull/220
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.2...0.6.3
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 toxThrow error when user provides no paths by @jsh9 in https://github.com/jsh9/pydoclint/pull/218
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.1...0.6.2
--only-attrs-with-ClassVar-are-treated-as-class-attrs is not
properly passed to the visitor in the flake8 modeMigrate to pyproject.toml by @pechersky in https://github.com/jsh9/pydoclint/pull/214
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.6.0...0.6.1
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)Add DOC003 to check docstring style mismatch by @jsh9 in https://github.com/jsh9/pydoclint/pull/207
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.19...0.6.0
DOC003, to detect docstring style mismatch (when
docstrings are written in the style different from specified)Fix false positive DOC405 & DOC201 for bare returns by @jsh9 in https://github.com/jsh9/pydoclint/pull/205
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.18...0.5.19
yield statements--should-document-star-arguments (if False, star
arguments such as *args and **kwargs should not be documented in the
docstring)Fix parsing and comparison of chained custom exceptions by @jsh9 in https://github.com/jsh9/pydoclint/pull/203
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.17...0.5.18
a.b.c.MyException.from_str
cannot be properly parsed and comparedAdd an option to auto regenerate baseline by @jsh9 in https://github.com/jsh9/pydoclint/pull/202
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.16...0.5.17
--auto-regenerate-baseline to automatically
regenerate the baseline file for every successful pydoclint run👌 Add pre-commit-hook to run pydoclint via flake8 by @s-weigand in https://github.com/jsh9/pydoclint/pull/200
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.15...0.5.16
Throw DOC001 when docstring sections can't be parsed (numpy style) by @jsh9 in https://github.com/jsh9/pydoclint/pull/199
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.14...0.5.15
ParseError when a non-empty docstring section cannot be parsed (in Numpy
style). This ParseError would lead to DOC001.Make pydoclint not crash on syntax erros (including invisible chars) by @jsh9 in https://github.com/jsh9/pydoclint/pull/194
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.13...0.5.14
DOC002 (syntax error) to handle cases where there are syntax errors
in the Python fileFix a bug with subscript assign by @jsh9 in https://github.com/jsh9/pydoclint/pull/191
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.12...0.5.13
abc['something'] = 123)
would result in EdgeCaseErrorDrop Python 3.8 support by @jsh9 in https://github.com/jsh9/pydoclint/pull/186
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.11...0.5.12
list and str | Nonemypy--only-attrs-with-ClassVar-are-treated-as-class-attrsfix: get name of a raised exception when bound in except by @Amar1729 in https://github.com/jsh9/pydoclint/pull/184
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.10...0.5.11
Hide msg about loading config in quiet mode by @aemonge in https://github.com/jsh9/pydoclint/pull/178
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.9...0.5.10
--quietunparseAnnotation() into unparseNode()EdgeCaseError into EdgeCaseErrordoc(usage): Including a null-ls use with neovim. by @aemonge in https://github.com/jsh9/pydoclint/pull/167
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.8...0.5.9
fix: DOC503 catch namespaced exceptions by @Amar1729 in https://github.com/jsh9/pydoclint/pull/168
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.7...0.5.8
a.b.c.MyException)docs: add "sphinx" as an allowed style by @Amar1729 in https://github.com/jsh9/pydoclint/pull/159
deps = . instead of pip install by @Amar1729 in https://github.com/jsh9/pydoclint/pull/160Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.6...0.5.7
DOC503, which checks that exceptions in the
function body match those in the "Raises" section of the docstringStop trying to check folder with names ending in .py by @jsh9 in https://github.com/jsh9/pydoclint/pull/155
.py by @jsh9 in https://github.com/jsh9/pydoclint/pull/155Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.5...0.5.6
.py as
filesImprove class attr comparison logic by @jsh9 in https://github.com/jsh9/pydoclint/pull/154
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.4...0.5.5
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 compatibilityAdd an option for private class attributes by @jsh9 in https://github.com/jsh9/pydoclint/pull/149
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.3...0.5.4
--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)Add DOC604 & 605 test cases; improve DOC605 err msg by @jsh9 in https://github.com/jsh9/pydoclint/pull/147
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.2...0.5.3
Make url a proper link by @Gabriel-p in https://github.com/jsh9/pydoclint/pull/137
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.1...0.5.2
--skip-checking-short-docstrings) is set to True, no DOC6xx
violations will be reportedFix annotation unparsing bug by @jsh9 in https://github.com/jsh9/pydoclint/pull/132
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.5.0...0.5.1
Check class attributes against docstring by @jsh9 in https://github.com/jsh9/pydoclint/pull/130
--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
attributesFull Changelog: https://github.com/jsh9/pydoclint/compare/0.4.2...0.5.0
--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
attributesImprove DOC403 message by @jsh9 in https://github.com/jsh9/pydoclint/pull/129
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.4.1...0.4.2
Fix double quotes in Literal type hint by @jsh9 in https://github.com/jsh9/pydoclint/pull/123
--src by @jsh9 in https://github.com/jsh9/pydoclint/pull/124Full Changelog: https://github.com/jsh9/pydoclint/compare/0.4.0...0.4.1
Literal["foo"]
could produce a false positive DOC203 violation.--srcInclude args with different type hints in DOC105 msg by @jsh9 in https://github.com/jsh9/pydoclint/pull/120
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.3.10...0.4.0
Documenting tool integration by @jamesbraza in https://github.com/jsh9/pydoclint/pull/104
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.3.9...0.3.10
--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 terminalFix false positive DOC203 in property methods by @jsh9 in https://github.com/jsh9/pydoclint/pull/115
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.3.8...0.3.9
DOC203 when there is no docstring return section
for methods with @property decoratorFix prepended escape char handling by @jsh9 in https://github.com/jsh9/pydoclint/pull/94
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.3.7...0.3.8
Disable parallel mode in pre-commit by @jsh9 in https://github.com/jsh9/pydoclint/pull/93
Full Changelog: https://github.com/jsh9/pydoclint/compare/0.3.6...0.3.7
One column per quarter.