"""Network utility functions for IP address classification.

This module provides utilities for classifying IP addresses and hostnames
as private/local vs public. Used for URL normalization and security validation.
"""

import ipaddress


def is_private_ip(hostname: str) -> bool:
    """Check if hostname is a private/local IP address.

    Recognizes:
    - Localhost values (127.0.0.1, localhost, [::1], 0.0.0.0)
    - RFC 1918 private IPv4 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
    - IPv6 private addresses (fc00::/7, fe80::/10)
    - mDNS .local domains

    Args:
        hostname: The hostname or IP address to check

    Returns:
        True if the hostname is a private/local address, False otherwise

    Examples:
        >>> is_private_ip("192.168.1.100")
        True
        >>> is_private_ip("172.16.0.50")
        True
        >>> is_private_ip("10.0.0.1")
        True
        >>> is_private_ip("8.8.8.8")
        False
        >>> is_private_ip("api.openai.com")
        False
    """
    # Known localhost values
    if hostname in ("localhost", "127.0.0.1", "[::1]", "0.0.0.0"):
        return True

    # Handle bracketed IPv6
    if hostname.startswith("[") and hostname.endswith("]"):
        hostname = hostname[1:-1]

    try:
        ip = ipaddress.ip_address(hostname)
        # Check if private (includes 10.x, 172.16-31.x, 192.168.x, fc00::/7, etc.)
        # Also check loopback and link-local
        return ip.is_private or ip.is_loopback or ip.is_link_local
    except ValueError:
        # Not a valid IP address, check for .local domain (mDNS)
        return hostname.endswith(".local")
