URLs and Query Strings

The URL layer implements WHATWG-style parsing — the same behaviour browsers apply — so URLs extracted from documents resolve and normalize the way they would in a real user agent.

Parsing and Validating

URL.parse() parses an absolute or relative URL; URL.can_parse() answers validity without constructing an object. Parse failures raise the typed URLParseError.

Query Strings

URLSearchParams reads and edits query parameters: append(), get(), get_all(), has(), and delete() cover the round-trip, preserving multi-value semantics.

Tips and Best Practices

Use can_parse() for cheap validation in filters; construct with parse() only when you need the components
Remember query keys repeat — use get_all() when a parameter may appear more than once
Catch URLParseError rather than pre-validating with regular expressions

Common Issues

Issue	Cause	Fix
Relative URL fails to parse	No base provided	Supply the base per `URL.parse()`
Only first query value returned	Used `get()` on a repeated key	Use `get_all()`
Odd characters in components	WHATWG normalization at work	Expected — this matches browser behaviour

FAQ

Does parsing follow the WHATWG standard?

Yes — normalization and component splitting mirror browser behaviour.

How do I check a URL without parsing it?

URL.can_parse() returns validity without object construction.

Can I edit a query string in place?

Yes — URLSearchParams supports append/get/has/delete round-trips.

API Reference Summary

Class/Method	Description
`URL.parse`	Parse a URL
`URL.can_parse`	Validity check without construction
`URLSearchParams.append`	Add a query parameter
`URLSearchParams.get_all`	All values for a key
`URLParseError`	Typed parse failure

URLs and Query Strings