无需触发LSP Pyright错误的tqdm进度条优雅切换方案

我基于docx2pdf开发自定义Python CLI工具，需要通过CLI的log参数控制tqdm进度条的显示/隐藏。目前通过partialmethod修改tqdm.__init__的方式实现了功能，但Pyright提示类型错误：Cannot assign member "__init__" for type "type [tqdm [_T@tqdm]]"，需要更优雅的实现方式或报错修复方案。

方案一：封装自定义tqdm工具函数（推荐） #

不用修改tqdm原类，而是封装一个全局可控的工具函数，通过全局变量控制disable参数，既避免类型检查报错，又不会污染全局tqdm行为：

from tqdm import tqdm
from typing import Iterable, Any, Optional

# 全局开关，从CLI的log参数赋值（log为True则启用进度条）
tqdm_enabled: bool = True

def my_tqdm(
    iterable: Optional[Iterable[Any]] = None,
    **kwargs: Any
) -> tqdm:
    # 根据全局开关自动设置disable参数，也允许传入kwargs覆盖
    return tqdm(iterable, disable=not tqdm_enabled, **kwargs)

使用时直接替换原tqdm调用：

# CLI初始化阶段设置开关
tqdm_enabled = cli_log_param

# 业务代码中使用
for file in my_tqdm(docx_files):
    docx2pdf.convert(file)

方案二：继承tqdm实现可控子类 #

通过继承tqdm重写__init__方法，把控制逻辑封装在子类中，同样避免全局修改：

方式1：实例化时传入log参数 #

from tqdm import tqdm
from typing import Iterable, Any

class ControlledTqdm(tqdm):
    def __init__(self, iterable: Optional[Iterable[Any]] = None, *, log: bool = True, **kwargs: Any):
        super().__init__(iterable, disable=not log, **kwargs)

# 使用时直接传入CLI的log参数
for file in ControlledTqdm(docx_files, log=cli_log_param):
    docx2pdf.convert(file)

方式2：全局类属性控制 #

from tqdm import tqdm
from typing import Iterable, Any

class ControlledTqdm(tqdm):
    enabled = True
    def __init__(self, iterable: Optional[Iterable[Any]] = None, **kwargs: Any):
        super().__init__(iterable, disable=not self.enabled, **kwargs)

# CLI初始化阶段设置全局开关
ControlledTqdm.enabled = cli_log_param

# 业务代码中使用
for file in ControlledTqdm(docx_files):
    docx2pdf.convert(file)

方案三：临时抑制Pyright报错（不推荐） #

如果必须保留原有的monkey patching方式，可以通过类型忽略注释让Pyright跳过检查，但这种方式会带来全局修改的副作用（其他地方的tqdm也会被禁用），仅作为临时妥协方案：

from functools import partialmethod
from tqdm import tqdm

def tqdm_log(log: bool = False) -> None:
    ''' tqdm logging switch '''
    if not log:
        # 告诉Pyright忽略这个赋值的类型检查
        # pyright: ignore[assignment]
        tqdm.__init__ = partialmethod(tqdm.__init__, disable=True)

总结 #

优先选择方案一或方案二，它们遵循Python的封装原则，不会污染全局依赖，同时完美兼容类型检查工具，代码可读性和可维护性更强。

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