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.