Как документировать возвращенный список в Python

Question

У меня есть кусок кода, который очищает веб-страницу расписания колледжа и генерирует список списков списков (списков), например, так:

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

Если бы я хотел документировать этот тип возвращаемых данных на Python (и, возможно, на Java или других языках), было бы лучшим вариантом для этого?

Примечание: я посмотрел на PEP, но не смог найти ничего, связанного с этим

Answer 1

Вы создаете простые классы для хранения ваших данных вместо использования вложенных списков:

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

Затем документ, который ваш метод возвращает список тех. Дополнительным преимуществом является то, что теперь вы можете добавлять дополнительные методы для этих объектов. Добавить __str__ метод для удобного отображения. И т.п.

Более того, вы можете задокументировать эти объекты ввода гораздо яснее, чем документальную структуру примитивных типов.

Answer 2

Такая структура лучше моделируется как словарь; ключом является код комнаты. Каждый ключ кода комнаты содержит список, и этот список содержит кортежи, которые представляют каждый курс / событие.

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

Это облегчает документирование, а также дает вам возможность делать такие вещи, как:

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

Вот как вы могли бы документировать это:

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,..)]}
    '''