advpyneng-cli-course 1.1
CLI tool for running advpyneng tests
License: MIT

## apyneng

### Установка и запуск

Установить модуль

```
pip install advpyneng-cli-course
```

После этого проверка заданий вызывается через утилиту apyneng в CLI.

### Этапы работы с заданиями

1. Выполнение заданий
2. Проверка, что задание отрабатывает как нужно ``python task_4_2.py`` или запуск скрипта в редакторе/IDE
3. Проверка заданий тестами ``apyneng 1-5``
4. Сдача заданий на проверку ``apyneng 1-5 -c`` 


> Второй шаг очень важен, потому что на этом этапе намного проще найти ошибки в синтаксисе
> и подобные проблемы с работой скрипта, чем при запуске кода через тест на 3 этапе.

## Проверка заданий тестами

После выполнения задания, его надо проверить с помощью тестов.
Для запуска тестов, надо вызвать apyneng в каталоге заданий.
Например, если вы делаете 4 раздел заданий, надо находиться в каталоге exercises/04_data_structures/
и запустить apyneng одним из способов, в зависимости от того какие задания на проверять.

[Примеры вывода тестов с пояснениями](/docs/pyneng-output/)

Запуск проверки всех заданий текущего раздела:

```
pyneng
```

Запуск тестов для задания 4.1:

```
apyneng 1
```

Запуск тестов для заданий 4.1, 4.2, 4.3:

```
apyneng 1-3
```

Если есть задания с буквами, например, в 7 разделе, можно запускать так,
 чтобы запустить проверку для заданий 7.2a, 7.2b (надо находиться в каталоге 07_files):

```
apyneng 2a-b
```

или так, чтобы запустить все задания 7.2x с буквами и без:

```
apyneng 2*
```


## Сдача заданий на проверку

> Для сдачи задания на проверку, надо сгенерировать токен на Github.
> Как это сделать написано в инструкции [Подготовка к работе с заданиями](/docs/pyneng-prepare/)

После того как задания прошли тесты и вы посмотрели варианты решения заданий,
можно сдавать задания на проверку.

Для этого надо добавить ``-c`` к вызову pyneng:
Такой вызов значит запустить тесты для заданий 1 и 2 и сдать их на проверку, если тесты прошли:

```
apyneng 1-2 -c
```

Запустить тесты для всех заданий и сдать их на проверку, если тесты прошли:

```
apyneng -c
```

При добавлении ``-c`` apyneng делает git add файлам заданий, которые прошли тесты, делает commit,
и git push. После этого пишет комментарий на github, что задания такие-то сданы на проверку.
 
Запустить тесты и сдать на проверку задания,
которые прошли тесты, но при этом загрузить на github все изменения
в текущем каталоге:

```
apyneng 1-5 -c --all
```

## Загрузить все изменения в текущем каталоге на github, без привязки к тому проходят ли тесты

```
apyneng --save-all
```

Выполняет команды
```
git add .
git commit -m "Все изменения сохранены"
git push origin main
```

## Обновление разделов

В apyneng есть два варианта обновления: обновлять разделами или конкретные
задания/тесты.  При обновлении раздела, каталог раздела удаляется и копируется
новая версия. Это подходит только для тех разделов, которые вы еще не начинали
выполнять. Если надо обновить конкретное задание, лучше использовать обновление
конкретных заданий (рассматривается дальше).

Перед любым вариантом обновления желательно сохранить все локальные изменения
на github!

Для обновления разделов, надо перейти в каталог online-x-имя-фамилия/exercises/
и дать команду:

```
apyneng --update-chapters 12-25
```

В этом случае обновятся разделы 12-25. Также можно указывать один раздел:

```
apyneng --update-chapters 11
```

Или несколько через запятую

```
apyneng --update-chapters 12,15,17
```

## Обновление заданий и тестов

В заданиях и тестах встречаются неточности и чтобы их можно было исправить,
apyneng добавлена опция ``--update``.

Общая логика:

* задания и тесты копируются из репозитория https://github.com/pyneng/pyneng-course-tasks
* копируется весь файл задания, не только описание, поэтому файл перепишется
* перед выполнением --update, лучше созранить все изменения на github

Как работает --update

* если в репозитории есть несохраненные изменения
  * утилита предлагает их сохранить (сделает ``git add .``, ``git commit``, ``git push``)
* если несохраненных изменений нет, копируются указанные задания и тесты
* утилита предлагает сохранить изменения и показывает какие файлы изменены, но не какие именно сделаны изменения
* можно отказаться сохранять изменения и посмотреть изменения git diff

#### Варианты вызова

Обновить все задания и тесты раздела:

```
apyneng --update
```

Обновить все тесты раздела (только тесты, не задания):

```
apyneng --update --test-only
```

Обновить задания 1,2 и соответствующие тесты раздела

```
apyneng 1,2 --update
```

Если никаких обновлений нет, будет такой вывод

```
$ apyneng --update
#################### git pull
Already up-to-date.


Обновленные задания и тесты скопированы
Задания и тесты уже последней версии
Aborted!
```

В любой момент можно прервать обновление Ctrl-C.

Пример вывода с несохраненными изменениями и наличием обновлений
```
apyneng --update
ОБНОВЛЕНИЕ ТЕСТОВ И ЗАДАНИЕ ПЕРЕЗАПИШЕТ СОДЕРЖИМОЕ НЕСОХРАНЕННЫХ ФАЙЛОВ!
В текущем каталоге есть несохраненные изменения! Хотите их сохранить? [y/n]: y
#################### git add .
#################### git commit -m "Сохранение изменений перед обновлением заданий"
[main 0e8c1cb] Сохранение изменений перед обновлением заданий
 1 file changed, 1 insertion(+)

#################### git push origin main
To git@github.com:pyneng/online-14-natasha-samoylenko.git
   fa338c3..0e8c1cb  main -> main

Все изменения в текущем каталоге сохранены. Начинаем обновление...
#################### git pull
Already up-to-date.


Обновленные задания и тесты скопированы
Были обновлены такие файлы:
#################### git diff --stat
 exercises/04_data_structures/task_4_0.py |  0
 exercises/04_data_structures/task_4_1.py |  1 -
 exercises/04_data_structures/task_4_3.py |  3 ---
 3 files changed, 0 insertions(+), 4 deletions(-)


Это короткий diff, если вы хотите посмотреть все отличия подробно, нажмите n и дайте команду git diff.
Также при желании можно отменить внесенные изменения git checkout -- file (или git restore file).

Сохранить изменения и добавить на github? [y/n]: n
Задания и тесты успешно обновлены
Aborted!
`-``