Проект "Yamdb"

В этом спринте вам предстоит написать REST API для сервиса YaMDb — базы отзывов о фильмах, книгах и музыке.
Этот проект вы будете делать в команде со своими однокурсниками, синхронизируясь через Git. Именно так ведётся разработка проектов в больших компаниях. В не очень больших — тоже. У вас будет не очень большая компания.
Ваша команда разработчиков состоит из трёх программистов, проект вы будете делать и сдавать из общего репозитория.
Один из вашей команды склонирует репозиторий api_yamdb (он доступен вам на Гитхабе), и в качестве коллабораторов (соразработчиков) подключит остальных участников команды. Соразработчики склонируют этот репозиторий себе, и каждый из команды займётся своей частью проекта, работая в собственной ветке Git.
Отправлять проект на проверку будет участник команды, создавший репозиторий. После выполнения задания славу разделят все разработчики из вашей команды.
Если ваш лид отправил проект на проверку, и проект был принят — остальным участникам команды надо скопировать проект и отправить архив ревьюерам со своего аккаунта. Выполнение будет засчитано автоматом.

Работа с Git в команде

Ветки (англ. "branches")

Ветка — это изолированный поток разработки, в котором можно делать коммиты так, что их не видно из других веток и они не влияют на основной код проекта. Если проект пишут несколько человек, каждый может работать в отдельной ветке и не мешать другим.
Прежде чем начать писать новую часть проекта, для неё создают отдельную ветку. Когда работа доделана, эту побочную ветку после ревью «вливают» в главную. Таким образом в главной ветке всегда будет стабильная версия проекта.
Основная ветка разработки называется master. Обычно в ней хранят финальную версию кода. Ветка master создаётся автоматически, когда в проекте инициализируется Git и создаётся первый коммит.
Чтобы увидеть все ветки и узнать, на какой ветке вы находитесь сейчас, введите команду git branch:
Скопировать кодBASH
git branch # команда для просмотра веток
* master # основная ветка проекта, звёздочкой отмечено, что вы в ней
Нажмите Q, чтобы покинуть режим просмотра веток.
Создать новую ветку можно командой git branch название_ветки. Название ветки лучше выбирать исходя из того, что в ней будет происходить. Имя ветки не должно содержать пробелов: это вызовет ошибку.
Скопировать кодBASH
git branch develop # создали новую ветку с именем develop
git branch # проверили, в какой ветке находимся
develop # появилась новая ветка
* master # но мы пока находимся в ветке master
Ветку создали, но пока мы находимся в ветке master. Чтобы переключиться в ветку develop, введите команду git checkout develop:
Скопировать кодBASH
git checkout develop # переключились в ветку develop
git branch # проверили
* develop
master
Можно создать ветку и сразу переключиться на неё командой:
Скопировать кодBASH
git checkout -b develop # создали и сразу переключились в ветку develop
Есть разные подходы к именованию веток, каждая команда разработки выбирает свой. При любом подходе ветки называют так, чтобы всем было понятно, что в них происходит.
Если ветка создана для разработки новой части проекта, её имя может начинаться со слова feature:
Скопировать кодBASH
git checkout -b feature/email-validation
Если в ветке планируется ловля и исправление багов, ей подойдёт название, начинающееся с bugfix:
Скопировать кодBASH
git checkout -b bugfix/resize-image

Слияние веток (англ. "merge")

После решения задачи вашу изолированную ветку нужно объединить с веткой master, залить в неё результаты вашей работы. Этот процесс называется «слияние веток», или merge.
Чтобы объединить («смёрджить») ветки, нужно переключиться в ветку, куда должны попасть изменения и из неё выполнить команду на слияние.
Чтобы залить код из ветки develop в ветку master, сперва переключаемся
Скопировать кодBASH
git checkout master # переключились в master
Теперь нужно переместить все коммиты из develop в ветку master, смёржить ветки:
Скопировать кодBASH
git merge develop
Если всё прошло хорошо, Git сообщит, сколько строк кода изменилось и в каких файлах. Но иногда при слиянии веток могут возникнуть «конфликты»: например, два разработчика в разных ветках изменили код в одной и той же строке, и после слияния Git не может решить, какой код оставить в финальной версии.
Git сообщает о конфликтах:
Скопировать кодBASH
git merge develop
# сливаем ветку develop в master

CONFLICT (content): Merge conflict in [название вашего файла]
Automatic merge failed; fix conflicts and then commit the result.
В коде файлов с конфликтами Git даёт подсказки на тех строках, где в разных ветках текст отличается. Например:
Скопировать кодBASH
<<<<<<< HEAD
one two three four five
=======
1 2 3 4 5
>>>>>>> develop
В этом файле произошёл конфликт — в ветке master (на неё указывает заголовок HEAD) строка состоит из слов, а в ветке develop из цифр. Git не понимает, какой из вариантов оставить. Если правильный вариант — это строка чисел, нужно удалить всё лишнее:
Скопировать кодBASH
1 2 3 4 5
Эту процедуру повторяют для всех конфликтующих файлов. После этого делается коммит, чтобы зафиксировать изменения — и ещё раз мёрж. Теперь слияние веток должно получиться!
Когда работа с веткой закончена и она больше не нужна, её можно удалить: git branch -d имя ветки (флаг d — от англ. delete, «удалить»):
Скопировать кодBASH
git branch -d develop
# удалили ветку develop
Чаще выполняйте команду git pull, чтобы иметь актуальное состояние репозитория.

Основные команды для работы с ветками:

git branch <название_ветки> — создать новую ветку.
git checkout <название_ветки> — переключиться в ветку.
git checkout -b <название_ветки> — создать ветку и сразу переключиться в неё.
git branch -d <название_ветки> — удалить ветку. Чтобы всё прошло хорошо, нужно переключиться из удаляемой ветки.
git merge <название_ветки> — скопировать все изменения из ветки в ветку. Чтобы перенести изменения из ветки develop в ветку master, нужно находиться в ветке master и выполнить команду git merge develop

Проект YaMDb

Проект YaMDb собирает отзывы (Review) пользователей на произведения (Title). Произведения делятся на категории: «Книги», «Фильмы», «Музыка». Список категорий (Category) может быть расширен (например, можно добавить категорию «Изобразительное искусство» или «Ювелирка»).
Сами произведения в YaMDb не хранятся, здесь нельзя посмотреть фильм или послушать музыку.
В каждой категории есть произведения: книги, фильмы или музыка. Например, в категории «Книги» могут быть произведения «Винни Пух и все-все-все» и «Марсианские хроники», а в категории «Музыка» — песня «Давеча» группы «Насекомые» и вторая сюита Баха. Произведению может быть присвоен жанр из списка предустановленных (например, «Сказка», «Рок» или «Артхаус»). Новые жанры может создавать только администратор.
Благодарные или возмущённые читатели оставляют к произведениям текстовые отзывы (Review) и выставляют произведению рейтинг (оценку в диапазоне от одного до десяти). Из множества оценок автоматически высчитывается средняя оценка произведения.

Техническое описание проекта YaMDb

Вам доступен репозиторий api_yamdb, в нём сохранён пустой Django-проект. К проекту по адресу /redoc подключена документация API YaMDb. В ней описаны шаблоны запросов к API и структура ожидаемых ответов. Для каждого запроса указаны уровни прав доступа: пользовательские роли, которым разрешён запрос.
Ваша задача — написать проект и API так, чтобы они полностью соответствовали документации.

Пользовательские роли

  • Аноним — может просматривать описания произведений, читать отзывы и комментарии.
  • Аутентифицированный пользователь (user)— может читать всё, как и Аноним, дополнительно может публиковать отзывы и ставить рейтинг произведениям (фильмам/книгам/песенкам), может комментировать чужие отзывы и ставить им оценки; может редактировать и удалять свои отзывы и комментарии.
  • Модератор (moderator) — те же права, что и у Аутентифицированного пользователя плюс право удалять любые отзывы и комментарии.
  • Администратор (admin) — полные права на управление проектом и всем его содержимым. Может создавать и удалять произведения, категории и жанры. Может назначать роли пользователям.
  • Администратор Django — те же права, что и у роли Администратор.

Алгоритм регистрации пользователей

  1. Пользователь отправляет POST-запрос с параметром email на /api/v1/auth/email/.
  2. YaMDB отправляет письмо с кодом подтверждения (confirmation_code) на адрес email .
  3. Пользователь отправляет POST-запрос с параметрами email и confirmation_code на /api/v1/auth/token/, в ответе на запрос ему приходит token (JWT-токен).
Эти операции выполняются один раз, при регистрации пользователя. В результате пользователь получает токен и может работать с API, отправляя этот токен с каждым запросом.
После регистрации и получения токена пользователь может отправить PATCH-запрос на /api/v1/users/me/ и заполнить поля в своём профайле (описание полей — в документации).
Если пользователя создаёт администратор (например, через POST-запрос api/v1/users/...) — письмо с кодом отправлять не нужно.
Автоматические тесты платформы не будут проверять отправку писем.

Ресурсы API YaMDb

  • Ресурс AUTH: аутентификация.
  • Ресурс USERS: пользователи.
  • Ресурс TITLES: произведения, к которым пишут отзывы (определённый фильм, книга или песенка).
  • Ресурс CATEGORIES: категории (типы) произведений («Фильмы», «Книги», «Музыка»).
  • Ресурс GENRES: жанры произведений. Одно произведение может быть привязано к нескольким жанрам.
  • Ресурс REVIEWS: отзывы на произведения. Отзыв привязан к определённому произведению.
  • Ресурс COMMENTS: комментарии к отзывам. Комментарий привязан к определённому отзыву.
Каждый ресурс описан в документации: указаны эндпойнты (адреса, по которым можно сделать запрос), разрешённые типы запросов, права доступа и дополнительные параметры, если это необходимо.

Связанные данные и каскадное удаление

При удалении объекта пользователя User должны удаляться все отзывы и комментарии этого пользователя (вместе с оценками-рейтингами).
При удалении объекта произведения Title должны удаляться все отзывы к этому произведению и комментарии к ним.
При удалении объекта категории Category не удалять связанные с этой категорией произведения (Title).
При удалении объекта жанра Genre не удалять связанные с этим жанром произведения (Title).
При удалении объекта отзыва Review должны быть удалены все комментарии к этому отзыву.

База данных

В репозитории с заданием в директории /data подготовлены несколько файлов .csv с контентом для Users, Titles, Categories, Genres, Review и Comments. Тестировать пустой проект будет неудобно, а наполнять его руками — долго.
После того, как вы подготовите модели — заполните базу данных контентом из приложенных .csv. Делать это не обязательно, однако заполнение базы готовыми данными упростит и ускорит работу: для проверки кода вам всё равно понадобятся тестовый контент.
«Закинь данные из CSV в БД» — достаточно распространённая задача, такой опыт обязательно пригодится вам в дальнейшей работе. И ещё очень повезёт, если с данными всё будет в порядке: например, в таблице могут быть пропущены какие-то обязательные значения; эти данные менеджер у себя в эксельке набивал, откуда ему знать.
Залить в базу данные из файлов .csv можно несколькими способами:
  • импортировать данные средствами SQLite, нужную команду ищите здесь;
  • написать скрипт, применив библиотеку csv;
  • подключить специальную библиотеку для импорта.
Выбирайте любой способ.

Распределение задач в команде

Мы предлагаем распределить работу между участниками таким образом:
Первый разработчик пишет всю часть, касающуюся управления пользователями (Auth и Users): систему регистрации и аутентификации, права доступа, работу с токеном, систему подтверждения e-mail, поля.
Второй разработчик пишет категории (Categories), жанры (Genres) и произведения (Titles): модели, view и эндпойнты для них.
Третий разработчик занимается отзывами (Review) и комментариями (Comments): описывает модели и view, настраивает эндпойнты, определяет права доступа для запросов. Рейтинги произведений тоже достаются третьему разработчику.
Это только наши рекомендации, вы можете распределить работу как-то иначе.