urllib3 2.7.0: ProxyManager, proxy_from_url

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 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.ProxyManager
  - urllib3.proxy_from_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:575184b151ddc3c18521e2dadaceb936f19e1348462be0c8a6b115f64c2914db","contract":["urllib3.ProxyManager initializes an HTTP/HTTPS proxy manager with target proxy URL and custom proxy headers","urllib3.proxy_from_url constructs a ProxyManager instance from a URL string with proxy endpoint details","urllib3.ProxyManager.connection_from_host creates proxy connection pools routing requests through the configured proxy"],"goal":"verify pkg:pypi/urllib3@2.7.0","kind":"HOW","packages":["pkg:pypi/urllib3@2.7.0"],"schemaVersion":1,"symbols":["urllib3.ProxyManager","urllib3.proxy_from_url"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/urllib3@2.7.0"],"schemaVersion":1,"subject":"pkg:pypi/urllib3@2.7.0","symbols":["urllib3.ProxyManager","urllib3.proxy_from_url"],"verifierAdapter":"python@1"}

urllib3==2.7.0

"""Sample demonstrating HTTP/HTTPS proxy configuration and management with urllib3."""

from typing import Dict, Optional
import urllib3
from urllib3 import ProxyManager, proxy_from_url
from urllib3.connectionpool import ConnectionPool


def create_proxy_manager(
    proxy_url: str,
    proxy_headers: Optional[Dict[str, str]] = None,
    num_pools: int = 10,
    maxsize: int = 1,
) -> ProxyManager:
    """Initialize a ProxyManager with custom proxy headers and connection pool settings."""
    return ProxyManager(
        proxy_url=proxy_url,
        proxy_headers=proxy_headers,
        num_pools=num_pools,
        maxsize=maxsize,
    )


def create_proxy_from_url(proxy_url: str, **kwargs) -> ProxyManager:
    """Construct a ProxyManager instance directly from a proxy URL string."""
    return proxy_from_url(proxy_url, **kwargs)


def get_proxy_connection_pool(
    manager: ProxyManager,
    host: str,
    port: Optional[int] = None,
    scheme: str = "http",
) -> ConnectionPool:
    """Obtain the proxy connection pool for a specific destination host and scheme."""
    return manager.connection_from_host(host=host, port=port, scheme=scheme)

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

"""Contract verification test for urllib3 ProxyManager and proxy_from_url utilities."""

import os
import sys

# Ensure project root is on sys.path for local module imports
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

import urllib3
from urllib3 import ProxyManager
from urllib3.connectionpool import HTTPConnectionPool, HTTPSConnectionPool
from urllib3.util import Url
from sample import (
    create_proxy_from_url,
    create_proxy_manager,
    get_proxy_connection_pool,
)


def test_proxy_manager_initialization() -> None:
    """Assertion 1: urllib3.ProxyManager initializes an HTTP/HTTPS proxy manager with target proxy URL and custom proxy headers."""
    proxy_url = "http://proxy.example.com:8080"
    headers = {"Proxy-Authorization": "Basic dXNlcjpwYXNz", "X-Proxy-Custom": "enabled"}
    pm = create_proxy_manager(proxy_url=proxy_url, proxy_headers=headers)

    assert isinstance(pm, ProxyManager), "Manager must be an instance of ProxyManager"
    assert isinstance(pm.proxy, Url), "Proxy attribute must be a Url object"
    assert pm.proxy.scheme == "http", f"Expected scheme http, got {pm.proxy.scheme}"
    assert pm.proxy.host == "proxy.example.com", f"Expected host proxy.example.com, got {pm.proxy.host}"
    assert pm.proxy.port == 8080, f"Expected port 8080, got {pm.proxy.port}"
    assert pm.proxy_headers["Proxy-Authorization"] == "Basic dXNlcjpwYXNz"
    assert pm.proxy_headers["X-Proxy-Custom"] == "enabled"


def test_proxy_from_url_construction() -> None:
    """Assertion 2: urllib3.proxy_from_url constructs a ProxyManager instance from a URL string with authentication and endpoint details."""
    raw_url = "http://proxy2.example.com:3128"
    pm = create_proxy_from_url(raw_url)

    assert isinstance(pm, ProxyManager), "Constructed object must be a ProxyManager"
    assert isinstance(pm.proxy, Url), "Proxy attribute must be a Url object"
    assert pm.proxy.scheme == "http", f"Expected scheme http, got {pm.proxy.scheme}"
    assert pm.proxy.host == "proxy2.example.com", f"Expected host proxy2.example.com, got {pm.proxy.host}"
    assert pm.proxy.port == 3128, f"Expected port 3128, got {pm.proxy.port}"


def test_proxy_connection_pool_resolution() -> None:
    """Assertion 3: urllib3.ProxyManager.connection_from_host creates proxy connection pools routing requests through the configured proxy."""
    pm = create_proxy_manager("http://proxy.example.com:8080")

    # HTTP destination pool connects directly via the proxy host
    http_pool = get_proxy_connection_pool(pm, host="api.example.com", port=80, scheme="http")
    assert isinstance(http_pool, HTTPConnectionPool), "Must return HTTPConnectionPool for http scheme"
    assert http_pool.proxy.host == "proxy.example.com", "HTTP pool proxy host mismatch"
    assert http_pool.proxy.port == 8080, "HTTP pool proxy port mismatch"

    # HTTPS destination pool connects to destination host via CONNECT tunnel through the proxy
    https_pool = get_proxy_connection_pool(pm, host="secure.example.com", port=443, scheme="https")
    assert isinstance(https_pool, HTTPSConnectionPool), "Must return HTTPSConnectionPool for https scheme"
    assert https_pool.proxy.host == "proxy.example.com", "HTTPS pool proxy host mismatch"
    assert https_pool.host == "secure.example.com", "HTTPS pool target host mismatch"
    assert https_pool.port == 443, "HTTPS pool target port mismatch"


def main() -> None:
    test_proxy_manager_initialization()
    test_proxy_from_url_construction()
    test_proxy_connection_pool_resolution()
    print("All contract assertions passed successfully.")


if __name__ == "__main__":
    main()