Metadata-Version: 2.1
Name: CupDefs
Version: 1.6
Author-email: Savtis <nihyisebe@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: colorama

# 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**, то запись в логи не произойдёт
> и будет выведено [сообщение об ошибке](#модуль-vars).

```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**, то запись в логи не произойдёт
> и будет выведено [сообщение об ошибке](#модуль-vars).

### 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)**
> Если функция инициализации достигнет лимита файлов для хеширования, то она завершиться досрочно и вернет False,
> в противном случае True. В обоих случаях инициализация будет считаться успешной.

### Функция generate

### () -> str | None

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

```python
from CupDefs import vergen
from CupDefs import utils

utils.get_code_dir('C')  # меняем текущую директорию на директорию кода, на основе которого будет генерироваться версия
#  см. модуль utils

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

### Функция get_code_dir

### (mode: str, add: str | None = '') -> str

Функция позволяет получить расположение скрипта, в котором она была вызвана.
Первый аргумент принимает в себя строку, состоящую из определенных букв,
каждая буква меняет поведение функции как указано в таблице:

| Буква | Значение                                                                                                         |
|-------|------------------------------------------------------------------------------------------------------------------|
| `'C'` | Меняет текущую рабочую папку программы на директорию расположения скрипта (**вместе с** *дополнительным путём*). |
| `'A'` | Добавляет директорию скрипта в sys.path (**вместе с** *дополнительным путём*).                                   |
| `'W'` | Функция вернет директорию скрипта **без** добавления дополнительного пути.                                       |

> Регистр символов не важен. Любые символы, не присутствующие в таблице выше, будут проигнорированы.
> Также, если вызвать функцию с флагом `'C'` и дополнительным путём, указывающим на файл, то это приведёт к исключению.

Второй аргумент - *дополнительный путь* который будет добавлен в конец пути директории скрипта, может указывать как на
папку, так и на файл

По-умолчанию, функция возвращает путь до директории скрипта + *добавочный путь*

Пример:

```python

# file home/project/test.py

from CupDefs import utils

utils.get_code_dir('')  # home/project
utils.get_code_dir('', 'meme/')  # home/project/meme/
utils.get_code_dir('W', 'meme/')  # home/project
```

### Функция clear

### () -> None

Очищает экран консоли, используя команду `clear`, если не была произведена инициализация.<br>
Инициализация устанавливает команду очистки консоли в зависимости от ОС. Для Windows - `cls`, для всех
остальных `clear`.
Инициализация происходит при вызове [функции инициализации модуля init](#инициализация).

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

## Модуль vars

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

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


