EJIO.utils package

Inheritance diagram of EJIO.utils.interface.dictable.Dictable, EJIO.utils.interface.listable.Listable, EJIO.utils.interface.tupleable.Tupleable, EJIO.utils.interface.singleton.Singleton, EJIO.utils.interface.prototype.Prototype, EJIO.utils.interface.prototype.ThreadSafePrototypeMixin, EJIO.utils.interface.static_class.StaticClass, EJIO.utils.interface.static_class.StaticClassMeta, EJIO.utils.interface.isolated_storage.IsolatedStorageMixin, EJIO.utils.interface.read_only_class.ReadOnlyMeta, EJIO.utils.interface.mutable_static_class.MutableStaticMeta, EJIO.utils.interface.mutable_static_class.static_property, EJIO.utils.interface.disposable.Disposable, EJIO.utils.interface.disposable.DisposableMeta, EJIO.utils.struct.stack.Stack, EJIO.utils.struct.queue.Queue, EJIO.utils.struct.deque.Deque, EJIO.utils.struct.registry.Registry, EJIO.utils.struct.list.List, EJIO.utils.struct.dict.Dict, EJIO.utils.struct.tree.TreeNode, EJIO.utils.struct.tree.TreeTraverser, EJIO.utils.system.properties.SystemProperties, EJIO.utils.system.paths.SystemPaths, EJIO.utils.system.hardware.HardwareProperties, EJIO.utils.system.localization.Localization, EJIO.utils.serialization.serializable.Serializable, EJIO.utils.serialization.storable.Storable, EJIO.utils.serialization.encapsulatable.Encapsulatable, EJIO.utils.serialization.serializer.Serializer, EJIO.utils.serialization.serializer_registry.SerializerRegistry, EJIO.utils.serialization.implementations.json_serializer.JSONSerializer, EJIO.utils.serialization.implementations.toml_serializer.TOMLSerializer, EJIO.utils.serialization.implementations.yaml_serializer.YAMLSerializer, EJIO.utils.serialization.implementations.msgpack_serializer.MessagePackSerializer, EJIO.utils.serialization.implementations.ini_serializer.INISerializer, EJIO.utils.serialization.implementations.xml_serializer.XMLSerializer, EJIO.utils.dataset.dataset_storage.DatasetStorage, EJIO.utils.dataset.dataset_registry.DatasetRegistry, EJIO.utils.dataset.implementations.csv_storage.CSVStorage, EJIO.utils.resource.manager.resource, EJIO.utils.resource.registry.GlobalResourceRegistry, EJIO.utils.component.numbers.big_number.BigNumber, EJIO.utils.component.clock.time_class.Time, EJIO.utils.component.clock.virtual_clock.VirtualClock, EJIO.utils.component.clock.realtime_clock.RealtimeClock, EJIO.utils.component.clock.timer.Timer, EJIO.utils.component.app.app.ApplicationCore, EJIO.utils.component.check.type_checker_types.TypeCheckerTypes, EJIO.utils.component.check.type_checker.TypeCheckerClass, EJIO.utils.component.check.type_check.Types, EJIO.utils.component.check.type_check.TypeChecker, EJIO.utils.component.check.str_type_check.StringTypes, EJIO.utils.component.check.str_type_check.StringChecker, EJIO.utils.component.color.color.Color, EJIO.utils.component.color.colors.COLORS, EJIO.utils.component.tree.general_tree.GeneralTreeNode, EJIO.utils.component.tree.bst.BSTNode

Subpackages

Submodules

EJIO.utils.base_error module

exception EJIO.utils.base_error.UtilsBaseError(message: str)[исходный код]

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

Базовое исключение пакета utils.

EJIO.utils.err module

exception EJIO.utils.err.ApplicationCoreError(message: str)[исходный код]

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

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

exception EJIO.utils.err.ClockError(message: str)[исходный код]

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

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

exception EJIO.utils.err.CryptographyError(message: str)[исходный код]

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

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

exception EJIO.utils.err.DatasetError(message: str)[исходный код]

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

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

exception EJIO.utils.err.LocalizationError(message: str)[исходный код]

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

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

exception EJIO.utils.err.RegistryKeyError(message: str)[исходный код]

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

Исключение, вызываемое при конфликтах или отсутствии ключей в регистре.

exception EJIO.utils.err.RegistryTypeError(message: str)[исходный код]

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

Исключение при попытке зарегистрировать класс неверного типа.

exception EJIO.utils.err.RequirementsError(message: str)[исходный код]

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

Исключение, связанное с отсутствием требуемых параметров приложения.

exception EJIO.utils.err.SerializationError(message: str)[исходный код]

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

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

exception EJIO.utils.err.UtilsBaseError(message: str)[исходный код]

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

Базовое исключение пакета utils.

Module contents

class EJIO.utils.ApplicationCore(*args: object, **kwargs: object)[исходный код]

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

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

settings: dict[str, Any] = {'application': {'name': 'DefaultEJIOApp'}}
start() → None[исходный код]

Запускает полный жизненный цикл оркестрации приложения.

Исключение:

ApplicationCoreError – При попытке запуска ядра приложения повторно.

class EJIO.utils.BSTNode(*args: Any)[исходный код]

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

Узел двоичного (бинарного) дерева поиска (Binary Search Tree). Содержит строго левого (меньшего) и правого (большего) потомков.

property children: Iterable[TreeNode]

Потокобезопасная проекция двоичной структуры на общий контракт TreeNode. Возвращает левого и правого детей, если они существуют.

Результат:

Список потомков.

destroy() → None[исходный код]

Итеративное, потокобезопасное и каскадное уничтожение бинарного дерева поиска. Полностью защищено от RecursionError и оптимизировано по скорости.

insert(val: Any) → None[исходный код]

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

Параметры:

val – Значение нового узла.

left: BSTNode | None
right: BSTNode | None
property value: Any

Возвращает значение текущего узла.

Результат:

Значение текущего узла.

class EJIO.utils.BigNumber(value: int | float, scale: str = '')[исходный код]

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

Представление большого числа с автоматическим управлением масштабом.

convert_to_scale(target_scale: str) → BigNumber[исходный код]

Преобразует число в указанную шкалу, например: миллионы в тысячи.

Параметры:

target_scale – Целевое обозначение масштаба

Результат:

Масштобированное значение.

Исключение:

ValueError – Если масштаб неподдерживаем

scales_dict: dict[str, float] = {'': 1, 'At': 1e+153, 'B': 1000000000.0, 'Ce': 1e+69, 'CeMi': 1e+132, 'DC': 1e+81, 'DCe': 1e+75, 'DCeMi': 1e+135, 'DDe': 1e+39, 'DMi': 1e+117, 'De': 1e+33, 'DeMi': 1e+123, 'Fe': 1e+150, 'K': 1000.0, 'M': 1000000.0, 'Mc': 1e+141, 'Mi': 1e+105, 'Mi-B': 1e+111, 'Mi-M': 1e+108, 'Mi-T': 1e+114, 'Na': 1e+144, 'Ng': 1e+66, 'No': 1e+30, 'NoC': 1e+102, 'Oc': 1e+27, 'OcC': 1e+99, 'Og': 1e+63, 'Pi': 1e+147, 'Qa': 1e+51, 'Qd': 1000000000000000.0, 'QdC': 1e+87, 'Qi': 1e+54, 'Qn': 1e+18, 'QnC': 1e+90, 'Se': 1e+57, 'Sg': 1e+60, 'Sp': 1e+24, 'SpC': 1e+96, 'Sx': 1e+21, 'SxC': 1e+93, 'T': 1000000000000.0, 'TC': 1e+84, 'TCe': 1e+78, 'TCeMi': 1e+138, 'TDe': 1e+42, 'TMi': 1e+120, 'Tg': 1e+48, 'TgMi': 1e+129, 'UCe': 1e+72, 'UDe': 1e+36, 'Ve': 1e+165, 'Vg': 1e+45, 'VgMi': 1e+126, 'Xo': 1e+162, 'Yo': 1e+159, 'Ze': 1e+156}
scales_list: list[tuple[str, float]] = [('', 1), ('K', 1000.0), ('M', 1000000.0), ('B', 1000000000.0), ('T', 1000000000000.0), ('Qd', 1000000000000000.0), ('Qn', 1e+18), ('Sx', 1e+21), ('Sp', 1e+24), ('Oc', 1e+27), ('No', 1e+30), ('De', 1e+33), ('UDe', 1e+36), ('DDe', 1e+39), ('TDe', 1e+42), ('Vg', 1e+45), ('Tg', 1e+48), ('Qa', 1e+51), ('Qi', 1e+54), ('Se', 1e+57), ('Sg', 1e+60), ('Og', 1e+63), ('Ng', 1e+66), ('Ce', 1e+69), ('UCe', 1e+72), ('DCe', 1e+75), ('TCe', 1e+78), ('DC', 1e+81), ('TC', 1e+84), ('QdC', 1e+87), ('QnC', 1e+90), ('SxC', 1e+93), ('SpC', 1e+96), ('OcC', 1e+99), ('NoC', 1e+102), ('Mi', 1e+105), ('Mi-M', 1e+108), ('Mi-B', 1e+111), ('Mi-T', 1e+114), ('DMi', 1e+117), ('TMi', 1e+120), ('DeMi', 1e+123), ('VgMi', 1e+126), ('TgMi', 1e+129), ('CeMi', 1e+132), ('DCeMi', 1e+135), ('TCeMi', 1e+138), ('Mc', 1e+141), ('Na', 1e+144), ('Pi', 1e+147), ('Fe', 1e+150), ('At', 1e+153), ('Ze', 1e+156), ('Yo', 1e+159), ('Xo', 1e+162), ('Ve', 1e+165)]
to_scale_string(precision: int = 2) → str[исходный код]

Возвращает строку с числом, автоматически масштабированным, например: „1.23 M“.

Параметры:

precision – Число знаков после запятой

Результат:

Строка с маштабированным числом.

to_scientific(precision: int = 2) → str[исходный код]

Возвращает число в научной нотации, например: „1.23e+06“.

Параметры:

precision – Число знаков после запятой

Результат:

Строка с числом в научной нотации.

value: float
class EJIO.utils.COLORS(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

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

Неизменяемый расширенный реестр системных и графических цветов. Содержит современные палитры Material / Tailwind UI.

AMBER: Color = Color(R=120, G=53, B=15, A=255)
AMBER_LIGHT: Color = Color(R=255, G=251, B=235, A=255)
BLACK: Color = Color(R=0, G=0, B=0, A=255)
BLUE: Color = Color(R=59, G=130, B=246, A=255)
CRIMSON: Color = Color(R=153, G=27, B=27, A=255)
CRIMSON_LIGHT: Color = Color(R=254, G=242, B=242, A=255)
CYAN: Color = Color(R=6, G=182, B=212, A=255)
EMERALD: Color = Color(R=6, G=78, B=59, A=255)
EMERALD_LIGHT: Color = Color(R=236, G=253, B=245, A=255)
GREEN: Color = Color(R=16, G=185, B=129, A=255)
INDIGO: Color = Color(R=99, G=102, B=241, A=255)
INFO_BLUE: Color = Color(R=30, G=58, B=138, A=255)
INFO_LIGHT: Color = Color(R=239, G=246, B=255, A=255)
ORANGE: Color = Color(R=249, G=115, B=22, A=255)
PINK: Color = Color(R=236, G=72, B=153, A=255)
PURPLE: Color = Color(R=139, G=92, B=246, A=255)
RED: Color = Color(R=239, G=68, B=68, A=255)
SLATE_100: Color = Color(R=241, G=245, B=249, A=255)
SLATE_300: Color = Color(R=203, G=213, B=225, A=255)
SLATE_50: Color = Color(R=248, G=250, B=252, A=255)
SLATE_500: Color = Color(R=100, G=116, B=139, A=255)
SLATE_700: Color = Color(R=51, G=65, B=85, A=255)
SLATE_800: Color = Color(R=30, G=41, B=59, A=255)
SLATE_900: Color = Color(R=15, G=23, B=42, A=255)
TEAL: Color = Color(R=20, G=184, B=166, A=255)
TRANSPARENT: Color = Color(R=0, G=0, B=0, A=0)
WHITE: Color = Color(R=255, G=255, B=255, A=255)
YELLOW: Color = Color(R=245, G=158, B=11, A=255)
classmethod clear() → None[исходный код]
classmethod destroy() → None[исходный код]
class EJIO.utils.CSVStorage(*args, **kwargs)[исходный код]

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

Реализация табличного хранилища для формата CSV. Поддерживает кастомные кодировки, разделители (delimiter) и диалекты.

static load(filename: str, **kwargs: Any) → list[dict[str, T]][исходный код]

Загрузить CSV-файл в виде списка словарей.

Параметры:

  • filename – Путь к файлу для загрузки.

  • kwargs – Дополнительные ключевые аргументы, для получения необязательных параметров.

Результат:

Список словарей.

Исключение:

DatasetError – При ошибке загрузки датасета.

static save(data: list[dict[str, T]], filename: str, **kwargs: Any) → None[исходный код]

Сохранить список словарей в CSV-файл.

Параметры:

  • data – Список словарей для сериализации.

  • filename – Путь к файлу для сохранения.

  • kwargs – Дополнительные ключевые аргументы, для получения необязательных параметров.

Исключение:

DatasetError – При ошибке сохранения датасета.

class EJIO.utils.Color(*args: Any)[исходный код]

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

Универсальный класс для работы с цветом. Инкапсулирует парсинг из любых форматов (HEX, RGB, RGBA, float) и лениво преобразует его в нужные рантайм-представления.

property hex: str

Возвращает стандартную шестнадцатеричную строку (например, „#FF5733“).

Результат:

Цвет в формате HEX.

property hex_alpha: str

Возвращает HEX строку, включающую альфа-компоненту (например, „#FF573380“).

Результат:

Цвет в формате HEXA.

property normalized: tuple[float, float, float, float]

Возвращает нормализованные float-координаты от 0.0 до 1.0.

Результат:

Нормализованный цвет в формате RGBA.

property rgb: tuple[int, int, int]

Возвращает классический кортеж целых чисел (R, G, B).

Результат:

Цвет в формате RGB.

property rgba: tuple[int, int, int, int]

Возвращает полный кортеж целых чисел с альфа-каналом (R, G, B, A).

Результат:

Цвет в формате RGBA.

class EJIO.utils.DatasetRegistry(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

Базовые классы: Registry[DatasetStorage]

Глобальный реестр табличных хранилищ данных (датасетов).

class EJIO.utils.DatasetStorage(*args, **kwargs)[исходный код]

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

Интерфейс для классов-хранилищ табличных наборов данных (датасетов).

abstractmethod static load(filename: str, **kwargs: Any) → list[dict[str, T]][исходный код]

Загрузить массив табличных строк из файла.

Параметры:

  • filename – Путь к файлу для загрузки.

  • kwargs – Ключевые параметры для хранилища данных.

Результат:

Список словарей, полученный из строки.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

abstractmethod static save(data: list[dict[str, T]], filename: str, **kwargs: Any) → None[исходный код]

Сохранить массив табличных строк в файл.

Параметры:

  • data – Список словарей для сериализации.

  • filename – Путь к файлу для сохранения.

  • kwargs – Ключевые параметры для хранилища данных.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

class EJIO.utils.Deque[исходный код]

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

Потокобезопасная двусторонняя очередь на двусвязном списке. Класс поддерживает основные операции с обоих концов структуры.

property empty: bool

Проверяет пуста ли очередь.

Результат:

True если очередь пуста, иначе False.

peek_back() → T[исходный код]

Возвращает последний элемент (в хвосте) без удаления.

Результат:

Объект из конца очереди.

Исключение:

IndexError – Если очередь пуста.

peek_front() → T[исходный код]

Возвращает первый элемент (в голове) без удаления.

Результат:

Объект из начала очереди.

Исключение:

IndexError – Если очередь пуста.

pop_back() → T[исходный код]

Удаляет и возвращает элемент из конца (хвоста) очереди.

Результат:

Объект из конца очереди.

Исключение:

IndexError – Если очередь пуста.

pop_front() → T[исходный код]

Удаляет и возвращает элемент из начала (головы) очереди.

Результат:

Объект из начала очереди.

Исключение:

IndexError – Если очередь пуста.

push_back(item: T) → None[исходный код]

Добавляет элемент в конец (хвост) очереди.

Параметры:

item – Объект для добавления.

push_front(item: T) → None[исходный код]

Добавляет элемент в начало (голову) очереди.

Параметры:

item – Объект для добавления.

property size: int

Возвращает текущий размер очереди.

Результат:

Размер очереди.

class EJIO.utils.Dict(*args: Any, **kwargs: Any)[исходный код]

Базовые классы: MutableMapping, Generic

Потокобезопасная обертка над стандартным словарем dict.

clear() → None[исходный код]

Очищает словарь.

class EJIO.utils.Dictable(*args, **kwargs)[исходный код]

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

Интерфейс объектов, которые поддерживают преобразование в/из словаря (dict). Используется для сериализации и десериализации объектов.

abstractmethod classmethod from_dict(data: dict[str, T]) → Self[исходный код]

Восстановить объект из словаря.

Параметры:

data – Словарь с данными.

Результат:

Новый объект, созданный из этого словаря.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

abstractmethod to_dict() → dict[str, T][исходный код]

Преобразовать объект в словарь.

Результат:

Словарь, отражающий состояние объекта.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

class EJIO.utils.Disposable(*args, **kwargs)[исходный код]

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

Единый интерфейс-протокол для всех долгоживущих рантайм-структур. Гарантирует автоматическую очистку памяти при завершении работы приложения.

clear() → None[исходный код]

Метод полной очистки внутреннего хранилища/состояния.

Исключение:

NotImplementedError – должен быть реализован в подклассах.

destroy() → None[исходный код]

Метод полной очистки внутреннего хранилища/состояния.

Исключение:

NotImplementedError – должен быть реализован в подклассах.

class EJIO.utils.DisposableMeta(name: str, bases: tuple[type, ...], attrs: dict[str, Any])[исходный код]

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

Метакласс для автоматического рантайм-учета всех уничтожаемых и очищаемых структур.

classmethod dispose_all() → None[исходный код]

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

class EJIO.utils.Encapsulatable(*args, **kwargs)[исходный код]

Базовые классы: Serializable, Storable, Protocol

Интерфейс сериализуемых и сохраняемых объектов, поддерживающий работу с любым сериализатором. Объекты должны уметь преобразовываться в/из словаря (Dictable), а также работать с внешним сериализатором.

class EJIO.utils.GeneralTreeNode(*args: Any)[исходный код]

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

Узел универсального дерева общего вида (N-арное дерево). Может содержать неограниченное количество дочерних потомков.

add_child(child_node: GeneralTreeNode) → GeneralTreeNode[исходный код]

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

Параметры:

child_node – Новый дочерний узел.

Результат:

Новый узел.

property children: Iterable[TreeNode]

Возвращает изолированную потокобезопасную копию списка потомков.

Результат:

Список потомков.

destroy() → None[исходный код]

Потокобезопасное каскадное уничтожение N-арного дерева.

remove_child(child_node: GeneralTreeNode) → None[исходный код]

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

Параметры:

child_node – Дочерний узел.

property value: Any

Возвращает значение текущего узла.

Результат:

Значение текущего узла.

class EJIO.utils.GlobalResourceRegistry(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

Базовые классы: Registry[Any]

Статическое изолированное хранилище для тяжелых глобальных ресурсов (кэш между экранами и окнами).

class EJIO.utils.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.INISerializer(*args, **kwargs)[исходный код]

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

Реализация интерфейса Serializer для конфигурационного формата INI. Канонично использует статические методы и современный синтаксис дженериков Python 3.12+.

static deserialize(data: str, /, **kwargs: Any) → dict[str, T][исходный код]

Преобразовать INI-строку обратно в словарь. Если задействована только дефолтная секция, возвращает её в плоском виде.

Параметры:

  • data – INI-строка.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Десериализованный словарь.

Исключение:

SerializationError – При ошибках десериализации.

static load(filename: str, /, **kwargs: Any) → dict[str, T][исходный код]

Загрузить словарь из INI-файла.

Параметры:

  • filename – Путь к файлу для загрузки.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из файла.

Исключение:

SerializationError – При ошибках десериализации.

static save(data: dict[str, T], filename: str, /, **kwargs: Any) → None[исходный код]

Сохранить словарь в INI-файл.

Параметры:

  • data – Сериализуемый словарь.

  • filename – Путь к файлу для сохранения.

  • kwargs – Ключевые параметры для сереализатора.

Исключение:

SerializationError – При ошибках сериализации.

static serialize(data: dict[str, T], /, **kwargs: Any) → str[исходный код]

Преобразовать словарь в INI-строку. Если передан плоский словарь, данные автоматически упаковываются в секцию DEFAULT.

Параметры:

  • data – Сериализуемый словарь.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

INI-строка.

Исключение:

SerializationError – При ошибках сериализации.

class EJIO.utils.IsolatedStorageMixin[исходный код]

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

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

class EJIO.utils.JSONSerializer(*args, **kwargs)[исходный код]

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

Реализация интерфейса Serializer для формата JSON.

static deserialize(data: str, /, **kwargs: Any) → dict[str, T][исходный код]

Преобразовать JSON-строку обратно в словарь.

Параметры:

  • data – JSON-строка.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из строки.

Исключение:

SerializationError – При ошибках десериализации.

static load(filename: str, /, **kwargs: Any) → dict[str, T][исходный код]

Загрузить словарь из JSON-файла.

Параметры:

  • filename – Путь к файлу для загрузки.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из строки.

Исключение:

SerializationError – При ошибках десериализации.

static save(data: dict[str, T], filename: str, /, **kwargs: Any) → None[исходный код]

Сохранить словарь в JSON-файл.

Параметры:

  • data – Сериализуемый словарь.

  • filename – Путь к файлу для сохранения.

  • kwargs – Ключевые параметры для сереализатора.

Исключение:

SerializationError – При ошибках сериализации.

static serialize(data: dict[str, T], /, **kwargs: Any) → str[исходный код]

Преобразовать словарь в JSON-строку.

Параметры:

  • data – Сериализуемый словарь.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

JSON-строка.

Исключение:

SerializationError – При ошибках сериализации.

class EJIO.utils.List(iterable: Iterable | None = None)[исходный код]

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

Потокобезопасный динамический список на базе двусвязного списка. Итерация по списку безопасна к удалениям элементов «на лету».

append(item: T) → None[исходный код]

Добавляет элемент в конец списка.

Параметры:

item – Элемент для добавления.

clear() → None[исходный код]

Очищает список, удаляя все элементы.

count(item: T) → int[исходный код]

Возвращает количество вхождений элемента в список.

Параметры:

item – Элемент для подсчета.

Результат:

Количество совпадений.

extend(iterable: Iterable) → None[исходный код]

Добавляет все элементы из итерируемого объекта в конец списка.

Параметры:

iterable – Итерируемый объект с элементами.

index(item: T, start: int = 0, end: int | None = None) → int[исходный код]

Возвращает индекс первого вхождения элемента в заданном диапазоне.

Параметры:

  • item – Искомый элемент.

  • start – Начальный индекс поиска.

  • end – Конечный индекс поиска (не включая его).

Результат:

Порядковый индекс элемента.

Исключение:

ValueError – Если элемент не найден в указанных границах.

insert(index: int, item: T) → None[исходный код]

Вставляет элемент по указанному индексу.

Параметры:

  • index – Индекс, на место которого будет вставлен элемент.

  • item – Значение для вставки.

pop(index: int = -1) → T[исходный код]

Удаляет и возвращает элемент по индексу.

Параметры:

index – Индекс удаляемого элемента (по умолчанию последний: -1).

Результат:

Удаленный элемент списка.

Исключение:

IndexError – Если список пуст или индекс вне диапазона.

remove(item: T) → None[исходный код]

Удаляет первое вхождение элемента. Поддерживает стабильность итератора.

Параметры:

item – Элемент, который требуется удалить.

Исключение:

ValueError – Если элемент отсутствует в списке.

reverse() → None[исходный код]

Разворачивает список на месте.

sort(key: Callable[[T], T] | None = None, reverse: bool = False) → None[исходный код]

Сортирует элементы списка на месте.

Параметры:

  • key – Функция, извлекающая ключ для сравнения из каждого элемента.

  • reverse – Если True, сортировка производится по убыванию.

Результат:

None

class EJIO.utils.Listable(*args, **kwargs)[исходный код]

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

Интерфейс объектов, которые поддерживают преобразование в/из списка (list).

abstractmethod classmethod from_list(data: list[T]) → Self[исходный код]

Восстановить объект из списка.

Параметры:

data – Список с данными.

Результат:

Новый объект, созданный из этого списка.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

abstractmethod to_list() → list[T][исходный код]

Преобразовать объект в список.

Результат:

Список, отражающий состояние объекта.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

class EJIO.utils.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.MessagePackSerializer(*args, **kwargs)[исходный код]

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

Реализация интерфейса Serializer для бинарного формата MessagePack.

static deserialize(data: str, /, **kwargs: Any) → dict[str, T][исходный код]

Преобразовать закодированную строку обратно в словарь.

Параметры:

  • data – Строковое представление байтового потока.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Десериализованный словарь.

Исключение:

SerializationError – При ошибках десериализации.

static load(filename: str, /, **kwargs: Any) → dict[str, T][исходный код]

Загрузить словарь из бинарного файла MessagePack.

Параметры:

  • filename – Путь к файлу для загрузки.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из файла.

Исключение:

SerializationError – При ошибках десериализации.

static save(data: dict[str, T], filename: str, /, **kwargs: Any) → None[исходный код]

Сохранить словарь в бинарный файл MessagePack.

Параметры:

  • data – Сериализуемый словарь.

  • filename – Путь к файлу для сохранения.

  • kwargs – Ключевые параметры для сереализатора.

Исключение:

SerializationError – При ошибках сериализации.

static serialize(data: dict[str, T], /, **kwargs: Any) → str[исходный код]

Преобразовать словарь в строку, закодированную через MessagePack.

Параметры:

  • data – Сериализуемый словарь.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Текстовое представление байтового потока.

Исключение:

SerializationError – При ошибках сериализации.

class EJIO.utils.MutableStaticMeta(name: str, bases: tuple[type, ...], attrs: dict[str, Any])[исходный код]

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

Метакласс для изменяемых статических структур конфигурации. Запрещает создание экземпляров, но разрешает чтение функций класса как вычисляемых свойств (property) без круглых скобок.

class EJIO.utils.Prototype(*args, **kwargs)[исходный код]

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

Протокол, реализующий методы для копирования себя.

clone() → Self[исходный код]

Поверхностное копирование (вложенные объекты остаются общими).

Результат:

Поверхностную копию объекта.

deep_clone() → Self[исходный код]

Глубокое копирование (вложенные объекты тоже дублируются).

Результат:

Полную копию объекта.

class EJIO.utils.Queue[исходный код]

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

Потокобезопасная очередь на односвязном списке. Класс поддерживает основные операции push, pop, peek, size, empty.

property empty: bool

Проверяет пуста ли очередь.

Результат:

True если очередь пуста, иначе False.

peek() → T[исходный код]

Возвращает первый элемент очереди без удаления.

Результат:

Объект из начала очереди.

Исключение:

IndexError – Если очередь пуста.

pop() → T[исходный код]

Удаляет и возвращает первый элемент очереди.

Результат:

Объект из начала очереди.

Исключение:

IndexError – Если очередь пуста.

push(item: T) → None[исходный код]

Добавляет элемент в конец очереди.

Параметры:

item – Объект для добавления.

property size: int

Возвращает текущий размер очереди.

Результат:

Размер очереди.

class EJIO.utils.ReadOnlyMeta(name: str, bases: tuple[type, ...], attrs: dict[str, Any])[исходный код]

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

Метакласс, реализующий свойства только для чтения на уровне самого класса и полностью запрещающий создание экземпляров.

class EJIO.utils.RealtimeClock[исходный код]

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

Реальные часы, основаны на системном времени.

get_time() → Time[исходный код]

Получает текущее системное время.

Результат:

Объект Time со значением текущего времени.

class EJIO.utils.Registry(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

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

Абстрактный базовый интерфейс для конкретных классов-регистров.

Объединяет запрет на создание экземпляров и механизм изолированного хранилища. Предоставляет API для регистрации и получения классов по строковому ключу. Работает строго с типами, унаследованными от T или являющимися T.

classmethod clear() → None[исходный код]

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

classmethod get(key: str) → type[T][исходный код]

Возвращает зарегистрированный класс по его ключу из текущего регистра.

Параметры:

key – Строковый ключ.

Результат:

Класс, сохраненный под этим ключом.

Исключение:

RegistryKeyError – Если класс с таким ключом не найден.

classmethod get_all() → dict[str, type[T]][исходный код]

Возвращает изолированную копию словаря со всеми зарегистрированными классами.

Результат:

Словарь вида {ключ: класс}.

classmethod has_key(key: str) → bool[исходный код]

Потокобезопасно проверяет, зарегистрирован ли какой-либо класс под данным ключом.

Параметры:

key – Строковый ключ для проверки.

Результат:

True, если ключ существует в реестре, иначе False.

classmethod register(key: str, target_cls: type[S]) → type[S][исходный код]

Регистрирует класс или объект в текущем регистре под определенным ключом. Выполняет потокобезопасную проверку на уникальность ключа.

Параметры:

  • key – Уникальный строковый идентификатор для класса.

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

Результат:

Сам зарегистрированный класс (поддерживает синтаксис декоратора).

Исключение:

RegistryKeyError – Если ключ уже занят в этом конкретном регистре.

classmethod unregister(key: str) → None[исходный код]

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

Параметры:

key – Строковый ключ для удаления.

Исключение:

RegistryKeyError – Если ключ отсутствует в реестре.

class EJIO.utils.Serializable(*args, **kwargs)[исходный код]

Базовые классы: Dictable, Protocol

Интерфейс сериализуемых объектов, поддерживающий преобразование в строку и из строки с любым сериализатором. Объекты должны уметь преобразовываться в/из словаря (Dictable), а также работать с внешним сериализатором.

classmethod deserialize(data: str, serializer: type[Serializer], /, **kwargs: Any) → Self[исходный код]

Десериализовать объект из строки с использованием сериализатора.

Параметры:

  • data – сериализованная строка.

  • serializer – Класс сериализатора.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Новый экземпляр объекта.

Исключение:

SerializationError – В случае ошибок десериализации.

serialize(serializer: type[Serializer], /, **kwargs: Any) → str[исходный код]

Сериализовать объект с помощью переданного сериализатора.

Параметры:

  • serializer – Класс сериализатора (например, JSONSerializer).

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Строка с сериализованными данными.

Исключение:

SerializationError – В случае ошибок сериализации.

class EJIO.utils.Serializer(*args, **kwargs)[исходный код]

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

Интерфейс для классов-сериализаторов. Определяет методы для преобразования словаря в строку и обратно.

abstractmethod static deserialize(data: str, /, **kwargs: Any) → dict[str, T][исходный код]

Десериализовать строку обратно в словарь.

Параметры:

  • data – Строка для десериализации.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из строки.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

abstractmethod static load(filename: str, /, **kwargs: Any) → dict[str, T][исходный код]

Загрузить словарь из файла.

Параметры:

  • filename – Путь к файлу для загрузки.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из строки.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

abstractmethod static save(data: dict[str, T], filename: str, /, **kwargs: Any) → None[исходный код]

Сохранить словарь в файл.

Параметры:

  • data – Словарь для сериализации.

  • filename – Путь к файлу для сохранения.

  • kwargs – Ключевые параметры для сереализатора.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

abstractmethod static serialize(data: dict[str, T], /, **kwargs: Any) → str[исходный код]

Сериализовать словарь в строку.

Параметры:

  • data – Словарь для сериализации.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Строка в формате, поддерживаемом реализующим классом.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

class EJIO.utils.SerializerRegistry(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

Базовые классы: Registry[Serializer]

Регистр сериализаторов, все сериализаторы должны наследовать интерфейс Serializer

class EJIO.utils.Singleton(*args: object, **kwargs: object)[исходный код]

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

Базовый класс Singleton.

class EJIO.utils.Stack[исходный код]

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

Потокобезопасный стек на односвязном списке. Класс поддерживает основные операции push, pop, peek, size, empty.

property empty: bool

Проверяет пуст ли стек.

Результат:

True если стек пуст, иначе False.

peek() → T[исходный код]

Возвращает верхний элемент стека без удаления.

Результат:

Объект из начала стека.

Исключение:

IndexError – Если стек пуст.

pop() → T[исходный код]

Удаляет и возвращает верхний элемент стека.

Результат:

Объект из начала стека.

Исключение:

IndexError – Если стек пуст.

push(item: T) → None[исходный код]

Добавляет элемент на вершину стека.

Параметры:

item – Объект для добавления.

property size: int

Возвращает текущий размер стека.

Результат:

Размер стека.

class EJIO.utils.StaticClass(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

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

Интерфейс-миксин для создания строго статических классов. Запрещает создание любых экземпляров данного класса или его наследников.

class EJIO.utils.StaticClassMeta(name: str, bases: tuple[type, ...], attrs: dict[str, Any])[исходный код]

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

Метакласс, запрещающий создание экземпляров.

class EJIO.utils.Storable(*args, **kwargs)[исходный код]

Базовые классы: Dictable, Protocol

Интерфейс сохраняемых объектов, поддерживающий сохранение в файл и загрузку из файла любым сериализатором. Объекты должны уметь преобразовываться в/из словаря (Dictable), а также работать с внешним сериализатором.

classmethod load(filename: str, serializer: type[Serializer], /, **kwargs: Any) → Self[исходный код]

Загрузить объект из файла.

Параметры:

  • filename – Имя файла.

  • serializer – Класс сериализатора.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Восстановленный объект.

Исключение:

SerializationError – Если не удалось десериализовать данные.

save(filename: str, serializer: type[Serializer], /, **kwargs: Any) → None[исходный код]

Сохранить объект в файл.

Параметры:

  • filename – Имя файла.

  • serializer – Класс сериализатора.

  • kwargs – Ключевые параметры для сереализатора.

Исключение:

SerializationError – Если не удалось сериализовать данные.

class EJIO.utils.StringChecker(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

Базовые классы: TypeCheckerClass[str, StringTypes]

Класс для определения и проверки содержимого строк по флагам StringTypes. Позволяет узнать, какому типу данных фактически соответствуют текстовые данные.

class EJIO.utils.StringTypes(*values)[исходный код]

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

Интегер-флаг, представляющий типы данных, которые могут быть закодированы в строке. Каждый флаг — это битовая маска, позволяющая комбинировать несколько проверок.

BOOL = 32
DICT = 16
FLOAT = 4
INT = 2
LIST = 8
NONE = 0
NONE_TYPE = 1
NUMBER = 64
PERCENT = 128
class EJIO.utils.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.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'
class EJIO.utils.TOMLSerializer(*args, **kwargs)[исходный код]

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

Реализация интерфейса Serializer для формата TOML.

static deserialize(data: str, /, **kwargs: Any) → dict[str, T][исходный код]

Преобразовать TOML-строку обратно в словарь.

Параметры:

  • data – TOML-строка.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из строки.

Исключение:

SerializationError – При ошибках десериализации.

static load(filename: str, /, **kwargs: Any) → dict[str, T][исходный код]

Загрузить словарь из TOML-файла.

Параметры:

  • filename – Путь к файлу для загрузки.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из файла.

Исключение:

SerializationError – При ошибках десериализации.

static save(data: dict[str, T], filename: str, /, **kwargs: Any) → None[исходный код]

Сохранить словарь в TOML-файл.

Параметры:

  • data – Сериализуемый словарь.

  • filename – Путь к файлу для сохранения.

  • kwargs – Ключевые параметры для сереализатора.

Исключение:

SerializationError – При ошибках сериализации.

static serialize(data: dict[str, T], /, **kwargs: Any) → str[исходный код]

Преобразовать словарь в TOML-строку.

Параметры:

  • data – Сериализуемый словарь.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

TOML-строка.

Исключение:

SerializationError – При ошибках сериализации.

class EJIO.utils.ThreadSafePrototypeMixin(*args: object, **kwargs: object)[исходный код]

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

Миксин-реализация для создания потокобезопасных прототипов. Использует Threading Lock для предотвращения состояния гонки при чтении/копировании.

clone() → Self[исходный код]

Потокобезопасное поверхностное копирование.

Результат:

Поверхностную копию объекта.

deep_clone() → Self[исходный код]

Потокобезопасное глубокое копирование.

Результат:

Полную копию объекта.

class EJIO.utils.Time(*, years: float = 0, days: float = 0, hours: float = 0, minutes: float = 0, seconds: float = 0, milliseconds: float = 0, microseconds: float = 0, nanoseconds: int = 0)[исходный код]

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

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

as_days() → int[исходный код]

Получить время в днях.

Результат:

Время в днях.

as_hours() → int[исходный код]

Получить время в часах.

Результат:

Время в часах.

as_microseconds() → int[исходный код]

Получить время в микросекундах.

Результат:

Время в микросекундах.

as_milliseconds() → int[исходный код]

Получить время в миллисекундах.

Результат:

Время в миллисекундах.

as_minutes() → int[исходный код]

Получить время в минутах.

Результат:

Время в минутах.

as_nanoseconds() → int[исходный код]

Получить время в наносекундах.

Результат:

Время в наносекундах.

as_seconds() → int[исходный код]

Получить время в секундах.

Результат:

Время в секундах.

as_years() → int[исходный код]

Получить время в годах.

Результат:

Время в годах.

format(fmt: str = '%Y:%j:%H:%M:%S:%f') → str[исходный код]

Форматирует время согласно шаблону.

%Y - Год %j - День %H - Часы %M - Минуты %S - Секунды %f - Микросекунды

Параметры:

fmt – Формат строки, по умолчанию „%Y:%j:%H:%M:%S:%f“.

Результат:

Отформатированная строка.

classmethod from_datetime(dt: datetime) → Time[исходный код]

Создает объект Time из объекта datetime.

Параметры:

dt – Объект datetime.

Результат:

Новый объект Time.

class EJIO.utils.Timer(duration: Time, func: Callable)[исходный код]

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

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

property completed: bool

Проверяет, завершился ли таймер.

Результат:

True, если таймер завершен, иначе False.

duration: Time
prolong(additional_time: Time) → Timer[исходный код]

Увеличивает длительность таймера.

Параметры:

additional_time – Время, на которое нужно увеличить таймер.

Результат:

Объект таймера.

Исключение:

TypeError – Если additional_time не является объектом Time.

property remaining_time: Time

Возвращает оставшееся время.

Результат:

Оставшееся время в формате Time.

start() → Timer[исходный код]

Запускает таймер.

Результат:

Объект таймера.

stop() → Timer[исходный код]

Останавливает таймер.

Результат:

Объект таймера.

class EJIO.utils.TreeNode(*args, **kwargs)[исходный код]

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

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

abstract property children: Iterable[TreeNode]

Возвращает итерируемый объект со всеми дочерними узлами (потомками).

Результат:

Итератор по всем дочерним узлам.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

abstractmethod destroy() → None[исходный код]

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

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

abstract property value: Any

Возвращает полезную нагрузку (данные), хранящуюся в узле.

Результат:

Значение хранящееся в узле.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

class EJIO.utils.TreeTraverser(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

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

Статический алгоритмический движок для итеративного обхода древовидных структур. Работает с любыми деревьями, поддерживающими протокол TreeNode.

Итеративный обход дерева в ширину (BFS / По уровням). Использует очередь из utils. Идеален для поиска кратчайших путей в графах/деревьях.

Параметры:

root – Корень дерева, обход которого необходимо совершить.

Yields:

Узлы дерева в порядке обхода.

Итеративный обход дерева в глубину (DFS / Pre-order). Использует стек. Безопасен для глубоких деревьев.

Параметры:

root – Корень дерева, обход которого необходимо совершить.

Yields:

Узлы дерева в порядке обхода.

class EJIO.utils.Tupleable(*args, **kwargs)[исходный код]

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

Интерфейс объектов, которые поддерживают преобразование в/из кортеж (tuple).

abstractmethod classmethod from_tuple(data: list[T]) → Self[исходный код]

Восстановить объект из кортежа.

Параметры:

data – Кортеж с данными.

Результат:

Новый объект, созданный из этого кортежа.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

abstractmethod to_tuple() → list[T][исходный код]

Преобразовать объект в кортеж.

Результат:

Кортеж, отражающий состояние объекта.

Исключение:

NotImplementedError – Должен быть реализован в подклассе.

class EJIO.utils.TypeChecker(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

Базовые классы: TypeCheckerClass[Any, Types]

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

class EJIO.utils.TypeCheckerClass(*args: tuple[object, ...], **kwargs: dict[str, object])[исходный код]

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

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

V: Тип проверяемого значения (например, Any или str). S: Тип флага.

classmethod check_types(value: V, flags: S) → bool[исходный код]

Проверяет, соответствует ли значение хотя бы одному из переданных флагов.

Параметры:

  • value – Значение, которое нужно проверить.

  • flags – Комбинация флагов типов для проверки.

Результат:

True, если значение соответствует хотя бы одному флагу, иначе False.

classmethod check_types_strict(value: V, flags: S) → bool[исходный код]

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

Параметры:

  • value – Значение, которое нужно проверить.

  • flags – Комбинация флагов типов, которой должно удовлетворять значение.

Результат:

True, если значение прошло все проверки для указанных флагов, иначе False.

classmethod get_types(value: V) → S[исходный код]

Определяет, к каким типам принадлежит переданное значение. Возвращает комбинацию флагов, описывающих все подходящие типы.

Параметры:

value – Значение, типы которого нужно определить.

Результат:

Комбинация флагов типа S.

class EJIO.utils.TypeCheckerTypes(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)[исходный код]

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

Аюстрактный класс, представляющий собой базовый класс для кслассов, содержащих проверяемые типы. Структура класса должна быть:

NONE = 0 NONE_TYPE = 1 << 0 INT = 1 << 1 FLOAT = 1 << 2 и т.д.

class EJIO.utils.Types(*values)[исходный код]

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

Интегер-флаг, представляющий разные типы данных. Каждый флаг — это битовая маска, позволяющая комбинировать несколько типов.

BOOL = 64
DICT = 32
FLOAT = 4
INT = 2
LIST = 16
NONE = 0
NONE_TYPE = 1
NUMBER = 128
PERCENT = 256
STRING = 8
class EJIO.utils.VirtualClock(start_time: Time | None = None)[исходный код]

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

Виртуальные часы, отслеживают прошедшее время без привязки к системному.

get_time() → Time[исходный код]

Возвращает текущее виртуальное время.

Результат:

Объект Time, представляющий текущее время.

start() → Self[исходный код]

Запускает виртуальные часы.

Результат:

Сам объект для цепочки вызовов.

Исключение:

ClockError – Если часы уже запущены.

stop() → Self[исходный код]

Останавливает виртуальные часы.

Результат:

Сам объект для цепочки вызовов.

Исключение:

ClockError – Если часы не запущены.

class EJIO.utils.XMLSerializer(*args, **kwargs)[исходный код]

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

Реализация интерфейса Serializer для формата XML на базе библиотеки xmltodict.

static deserialize(data: str, /, **kwargs: Any) → dict[str, T][исходный код]

Парсит XML строку обратно в словарь, очищая корневой тег root.

Параметры:

  • data – XML-строка.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Десериализованный словарь.

Исключение:

SerializationError – При ошибках десериализации.

static load(filename: str, /, **kwargs: Any) → dict[str, T][исходный код]

Загрузить словарь из XML-файла.

Параметры:

  • filename – Путь к файлу для загрузки.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из файла.

Исключение:

SerializationError – При ошибках десериализации.

static save(data: dict[str, T], filename: str, /, **kwargs: Any) → None[исходный код]

Сохранить словарь в XML-файл.

Параметры:

  • data – Сериализуемый словарь.

  • filename – Путь к файлу для сохранения.

  • kwargs – Ключевые параметры для сереализатора.

Исключение:

SerializationError – При ошибках сериализации.

static serialize(data: dict[str, T], /, **kwargs: Any) → str[исходный код]

Превращает словарь в XML строку, оборачивая её в корневой тег root.

Параметры:

  • data – Сериализуемый словарь.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

XML-строка.

Исключение:

SerializationError – При ошибках сериализации.

class EJIO.utils.YAMLSerializer(*args, **kwargs)[исходный код]

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

Реализация интерфейса Serializer для формата YAML.

static deserialize(data: str, /, **kwargs: Any) → dict[str, T][исходный код]

Преобразовать YAML-строку обратно в словарь.

Параметры:

  • data – YAML-строка.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из строки.

Исключение:

SerializationError – При ошибках десериализации.

static load(filename: str, /, **kwargs: Any) → dict[str, T][исходный код]

Загрузить словарь из YAML-файла.

Параметры:

  • filename – Путь к файлу для загрузки.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Словарь, полученный из файла.

Исключение:

SerializationError – При ошибках десериализации.

static save(data: dict[str, T], filename: str, /, **kwargs: Any) → None[исходный код]

Сохранить словарь в YAML-файл.

Параметры:

  • data – Сериализуемый словарь.

  • filename – Путь к файлу для сохранения.

  • kwargs – Ключевые параметры для сереализатора.

Исключение:

SerializationError – При ошибках сериализации.

static serialize(data: dict[str, T], /, **kwargs: Any) → str[исходный код]

Преобразовать словарь в YAML-строку.

Параметры:

  • data – Сериализуемый словарь.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

YAML-строка.

Исключение:

SerializationError – При ошибках сериализации.

EJIO.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.create_decorator(registry_cls: type[R]) → Callable[[str], Callable[[type[Any]], type[Any]]][исходный код]

Фабрика, создающая именной декоратор для конкретного класса регистра.

Позволяет вместо длинного @register_to(MyRegistry, «key») писать лаконичный @register_my_registry(«key»).

Параметры:

registry_cls – Клас реестра для которого требуется создать декаратор.

Результат:

Кастомный декоратор регистрации объетов.

EJIO.utils.decrypt_payload(cipher_data: bytes, key: str) → bytes[исходный код]

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

Параметры:

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

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

Результат:

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

Исключение:

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

EJIO.utils.deserialize(target_cls: type[T], data: str, serializer_key: str = 'json', /, **kwargs: Any) → T[исходный код]
EJIO.utils.deserialize(target_cls: None, data: str, serializer_key: str = 'json', /, **kwargs: Any) → dict[str, Any]

Десериализовать данные из строки, используя ключ зарегистрированного сериализатора. Поддерживает как объекты Serializable, так и простые словари.

Параметры:

  • target_cls – Класс восстанавливаемого объекта (должен быть наследником Serializable) либо None.

  • data – Сериализованная строка данных.

  • serializer_key – Строковый ключ сериализатора в глобальном регистре.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Новое состояние экземпляра класса target_cls, или словарь, если target_cls == None.

EJIO.utils.encrypt_payload(data: bytes, key: str) → bytes[исходный код]

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

Параметры:

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

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

Результат:

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

Raises:

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

EJIO.utils.generate_secure_key() → str[исходный код]

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

Результат:

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

EJIO.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.generate_weighted_pool(weighted_items: dict[T, float], total_pulls: int, /) → list[T][исходный код]

Генерирует список случайных объектов на основе переданного словаря весов (вероятностей). Автоматически масштабируется и использует многопоточность для ускорения генерации больших пулов.

Пример: generate_weighted_pool({ItemA: 0.7, ItemB: 0.3}, total_pulls=100000)

Параметры:

  • weighted_items – Словарь вида {объект: float_вероятность}. Веса могут не суммироваться в 1.0.

  • total_pulls – Общее количество извлечений (размер результирующего списка).

Результат:

Список случайных объектов.

Исключение:

AttributeError – Если параметры заданы неверно.

EJIO.utils.get_app_root() → Path[исходный код]

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

Результат:

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

EJIO.utils.get_class_hierarchy(base_class: type) → dict[str, Any][исходный код]

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

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

„WidgetContainer“: {

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

}

}

Параметры:

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

Результат:

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

EJIO.utils.import_module_from_path(file_path: str | Path) → ModuleType[исходный код]

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

Параметры:

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

Результат:

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

Исключение:

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

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

EJIO.utils.inject_to_builtins(mapping: dict[str, Any], /) → None[исходный код]
EJIO.utils.inject_to_builtins(name: str, attribute: Any, /) → None

Универсальная функция для инъекции атрибутов во встроенное пространство имен builtins.

Параметры:

  • first – Словарь с объектами или ключ для регистрации.

  • second – Объект для регистрации в случае, если первый аргумент - ключ.

Исключение:

TypeError – Если первый аргумент не словарь и не строка.

EJIO.utils.isset(context: Mapping[str, Any] | ModuleType, key: str) → bool[исходный код]

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

Пример:

if not isset(globals(), «DATABASE_URL»):

print(«Внимание: DATABASE_URL не настроена!»)

context = os.environ if isset(context, «PORT»):

print(f»Приложение будет запущено на порту {context[„PORT“]}»)

Параметры:

  • context – Словарь или объект Mapping (например, os.environ или locals()) или модуль.

  • key – Имя проверяемой переменной (ключ).

Результат:

True, если ключ присутствует и значение не None, иначе False.

EJIO.utils.load(target_cls: Any, filename: str, format_key: str | None = None, /, **kwargs: Any) → Any

Рантайм-воркер: динамически перенаправляет вызов на основе расширения или переданного класса.

EJIO.utils.measure_time(func: F, /) → F[исходный код]
EJIO.utils.measure_time() → Callable[[Any], Any]

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

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

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

Параметры:

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

Результат:

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

EJIO.utils.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.profile_function(file_name: F, /) → F[исходный код]
EJIO.utils.profile_function(file_name: str | None = None, /) → Callable[[F], F]

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

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

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

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

Параметры:

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

Результат:

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

EJIO.utils.register_dataset(key: str) → Callable[[type[Any]], type[Any]]

Специализированный декоратор для регистрации классов в реестре DatasetRegistry.

Параметры:

key – Уникальный строковый ключ-идентификатор для регистрации.

Результат:

Возвращает исходный класс без изменений.

EJIO.utils.register_serializer(key: str) → Callable[[type[Any]], type[Any]]

Специализированный декоратор для регистрации классов в реестре SerializerRegistry.

Параметры:

key – Уникальный строковый ключ-идентификатор для регистрации.

Результат:

Возвращает исходный класс без изменений.

EJIO.utils.register_serializer_for_extension(extension: str, serializer_name: str) → None[исходный код]

Выставляет соответствие между расширением файла и сериализатором, ответственным за файлы с этим расширением.

Параметры:

  • extension – Расширение файла.

  • serializer_name – Имя сериализатора, под которым он зарегестрирован в реестре.

Исключение:

KeyError – Если соответствие для расширения уже задано.

EJIO.utils.register_storage_for_extension(extension: str, storage_name: str) → None[исходный код]

Выставляет соответствие между расширением файла и хранилищем, ответственным за файлы с этим расширением.

Параметры:

  • extension – Расширение файла.

  • storage_name – Имя хранилища, под которым оно зарегестрировано в реестре.

Исключение:

KeyError – Если соответствие для расширения уже задано.

EJIO.utils.require(context: Mapping[str, R] | ModuleType, key: str, error_message: str | None = None) → R[исходный код]

Проверяет наличие переменной в контексте. Если переменная отсутствует или равна None, генерирует исключение RequirementsError.

Пример:

try:

api_token = require(globals(), «API_KEY», «Критическая ошибка: Без API_KEY приложение не запустится!»)

except RequirementsError as e:

print(f»Ошибка инициализации: {e}»)

context = os.environ try:

secret_key = require(context, «OS_SECRET_KEY»)

except RequirementsError as e:

print(f»Старт заблокирован: {e}»)

Параметры:

  • context – Словарь или объект Mapping (например, os.environ или locals()) или модуль.

  • key – Имя обязательной переменной.

  • error_message – Кастомное сообщение об ошибке.

Результат:

Значение переменной, если проверка успешна.

Исключение:

RequirementsError – Если переменная отсутствует или равна None.

class EJIO.utils.resource(key: str, *, is_global: bool = False)[исходный код]

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

Высокоуровневый фасад и контекстный менеджер для ленивой загрузки и кэширования тяжелых ресурсов (графов, байт, изображений).

Поддерживает работу в режиме менеджера контекста (with) и в режиме прямой фабрики.

classmethod get_or_create(key: str, factory: Callable[[...], Any], *args: Any, is_global: bool = False, **kwargs: Any) → Any[исходный код]

Функция-обертка: атомарно проверяет кэш, и если ресурса нет — сама запускает фабрику, кэширует результат и возвращает его.

Параметры:

  • key – Ключ под которым хранится ресурс.

  • factory – Функция, генерирующая ресурс.

  • is_global – Какое хранилище использовать. Если True, то глобальное, иначе - локальное.

  • args – Аргументы для функции-генератора.

  • kwargs – Ключевые аргументы для функции-генератора.

Результат:

Ресурс.

classmethod remove(key: str, *, is_global: bool = False) → bool[исходный код]

Принудительно и потокобезопасно удаляет ресурс из кэша по его ключу. Полезно для инвалидации кэша, когда данные изменились.

Параметры:

  • key – Текстовый маркер ресурса.

  • is_global – Где искать ресурс — в глобальном реестре или локальном контексте.

Результат:

True, если ресурс был успешно найден и удален, иначе False.

property value: Any

Возвращает значение удерживаемого ресурса (None, если он еще не создан).

Результат:

Значение ресурса, или None.

EJIO.utils.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.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.run_on_import(func: Callable[[P], R]) → Callable[[P], R][исходный код]

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

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

Параметры:

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

Результат:

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

EJIO.utils.save(obj: Any, filename: str, format_key: str | None = None, /, **kwargs: Any) → None

Рантайм-воркер: динамически перенаправляет вызов на основе типа данных.

EJIO.utils.save_atomic(target_path: str | Path, write_callback: Callable[[Path], None]) → None[исходный код]

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

Параметры:

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

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

EJIO.utils.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.serialize(obj: T, serializer_key: str = 'json', /, **kwargs: Any) → str[исходный код]
EJIO.utils.serialize(obj: dict[str, Any], serializer_key: str = 'json', /, **kwargs: Any) → str

Сериализовать данные в строку, используя ключ зарегистрированного сериализатора. Поддерживает как объекты Serializable, так и простые словари.

Параметры:

  • obj – Объект, реализующий интерфейс Serializable или словарь.

  • serializer_key – Строковый ключ сериализатора в глобальном регистре.

  • kwargs – Ключевые параметры для сереализатора.

Результат:

Строка с сериализованными данными.

class EJIO.utils.static_property(func: Callable[[...], Any])[исходный код]

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

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