CupDefs

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

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

Модуль init

---

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

from CupDefs import init
init.init()

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

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

Прочие строки и/или значения ни к чему не приведут.

Функция init также возвращает True, если инициализация была успешной, иначе - False

Логирование

Модуль logger

---

Класс LogType

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

Значения:ф

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

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

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

Класс Logger

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

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

() -> bool

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

Если указана пустая строка или None, то в качестве пути будет использована строка “./last_launch.log”, что создаст файл лога в папке с исполняемым файлом

from CupDefs import logger

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

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

(log_type, text: str) -> None

Функция принимает одно из значений класса LogType и строку, которая будет записана в логи.

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

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 и строку, которая будет записана в логи.
Запись происходит только если аргумент condition является истинным или вызываемый объект возвращает истину.

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

close_logs

() -> bool

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

Формат логов

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

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

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

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

---

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

Если функция инициализации достигнет лимита файлов для хеширования, то она завершиться досрочно и вернет False, в противном случае True. В обоих случаях инициализация будет считаться успешной.

Функция generate

() -> str | None

Функция генерирует номер сборки.

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

from CupDefs import vergen
from CupDefs import utils

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

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

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

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

“Цифры”

Алгоритм их генерации основан на методе нумерации сборок игры S.T.A.L.K.E.R.

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

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:

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-арта.
Если аргумент colorize истинный, то будет выведена цветная версия, иначе - бесцветная.
Логотип также выводится при вызове функции инициализации модуля init, если не был передан флаг “no_logo”.

Функция get_code_dir

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

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

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

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

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

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

Пример:

# 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, если не была произведена инициализация.
Инициализация устанавливает команду очистки консоли в зависимости от ОС. Для 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