Fix mixed Google/numpy docstring style across bump.py, bump_toml.py, config.py

[coderabbitai]

Summary

Several docstrings in the codebase mix Google-style Args: blocks with numpy-style Returns/Raises sections. Per the repository's path instructions, docstrings must follow the numpy style guide throughout: private functions/methods should carry only a single-line summary, and public interfaces should use full structured numpy-style docs (Parameters, Returns, Raises — not Args:).

Originating from review discussion on #121 (comment: #121 (comment)), raised by @leynos.

Affected locations

Private helpers (should be truncated to a single-line summary):

• lading/commands/bump.py — _determine_package_selectors (Lines 434-449)
• lading/commands/bump.py — _update_manifest (Lines 481-500)
• lading/config.py — _validate_mapping_keys (Lines 225-244)

Public functions (should be converted to full numpy-style docs, i.e. Args: → Parameters\n----------):

• lading/commands/bump_toml.py — update_section (Lines 128-144)
• lading/commands/bump_toml.py — update_dependency_sections (Lines 156-171)

Required changes

• For each private helper listed above, replace the docstring with a single-line summary only, removing the Args:/Returns/Raises sections.
• For each public function listed above, rewrite the docstring to full numpy style: replace Args: with Parameters\n---------- (with parameter types), and keep Returns/Raises sections in numpy format (already numpy-style in these cases).
• Audit the rest of the codebase for the same Args: + numpy-section mixed pattern to catch any remaining instances beyond those listed here.

Acceptance criteria

• No docstring mixes Google-style Args: with numpy-style Returns/Raises sections.
• Private functions/methods carry single-line-summary docstrings only.
• Public functions/methods carry full numpy-style structured docstrings.

References

• PR: Derive bump crate sets once in the bump context (#97) #121
• Requested by: @leynos

[coderabbitai]

🔗 Related PRs

leynos/concordat#8 - Add Scaleway-backed remote tfstate persistence [closed]
leynos/tei-rapporteur#65 - [codex] Expand struct docstrings [closed]
leynos/beatcue#16 - Refresh repository documentation guidance [merged]
#114 - Centralise hardcoded Cargo dependency-section names (#103) [closed]
leynos/concordat#22 - Align roadmap with the roadmap grammar [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Truncate the three private helpers (two in bump_manifests.py, one in config.py) to single-line summaries, correcting the ticket's mislocated bump.py line references.
• Convert the two public bump_toml.py helpers to full NumPy style, replacing Args: with Parameters and fixing the Returns type line.
• Remediate the sole additional mixed instance (make_preflight_config) surfaced by the audit and re-verify no mixed patterns remain.
• Change docstring text only — touch no logic, imports, or call sites.

---

Follow-up agent instructions

Apply NumPy docstring conventions exactly as used in lading/: header underline length matches the header word (Parameters=10 dashes, Returns=7, Raises=6); one blank line after the summary; PEP 604 unions in type fields (A | None, never Optional); no blank line before the closing triple-quote in function docstrings. Private (underscore-prefixed) helpers get one sentence on one line and nothing else. Change docstring text only; do not modify logic, imports, or call sites. Note that _determine_package_selectors and _update_manifest are defined in lading/commands/bump_manifests.py (lines 60 and 114), NOT lading/commands/bump.py — edit the definitions there.

Design Choices

Design Choice 1: Scope of the single-line-summary fix for private functions with consistent NumPy multi-section docstrings

Options Considered:

1. Fix only the explicitly listed private helpers plus any true mixed-pattern instance found in the audit.
2. Sweep every private function in the codebase to a single-line summary.

Chosen Option: 1

Rationale: Respect the ticket's stated scope, keep the change reviewable, and avoid unrequested edits; flag the broader sweep separately if maintainers want it. Exploration found _should_skip_crate_update (bump_manifests.py), _collect_stale_lockfiles (publish_preflight.py), and runner.__call__ carry multi-section NumPy docstrings, but the ticket's explicit "Affected locations" list does not include these.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Truncate private helper docstrings to single-line summaries

Bring the flagged private helpers into line with the repository's hard single-line-summary rule for underscore-prefixed functions. Correct the ticket's location error: two of these helpers reside in bump_manifests.py, not bump.py.

Task 1: Truncate the manifest helper docstrings

Reduce _determine_package_selectors and _update_manifest to their one-line summaries.

• Edit lading/commands/bump_manifests.py (definitions at lines 60 and 114), not bump.py, which only imports these names.
• Retain each existing single-sentence summary line and delete the Parameters/Returns sections wholesale, leaving a one-line docstring.
• Leave the imports and call sites in bump.py untouched.

Task 2: Truncate the config validation helper docstring

Reduce _validate_mapping_keys to its one-line summary, removing the mixed Args:/Raises block.

• Edit lading/config.py (lines 228–254): keep the summary "Validate that mapping contains only allowed keys." and drop the Args: and Raises sections entirely.
• Do not alter the validation logic or the raised ConfigurationError.

🤖 Prompt for AI agents

Truncate three private helper docstrings down to their single-line summaries,
deleting the mixed Google/NumPy sections wholesale. Change docstring text only —
do not touch logic, imports, or call sites anywhere in this phase.

- In `lading/commands/bump_manifests.py` (NOT `bump.py`, which only imports
these names), edit the `_determine_package_selectors` definition (line 60) and
the `_update_manifest` definition (line 114). Retain each function's existing
single-sentence summary line and delete the `Parameters`/`Returns` sections
wholesale, leaving a one-line docstring. Leave the imports and call sites in
`bump.py` untouched.
- In `lading/config.py`, edit the `_validate_mapping_keys` docstring (lines
228–254). Keep the summary line "Validate that mapping contains only allowed
keys." and drop the `Args:` and `Raises` sections entirely. Do not alter the
validation logic or the raised `ConfigurationError`.

Phase 2: Convert public docstrings to full NumPy style

Rewrite the two public TOML helpers so parameters are documented under a proper Parameters header, eliminating the Google Args: block while preserving the NumPy Returns section.

Rewrite `update_section` and `update_dependency_sections`

Replace Args: with Parameters\n---------- and format to repo norms.

• Edit lading/commands/bump_toml.py (definitions at lines 125 and 151).
• Convert each Args: block to a Parameters section with a 10-dash underline; document each parameter on its own line with a PEP 604 type where useful (document : TOMLDocument, path : tuple[str, ...], names : cabc.Collection[str], target_version : str, dependency_sections : cabc.Mapping[str, cabc.Collection[str]], include_workspace_sections : bool, optional).
• Fix the Returns section to place the return type (bool) on its own line above the description, matching bump_manifests.py/lockfile.py templates.
• Add no Raises section — neither function raises.
• Keep a blank line after the summary and no blank line before the closing """.

🤖 Prompt for AI agents

Rewrite the docstrings of `update_section` and `update_dependency_sections` in
`lading/commands/bump_toml.py` (definitions at lines 125 and 151) into full
NumPy style, eliminating the Google `Args:` block while preserving the NumPy
`Returns` section.

- Convert each `Args:` block into a `Parameters` section headed by a 10-dash
underline (`----------`).
- Document each parameter on its own line with a PEP 604 type where useful:
`document : TOMLDocument`, `path : tuple[str, ...]`, `names :
cabc.Collection[str]`, `target_version : str`, `dependency_sections :
cabc.Mapping[str, cabc.Collection[str]]`, `include_workspace_sections : bool,
optional`.
- Fix the `Returns` section to place the return type (`bool`) on its own line
above the description, matching the `bump_manifests.py`/`lockfile.py` templates.
- Add no `Raises` section — neither function raises.
- Keep a blank line after the summary and no blank line before the closing
`"""`.

Phase 3: Audit and remediate remaining mixed instances

Close out the acceptance criterion that no docstring mixes the two styles.

Task 1: Fix the test-fixture mixed docstring

Convert the one additional true mixed instance found in the audit.

• Edit tests/unit/publish/conftest.py::make_preflight_config (line 77): replace the Google Args: block with a NumPy Parameters section and correct the Returns section to the header-plus-type-line form.

Task 2: Confirm no mixed patterns remain

Re-run the audit to verify the acceptance criteria.

• Search the tree for docstrings combining a literal Args: header with Parameters/Returns/Raises NumPy underlines; confirm zero matches after Phases 1–3.
• Note for reviewers: tests/helpers/workspace_metadata.py::build_test_package uses pure Google Args: with no NumPy counterpart — it is not a mixed instance and is intentionally out of scope for this ticket.

🤖 Prompt for AI agents

Remediate the remaining mixed-style docstring found by the audit and re-verify
the codebase is clean.

- Edit `tests/unit/publish/conftest.py::make_preflight_config` (line 77):
replace the Google `Args:` block with a NumPy `Parameters` section and correct
the `Returns` section to the header-plus-type-line form.
- Search the entire tree for docstrings combining a literal `Args:` header with
`Parameters`/`Returns`/`Raises` NumPy underlines; confirm zero matches remain
after Phases 1–3.
- Leave `tests/helpers/workspace_metadata.py::build_test_package` untouched — it
uses pure Google `Args:` with no NumPy counterpart, so it is not a mixed
instance and sits outside this ticket's scope.

Research

lading is a Python workspace-versioning tool. The relevant modules are lading/commands/bump.py (coordinator that imports and re-exports helpers), lading/commands/bump_manifests.py (defines the private manifest helpers), lading/commands/bump_toml.py (public TOML mutation helpers), and lading/config.py (configuration loading and validation). The repo mandates NumPy-style docstrings via .rules/python-00.md; live code consistently applies header-length-matched underlines, PEP 604 unions in type fields, and strictly single-line summaries for private helpers. docs/documentation-style-guide.md covers Rust only and imposes no Python docstring rules.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Truncate three private helper docstrings down to their single-line summaries,
deleting the mixed Google/NumPy sections wholesale. Change docstring text only —
do not touch logic, imports, or call sites anywhere in this phase.

- In `lading/commands/bump_manifests.py` (NOT `bump.py`, which only imports
these names), edit the `_determine_package_selectors` definition (line 60) and
the `_update_manifest` definition (line 114). Retain each function's existing
single-sentence summary line and delete the `Parameters`/`Returns` sections
wholesale, leaving a one-line docstring. Leave the imports and call sites in
`bump.py` untouched.
- In `lading/config.py`, edit the `_validate_mapping_keys` docstring (lines
228–254). Keep the summary line "Validate that mapping contains only allowed
keys." and drop the `Args:` and `Raises` sections entirely. Do not alter the
validation logic or the raised `ConfigurationError`.
===============================================================================

Task: 2

Rewrite the docstrings of `update_section` and `update_dependency_sections` in
`lading/commands/bump_toml.py` (definitions at lines 125 and 151) into full
NumPy style, eliminating the Google `Args:` block while preserving the NumPy
`Returns` section.

- Convert each `Args:` block into a `Parameters` section headed by a 10-dash
underline (`----------`).
- Document each parameter on its own line with a PEP 604 type where useful:
`document : TOMLDocument`, `path : tuple[str, ...]`, `names :
cabc.Collection[str]`, `target_version : str`, `dependency_sections :
cabc.Mapping[str, cabc.Collection[str]]`, `include_workspace_sections : bool,
optional`.
- Fix the `Returns` section to place the return type (`bool`) on its own line
above the description, matching the `bump_manifests.py`/`lockfile.py` templates.
- Add no `Raises` section — neither function raises.
- Keep a blank line after the summary and no blank line before the closing
`"""`.
===============================================================================

Task: 3

Remediate the remaining mixed-style docstring found by the audit and re-verify
the codebase is clean.

- Edit `tests/unit/publish/conftest.py::make_preflight_config` (line 77):
replace the Google `Args:` block with a NumPy `Parameters` section and correct
the `Returns` section to the header-plus-type-line form.
- Search the entire tree for docstrings combining a literal `Args:` header with
`Parameters`/`Returns`/`Raises` NumPy underlines; confirm zero matches remain
after Phases 1–3.
- Leave `tests/helpers/workspace_metadata.py::build_test_package` untouched — it
uses pure Google `Args:` with no NumPy counterpart, so it is not a mixed
instance and sits outside this ticket's scope.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!