✧ Собираем утилиту целиком ✧

🚀 Запускаем

Соберём всё, что узнали в этом разделе, в одну настоящую утилиту farm: она записывает, сколько смолы потрачено и где, и помнит это между запусками. Сначала запусти пример: он записывает файл farm.py и вызывает его три раза как отдельную программу, ровно так, как ты делал бы это в терминале.

import subprocess
import sys
from pathlib import Path

Path("farm.py").write_text('''
import argparse
import json
import sys
from pathlib import Path

DB = Path("farm.json")


def load():
    return json.loads(DB.read_text(encoding="utf-8")) if DB.exists() else {}


def main(argv=None):
    parser = argparse.ArgumentParser(prog="farm")
    commands = parser.add_subparsers(dest="command", required=True)
    add = commands.add_parser("add")
    add.add_argument("place")
    add.add_argument("resin", type=int)
    commands.add_parser("total")
    args = parser.parse_args(argv)

    data = load()
    if args.command == "add":
        data[args.place] = data.get(args.place, 0) + args.resin
        DB.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
        print("Записано:", args.place, args.resin)
    else:
        print("Всего потрачено:", sum(data.values()))
    return 0


if __name__ == "__main__":
    sys.exit(main())
''', encoding="utf-8")

for command in (["add", "Подземелье", "20"], ["add", "Босс", "40"], ["total"], ["add", "Босс", "abc"]):
    result = subprocess.run([sys.executable, "farm.py", *command], capture_output=True, text=True)
    print(command, "→", result.returncode, result.stdout.strip() or result.stderr.splitlines()[-1])
['add', 'Подземелье', '20'] → 0 Записано: Подземелье 20
['add', 'Босс', '40'] → 0 Записано: Босс 40
['total'] → 0 Всего потрачено: 60
['add', 'Босс', 'abc'] → 2 farm add: error: argument resin: invalid int value: 'abc'

Каждый запуск — отдельный процесс, переменных между ними нет. Но третий запуск знает про первые два, потому что данные лежат в файле farm.json. А четвёртый показывает, что argparse сам отказался принять abc вместо числа и завершился с кодом 2. Всё вместе — те же кирпичики, что мы разбирали по отдельности.

📜 Теория: из скрипта в утилиту

Три слоя

def add_run(data, place, resin):          # логика: чистая функция, легко проверить тестом
    data[place] = data.get(place, 0) + resin
    return data


def load(path): ...                       # хранение: читает и пишет файл или базу
def save(path, data): ...


def main(argv=None): ...                  # интерфейс: разбирает аргументы, печатает, возвращает код

Разделяй программу на три слоя: логику (вычисления над данными), хранение (файл или база) и интерфейс (аргументы и печать). Логика не знает, откуда пришли данные и куда пойдёт ответ, поэтому её можно проверить обычным тестом и подключить потом не к терминалу, а, например, к сайту. Для большой утилиты каждому слою отводят свой файл: logic.py, storage.py, cli.py.

Где хранить данные между запусками

from pathlib import Path

DATA_DIR = Path.home() / ".farm"
DATA_DIR.mkdir(exist_ok=True)
DB = DATA_DIR / "farm.json"

Если записывать данные в рабочую папку, как в нашем примере, они будут появляться там, откуда запустили утилиту. Принято прятать их в папку пользователя (Path.home()) под точкой в начале имени (на Linux и macOS такие папки скрыты) или в специальную папку приложений — её адрес подсказывает библиотека platformdirs. Для небольших данных подойдёт JSON, для больших и сложных — SQLite. Запись делай аккуратно (сначала во временный файл, потом replace), как в уроке про защиту от потерь.

Структура проекта

farm/
    pyproject.toml          # описание проекта и команд
    farm/
        __init__.py
        __main__.py         # запуск: python -m farm
        cli.py              # аргументы и печать
        storage.py          # файл или база
    tests/
        test_logic.py

Папка farm/ с файлом __main__.py запускается командой python -m farm, а модули внутри импортируют друг друга через относительные импорты — это мы разбирали в уроке про пакеты. Тесты лежат отдельно и проверяют логику, не трогая терминал.

Команда вместо python farm.py

# pyproject.toml
[project]
name = "farm"
version = "0.1"

[project.scripts]
farm = "farm.cli:main"

Чтобы запускать утилиту просто как farm add Босс 40, в pyproject.toml описывают точку входа ([project.scripts]: имя команды = модуль и функция main), а потом ставят проект в своё окружение: pip install -e .. Функция main при этом должна возвращать код выхода, как мы делали. Отправить проект другим можно на сайт PyPI, откуда его ставят командой pip install имя. На своём компьютере попробуй этот шаг, когда у тебя будет готовая утилита, а в песочнице он не нужен.

Чек-лист утилиты

  • Справка (-h) объясняет, что делает программа и каждая команда.
  • Результат идёт в stdout, ошибки и предупреждения в stderr, код выхода говорит об успехе.
  • Ошибки пользователя (нет файла, неверный формат) заканчиваются понятным сообщением, а не трассировкой.
  • Опасные действия (удаление, перезапись) умеют «сухой» режим --dry-run или просят подтверждения.
  • Журнал (--verbose) включается по просьбе: обычно он не нужен, а при поломке очень помогает.
  • Логика отделена от интерфейса и проверена тестами.

🧪 Попробуй сам

★★★

🎯 Задача: Дневник смолы

10 очков

Напиши в файле farm.py утилиту «дневник смолы». Её запускают как отдельную программу: python farm.py add Босс 40. Данные хранятся в файле farm.json в текущей папке (словарь «место → сумма») и должны переживать запуски.

Команды:

  • add МЕСТО СМОЛА — прибавить смолу (целое число) к месту; печатает Записано: МЕСТО +СМОЛА;
  • total — печатает Всего потрачено: <сумма по всем местам>;
  • top — печатает Больше всего: МЕСТО (СУММА); при равных суммах выигрывает место, раньше стоящее по алфавиту; если записей нет, печатает Записей нет.

При неверных аргументах программа должна завершаться с кодом 2 (это делает argparse). Функция main(argv=None) возвращает код выхода, а запуск оформлен как sys.exit(main()) под проверкой __name__.

Файл main.py менять не нужно: он запускает farm.py отдельным процессом для каждой команды из ввода, печатает всё, что программа вывела, и добавляет [код N], если код выхода не нулевой. Первая строка ввода — число команд.

Пример. Ввод:

5
add Подземелье 20
add Босс 40
add Подземелье 20
total
top

Вывод:

Записано: Подземелье +20
Записано: Босс +40
Записано: Подземелье +20
Всего потрачено: 80
Больше всего: Босс (40)

Заготовка (кнопка у блока отправит её в песочницу):

import shlex
import subprocess
import sys

for _ in range(int(input())):
    command = shlex.split(input())
    result = subprocess.run([sys.executable, "farm.py", *command], capture_output=True, text=True)
    if result.stdout.strip():
        print(result.stdout.strip())
    if result.returncode != 0:
        print(f"[код {result.returncode}]")
★★★

🎯 Задача: Журнал заходов

25 очков

Напиши в файле journal.py утилиту «журнал заходов»: она запоминает, когда и сколько смолы потрачено, в базе SQLite journal.db (таблица runs: moment, place, resin). Запускают её отдельными процессами: python journal.py add Босс 40 --at "2026-11-15 10:30".

Команды:

  • add МЕСТО СМОЛА --at "ГГГГ-ММ-ДД ЧЧ:ММ" — добавить запись. --at обязателен; если время записано неверно, программа должна завершиться с кодом 2 и ничего не добавить (проверку сделай через type= у аргумента). Печатает Записано;
  • day ГГГГ-ММ-ДД — печатает <дата>: записей <сколько>, смолы <сумма> (если записей нет, обе цифры равны 0); неверная дата — код 2;
  • export — печатает все записи в формате CSV: сначала строка moment,place,resin, затем записи по возрастанию времени, при равном времени по месту. Время в таблице хранится в виде ГГГГ-ММ-ДД ЧЧ:ММ. Названия мест с запятыми csv заключает в кавычки сам.

Функция main(argv=None) возвращает код выхода, запуск оформлен как sys.exit(main()) под проверкой __name__.

Файл main.py менять не нужно: он запускает journal.py отдельным процессом для каждой команды из ввода и печатает всё, что программа вывела, добавляя [код N], если код выхода не нулевой.

Пример. Ввод:

4
add Босс 40 --at "2026-11-15 10:30"
add "Дикий кабан, север" 20 --at "2026-11-15 09:00"
day 2026-11-15
export

Вывод:

Записано
Записано
2026-11-15: записей 2, смолы 60
moment,place,resin
2026-11-15 09:00,"Дикий кабан, север",20
2026-11-15 10:30,Босс,40

Заготовка (кнопка у блока отправит её в песочницу):

import shlex
import subprocess
import sys

for _ in range(int(input())):
    command = shlex.split(input())
    result = subprocess.run([sys.executable, "journal.py", *command], capture_output=True, text=True)
    if result.stdout.strip():
        print(result.stdout.strip())
    if result.returncode != 0:
        print(f"[код {result.returncode}]")

✅ Что мы узнали

Хорошая утилита делится на логику, хранение и интерфейс; её main(argv=None) возвращает код выхода, данные между запусками лежат в файле или базе (лучше в папке пользователя), а справка, сообщения об ошибках и «сухой» режим делают её удобной. Папка с __main__.py запускается как python -m имя, а точка входа в pyproject.toml превращает её в команду.

Так мы прошли раздел про утилиты: аргументы, команды, файлы, запуск программ, шаблоны, время, перебор и базы данных.

⟵ Связываем таблицы и защищаем изменения К содержанию ⟶