How to document a returned list in Python
Domanda
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
Soluzione
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.
Altri suggerimenti
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,..)]}
'''