Skip to content

pywhatwgurl - Python WHATWG URL Parser

Pure Python implementation of the WHATWG URL Standard.

PyPI version Python versions License Typed

What is pywhatwgurl?

pywhatwgurl is a Python library that implements the WHATWG URL Standard — the same URL parsing specification used by modern web browsers.

pywhatwgurl is listed as a complete Python implementation in the official WHATWG URL repository.

Unlike Python's built-in urllib.parse, which follows RFC 3986/3987, pywhatwgurl prioritizes web compatibility:

  • ✅ Browser-compatible URL parsing — Parse URLs exactly like Chrome, Firefox, and Safari
  • ✅ Modern API — Familiar URL and URLSearchParams classes matching the Web API
  • ✅ Pure Python — No compiled dependencies, works everywhere Python runs
  • ✅ Type-annotated — Full type hints for excellent IDE support

Quick Example

from pywhatwgurl import URL

# Parse a URL
url = URL("https://example.com:8080/path?query=value#hash")

print(url.hostname)  # "example.com"
print(url.port)      # "8080"
print(url.pathname)  # "/path"
print(url.search)    # "?query=value"
print(url.hash)      # "#hash"

# Modify URL components
url.pathname = "/new/path"
print(url.href)  # "https://example.com:8080/new/path?query=value#hash"

# Work with query parameters (Pythonic dictionary-style access)
url.search_params["page"] = "2"
print(url.search)  # "?query=value&page=2"

Why WHATWG URL?

The WHATWG URL Standard defines how browsers act, refining the generic URI syntax from RFC 3986 to ensure interoperability on the web.

Feature WHATWG URL RFC 3986
Browser compatibility ✅ Matches browsers exactly ⚠️ Defines generic syntax
Error handling ✅ Strictly defined ℹ️ Implementation-dependent
Unicode support ✅ Full IDNA (UTS #46) ℹ️ Varies by implementation
Edge cases ✅ Specified behavior ℹ️ Flexible

Staying Current

The WHATWG URL Standard is a living standard — it evolves continuously. pywhatwgurl tracks spec changes automatically:

  • A weekly CI workflow checks the WPT repository for updates to the url/ test data and opens a PR when changes are detected
  • All conformance tests must pass before any merge — regressions are caught immediately
  • Test data is pinned to a specific WPT commit for reproducibility, so every build is validated against a known snapshot
  • The workflow can also be triggered manually for urgent spec updates

This means spec changes are typically picked up within a week of landing in WPT, with a review cycle to verify correctness before merging.

Installation

pip install pywhatwgurl

Or with uv:

uv add pywhatwgurl

Next Steps

  • Getting Started

    Install pywhatwgurl and learn the basics

    Installation

  • User Guide

    Learn how to parse URLs and work with components

    URL Parsing

  • API Reference

    Complete API documentation with examples

    API Docs

  • Compliance

    Learn about WHATWG URL standard conformance

    Compliance