urllib3 2.7.0: util.Url

# urllib3 Url API

This sample pins `urllib3` 2.7.0 and verifies `urllib3.util.Url` for URL data representation, component extraction, and string reconstruction.

The contract verifies:
- `Url` NamedTuple stores `scheme`, `auth`, `host`, `port`, `path`, `query`, and `fragment` fields, normalizing scheme to lowercase and path to begin with a leading slash.
- `url` property and `__str__()` reconstruct the full RFC-compliant URL string from components.
- `authority`, `netloc`, and `hostname` properties correctly extract host, port, and authentication components.
- `request_uri` property returns the combined path and query string, defaulting to `'/'` when path is absent.
- `Url` instances are immutable namedtuples that support `_replace()` and can be hashed and compared for equality.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify urllib3.util.Url in pkg:pypi/urllib3@2.7.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/urllib3@2.7.0
Demonstrate these symbols/APIs:
  - urllib3.util.Url

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:bf98bcb58d34ae175afc5ef77a5be673ee52d578f68f369a5b942925d724a147","contract":["Url NamedTuple stores scheme, auth, host, port, path, query, and fragment fields, normalizing scheme to lowercase and path to begin with a leading slash.","url property and __str__() reconstruct the full RFC-compliant URL string from components.","authority, netloc, and hostname properties correctly extract host, port, and authentication components.","request_uri property returns the combined path and query string, defaulting to '/' when path is absent.","Url instances are immutable namedtuples that support _replace() and can be hashed and compared for equality."],"goal":"verify urllib3.util.Url in pkg:pypi/urllib3@2.7.0","kind":"HOW","packages":["pkg:pypi/urllib3@2.7.0"],"schemaVersion":1,"symbols":["urllib3.util.Url"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","executionContext":"python","language":"python","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/urllib3@2.7.0"],"schemaVersion":1,"subject":"pkg:pypi/urllib3@2.7.0","symbols":["urllib3.util.Url"],"verifierAdapter":"python@1"}

urllib3==2.7.0

{
  "schemaVersion": 1,
  "goal": "verify urllib3.util.Url in pkg:pypi/urllib3@2.7.0",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/urllib3@2.7.0"
  ],
  "symbols": [
    "urllib3.util.Url"
  ]
}

import urllib3
from urllib3.util import Url, parse_url

# 1. Url NamedTuple stores scheme, auth, host, port, path, query, and fragment fields,
#    normalizing scheme to lowercase and path to begin with a leading slash.
u = Url(
    scheme="HTTPS",
    auth="user:pass",
    host="example.com",
    port=8443,
    path="api/v1/resource",
    query="filter=active&limit=10",
    fragment="section2",
)
assert u.scheme == "https", f"Expected scheme lowercased to https, got {u.scheme}"
assert u.auth == "user:pass"
assert u.host == "example.com"
assert u.port == 8443
assert u.path == "/api/v1/resource", f"Expected path with leading slash, got {u.path}"
assert u.query == "filter=active&limit=10"
assert u.fragment == "section2"

# 2. url property and __str__() reconstruct the full RFC-compliant URL string from components.
u_clean = Url(
    scheme="HTTPS",
    host="example.com",
    port=8443,
    path="api/v1/resource",
    query="filter=active&limit=10",
    fragment="section2",
)
clean_url = "https://example.com:8443/api/v1/resource?filter=active&limit=10#section2"
assert u_clean.url == clean_url
assert str(u_clean) == clean_url

# Ensure auth component is included when reconstructing URL with authentication
assert u.url.startswith("https://")
assert f"{u.auth}@" in u.url
assert u.url.endswith("example.com:8443/api/v1/resource?filter=active&limit=10#section2")

# 3. authority, netloc, and hostname properties correctly extract host, port, and authentication components.
assert u.netloc == "example.com:8443"
assert u.authority == "user:pass@example.com:8443"
assert u.hostname == "example.com"

u_no_auth = Url(scheme="http", host="example.com", port=80)
assert u_no_auth.netloc == "example.com:80"
assert u_no_auth.authority == "example.com:80"

u_no_port = Url(scheme="http", host="example.com")
assert u_no_port.netloc == "example.com"
assert u_no_port.authority == "example.com"
assert Url(path="/relative").hostname is None

# 4. request_uri property returns the combined path and query string, defaulting to '/' when path is absent.
assert u.request_uri == "/api/v1/resource?filter=active&limit=10"
assert Url(scheme="http", host="example.com").request_uri == "/"
assert Url(path="/index.html").request_uri == "/index.html"
assert Url(path="/search", query="q=test").request_uri == "/search?q=test"

# 5. Url instances are immutable namedtuples that support _replace() and can be hashed and compared for equality.
try:
    u.host = "localhost"
    raise AssertionError("Url instance should be immutable")
except AttributeError:
    pass

u_replaced = u_clean._replace(path="/api/v2/items", port=443)
assert u_replaced.path == "/api/v2/items"
assert u_replaced.port == 443
assert u_replaced.host == "example.com"
assert u_replaced.url == "https://example.com:443/api/v2/items?filter=active&limit=10#section2"

u_identical = Url(
    scheme="https",
    auth="user:pass",
    host="example.com",
    port=8443,
    path="/api/v1/resource",
    query="filter=active&limit=10",
    fragment="section2",
)
assert u == u_identical
assert hash(u) == hash(u_identical)
url_set = {u, u_replaced}
assert len(url_set) == 2
assert u in url_set

# Interoperability with parse_url
parsed = parse_url(clean_url)
assert isinstance(parsed, Url)
assert parsed == u_clean

print("CONTRACT PASS: urllib3.util.Url verified offline")