Python类变量指向pandas函数实例调用报ValueError问题排查

计划基于面向对象机制实现多类型输入数据的统一读取逻辑：父类定义通用读取方法，内部调用read_func属性；子类负责实现read_func的具体逻辑，既可以直接指向pd.read_excel这类pandas内置读取函数，也可以在函数外封装自定义数据清洗步骤。

开发过程中出现异常，最小复现代码如下（test.py）：

import pandas as pd
class test:
  read_func = pd.read_excel
print(pd.read_excel("test.xlsx")) # 正常读取excel内容
print(test().read_func) # 输出 <bound method read_excel of <__main__.test object at 0x104cebc70>>
print(test().read_func("test.xlsx")) # 抛出错误

直接调用pd.read_excel("test.xlsx")可正常读取文件，调用实例的read_func传入文件路径时抛出如下错误：

Traceback (most recent call last):
  File "my/file/path/test.py", line 6, in <module>
    test().read_func("test.xlsx")
  File "/opt/homebrew/lib/python3.9/site-packages/pandas/util/_decorators.py", line 311, in wrapper
    return func(*args, **kwargs)
  File "/opt/homebrew/lib/python3.9/site-packages/pandas/io/excel/_base.py", line 457, in read_excel
    io = ExcelFile(io, storage_options=storage_options, engine=engine)
  File "/opt/homebrew/lib/python3.9/site-packages/pandas/io/excel/_base.py", line 1376, in __init__
    ext = inspect_excel_format(
  File "/opt/homebrew/lib/python3.9/site-packages/pandas/io/excel/_base.py", line 1250, in inspect_excel_format
    with get_handle(
  File "/opt/homebrew/lib/python3.9/site-packages/pandas/io/common.py", line 670, in get_handle
    ioargs = _get_filepath_or_buffer(
  File "/opt/homebrew/lib/python3.9/site-packages/pandas/io/common.py", line 427, in _get_filepath_or_buffer
    raise ValueError(msg)
ValueError: Invalid file path or buffer object type: <class '__main__.test'>

Python访问类实例的属性时，若属性是定义在类层面的可调用对象，会自动触发方法绑定机制：调用时会将实例自身作为第一个位置参数隐式传入。

类层面直接将pd.read_excel赋值给read_func属性后，通过实例执行test().read_func("test.xlsx")时，实际等价于调用pd.read_excel(<test类实例>, "test.xlsx")。pandas将接收到的test实例作为文件路径参数解析，最终抛出无效文件路径类型的错误，和报错信息中提示的参数类型为<class '__main__.test'>完全对应。

• 方案1：使用staticmethod包裹类属性的函数，阻止自动绑定行为。将类中的属性定义改为read_func = staticmethod(pd.read_excel)即可，实例调用时不会自动注入实例参数，行为和直接调用pd.read_excel完全一致，也支持替换为自定义封装的清洗函数。
• 方案2：按照最初的设计思路，不在实例层直接暴露可调用属性，而是在父类中定义显式的通用读取方法，内部调用类层面的读取函数，从设计上规避自动绑定问题，同时方便扩展通用前置、后置逻辑，参考实现：

import pandas as pd

class BaseDataReader:
    read_func = None
    def read(self, file_path, **kwargs):
        # 可扩展通用逻辑：参数校验、读取日志、异常捕获等
        raw_data = self.read_func(file_path, **kwargs)
        # 可扩展通用后置逻辑：格式转换、元数据记录等
        return raw_data

class ExcelReader(BaseDataReader):
    read_func = staticmethod(pd.read_excel)

# 带自定义清洗逻辑的子类示例
class CleanedExcelReader(BaseDataReader):
    @staticmethod
    def read_func(file_path, **kwargs):
        df = pd.read_excel(file_path, **kwargs)
        # 自定义清洗逻辑：去除全空行、统一列名格式等
        df = df.dropna(how="all")
        df.columns = [col.strip().lower() for col in df.columns]
        return df

• 方案3：在实例初始化阶段将读取函数赋值为实例属性，实例属性不会触发类级别的方法自动绑定逻辑：

import pandas as pd
class test:
    def __init__(self):
        self.read_func = pd.read_excel

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