EJIO.utils.system package

Submodules

EJIO.utils.system.crypto module

EJIO.utils.system.crypto.decrypt_payload(cipher_data: bytes, key: str) → bytes

Расшифровывает поток байт и проверяет его целостность.

Параметры:

• cipher_data – Зашифрованные данные.

• key – Ключ шифрования.

Результат:

Расшифрованные данные.

Исключение:

CryptographyError – Если ключ не подходит или файл был поврежден/модифицирован.

EJIO.utils.system.crypto.encrypt_payload(data: bytes, key: str) → bytes

Шифрует поток байт с помощью крипто-стандарта AES/HMAC (Fernet). Полностью защищает файл от десериализации и анализа.

Параметры:

• data – Данные для шифрования.

• key – Ключ шифрования.

Результат:

Зашифрованные данные.

Raises:

CryptographyError если произошла ошибка шифрования.

EJIO.utils.system.crypto.generate_secure_key() → str

Генерирует криптографически стойкий случайный ключ безопасности (URL-safe Base64).

Результат:

Ключ шифрования.

EJIO.utils.system.err module

exception EJIO.utils.system.err.CryptographyError(message: str)

Базовые классы: UtilsBaseError

Исключение, связанное с ошибками криптографии.

exception EJIO.utils.system.err.LocalizationError(message: str)

Базовые классы: UtilsBaseError

Исключение, связанное с ошибками локализации.

EJIO.utils.system.file_utils module

EJIO.utils.system.file_utils.change_cwd(target_path: str | Path) → Generator[Path, None, None]

Контекстный менеджер для временной смены текущей рабочей директории (CWD). По завершении блока кода или при возникновении исключения гарантированно возвращает рабочую папку в исходное состояние.

Пример использования: with change_cwd(«./resources»):

# Код выполняется внутри папки resources open(«theme.json», «r»)

Параметры:

target_path – Путь к директории.

Yields:

Путь к директории.

EJIO.utils.system.file_utils.generate_timestamped_filename(base_name: str, extension: str, prefix_date: bool = False) → str

Генерирует имя файла, интегрируя текущую дату и время в безопасном формате ISO.

Пример: generate_timestamped_filename(«report», «json») Результат: «report_20260621_153045.json»

Параметры:

• base_name – Базовое имя файла (например, „backup“, „log“).

• extension – Расширение файла без точки (например, „txt“, „csv“).

• prefix_date – Если True, дата-время встанет в начало: „20260621_153045_report.json“.

Результат:

Строка с уникальным именем файла.

EJIO.utils.system.file_utils.rotate_and_save(target_path: str | Path, max_backups: int, write_callback: Callable[[Path], None]) → None

Управляет ротацией бэкапов файла по индексам (file.1.ext, file.2.ext) и атомарно сохраняет новое состояние под основным именем.

Параметры:

• target_path – Путь к основному файлу (например, „config.json“).

• max_backups – Максимальное количество удерживаемых файлов бэкапа (>= 1).

• write_callback – Функция-коллбэк для безопасной записи нового файла.

EJIO.utils.system.file_utils.save_atomic(target_path: str | Path, write_callback: Callable[[Path], None]) → None

Выполняет транзакционную (атомарную) запись в файл через скрытый временный файл. Гарантирует, что оригинальный файл не будет поврежден в случае сбоя программы или ОС.

Параметры:

• target_path – Целевой путь к файлу (куда нужно сохранить итог).

• write_callback – Функция-коллбэк, принимающая Path временного файла, куда нужно писать данные.

EJIO.utils.system.hardware module

class EJIO.utils.system.hardware.HardwareProperties(*args: tuple[object, ...], **kwargs: dict[str, object])

Базовые классы: object

Неизменяемая структура рантайм-сведений об аппаратном обеспечении (Железе). Полностью кроссплатформенна, работает через Си-вызовы и парсинг системных утилит.

classmethod clear() → None

cpu_cores = 2

cpu_model = 'AMD EPYC 9V74 80-Core Processor'

classmethod destroy() → None

gpu_model = 'Integrated Graphics Controller'

motherboard = 'Microsoft Corporation Virtual Machine'

ram_total_gb = 8

storage_drives = [{'device': '/dev/nvme0n1', 'size_gb': 75, 'type': 'SSD'}]

EJIO.utils.system.introspection module

EJIO.utils.system.introspection.get_class_hierarchy(base_class: type) → dict[str, Any]

Рекурсивно строит дерево иерархии классов (наследников) для указанного базового класса. Помогает отслеживать и инспектировать структуру всех зарегистрированных компонентов.

Пример вывода: {

„WidgetContainer“: {

„Form“: {}, „Layout“: {}, „Tabview“: {}

}

}

Параметры:

base_class – Базовый класс (например, Widget, Event, Window).

Результат:

Словарь, представляющий дерево наследования.

EJIO.utils.system.introspection.import_module_from_path(file_path: str | Path) → ModuleType

Динамически импортирует и регистрирует в системе Python-модуль (скрипт) по его абсолютному или относительному пути в файловой системе. Полезно для построения систем плагинов и аддонов.

Параметры:

file_path – Имя файла или путь к .py скрипту.

Результат:

Объект импортированного модуля (ModuleType).

Исключение:

• FileNotFoundError – Если модуля по указанному пути не существует.

• ImportError – Если загрузка модуля не получилась.

EJIO.utils.system.introspection.measure_time(func: F, /) → F

EJIO.utils.system.introspection.measure_time() → Callable[[Any], Any]

Декоратор для измерения времени выполнения функции с использованием loguru.

Логирует результат на уровне DEBUG, подменяя контекст на вызываемую функцию.

Поддерживает вызов как со скобками, так и без них: @measure_time @measure_time()

Параметры:

func – Функция время выполнения которой нужно измерить или None, в случае вызова как декоратора со скобками.

Результат:

Декоратор ввыполняющий измерение времени выполнения указанной функции.

EJIO.utils.system.introspection.print_class_hierarchy(hierarchy: dict[str, Any], indent: str = '', project_only: bool = True) → None

Красиво выводит древовидный словарь иерархии классов в терминал с отступами-ветвями.

Пример вывода: ├── WidgetContainer │ ├── Form │ └── Layout └── Button

Параметры:

• hierarchy – Словарь предстваляющий иерархию пректа, собранную через get_class_hierarchy или scan_package_classes

• indent – разделитель между ветвями

• project_only – Если True, скрывает системные модули Python, выводя только классы вашего фреймворка/приложения.

EJIO.utils.system.introspection.profile_function(file_name: F, /) → F

EJIO.utils.system.introspection.profile_function(file_name: str | None = None, /) → Callable[[F], F]

Декоратор для создания профиля функции.

Записывает профиль в файл, или выводит в консоль, если файл не задан.

Поддерживает вызов как со скобками, так и без них: @profile_function @profile_function(«profile.prof»)

Просмотреть профиль можно выполнив tuna file_name в консоли

Параметры:

file_name – Имя файла для сохранения профиля функции.

Результат:

Декоратор выполняющий профилирование указанной функции.

EJIO.utils.system.introspection.retry(*exceptions: type[BaseException], tries: int = 3, delay: float = 0.1) → Callable[[Callable[[P], R]], Callable[[P], R]]

Декоратор для повторного выполнения функции при возникновении ошибок.

Можно использовать как @retry, @retry(ValueError) или @retry(ValueError, TypeError, tries=5).

Параметры:

• exceptions – Перечень исключений, при которых нужен повтор. Если не передано, перехватывает любое исключение (Exception).

• tries – Количество попыток выполнения функции, по умолчанию 3.

• delay – Задержка между попытками в секундах, по умолчанию 0.1.

Результат:

Декорированная функция с поддержкой повторных попыток.

Исключение:

BaseException – Последнее пойманное исключение, если все попытки исчерпаны.

EJIO.utils.system.introspection.run_on_import(func: Callable[[P], R]) → Callable[[P], R]

Декоратор для автоматического запуска функции в момент импорта модуля.

Функция вызывается без аргументов сразу при инициализации файла.

Параметры:

func – Декорируемая функция, не должна требовать обязательных аргументов.

Результат:

Исходная функция для возможности последующих ручных вызовов.

EJIO.utils.system.introspection.scan_package_classes(package_name: str, base_class: type = <class 'object'>) → dict[str, Any]

Сканирует все подмодули указанного пакета, используя встроенный механизм pkgutil. Автоматически и корректно разрешает относительные импорты (relative imports), загружая модули с учетом их полного родительского контекста. Сканирует все .py файлы в указанной директории пакета, принудительно импортирует их в память Python, после чего строит и возвращает полную иерархию классов для base_class.

Параметры:

• package_name – Имя импортированного пакета.

• base_class – Базовый класс, иерархию которого нужно собрать.

Результат:

Словарь дерева иерархии классов.

Исключение:

• ImportError – При ошибке импорта корневого пакета.

• ValueError – Если указанный пакет не является пакетом.

EJIO.utils.system.localization module

class EJIO.utils.system.localization.Localization(*args: tuple[object, ...], **kwargs: dict[str, object])

Базовые классы: StaticClass, Disposable

Глобальный статический менеджер локализации (i18n). Хранит словари переводов и обеспечивает рантайм-доступ к фразам.

classmethod clear() → None

Потокобезопасно очищает все загруженные переводы и сбрасывает локаль.

current_locale: str = 'en'

classmethod destroy() → None

Потокобезопасно очищает все загруженные переводы и сбрасывает локаль.

classmethod get(key_path: str, default: str | None = None) → str

Извлекает фразу по иерархическому пути через точку. Пример: Localization.get(«auth.login_btn»)

Параметры:

• key_path – Путь к ключу (например, „main_menu.profile.title“).

• default – Значение по умолчанию, если ключ не найден.

Результат:

Значение, установленное по данному ключу.

classmethod initialize() → None

Автоматическая инициализация дефолтного системного языка.

classmethod load_from_dict(locale: str, data: dict[str, Any]) → None

Загружает словарь переводов. Безопасно выполняет глубокое рекурсивное слияние, если ключи (например, „ERRORS“) пересекаются в разных модулях.

Параметры:

• locale – Локаль, данные для которой нужно установить.

• data – Словарь с данными, которые необходимо загрузить.

classmethod load_from_json(locale: str, file_path: str | Path) → None

Загружает переводы из внешнего JSON-файла.

Параметры:

• locale – Локаль, данные для которой нужно установить.

• file_path – Путь к файлу со словарем с данными, которые необходимо загрузить.

classmethod set_locale(locale: str) → None

Переключает текущий активный язык приложения в рантайме.

Параметры:

locale – Локаль которую необходимо установить.

Исключение:

LocalizationError – Если данная локаль не инициализированна.

EJIO.utils.system.paths module

class EJIO.utils.system.paths.SystemPaths(*args: tuple[object, ...], **kwargs: dict[str, object])

Базовые классы: object

Неизменяемая структура системных путей только для чтения. Корректно работает на Windows, Linux и macOS.

app_cache = PosixPath('/home/runner/.cache')

app_data = PosixPath('/home/runner/.config')

classmethod clear() → None

Реализация контракта Disposable..

desktop = PosixPath('/home/runner/Desktop')

classmethod destroy() → None

Реализация контракта Disposable.

documents = PosixPath('/home/runner/Documents')

temp = PosixPath('/tmp')

user_home = PosixPath('/home/runner')

EJIO.utils.system.paths.get_app_root() → Path

Возвращает абсолютный путь к корневой папке, где запущен главный файл приложения. Надежно работает как при обычном запуске скрипта, так и при сборке через PyInstaller.

Результат:

Путь к корню программы.

EJIO.utils.system.properties module

class EJIO.utils.system.properties.SystemProperties(*args: tuple[object, ...], **kwargs: dict[str, object])

Базовые классы: object

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

classmethod clear() → None

Реализация контракта Disposable..

cpu_count = 2

date_format = '%m/%d/%y'

classmethod destroy() → None

Реализация контракта Disposable.

is_64bit = True

language = 'C'

os = 'linux'

os_release = '6.17.0-1022-azure'

python_version = '3.12.14'

screen_height = 1080

screen_width = 1920

theme = 'light'

timezone = zoneinfo.ZoneInfo(key='Etc/UTC')

timezone_name = 'UTC'

user_home = PosixPath('/home/runner')

user_name = 'runner'

Module contents

class EJIO.utils.system.HardwareProperties(*args: tuple[object, ...], **kwargs: dict[str, object])

Базовые классы: object

Неизменяемая структура рантайм-сведений об аппаратном обеспечении (Железе). Полностью кроссплатформенна, работает через Си-вызовы и парсинг системных утилит.

classmethod clear() → None

cpu_cores = 2

cpu_model = 'AMD EPYC 9V74 80-Core Processor'

classmethod destroy() → None

gpu_model = 'Integrated Graphics Controller'

motherboard = 'Microsoft Corporation Virtual Machine'

ram_total_gb = 8

storage_drives = [{'device': '/dev/nvme0n1', 'size_gb': 75, 'type': 'SSD'}]

class EJIO.utils.system.Localization(*args: tuple[object, ...], **kwargs: dict[str, object])

Базовые классы: StaticClass, Disposable

Глобальный статический менеджер локализации (i18n). Хранит словари переводов и обеспечивает рантайм-доступ к фразам.

classmethod clear() → None

Потокобезопасно очищает все загруженные переводы и сбрасывает локаль.

current_locale: str = 'en'

classmethod destroy() → None

Потокобезопасно очищает все загруженные переводы и сбрасывает локаль.

classmethod get(key_path: str, default: str | None = None) → str

Извлекает фразу по иерархическому пути через точку. Пример: Localization.get(«auth.login_btn»)

Параметры:

• key_path – Путь к ключу (например, „main_menu.profile.title“).

• default – Значение по умолчанию, если ключ не найден.

Результат:

Значение, установленное по данному ключу.

classmethod initialize() → None

Автоматическая инициализация дефолтного системного языка.

classmethod load_from_dict(locale: str, data: dict[str, Any]) → None

Загружает словарь переводов. Безопасно выполняет глубокое рекурсивное слияние, если ключи (например, „ERRORS“) пересекаются в разных модулях.

Параметры:

• locale – Локаль, данные для которой нужно установить.

• data – Словарь с данными, которые необходимо загрузить.

classmethod load_from_json(locale: str, file_path: str | Path) → None

Загружает переводы из внешнего JSON-файла.

Параметры:

• locale – Локаль, данные для которой нужно установить.

• file_path – Путь к файлу со словарем с данными, которые необходимо загрузить.

classmethod set_locale(locale: str) → None

Переключает текущий активный язык приложения в рантайме.

Параметры:

locale – Локаль которую необходимо установить.

Исключение:

LocalizationError – Если данная локаль не инициализированна.

class EJIO.utils.system.SystemPaths(*args: tuple[object, ...], **kwargs: dict[str, object])

Базовые классы: object

Неизменяемая структура системных путей только для чтения. Корректно работает на Windows, Linux и macOS.

app_cache = PosixPath('/home/runner/.cache')

app_data = PosixPath('/home/runner/.config')

classmethod clear() → None

Реализация контракта Disposable..

desktop = PosixPath('/home/runner/Desktop')

classmethod destroy() → None

Реализация контракта Disposable.

documents = PosixPath('/home/runner/Documents')

temp = PosixPath('/tmp')

user_home = PosixPath('/home/runner')

class EJIO.utils.system.SystemProperties(*args: tuple[object, ...], **kwargs: dict[str, object])

Базовые классы: object

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

classmethod clear() → None

Реализация контракта Disposable..

cpu_count = 2

date_format = '%m/%d/%y'

classmethod destroy() → None

Реализация контракта Disposable.

is_64bit = True

language = 'C'

os = 'linux'

os_release = '6.17.0-1022-azure'

python_version = '3.12.14'

screen_height = 1080

screen_width = 1920

theme = 'light'

timezone = zoneinfo.ZoneInfo(key='Etc/UTC')

timezone_name = 'UTC'

user_home = PosixPath('/home/runner')

user_name = 'runner'

EJIO.utils.system.change_cwd(target_path: str | Path) → Generator[Path, None, None]

Контекстный менеджер для временной смены текущей рабочей директории (CWD). По завершении блока кода или при возникновении исключения гарантированно возвращает рабочую папку в исходное состояние.

Пример использования: with change_cwd(«./resources»):

# Код выполняется внутри папки resources open(«theme.json», «r»)

Параметры:

target_path – Путь к директории.

Yields:

Путь к директории.

EJIO.utils.system.decrypt_payload(cipher_data: bytes, key: str) → bytes

Расшифровывает поток байт и проверяет его целостность.

Параметры:

• cipher_data – Зашифрованные данные.

• key – Ключ шифрования.

Результат:

Расшифрованные данные.

Исключение:

CryptographyError – Если ключ не подходит или файл был поврежден/модифицирован.

EJIO.utils.system.encrypt_payload(data: bytes, key: str) → bytes

Шифрует поток байт с помощью крипто-стандарта AES/HMAC (Fernet). Полностью защищает файл от десериализации и анализа.

Параметры:

• data – Данные для шифрования.

• key – Ключ шифрования.

Результат:

Зашифрованные данные.

Raises:

CryptographyError если произошла ошибка шифрования.

EJIO.utils.system.generate_secure_key() → str

Генерирует криптографически стойкий случайный ключ безопасности (URL-safe Base64).

Результат:

Ключ шифрования.

EJIO.utils.system.generate_timestamped_filename(base_name: str, extension: str, prefix_date: bool = False) → str

Генерирует имя файла, интегрируя текущую дату и время в безопасном формате ISO.

Пример: generate_timestamped_filename(«report», «json») Результат: «report_20260621_153045.json»

Параметры:

• base_name – Базовое имя файла (например, „backup“, „log“).

• extension – Расширение файла без точки (например, „txt“, „csv“).

• prefix_date – Если True, дата-время встанет в начало: „20260621_153045_report.json“.

Результат:

Строка с уникальным именем файла.

EJIO.utils.system.get_app_root() → Path

Возвращает абсолютный путь к корневой папке, где запущен главный файл приложения. Надежно работает как при обычном запуске скрипта, так и при сборке через PyInstaller.

Результат:

Путь к корню программы.

EJIO.utils.system.get_class_hierarchy(base_class: type) → dict[str, Any]

Рекурсивно строит дерево иерархии классов (наследников) для указанного базового класса. Помогает отслеживать и инспектировать структуру всех зарегистрированных компонентов.

Пример вывода: {

„WidgetContainer“: {

„Form“: {}, „Layout“: {}, „Tabview“: {}

}

}

Параметры:

base_class – Базовый класс (например, Widget, Event, Window).

Результат:

Словарь, представляющий дерево наследования.

EJIO.utils.system.import_module_from_path(file_path: str | Path) → ModuleType

Динамически импортирует и регистрирует в системе Python-модуль (скрипт) по его абсолютному или относительному пути в файловой системе. Полезно для построения систем плагинов и аддонов.

Параметры:

file_path – Имя файла или путь к .py скрипту.

Результат:

Объект импортированного модуля (ModuleType).

Исключение:

• FileNotFoundError – Если модуля по указанному пути не существует.

• ImportError – Если загрузка модуля не получилась.

EJIO.utils.system.measure_time(func: F, /) → F

EJIO.utils.system.measure_time() → Callable[[Any], Any]

Декоратор для измерения времени выполнения функции с использованием loguru.

Логирует результат на уровне DEBUG, подменяя контекст на вызываемую функцию.

Поддерживает вызов как со скобками, так и без них: @measure_time @measure_time()

Параметры:

func – Функция время выполнения которой нужно измерить или None, в случае вызова как декоратора со скобками.

Результат:

Декоратор ввыполняющий измерение времени выполнения указанной функции.

EJIO.utils.system.print_class_hierarchy(hierarchy: dict[str, Any], indent: str = '', project_only: bool = True) → None

Красиво выводит древовидный словарь иерархии классов в терминал с отступами-ветвями.

Пример вывода: ├── WidgetContainer │ ├── Form │ └── Layout └── Button

Параметры:

• hierarchy – Словарь предстваляющий иерархию пректа, собранную через get_class_hierarchy или scan_package_classes

• indent – разделитель между ветвями

• project_only – Если True, скрывает системные модули Python, выводя только классы вашего фреймворка/приложения.

EJIO.utils.system.profile_function(file_name: F, /) → F

EJIO.utils.system.profile_function(file_name: str | None = None, /) → Callable[[F], F]

Декоратор для создания профиля функции.

Записывает профиль в файл, или выводит в консоль, если файл не задан.

Поддерживает вызов как со скобками, так и без них: @profile_function @profile_function(«profile.prof»)

Просмотреть профиль можно выполнив tuna file_name в консоли

Параметры:

file_name – Имя файла для сохранения профиля функции.

Результат:

Декоратор выполняющий профилирование указанной функции.

EJIO.utils.system.retry(*exceptions: type[BaseException], tries: int = 3, delay: float = 0.1) → Callable[[Callable[[P], R]], Callable[[P], R]]

Декоратор для повторного выполнения функции при возникновении ошибок.

Можно использовать как @retry, @retry(ValueError) или @retry(ValueError, TypeError, tries=5).

Параметры:

• exceptions – Перечень исключений, при которых нужен повтор. Если не передано, перехватывает любое исключение (Exception).

• tries – Количество попыток выполнения функции, по умолчанию 3.

• delay – Задержка между попытками в секундах, по умолчанию 0.1.

Результат:

Декорированная функция с поддержкой повторных попыток.

Исключение:

BaseException – Последнее пойманное исключение, если все попытки исчерпаны.

EJIO.utils.system.rotate_and_save(target_path: str | Path, max_backups: int, write_callback: Callable[[Path], None]) → None

Управляет ротацией бэкапов файла по индексам (file.1.ext, file.2.ext) и атомарно сохраняет новое состояние под основным именем.

Параметры:

• target_path – Путь к основному файлу (например, „config.json“).

• max_backups – Максимальное количество удерживаемых файлов бэкапа (>= 1).

• write_callback – Функция-коллбэк для безопасной записи нового файла.

EJIO.utils.system.run_on_import(func: Callable[[P], R]) → Callable[[P], R]

Декоратор для автоматического запуска функции в момент импорта модуля.

Функция вызывается без аргументов сразу при инициализации файла.

Параметры:

func – Декорируемая функция, не должна требовать обязательных аргументов.

Результат:

Исходная функция для возможности последующих ручных вызовов.

EJIO.utils.system.save_atomic(target_path: str | Path, write_callback: Callable[[Path], None]) → None

Выполняет транзакционную (атомарную) запись в файл через скрытый временный файл. Гарантирует, что оригинальный файл не будет поврежден в случае сбоя программы или ОС.

Параметры:

• target_path – Целевой путь к файлу (куда нужно сохранить итог).

• write_callback – Функция-коллбэк, принимающая Path временного файла, куда нужно писать данные.

EJIO.utils.system.scan_package_classes(package_name: str, base_class: type = <class 'object'>) → dict[str, Any]

Сканирует все подмодули указанного пакета, используя встроенный механизм pkgutil. Автоматически и корректно разрешает относительные импорты (relative imports), загружая модули с учетом их полного родительского контекста. Сканирует все .py файлы в указанной директории пакета, принудительно импортирует их в память Python, после чего строит и возвращает полную иерархию классов для base_class.

Параметры:

• package_name – Имя импортированного пакета.

• base_class – Базовый класс, иерархию которого нужно собрать.

Результат:

Словарь дерева иерархии классов.

Исключение:

• ImportError – При ошибке импорта корневого пакета.

• ValueError – Если указанный пакет не является пакетом.