【问题标题】:What's the standard way to document a namedtuple?记录命名元组的标准方法是什么?
【发布时间】:2016-08-23 23:22:09
【问题描述】:

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

之前:

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),我非常喜欢它,因为它可以更轻松地跟踪传入的类型。

我的问题是,在这种情况下,您将如何记录命名元组?显然,正如当前设置的那样,您没有关于命名元组中类型的信息。是否有一种可接受的方式来在这里扩展文档字符串,或者在它定义的地方记录命名元组(未显示)?

我知道你可以在这个庄园中记录一个类,但我试图远离使用一个类,因为除了保存变量之外我没有任何目的。

【问题讨论】:

  • 为什么是命名元组?为什么不直接使用 {ident:session} 的(任意)字典,甚至只是一个会话列表......你是否真的在验证它是一个传入的命名元组(根据我的经验,命名元组作为返回值比方法参数)
  • 没有特别的原因。我考虑了两者并任意选择了 namedtuple - 它似乎更“轻量级”,并且通常我在值都是相同类型时使用字典(我知道你可以混合类型)。无论如何,我认为两者的问题是相同的 - 从更一般的意义上说,当您将其中任何一个传递给一个函数并且它们包含混合类型时,记录它的最佳方法是什么?也许最好只使用一个类(在类文档中记录类型),或者不要担心它并回溯到初始化命名元组/字典的位置。

标签: python code-documentation


【解决方案1】:

namedtuple 的 Python3 文档显示,可以通过将您自己的字符串附加到 __doc__ 字段来自定义命名元组的文档字符串。对于你的问题,你可以写:

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 的自动文档文本数量可能使您难以找到您添加的特定文档。

【讨论】:

  • 我在尝试这个时遇到了这个错误:AttributeError: attribute '__doc__' of 'type' objects is not writable。我在 python 2.7 中。
  • @BenCaine 这在 2.7 中是预期的,部分解决方法是将命名元组子类化。有关简单示例,请参阅此答案stackoverflow.com/a/28568351/3527268文档中的示例部分。
【解决方案2】:

我不熟悉谷歌风格指南,但是这个怎么样:

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

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.
    """    

另一方面,如果我使用命名元组的属性,那么可能是这样的

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.
    """   

在每种情况下,只要求功能正常工作所需的最低功能

【讨论】:

    猜你喜欢
    • 2020-12-17
    • 2015-11-03
    • 2011-01-15
    • 1970-01-01
    • 1970-01-01
    • 1970-01-01
    • 2020-09-19
    • 2013-02-08
    • 2012-08-23
    相关资源
    最近更新 更多