aio-libs / yarl / 36824558502

98%

push

github

Keep the brackets of an IPvFuture host (#1956)

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

## What do these changes do?

An IPvFuture address (RFC 3986 section 3.2.2) lost its brackets:
`URL('http://[v1.x]:80/', mode='rfc')` printed `http://v1.x/`, a
reg-name, so `str()` named a different host. `split_netloc()` now keeps
the brackets for an IPvFuture host (IPv6 addresses never start with
`v`), the host encoder validates it against the grammar and lowercases
it, and `raw_host`, `host`, `host_subcomponent`,
`host_port_subcomponent` and `human_repr()` no longer add a second pair
of brackets. Parsing, `URL.build()`, `with_host()`, `with_port()`,
`join()`, pickling and default port dropping all round-trip it now.

The WHATWG URL Standard has no IPvFuture (its host parser reads `[...]`
as IPv6 and fails), so WHATWG mode rejects one when parsing, building,
replacing the host, joining an RFC-mode reference or converting an
RFC-mode URL. A pre-encoded WHATWG URL is taken as is, as for other
hosts.

## Are there changes in behavior for the user?

Yes. In RFC 3986 mode the host keeps its brackets (`raw_host ==
'[v1.x]'`), and an IPvFuture with characters outside its grammar, such
as `%`, is rejected. In the default WHATWG mode `http://[v1.x]/` is
rejected instead of being parsed as the reg-name `v1.x`.

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

No. The new checks sit on branches only taken for bracketed or unusual
hosts; the WHATWG hot path timings are unchanged.

## 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`
- [x] Add a new news fragment into the `CHANGES/` folder

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

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

Tests: `pytest -n auto --cov=yarl --... (continued)

97 of 194 branches covered (50.0%)

Branch coverage included in aggregate %.

161 of 165 new or added lines in 5 files covered. (97.58%)

9669 of 9800 relevant lines covered (98.66%)

0.99 hits per line