记录命名元组的标准方法是什么？

Question

希望通过使用命名元组来保存多个变量以通过多个函数来清理一些代码。下面是一个简化的例子（实际上我还有一些额外的参数）。

之前：

def my_function(session_cass, session_solr, session_mysql, some_var, another):
"""Blah blah.

Args:
    session_cass (Session): Cassandra session to execute queries with.
    session_solr (SolrConnection): Solr connection to execute requests with.
    session_mysql (connection): MySQL connection to execute queries with.
    some_var (str): Yada yada.
    another (int): Yada yada.
"""

之后：

def my_function(sessions, some_var, another):
"""Blah blah.

Args:
    sessions (namedtuple): Holds all the database sessions.
    some_var (str): Yada yada.
    another (int): Yada yada.
"""

对于文档字符串，我一直遵循 Google 风格指南，并添加了类型（受 this post 启发），我非常喜欢它，因为它更容易保留跟踪哪些类型正在进入。

我的问题是，在这种情况下，您将如何记录命名元组？显然，由于它当前的设置，您没有关于 namedtuple 中类型的信息。是否有一种可接受的方法来扩展此处的文档字符串，或在其定义的地方记录命名元组（未显示）？

我知道您可以在这个庄园中记录 class，但我尽量避免使用 class，因为除了保持变量。

Answer 1

我不熟悉 Google 风格指南，但是这个怎么样：

对于命名元组、元组或列表或任何可互换的东西，我会选择这样的东西

def my_function(sessions, some_var, another):
    """Blah blah.

    Args:
        sessions (sequence): A sequence of length n that 
                             holds all the database sessions.
                             In position 0 need bla bla
                             In position 1 need ble ble
                             ...
                             In position n-1 need blu blu
        some_var (str): Yada yada.
        another (int): Yada yada.
    """

另一方面，如果我使用 namedtuple 的属性，那么可能是这样的

def my_function(sessions, some_var, another):
    """Blah blah.

    Args:
        sessions (object): A object that holds all the database sessions.
                           It need the following attributes 
                           bla_bla is ...
                           ble_ble is ...
                             ...
                           blu_blu is ...
        some_var (str): Yada yada.
        another (int): Yada yada.
    """

要字典，这个怎么样

def my_function(sessions, some_var, another):
    """Blah blah.

    Args:
        sessions (map): A dictionary-like object that holds all the 
                        database sessions, it need the following keys
                        bla_bla is ...
                        ble_ble is ...
                           ...
                        blu_blu is ...
        some_var (str): Yada yada.
        another (int): Yada yada.
    """

或

def my_function(sessions, some_var, another):
    """Blah blah.

    Args:
        sessions (customclass): Holds all the database sessions.
        some_var (str): Yada yada.
        another (int): Yada yada.
    """

在每个实例中，只需询问函数正常工作所需的最少功能

Answer 2

namedtuple 的 Python3 文档表明，可以通过将您自己的字符串附加到 __doc__ 字段来自定义 namedtuple 的文档字符串。对于你的问题，你可以这样写：

Sessions = namedtuple('Sessions', ['cass', 'solr', 'mysql'])
Sessions.__doc__ += ': All database sessions.'
Sessions.cass.__doc__ += ': Cassandra session to execute queries with.'
Sessions.solr.__doc__ += ': Solr connection to execute requests with.'
Sessions.mysql.__doc__ += ': MySQL connection to execute requests with.'

然后执行help(Sessions)输出：

Help on class Sessions in module MyModule:

class Sessions(builtins.tuple)
|  Sessions(cass, solr, mysql): All database sessions.
|  
|  Method resolution order:
|      Sessions

然后在其他几行文档之后：

|----------------------------------------------------------------------
|  Data descriptors defined here:
|  
|  cass
|      Alias for field number 0: Cassandra session to execute queries with.
|  
|  solr
|      Alias for field number 1: Solr connection to execute requests with.
|  
|  mysql
|      Alias for field number 2: MySQL connection to execute requests with.
|  
|  ----------------------------------------------------------------------

诚然，Sessions 的自动文档文本数量可能会导致很难找到您添加的特定文档。

记录命名元组的标准方法是什么？

What's the standard way to document a namedtuple?

python

code-documentation