aio-libs / multidict / 36129676026

87%

push

github

Fix popone()/pop() docstrings and document single-value checks (#1578)

<!-- Thank you for your contribution! -->

## What do these changes do?

The C extension's `popone()` and `pop()` docstrings said "Remove the
last occurrence of key"; the implementation removes the first one, as
the pure-Python backend and `docs/multidict.rst` already say. Both
backends now carry the same "Remove the first occurrence of key"
docstring, and a test pins it to the actual behaviour.

It also adds a note to the `MultiDict` reference: `d[key]`, `getone()`
and `get()` silently return the first value, so a key that must carry
exactly one value (for example `Host`, `Content-Length` or
`Authorization`) should be read with `getall()` and rejected unless
there is exactly one.

## Are there changes in behavior for the user?

No, documentation only.

## Is it a substantial burden for the maintainers to support this?

No.

## Related issue number

N/A

## Checklist

- [x] I think the code is well written
- [x] Unit tests for the changes exist
- [x] Documentation reflects the changes
- [ ] If you provide code modification, please add yourself to
`CONTRIBUTORS.txt` (N/A)
- [x] Add a new news fragment into the `CHANGES/` folder
- [x] `make doc-spelling` passes and any new technical words are added
to `docs/spelling_wordlist.txt`

Drafted with Claude Code (Claude Opus 5.5); pending review by @asvetlov.

<details>
<summary>Agent run details (optional, for reviewers)</summary>

- C extension, 3.14: 2691 passed, 180 skipped
- Pure Python (`MULTIDICT_NO_EXTENSIONS=1`, `--no-c-extensions`, clean
tree copy): 1282 passed, 11 skipped
- 3.10 C extension: 2704 passed, 167 skipped
- `make doc-spelling` and pre-commit: clean
</details>

779 of 1558 branches covered (50.0%)

Branch coverage included in aggregate %.

4 of 8 new or added lines in 1 file covered. (50.0%)

7983 of 8509 relevant lines covered (93.82%)

1.88 hits per line