chore: replace darglint with pydoclint#45
Conversation
Migrate from archived darglint to pydoclint per updated standards manifest. Replaces [tool.darglint] config and local hook with the upstream pydoclint pre-commit hook. Removes .darglint config file. Lockfile swaps darglint 1.8.1 for pydoclint 0.8.4. Posture: keep raises checks, require arg type hints, lenient on Returns/Yields missing sections. NOTE: 807 DOC findings exist across src/ and packages/ (histogram below); these require a separate docstring-fix pass. DOC histogram: DOC109/110x157, DOC203x174, DOC105x156, DOC301x33, DOC103/101x28, DOC503x19, DOC603x14, DOC605x11, DOC502x10, DOC602x8, DOC601x5, DOC501x4, DOC107x2, DOC106x1. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 29 minutes and 4 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (16)
WalkthroughThis PR replaces Darglint with Pydoclint for docstring validation and standardizes docstring formatting across the codebase. The tool migration updates dependencies and configuration, while docstring changes introduce consistent type-annotated parameter and return value documentation throughout multiple packages. ChangesDocstring Validation Tool Migration and Standardization
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested labels
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Migrates docstring argument validation from the archived darglint to the actively maintained pydoclint per updated standards (TOOL-007/PC-006/TOOL-013). The configuration keeps raises checks enabled and remains lenient on Returns/Yields sections, matching the previous darglint posture. The PR description notes 807 existing docstring findings to be addressed in a follow-on PR.
Changes:
- Swap
darglint>=1.8.1forpydoclint>=0.8.4inpyproject.tomldev deps and replace[tool.darglint]with[tool.pydoclint](google style, raises enabled, lenient Returns/Yields). - Replace local
darglintpre-commit hook with the upstreamjsh9/pydoclinthook pinned to 0.8.4, and removedarglintfrom the CIskip:list. - Delete the legacy
.darglintfile and updateuv.lock(remove darglint, add pydoclint + docstring-parser-fork).
Reviewed changes
Copilot reviewed 3 out of 4 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
pyproject.toml |
Replaces darglint dep and config block with pydoclint equivalent (google style, type-hint checks, lenient returns/yields). |
.pre-commit-config.yaml |
Switches from local darglint hook to upstream pydoclint hook; removes darglint from CI skip list. |
.darglint |
Removes the legacy darglint config file (config now lives in pyproject.toml). |
uv.lock |
Drops darglint 1.8.1; adds pydoclint 0.8.4 and its docstring-parser-fork transitive dep. |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Add argument and return type hints to docstrings in src/python_libs to match function signatures exactly. Move __init__ argument docs into the class docstring Args sections per pydoclint DOC301 guidance. Document the pydantic model_config class attribute without a type hint (the assignment carries no annotation). src/ now reports zero pydoclint violations. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add argument and return type hints to docstrings to match signatures exactly. Remove ImportError from generate_image Raises section: it is raised in the _get_genai helper, not directly in the function body, so pydoclint does not count it. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add argument and return type hints to docstrings to match signatures exactly. Move GCSClient.__init__ argument docs into the class docstring. Remove Raises entries for exceptions raised only in helper methods (FileNotFoundError via _validate_local_path) and drop the Raises section from upload_directory which has no direct raise statements. Document the broad re-raise in _get_or_create_bucket. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add argument and return type hints to docstrings and move __init__ argument docs into class docstrings. Document pydantic model fields with their annotated types. Refactor CloudflareAPIClient._handle_api_error to NoReturn (it always raises) and drop the unreachable bare re-raises so the Raises sections reflect the exceptions actually raised in each body: delegating methods document none, methods that raise CloudflareConflict- Error directly keep that entry. Behavior is unchanged; 83 cloudflare-api tests pass. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
coderabbitai
Bot
added
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/gcs-utilities/src/gcs_utilities/client.py`:
- Around line 51-53: Update the GCSClient class docstring to list all exceptions
that __init__ can raise: add GCSConfigError for missing credentials and
GCSNotFoundError for missing bucket when auto-create is false alongside the
existing GCSAuthError; locate the constructor GCSClient.__init__ and ensure the
"Raises:" section mentions GCSAuthError, GCSConfigError, and GCSNotFoundError
with short descriptions matching the actual error conditions.
- Around line 178-179: Update the _get_or_create_bucket docstring to stop
listing a broad Exception: instead document the actual exceptions the function
can raise—explicitly mention that it re-raises GCSNotFoundError (when caught by
the broad handler) and raises GCSAuthError for authentication failures; adjust
the Raises section text to accurately describe those two exception cases and
remove the generic Exception entry so callers know the precise error types to
handle.
In `@packages/gemini-image/src/gemini_image/generator.py`:
- Around line 92-94: The docstring for generate_image currently only documents
ValueError but _get_genai can raise ImportError when the google-genai dependency
is missing; update the generate_image docstring (the Raises section) to include
ImportError with a brief description like "If google-genai is not installed or
cannot be imported" and ensure the wording references the call to _get_genai so
readers know the missing-dependency case is covered.
In `@pyproject.toml`:
- Around line 663-665: The pyproject.toml contains invalid pydoclint option
keys: replace the unsupported keys require-return-section-when-returning-values
and require-yield-section-when-yielding-values with the correct documented keys
require-return-section-when-returning-nothing and
require-yield-section-when-yielding-nothing respectively so the pydoclint
settings take effect; update the entries in the [tool.pydoclint] table (the two
key names shown) to the corrected names and preserve the boolean values you
intended.
In `@src/python_libs/core/config.py`:
- Line 17: Update the Attributes docstring entry for model_config to include an
explicit type annotation; replace the current line "model_config: Pydantic
settings configuration." with something like "model_config (dict): Pydantic
settings configuration." (or "model_config (Mapping[str, Any]): Pydantic
settings configuration." if you prefer a more generic type) so the Attributes
section consistently lists types for all attributes and follows the Google-style
docstring convention.
In `@src/python_libs/utils/logging.py`:
- Around line 44-53: Add missing "Returns" and "Raises" sections to the
Google-style docstrings for setup_logging and log_performance: update the
docstring for setup_logging to include a Returns clause (e.g., returning the
configured logging.Logger or None) and a Raises clause documenting any
exceptions that can be propagated during logger configuration (e.g., ValueError
for invalid level or OSError for handler setup), and update log_performance
docstring similarly to state what it returns (if anything) and which exceptions
it may raise (e.g., KeyError or RuntimeError if context or timer retrieval
fails); ensure the exact function names setup_logging and log_performance are
updated and the wording matches existing Args style and project docstring
policy.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: d65e5692-9dde-418c-a83a-c83484dad484
⛔ Files ignored due to path filters (1)
uv.lockis excluded by!**/*.lock,!**/*.lock
📒 Files selected for processing (13)
.darglint.pre-commit-config.yamlpackages/cloudflare-api/src/cloudflare_api/client.pypackages/cloudflare-api/src/cloudflare_api/exceptions.pypackages/cloudflare-api/src/cloudflare_api/models.pypackages/cloudflare-api/src/cloudflare_api/settings.pypackages/gcs-utilities/src/gcs_utilities/client.pypackages/gemini-image/src/gemini_image/generator.pypackages/gemini-image/src/gemini_image/utils.pypyproject.tomlsrc/python_libs/core/config.pysrc/python_libs/core/exceptions.pysrc/python_libs/utils/logging.py
💤 Files with no reviewable changes (1)
- .darglint
| Raises: | ||
| GCSAuthError: If authentication fails. | ||
|
|
There was a problem hiding this comment.
Document all constructor exception paths.
GCSClient.__init__ can also surface GCSConfigError (missing credentials) and
GCSNotFoundError (missing bucket when auto-create is off), but the class docstring
currently lists only GCSAuthError.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/gcs-utilities/src/gcs_utilities/client.py` around lines 51 - 53,
Update the GCSClient class docstring to list all exceptions that __init__ can
raise: add GCSConfigError for missing credentials and GCSNotFoundError for
missing bucket when auto-create is false alongside the existing GCSAuthError;
locate the constructor GCSClient.__init__ and ensure the "Raises:" section
mentions GCSAuthError, GCSConfigError, and GCSNotFoundError with short
descriptions matching the actual error conditions.
| Exception: Re-raised if it is a GCSNotFoundError caught by the | ||
| broad handler. |
There was a problem hiding this comment.
Avoid broad Exception in Raises docstring.
_get_or_create_bucket re-raises GCSNotFoundError and otherwise raises
GCSAuthError; documenting a generic Exception is inaccurate and weakens API clarity.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/gcs-utilities/src/gcs_utilities/client.py` around lines 178 - 179,
Update the _get_or_create_bucket docstring to stop listing a broad Exception:
instead document the actual exceptions the function can raise—explicitly mention
that it re-raises GCSNotFoundError (when caught by the broad handler) and raises
GCSAuthError for authentication failures; adjust the Raises section text to
accurately describe those two exception cases and remove the generic Exception
entry so callers know the precise error types to handle.
| Raises: | ||
| ValueError: If model_key is invalid or API key is missing. | ||
| ImportError: If google-genai is not installed. | ||
|
|
There was a problem hiding this comment.
Document ImportError in generate_image Raises section.
generate_image() calls _get_genai() (Line 96), which raises ImportError when google-genai is unavailable, but the docstring only lists ValueError.
Suggested docstring fix
Raises:
ValueError: If model_key is invalid or API key is missing.
+ ImportError: If the google-genai package is not installed.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Raises: | |
| ValueError: If model_key is invalid or API key is missing. | |
| ImportError: If google-genai is not installed. | |
| Raises: | |
| ValueError: If model_key is invalid or API key is missing. | |
| ImportError: If the google-genai package is not installed. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/gemini-image/src/gemini_image/generator.py` around lines 92 - 94,
The docstring for generate_image currently only documents ValueError but
_get_genai can raise ImportError when the google-genai dependency is missing;
update the generate_image docstring (the Raises section) to include ImportError
with a brief description like "If google-genai is not installed or cannot be
imported" and ensure the wording references the call to _get_genai so readers
know the missing-dependency case is covered.
| require-return-section-when-returning-nothing = false | ||
| require-return-section-when-returning-values = false | ||
| require-yield-section-when-yielding-values = false |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
pydoclint 0.8.4 valid pyproject.toml options require-yield-section-when-yielding-nothing behavior on unknown config keys
💡 Result:
- pydoclint 0.8.4: valid [tool.pydoclint] options in pyproject.toml pydoclint reads configuration from TOML under a [tool.pydoclint] section (and the default config filename is pyproject.toml when using the --config option) [1][2]. The official “Configuration options” page lists the supported options (i.e., the ones you can set in TOML) [1]. 2) Option require-yield-section-when-yielding-nothing I could not find a page in the official documentation (config options list / violation codes / config how-to) that mentions a configuration key named require-yield-section-when-yielding-nothing for pydoclint 0.8.4. The official yield-related violation code DOC403 explains the policy “Yields section in the docstring, but there are no “yield” statements, or the return annotation is not a Generator/Iterator/Iterable” [3], but this does not map to a config key with that exact name in the config options list [1]. 3) Behavior on unknown config keys The official docs I found explain how to point pydoclint at a config file and that CLI flags take precedence, but they do not describe what happens when the TOML contains unknown keys (e.g., ignore vs warn vs error) [1][2]. So I can’t state the behavior with evidence from the sources I retrieved. What you can do - Verify the correct TOML key name against the official pydoclint configuration options list [1]. - If you need the exact unknown-key behavior, you’ll likely need to confirm it empirically (run pydoclint with a deliberately misspelled option in [tool.pydoclint]) or consult the project’s source/CLI parsing code; it wasn’t documented in the pages retrieved.
Citations:
- 1: https://jsh9.github.io/pydoclint/config_options.html
- 2: https://pypi.org/project/pydoclint/0.1.1/
- 3: https://jsh9.github.io/pydoclint/violation_codes.html
🌐 Web query:
pydoclint config_options require-return-section-when-returning-none require-return-section-when-returning-nothing
💡 Result:
In pydoclint, the configuration option is --require-return-section-when-returning-nothing (short form: -rrs) [1]. There is no official configuration option named "require-return-section-when-returning-none"; the aforementioned option covers both cases [1][2]. When this option is set to False (the default), a "return" section is not required in the docstring if the function implicitly returns None (e.g., has no return statement or uses -> None as the return annotation) or does not return at all (e.g., has a NoReturn type) [1][2]. Setting this option to True enforces the presence of a "return" section even in these scenarios [2][3].
Citations:
- 1: https://jsh9.github.io/pydoclint/config_options.html
- 2: https://pypi.org/project/pydoclint/0.0.11/
- 3: https://marketplace.visualstudio.com/items?itemName=boileaum.pydoclint
🌐 Web query:
pydoclint config_options require-yield-section-when-yielding-nothing
💡 Result:
The configuration option --require-yield-section-when-yielding-nothing in pydoclint controls whether a Yields section is required in a docstring when a function yields None [1]. Key details include: - Default Value: True [1]. - Short Form: -rys [1]. - Functionality: When set to True (default), pydoclint requires a Yields section in the docstring even if the function only yields None [1]. When set to False, a Yields section is not mandatory in the docstring if the function yields None [1]. This option helps maintain consistent documentation standards for generator functions [1]. If you are using pydoclint via a configuration file (such as pyproject.toml), you can explicitly set this to false if you prefer not to document trivial yields of None [1][2].
Citations:
- 1: https://jsh9.github.io/pydoclint/config_options.html
- 2: https://github.com/finite-sample/incline/blob/master/pyproject.toml
🌐 Web query:
pydoclint 0.8.4 unknown keys behavior click default_map ignore error
💡 Result:
There is no specific interaction between pydoclint 0.8.4 and Click's default_map regarding "unknown keys." Pydoclint is a docstring linter and does not interact with the command-line argument parsing or context configuration of the CLI applications it may be linting [1][2]. If you are experiencing issues with "unknown keys" in Click's default_map, this behavior is governed by the Click library itself, not pydoclint. In recent versions of Click, there have been updates to how default_map is processed, particularly regarding the handling of internal sentinels like UNSET [3][4][5] and multi-value parameter parsing [6][5]. If your application is failing due to unexpected keys or values in your default_map, consider the following standard Click troubleshooting steps: 1. Ignore Unknown Options: If the "unknown keys" are actually unknown command-line options that you want Click to ignore, you can use the context setting ignore_unknown_options=True [7][8]. context_settings=dict(ignore_unknown_options=True) 2. Verify default_map Structure: Ensure that the structure of your default_map matches the names of the parameters defined in your Click commands. Mismatches or unexpected data types (especially when using nargs > 1) can cause errors [9][6][5]. 3. Update Click: Recent versions of Click (such as 8.4.x) include fixes for edge cases involving UNSET in default_map and parameter processing [5]. Ensure you are using the latest stable version of Click to benefit from these improvements. Pydoclint is primarily concerned with validating docstring content against function signatures [1][2][10] and is unrelated to the runtime CLI argument processing logic.
Citations:
- 1: https://pypi.org/project/pydoclint/0.8.4/
- 2: https://jsh9.github.io/pydoclint/how_to_ignore.html
- 3: Reduce blast-radius of
UNSETindefault_mappallets/click#3240 - 4: Hide
Sentinel.UNSETvalues asNoneinlookup_default()pallets/click#3224 - 5: https://click.palletsprojects.com/en/stable/changes/
- 6: Split string values from
default_mapfor multi-value parameters pallets/click#3364 - 7: https://stackoverflow.com/questions/40002150/how-can-i-get-click-to-ignore-unknown-options-so-i-dont-have-to-define-pydevd-v
- 8: Any way to ignore unknown commands? pallets/click#1509
- 9: Modifying
default_mapin callback behaves differently between click 7.1.2 and 8.0.0 pallets/click#2745 - 10: Parameters not processed correctly for numpy style with incorrect underscoring jsh9/pydoclint#102
🌐 Web query:
pydoclint default_map [tool.pydoclint] click
💡 Result:
In pydoclint, the configuration key path [tool.pydoclint] is read from your TOML config file (by default, the CLI flag --config points to pyproject.toml), and the relevant options can include the ones you’d like to “map” (e.g., baseline, style, exclude, etc.). The tool does not appear to have a built-in setting named exactly default_map under [tool.pydoclint], nor is there evidence of a click-specific default_map [tool.pydoclint] mechanism in the official docs. What you can do instead (supported by docs): 1) Put options under a [tool.pydoclint] section in pyproject.toml (or another TOML file). 2) If needed, point pydoclint at a different config file using --config=... (command-line options take precedence over the TOML file). Example configuration (from the project’s docs): [tool.pydoclint] style = 'google' exclude = '.git|.tox|tests/data|some_script.py' require-return-section-when-returning-none = true The same docs describe that pydoclint’s CLI uses a --config option (defaulting to pyproject.toml) and that TOML values under [tool.pydoclint] are how you set configuration without passing flags on every run. [1][2][3] If you meant something else by “default_map” (for example, a Click feature named default_map), tell me where you saw the term (link or snippet) and I’ll map it precisely to the pydoclint/Click configuration behavior.
Citations:
- 1: https://jsh9.github.io/pydoclint/config_options.html
- 2: https://pypi.org/project/pydoclint/0.1.1/
- 3: https://pypi.org/project/pydoclint/0.1.2/
🌐 Web query:
pydoclint config_options unknown key handling
💡 Result:
pydoclint config “unknown key” handling: the public documentation for pydoclint’s TOML/pyproject configuration lists specific supported options, but it does not state any explicit policy for what happens when unknown/typo keys are present in the config. The only authoritative, source-backed behavior I could find is that pydoclint loads a TOML config file and may report errors related to configuration loading/parsing, but I did not find a documented “unknown key” mode (e.g., ignore vs error) in the provided sources. What you can conclude from the docs we found: - pydoclint’s configuration is TOML-based and the CLI config path defaults to pyproject.toml; CLI options take precedence over TOML [1]. - pydoclint advertises a fixed set of configuration options (e.g., many --... options are enumerated on the config options page), but the docs do not mention validation/strictness for unexpected keys [1]. If you need a definitive answer for your specific version, the most reliable approach is to test: add a deliberately invalid key under the pydoclint config section in pyproject.toml (e.g., unknown_option = true) and run pydoclint --config=pyproject.toml ... to see whether it errors or silently ignores it—because this behavior is not documented in the sources above. Note: a related GitHub issue log shows pydoclint loading “pyproject.toml” but the captured failure there is an InternalError in AST handling (not an unknown config key), so it doesn’t confirm the unknown-key policy [2].
Citations:
- 1: https://jsh9.github.io/pydoclint/config_options.html
- 2: pydoclint failing with InternalError after upgrade from 0.4.2 -> 0.5.3 jsh9/pydoclint#151
🌐 Web query:
site:jsh9.github.io/pydoclint "unknown" "tool.pydoclint"
💡 Result:
The term tool.pydoclint is not a standard identifier or configuration key. Instead, pydoclint is a Python docstring linter [1]. In the context of Python tooling and configuration, especially within pyproject.toml files or editor integrations like Neovim, references to this tool are typically made via the pydoclint package name or its associated executable pydoclint [1]. If you encountered "tool.pydoclint" in a configuration file or search result, it is likely a reference to the tool's settings within a configuration block (often formatted as [tool.pydoclint] if used in a project's pyproject.toml file) [2]. Key points regarding pydoclint: - Purpose: It is a high-speed Python docstring linter that checks if docstring sections (arguments, return values, raises, etc.) match the function signature or implementation [1]. - Usage: It can be used as a native command-line tool or as a flake8 plugin [1]. - Configuration: Options are typically defined in a.toml configuration file [2]. When integrating the tool into a project, configuration sections in a pyproject.toml are standard practice, which may explain the appearance of the string as [tool.pydoclint] [2]. - Integration: It can be integrated into various environments, such as Neovim (via null-ls) or used with pre-commit hooks [1][3]. If you are trying to configure the tool, you should look for the documentation on how to set options within your pyproject.toml file [2].
Citations:
- 1: https://jsh9.github.io/pydoclint/
- 2: https://jsh9.github.io/pydoclint/config_options.html
- 3: https://jsh9.github.io/pydoclint/notes_for_users.html
🌐 Web query:
pydoclint click default_map
💡 Result:
There is no direct relationship between pydoclint and Click's default_map feature; they belong to two different domains of Python development [1][2][3]. Pydoclint is a static analysis tool designed to lint Python docstrings [1][4][5]. It includes a configuration option called --check-arg-defaults (shortform -cad) [6], which checks whether the default values of function arguments are documented, but this is entirely separate from the Click library's mechanism for handling command-line argument defaults [1][7]. Click, on the other hand, uses context.default_map to provide default values for command-line parameters, often sourced from configuration files or environment variables [8][9]. If you are encountering confusion between the two, it may stem from the fact that both tools use Click for their own CLI implementations (pydoclint uses Click to define its own command-line interface) [3][5], or perhaps from a misunderstanding of the term "default_map" in the context of Click versus the "check-arg-defaults" configuration flag in pydoclint [9][6].
Citations:
- 1: https://pypi.org/project/pydoclint/0.7.3/
- 2: https://github.com/jsh9/pydoclint/blob/main/README.md
- 3: https://tessl.io/registry/tessl/pypi-pydoclint
- 4: https://tessl.io/registry/tessl/pypi-pydoclint/0.7.0/files/docs/index.md
- 5: https://github.com/jsh9/pydoclint/blob/main/AGENTS.md
- 6: https://jsh9.github.io/pydoclint/config_options.html
- 7: jsh9/pydoclint@7189f6a
- 8: http://pocoo-click.readthedocs.io/en/latest/options/
- 9: https://click.palletsprojects.com/en/stable/api/
🌐 Web query:
site:github.com jsh9 pydoclint default_map
💡 Result:
In the jsh9/pydoclint project, there is no configuration option named default_map. The confusion likely stems from the project's internal use of mapping structures to handle argument defaults [1]. Pydoclint does not use a user-facing default_map configuration. Instead, it manages argument defaults internally during AST (Abstract Syntax Tree) parsing, specifically using an internal mapping—often referred to as argToDefaultMapping in the source code—to associate function arguments with their defined default values [1]. This logic is used to support features like the --check-arg-defaults flag [1]. If you are looking for information on configuring pydoclint, official configuration options are managed through CLI flags or configuration files (such as pyproject.toml), which are documented on the project's official configuration page [2][3]. Typical configuration involves options like --style, --check-arg-defaults, or --skip-checking-short-docstrings [1][2][3].
Citations:
- 1: jsh9/pydoclint@7189f6a
- 2: https://github.com/jsh9/pydoclint
- 3: https://github.com/jsh9/pydoclint/blob/main/README.md
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Confirm the exact keys at the referenced lines
if [ -f pyproject.toml ]; then
echo "== pyproject.toml exists =="
sed -n '640,690p' pyproject.toml | nl -ba | sed -n '1,120p'
else
echo "pyproject.toml not found at repo root"
exit 1
fi
# Check whether the invalid option names appear anywhere else
rg -n "require-return-section-when-returning-values|require-yield-section-when-yielding-values" pyproject.toml || true
rg -n "require-return-section-when-returning-none|require-return-section-when-returning-nothing|require-yield-section-when-yielding-nothing" pyproject.toml || trueRepository: ByronWilliamsCPA/python-libs
Length of output: 161
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# If the repo vendors docs/config or a lockfile pins pydoclint, we can locate it.
# (Best-effort: doesn't assume dependency managers.)
rg -n "pydoclint" pyproject.toml || true
ls -la | headRepository: ByronWilliamsCPA/python-libs
Length of output: 765
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Fetch pydoclint's config options list quickly (best-effort, no assumptions).
# Uses curl if available.
if command -v curl >/dev/null 2>&1; then
echo "== Fetching pydoclint config options page =="
curl -fsSL "https://jsh9.github.io/pydoclint/config_options.html" | head -n 40
echo "== Searching within the page for require-return-section keys =="
curl -fsSL "https://jsh9.github.io/pydoclint/config_options.html" | rg -n "require-return-section|require-yield-section" || true
else
echo "curl not available"
fiRepository: ByronWilliamsCPA/python-libs
Length of output: 1984
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the relevant [tool.pydoclint] section with line numbers
# (cat -n is available; nl isn't.)
sed -n '640,680p' pyproject.toml | cat -nRepository: ByronWilliamsCPA/python-libs
Length of output: 1576
🏁 Script executed:
#!/bin/bash
set -euo pipefail
URL="https://jsh9.github.io/pydoclint/config_options.html"
# Extract any require-return / require-yield option keys from the config options page
curl -fsSL "$URL" | rg -o "require-(return|yield)-section-when-[a-zA-Z0-9_-]+" | sort -uRepository: ByronWilliamsCPA/python-libs
Length of output: 309
🏁 Script executed:
#!/bin/bash
set -euo pipefail
URL="https://jsh9.github.io/pydoclint/config_options.html"
# Explicitly check for the specific (possibly-wrong) "values" keys
curl -fsSL "$URL" | rg -n "require-return-section-when-returning-values|require-yield-section-when-yielding-values" || trueRepository: ByronWilliamsCPA/python-libs
Length of output: 54
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Also search the local pyproject for any variants to ensure we don't miss typos elsewhere.
rg -n "require-return-section-when-|require-yield-section-when-" pyproject.tomlRepository: ByronWilliamsCPA/python-libs
Length of output: 242
🏁 Script executed:
#!/bin/bash
set -euo pipefail
URL="https://jsh9.github.io/pydoclint/config_options.html"
curl -fsSL "$URL" | rg -n "returning-values|yielding-values" || trueRepository: ByronWilliamsCPA/python-libs
Length of output: 54
Fix invalid pydoclint option keys in [tool.pydoclint] (lines 663–665)
pyproject.toml uses unsupported keys:
require-return-section-when-returning-values(line 664)require-yield-section-when-yielding-values(line 665)
Pydoclint’s documented options are require-return-section-when-returning-nothing and require-yield-section-when-yielding-nothing—so the current settings won’t apply. In particular, because require-yield-section-when-yielding-nothing isn’t set, it will use the documented default (true), and pydoclint may still require a Yields section when yielding None.
🔧 Proposed fix — use valid option names
skip-checking-raises = false
require-return-section-when-returning-nothing = false
-require-return-section-when-returning-values = false
-require-yield-section-when-yielding-values = false
+require-yield-section-when-yielding-nothing = false📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| require-return-section-when-returning-nothing = false | |
| require-return-section-when-returning-values = false | |
| require-yield-section-when-yielding-values = false | |
| require-return-section-when-returning-nothing = false | |
| require-yield-section-when-yielding-nothing = false |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@pyproject.toml` around lines 663 - 665, The pyproject.toml contains invalid
pydoclint option keys: replace the unsupported keys
require-return-section-when-returning-values and
require-yield-section-when-yielding-values with the correct documented keys
require-return-section-when-returning-nothing and
require-yield-section-when-yielding-nothing respectively so the pydoclint
settings take effect; update the entries in the [tool.pydoclint] table (the two
key names shown) to the corrected names and preserve the boolean values you
intended.
| log_level: The logging level for the application. | ||
| json_logs: Flag to enable or disable JSON formatted logs. | ||
| include_timestamp: Flag to include timestamps in logs. | ||
| model_config: Pydantic settings configuration. |
There was a problem hiding this comment.
Add explicit type for model_config in the Attributes docstring.
model_config is the only listed attribute without an explicit type, which breaks the
typed-docstring consistency introduced in this PR.
As per coding guidelines, "Use Google-style docstrings with Args, Returns, and Raises sections for all functions and classes".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/python_libs/core/config.py` at line 17, Update the Attributes docstring
entry for model_config to include an explicit type annotation; replace the
current line "model_config: Pydantic settings configuration." with something
like "model_config (dict): Pydantic settings configuration." (or "model_config
(Mapping[str, Any]): Pydantic settings configuration." if you prefer a more
generic type) so the Attributes section consistently lists types for all
attributes and follows the Google-style docstring convention.
| Args: | ||
| level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). | ||
| level (str): Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL). | ||
| Defaults to INFO. | ||
| json_logs: If True, output JSON logs (production mode). If False, | ||
| json_logs (bool): If True, output JSON logs (production mode). If False, | ||
| use rich console formatting (development mode). Defaults to False. | ||
| include_timestamp: Whether to include timestamps in log output. | ||
| include_timestamp (bool): Whether to include timestamps in log output. | ||
| Defaults to True. | ||
| include_correlation: Whether to include correlation IDs from request | ||
| context in log output. Defaults to True. Requires API framework. | ||
| include_correlation (bool): Whether to include correlation IDs from | ||
| request context in log output. Defaults to True. Requires API | ||
| framework. |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win
Add missing Returns/Raises sections to satisfy src docstring policy.
For setup_logging and log_performance, the updated docstrings include Args but still omit Returns and Raises, which violates the src-level docstring requirement.
Suggested docstring structure update
def setup_logging(
@@
Args:
level (str): Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
Defaults to INFO.
@@
request context in log output. Defaults to True. Requires API
framework.
+
+ Returns:
+ None: This function configures global logging state.
+
+ Raises:
+ Exception: Propagates configuration/runtime errors from logging handlers.
@@
def log_performance(
@@
Args:
logger (BoundLogger): Structlog logger instance from get_logger().
@@
**context (object): Additional context key-value pairs to include in
the log.
+
+ Returns:
+ None: This function emits a structured performance log entry.
+
+ Raises:
+ Exception: Propagates logger backend errors if emission fails.Also applies to: 173-179
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/python_libs/utils/logging.py` around lines 44 - 53, Add missing "Returns"
and "Raises" sections to the Google-style docstrings for setup_logging and
log_performance: update the docstring for setup_logging to include a Returns
clause (e.g., returning the configured logging.Logger or None) and a Raises
clause documenting any exceptions that can be propagated during logger
configuration (e.g., ValueError for invalid level or OSError for handler setup),
and update log_performance docstring similarly to state what it returns (if
anything) and which exceptions it may raise (e.g., KeyError or RuntimeError if
context or timer retrieval fails); ensure the exact function names setup_logging
and log_performance are updated and the wording matches existing Args style and
project docstring policy.
…pydoclint Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…request params Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Summary
Migrates from the archived
darglintlibrary topydoclintper the updated standards manifest (TOOL-007/PC-006/TOOL-013).darglint>=1.8.1withpydoclint>=0.8.4in dev dependencies[tool.darglint]config block; adds[tool.pydoclint]with google styledarglintpre-commit hook; adds the upstreampydoclinthook (rev 88d83c94156c5e51a09938e77019f2c58e92ab58 / 0.8.4)darglintfromci: skip:list.darglintconfig file viagit rmuv.lock: removes darglint 1.8.1, adds pydoclint 0.8.4 + docstring-parser-fork 0.0.14Posture: keep raises checks, require arg type hints, lenient on Returns/Yields missing sections.
Docstring findings (DONE_WITH_CONCERNS)
Running
uv run pydoclint src/ packages/reveals 807 findings across the codebase, exceeding the ~30-finding auto-fix threshold. These require a separate docstring-fix pass and are tracked as follow-on work.DOC histogram:
Test plan
grep -rn darglint pyproject.toml .pre-commit-config.yamlreturns emptyuv run pydoclint --versionshows 0.8.4Generated with Claude Code
Summary by CodeRabbit