Add check-arg-defaults

Author: jsh9

CHANGELOG.md

@@ -1,11 +1,16 @@
 # Change Log
 
-## [Unpublished]
+## [0.7.0] - 2025-09-01
 
+- Added
+  - A new config option `--check-arg-default` (default: False) to check
+    consistency of argument defaults (between docstring and function signature)
 - Changed
   - Replace `Prettier` with: [yamlfix](https://github.com/lyz-code/yamlfix),
     [mdformat](https://github.com/hukkin/mdformat), and
     [pretty-format-json](https://github.com/pre-commit/pre-commit-hooks?tab=readme-ov-file#pretty-format-json)
+- Full diff
+  - https://github.com/jsh9/pydoclint/compare/0.6.11...0.7.0
 
 ## [0.6.11] - 2025-08-31
 

CLAUDE.md

@@ -1,15 +1,108 @@
-# pydoclint Project Conventions
+# CLAUDE.md
 
-## Code Style
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+## pydoclint Project Conventions
+
+### Code Style
 
 - Use camelCase for function and variable names (not snake_case)
 
-## Branch Naming
+### Branch Naming
 
 - Format: `yyyy-mm-dd-What-this-branch-does`
 
-## Commit Messages & PR Titles
+### Commit Messages & PR Titles
 
 - Use action verbs (imperative mood), not past tense
 - Good: "Add feature", "Fix bug"
 - Bad: "Added feature", "Fixed bug"
+
+## Development Commands
+
+### Testing
+
+- `pytest --tb=long .` - Run all tests with detailed traceback
+- `tox` - Run full test suite across multiple Python versions
+- `tox -e py311` - Run tests on specific Python version (py39, py310, py311,
+  py312, py313)
+
+### Code Quality
+
+- `mypy pydoclint/` - Type checking
+- `muff format --diff --config=muff.toml pydoclint tests` - Format checking
+  (use `--diff` to avoid accidental formatting)
+- `flake8 .` - Basic linting
+- `pydoclint --config=pyproject.toml .` - Self-check using pydoclint
+- `pre-commit run -a` - Run all pre-commit hooks
+
+### Specialized Tox Commands
+
+- `tox -e mypy` - Type checking only
+- `tox -e muff` - Format checking only
+- `tox -e check-self` - Run pydoclint on itself
+- `tox -e flake8-basic` - Basic flake8 checks
+- `tox -e flake8-misc` - Additional flake8 plugins
+- `tox -e flake8-docstrings` - Docstring style checks
+- `tox -e pre-commit` - Pre-commit hooks (skips muff formatter)
+
+### Running a Single Test
+
+Use pytest with specific test file or test function:
+
+```bash
+pytest tests/test_main.py
+pytest tests/test_main.py::test_function_name
+```
+
+## Architecture Overview
+
+Pydoclint is a Python docstring linter that checks docstring sections against
+function signatures. The core architecture consists of:
+
+### Main Components
+
+- **main.py**: CLI entry point using Click, handles command-line options and
+  orchestrates linting
+- **visitor.py**: AST visitor that traverses Python code and applies docstring
+  checks
+- **flake8_entry.py**: Plugin interface for flake8 integration
+- **parse_config.py**: Configuration parsing from pyproject.toml and other
+  sources
+- **baseline.py**: Baseline functionality for gradual adoption
+
+### Utils Package Structure
+
+- **arg.py/argList.py**: Function argument representation and handling
+- **doc.py**: Docstring parsing and representation
+- **return_arg.py/yield_arg.py**: Return/yield argument handling
+- **violation.py**: Violation representation and reporting
+- **astTypes.py**: AST type definitions and utilities
+- **generic.py**: Common utility functions
+- **method_type.py**: Method type detection (regular, static, class, property)
+- **parse_docstring.py**: Core docstring parsing for numpy/google/sphinx styles
+- **return_yield_raise.py**: Analysis of return/yield/raise statements in
+  function bodies
+- **visitor_helper.py**: Helper functions for the main visitor
+
+### Supported Docstring Styles
+
+- **Numpy**: numpydoc format
+- **Google**: Google-style docstrings
+- **Sphinx**: Sphinx/reStructuredText format
+
+### Key Features
+
+- Fast AST-based analysis (thousands of times faster than darglint)
+- Supports type hint checking against docstring parameter types
+- Class attribute documentation checking
+- Baseline mode for gradual adoption in existing codebases
+- Both standalone CLI and flake8 plugin modes
+
+### Test Structure
+
+- `tests/data/` contains test cases organized by docstring style (google,
+  numpy, sphinx, edge_cases)
+- Tests use real Python files with expected violations rather than string-based
+  tests

README.md

@@ -26,7 +26,9 @@ Currently, _pydoclint_ supports three docstring styles:
 [numpy](https://numpydoc.readthedocs.io/en/latest/format.html),
 [Google](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html),
 and
-[Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html).
+[Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html),
+with some
+[minor style deviations](https://jsh9.github.io/pydoclint/style_deviations.html).
 
 Another note: this linter and [pydocstyle](https://github.com/PyCQA/pydocstyle)
 serves complementary purposes. It is recommended that you use both together.

docs/config_options.md

@@ -31,11 +31,12 @@ page:
 - [18. `--only-attrs-with-ClassVar-are-treated-as-class-attrs` (shortform: `-oawcv`, default: `False`)](#18---only-attrs-with-classvar-are-treated-as-class-attrs-shortform--oawcv-default-false)
 - [19. `--should-document-star-arguments` (shortform: `-sdsa`, default: `True`)](#19---should-document-star-arguments-shortform--sdsa-default-true)
 - [20. `--check-style-mismatch` (shortform: `-csm`, default: `False`)](#20---check-style-mismatch-shortform--csm-default-false)
-- [21. `--baseline`](#21---baseline)
-- [22. `--generate-baseline` (default: `False`)](#22---generate-baseline-default-false)
-- [23. `--auto-regenerate-baseline` (shortform: `-arb`, default: `True`)](#23---auto-regenerate-baseline-shortform--arb-default-true)
-- [24. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)](#24---show-filenames-in-every-violation-message-shortform--sfn-default-false)
-- [25. `--config` (default: `pyproject.toml`)](#25---config-default-pyprojecttoml)
+- [21. `--check-arg-defaults` (shortform: `-cad`, default: `False`)](#21---check-arg-defaults-shortform--cad-default-false)
+- [22. `--baseline`](#22---baseline)
+- [23. `--generate-baseline` (default: `False`)](#23---generate-baseline-default-false)
+- [24. `--auto-regenerate-baseline` (shortform: `-arb`, default: `True`)](#24---auto-regenerate-baseline-shortform--arb-default-true)
+- [25. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)](#25---show-filenames-in-every-violation-message-shortform--sfn-default-false)
+- [26. `--config` (default: `pyproject.toml`)](#26---config-default-pyprojecttoml)
 
 <!--TOC-->
 
@@ -234,7 +235,13 @@ If True, check that style specified in --style matches the detected style of
 the docstring. If there is a mismatch, DOC003 will be reported. Setting this to
 False will silence all DOC003 violations.
 
-## 21. `--baseline`
+## 21. `--check-arg-defaults` (shortform: `-cad`, default: `False`)
+
+If True, docstring type hints should contain default values consistent with the
+function signature. If False, docstring type hints should not contain default
+values. (Only applies to numpy style for now.)
+
+## 22. `--baseline`
 
 Baseline allows you to remember the current project state and then show only
 new violations, ignoring old ones. This can be very useful when you'd like to
@@ -256,20 +263,20 @@ If `--generate-baseline` is not passed to _pydoclint_ (the default is `False`),
 _pydoclint_ will read your baseline file, and ignore all violations specified
 in that file.
 
-## 22. `--generate-baseline` (default: `False`)
+## 23. `--generate-baseline` (default: `False`)
 
 Required to use with `--baseline` option. If `True`, generate the baseline file
 that contains all current violations.
 
-## 23. `--auto-regenerate-baseline` (shortform: `-arb`, default: `True`)
+## 24. `--auto-regenerate-baseline` (shortform: `-arb`, default: `True`)
 
 If it's set to True, _pydoclint_ will automatically regenerate the baseline
 file every time you fix violations in the baseline and rerun _pydoclint_.
 
 This saves you from having to manually regenerate the baseline file by setting
 `--generate-baseline=True` and run _pydoclint_.
 
-## 24. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)
+## 25. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)
 
 If False, in the terminal the violation messages are grouped by file names:
 
@@ -303,7 +310,7 @@ This can be convenient if you would like to click on each violation message and
 go to the corresponding line in your IDE. (Note: not all terminal app offers
 this functionality.)
 
-## 25. `--config` (default: `pyproject.toml`)
+## 26. `--config` (default: `pyproject.toml`)
 
 The full path of the .toml config file that contains the config options. Note
 that the command line options take precedence over the .toml file. Look at this

docs/index.md

@@ -26,7 +26,9 @@ Currently, _pydoclint_ supports three docstring styles:
 [numpy](https://numpydoc.readthedocs.io/en/latest/format.html),
 [Google](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html),
 and
-[Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html).
+[Sphinx](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html),
+with some
+[minor style deviations](https://jsh9.github.io/pydoclint/style_deviations.html).
 
 Another note: this linter and [pydocstyle](https://github.com/PyCQA/pydocstyle)
 serves complementary purposes. It is recommended that you use both together.

docs/notes_for_users.md

@@ -4,7 +4,7 @@
 
 <!--TOC-->
 
-- [1. Why is _pydoclint_ so much faster than _darglint_](#1-why-is-pydoclint-so-much-faster-than-darglint)
+- [1. Why is _pydoclint_ so much faster than _darglint_, hhe](#1-why-is-pydoclint-so-much-faster-than-darglint-hhe)
 - [2. Cases that _pydoclint_ is not designed to handle](#2-cases-that-pydoclint-is-not-designed-to-handle)
 - [3. Notes on writing type hints](#3-notes-on-writing-type-hints)
 - [4. Notes on writing Sphinx-style docstrings](#4-notes-on-writing-sphinx-style-docstrings)
@@ -15,7 +15,7 @@
 
 <!--TOC-->
 
-## 1. Why is _pydoclint_ so much faster than _darglint_
+## 1. Why is _pydoclint_ so much faster than _darglint_, hhe
 
 Based on the best understanding of the authors of _pydoclint_, here are some
 reasons (this may not be an exhaustive list):
@@ -129,51 +129,15 @@ in order to achieve fast linting and reduce ambiguity.
 
 ## 4. Notes on writing Sphinx-style docstrings
 
-The
-[official Sphinx documentation](https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html)
-does not explicitly state this, so it is unclear what header to use to specify
-the type of what a function yields.
-
-Many people use `rtype`, but the authors of _pydoclint_ find it difficult to
-differentiate the type of return value and the type of yield value.
-
-Therefore, _pydoclint_ expects the convention of `ytype` for yield types. This
-is actually common practice, as evident from a code search on GitHub:
-https://github.com/search?q=%3Aytype%3A+language%3APython&type=code&l=Python
+See
+[minor style deviations](https://jsh9.github.io/pydoclint/style_deviations.html#sphinx)
+for more details.
 
 ## 5. Notes for Google-style users
 
-By default, _pydoclint_ checks return type and yield type consistencies, and it
-also requires argument types in the docstring. In other words, by _pydoclint_'s
-default, this is an acceptable Google-style docstring:
-
-```python
-"""
-This is a function.
-
-Args:
-    arg1 (int): Arg 1
-    arg2 (float): Arg 2
-    arg3 (Optional[Union[float, int, str]]): Arg 3
-
-Returns:
-    int: Result
-"""
-```
-
-However, this may not be the convention of a lot of Google-style docstring
-writers.
-
-But do not worry: here are some config options to tweak:
-
-- `--arg-type-hints-in-docstring`: you can set it to `False`
-- `--check-return-types`: you can set it to `False`
-- `--check-yield-types`: you can set it to `False`
-
-[Here](https://jsh9.github.io/pydoclint/config_options.html) are all the
-configurable options of _pydoclint_, and
-[here](https://jsh9.github.io/pydoclint/how_to_config.html) is how to configure
-_pydoclint_.
+See
+[minor style deviations](https://jsh9.github.io/pydoclint/style_deviations.html#google)
+for more details.
 
 ## 6. How to adopt _pydoclint_ more easily in legacy projects