idna 3.11: encode, decode, uts46_remap

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/idna@3.11
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/idna@3.11
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:f050b8b578c60c7b7d32bb5960ecf9a5a33d4acdf3b3a85363f201510ef0a28d","contract":["idna.encode(name) encodes internationalized domain names into Punycode bytes","idna.decode(bytes) decodes Punycode byte sequences into Unicode domain strings","idna.uts46_remap(domain) remaps and normalizes domain names following UTS 46","idna.encode(name) raises IDNAError when domain labels are invalid or empty"],"goal":"verify pkg:pypi/idna@3.11","kind":"HOW","packages":["pkg:pypi/idna@3.11"],"schemaVersion":1,"symbols":["encode","decode","uts46_remap"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"alpine","ecosystem":"pypi","language":"python","libc":"musl","libcVersion":"1.2","os":"linux","osVersionBucket":"24","packageManager":"pip","runtime":"python","runtimeVersion":"3.12","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/idna@3.11"],"schemaVersion":1,"subject":"pkg:pypi/idna@3.11","symbols":["encode","decode","uts46_remap"],"verifierAdapter":"python@1"}

idna==3.11

{
  "schemaVersion": 1,
  "goal": "verify pkg:pypi/idna@3.11",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/idna@3.11"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

"""Domain encoding and decoding module demonstrating idna library functions."""

import idna


def encode_domain(domain_name: str) -> bytes:
    """Encode an internationalized domain name into IDNA 2008 / Punycode bytes.

    Args:
        domain_name: Unicode domain name string.

    Returns:
        ASCII bytes representation of the domain name.

    Raises:
        idna.IDNAError: If the domain name or label violates IDNA rules.
    """
    return idna.encode(domain_name)


def decode_domain(domain_bytes: bytes) -> str:
    """Decode IDNA 2008 / Punycode byte sequence back to a Unicode domain name string.

    Args:
        domain_bytes: ASCII bytes or bytearray of the Punycode domain name.

    Returns:
        Decoded Unicode domain name string.

    Raises:
        idna.IDNAError: If the Punycode sequence is invalid.
    """
    return idna.decode(domain_bytes)


def normalize_domain(domain_name: str) -> str:
    """Normalize and remap a domain name string using UTS 46 rules.

    Args:
        domain_name: Unicode domain name string.

    Returns:
        Remapped and normalized domain name string.

    Raises:
        idna.IDNAError: If the domain name contains prohibited codepoints under UTS 46.
    """
    return idna.uts46_remap(domain_name)

"""Contract verification test for pkg:pypi/idna@3.11."""

import os
import sys

# Ensure repository root is on sys.path
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

import idna
from src.domain_codec import decode_domain, encode_domain, normalize_domain


def test_encode():
    # Internationalized domain name with non-ASCII characters
    unicode_domain = "bücher.example"
    encoded = encode_domain(unicode_domain)
    assert isinstance(encoded, bytes), f"Expected bytes, got {type(encoded)}"
    assert encoded == b"xn--bcher-kva.example", f"Unexpected encoded value: {encoded}"

    # Direct library call
    direct_encoded = idna.encode("münchen.example")
    assert direct_encoded == b"xn--mnchen-3ya.example", f"Unexpected encoded value: {direct_encoded}"

    # Pure ASCII domain name
    ascii_domain = "example.com"
    encoded_ascii = encode_domain(ascii_domain)
    assert encoded_ascii == b"example.com", f"Unexpected encoded ASCII value: {encoded_ascii}"


def test_decode():
    # Punycode byte sequence decoded back to unicode
    punycode_bytes = b"xn--bcher-kva.example"
    decoded = decode_domain(punycode_bytes)
    assert isinstance(decoded, str), f"Expected str, got {type(decoded)}"
    assert decoded == "bücher.example", f"Unexpected decoded value: {decoded}"

    # Direct library call with bytes and str
    direct_decoded = idna.decode(b"xn--mnchen-3ya.example")
    assert direct_decoded == "münchen.example", f"Unexpected decoded value: {direct_decoded}"

    # ASCII domain decoding
    ascii_bytes = b"example.com"
    decoded_ascii = decode_domain(ascii_bytes)
    assert decoded_ascii == "example.com", f"Unexpected decoded ASCII value: {decoded_ascii}"


def test_uts46_remap():
    # Normalizing mixed-case internationalized domain
    raw_domain = "Bücher.Example"
    remapped = normalize_domain(raw_domain)
    assert isinstance(remapped, str), f"Expected str, got {type(remapped)}"
    assert remapped == "bücher.example", f"Unexpected remapped value: {remapped}"

    # Direct library call
    direct_remapped = idna.uts46_remap("EXAMPLE.COM")
    assert direct_remapped == "example.com", f"Unexpected remapped value: {direct_remapped}"


def test_error_handling():
    # Empty label / invalid double dots
    try:
        encode_domain("invalid..domain")
        assert False, "Expected IDNAError on invalid domain name"
    except idna.IDNAError:
        pass

    # Invalid Punycode A-label decoding
    try:
        decode_domain(b"xn--invalid_label!!!")
        assert False, "Expected IDNAError on invalid A-label"
    except idna.IDNAError:
        pass


def main():
    test_encode()
    test_decode()
    test_uts46_remap()
    test_error_handling()
    print("Contract tests for pkg:pypi/idna@3.11 passed successfully.")
    return 0


if __name__ == "__main__":
    sys.exit(main())