aio-libs / multidict / 37273548977

86%

push

github

Deprecate upstr with a module __getattr__ (#1680)

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

## What do these changes do?

``upstr`` has been documented as a deprecated alias for ``istr`` since
2.0 but never warned. Accessing ``multidict.upstr`` now goes through a
module ``__getattr__`` that emits ``DeprecationWarning`` and returns
``istr``. A ``from multidict import upstr`` warns twice, since importlib
probes the name with ``hasattr()`` before the real lookup; the default
warning filters collapse the duplicate. The name is dropped from
``__all__`` so ``from multidict import *`` does not warn, and a module
``__dir__`` keeps it in ``dir(multidict)``. Type checkers still see
``upstr = istr`` under ``TYPE_CHECKING``; ``__getattr__`` is hidden from
them so a misspelled ``multidict.X`` is still an error.

The change lives in ``multidict/__init__.py`` only, so both backends get
it.

## Are there changes in behavior for the user?

Yes; ``multidict.upstr`` and ``from multidict import upstr`` emit
``DeprecationWarning``, and ``upstr`` is no longer in ``__all__``.

## 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 Opus 5.5 (Claude Code); reviewed by @asvetlov.

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

Tests, C extension, CPython 3.14: 4089 passed, 181 skipped
Tests, pure Python (`MULTIDICT_NO_EXTENSIONS=1 --no-c-extensions`),
clean tree copy: 1610 passed, 24 skipped
CPython 3.10, C extension: `test_istr.py`, `test_circular_imports.py`,
`test_mypy.py` passed
mypy: `multidict.upstr` re... (continued)

793 of 1586 branches covered (50.0%)

Branch coverage included in aggregate %.

25 of 26 new or added lines in 2 files covered. (96.15%)

9352 of 10217 relevant lines covered (91.53%)

1.83 hits per line