docs: clarify valuecounter field arguments

[codeofwxz]

This PR corrects the valuecounter() field-selection documentation referenced in #641. The docstring currently says a tuple of field names or indexes can be passed directly, but valuecounter(table, fields) raises FieldSelectionError; multiple fields must be separate positional arguments or unpacked with *fields.

Changes

1. Replace the incorrect tuple-argument description with the supported calling convention.
2. Add executable examples for mixed field names/indexes and tuple unpacking.
3. Record the documentation correction in docs/changes.rst.

The public API and counting behavior are unchanged. This addresses the documentation mismatch discussed in #641; it does not change exception formatting.

Validation

On Windows with Python 3.9.13:

• The directly passed tuple reproduces FieldSelectionError; the unpacked tuple and equivalent positional fields return the expected counts.
• python -m pytest -v petl/test/util/test_counting.py --doctest-modules petl/util/counting.py -k 'test_ or valuecounter': 12 passed, 9 deselected, on both the base and updated tree. The valuecounter doctest now contains seven examples instead of three.
• python -m sphinx -W -b html docs ../docs-html: build succeeded.
• git diff --check: passed.

The full test suite, tox version matrix, and hosted CI have not been run for this documentation-only change.

Checklist

• Documentation examples are executable and tested; no new functions or runtime behavior changes.
• Change is recorded in docs/changes.rst.
• Patch contains only the docstring and changelog changes.
• Tested locally using pytest and a strict Sphinx build.
• Based on current master (deb9618); relevant pytest/doctest checks rerun before publication.
• Hosted CI and coverage checks pass (pending publication).
• Ready for review.

Refs #641.

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can hide the parts of a finding you never read, like the evidence or the agent prompt

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Clarify valuecounter multi-field argument usage

📝 Documentation 🕐 Less than 5 minutes

AI Description

• Corrects valuecounter() guidance to require separate positional field arguments.
• Adds executable examples for mixed selectors and iterable unpacking.
• Records the correction for issue #641 in the unreleased changelog.

Diagram

graph TD
  A["counting.py docstring"] --> C["Sphinx docs"] --> D["API readers"]
  B["changes.rst notes"] --> C

Loading

High-Level Assessment

The documentation-only correction is the appropriate approach because the public API and counting behavior are already correct. Expanding the runtime API to interpret a tuple as multiple selectors would introduce behavior and ambiguity beyond issue #641, so it is rightly excluded.

Files changed (2) +20 / -2

Documentation (2) +20 / -2

changes.rstRecord corrected valuecounter argument guidance +4/-0

Record corrected valuecounter argument guidance

• Adds an unreleased changelog entry explaining that multiple fields are positional arguments and referencing issue #641.

docs/changes.rst

counting.pyClarify valuecounter multi-field selection examples +16/-2

Clarify valuecounter multi-field selection examples

• Replaces the incorrect tuple-argument claim with the supported positional calling convention. Adds executable examples covering mixed field names and indexes plus tuple unpacking.

petl/util/counting.py

[Copilot]

🟢 Approval recommended

Documentation changes are validated with tests and a strict Sphinx build.

Pull request overview

Clarifies valuecounter() field-selection documentation without changing runtime behavior.

Changes:

• Documents positional fields and tuple unpacking.
• Adds executable mixed-field examples.
• Records the correction in the changelog.

File summaries

File	Summary
petl/util/counting.py	Updates valuecounter() documentation and doctests.
docs/changes.rst	Records the documentation clarification.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[coveralls]

Coverage Report for CI Build 34686667306

Coverage remained the same at 92.066%

Details

• Coverage remained the same as the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	15466
Covered Lines:	14239
Line Coverage:	92.07%
Coverage Strength:	0.92 hits per line

---

💛 - Coveralls