如何在Python中记录结构？

12 投票

6 回答

4399 浏览

提问于 2025-04-17 15:08

如果一个函数的参数需要是某种特定的结构，比如用 Python 的 list、tuple 和 dict 创建的结构，那么应该怎么和在哪里进行说明呢？

下面是一个示例文档：

def foo(bar):
    """
    Args:
        bar: 2-tuple, ([(<mapping>,<number>), ...], <string>)
    """
    pass

这个示例有点繁琐，存在一些问题：

这个结构很难读懂
很难说明结构中每个元素的具体含义
怎么表示长度不是固定的
应该只在一个地方说明，还是到处都要说明
补充：怎么清楚地表明某个元素可以是鸭子类型（也就是说，"dict" 和 "像映射的东西" 都可以）

补充：这个示例并不是为了强制规定类型，而是为了说明一种结构。在这个情况下，鸭子类型是 可以的。

数据结构文档生成代码注释可读性鸭子类型结构化数据类型注解参数说明

6 个回答

我简单回答你的问题就是引用一下Python的哲学："明确比隐含更好"。对于你的问题来说，这意味着要把需要的内容写得清清楚楚，哪怕为了说明一个参数需要写一整段话。你可以看看Python的文档，里面有很多例子。在你的具体情况下，你可以用序列来表示鸭子类型，而不是用元组（可以参考http://docs.python.org/2/library/collections.html#collections-abstract-base-classes）。

回答于 2025-04-17 由 Python大师

分享举报

如果你在使用Python 3，可能会对“函数注解”感兴趣。它们不是强制的，完全可以选择使用，但看起来能满足你的需求。注解可以是任何Python表达式，它们会放在函数头部，和参数一起。例如（抱歉这个例子有点无厘头）：

def fn(name: str, age: int, hobbies: "something else goes here") -> max(2, 9):
  # la la la
  return 9

这里有更多的细节（包括可能的使用场景和示例）：PEP 3107

回答于 2025-04-17 由 Python大师

分享举报

我在工作中遇到了这个问题。根据我个人的研究（也就是做了一些比较全面的谷歌搜索），发现没有一个标准的方法来记录复杂的、嵌套的函数参数。于是我自己想出了一个方法，用 <> 来表示数据结构中的元素，每个元素都有自己的标题和段落来说明。在这里举个例子：

<options>
---------

A mapping:

  {'years':<years>,
   'states':<states>}

This is the root level of the `options` argument.

<years>
-------

A sequence of integers, each of which is a year to be included in the analysis.


<states>
--------

A sequence of strings, each of which is a state to be included in the analysis.

这些文档可以放在函数的文档字符串里，但在我的情况下，我选择把它单独写成一个文档。这个方法也可以扩展到更复杂的结构。比如，你可以在我的文档这里查看。

回答于 2025-04-17 由 Python大师

分享举报

如何在Python中记录结构？

6 个回答

撰写回答