chardet — 字符编码检测利器

# 手动尝试的致命问题
raw = b'\xc4\xe3\xba\xc3'  # "你好" 的 GBK 编码

# 尝试 UTF-8 → 失败
raw.decode('utf-8')  # UnicodeDecodeError

# 尝试 Latin-1 → "成功"但结果是乱码！
raw.decode('latin-1')  # 'ÄãºÃ' — 不报错但完全错误
# Latin-1 是单字节编码，任何 bytes 都能"解码"，但结果可能毫无意义

pip install chardet

import chardet

result = chardet.detect(b'some bytes')  # 调用 detect 函数，传入 bytes 数据
print(result)
# {'encoding': 'ascii', 'confidence': 1.0, 'language': ''}

import chardet

# 1. ASCII 文本 — 特征明确，confidence 为 1.0
result = chardet.detect(b'Hello, world!')  # 纯英文 ASCII 文本
print(result)
# {'encoding': 'ascii', 'confidence': 1.0, 'language': ''}
# encoding='ascii'：纯英文，ASCII 编码特征唯一
# confidence=1.0：100% 确定
# language=''：ASCII 不关联特定语言

# 2. GBK 编码的中文 — GBK 是 GB2312 的超集，检测可能返回 GB2312
data = '离离原上草，一岁一枯荣'.encode('gbk')  # 将中文编码为 GBK bytes
result = chardet.detect(data)  # 检测编码
print(result)
# {'encoding': 'GB2312', 'confidence': 0.7407407407407407, 'language': 'Chinese'}
# encoding='GB2312'：GBK 的子集，两者兼容
# confidence=0.74：中文短文本特征不够充分，置信度较低
# language='Chinese'：检测到中文语言特征

# 3. UTF-8 编码的中文 — UTF-8 特征字节明显，confidence 较高
data = '离离原上草，一岁一枯荣'.encode('utf-8')  # 将中文编码为 UTF-8 bytes
result = chardet.detect(data)  # 检测编码
print(result)
# {'encoding': 'utf-8', 'confidence': 0.99, 'language': ''}
# encoding='utf-8'：UTF-8 多字节序列特征明显
# confidence=0.99：接近 100% 确定
# language=''：UTF-8 是通用编码，不关联特定语言

import chardet
import locale

# Python 内置只能获取系统默认编码，无法检测未知 bytes 的编码
print(locale.getpreferredencoding())  # 如 'UTF-8'，仅反映系统设置

# chardet 可以检测任意 bytes 的实际编码
unknown_bytes = b'\xc4\xe3\xba\xc3'  # "你好" 的 GBK 编码
result = chardet.detect(unknown_bytes)  # 检测编码
print(result)  # {'encoding': 'GB2312', 'confidence': 0.676..., 'language': 'Chinese'}

# Python 内置 decode 必须指定编码，猜错就会报错
unknown_bytes.decode('utf-8')  # UnicodeDecodeError!
unknown_bytes.decode(result['encoding'])  # '你好' — 用 chardet 检测结果解码成功

import time
import chardet
import cchardet

# 准备测试数据：100KB 的中文 UTF-8 文本
test_data = '白日依山尽，黄河入海流。欲穷千里目，更上一层楼。'.encode('utf-8') * 1000
print(f'测试数据大小: {len(test_data) / 1024:.1f} KB')

# chardet 性能测试
start = time.perf_counter()  # 记录开始时间
for _ in range(10):  # 循环 10 次取平均
    result_py = chardet.detect(test_data)  # 纯 Python 检测
elapsed_py = (time.perf_counter() - start) / 10  # 计算平均耗时

# cchardet 性能测试
start = time.perf_counter()  # 记录开始时间
for _ in range(10):  # 循环 10 次取平均
    result_c = cchardet.detect(test_data)  # C 加速检测
elapsed_c = (time.perf_counter() - start) / 10  # 计算平均耗时

print(f'chardet:   {elapsed_py*1000:.1f}ms  →  {result_py}')
print(f'cchardet:  {elapsed_c*1000:.1f}ms  →  {result_c}')
print(f'加速比:    {elapsed_py / elapsed_c:.0f}x')
# 典型输出：
# chardet:   45.2ms  →  {'encoding': 'utf-8', 'confidence': 0.99, 'language': ''}
# cchardet:  0.8ms   →  {'encoding': 'utf-8', 'confidence': 0.99}
# 加速比:    56x

import chardet
import urllib.request
import re

def detect_web_encoding(url):
    """检测网页的实际编码，优先使用服务器声明，chardet 作为兜底"""
    # 第一步：下载网页原始字节
    response = urllib.request.urlopen(url)  # 发起 HTTP 请求
    raw_data = response.read()  # 读取原始 bytes（未解码）

    # 第二步：尝试从 HTTP 头获取编码
    content_type = response.headers.get('Content-Type', '')  # 获取 Content-Type 头
    declared_encoding = None
    if 'charset=' in content_type:
        # 从 Content-Type 中提取 charset 值
        declared_encoding = content_type.split('charset=')[-1].strip()

    # 第三步：尝试从 HTML meta 标签获取编码
    if not declared_encoding:
        # 用正则匹配 <meta charset="xxx"> 或 <meta http-equiv="Content-Type" content="...charset=xxx">
        meta_match = re.search(
            rb'<meta[^>]+charset=["\']?([^"\';\s>]+)',
            raw_data[:1024],  # 只搜索前 1024 字节（meta 标签通常在文件头）
            re.IGNORECASE
        )
        if meta_match:
            declared_encoding = meta_match.group(1).decode('ascii')  # 提取 meta 中的编码

    # 第四步：用 chardet 检测实际编码
    detected = chardet.detect(raw_data)  # 检测编码
    detected_encoding = detected['encoding']
    confidence = detected['confidence']

    # 第五步：决策逻辑 — 综合声明编码和检测结果
    if declared_encoding and confidence < 0.9:
        # 服务器声明了编码，但 chardet 不太确定，优先用服务器声明
        final_encoding = declared_encoding
        source = 'HTTP/meta header'
    elif confidence >= 0.9:
        # chardet 高置信度，使用检测结果
        final_encoding = detected_encoding
        source = 'chardet (high confidence)'
    else:
        # 都不确定，使用检测结果但标记为低置信度
        final_encoding = detected_encoding or 'utf-8'
        source = 'chardet (low confidence, fallback to utf-8)'

    # 第六步：解码网页内容
    html_text = raw_data.decode(final_encoding, errors='replace')  # errors='replace' 防止个别字符解码失败

    print(f'声明编码: {declared_encoding}')
    print(f'检测编码: {detected_encoding} (confidence={confidence:.2f})')
    print(f'最终编码: {final_encoding} (来源: {source})')
    return html_text

# 使用示例
html = detect_web_encoding('https://example.org')

import chardet

def read_file_with_auto_encoding(filepath, min_confidence=0.7):
    """
    自动检测文件编码并读取内容

    Args:
        filepath: 文件路径
        min_confidence: 最低置信度阈值，低于此值时回退到 utf-8

    Returns:
        (text, encoding, confidence) 元组
    """
    # 读取原始字节（注意：大文件应只读取前 N 字节，见 FAQ）
    with open(filepath, 'rb') as f:  # 以二进制模式打开，避免自动解码
        raw = f.read()  # 读取全部内容

    # 检测编码
    result = chardet.detect(raw)  # 调用 detect 检测编码
    encoding = result['encoding']  # 获取检测到的编码名
    confidence = result['confidence']  # 获取置信度

    # 置信度检查
    if confidence < min_confidence:
        print(f'警告: 检测置信度 {confidence:.2f} 低于阈值 {min_confidence}')
        print(f'检测编码: {encoding}，回退到 utf-8')
        encoding = 'utf-8'  # 低置信度时回退到 utf-8

    # 解码文件内容
    try:
        text = raw.decode(encoding, errors='replace')  # 尝试用检测到的编码解码
    except (LookupError, UnicodeDecodeError) as e:
        # LookupError: 编码名不被 Python 识别
        # UnicodeDecodeError: 编码名有效但解码失败
        print(f'解码失败: {e}，回退到 utf-8')
        text = raw.decode('utf-8', errors='replace')  # 回退到 utf-8
        encoding = 'utf-8'

    return text, encoding, confidence

# 使用示例
text, enc, conf = read_file_with_auto_encoding('unknown_encoding.txt')
print(f'编码: {enc}, 置信度: {conf:.2f}')
print(f'内容前 100 字: {text[:100]}')

import chardet
import os
import time

def batch_detect_encoding(directory, extensions=None, use_cchardet=False):
    """
    批量检测目录下所有文件的编码

    Args:
        directory: 目标目录路径
        extensions: 只检测指定扩展名，如 ['.txt', '.csv']，None 表示所有文件
        use_cchardet: 是否使用 cchardet 加速（需安装 cchardet）

    Returns:
        检测结果列表，每项包含 (filepath, encoding, confidence)
    """
    # 选择检测引擎
    if use_cchardet:
        try:
            import cchardet as detector  # 尝试导入 cchardet
        except ImportError:
            print('cchardet 未安装，回退到 chardet')
            import chardet as detector  # 回退到 chardet
    else:
        import chardet as detector  # 使用 chardet

    results = []
    start_time = time.perf_counter()  # 记录开始时间

    for root, dirs, files in os.walk(directory):  # 递归遍历目录
        for filename in files:
            # 过滤扩展名
            if extensions and not any(filename.endswith(ext) for ext in extensions):
                continue  # 跳过不匹配的文件

            filepath = os.path.join(root, filename)  # 拼接完整路径

            try:
                # 只读取前 1024 字节用于检测（提升速度，对大多数编码足够）
                with open(filepath, 'rb') as f:
                    raw = f.read(1024)  # 读取前 1KB

                if not raw:  # 空文件
                    results.append((filepath, 'empty', 0.0)
                    continue

                result = detector.detect(raw)  # 检测编码
                results.append((
                    filepath,
                    result.get('encoding') or 'unknown',  # encoding 可能为 None
                    result.get('confidence', 0.0)  # 获取置信度
                )
            except (IOError, OSError) as e:
                results.append((filepath, f'error: {e}', 0.0)

    # 按置信度排序，低置信度的排在前面（需要关注的）
    results.sort(key=lambda x: x[2])

    elapsed = time.perf_counter() - start_time  # 计算总耗时

    # 打印报告
    print(f'\n批量编码检测报告（共 {len(results)} 个文件，耗时 {elapsed:.2f}s）')
    print(f'{"文件路径":<50} {"编码":<15} {"置信度":<10}')
    print('-' * 75)
    for filepath, encoding, confidence in results:
        flag = ' ⚠️' if confidence < 0.8 else ''  # 低置信度标记
        print(f'{filepath:<50} {encoding:<15} {confidence:.2f}{flag}')

    # 统计摘要
    low_conf = sum(1 for _, _, c in results if c < 0.8 and c > 0)
    print(f'\n低置信度文件（< 0.8）: {low_conf} 个，需人工确认')

    return results

# 使用示例
results = batch_detect_encoding('./data', extensions=['.txt', '.csv', '.log'])
# 如需加速：results = batch_detect_encoding('./data', use_cchardet=True)

from chardet.universaldetector import UniversalDetector

def detect_large_file(filepath, chunk_size=4096):
    """增量检测大文件编码，避免一次性读入内存"""
    detector = UniversalDetector()  # 创建检测器实例

    with open(filepath, 'rb') as f:  # 以二进制模式打开
        while True:
            chunk = f.read(chunk_size)  # 分块读取，每次 4KB
            if not chunk:  # 文件读取完毕
                break
            detector.feed(chunk)  # 喂入数据，增量分析
            # 如果已经确定编码，提前结束（节省时间）
            if detector.done:
                print(f'提前确定编码，已读取 {f.tell()} 字节')
                break

    detector.close()  # 关闭检测器，触发最终计算
    result = detector.result  # 获取检测结果
    print(f'编码: {result["encoding"]}, 置信度: {result["confidence"]:.2f}')
    return result

# 使用示例
result = detect_large_file('large_file.txt')

def smart_decode(raw_bytes, min_confidence=0.7):
    """智能解码：低置信度时尝试多种策略"""
    result = chardet.detect(raw_bytes)  # 先用 chardet 检测

    if result['confidence'] >= min_confidence:  # 置信度足够高
        return raw_bytes.decode(result['encoding'])  # 直接解码

    # 策略1：检查 BOM（字节序标记）
    if raw_bytes[:3] == b'\xef\xbb\xbf':  # UTF-8 BOM
        return raw_bytes[3:].decode('utf-8')  # 跳过 BOM 后解码
    if raw_bytes[:2] in (b'\xff\xfe', b'\xfe\xff'):  # UTF-16 BOM
        return raw_bytes.decode('utf-16')  # UTF-16 解码

    # 策略2：尝试常见编码列表
    for encoding in ['utf-8', 'gbk', 'latin-1']:
        try:
            return raw_bytes.decode(encoding)  # 尝试解码
        except UnicodeDecodeError:
            continue  # 失败则尝试下一个

    # 策略3：最终兜底 — utf-8 + 替换错误字符
    return raw_bytes.decode('utf-8', errors='replace')

# 方案1：只检测前 1024 字节（推荐，对大多数编码足够）
with open('big_file.txt', 'rb') as f:
    header = f.read(1024)  # 只读前 1KB
result = chardet.detect(header)  # 检测速度大幅提升

# 方案2：使用 cchardet（API 完全兼容，只需替换 import）
import cchardet as chardet  # 替换 import，其余代码不变
result = chardet.detect(raw_bytes)

# 方案3：多进程批量检测（绕过 GIL）
from concurrent.futures import ProcessPoolExecutor

def detect_one(filepath):
    with open(filepath, 'rb') as f:
        raw = f.read(1024)
    return filepath, chardet.detect(raw)

with ProcessPoolExecutor(max_workers=4) as executor:  # 4 个进程并行
    results = list(executor.map(detect_one, file_list)

from chardet.universaldetector import UniversalDetector

def detect_encoding_smart(filepath, max_sample=65536):
    """
    智能检测大文件编码
    - 先检查 BOM（只需前几字节）
    - 再采样前 64KB 数据检测
    - 如果不确定，继续读取更多数据
    """
    # 第一步：检查 BOM（字节序标记）
    with open(filepath, 'rb') as f:
        header = f.read(4)  # 读取前 4 字节（UTF-32 BOM 最长 4 字节）

    if header[:3] == b'\xef\xbb\xbf':  # UTF-8 BOM: EF BB BF
        return 'utf-8-sig'  # Python 的 utf-8-sig 编码会自动处理 BOM
    if header[:2] in (b'\xff\xfe', b'\xfe\xff'):  # UTF-16 BOM
        return 'utf-16'
    if header[:4] in (b'\xff\xfe\x00\x00', b'\x00\x00\xfe\xff'):  # UTF-32 BOM
        return 'utf-32'

    # 第二步：采样检测（只读前 64KB，避免内存问题）
    detector = UniversalDetector()  # 创建增量检测器
    with open(filepath, 'rb') as f:
        total_read = 0
        while total_read < max_sample:  # 最多读取 max_sample 字节
            chunk = f.read(4096)  # 每次读 4KB
            if not chunk:  # 文件已读完
                break
            detector.feed(chunk)  # 喂入数据
            total_read += len(chunk)  # 累计已读字节数
            if detector.done:  # 已确定编码
                break

    detector.close()  # 关闭检测器
    return detector.result['encoding'] or 'utf-8'  # 返回编码，不确定则回退 utf-8

# charset_normalizer 用法（API 类似）
import charset_normalizer
result = charset_normalizer.detect(b'some bytes')
# {'encoding': 'ascii', 'confidence': 1.0, 'language': ''}

# charset_normalizer 的高级用法：获取多个候选结果
matches = charset_normalizer.from_bytes(b'some bytes')
for match in matches:  # 按置信度排序的候选列表
    print(f'{match.encoding} (confidence={match.spec_encoding})')

import chardet

def detect_mixed_encoding(raw_bytes, chunk_size=1024):
    """
    分段检测混合编码
    将数据分成多个片段，分别检测每段的编码

    Args:
        raw_bytes: 原始字节数据
        chunk_size: 每段的大小（字节）

    Returns:
        分段检测结果列表
    """
    results = []
    offset = 0  # 当前偏移量

    while offset < len(raw_bytes):
        chunk = raw_bytes[offset:offset + chunk_size]  # 截取当前段
        result = chardet.detect(chunk)  # 检测当前段编码
        results.append({
            'offset': offset,  # 起始偏移量
            'size': len(chunk),  # 段大小
            'encoding': result['encoding'],  # 检测到的编码
            'confidence': result['confidence']  # 置信度
        })
        offset += chunk_size  # 移动到下一段

    # 打印分段结果
    print(f'{"偏移量":<10} {"大小":<8} {"编码":<15} {"置信度":<10}')
    print('-' * 45)
    for r in results:
        print(f'{r["offset"]:<10} {r["size"]:<8} {r["encoding"]:<15} {r["confidence"]:.2f}')

    # 检查是否存在编码切换
    encodings = [r['encoding'] for r in results if r['encoding']]
    unique_encodings = set(encodings)
    if len(unique_encodings) > 1:
        print(f'\n⚠️ 检测到混合编码: {unique_encodings}')
        print('建议：分段解码后拼接')

    return results

# 使用示例：模拟混合编码数据
part1 = '这是中文部分'.encode('gbk')  # GBK 编码的中文
part2 = 'This is English part'.encode('ascii')  # ASCII 编码的英文
mixed = part1 + part2
results = detect_mixed_encoding(mixed, chunk_size=10)

import chardet

# GBK 编码的中文被检测为 GB2312
data = '你好世界'.encode('gbk')
result = chardet.detect(data)
print(result)  # {'encoding': 'GB2312', ...}

# 解决方案：如果检测到 GB2312，尝试用 GBK 解码（GBK 是 GB2312 的超集）
encoding = result['encoding']
if encoding and encoding.upper() in ('GB2312', 'GB18030'):
    # GBK 包含 GB2312 的全部字符，且支持更多汉字
    try:
        text = data.decode('gbk')  # 优先用 GBK 解码
        print(f'GBK 解码成功: {text}')
    except UnicodeDecodeError:
        text = data.decode(encoding)  # 回退到检测到的编码