Проект 1: Книги
Опубликовано |
Суббота, 14 апреля |
Конец |
Суббота, 5 мая 23:59 |
Цели
- Стать более уверенными пользователями Python'а.
- Набраться опыта в работе с Flask.
- Научиться использовать SQL, для взаимодействия с базами данных.
Получение Помощи
Если вам понадобится помощь в работе над проектом, можете спокойно воспользоваться следующими ресурсами (их все ещё не так много ;D):
- Группа в телеграмме, ссылку можно получить у TF.
Описание
В данной проекте, вам нужно будет создать сайт с обзорами на различные книги. Пользователи смогут регистрироваться на вашем сайте, а также авторизовываться, используя свои учетные данные (логин и пароль). После авторизации, они должны иметь возможность искать книги, оставлять о них отзывы и видеть отзывы других пользователей.
Вы также воспользуетесь сторонним API, предоставляемый сайтом Goodreads (тоже сайт книжных отзывов), таким образом получая доступ к рейтингам более обширной аудитории, которые вам нужно будет задействовать в своем проекте.
И наконец, пользователи смогут программным путем запрашивать подробную информацию о книгах и об их отзывах, пользуясь вашим веб-сайтовским API.
С чего начать
GitHub Classroom (Виртуальный класс от Гитхаба)
Мы вновь воспользуемся сервисом GitHub Classroom, для раздачи и проверки проектов. Чтобы начать работу с Проектом 1, проделайте следующее:
- Нажав сюда вы перейдете к странице GitHub Classroom, где вы сможете начать выполнение задания.
- Нажмите на зеленую кнопку “Accept this assignment” (Принять задание). Таким образом вы создадите Github'овский репозиторий для вашего проекта. Имейте ввиду, что git'овский репозиторий - это всего лишь место, где будет храниться ваш код и благодаря которому вы сможете отслеживать вносимые вами изменения, которые, несомненно, со временем будут иметь место быть.
- Нажмите на следующую за данным текстом ссылку “Your assignment has been created here” (Ваше задание было создано и находится здесь), которая перенаправит вас на страницу GitHub'овского репозитория, где и будет храниться ваш проект. GitHub'у понадобится всего лишь несколько секунд для того, чтобы закончить создание вашего репозитория.
- В правом верхнем углу страницы репозитория нажмите на кнопку "Fork" (Ответвление/Развилка/Вилка), а затем (если вас попросят) кликните на ваш никнейм. Так вы создадите ответвление (Fork) вашего проектного репозитория, т.е. версию репозитория, которая будет принадлежать именно вашему GitHub аккаунту.
- Теперь вы должны видеть новый заголовок GitHub репозитория, а именно username/project1-username, где username (никнейм) является вашим GitHub'овским никнеймом. Это будет репозиторий, куда вы будете отправлять (push) весь ваш код, в процессе разработки проекта. Работая над проектом, не пытайтесь публиковать (push) вашу работу напрямую в репозитории makeweb50/project1-username: всегда публикуйте (push) свой код в вашем репозитории username/project1-username.
PostgreSQL
Для данного проекта вам понадобится настроить базу данных PostgreSQL, чтобы она работала с нашим приложением. Вы, конечно, можете локально развернуть на вашем компьютере базу данных PostgreSQL, но в данном проекте мы воспользуемся базой, предоставляемой сервисом Heroku (онлайн-хостинга).
- Перейдите на сайт https://www.heroku.com/ и создайте аккаунт, если вы, конечно, ранее не регистрировались.
- В панели управления (Dashboard) Heroku, кликните на “New” (Новый) и выберите “Create new app” (Создать новое приложение).
- Дайте название своему приложению и нажмите на “Create app.”
- Выберите страницу вашего приложение, под названием “Overview” (Обзор), кликните по кнопке “Configure Add-ons” (Настроить дополнения).
- На данной странице найдите раздел “Add-ons”, далее введите в поиске “Heroku Postgres” и выберите его.
- Выберите опцию (plan) “Hobby Dev - Free”, которая даст вам доступ к бесплатной базе данных PostgreSQL, имеющая возможность хранить до 10,000 строк/записей информации. Кликните
“Provision.”
- Теперь кликните по ссылке “Heroku Postgres :: Database”.
- Теперь вы должны быть на странице, дающей общую информацию о вашей базе. Нажмите на “Settings” (Настройки), а потом на “View Credentials” (просмотреть данные учетной записи). Эта вся необходимая информация для того, чтобы вы могли авторизоваться в вашей базе данных. Вы можете получить доступ к базе данных с помощью Adminer, указав адрес сервера (значение “Host” на сайте heroku, страница с данными нашей учетной записи/Credentials), ваше имя пользователя ( “User”), ваш пароль и название базы данных. Вся эта информация может быть найдена на странице сайта Heroku, под названием Credentials.
В качестве альтернативы, вы можете установить
PostgreSQL на свой компьютер, далее получая возможность выполнить в командной строке psql URI
, где URI
- это ссылка, которую мы берем со страницы сайта Heroku, страница с информацией о нашей учетной записи.
Python и Flask
- В первую очередь, убедитесь что у вас установлен Python. На этом курсе мы будем использовать версию Python'а не меньше 3.6.
- Вам также нужно будет установить
pip
. Если вы скачали Python с официального веб-сайта, тогда вполне вероятно, что у вас на компьютере уже имеется pip
(вы можете это проверить, запустив команду pip
в терминальном окне). В противном случае, обязательно проведите установку данного пакета, до того как перейти к следующему шагу!
Для пробного запуска вашего первого Flask-приложения:
- Скачайте (клонируйте/clone) ваш репозиторий username/project1-username с GitHub (примечание: это НЕ ваш makeweb50/project1-username репозиторий).
- Находясь в окне терминала, перейдите в директорию
project1
.
- Запустите команду
pip3 install -r requirements.txt
в вашем терминальном окне, дабы убедиться, что все необходимые Python'овские пакеты (например Flask и SQLAlchemy) были успешно установлены.
- Создайте переменную среды
FLASK_APP
, указав в качестве значения application.py
. На Mac'е или на Linux'е данная команда выглядит следующим образом export FLASK_APP=application.py
. На
Windows'е команда выглядит немного иначе: set FLASK_APP=application.py
. Возможно, вы дополнительно захотите установить переменную среды FLASK_DEBUG
, со значением 1
, которая активирует дебаггер Flask'a и будет автоматически перезагружать ваше веб-приложение, при каждом сохранении вносимого в файл изменения.
- Задайте переменную среды
DATABASE_URL
таким образом, чтобы она указывала на местонахождение/адрес (URI) вашей базы данных, которую вы можете получить со страницы Heroku, раздел Credentials (данные учетной записи).
- Запустите команду
flask run
, дабы запустить ваше Flask-приложение.
- Если вы перейдете по ссылке (URL), предоставленной
flask'ом
, то увидите текст "Project 1: TODO"
!
Goodreads API
Goodreads - это популярный сайт, посвященный книжным отзывам. В данном проекте мы воспользуемся их API, чтобы получить доступ к отзывам каждой отдельной книги.
- Перейдите на https://www.goodreads.com/api и зарегистрируйте Goodreads аккаунт, конечно, если у вас еще нет данной учетной записи.
- Перейдите по ссылке
https://www.goodreads.com/api/keys и подайте заявку на получение ключа API. Поля “Application name” (название приложения) и “Company name” (название компании) можете просто заполнить текстом “project1”, и нет необходимости включать ссылку приложения, callback URL или ссылку поддержки/запасную/дополнительную (support URL).
- Далее вы должны увидеть свой ключ API (В данной проекте, нас интересует только “key” (ключ), не “secret”.)
- Теперь вы можете применить этот ключ API для создания запросов, направленных на Goodreads API. Здесь вся необходимая документация. В частности, Python'овский код, подобным тому, что приведен ниже
import requests
res = requests.get("https://www.goodreads.com/book/review_counts.json", params={"key": "KEY", "isbns": "9781632168146"})
print(res.json())
где KEY
- это ваш ключ API, он даст вам доступ к данным об отзыве и рейтинге определенной, имеющей ISBN номер (международный стандартный книжный номер), книги. Проще говоря, вы увидите что-то схожее со следующим словарем:
{'books': [{
'id': 29207858,
'isbn': '1632168146',
'isbn13': '9781632168146',
'ratings_count': 0,
'reviews_count': 1,
'text_reviews_count': 0,
'work_ratings_count': 26,
'work_reviews_count': 113,
'work_text_reviews_count': 10,
'average_rating': '4.04'
}]
}
Имейте ввиду, что work_ratings_count
(количество_полученных_данной_работой_оценок) - указывает на количество полученных данной книгой рейтингов/оценок, и average_rating
(средний_рейтинг) - это средняя оценка книги, максимальное значение 5.
Требования
Хорошо, теперь пришло время перейти к непосредственному созданию вашего веб-приложения! Вот требования:
- Регистрация: Пользователи должны иметь возможность регистрироваться на вашем сайте, как минимум ваш сайт должен требовать никнейм (username) и пароль (password).
- Авторизация: Зарегистрировавшиеся пользователи должны иметь возможность авторизовываться с помощью своих учетных данных (логина и пароля).
- Деавторизация: Авторизованные пользователи должны иметь возможность деавторизовываться с сайта.
- Импортирование: К данному проекту прилагается файл под названием
books.csv
, который представляет из себя таблицу формата CSV, содержащую данные 5000 различных книг.
У каждой книги есть номер ISBN, название (title), автор (author) и дата публикации (publication date).
В Python'овском файле под названием import.py
, отдельно от вашего веб-приложения, напишите программу, которая будет брать информацию о книгах и заносить ее в базу данных PostgreSQL.
Вам сперва нужно будет решить, какие таблицы(цу) вы будете создавать, какие столбики должны быть у данных таблиц и как они должны взаимодействовать друг с другом. Запустите вашу программу командой python3 import.py
, таким образом вы импортируете данные о книгах в вашу базу. Отправляя проект на проверку, не забудьте включить данную программу в свой код.
- Поиск: Как только пользователь авторизуется, он должен быть перенаправлен на страницу, где он сможет осуществлять поиск интересующей его книги.
У пользователей должна быть возможность вводить книжный ISBN номер, название книги или имя автора книги.
После произведения сайтом операции поиска, он должен отобразить список возможных
результатов или отобразить сообщение, при отсутствии каких-либо результатов.
Если пользователь введет только часть названия книги, неполный номер ISBN или неполное имя автора, ваша страница должна и под них выдать результаты!
- Страница Описания Книги: Когда пользователи нажмут на книгу, предоставленной страницей поиска, они должный быть перенаправлены на страницу книги, с подробной детализацией рассматриваемой работы: ее название, автор, дата публикации, номер ISBN и какие-либо отзывы, оставленные пользователями на вашем сайте.
- Оставление Отзыва Review Submission: Находясь на странице с описанием книги, у пользователя должна быть возможность оставлять отзывы, в которые будет входить оценка по шкале от 1 до 5 баллов, а также текст, где пользователь сможет записывать свое мнение о книге.
Пользователю нельзя публиковать несколько отзывов на одну и ту жу книгу.
- Отзывы Goodreads: На странице книги также должны быть показаны (если есть) средняя оценка и количество оценок, полученных книгой от ресурса Goodreads.
- Доступ к API: Если пользователь пошлет GET-запрос на ваш веб-страничный маршрут
/api/<isbn>
, где <isbn>
является номером ISBN, тогда ваш веб-сайт должен вернуть JSON-объект, содержащий название книги (title), автора (author), дату публикации (year), номер ISBN, количество отзывов (review count) и среднюю оценку (average score). В результате должен получиться JSON-объект следующего формата:
{
"title": "Memory",
"author": "Doug Lloyd",
"year": 2015,
"isbn": "1632168146",
"review_count": 28,
"average_score": 5.0
}
Если запрашиваемого номера ISBN нет в вашей базе данных, то ваш сайт должен вернуть ошибку 404.
- Вы должны использовать только "чистые" (raw) SQL-команды (с помощью метода SQLAlchemy, имеющий название
execute
), в составлении запросов к базе базе данных. В этом проекте вам нельзя прибегать к SQLAlchemy ORM (даже если вам известны способы его применения).
- Файл
README.md
содержит короткое
описание вашего проекта: что содержится в каждом файле и (по желанию) какая-либо еще дополнительная информация, которую нам стоило бы знать при проверке вашего проекта.
- Если вы добавили какие-либо еще дополнительные Python'овские пакеты, без которых ваше приложение не может быть запущено, обязательно добавьте их названия в файл
requirements.txt
!
Помимо этих требований, вы можете добавить в проект свои идеи. Дизайн, вид и общее ощущение от использования сайта могут быть свободно дополнены вашим собственным видением!
Подсказки
- Как минимум, вы скорее всего захотите добавить хотя бы одну таблицу, для отслеживания пользователей, еще одну для книг и последнюю для отзывов. Но вам необязательно ограничивать себя только этими тремя таблицами, если вы считаете, что еще несколько не помешали бы!
- Говоря об авторизации, напомним вам, что вы можете хранить информацию внутри
session
(сессии), которая может хранить разные значения для разных пользователей.
В частности, если у каждого пользователя есть id
, тогда вы можете сохранить этот id
в
session (т.е. в session["user_id"]
), для понимания того, который именно пользователь на данных момент находится в системе (авторизован).
Вопросы
Касаемо API, нужно ли располагать ключи JSON в определенном порядке (сортировано)?
Можете располагать в любом порядке!
AttributeError: 'NoneType' object has no attribute '_instantiate_plugins'
Удостоверьтесь, что перед тем как запустить flask run
, вы установили переменную среды DATABASE_URL
!
Как отправить
- Перейдите на страницу GitHub'а, где находится ваш репозиторий username/project1-username (примечание: не перепутайте с репозиторием makeweb50/project1-username).
- На правой стороне экрана кликните по кнопке "Pull request" ("Принятие изменений").
- Обязательно удостоверьтесь, что “base fork” (основной fork) - это
makeweb50/project1-username
и “head fork” (головной fork) - это username/project1-username
.
- Кликните по “Create pull request”.
- На следующей странице вам опять придется нажать на кнопку “Create pull request”.
Поздравляем! Вы завершили Проект 1.