如何修复str | bytebuf类型变量调用startswith()的类型检查错误？

我编写了如下Python代码，用于解析JSONLZ4格式的数据：

import json
from typing_extensions import Any

import lz4.block

bytebuf = bytes | bytearray
MAGIC_HEADER = b"mozLz40\0"


def jsonlz4_loads(buf: str | bytebuf) -> Any:
    if isinstance(buf, bytebuf):
        header: bytes = MAGIC_HEADER
    else:
        header: str = MAGIC_HEADER.decode("ascii")

    if not buf.startswith(header):
        raise ValueError("Not a valid JSONLZ4 buffer - magic bytes missing")

    return json.loads(lz4.block.decompress(buf[len(header):]))

使用ty（astral）、pyright、pyrefly、mypy等主流类型检查器时，buf.startswith()处出现参数类型不兼容错误，报错信息如下：

jsonlz4.py:18:27: error[invalid-argument-type] Argument to bound method `startswith` is incorrect: Expected `str | tuple[str, ...]`, found `Literal[b"mozLz40\x00"] | str`
jsonlz4.py:18:27: error[invalid-argument-type] Argument to bound method `startswith` is incorrect: Expected `Buffer | tuple[Buffer, ...]`, found `Literal[b"mozLz40\x00"] | str`
jsonlz4.py:18:27: error[invalid-argument-type] Argument to bound method `startswith` is incorrect: Expected `Buffer | tuple[Buffer, ...]`, found `Literal[b"mozLz40\x00"] | str`

我原以为isinstance(buf, bytebuf)已完成足够的类型窄化，但显然存在问题。请问如何在不使用# type: ignore的情况下让代码通过类型检查？

类型检查器无法自动关联buf与header的类型分支关系——它没法推断出buf为bytes/bytearray时header一定是bytes，buf为str时header一定是str。以下是几种可行的修复方式：

方法1：将检查逻辑合并到类型分支内 #

把startswith的校验放到对应的类型判断分支中，让类型检查器明确每个分支里buf和header的类型完全匹配，同时还能修复原代码中str类型传入lz4的运行时错误：

import json
from typing_extensions import Any

import lz4.block

bytebuf = bytes | bytearray
MAGIC_HEADER = b"mozLz40\0"
MAGIC_HEADER_STR = MAGIC_HEADER.decode("ascii")


def jsonlz4_loads(buf: str | bytebuf) -> Any:
    if isinstance(buf, bytebuf):
        if not buf.startswith(MAGIC_HEADER):
            raise ValueError("Not a valid JSONLZ4 buffer - magic bytes missing")
        decompressed_data = lz4.block.decompress(buf[len(MAGIC_HEADER):])
    else:
        if not buf.startswith(MAGIC_HEADER_STR):
            raise ValueError("Not a valid JSONLZ4 buffer - magic bytes missing")
        # str类型需转成bytes才能传给lz4解压
        decompressed_data = lz4.block.decompress(buf[len(MAGIC_HEADER_STR):].encode("ascii"))
    
    return json.loads(decompressed_data)

方法2：使用类型守卫（Python 3.10+） #

自定义类型守卫函数，让类型检查器更精准地识别buf的类型，避免分支推断歧义：

import json
from typing import TypeGuard
from typing_extensions import Any

import lz4.block

bytebuf = bytes | bytearray
MAGIC_HEADER = b"mozLz40\0"
MAGIC_HEADER_STR = MAGIC_HEADER.decode("ascii")


def is_bytebuf(buf: str | bytebuf) -> TypeGuard[bytebuf]:
    return isinstance(buf, (bytes, bytearray))


def jsonlz4_loads(buf: str | bytebuf) -> Any:
    if is_bytebuf(buf):
        if not buf.startswith(MAGIC_HEADER):
            raise ValueError("Not a valid JSONLZ4 buffer - magic bytes missing")
        decompressed_data = lz4.block.decompress(buf[len(MAGIC_HEADER):])
    else:
        if not buf.startswith(MAGIC_HEADER_STR):
            raise ValueError("Not a valid JSONLZ4 buffer - magic bytes missing")
        decompressed_data = lz4.block.decompress(buf[len(MAGIC_HEADER_STR):].encode("ascii"))
    
    return json.loads(decompressed_data)

方法3：显式类型转换（不推荐，仅作应急） #

如果不想重构代码结构，可以用typing.cast强制告诉类型检查器当前buf和header的类型匹配，但这种方式会弱化类型检查的严谨性：

import json
from typing import cast
from typing_extensions import Any

import lz4.block

bytebuf = bytes | bytearray
MAGIC_HEADER = b"mozLz40\0"


def jsonlz4_loads(buf: str | bytebuf) -> Any:
    if isinstance(buf, bytebuf):
        header = cast(bytes, MAGIC_HEADER)
        buf = cast(bytebuf, buf)
    else:
        header = cast(str, MAGIC_HEADER.decode("ascii"))
        buf = cast(str, buf)

    if not buf.startswith(header):
        raise ValueError("Not a valid JSONLZ4 buffer - magic bytes missing")
    
    # 处理str转bytes的运行时问题
    raw_data = buf[len(header):]
    if isinstance(raw_data, str):
        raw_data = raw_data.encode("ascii")
    
    return json.loads(lz4.block.decompress(raw_data))

内容的提问来源于stack exchange，提问作者mathrick