[`pydoclint`] Add `docstring-missing-parameter` and `docstring-extraneous-parameter` (`DOC101`, `DOC102`) #13280

augustelalande · 2024-09-07T23:57:55Z

Summary

Add docstring-missing-parameter and docstring-extraneous-parameter (DOC101, DOC102). These rules check that the parameters defined in a functions signature match thos defined in the docstring.

Part of #12434.

Test Plan

Test cases added.

codspeed-hq · 2024-09-08T00:15:54Z

CodSpeed Performance Report

Merging #13280 will not alter performance

_{Comparing augustelalande:doc10x (8639117) with main (ec86a4e)}

Summary

✅ 42 untouched

github-actions · 2024-09-08T00:23:28Z

`ruff-ecosystem` results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

ℹ️ ecosystem check detected linter changes. (+12319 -13 violations, +0 -0 fixes in 6 projects; 49 projects unchanged)

apache/airflow (+7445 -0 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --ignore RUF9 --no-fix --output-format concise --preview --select ALL

+ airflow-core/docs/conf.py:147:5: DOC101 Parameter `exclude_patterns` missing from the docstring
+ airflow-core/src/airflow/api/common/delete_dag.py:44:5: DOC101 These parameters are missing from the docstring: `dag_id`, `keep_records_in_log`, `session`
+ airflow-core/src/airflow/api/common/mark_tasks.py:114:5: DOC101 These parameters are missing from the docstring: `dag`, `state`, `task_ids`, `run_ids`
+ airflow-core/src/airflow/api/common/mark_tasks.py:128:5: DOC101 These parameters are missing from the docstring: `tasks`, `downstream`, `upstream`
+ airflow-core/src/airflow/api/common/mark_tasks.py:146:5: DOC101 These parameters are missing from the docstring: `dag`, `run_id`, `future`, `past`, `session`
+ airflow-core/src/airflow/api/common/mark_tasks.py:180:5: DOC101 These parameters are missing from the docstring: `dag_id`, `run_id`, `state`, `session`
+ airflow-core/src/airflow/api/common/mark_tasks.py:203:5: DOC101 These parameters are missing from the docstring: `dag`, `run_id`, `commit`, `session`
+ airflow-core/src/airflow/api/common/mark_tasks.py:264:5: DOC101 These parameters are missing from the docstring: `dag`, `run_id`, `commit`, `session`
+ airflow-core/src/airflow/api/common/mark_tasks.py:356:5: DOC101 These parameters are missing from the docstring: `new_state`, `dag`, `run_id`, `commit`, `session`
+ airflow-core/src/airflow/api/common/mark_tasks.py:387:5: DOC101 These parameters are missing from the docstring: `dag`, `run_id`, `commit`, `session`
+ airflow-core/src/airflow/api/common/mark_tasks.py:56:5: DOC101 These parameters are missing from the docstring: `tasks`, `run_id`, `upstream`, `downstream`, `future`, `past`, `state`, `commit`, `session`
+ airflow-core/src/airflow/api/common/trigger_dag.py:140:5: DOC101 These parameters are missing from the docstring: `dag_id`, `triggered_by`, `triggering_user_name`, `run_after`, `run_id`, `conf`, `logical_date`, `replace_microseconds`, `session`
+ airflow-core/src/airflow/api/common/trigger_dag.py:55:5: DOC101 These parameters are missing from the docstring: `dag_id`, `dag_bag`, `triggered_by`, `triggering_user_name`, `run_after`, `run_id`, `conf`, `logical_date`, `replace_microseconds`, `session`
+ airflow-core/src/airflow/api_fastapi/app.py:108:5: DOC101 These parameters are missing from the docstring: `config`, `testing`, `apps`
+ airflow-core/src/airflow/api_fastapi/app.py:147:5: DOC101 Parameter `app` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/app.py:172:5: DOC101 Parameter `app` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/auth/managers/base_auth_manager.py:100:9: DOC101 Parameter `token` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/auth/managers/base_auth_manager.py:116:9: DOC101 These parameters are missing from the docstring: `user`, `expiration_time_in_seconds`
+ airflow-core/src/airflow/api_fastapi/auth/managers/base_auth_manager.py:321:9: DOC101 These parameters are missing from the docstring: `requests`, `user`
+ airflow-core/src/airflow/api_fastapi/auth/managers/base_auth_manager.py:349:9: DOC101 These parameters are missing from the docstring: `user`, `method`, `session`
+ airflow-core/src/airflow/api_fastapi/auth/managers/base_auth_manager.py:370:9: DOC101 These parameters are missing from the docstring: `dag_ids`, `user`, `method`
+ airflow-core/src/airflow/api_fastapi/auth/managers/base_auth_manager.py:401:9: DOC101 Parameter `user` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/auth/managers/base_auth_manager.py:405:9: DOC101 Parameter `user` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/auth/managers/base_auth_manager.py:427:9: DOC101 Parameter `expiration_time_in_seconds` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/auth/managers/simple/routes/login.py:109:5: DOC101 Parameter `body` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/auth/managers/simple/routes/login.py:66:5: DOC101 Parameter `body` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/auth/managers/simple/routes/login.py:86:5: DOC101 Parameter `request` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/auth/managers/simple/services/login.py:36:9: DOC101 These parameters are missing from the docstring: `body`, `expiration_time_in_seconds`
+ airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py:146:9: DOC101 Parameter `kwargs` missing from the docstring
+ airflow-core/src/airflow/api_fastapi/auth/managers/simple/simple_auth_manager.py:325:9: DOC101 These parameters are missing from the docstring: `method`, `allow_role`, `user`, `allow_get_role`
... 7415 additional changes omitted for project

apache/superset (+1972 -11 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --ignore RUF9 --no-fix --output-format concise --preview --select ALL

+ RELEASING/changelog.py:107:9: DOC101 Parameter `git_log` missing from the docstring
+ RELEASING/changelog.py:335:5: DOC101 These parameters are missing from the docstring: `ctx`, `previous_version`, `current_version`
+ RELEASING/changelog.py:347:5: DOC101 Parameter `base_parameters` missing from the docstring
+ RELEASING/changelog.py:380:5: D400 First line should end with a period
- RELEASING/changelog.py:380:5: D400 First line should end with a period
+ RELEASING/changelog.py:380:5: D415 First line should end with a period, question mark, or exclamation point
- RELEASING/changelog.py:380:5: D415 First line should end with a period, question mark, or exclamation point
+ RELEASING/changelog.py:380:5: DOC101 These parameters are missing from the docstring: `base_parameters`, `csv`, `access_token`, `risk`
+ RELEASING/changelog.py:52:9: DOC101 Parameter `other` missing from the docstring
+ RELEASING/changelog.py:87:9: DOC101 Parameter `pr_number` missing from the docstring
... 1930 additional changes omitted for rule DOC101
... 1973 additional changes omitted for project

bokeh/bokeh (+342 -0 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --ignore RUF9 --no-fix --output-format concise --preview --select ALL

+ examples/advanced/extensions/parallel_plot/parallel_plot.py:15:5: DOC101 These parameters are missing from the docstring: `df`, `color`, `palette`
+ examples/interaction/js_callbacks/js_on_event.py:16:5: DOC101 These parameters are missing from the docstring: `div`, `attributes`
+ examples/models/gauges.py:33:5: DOC101 Parameter `val` missing from the docstring
+ examples/models/trail.py:20:5: DOC101 These parameters are missing from the docstring: `p1`, `p2`
+ examples/output/jupyter/push_notebook/Numba Image Example.ipynb:cell 22:3:5: DOC101 These parameters are missing from the docstring: `img`, `tmp`
+ examples/server/app/events_app.py:17:5: DOC101 These parameters are missing from the docstring: `div`, `attributes`
... 306 additional changes omitted for rule DOC101
+ src/bokeh/core/has_props.py:424:9: DOC102 These documented parameters are not in the function's signature: `json`, `models`, `setter(ClientSession`
+ src/bokeh/core/property/dataspec.py:449:9: DOC102 Documented parameter `name` is not in the function's signature
+ src/bokeh/core/property/descriptors.py:399:9: DOC102 These documented parameters are not in the function's signature: `json`, `models`
+ src/bokeh/core/property/descriptors.py:664:9: DOC102 Documented parameter `new` is not in the function's signature
... 332 additional changes omitted for project

langchain-ai/langchain (+1895 -2 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --ignore RUF9 --no-fix --output-format concise --preview

+ libs/cli/langchain_cli/cli.py:72:5: DOC101 These parameters are missing from the docstring: `port`, `host`
+ libs/cli/langchain_cli/dev_scripts.py:17:5: DOC101 These parameters are missing from the docstring: `config_keys`, `playground_type`
+ libs/cli/langchain_cli/namespaces/app.py:164:5: DOC101 These parameters are missing from the docstring: `dependencies`, `api_path`, `project_dir`, `repo`, `branch`, `pip`
+ libs/cli/langchain_cli/namespaces/app.py:317:5: DOC101 These parameters are missing from the docstring: `api_paths`, `project_dir`
+ libs/cli/langchain_cli/namespaces/app.py:364:5: DOC101 These parameters are missing from the docstring: `port`, `host`, `app`
+ libs/cli/langchain_cli/namespaces/app.py:65:5: DOC101 These parameters are missing from the docstring: `name`, `package`, `pip`, `noninteractive`
... 1866 additional changes omitted for rule DOC101
+ libs/core/langchain_core/beta/runnables/context.py:399:9: DOC102 These documented parameters are not in the function's signature: `_key`, `_value`
+ libs/core/langchain_core/beta/runnables/context.py:437:9: DOC102 These documented parameters are not in the function's signature: `_key`, `_value`
+ libs/core/langchain_core/callbacks/file.py:132:9: DOC102 Documented parameter `file` is not in the function's signature
+ libs/core/langchain_core/messages/ai.py:313:9: DOC102 Documented parameter `values` is not in the function's signature
... 1887 additional changes omitted for project

reflex-dev/reflex (+45 -0 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --ignore RUF9 --no-fix --output-format concise --preview

+ reflex/app.py:1780:5: DOC102 Documented parameter `_request` is not in the function's signature
+ reflex/app.py:1792:5: DOC102 Documented parameter `_request` is not in the function's signature
+ reflex/assets.py:38:5: DOC102 Documented parameter `_stack_level` is not in the function's signature
+ reflex/components/component.py:2919:9: DOC102 Documented parameter `_var_data` is not in the function's signature
+ reflex/event.py:1907:9: DOC102 Documented parameter `_var_data` is not in the function's signature
+ reflex/event.py:1994:9: DOC102 Documented parameter `_var_data` is not in the function's signature
... 28 additional changes omitted for rule DOC102
+ reflex/reflex.py:124:5: DOC101 These parameters are missing from the docstring: `name`, `template`, `ai`
+ reflex/reflex.py:136:5: DOC101 These parameters are missing from the docstring: `env`, `frontend`, `backend`, `frontend_port`, `backend_port`, `backend_host`
+ reflex/reflex.py:330:5: DOC101 These parameters are missing from the docstring: `env`, `frontend_only`, `backend_only`, `frontend_port`, `backend_port`, `backend_host`
+ reflex/reflex.py:364:5: DOC101 Parameter `dry` missing from the docstring
... 35 additional changes omitted for project

zulip/zulip (+620 -0 violations, +0 -0 fixes)

ruff check --no-cache --exit-zero --ignore RUF9 --no-fix --output-format concise --preview --select ALL

+ analytics/lib/fixtures.py:19:5: DOC101 These parameters are missing from the docstring: `days`, `business_hours_base`, `non_business_hours_base`, `growth`, `autocorrelation`, `spikiness`, `holiday_rate`, `frequency`, `partial_sum`, `random_seed`
+ analytics/migrations/0015_clear_duplicate_counts.py:8:5: DOC101 These parameters are missing from the docstring: `apps`, `schema_editor`
+ analytics/tests/test_counts.py:222:9: DOC101 These parameters are missing from the docstring: `table`, `arg_keys`, `arg_values`
+ confirmation/migrations/0016_realmcreationkey_to_realmcreationstatus.py:15:5: DOC101 These parameters are missing from the docstring: `apps`, `schema_editor`
+ confirmation/models.py:296:5: DOC101 These parameters are missing from the docstring: `user_profile`, `email_type`
+ confirmation/models.py:92:5: DOC101 These parameters are missing from the docstring: `confirmation_key`, `confirmation_types`, `mark_object_used`, `allow_used`
+ corporate/lib/activity.py:93:5: DOC101 Parameter `cursor` missing from the docstring
+ corporate/lib/stripe.py:1143:9: DOC101 Parameter `metadata` missing from the docstring
+ corporate/lib/stripe.py:386:5: DOC101 These parameters are missing from the docstring: `customer`, `plan_tier`
+ corporate/lib/stripe.py:5370:5: DOC101 Parameter `remote_server` missing from the docstring
... 610 additional changes omitted for project

... Truncated remaining completed project reports due to GitHub comment length restrictions

Changes by rule (8 rules affected)

code	total	+ violation	- violation
DOC101	12194	12194	0
DOC102	112	112	0
D415	8	4	4
D202	4	2	2
D200	4	2	2
D212	4	2	2
DOC201	4	2	2
D400	2	1	1

MichaReiser

This is great. I haven't gone through the ecossytem results but I think there are a few cases where we don't parse the parameter names correctly.

crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs

...s/ruff_linter__rules__pydoclint__tests__docstring-extraneous-parameter_DOC102_google.py.snap

crates/ruff_linter/resources/test/fixtures/pydoclint/DOC101_google.py

Co-authored-by: Micha Reiser <[email protected]>

MichaReiser · 2024-09-10T22:19:38Z

Hmm, there's an overlap with https://docs.astral.sh/ruff/rules/undocumented-param/. Not quiet sure how to resolve the overlap.

augustelalande · 2024-09-10T22:23:30Z

UndocumentedParam in its current implimentation is restricted to google-style docstring only. I would suggest deprecating that rule in favor of this one, since it makes more sense as part of the pydoclint package.

MichaReiser · 2024-09-10T22:24:55Z

UndocumentedParam in its current implimentation is restricted to google-style docstring only. I would suggest deprecating that rule in favor of this one, since it makes more sense as part of the pydoclint package.

That's fair. But the google style one is less strict than the new one. It doesn't require that you document the parameters of all functions. It only requires that the parameters match the function's parameters if there's an Arguments section.

augustelalande · 2024-09-10T22:36:32Z

We could add an option to only highlight violations when a section is present. I tried something similar #13302.

AllanChain · 2025-01-03T10:58:11Z

This PR has been pending for some time. Just want to gently bump this thread to see if there are any updates or if there's anything blocking its progress. This rule would be very useful, so I'm eager to see it merged.

crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs

...s/ruff_linter__rules__pydoclint__tests__docstring-extraneous-parameter_DOC102_google.py.snap

augustelalande · 2025-02-06T15:20:01Z

Is there anymore feedback here?

mschoettle · 2025-03-18T20:28:54Z

Would love to have these extra rules!

dobeerman-sts · 2025-08-22T07:07:05Z

Still in progress?

augustelalande · 2025-08-23T19:58:49Z

I am waiting for feedback from the astral team

dobeerman-sts · 2025-08-24T14:24:01Z

I am waiting for feedback from the astral team

@augustelalande meantime, would you mind to fix merge conflicts? ;)

Samoed · 2025-08-25T06:49:21Z

Maybe tag maintainer for review?

ntBre · 2025-09-11T13:08:36Z

DOC102 came up today in #20346, so I was looking at this PR again. I think I agree with @MichaReiser here that it could make sense to separate the two rules into separate PRs. I don't think we have any overlapping rules with DOC102, so it may be easier to get that part landed on its own.

Micha will be back next week and can weigh in then, but the conflict between DOC101 and D417 seems like the main blocker to me from my read of the thread here.

augustelalande · 2025-09-12T04:14:04Z

@ntBre I thought the blocker was resolved by @charliermarsh's comment

ntBre · 2025-09-12T13:07:30Z

I think that's the long-term solution, but it's been almost a year, so we'd need to double check that everyone is still on board with that plan. If we have two heavily overlapping rules, we need to think about a conflict warning, a deprecation plan, etc. That only affects DOC101, so I thought splitting the two up would be an easy way to defer that decision and have a shorter path to DOC102.

It would also make it easier for reviewers coming back to this (or a potential new reviewer like me) to look at two PRs half this size.

We can wait and see what Micha thinks, though. He might have a better idea :)

…20376) ## Summary Implement `docstring-extraneous-parameter` (`DOC102`). This rule checks that all parameters present in a functions docstring are also present in its signature. Split from #13280, per this [comment](#13280 (comment)). Part of #12434. ## Test Plan Test cases added. --------- Co-authored-by: Brent Westbrook <[email protected]>

augustelalande added 6 commits August 5, 2024 00:35

create violations

2140312

Merge branch 'main' into doc10x

4d6510c

more work

7316554

parse parameters from docstring

928c0c7

finish implementation

62d447f

clippy and doc

d45967f

MichaReiser added rule Implementing or modifying a lint rule preview Related to preview mode features labels Sep 10, 2024

MichaReiser reviewed Sep 10, 2024

View reviewed changes

augustelalande added 7 commits September 10, 2024 16:43

group missing params into one violation

04a91fe

simplify fix message

7c60ddd

better extraction of google params

dcc0065

add numpy test without types

352c815

simply signature parameter extraction

6c8cc99

use dummy_variable_rgx

65b9b5b

better extraction of google params

993deb8

MichaReiser reviewed Sep 10, 2024

View reviewed changes

Nit

4d47b2d

Co-authored-by: Micha Reiser <[email protected]>

augustelalande force-pushed the doc10x branch from 7b96439 to 4d47b2d Compare September 10, 2024 22:16

Nit

55aa072

Nit

888bcac

augustelalande added 2 commits September 10, 2024 18:25

fix

f0f6ef1

update violation message

03a1182

seperate PR

76c1e5f

jamesfricker mentioned this pull request Nov 12, 2024

[pydoclint] Implement fewer arguments (DOC101) #14286

Closed

dhruvmanila reviewed Jan 6, 2025

View reviewed changes

dhruvmanila requested a review from MichaReiser January 6, 2025 10:51

augustelalande added 9 commits January 6, 2025 11:34

fix typo

2d35922

add comment and test for classmethod

e0b812e

target section header if available

2a81315

format

12ec276

Merge branch 'main' into doc10x

85818bc

clippy

491fe02

use indentation from first line

37c4b86

Merge branch 'main' into doc10x

e0b12ca

fix test errors

9d12e93

MichaReiser mentioned this pull request Mar 4, 2025

[pydocstyle]: d417 being ignored with convention=google #16477

Closed

ntBre mentioned this pull request Mar 31, 2025

Implement rules in darglint #458

Open

augustelalande added 2 commits August 24, 2025 10:49

Merge branch 'main' into doc10x

9f95db6

update snaps

8639117

augustelalande requested a review from dhruvmanila August 25, 2025 15:15

augustelalande mentioned this pull request Sep 13, 2025

[pydoclint] Implement docstring-extraneous-parameter (DOC102) #20376

Merged

augustelalande mentioned this pull request Oct 25, 2025

[pydoclint] Implement docstring-missing-parameter (DOC101) #21076

Open

Uh oh!

[pydoclint] Add docstring-missing-parameter and docstring-extraneous-parameter (DOC101, DOC102) #13280

Are you sure you want to change the base?

[pydoclint] Add docstring-missing-parameter and docstring-extraneous-parameter (DOC101, DOC102) #13280

Uh oh!

Conversation

augustelalande commented Sep 7, 2024

Summary

Test Plan

Uh oh!

codspeed-hq bot commented Sep 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #13280 will not alter performance

Summary

Uh oh!

github-actions bot commented Sep 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ruff-ecosystem results

Linter (stable)

Linter (preview)

Uh oh!

MichaReiser left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MichaReiser commented Sep 10, 2024

Uh oh!

augustelalande commented Sep 10, 2024

Uh oh!

MichaReiser commented Sep 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

augustelalande commented Sep 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AllanChain commented Jan 3, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

augustelalande commented Feb 6, 2025

Uh oh!

mschoettle commented Mar 18, 2025

Uh oh!

dobeerman-sts commented Aug 22, 2025

Uh oh!

augustelalande commented Aug 23, 2025

Uh oh!

dobeerman-sts commented Aug 24, 2025

Uh oh!

Samoed commented Aug 25, 2025

Uh oh!

ntBre commented Sep 11, 2025

Uh oh!

augustelalande commented Sep 12, 2025

Uh oh!

ntBre commented Sep 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

[`pydoclint`] Add `docstring-missing-parameter` and `docstring-extraneous-parameter` (`DOC101`, `DOC102`) #13280

[`pydoclint`] Add `docstring-missing-parameter` and `docstring-extraneous-parameter` (`DOC101`, `DOC102`) #13280

codspeed-hq bot commented Sep 8, 2024 •

edited

Loading

github-actions bot commented Sep 8, 2024 •

edited

Loading

`ruff-ecosystem` results

MichaReiser commented Sep 10, 2024 •

edited

Loading

augustelalande commented Sep 10, 2024 •

edited

Loading