Разберём урок по гитлабу. В папке git есть два файла git_class.py и main_git.py. Сначала поговорим про первый.
¶ git_class
В этом файле находятся функции для взаимодействия приложения и гитлаба. Посмотрим, для что они делают:
| Функция | Аргументы | Описание |
|---|---|---|
| search_user_id(mail) | Почта пользователя | Возвращает id пользователя по его электронному адресу, если пользователь зарегистрирован на гитлабе, или None, если пользователь не найден |
| create_new_group(mail) | Почта пользователя | Возвращает id созданной группы. Почта нужна для персонализации описания группы |
| create_new_project(mail, group_id) | Почта и id группы | Возвращает id проекта, созданного в указанной группе |
| add_user_to_group(user_id, group_id) | id пользователя и id группы | Добавляет пользователя с user_id в группу с group_id. Возвращает id группы |
| add_hooks_to_project(project_id) | id проекта | Добавляет вебхук к указанному проекту. Хук срабатывает при push или merge-request событиях. Ссылка, по которой будет работать вебхук, заранее указывается |
| delete_environment(group_id, project_id) | id группы и id проекта | Удаляет указанные проект и группу |
Эти функции находятся в классе GitClass, импортировать их можно так: from Git.git_class import GitClass.
Кроме этих функций в классе GitClass в файле вы найдёте функции
send_smart_messageиsend_smart_comments. Эти функции облегчают работу с таблицей и сообщениями одновременно, мне удобно ими пользоваться. Если вы захотите использовать их в своём уроке, то вам придётся сделать таблицу по такому же правилу, что и таблица для гитлаба. Подробнее об этом я расскажу ниже.
¶ main_git
Это основной файл урока. В нём находится блюпринт и четыре функции.
¶ start_git
Эта функция начинает урок. Она вызывается при переходе пользователя по пригласительной ссылке или после рестарта урока (про это читайте здесь).
Функция start_git
Эта функция принимает в качестве аргумента почту пользователя. При вызове функция загружает из гугл-таблицы все значения (строка 21) и отправляет приветствие пользователю в чат.
Далее мы запрашиваем у гитлаба user_id. Если такого пользователя на гитлабе ещё нет, то на этом урок прекращаем и просим пользователя авторизоваться на гитлабе. Иначе пытаемся удаляем прошлое окружение и пользователя из базы данных (функция delete_env_and_user); это нужно, если прошлый урок завершился некорректно или если происходит рестарт.
Теперь мы создаём нового пользователя в таблицах User и GitUser (строки 35-40).
Переходим к созданию среды. Создаём группу, создаём проект, добавляем вебхуки в проект и пользователя в группу.
Записываем полученные id в поля group_id и project_id таблицы GitUser в базе данных. В поле marks_list записываем список оценок в виде строки, в поле comment_list записываем список комментариев (-1 в данном случае означает, что пользователь не начал делать тот или иной шаг).
После этого мы посылаем пользователю следующую порцию сообщений — step_0. На этом запуск урока завершён, пользователь начинает делать задание.
¶ score_user
Следующая функция, которую мы рассмотрим, занимается вычислением оценки и отправкой комментариев. На вход она получает почту пользователя (вы, наверное, уже заметили, что большинство операций используют почту как первичный ключ), а данные об оценках и комментариях получает из базы данных.
Функция score_user
Что мы делаем внутри функции? Сначала мы ищём в базе данных пользователя с указанным электронным адресом, преобразуем строки с оценками и комментариями в формат листа. Если какая-то оценка оказалась меньше нуля, то она должна быть ноль. Дальше считаем суммарную оценку, помещаем её в начало массива. Далее посылаем пользователю сообщение об оценках, сообщение о комментариях и финальное сообщение. Возвращаем суммарную оценку (для выставления в классрум).
¶ delete_env_and_user
Эта функция удаляет созданные для урока группу, проект, а также записи из базы данных. Аргумент — почта.
Функция delete_env_and_user
Сначала мы находим в таблице User пользователя с указанной почтой. Если пользователь нашёлся, ищём информацию о нём в таблице GitUser. Узнав номер номер группы и номер проекта, удаляем их (функция GitClass.delete_environment). Удаляем запись из таблицы GitUser, затем из таблицы User.
¶ end_git
Эта функция по очереди запускает функции score_user, send_score, delete_env_and_user.
¶ githook (blueprint)
Это часть файла отвечает за обработку входящих вебхуков от гитлаба, оценивание действий и выбор подходящего комментария.
Функция githook
Функция запускается, как только GitLab посылает вебхук по адресу /git/hook. Вместе с запросом мы получаем тело вебхука в формате json. Подробнее о вебхуках гитлаба читайте в документации гитлаба. Далее мы по project_id из вебхука находим пользователя в таблице GitUser и узнаём почту, оценки, комментарии и номер шага, на котором сейчас находится пользователь.
Если присланный хук описывает push событие, то для удобства собираем данные обо всех добавленных, изменённых или удалённых файлах из всех коммитов в три листа.
Теперь мы готовы проверять, является ли присланный хук правильным с точки зрения текущего шага. Для этого мы переходим в одно из ветвлений и начинаем проверять определённые поля в вебхуке с эталонными значениями. Начинаем проверку с самого слабого критерия — если хук ему соответствует, то текущий шаг считается выполненным (пока на 0 баллов). Далее происходит следующая проверка по более строгому условию. Если и эта проверка пройдена, то повышаем оценку. Параллельно мы можем установить, в чём ошибка пользователя, и задать id комментария, ей соответвующего. В итоге записываем новое значение шага, оценки и комментария в соответствующий список и обновляем базу данных.
Если пользователь перешёл на следующий шаг, то посылаем ему следующую порцию задания.
¶ Почему такая гугл-таблица?
Теперь подробнее о функциях send_smart_message и send_comment_message. Эти функции в качестве обязательных аргументов получают лист таблицы (результат работы get_values), почту пользователя и некоторое кодовое слово, например, "step_0". Что с эти делает send_smart_message? Посмотрим на лист git в гугл-таблице. В столбцах A и D расположены кодовые слова (в том числе и "step_0"). Столбец A используется первой функцией, а D — второй. При получении кодового слова функция начинает поиск по столбцу с кодовыми словми, пока не встретит совпадение. Если указанное кодовое слово нашлось, то функция смещается на столбец вправо и начинает посылать всё, что находится в этой ячейке и ниже до тех пор, пока не встретит ячейку со словом "STOP". После этого посылание сообщений прекращается. Функция send_comment_message посылает только одну ячейку, которая справа от нужного кодового слова.
Преимущества такого решения в том, что вы можете передвигать ячейки в таблице, добавлять новые или удалять старые — и приложение продолжит работать.
Разберёмся с отправкой оценок. Для этого используется форматирование строк. В таблице указываем, какую переменную подставлять в данный пропуск, а в функцию send_smart_message передаём эту переменную в качестве аргумента. Например, для отправки оценок вы должны передать в качестве аргумента marks словарь с числами, где первый элемент — суммарная оценка. Функция подставит на место пропусков те оценки, которые вы ей передали.
send_comment_message в качестве аргумента принимает словарь с номерами комментариев. В нашем случае это четыре числа, -1 означает, что пользователь не добрался до данного шага, 0 — ошибок (и комментариев) нет. Если на какой-то позиции стоит число, отличное от 0, функция отправит соответствующий комментарий и подпишет, к какому шагу он относится.
Следите, чтобы не было пустых строк в таблице.
¶ Ссылка-приглашение
https://301.miem.vmnet.top/invite?state=git@pm21project