EJIO.utils.struct package

Submodules

EJIO.utils.struct.deque module

class EJIO.utils.struct.deque.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

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

Результат:

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

EJIO.utils.struct.dict module

class EJIO.utils.struct.dict.Dict(*args: Any, **kwargs: Any)

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

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

clear() → None

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

EJIO.utils.struct.err module

exception EJIO.utils.struct.err.RegistryKeyError(message: str)

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

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

exception EJIO.utils.struct.err.RegistryTypeError(message: str)

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

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

EJIO.utils.struct.list module

class EJIO.utils.struct.list.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

EJIO.utils.struct.queue module

class EJIO.utils.struct.queue.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

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

Результат:

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

EJIO.utils.struct.registry module

class EJIO.utils.struct.registry.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 – Если ключ отсутствует в реестре.

EJIO.utils.struct.registry.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.struct.stack module

class EJIO.utils.struct.stack.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

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

Результат:

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

EJIO.utils.struct.tree module

class EJIO.utils.struct.tree.TreeNode(*args, **kwargs)

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

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

abstract property children: Iterable[TreeNode]

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

Результат:

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

Исключение:

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

abstractmethod destroy() → None

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

Исключение:

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

abstract property value: Any

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

Результат:

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

Исключение:

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

class EJIO.utils.struct.tree.TreeTraverser(*args: tuple[object, ...], **kwargs: dict[str, object])

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

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

classmethod breadth_first_search(root: T) → Generator[T, None, None]

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

Параметры:

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

Yields:

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

classmethod depth_first_search(root: T) → Generator[T, None, None]

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

Параметры:

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

Yields:

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

Module contents

class EJIO.utils.struct.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.struct.Dict(*args: Any, **kwargs: Any)

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

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

clear() → None

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

class EJIO.utils.struct.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.struct.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.struct.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.struct.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.struct.TreeNode(*args, **kwargs)

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

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

abstract property children: Iterable[TreeNode]

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

Результат:

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

Исключение:

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

abstractmethod destroy() → None

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

Исключение:

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

abstract property value: Any

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

Результат:

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

Исключение:

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

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

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

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

classmethod breadth_first_search(root: T) → Generator[T, None, None]

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

Параметры:

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

Yields:

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

classmethod depth_first_search(root: T) → Generator[T, None, None]

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

Параметры:

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

Yields:

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

EJIO.utils.struct.create_decorator(registry_cls: type[R]) → Callable[[str], Callable[[type[Any]], type[Any]]]

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

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

Параметры:

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

Результат:

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