charset-normalizer 3.5.1: charset_normalizer.detect

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 charset_normalizer.detect in pkg:pypi/charset-normalizer@3.5.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/charset-normalizer@3.5.1
Demonstrate these symbols/APIs:
  - charset_normalizer.detect

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:cf67defb69f32292fb435499cb536b9728bf031e669edaa344074b6ce5b77fec","contract":["charset_normalizer.detect(data) detects character encoding from raw byte sequences","detect(data) returns dictionary with encoding, language, and confidence","detect(data) returns encoding='utf-8' and confidence=1.0 for UTF-8 encoded text","detect(data) returns encoding='ascii' and confidence=1.0 for ASCII text","detect(data) accepts bytearray input instances","detect(data) raises TypeError when input is not bytes or bytearray"],"goal":"verify charset_normalizer.detect in pkg:pypi/charset-normalizer@3.5.1","kind":"HOW","packages":["pkg:pypi/charset-normalizer@3.5.1"],"schemaVersion":1,"symbols":["charset_normalizer.detect"]},"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/charset-normalizer@3.5.1"],"schemaVersion":1,"subject":"pkg:pypi/charset-normalizer@3.5.1","symbols":["charset_normalizer.detect"],"verifierAdapter":"python@1"}

charset-normalizer==3.5.1

{
  "schemaVersion": 1,
  "goal": "verify charset_normalizer.detect in pkg:pypi/charset-normalizer@3.5.1",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/charset-normalizer@3.5.1"
  ],
  "symbols": [
    "charset_normalizer.detect"
  ]
}

"""Charset detection module demonstrating charset_normalizer.detect."""

import charset_normalizer


def detect_charset(data: bytes | bytearray) -> dict:
    """Detect character encoding from raw bytes using charset_normalizer.detect.

    Args:
        data: Raw byte sequence to analyze.

    Returns:
        dict containing 'encoding', 'language', and 'confidence'.

    Raises:
        TypeError: If data is not bytes or bytearray.
    """
    if not isinstance(data, (bytes, bytearray)):
        raise TypeError(f"Expected bytes or bytearray, got {type(data).__name__}")

    return charset_normalizer.detect(data)

"""Contract verification test for charset_normalizer.detect."""

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 charset_normalizer
from src.detector import detect_charset


def test_detect_utf8():
    raw = "Hello world! Café & résumé.".encode("utf-8")
    result = charset_normalizer.detect(raw)
    assert isinstance(result, dict), f"Expected dict, got {type(result)}"
    assert result.get("encoding") == "utf-8", f"Expected utf-8, got {result.get('encoding')}"
    assert result.get("confidence") == 1.0, f"Expected 1.0 confidence, got {result.get('confidence')}"


def test_detect_ascii():
    raw = b"Simple plain ASCII text without special characters."
    result = charset_normalizer.detect(raw)
    assert isinstance(result, dict), f"Expected dict, got {type(result)}"
    assert result.get("encoding") == "ascii", f"Expected ascii, got {result.get('encoding')}"
    assert result.get("confidence") == 1.0, f"Expected 1.0 confidence, got {result.get('confidence')}"


def test_detect_bytearray():
    raw = bytearray(b"Bytearray payload for charset detection.")
    result = charset_normalizer.detect(raw)
    assert isinstance(result, dict), f"Expected dict, got {type(result)}"
    assert result.get("encoding") == "ascii", f"Expected ascii, got {result.get('encoding')}"
    assert result.get("confidence") == 1.0, f"Expected 1.0 confidence, got {result.get('confidence')}"


def test_detect_wrapper():
    raw = "Sample payload for wrapper verification.".encode("utf-8")
    result = detect_charset(raw)
    assert isinstance(result, dict), f"Expected dict, got {type(result)}"
    assert result.get("encoding") in ("ascii", "utf-8"), f"Unexpected encoding: {result.get('encoding')}"
    assert result.get("confidence") == 1.0, f"Unexpected confidence: {result.get('confidence')}"


def test_detect_type_error():
    try:
        charset_normalizer.detect("not-bytes-string")
        assert False, "Expected TypeError when passing str to charset_normalizer.detect"
    except TypeError:
        pass

    try:
        detect_charset(12345)
        assert False, "Expected TypeError when passing int to detect_charset"
    except TypeError:
        pass


def main():
    test_detect_utf8()
    test_detect_ascii()
    test_detect_bytearray()
    test_detect_wrapper()
    test_detect_type_error()
    print("Contract verification for charset_normalizer.detect passed.")
    return 0


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