如何用NumPy(PEP257)规范为含*args的Python方法编写参数文档？

问题描述 #

我在类中定义了如下方法：

def add_seis(self, *args, timeout=-1):
    '''
    Add new Seis to live feed
    
    The user can provide an already defined Seis object
    or simply symbol, exchange and interval values. If
    latter is provided then new Seis object will be 
    created and returned after adding it to the live feed.
    Timeout value can be used to specify maximum wait time
    for the method to return.
    
    Parameters
    ----------
    ???
    '''

该方法允许传入单个Seis对象，或传入str、str、Interval三个值（内部会据此创建Seis对象）。需要按照NumPy（PEP257）规范，在Parameters部分正确编写*args的文档。

符合规范的写法 #

以下是适配NumPy风格的完整文档字符串：

def add_seis(self, *args, timeout=-1):
    '''
    向实时数据流添加新的Seis对象
    
    用户可以传入一个已定义的Seis对象，或者依次传入合约代码、交易所、时间周期三个值。
    如果传入的是后者，方法会自动创建新的Seis对象，添加到实时数据流后返回该对象。
    超时参数可用于指定方法返回前的最长等待时间。
    
    Parameters
    ----------
    *args : Seis or (str, str, Interval)
        两种合法传入方式：
        - 单个Seis对象：直接将该对象添加到实时数据流
        - 三元参数组：依次为合约代码（字符串类型）、交易所名称（字符串类型）、时间周期（Interval类型），
          方法会基于这三个参数创建新的Seis对象
    timeout : int, optional
        方法返回前的最长等待时间，默认值为-1（表示无超时限制）
    
    Returns
    -------
    Seis
        已添加到实时数据流的Seis对象
    '''

写法说明 #

1. 对*args的类型做明确声明，用or区分两种合法的参数组合
2. 用列表形式拆分两种传参逻辑，清晰说明每种方式的用途
3. 遵循NumPy文档的层级结构：参数名后紧跟类型，可选参数标注optional并说明默认值
4. 补充Returns模块（NumPy风格文档通常要求明确返回值信息），让文档逻辑更完整

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