aplakhov / notq

This is the source code of notq. You can read more about notq here (in Russian). TLDR is that it's a web community not dissimilar to Hackernews, if not that popular (yet?)

As most of its members are native Russian speakers, details follow in Russian.

Перед вами исходный код notq. Вы можете почитать больше о том, что это за сервис, здесь.

Используемые технологии

notq - очень простой сервис, написанный с минимальным использованием фреймворков и других дополнительных зависимостей. Код основан на Flask, в качестве базы данных используется Postgres, а html и js сейчас написаны вручную и очень просты. Свойство минимальности кода и зависимостей хочется поддерживать и впредь.

Организация кода

• notq - основной код "бекенда"
• notq/static - статика, включая js-код UI и css
• notq/templates - шаблоны HTML
• tests - тесты (pytest-style)

Как развернуть у себя и протестировать изменения

Здесь приведен самый быстрый способ, хотя и не самый чистый. Считается более правильным работать в виртуальном окружении (venv), но если вы знаете, что это и зачем вам это нужно, вы знаете и то, как это делается.

1. Клонируйте репозиторий на свою машинку, запустив git clone https://github.com/aplakhov/notq.git

2. Установите зависимости, запустив pip install -e . (если вы не python-разработчик, то у вас, возможно, не установлен pip; установите его, например, так sudo apt install python3-pip)

3. Инициализируйте базу данных: flask --app notq init-db-drops-all-extremely-unsafe

4. Запустите сервис: flask --app notq run --host 0.0.0.0 --port 5013 --debug

В этот момент по в браузере по адресу http://localhost:5013 (или http://<внешний_ip_вашей_машинки>:5013) вы должны увидеть пустую, но работающую нотку, в которой можно зарегистрироваться, создавать посты и т.п.

Flask - очень приятная технология: вы можете оставить процесс в этом состоянии, и с флагом --debug он будет переподхватывать изменившиеся html-шаблоны и python-файлы, вам останется только обновлять страницу в браузере

Раз вы собираетесь что-то поменять, скорее всего, вам захочется убедиться, что вы ничего не сломали

5. pip install -U pytest

6. pytest

Про различные БД

Как вы могли заметить, в инструкции выше ничего не говорится о базе данных. Для тестов и отладки в локальном режиме используется sqlite - небольшая SQL-совместимая БД, хранящая все данные в локальном бинарном файлике instance/notq.sqlite. Это удобно, т.к. позволяет уложить начало работы в минимальное количество шагов.

Продакшн-версия работает на "настоящей" БД postgres, развернутой отдельно. Библиотека SQLAlchemy, используемая для абстрагирования от конкретной используемой БД (как в notq, так и во многих других проектах), к сожалению, не полностью стирает отличия между диалектами SQL и особенностями реализации. Многие запросы могут работать в sqlite и не работать в postgres и наоборот. Поэтому, если вы меняете запросы к БД или добавляете новые, вам понадобится:

• поднять пустую базу данных postgres
• создать файлики instance/config.py и instance/config_testing.py
• в каждом из них написать следующую строчку: DATABASE='postgresql+psycopg2://{user}:{password}@{host}:{port}/{dbname}'
• прогнать тесты (pytest) в этом варианте
• инициализировать "настоящую" БД, запустив flask --app notq init-db-drops-all-extremely-unsafe
• протестировать вручную, запустив flask --app notq run --host 0.0.0.0 --port <port> --debug