idna 3.11: decode

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 idna.decode in pkg:pypi/idna@3.11
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/idna@3.11
Demonstrate these symbols/APIs:
  - idna.decode

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:51b83d55bd7c99d46ace6e1da3dd0fcac8ce3e38b18bab3668fb7dba5a67994c","contract":["idna.decode(s) decodes ASCII-compatible encoded (ACE/Punycode) domain name strings to Unicode","idna.decode(s) accepts bytes and bytearray input representations","idna.decode(s) returns plain ASCII domain names unchanged","idna.decode(s) preserves trailing root domain dot","idna.decode(s) decodes multiple internationalized domain labels separated by dots","idna.decode(s) raises idna.IDNAError on malformed Punycode labels or leading dots"],"goal":"verify idna.decode in pkg:pypi/idna@3.11","kind":"HOW","packages":["pkg:pypi/idna@3.11"],"schemaVersion":1,"symbols":["idna.decode"]},"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/idna@3.11"],"schemaVersion":1,"subject":"pkg:pypi/idna@3.11","symbols":["idna.decode"],"verifierAdapter":"python@1"}

idna==3.11

{
  "schemaVersion": 1,
  "goal": "verify idna.decode in pkg:pypi/idna@3.11",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/idna@3.11"
  ],
  "symbols": [
    "idna.decode"
  ]
}

"""Domain name decoding module demonstrating idna.decode."""

from typing import Union
import idna


def decode_domain(domain: Union[str, bytes, bytearray], uts46: bool = False, strict: bool = False) -> str:
    """Decode an ASCII-compatible encoded (ACE/Punycode) domain name to Unicode.

    Args:
        domain: Domain name as str, bytes, or bytearray.
        uts46: Enable UTS#46 compatibility processing.
        strict: Enforce strict IDNA2008 validation rules.

    Returns:
        Decoded Unicode domain name.

    Raises:
        idna.IDNAError: If domain contains invalid Punycode or violates IDNA rules.
    """
    return idna.decode(domain, uts46=uts46, strict=strict)

"""Contract verification test for idna.decode."""

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_decoder import decode_domain


def test_decode_punycode_str():
    # idna.decode(s) decodes ASCII-compatible encoded (ACE/Punycode) domain name strings to Unicode
    ace_domain = "xn--bcher-kva.example"
    expected = "bücher.example"
    result = idna.decode(ace_domain)
    assert result == expected, f"Expected {expected}, got {result}"

    wrapped = decode_domain(ace_domain)
    assert wrapped == expected, f"Expected {expected}, got {wrapped}"


def test_decode_bytes_and_bytearray():
    # idna.decode(s) accepts bytes and bytearray input representations
    expected = "bücher.example"

    bytes_input = b"xn--bcher-kva.example"
    result_bytes = idna.decode(bytes_input)
    assert result_bytes == expected, f"Expected {expected}, got {result_bytes}"

    bytearray_input = bytearray(b"xn--bcher-kva.example")
    result_bytearray = idna.decode(bytearray_input)
    assert result_bytearray == expected, f"Expected {expected}, got {result_bytearray}"

    assert decode_domain(bytes_input) == expected
    assert decode_domain(bytearray_input) == expected


def test_decode_plain_ascii():
    # idna.decode(s) returns plain ASCII domain names unchanged
    ascii_domain = "example.com"
    result = idna.decode(ascii_domain)
    assert result == "example.com", f"Expected 'example.com', got {result}"
    assert decode_domain(ascii_domain) == "example.com"


def test_decode_preserve_trailing_dot():
    # idna.decode(s) preserves trailing root domain dot
    trailing = "xn--bcher-kva.example."
    assert idna.decode(trailing) == "bücher.example."
    assert decode_domain(trailing) == "bücher.example."


def test_decode_multiple_labels():
    # idna.decode(s) decodes multiple internationalized domain labels separated by dots
    multi_label = "xn--mnchen-3ya.xn--bcher-kva.de"
    expected = "münchen.bücher.de"
    result = idna.decode(multi_label)
    assert result == expected, f"Expected {expected}, got {result}"
    assert decode_domain(multi_label) == expected


def test_decode_malformed_punycode_raises_idna_error():
    # idna.decode(s) raises idna.IDNAError on malformed Punycode labels or leading dots
    invalid_inputs = ["xn--", "xn--invalid!label", "..", ".xn--bcher-kva.example"]
    for item in invalid_inputs:
        try:
            idna.decode(item)
            assert False, f"Expected idna.IDNAError for {item!r}"
        except idna.IDNAError:
            pass

        try:
            decode_domain(item)
            assert False, f"Expected idna.IDNAError for decode_domain({item!r})"
        except idna.IDNAError:
            pass


def main():
    test_decode_punycode_str()
    test_decode_bytes_and_bytearray()
    test_decode_plain_ascii()
    test_decode_preserve_trailing_dot()
    test_decode_multiple_labels()
    test_decode_malformed_punycode_raises_idna_error()
    print("Contract verification for idna.decode passed.")
    return 0


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