Add OOP module task

Author: Vlad Ponomarov

OOP_task.md

@@ -0,0 +1,194 @@
+# Модульное задание по 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 - выйти из игры