What's the standard way to document a namedtuple?

Question

Looking to clean up some code by using a namedtuple to hold multiple variables for passing through a number of functions. Below is a simplified example (I actually have a few more additional arguments).

Before:

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

After:

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

For docstrings, I've been following the Google style guide, with the addition of types (inspired by this post), which I really like because it makes it a lot easier to keep track of what types are coming in.

My question is, how would you go about documenting a namedtuple in this scenario? Obviously as it's currently set up, you have no information about the types within the namedtuple. Is there an accepted way to extend the docstring here, or document the namedtuple where it's defined (not shown)?

I know you could document a class in this manor, but I'm trying to stay away from using a class as I don't really have any purpose for it other than to hold the variables.

Answer 1

The Python3 documentation for namedtuple shows that a namedtuple's docstrings can be customized by appending your own strings to the __doc__ fields. For your question, you could write:

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

Then executing help(Sessions) outputs:

Help on class Sessions in module MyModule:

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

and then after few other rows of documentation comes:

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

Admittedly the amount of automatically documentation text for Sessions can make it difficult to find specific documentation you added.

Answer 2

I am not familiar with Google style guide, but how about this:

for a namedtuple or tuple or list or whatever that is interchangeable I would go for something like this

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

on the other hand if I use the attributes of the namedtuple, then maybe something like this

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

for a dictionary, how about this

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

or

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

In each instance just ask for the minimum functionality that the function need to work correctly