How to document a returned list in Python

Question

I have a piece of code that scrapes a college timetable webpage and generates a list of lists of lists (of lists) like so:

[[[[start_time, end_time], [module_code, period_type, {period_number}], [room_code]], {next modules...}],{next_days...}]

If I wanted to document this kind of returned data in Python (and possibly Java or other languages) would there be a best practice for doing so?

Note: I've looked at PEP but haven't been able to find anything related to this

Answer 1

You create simple classes to hold your data instead of using nested lists:

 class TimeTableEntry(object):
     def __init__(self, start, end, module, room):
         self.start = start
         self.end = end
         self.module = module
         self.room = room

Then document that your method returns a list of those. The added advantage is that now you can add additional methods on these objects. Add a __str__ method for easy display. Etc.

Most of all, you can document these entry objects far more clearly than you could document a nested structure of primitive types.

Answer 2

This sort of structure is better modeled as a dictionary; with the key being the room code. Each room code key holds a list, and this list has tuples that represent each course/event.

schedule = dict()
schedule['room_1'] = [(start_time,end_time,module_code,period_type,..),
                      (start_time,end_time,module_code,period.....),
                      ...
                     ]
schedule['room_2'] = [ ... ] # as above

This makes it easier to document and also gives you the ability to do things like:

for i in schedule:
   print '{0} events scheduled for room {1}".format(len(schedule[i]),i)

Here is how you could possibly document it:

def foo(bar):
    '''
    Does some magic with `bar`.  Cats may be harmed and
    the space time continuum may be disturbed if you pass in
    silly things like None.

    Args:
        bar: The best name for a variable since foo.

    Returns:
        A dict mapping keys to the room and rows representing
        the room's schedule. A row is represented as a list.
        Each element of the list is a tuple of strings representing
        and event. For example:

        {'room_1': [(start_time,end_time,module_code,period_type,..)]}
    '''