IDNA-Safe URL Normalizer

A utility that canonicalizes user-supplied URLs while enforcing encoding rules and validating hosts and ports.

Capabilities

Canonicalizes Unicode hosts and encodes paths

• Normalizes https://Tést.Example/mañana/agenda?q=niño&redirect=/a b to https://xn--tst-6la.example/ma%C3%B1ana/agenda?q=ni%C3%B1o&redirect=%2Fa%20b @test

Rejects invalid ports

• Passing http://example.com:70000/report raises a ValueError for an out-of-range port instead of silently correcting it @test

Warns on improperly encoded input when strict

• With strict=True, normalizing https://example.com/a b/c?q=needs encoding emits a UserWarning about encoding and returns https://example.com/a%20b/c?q=needs+encoding @test

Implementation

@generates

API

def normalize_url(raw_url: str, *, strict: bool = False) -> str:
    """
    Normalize a user-supplied URL string into a canonical, encoded form.
    - Converts Unicode hosts to IDNA/punycode
    - Percent-encodes path and query components while preserving order and repeated parameters
    - Validates hosts and ports and raises ValueError on invalid input
    - When strict is True, emits a UserWarning on improperly encoded path or query input before returning the normalized URL
    """

Dependencies { .dependencies }

furl { .dependency }

URL parsing/manipulation library with IDNA support, encoding-aware components, strict warnings, and host/port validation.