Merge updates from the upstream repo into devel branch (#188)

Author: shorodilov

OOP_task.md

@@ -0,0 +1,221 @@
+# Модульное задание по OOP
+
+Создаем консольную игру камень-ножницы-бумага
+
+## Общее описание
+
+Нам нужно создать консольную игру в которой игрок будет выбирать свой ход из 3 вариантов (камень, ножницы, бумага) путем
+ввода в консоль одной из 3 цифр 1, 2 или 3.
+Вымышленный соперник, будет выбирать свой вариант случайно из таких же трех вариантов.
+
+Игра идет до тех пор, пока у игрока есть `жизни`, если атака успешна, или соперник умер, должны быть начислены очки в
+зависимости от выбранного уровня сложности. Если игрок умер, очки должны быть записаны в файл с результатами.
+
+## Необходимые файлы и папки
+
+- `main.py` - основной скрипт, отвечает за меню и за запуск игры
+- Папка `game` - со всеми основными файлами игры
+  Все остальные файлы должны быть в этой папке
+- `models.py` - файл с описанием моделей которые есть в игре (игрок и соперник)
+- `settings.py` - файл со всеми константами которые могут нам понадобиться
+- `exceptions.py` - файл с необходимыми нам исключениями
+- `game.py` - файл с основной логикой игры
+- `score.py` - файл с логикой сохранения очков игры
+
+## Разберем каждый файл
+
+### models.py
+
+Должен содержать два класса
+
+- `Player`
+- `Enemy`
+
+#### Player
+
+Аттрибуты:
+
+- `name` - Имя игрока, задается пользователем через консоль
+- `lives` - Количество жизней, берется из константы из `settings.py`
+- `score` - Очки игрока, изначально 0
+
+Методы:
+
+- `__init__` - для инициализации игрока, принимает только имя, назначает имя, кол-во жизней и очков.
+- `select_attack` - метод для ввода атаки игроком. Вводим до тех пор, пока пользователь не введет валидное значение (1, 2,
+  3), использует константы из файла `settings.py`
+- `decrease_lives` - метод, который будет вызываться если игрок проиграл "бой", уменьшает жизни на 1. Если жизни
+  закончились, вызывает исключение `GameOver` из файла `exceptions.py`
+- `add_score` - метод для начисления очков игроку.
+
+#### Enemy
+
+Аттрибуты:
+
+- `lives` - Кол-во жизней, изначально зависит от уровня соперника и уровня сложности, уменьшается на 1 когда соперник
+  проигрывает "бой"
+- `level` - уровень соперника, будет увеличиваться с каждым новым соперником. Изначально 1.
+
+Методы:
+
+- `__init__` - для инициализации соперника, принимает только уровень и сложность, что бы вычислить кол-во жизней,
+  назначает кол-во жизней и уровень.
+- `select_attack` - метод для случайного выбора атаки (1, 2, 3), использует константы из файла `settings.py`
+- `decrease_lives` - уменьшает жизни при проигрыше "боя", вызывает исключение `EnemyDown` из файла `exceptions.py` если у
+  соперника закончились жизни
+
+### game.py
+
+Содержит класс игры `Game`
+
+### Game
+
+Аттрибуты:
+
+- `player` - объект игрока
+- `enemy` - объект соперника, при убийстве будет создан новый, с более высоким уровнем
+- `mode` - уровень сложности, normal или hard, содержит либо 1, либо 2, которые определены константами
+
+Методы:
+
+- `__init__` - принимает объект игрока и уровень сложности, создает первого соперника
+- `create_enemy` - метод для создания нового соперника
+- `play` - метод запуска игры. Запускает бесконечный цикл в одной итерации которого происходит "бой". Для этого вызывает
+  два метода, `fight` и `handle_fight_result`. Отслеживает не произошло ли одно из исключений при вызове второго
+  метода `GameOver` или `EnemyDown`, при первом завершает игру и вызывает метод для записи очков, при втором создает
+  нового, более сильного соперника.
+- `fight` - метод запрашивает у пользователя и соперника атаки, из констант получает результат боя (-1, 0, 1)
+- `handle_fight_result` - принимает результат боя, и в зависимости от результата отнимает жизни либо у игрока, либо у
+  соперника.
+- `save_score` - вызывает сохранение очков при помощи вызова класса из файла `score.py`
+
+### exceptions.py
+
+Классы
+
+- `GameOver` - когда у игрока заканчиваются жизни
+- `EnemyDown` - когда у соперника заканчиваются жизни
+
+### settings.py
+
+Содержит все константы
+
+Примерное содержание:
+
+```python
+MODE_NORMAL = 'Normal'
+MODE_HARD = 'Hard'
+MODES = {'1': MODE_NORMAL,
+         '2': MODE_HARD}
+
+PLAYER_LIVES = 2
+POINTS_FOR_FIGHT = 1
+POINTS_FOR_KILLING = 5
+MAX_RECORDS_NUMBER = 5
+HARD_MODE_MULTIPLIER = 2
+
+SCORE_FILE = 'scores.txt'
+
+PAPER = 'Paper'
+STONE = 'Stone'
+SCISSORS = 'Scissors'
+
+WIN = 1
+DRAW = 0
+LOSE = -1
+
+ALLOWED_ATTACKS = {
+    '1': PAPER,
+    '2': STONE,
+    '3': SCISSORS
+}
+
+ATTACK_PAIRS_OUTCOME = {
+    (PAPER, PAPER): DRAW,
+    (PAPER, STONE): WIN,
+    (PAPER, SCISSORS): LOSE,
+    (STONE, PAPER): LOSE,
+    (STONE, STONE): DRAW,
+    (STONE, SCISSORS): WIN,
+    (SCISSORS, PAPER): WIN,
+    (SCISSORS, STONE): LOSE,
+    (SCISSORS, SCISSORS): DRAW
+}
+```
+
+### score.py
+
+Классы:
+
+- `ScoreHandler` - класс для обработки очков
+- `GameRecord` - класс содержащий записи об игроках
+- `PlayerRecord` - класс для хранения записи об одном игроке
+
+#### ScoreHandler
+
+Аттрибуты:
+
+- `game_record` - объект класса GameRecord, туда мы будем считывать сохраненные очки и записывать таблицу с новыми
+- `file_name` - имя файла откуда и куда мы записываем очки
+
+Методы:
+
+- `__init__` - принимает только имя файла и сохраняет его. Вызывает метод для чтения файла.
+- `read` - метод, который будет читать файл и каждую его строку сохранять в `PlayerRecord`, которые будут сохранятся в
+  `GameRecord`.
+- `save` - метод, который нужен, что бы записать новые результаты в файл (предварительно отсортировать и обрезать, если
+  нужно)
+- `display` - метод для отображения очков
+
+#### GameRecord
+
+Аттрибуты:
+
+- `records` - список объектов типа PlayerRecord
+
+Методы:
+
+- `__init__` - создает объект с пустым списком записей
+- `add_record` - метод для добавления записи об одном игроке. Должен проверять нет ли у нас уже такого игрока, и если
+  есть, то перезаписывать его результат. Тот же самый игрок проверяется по имени и уровню сложности (игрок может быть
+  представлен в таблице два раза на разном уровне сложности). (Можно использовать меджик метод `__eq__` для поиска
+  через `in`)
+- `prepare_records` - метод для сортировки существующих результатов и обрезки до максимального кол-ва указанного в
+  настройках
+
+#### PlayerRecord
+
+Аттрибуты:
+
+- `name` - имя игрока
+- `mode` - уровень сложности
+- `score` - кол-во очков
+
+Методы:
+
+- `__init__` - для создания объекта принимает все три параметра
+- `__gt__` - для того что бы можно было отсортировать записи по очкам
+- `__str__` - для удобного вывода данных
+
+### main.py
+
+Содержит функции:
+
+- `main` - для запуска всего кода, внутри этой функции должен быть запущен процесс выбора из трех пунктов (Запуск игры,
+  посмотреть очки и выйти из игры (1,2,3))
+- `play_game` - вызывается если игрок выбрал начать игру, в этой функции будет запущен процесс создания игрока, создание
+  объекта игры и запуск самой игры
+- `create_player` - спросить игрока имя и сложность, создать объект игрока с указанным именем, и передать объект игрока и
+  сложность в класс игры.
+- `show_scores` - показать очки, используя класс `ScoreHandler`
+- `exit` - выйти из игры
+
+## Пример как выглядит содержимое файла с очками
+
+| Name | Mode   | Score |
+|------|--------|-------|
+| Vlad | Normal | 14    |
+| Test | Hard   | 12    |
+| Jack | Normal | 12    |
+| Vlad | Hard   | 10    |
+| Jack | Hard   | 9     |

PR_explanation.md renamed to PR_explanation_Django.md

@@ -1,4 +1,4 @@
-# Как сдавать домашки
+# Как сдавать домашки по Django
 
 При помощи пулл-реквеста на GitHub.
 

PR_explanation_OOP.md

@@ -0,0 +1,64 @@
+# Как сдавать домашки
+
+При помощи пулл-реквеста на GitHub.
+
+## Что должно быть в репозитории??
+
+- Код проекта
+
+## Чего не должно быть в репозитории??
+
+Если коротко, то ничего лишнего.
+
+- Папок `__pycache__` и любого его содержимого.
+- Файлов настроек `IDE` например папки `.idea` или аналогов для других `IDE`
+- Для маков, файлов `.DS_Store`
+
+Все эти файлы и папки должны быть занесены в `.gitignore`
+
+## Как создать проект и репозиторий корректно (Делается один раз когда нам необходимо создать новый проект)
+
+Действия по пунктам:
+
+1. Создать репозиторий (`git init`)
+2. Подключить репозиторий к проекту (`git remote ...`)
+3. Создать и заполнить `.gitignore`
+4. Убедиться, что мы работаем в ветке `master` или `main`
+5. Закоммитить всё что у вас есть в свежем проекте. (Только файл `.gitignore`)
+   
+   Для коммита делаем две команды
+   
+   `git add .`
+   
+   `git commit -m "Some text"`
+6. Запушить пустой проект (только .gitignore) в мастер или мейн. (`git push`)
+7. Добавить меня в колабораторы проекта. Ник на гитхабе (`PonomaryovVladyslav`)
+
+## Как делать домашку
+
+1. Создать **из мастера** ветку, в названии которой будет информация о том, что это домашка и её номер. Например `hw_3`
+2. Выполнить домашнюю работу :) Рекомендуется коммитить изменения после любого осмысленного блока. По одной задаче или
+   даже куску задачи.
+3. Выполнить **пуш** этой ветки на удалённый репозиторий. (`git push`)
+4. Создать **пулл-реквест** из ветки с вашей **домашней работы** на **мастер** (онлайн на сайте github)
+5. Добавить меня в раздел `Reviewers`
+6. Дождаться моего апрува или комментариев, что нужно изменить
+   
+   6.1. Если получили коментарии о необходимости изменений, изменения добавляем (`git add` + `git commit`) на ветку
+   **домашней работы** после чего выполняем **пуш** (`git push`), пулл реквест сам обновится, 
+   и я получу уведомление об этом автоматически.
+7. После того как получили апрув, мержим изменения в мастер. (онлайн на сайте)
+
+## Что делать если я уже внёс файлы \__pycache__ или .idea на гит?
+
+В этом случае вам надо удалить файлы из гита, но сохранить их на локальной версии.
+
+Для этого необходимо выполнить команду:
+
+```
+git rm <file Relative path> --cached
+```
+
+Для каждого файла или папки.
+
+После чего выполнить коммит (`git commit`) и пуш (`git push`) снова.