# API Reference

## Базовые модели

### *class* source.models.base.Cell(x: int, y: int, is_wall: bool = False, is_start: bool = False, is_exit: bool = False)

Базовые классы: `object`

Представляет одну клетку поля лабиринта.

Каждая клетка хранит свои координаты и один из четырёх возможных
типов: стена, старт, выход или пустая клетка. Типы взаимоисключают
друг друга: установка одного автоматически сбрасывает остальные.

#### \_\_init_\_(x: int, y: int, is_wall: bool = False, is_start: bool = False, is_exit: bool = False)

Инициализирует клетку с заданными координатами и типом.

* **Параметры:**
  * **x** – Координата клетки по оси X.
  * **y** – Координата клетки по оси Y.
  * **is_wall** – Если True — клетка является стеной.
  * **is_start** – Если True — клетка является стартом.
  * **is_exit** – Если True — клетка является выходом.

#### *property* is_exit *: bool*

True, если клетка является выходом из лабиринта.

#### is_possible() → bool

Проверяет, можно ли переместиться в эту клетку.

* **Результат:**
  True, если клетка не является стеной, иначе False.

#### *property* is_start *: bool*

True, если клетка является стартовой позицией.

#### *property* is_wall *: bool*

True, если клетка является стеной.

### *class* source.models.base.Maze(size: tuple[int, int] = (10, 10))

Базовые классы: `object`

Представляет двумерный лабиринт из клеток Cell.

Лабиринт хранится как список списков клеток. Доступ к отдельным
клеткам и их изменение возможны через индексацию вида maze[row, col].

#### \_\_init_\_(size: tuple[int, int] = (10, 10))

Создаёт пустой лабиринт заданного размера.

* **Параметры:**
  **size** – Кортеж (width, height) — ширина и высота лабиринта в клетках.

#### *property* exit *: [Cell](#source.models.base.Cell) | None*

#### get_cell(x: int, y: int) → [Cell](#source.models.base.Cell) | None

Возвращает клетку по координатам или None, если координаты вне границ.

* **Параметры:**
  * **x** – Координата по оси X.
  * **y** – Координата по оси Y.
* **Результат:**
  Объект Cell, если координаты корректны, иначе None.

#### get_neighbors(x: int, y: int) → list[[Cell](#source.models.base.Cell)] | None

Возвращает список проходимых соседей клетки (вверх, вправо, вниз, влево).

* **Параметры:**
  * **x** – Координата клетки по оси X.
  * **y** – Координата клетки по оси Y.
* **Результат:**
  Список проходимых соседних клеток, или None если (x, y) вне границ.

#### *property* shape *: tuple[int, int]*

#### *property* start *: [Cell](#source.models.base.Cell) | None*

## Загрузка лабиринта

### *class* source.build.builder.MazeBuilder

Базовые классы: `ABC`

#### *abstractmethod* build_from_file(filename: str) → [Maze](#source.models.base.Maze)

Возвращает объект лабиринта по указанному пути файлу.

* **Параметры:**
  **filename** (*str*) – Путь к файлу
* **Исключение:**
  **TypeError** – Если введен путь файла с нерассмотренным расширением
* **Результат:**
  Объект лабиринта
* **Тип результата:**
  [Maze](#source.models.base.Maze)

### *class* source.build.builder.TextFileBuilder

Базовые классы: [`MazeBuilder`](#source.build.builder.MazeBuilder)

#### build_from_file(filename: str) → [Maze](#source.models.base.Maze)

Возвращает объект лабиринта по указанному пути файлу.

* **Параметры:**
  **filename** (*str*) – Путь к файлу
* **Исключение:**
  **TypeError** – Если введен путь файла с нерассмотренным расширением
* **Результат:**
  Объект лабиринта
* **Тип результата:**
  [Maze](#source.models.base.Maze)

## Стратегии поиска пути

### *class* source.strategy.algorithms.PathFindingStrategy

Базовые классы: `ABC`

Интерфейс стратегии поиска пути в лабиринте.

#### *abstractmethod* find_path(maze: [Maze](#source.models.base.Maze), start: [Cell](#source.models.base.Cell) = None, exit: [Cell](#source.models.base.Cell) = None) → list[[Cell](#source.models.base.Cell)]

Найти путь от start до exit.

* **Параметры:**
  * **maze** – Объект лабиринта.
  * **start** – Стартовая клетка.
  * **exit** – Целевая клетка.
* **Результат:**
  Список клеток пути (от start до exit включительно).
  Пустой список, если путь не найден.

<a id="module-source.strategy.bfs"></a>

### *class* source.strategy.bfs.BFSStrategy

Базовые классы: [`PathFindingStrategy`](#source.strategy.algorithms.PathFindingStrategy)

Поиск в ширину (Breadth-First Search).

Гарантирует кратчайший путь по количеству шагов.
Сложность: O(V + E) по времени и памяти.

#### find_path(maze: [Maze](#source.models.base.Maze), start: [Cell](#source.models.base.Cell) | None = None, exit: [Cell](#source.models.base.Cell) | None = None) → list[[Cell](#source.models.base.Cell)]

Найти путь от start до exit.

* **Параметры:**
  * **maze** – Объект лабиринта.
  * **start** – Стартовая клетка.
  * **exit** – Целевая клетка.
* **Результат:**
  Список клеток пути (от start до exit включительно).
  Пустой список, если путь не найден.

<a id="module-source.strategy.dfs"></a>

### *class* source.strategy.dfs.DFSStrategy

Базовые классы: [`PathFindingStrategy`](#source.strategy.algorithms.PathFindingStrategy)

Поиск в глубину (Depth-First Search).

Находит путь, но не гарантирует кратчайший.

#### find_path(maze: [Maze](#source.models.base.Maze), start: [Cell](#source.models.base.Cell) | None = None, exit: [Cell](#source.models.base.Cell) | None = None) → list[[Cell](#source.models.base.Cell)]

Найти путь от start до exit.

* **Параметры:**
  * **maze** – Объект лабиринта.
  * **start** – Стартовая клетка.
  * **exit** – Целевая клетка.
* **Результат:**
  Список клеток пути (от start до exit включительно).
  Пустой список, если путь не найден.

<a id="module-source.strategy.astar"></a>

### *class* source.strategy.astar.AStarStrategy

Базовые классы: [`PathFindingStrategy`](#source.strategy.algorithms.PathFindingStrategy)

Алгоритм A\* с манхэттенской эвристикой.

#### find_path(maze: [Maze](#source.models.base.Maze), start: [Cell](#source.models.base.Cell) | None = None, exit: [Cell](#source.models.base.Cell) | None = None) → list[[Cell](#source.models.base.Cell)]

Найти путь от start до exit.

* **Параметры:**
  * **maze** – Объект лабиринта.
  * **start** – Стартовая клетка.
  * **exit** – Целевая клетка.
* **Результат:**
  Список клеток пути (от start до exit включительно).
  Пустой список, если путь не найден.

## Оркестратор

### *class* source.strategy.solver.MazeSolver(maze: [Maze](#source.models.base.Maze), strategy: [PathFindingStrategy](#source.strategy.algorithms.PathFindingStrategy))

Базовые классы: `object`

Оркестратор поиска пути в лабиринте.

Принимает лабиринт и стратегию поиска, выполняет поиск
и возвращает результат вместе со статистикой выполнения.

### Пример

solver = MazeSolver(maze, BFSStrategy())
stats = solver.solve()
print(stats)

solver.set_strategy(AStarStrategy())
stats = solver.solve()

#### \_\_init_\_(maze: [Maze](#source.models.base.Maze), strategy: [PathFindingStrategy](#source.strategy.algorithms.PathFindingStrategy)) → None

Инициализирует солвер с лабиринтом и стратегией поиска.

* **Параметры:**
  * **maze** – Объект лабиринта.
  * **strategy** – Стратегия поиска пути.

#### set_strategy(strategy: [PathFindingStrategy](#source.strategy.algorithms.PathFindingStrategy)) → None

Заменяет текущую стратегию поиска.

* **Параметры:**
  **strategy** – Новая стратегия поиска пути.

#### solve(start: [Cell](#source.models.base.Cell) = None, exit: [Cell](#source.models.base.Cell) = None) → [SearchStats](#source.strategy.solver.SearchStats)

Выполняет поиск пути и собирает статистику.

Если start или exit не переданы явно, стратегия найдёт
их самостоятельно по флагам is_start / is_exit в лабиринте.

* **Параметры:**
  * **start** – Стартовая клетка (опционально).
  * **exit** – Конечная клетка (опционально).
* **Результат:**
  Объект SearchStats с временем выполнения, количеством
  посещённых клеток и длиной найденного пути.

### *class* source.strategy.solver.SearchStats(elapsed_ms: float, visited_count: int, path_length: int, path: list[[Cell](#source.models.base.Cell)])

Базовые классы: `object`

Статистика выполнения поиска пути.

#### elapsed_ms

Время выполнения в миллисекундах.

* **Type:**
  float

#### visited_count

Количество посещённых клеток.

* **Type:**
  int

#### path_length

Длина найденного пути (0 если путь не найден).

* **Type:**
  int

#### path

Найденный путь — список клеток от старта до выхода.

* **Type:**
  list[[source.models.base.Cell](#source.models.base.Cell)]

#### \_\_init_\_(elapsed_ms: float, visited_count: int, path_length: int, path: list[[Cell](#source.models.base.Cell)]) → None

#### elapsed_ms *: float*

#### path *: list[[Cell](#source.models.base.Cell)]*

#### path_length *: int*

#### visited_count *: int*

## Визуализация

### *class* source.view.observer.ConsoleView

Базовые классы: [`Observer`](#source.view.observer.Observer)

Отображает состояние лабиринта и события в консоли.

#### PATH_SYMBOL *= '·'*

#### PLAYER_SYMBOL *= 'P'*

#### render(maze: [Maze](#source.models.base.Maze), player: [Cell](#source.models.base.Cell) | None = None, path: list[[Cell](#source.models.base.Cell)] | None = None) → None

Рисует лабиринт в консоли.

Путь отмечается символом „·“, позиция игрока — „P“.

* **Параметры:**
  * **maze** – Объект лабиринта.
  * **player** – Текущая клетка игрока (опционально).
  * **path** – Список клеток найденного пути (опционально).

#### update(event: [Event](#source.view.observer.Event)) → None

Реагирует на события и выводит информацию в консоль.

* **Параметры:**
  **event** – Объект события.

### *class* source.view.observer.Event(type: str, payload: dict = None)

Базовые классы: `object`

Событие, передаваемое наблюдателям.

#### type

Тип события („maze_loaded“, „path_found“, „move“, „no_path“).

* **Type:**
  str

#### payload

Дополнительные данные события.

* **Type:**
  dict

#### \_\_init_\_(type: str, payload: dict = None) → None

#### payload *: dict* *= None*

#### type *: str*

### *class* source.view.observer.Observer

Базовые классы: `ABC`

Интерфейс наблюдателя за событиями лабиринта.

#### *abstractmethod* update(event: [Event](#source.view.observer.Event)) → None

Обрабатывает входящее событие.

* **Параметры:**
  **event** – Объект события с типом и данными.

## Управление игроком

### *class* source.view.command.Command

Базовые классы: `ABC`

Интерфейс команды с поддержкой отмены.

#### *abstractmethod* execute() → bool

Выполняет команду.

* **Результат:**
  True если команда выполнена успешно, False иначе.

#### *abstractmethod* undo() → None

Отменяет команду, восстанавливая предыдущее состояние.

### *class* source.view.command.CommandHistory

Базовые классы: `object`

Хранит историю выполненных команд и позволяет отменять их.

### Пример

history = CommandHistory()
cmd = MoveCommand(player, „w“, maze)
if cmd.execute():

> history.push(cmd)

history.undo()  # отменяет последний успешный ход

#### \_\_init_\_() → None

#### clear() → None

Очищает историю команд.

#### push(command: [Command](#source.view.command.Command)) → None

Добавляет выполненную команду в историю.

* **Параметры:**
  **command** – Успешно выполненная команда.

#### undo() → bool

Отменяет последнюю команду из истории.

* **Результат:**
  True если отмена выполнена, False если история пуста.

### *class* source.view.command.MoveCommand(player: [Player](#source.view.command.Player), direction: str, maze: [Maze](#source.models.base.Maze))

Базовые классы: [`Command`](#source.view.command.Command)

Перемещает игрока в заданном направлении.

Сохраняет предыдущую клетку для возможности отмены хода.

#### \_\_init_\_(player: [Player](#source.view.command.Player), direction: str, maze: [Maze](#source.models.base.Maze)) → None

Инициализирует команду перемещения.

* **Параметры:**
  * **player** – Объект игрока.
  * **direction** – Направление („w“, „a“, „s“, „d“).
  * **maze** – Объект лабиринта для проверки проходимости.
* **Исключение:**
  **ValueError** – Если направление не распознано.

#### execute() → bool

Перемещает игрока если целевая клетка проходима.

* **Результат:**
  True если перемещение выполнено, False если клетка непроходима.

#### undo() → None

Возвращает игрока на предыдущую клетку.

### *class* source.view.command.Player(cell: [Cell](#source.models.base.Cell))

Базовые классы: `object`

Хранит текущее положение игрока в лабиринте.

#### cell

Текущая клетка игрока.

#### \_\_init_\_(cell: [Cell](#source.models.base.Cell)) → None

Инициализирует игрока на заданной клетке.

* **Параметры:**
  **cell** – Начальная клетка игрока.
