# CupDefs

## Пространства имён (файлы):

## Инициализация

### Модуль init

------

Инициализация выполняется функцией *init(\*args)* модуля **init**

``` python
from CupDefs import init
init.init()
```

Функция init принимает неограниченное кол-во аргументов.
Передача некоторых строк позволяет настроить инициализацию.<br>
Список строк:

* "no_color" - отключает инициализацию модуля colorama и цветной вывод
* "no_vergen" - отключает инициализацию генератора номера сборки
* "no_logo" - отключает вывод логотипа

Прочие строки и/или значения ни к чему не приведут.<br>
> Функция *init* также возвращает True, если инициализация была успешной, иначе - False

## Логирование

### Модуль logger

-----

### Класс LogType

Нужен для указания типа записи в логах.

Значения:

| Имя поля | Цвет лога | Смысл             | Префикс в логах |
|----------|-----------|-------------------|:---------------:|
| DONE     | Зелёный   | Успех             |      [OK ]      |
| ERROR    | Красный   | Ошибка            |      [ERR]      |
| WARNING  | Жёлтый    | Предупреждение    |      [WRN]      |
| INFO     | Голубой   | Прочая информация |      [INF]      |

Значения, по-факту, представляют собой функции цветного вывода модуля **utils** и *являются вызываемыми объектами*

``` python
from CupDefs import logger
logger.LogType.DONE  # этот тип лога обозначает успешно выполненную задачу
```

### Класс Logger

Нужен для ведения логов во время выполнения программы.

### Статическая функция init_logs

### () -> bool

Инициализирует модуль ведения логов.<br>
В качестве аргумента принимает строку или None. Строка обозначает путь до файла, куда будут записаны логи.
Если файл, уже существует, то он будет очищен, если нет, то будет создан.
В случае успеха возвращает True, иначе - False.
> Если указана пустая строка или None, то в качестве пути будет использована строка "./last_launch.log",
> что создаст файл лога в папке с исполняемым файлом

```python
from CupDefs import logger

logger.Logger.init_logs('example.log')  # создаст файл лога с именем example.log
```

### Статическая функция mklog

### (log_type, text: str) -> None

Функция принимает одно из значений класса **LogType** и строку, которая будет записана в логи.
> Если не была вызвана функция **init_logs**, то запись в логи не произойдёт
> и будет выведено [сообщение об ошибке](#REPLACE1).

```python
from CupDefs import logger
from CupDefs import init

init.init()  # инициализация

logger.Logger.init_logs('example.md')
logger.Logger.mklog(logger.LogType.DONE, 'ОШИБОЧКА ПРОИЗОШЛА!')
logger.Logger.mklog(logger.LogType.INFO, 'кстати, вот инфа')
logger.Logger.mklog(logger.LogType.WARNING, 'тут проблема...')
```

### Статическая функция mklogif

### (condition: bool | typing.Callable, log_type, text: str) -> None

Функция принимает в первый аргумент булево значение или вызываемый объект (*напр. Функция*), затем она принимает
одно из значений класса **LogType** и строку, которая будет записана в логи.<br>
Запись происходит только если аргумент *condition* является истинным или вызываемый объект возвращает истину.
> Если не была вызвана функция **init_logs**, то запись в логи не произойдёт
> и будет выведено [сообщение об ошибке](#REPLACE1).

### close_logs

### () -> bool

Закрывает файл логов. Чтобы снова иметь возможность осуществлять запись -
требуется снова вызвать функцию [init_logs](#статическая-функция-init_logs)
В случае успеха возвращает True, иначе - False.

### Формат логов

```text
<префикс>[день.месяц.год-час:минута:секунда] <сообщения лога>

пример:
[OK ][28.08.24-17:54:16] Операция завершилась успешно.
```

Время в логах указывается по UTC. 24-часовой формат. Год указывается без 2000. Числа **выравниваются** нулями слева.

## Генератор номера сборки

-----
Инициализация генератора номера сборки происходит путём вызова *init_vergen()*,
если он до этого не был инициализирован функцией *init* модуля **[init](#модуль-init)**

### Функция generate

### () -> str | None

Функция генерирует номер сборки.
> Если генератор не был инициализирован, то функция будет выводить надпись об ошибке и возвращать None,
> если же всё прошло успешно, то функция вернет сгенерированный номер сборки.

```python
from CupDefs import vergen

vergen.init_vergen()
result = vergen.generate()
# (случайный пример)
print(result)  # 2342bf0c
```

## Алгоритм вычисления номера сборки

Генерируемый номер сборки состоит из двух частей: **цифры** и **4 символа**

### "Цифры"

Алгоритм их генерации основан
на [методе нумерации сборок](https://stalker-game.fandom.com/ru/wiki/Принцип_нумерации_сборок) игры S.T.A.L.K.E.R.

Оригинальный алгоритм:

```python
days = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 303, 334, 365]  # число дней с начала года
m = 6  # 0 <= m <= 11
y = 2009
d = 25
num = 365 * (y - 1999) - 31 + days[m] + d  # результат: 3825
```

Алгоритм, используемый в CupDefs:

```python
days = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 303, 334, 365]  # число дней с начала года
m = 7  # 1 <= m <= 12
y = 2023
d = 25
num = 365 * (y - 2020) - 31 + days[(m - 1)] + d  # результат: 1270
```

В обоих случаях,

* y - текущий год
* m - текущий месяц
* d - текущий день

### "4 символа"

Вычисляются по следующему принципу:

1. Ищутся все файлы, начиная с директории, указанной в vars.VERGEN_HASH_PATH, и далее рекурсивно.
2. Происходит вычисление хеша всех файлов по их содержимому.
3. Все полученные хеши соединяются в одну строку и вычисляется конечный хеш.

После чего "цифры" и "4 символа соединяются", что и является конечным результатом.

## Утилиты

## Модуль utils

-----
Этот модуль содержит различные вспомогательные функции, которые используются пакетом CupDefs,
а также их можно использовать и отдельно.

### Функции pdone, pwarn, perror, pinfo

### (text: str) -> None

Функции выводят цветной текст. Вывод происходит с переносом на новую строку.

| Имя функции | Цвет текста |
|-------------|-------------|
| pdone       | Зелёный     |
| perror      | Красный     |
| pwarn       | Жёлтый      |
| pinfo       | Голубой     |

> Если была вызвана [функция инициализации модуля init](#инициализация) с флагом "no_color" то,
> вывод этих функций **не будет** цветным.

### Функция print_logo

### (colorize: bool) -> None

Функция выводит логотип Cuplarax в виде ASCII-арта.<br>
Если аргумент colorize истинный, то будет выведена цветная версия, иначе - бесцветная.<br>
Логотип также выводится при вызове [функции инициализации модуля init](#инициализация), если не был передан флаг
"no_logo".

## Переменные

## Модуль vars

----
Модуль содержит переменные, которые отвечают за поведение некоторых функций.

| Имя переменной   | Тип  | Назначение                                                         | Значение по-умолчанию |
|------------------|------|--------------------------------------------------------------------|-----------------------|
| AUTO_PRINT_ERROR | bool | Выводить ли сообщения об ошибках CupDefs или нет                   | True                  |
| PRINT_LOGS_CLI   | bool | Выводить ли в консоль сообщения, которые записываются в логи       | True                  |
| VERGEN_HASH_SIZE | int  | Размер конечного хеша                                              | 2                     |
| VERGEN_HASH_PATH | str  | Корневая директория, откуда будут браться файлы для генерации хеша | "."                   |

