Fetch

def describe(fetched: Fetched) -> dict[str, Any]:
    """What a run records of a fetch: the URLs and the content type, never the body.

    Args:
        fetched: What a fetch read.

    Returns:
        ``url``, ``final_url``, ``hops`` and ``content_type``.
    """
    return {
        "url": fetched.url,
        "final_url": fetched.final_url,
        "hops": list(fetched.hops),
        "content_type": fetched.content_type,
    }

def fetch(  # noqa: PLR0913 - the URL, the policy's limits, and the two seams for tests
    url: str,
    *,
    resolve: Resolve = _resolve,
    connect: Connect = _connect,
    max_hops: int = MAX_HOPS,
    timeout: float = TIMEOUT,
    max_seconds: float = MAX_SECONDS,
    max_bytes: int = MAX_BYTES,
) -> Fetched:
    """Fetch a URL under the policy of this module, following redirects.

    Args:
        url: An ``http`` or ``https`` URL.
        resolve: Resolves a host name; the system resolver by default.
        connect: Opens a connection to an address; http.client by default.
        max_hops: The most requests made, the first included.
        timeout: Seconds a connection or a read may wait.
        max_seconds: Seconds the whole fetch may take, redirects and bodies included.
        max_bytes: The largest body read.

    Returns:
        What was read.

    Raises:
        FetchError: ``refused-url`` when the URL, a redirect or an address is refused; ``fetch-failed``
            when the body cannot be read, is too large or too slow, or the final response is not 200.
    """
    deadline = time.monotonic() + max_seconds
    hops: list[str] = []
    current = url
    while True:
        hops.append(current)
        status, headers, data = _hop(current, resolve, connect, timeout=timeout, max_bytes=max_bytes, deadline=deadline)
        if status in REDIRECTS:
            location = headers.get("location")
            if not location:
                raise FetchError("fetch-failed", f"{current!r} redirects without a location")
            if len(hops) >= max_hops:
                raise FetchError("fetch-failed", f"{url!r} redirects more than {max_hops - 1} times")
            current = urljoin(current, location)
            continue
        if status != http.client.OK:
            raise FetchError("fetch-failed", f"{current!r} answered {status}")
        content_type = headers.get("content-type", "").split(";", 1)[0].strip().lower()
        return Fetched(url, current, tuple(hops), content_type, data)

def forbidden(address: str) -> str | None:
    """Say why an address may not be fetched from, or ``None`` for a public unicast address.

    Args:
        address: An IPv4 or IPv6 address.

    Returns:
        The reason, or ``None``.
    """
    try:
        ip = _ip(address)
    except ValueError:
        return f"{address!r} is not an IP address"
    if isinstance(ip, ipaddress.IPv6Address):
        carried = ip.ipv4_mapped or ip.sixtofour or (ip.teredo[1] if ip.teredo else None)
        if carried is None and ip in _NAT64:
            carried = ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
        if carried is not None:
            reason = forbidden(str(carried))
            return f"{ip} carries {carried}, which {reason.split(' ', 1)[1]}" if reason else None
    if ip.is_multicast:
        return f"{ip} is a multicast address"
    if not ip.is_global:
        return f"{ip} is not a public address (loopback, private, link-local or reserved)"
    return None