Package: pydoclint
pydoclintPydoclintis a Python docstring linter to check whether a docstring's
sections (arguments, returns, raises, ...) match the function signature or
function implementation.It runs really fast. In fact, it can be thousands of times faster thandarglint(or its maintained forkdarglint2).Here is a comparison of linting time on some famous Python projects:pydoclintdarglintnumpy2.0 sec49 min 9 sec (1,475x slower)scikit-learn2.4 sec3 hr 5 min 33 sec (4,639x slower)Additionally,pydoclintcan detect some quite a few style violations that
darglint cannot.Currently,pydoclintsupports three docstring styles:numpy,Google,
andSphinx.Another note: this linter andpydocstyleserves complementary purposes. It is recommended that you use both together.The full documentation ofpydoclint(including this README) can be found
here:https://jsh9.github.io/pydoclintThe corresponding Github repository ofpydoclintis:https://github.com/jsh9/pydoclintTable of Contents1. Installation2. Usage2.1. As a native command line tool2.2. As aflake8plugin2.3. As a pre-commit hook2.4. Native vsflake82.5. How to configurepydoclint2.6. How to ignore certain violations inflake8mode3. Style violation codes4. Notes for users5. Notes for developers1. InstallationTo install only the nativepydoclinttooling, run this command:pip install pydoclintTo usepydoclintas aflake8plugin, please run this command, which will
also installflake8to the current Python environment:pip install pydoclint[flake8]Note thatpydoclintcurrently only supports Python 3.8 and above. (Python 3.7
support may be added if there are interests and requests.)2. Usage2.1. As a native command line toolpydoclint <FILE_OR_FOLDER>Replace<FILE_OR_FOLDER>with the file/folder names you want, such as..2.2. As aflake8pluginOnce you installpydoclintyou will have also installedflake8. Then you
can run:flake8 --select=DOC <FILE_OR_FOLDER>If you don't include--select=DOCin your command,flake8will also run
other built-inflake8linters on your code.2.3. As a pre-commit hookpydoclintis configured forpre-commitand can be
set up as a hook with the following.pre-commit-config.yamlconfiguration:-repo:https://github.com/jsh9/pydoclintrev:<latest_tag>hooks:-id:pydoclintargs:[--style=google,--check-return-types=False]You will need to installpre-commitand runpre-commit install.2.4. Native vsflake8Should I usepydoclintas a native command line tool or aflake8plugin?
Here's comparison:ProsConsNative toolSlightly faster; supports "baseline" [*]No inline or project-wide omission support right now [**]flake8pluginSupports inline or project-wide omissionSlightly slower because other flake8 plugins are run together*) "Baseline" allows you to log the current violation state of your existing
project, making adoption ofpydoclintmuch easier.**) This feature may be added in the near future2.5. How to configurepydoclintPlease read this page:How to configurepydoclint2.6. How to ignore certain violations inflake8modePlease read this page:How to ignore certain violations3. Style violation codespydoclintcurrently has 6 categories of style violation codes:DOC0xx: Docstring parsing issuesDOC1xx: Violations about input argumentsDOC2xx: Violations about return argument(s)DOC3xx: Violations about class docstring and class constructorDOC4xx: Violations about "yield" statementsDOC5xx: Violations about "raise" statementsFor detailed explanations of each violation code, please read this page:pydoclintstyle violation codes.4. Notes for usersIf you'd like to usepydoclintfor your project, it is recommended that you
read these additional noteshere.Specifically, there is a section in the additional notes on how to easily adoptpydoclintfor existing legacy projects.5. Notes for developersIf you'd like to contribute to the code base ofpydoclint, thank you!This guidecan
hopefully help you get familiar with the code base faster.