k12. Мини-проект CLI «Fake GCS»

Задача 12.1. Модуль конфигурации

Файл практики: k12_config.py.

Создайте модуль конфигурации: класс настроек AppConfig с шестью полями, кортеж обязательных ключей REQUIRED_KEYS, собственное исключение ConfigError и функцию load_config() с проверкой чтения, формата JSON, состава ключей и согласованности порогов напряжения.

Ожидаемый результат. Импорт from k12_config import AppConfig, ConfigError, load_config проходит без ошибок.

• Полный текст файла k12_config.py

  Скопируйте приведённое ниже содержимое в файл code/M01_python/k12_config.py в проекте PyCharm (виртуальное окружение). Ниже приведён полный учебный текст файла; он совпадает с файлом в репозитории курса.

  # k12_config.py
  # Конфигурация мини-проекта Fake GCS (K12):
  # чтение JSON, проверка обязательных ключей, своё исключение ConfigError.
  
  import json
  from dataclasses import dataclass
  from pathlib import Path
  
  
  class ConfigError(Exception):
      """Файл конфигурации отсутствует, не читается или содержит неверные значения."""
  
  
  @dataclass
  class AppConfig:
      """Настройки приложения, собранные из JSON-файла."""
  
      log_file: str
      log_level: str
      state_file: str
      csv_track: str
      low_voltage_v: float
      critical_voltage_v: float
  
  
  REQUIRED_KEYS = (
      "log_file",
      "log_level",
      "state_file",
      "csv_track",
      "low_voltage_v",
      "critical_voltage_v",
  )
  
  
  def load_config(path: Path) -＞ AppConfig:
      """Прочитать JSON-конфигурацию и вернуть проверенный AppConfig.
  
      Поднимает ConfigError, если файл не читается, если JSON повреждён,
      если отсутствуют обязательные ключи или если пороги напряжения
      противоречат друг другу.
      """
      try:
          text = path.read_text(encoding="utf-8")
      except OSError as exc:
          raise ConfigError(f"файл конфигурации не читается: {path}") from exc
      try:
          data = json.loads(text)
      except json.JSONDecodeError as exc:
          raise ConfigError(
              f"файл конфигурации не является корректным JSON: {path}"
          ) from exc
      if not isinstance(data, dict):
          raise ConfigError("JSON-конфигурация должна быть объектом со строковыми ключами")
      missing = [key for key in REQUIRED_KEYS if key not in data]
      if missing:
          raise ConfigError(f"в конфигурации отсутствуют ключи: {', '.join(missing)}")
      try:
          config = AppConfig(
              log_file=str(data["log_file"]),
              log_level=str(data["log_level"]),
              state_file=str(data["state_file"]),
              csv_track=str(data["csv_track"]),
              low_voltage_v=float(data["low_voltage_v"]),
              critical_voltage_v=float(data["critical_voltage_v"]),
          )
      except (TypeError, ValueError) as exc:
          raise ConfigError(f"поле конфигурации имеет неверный тип: {exc}") from exc
      if config.critical_voltage_v ＞= config.low_voltage_v:
          raise ConfigError(
              "порог critical_voltage_v должен быть строго меньше порога low_voltage_v"
          )
      return config

Задача 12.2. Модуль аппарата

Файл практики: k12_vehicle.py.

Создайте модуль аппарата: перечисление режимов FlightMode, структуру отсчёта TelemetrySample, исключение PrearmError и класс FakeVehicle с загрузкой состояния, атомарным сохранением, командами arm(), disarm(), set_mode() и меткой батареи battery_label().

Ожидаемый результат. Импорт from k12_vehicle import FakeVehicle, FlightMode, PrearmError, TelemetrySample проходит без ошибок.

• Полный текст файла k12_vehicle.py

  Скопируйте приведённое ниже содержимое в файл code/M01_python/k12_vehicle.py в проекте PyCharm (виртуальное окружение). Ниже приведён полный учебный текст файла; он совпадает с файлом в репозитории курса.

  # k12_vehicle.py
  # Модель «аппарата» для фейковой наземной станции управления:
  # перечисление режимов, отсчёт телеметрии, класс FakeVehicle с prearm-проверками.
  
  import json
  import os
  from dataclasses import dataclass
  from enum import Enum
  from pathlib import Path
  
  from k12_config import AppConfig
  
  
  class FlightMode(Enum):
      """Учебные режимы полёта (имена как у ArduPilot Copter)."""
  
      STABILIZE = "STABILIZE"
      LOITER = "LOITER"
      GUIDED = "GUIDED"
      AUTO = "AUTO"
      RTL = "RTL"
      LAND = "LAND"
  
  
  @dataclass
  class TelemetrySample:
      """Один отсчёт телеметрии из канала-заглушки."""
  
      tick: int
      altitude_m: float
      voltage_v: float
  
  
  class PrearmError(Exception):
      """Prearm-проверка не пройдена: взведение моторов запрещено."""
  
  
  class FakeVehicle:
      """Фейковый аппарат: состояние хранится в JSON-файле между запусками CLI."""
  
      def __init__(
          self,
          config: AppConfig,
          armed: bool = False,
          mode: FlightMode = FlightMode.STABILIZE,
          battery_v: float = 15.2,
          tick: int = 0,
      ):
          self.config = config
          self.armed = armed
          self.mode = mode
          self.battery_v = battery_v
          self.tick = tick
  
      @classmethod
      def load(cls, config: AppConfig) -＞ "FakeVehicle":
          """Загрузить состояние из файла; если файла нет — взять значения по умолчанию."""
          path = Path(config.state_file)
          if not path.exists():
              return cls(config)
          data = json.loads(path.read_text(encoding="utf-8"))
          return cls(
              config,
              armed=bool(data.get("armed", False)),
              mode=FlightMode(str(data.get("mode", "STABILIZE"))),
              battery_v=float(data.get("battery_v", 15.2)),
              tick=int(data.get("tick", 0)),
          )
  
      def save_state(self) -＞ None:
          """Сохранить состояние атомарно: сначала временный файл, затем os.replace."""
          path = Path(self.config.state_file)
          tmp_path = Path(str(path) + ".tmp")
          payload = {
              "armed": self.armed,
              "mode": self.mode.value,
              "battery_v": self.battery_v,
              "tick": self.tick,
          }
          tmp_path.write_text(
              json.dumps(payload, indent=2, ensure_ascii=False),
              encoding="utf-8",
          )
          os.replace(tmp_path, path)
  
      def arm(self) -＞ None:
          """Взвести моторы, если prearm-проверки пройдены."""
          if self.armed:
              raise PrearmError("аппарат уже взведён (armed)")
          if self.battery_v ＜ self.config.critical_voltage_v:
              raise PrearmError(
                  f"напряжение батареи {self.battery_v:.2f} В ниже критического порога "
                  f"{self.config.critical_voltage_v:.2f} В"
              )
          self.armed = True
  
      def disarm(self) -＞ None:
          """Снять моторы с взведения. Команда идемпотентна: повтор безопасен."""
          self.armed = False
  
      def set_mode(self, name: str) -＞ None:
          """Установить режим полёта по имени; при неизвестном имени — ValueError."""
          self.mode = FlightMode(name.upper())
  
      def apply_sample(self, sample: TelemetrySample) -＞ None:
          """Обновить напряжение и счётчик отсчётов по последнему отсчёту телеметрии."""
          self.battery_v = sample.voltage_v
          self.tick = sample.tick
  
      def battery_label(self) -＞ str:
          """Учебная метка состояния батареи: OK / LOW / CRITICAL (как в K11)."""
          if self.battery_v ＜ self.config.critical_voltage_v:
              return "CRITICAL"
          if self.battery_v ＜ self.config.low_voltage_v:
              return "LOW"
          return "OK"
  
      def status_text(self) -＞ str:
          """Короткая человекочитаемая сводка состояния для команды status."""
          state = "ARMED" if self.armed else "DISARMED"
          return (
              f"mode={self.mode.value}  state={state}  "
              f"battery={self.battery_v:.2f} V ({self.battery_label()})  tick={self.tick}"
          )

Задача 12.3. Канал-заглушка и CSV-трек

Файл практики: k12_link.py.

Создайте модуль канала: класс FakeLink с интерфейсом open() / read_sample() / close(), детерминированными формулами телеметрии и функцию save_track_csv() для записи трека.

Ожидаемый результат. Импорт from k12_link import FakeLink, save_track_csv проходит без ошибок.

• Полный текст файла k12_link.py

  Скопируйте приведённое ниже содержимое в файл code/M01_python/k12_link.py в проекте PyCharm (виртуальное окружение). Ниже приведён полный учебный текст файла; он совпадает с файлом в репозитории курса.

  # k12_link.py
  # Канал-заглушка телеметрии вместо настоящего serial/UDP-порта
  # и сохранение трека в CSV.
  
  import csv
  import logging
  from pathlib import Path
  
  from k12_vehicle import TelemetrySample
  
  log = logging.getLogger("fake_gcs.link")
  
  
  class FakeLink:
      """Заглушка канала связи: детерминированная телеметрия без реальных портов.
  
      Интерфейс open() / read_sample() / close() намеренно похож на будущую
      реальную связь с SITL по MAVLink: в модуле M5 внутри заменится
      реализация, а вызывающий код останется прежним.
      """
  
      def __init__(self, start_tick: int = 0):
          self._tick = start_tick
          self._opened = False
  
      @property
      def tick(self) -＞ int:
          """Текущий счётчик отсчётов."""
          return self._tick
  
      def open(self) -＞ None:
          """«Открыть порт»: разрешить чтение отсчётов."""
          if self._opened:
              raise RuntimeError("канал уже открыт")
          self._opened = True
          log.info("канал-заглушка открыт (fake link)")
  
      def close(self) -＞ None:
          """«Закрыть порт». Закрытый канал можно открыть снова."""
          if self._opened:
              self._opened = False
              log.info("канал-заглушка закрыт")
  
      def read_sample(self) -＞ TelemetrySample:
          """Вернуть следующий отсчёт телеметрии.
  
          Значения вычисляются по формулам от счётчика _tick, поэтому
          последовательность детерминирована: это удобно проверять тестами.
          """
          if not self._opened:
              raise RuntimeError("канал не открыт: сначала вызовите open()")
          self._tick += 1
          altitude_m = round(min(10.0 + 0.1 * self._tick, 50.0), 2)
          voltage_v = round(max(15.2 - 0.02 * self._tick, 13.2), 2)
          return TelemetrySample(
              tick=self._tick, altitude_m=altitude_m, voltage_v=voltage_v
          )
  
  
  def save_track_csv(samples: list[TelemetrySample], path: Path) -＞ None:
      """Записать отсчёты телеметрии в CSV-файл с заголовком."""
      with path.open("w", encoding="utf-8", newline="") as handle:
          writer = csv.writer(handle)
          writer.writerow(["tick", "altitude_m", "voltage_v"])
          for sample in samples:
              writer.writerow([sample.tick, sample.altitude_m, sample.voltage_v])
      log.info("трек сохранён в CSV: %s (отсчётов: %d)", path, len(samples))

Задача 12.4. Точка входа CLI

Файл практики: k12_cli.py.

Создайте точку входа мини-проекта: build_parser() с шестью подкомандами, setup_logging(), диспетчер run_command() и функцию main() с кодами возврата. Это самый большой файл проекта — сверяйте его с аккордеоном целиком.

Ожидаемый результат. Команда python k12_cli.py --help печатает справку со списком подкоманд config, status, arm, disarm, mode и tele.

• Полный текст файла k12_cli.py

  Скопируйте приведённое ниже содержимое в файл code/M01_python/k12_cli.py в проекте PyCharm (виртуальное окружение). Ниже приведён полный учебный текст файла; он совпадает с файлом в репозитории курса.

  # k12_cli.py
  # Точка входа CLI мини-проекта Fake GCS (K12).
  # Запуск из каталога code/M01_python:
  #   python k12_cli.py --config k12_config_example.json status
  #   python k12_cli.py --config k12_config_example.json arm
  #   python k12_cli.py --config k12_config_example.json tele --count 5 --csv
  
  import argparse
  import logging
  import sys
  from pathlib import Path
  
  from k12_config import AppConfig, ConfigError, load_config
  from k12_link import FakeLink, save_track_csv
  from k12_vehicle import FakeVehicle, FlightMode, PrearmError
  
  log = logging.getLogger("fake_gcs.cli")
  
  EXIT_OK = 0
  EXIT_CONFIG_ERROR = 2
  EXIT_COMMAND_ERROR = 3
  
  
  def build_parser() -＞ argparse.ArgumentParser:
      """Собрать парсер аргументов командной строки и подкоманд."""
      parser = argparse.ArgumentParser(
          prog="k12_cli.py",
          description="Fake GCS: учебная наземная станция управления без реального железа.",
      )
      parser.add_argument(
          "--config",
          default="k12_config_example.json",
          help="путь к JSON-файлу конфигурации (по умолчанию k12_config_example.json)",
      )
      sub = parser.add_subparsers(dest="command", required=True)
  
      sub.add_parser("config", help="показать загруженную конфигурацию")
      sub.add_parser("status", help="показать состояние аппарата")
      sub.add_parser("arm", help="взвести моторы (выполняются prearm-проверки)")
      sub.add_parser("disarm", help="снять моторы с взведения")
  
      mode_parser = sub.add_parser("mode", help="установить режим полёта")
      mode_parser.add_argument(
          "name",
          choices=[m.value for m in FlightMode],
          help="имя режима, например RTL или LOITER",
      )
  
      tele_parser = sub.add_parser("tele", help="прочитать телеметрию из канала-заглушки")
      tele_parser.add_argument(
          "--count",
          type=int,
          default=5,
          help="число отсчётов телеметрии (по умолчанию 5)",
      )
      tele_parser.add_argument(
          "--csv",
          action="store_true",
          help="сохранить трек в CSV-файл из конфигурации",
      )
      return parser
  
  
  def setup_logging(config: AppConfig) -＞ None:
      """Настроить логирование в консоль и в файл (урок K08)."""
      level = getattr(logging, config.log_level.upper(), logging.INFO)
      logging.basicConfig(
          level=level,
          format="%(asctime)s %(levelname)s %(name)s %(message)s",
          handlers=[
              logging.StreamHandler(sys.stdout),
              logging.FileHandler(config.log_file, encoding="utf-8"),
          ],
          force=True,
      )
  
  
  def format_config(config: AppConfig) -＞ str:
      """Вернуть конфигурацию в виде текста для команды config."""
      lines = [
          f"log_file           = {config.log_file}",
          f"log_level          = {config.log_level}",
          f"state_file         = {config.state_file}",
          f"csv_track          = {config.csv_track}",
          f"low_voltage_v      = {config.low_voltage_v}",
          f"critical_voltage_v = {config.critical_voltage_v}",
      ]
      return "\n".join(lines)
  
  
  def run_command(args: argparse.Namespace, config: AppConfig) -＞ int:
      """Выполнить выбранную подкоманду и вернуть код возврата."""
      vehicle = FakeVehicle.load(config)
  
      if args.command == "config":
          print(format_config(config))
          return EXIT_OK
  
      if args.command == "status":
          print(vehicle.status_text())
          return EXIT_OK
  
      if args.command == "arm":
          vehicle.arm()
          vehicle.save_state()
          log.info("команда arm выполнена")
          print(vehicle.status_text())
          return EXIT_OK
  
      if args.command == "disarm":
          vehicle.disarm()
          vehicle.save_state()
          log.info("команда disarm выполнена")
          print(vehicle.status_text())
          return EXIT_OK
  
      if args.command == "mode":
          vehicle.set_mode(args.name)
          vehicle.save_state()
          log.info("установлен режим %s", vehicle.mode.value)
          print(vehicle.status_text())
          return EXIT_OK
  
      if args.command == "tele":
          if args.count ＜ 1:
              raise ValueError("значение --count должно быть не меньше 1")
          link = FakeLink(start_tick=vehicle.tick)
          link.open()
          try:
              samples = [link.read_sample() for _ in range(args.count)]
          finally:
              link.close()
          for sample in samples:
              print(
                  f"tick={sample.tick}  alt={sample.altitude_m:.2f} m  "
                  f"volt={sample.voltage_v:.2f} V"
              )
          vehicle.apply_sample(samples[-1])
          vehicle.save_state()
          if args.csv:
              save_track_csv(samples, Path(config.csv_track))
              print(f"CSV-трек сохранён: {config.csv_track}")
          return EXIT_OK
  
      raise ValueError(f"неизвестная команда: {args.command}")
  
  
  def main(argv: list[str] | None = None) -＞ int:
      """Точка входа: разобрать аргументы, настроить лог, выполнить команду.
  
      Параметр argv нужен тестам: в них список аргументов передают вручную.
      При обычном запуске argv равен None, и argparse берёт sys.argv сам.
      """
      parser = build_parser()
      args = parser.parse_args(argv)
      try:
          config = load_config(Path(args.config))
      except ConfigError as exc:
          print(f"Ошибка конфигурации: {exc}")
          return EXIT_CONFIG_ERROR
      setup_logging(config)
      log.info("запуск Fake GCS, команда: %s", args.command)
      try:
          return run_command(args, config)
      except (PrearmError, ValueError, RuntimeError, OSError) as exc:
          log.error("команда %s завершилась ошибкой: %s", args.command, exc)
          print(f"Ошибка команды: {exc}")
          return EXIT_COMMAND_ERROR
  
  
  if __name__ == "__main__":
      sys.exit(main())

Задача 12.5. Пример конфигурации

Файл практики: k12_config_example.json.

Создайте JSON-файл конфигурации с шестью ключами. Значения можно менять: например, повысьте critical_voltage_v и убедитесь, что prearm-проверка начинает отклонять команду arm раньше.

Ожидаемый результат. Команда python k12_cli.py --config k12_config_example.json config печатает все шесть настроек.

• Полный текст файла k12_config_example.json

  Скопируйте приведённое ниже содержимое в файл code/M01_python/k12_config_example.json в проекте PyCharm. Это пример конфигурации мини-проекта; артефакты программы (журнал, состояние, трек) будут создаваться рядом с ним.

  {
    "log_file": "k12_gcs.log",
    "log_level": "INFO",
    "state_file": "k12_state.json",
    "csv_track": "k12_track.csv",
    "low_voltage_v": 14.4,
    "critical_voltage_v": 14.0
  }

Задача 12.6. Тесты мини-проекта

Файл практики: k12_test_app.py.

Создайте файл тестов: четыре проверки конфигурации, пять проверок аппарата, две проверки канала-заглушки и шесть интеграционных проверок CLI с фикстурой tmp_path — всего семнадцать тестов.

Ожидаемый результат. Команда python -m pytest k12_test_app.py -v показывает 17 passed.

• Полный текст файла k12_test_app.py

  Скопируйте приведённое ниже содержимое в файл code/M01_python/k12_test_app.py в проекте PyCharm (виртуальное окружение). Ниже приведён полный учебный текст файла; он совпадает с файлом в репозитории курса.

  # k12_test_app.py
  # Тесты мини-проекта Fake GCS: конфигурация, аппарат, канал-заглушка, CLI.
  # Запуск из каталога code/M01_python:
  #   python -m pytest k12_test_app.py -v
  
  import json
  from pathlib import Path
  from unittest.mock import MagicMock
  
  import pytest
  
  from k12_cli import EXIT_COMMAND_ERROR, EXIT_CONFIG_ERROR, EXIT_OK, main
  from k12_config import AppConfig, ConfigError, load_config
  from k12_link import FakeLink
  from k12_vehicle import FakeVehicle, PrearmError
  
  VALID_CONFIG = {
      "log_file": "k12_gcs.log",
      "log_level": "INFO",
      "state_file": "k12_state.json",
      "csv_track": "k12_track.csv",
      "low_voltage_v": 14.4,
      "critical_voltage_v": 14.0,
  }
  
  
  def make_fake_config_path(payload: dict) -＞ MagicMock:
      """Заглушка Path, у которой read_text возвращает заданный JSON (приём из K11)."""
      fake_path = MagicMock(spec=Path)
      fake_path.read_text.return_value = json.dumps(payload)
      return fake_path
  
  
  def loaded_config() -＞ AppConfig:
      """Загрузить корректную конфигурацию через заглушку пути."""
      return load_config(make_fake_config_path(VALID_CONFIG))
  
  
  def make_vehicle(battery_v: float) -＞ FakeVehicle:
      """Создать аппарат с заданным напряжением батареи (файл состояния не нужен)."""
      return FakeVehicle(loaded_config(), battery_v=battery_v)
  
  
  def write_config(tmp_path: Path) -＞ Path:
      """Записать настоящую конфигурацию во временный каталог теста."""
      payload = dict(VALID_CONFIG)
      payload["log_file"] = str(tmp_path / "gcs.log")
      payload["state_file"] = str(tmp_path / "state.json")
      payload["csv_track"] = str(tmp_path / "track.csv")
      config_path = tmp_path / "config.json"
      config_path.write_text(json.dumps(payload), encoding="utf-8")
      return config_path
  
  
  # --- конфигурация (JSON + проверка) -------------------------------------
  
  
  def test_load_config_ok():
      config = loaded_config()
      assert config.low_voltage_v == 14.4
      assert config.state_file == "k12_state.json"
  
  
  def test_load_config_missing_key():
      payload = dict(VALID_CONFIG)
      del payload["csv_track"]
      with pytest.raises(ConfigError):
          load_config(make_fake_config_path(payload))
  
  
  def test_load_config_bad_json():
      fake_path = MagicMock(spec=Path)
      fake_path.read_text.return_value = "{not-json"
      with pytest.raises(ConfigError):
          load_config(fake_path)
  
  
  def test_load_config_bad_thresholds():
      payload = dict(VALID_CONFIG)
      payload["critical_voltage_v"] = 15.0  # больше low_voltage_v — так нельзя
      with pytest.raises(ConfigError):
          load_config(make_fake_config_path(payload))
  
  
  # --- аппарат и prearm-проверки ------------------------------------------
  
  
  def test_arm_and_disarm():
      vehicle = make_vehicle(15.0)
      vehicle.arm()
      assert vehicle.armed is True
      vehicle.disarm()
      assert vehicle.armed is False
  
  
  def test_arm_twice_raises():
      vehicle = make_vehicle(15.0)
      vehicle.arm()
      with pytest.raises(PrearmError):
          vehicle.arm()
  
  
  def test_arm_on_critical_battery_raises():
      vehicle = make_vehicle(13.5)
      with pytest.raises(PrearmError):
          vehicle.arm()
  
  
  def test_battery_label():
      assert make_vehicle(15.0).battery_label() == "OK"
      assert make_vehicle(14.2).battery_label() == "LOW"
      assert make_vehicle(13.5).battery_label() == "CRITICAL"
  
  
  def test_set_mode_unknown_raises():
      vehicle = make_vehicle(15.0)
      vehicle.set_mode("loiter")
      assert vehicle.mode.value == "LOITER"
      with pytest.raises(ValueError):
          vehicle.set_mode("ACROBATICS")
  
  
  # --- канал-заглушка ------------------------------------------------------
  
  
  def test_link_requires_open():
      link = FakeLink()
      with pytest.raises(RuntimeError):
          link.read_sample()
  
  
  def test_link_deterministic():
      first = FakeLink()
      first.open()
      second = FakeLink()
      second.open()
      samples_a = [first.read_sample() for _ in range(3)]
      samples_b = [second.read_sample() for _ in range(3)]
      assert samples_a == samples_b
      assert samples_a[0].altitude_m == 10.1
      assert samples_a[0].voltage_v == 15.18
  
  
  # --- CLI целиком (фикстура tmp_path) -------------------------------------
  
  
  def test_cli_status_ok(tmp_path):
      config_path = write_config(tmp_path)
      assert main(["--config", str(config_path), "status"]) == EXIT_OK
  
  
  def test_cli_arm_persists_state(tmp_path):
      config_path = write_config(tmp_path)
      assert main(["--config", str(config_path), "arm"]) == EXIT_OK
      state = json.loads((tmp_path / "state.json").read_text(encoding="utf-8"))
      assert state["armed"] is True
  
  
  def test_cli_tele_writes_csv(tmp_path):
      config_path = write_config(tmp_path)
      code = main(["--config", str(config_path), "tele", "--count", "3", "--csv"])
      assert code == EXIT_OK
      lines = (tmp_path / "track.csv").read_text(encoding="utf-8").splitlines()
      assert lines[0] == "tick,altitude_m,voltage_v"
      assert len(lines) == 4  # заголовок + три отсчёта
  
  
  def test_cli_missing_config_returns_exit_code(tmp_path):
      missing = tmp_path / "missing.json"
      assert main(["--config", str(missing), "status"]) == EXIT_CONFIG_ERROR
  
  
  def test_cli_bad_count_returns_exit_code(tmp_path):
      config_path = write_config(tmp_path)
      code = main(["--config", str(config_path), "tele", "--count", "0"])
      assert code == EXIT_COMMAND_ERROR
  
  
  def test_cli_unknown_mode_exits_via_argparse(tmp_path):
      config_path = write_config(tmp_path)
      with pytest.raises(SystemExit) as exc_info:
          main(["--config", str(config_path), "mode", "ACROBATICS"])
      assert exc_info.value.code == 2  # так argparse сообщает об ошибке выбора

Задача 12.7. Памятка команд

Файл практики: k12_run_note.py.

Создайте файл-памятку и откройте его: в комментариях перечислены все команды мини-проекта в порядке выполнения, как в задаче 12.8.

Ожидаемый результат. Файл открывается в редакторе; при запуске печатается одно напоминание.

• Полный текст файла k12_run_note.py

  Скопируйте приведённое ниже содержимое в файл code/M01_python/k12_run_note.py в проекте PyCharm (виртуальное окружение). Ниже приведён полный учебный текст файла; он совпадает с файлом в репозитории курса.

  # k12_run_note.py
  # Памятка команд мини-проекта K12 (выполняйте в venv из каталога code/M01_python).
  #
  # 1) Показать конфигурацию:
  #    python k12_cli.py --config k12_config_example.json config
  # 2) Состояние аппарата:
  #    python k12_cli.py --config k12_config_example.json status
  # 3) Взвести моторы (выполняются prearm-проверки):
  #    python k12_cli.py --config k12_config_example.json arm
  # 4) Установить режим:
  #    python k12_cli.py --config k12_config_example.json mode LOITER
  # 5) Телеметрия с сохранением CSV-трека:
  #    python k12_cli.py --config k12_config_example.json tele --count 5 --csv
  # 6) Снять с взведения:
  #    python k12_cli.py --config k12_config_example.json disarm
  # 7) Тесты мини-проекта:
  #    python -m pytest k12_test_app.py -v
  #
  # После работы в каталоге появятся артефакты: k12_gcs.log, k12_state.json,
  # k12_track.csv. В git коммитьте только исходники (.py и пример конфигурации).
  
  print("Откройте комментарии этого файла и выполните команды по порядку в терминале.")

Задача 12.8. Прогон CLI (обязательно выполнить)

Выполните команды основного сценария по порядку из каталога code/M01_python с активным виртуальным окружением. Перед каждой напечатанной строкой программа выводит запись журнала с точным временем — ваше время будет другим, это нормально.

# Каталог: code/M01_python (venv активен)
python k12_cli.py --config k12_config_example.json config
python k12_cli.py --config k12_config_example.json status
python k12_cli.py --config k12_config_example.json arm
python k12_cli.py --config k12_config_example.json mode LOITER
python k12_cli.py --config k12_config_example.json tele --count 5 --csv
python k12_cli.py --config k12_config_example.json disarm
python k12_cli.py --config k12_config_example.json status

Ожидаемый результат. Ключевые строки вывода (записи журнала опущены):

mode=STABILIZE  state=DISARMED  battery=15.20 V (OK)  tick=0   # status до arm
mode=STABILIZE  state=ARMED     battery=15.20 V (OK)  tick=0   # после arm
mode=LOITER     state=ARMED     battery=15.20 V (OK)  tick=0   # после mode LOITER
tick=1  alt=10.10 m  volt=15.18 V                              # tele: пять отсчётов
tick=2  alt=10.20 m  volt=15.16 V
tick=3  alt=10.30 m  volt=15.14 V
tick=4  alt=10.40 m  volt=15.12 V
tick=5  alt=10.50 m  volt=15.10 V
CSV-трек сохранён: k12_track.csv
mode=LOITER     state=DISARMED  battery=15.10 V (OK)  tick=5   # после disarm

Затем воспроизведите сценарий отказа prearm-проверки: сначала «разрядите батарею» длинной серией отсчётов, убедитесь в отказе команды arm, затем удалите файл состояния и взведите аппарат снова.

# Каталог: code/M01_python (venv активен)

# «Разряжаем батарею»: сто отсчётов уронят напряжение до 13.20 В
python k12_cli.py tele --count 100
python k12_cli.py status
# Ожидается строка: battery=13.20 V (CRITICAL)

# Команда arm отклоняется prearm-проверкой, код возврата 3
python k12_cli.py arm
# Ожидается: Ошибка команды: напряжение батареи 13.20 В ниже критического порога 14.00 В

# «Меняем батарею»: удаляем файл состояния и взводим снова
# (в cmd и PowerShell работает del; аналог в PowerShell — Remove-Item)
del k12_state.json
python k12_cli.py arm
# Ожидается: mode=STABILIZE  state=ARMED  battery=15.20 V (OK)  tick=0

Ожидаемый результат. Первый arm отклонён с кодом возврата 3 и внятной причиной; после удаления k12_state.json второй arm выполнен успешно. Файлы k12_track.csv и k12_gcs.log существуют в каталоге.

Задача 12.9. Прогон тестов (обязательно выполнить)

Запустите весь набор тестов мини-проекта. Фикстура tmp_path создаёт временные каталоги автоматически — готовить файлы на диске не нужно.

# Каталог: code/M01_python (venv активен, pytest установлен на уроке K11)
python -m pytest k12_test_app.py -v
# Ожидается: все семнадцать тестов passed

Ожидаемый результат. В отчёте pytest семнадцать строк PASSED и итог вида «17 passed». Если тест упал, прочитайте раздел вывода FAILED: в нём показаны фактическое и ожидаемое значения.

Задача 12.10. Сохранение в Git

Добавьте в репозиторий только исходники мини-проекта и пример конфигурации. Артефакты запуска (k12_gcs.log, k12_state.json, k12_track.csv) коммитить не нужно: они пересоздаются при каждом запуске. При желании добавьте их в файл .gitignore.

# Из корня репозитория курса
git add code/M01_python/k12_config.py code/M01_python/k12_vehicle.py code/M01_python/k12_link.py code/M01_python/k12_cli.py code/M01_python/k12_test_app.py code/M01_python/k12_run_note.py code/M01_python/k12_config_example.json
git commit -m "K12: Fake GCS mini-project - argparse CLI, JSON config/state, CSV track, 17 tests (G1)"

Ожидаемый результат. Команда git status показывает чистое рабочее дерево по файлам k12_*, а в истории появился коммит с сообщением про мини-проект K12 и гейт G1.