function-tools 0.10.2

Tools for creating functions

function-tools - это библиотека вспомогательных классов для реализации Функций системы.

Договоримся

Необходимо различать функции - объект Python и бизнес-функцию. В тех местах, где речь будет вестить про Python-функции - они будут написаны с маленькой буквы - функции, про бизнес-функции с большой буквы - Функции. Если абстрагироваться, то система - хранилище данных и функционал, который каким-то образом изменяет данные, при этом достигая ожидаего результата описанного в бизнес требованиях. Таким образом, Функции - это ядро системы и необходимо уделять пристальное внимание тому, как Функции реализованы в системе.

В большинстве случаев Функции имеют следующие признаки:

• Реализованы в виде функций длинной не влазящик ни в один экран монитора;
• Имеют запутанный код с множеством условных конструкций (умеренное количество допустимо);
• Взаимодействие с базой данных выстроено таким образом, как будто вся база данных хранится в оперативной памяти и нет необходимости заботиться о количестве запросов и их оптимальности;
• Наименование функций и названий переменных сокращено настолько, что для понимания кода иногда не хватает простого прочтения и возникает необходимость дебага. Часто это дополнятся размером функций, когда в середине не помнишь, что было в начале.
• Высокая когнитивная нагрузка связанная со сложностью реализации и правилами, для которых нет описания, но они имеют фундаментальное значение в работе Функций.
• Низкий уровень самодокументируемости кода из-за плохой его декомпозиции;
• Перегруженность функций действиями, которые являются вспомогательными и никак не отражают реализованные бизнес требования.
• Отсутствие валидации входных данных и данных при выполнении функции, что позволяет потенциально испортить данные;
• Кеширование данных для работы функции часто замешано код функции;
• Большая вариативность реализаций Функций, что не позволят однозначно найти причину ошибки при ее возникновении в виде Инцидента или Бага (если конечно не сам сегодня эту ошибку совершил).

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

Упрощенная диаграмма классов представлена на Рисунке 1.

Основные компоненты:

Cache

Кеш объектов некоторой указанной сущности. Служит для однократной выборки данных и дальнейшего их использования в рамках функции (Function).

StorageCache

Хранилище кешей. Состоит из кешей и используется для более удобного хранения и доступа к ним.

Helper

Помощник запускаемого объекта. Содержит вспомогательные функции, кеш.

Validator

Валидатор данных. Имеется у Пускателя и Функции.

Function

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

Runner

Пускатель. Умеет запускать как одинчные функции, так и цепочные функции представленные в виде пускателей.

RunnerManager

Менеджер пускателя. Отвечает за создание функций и пускателей и дальнейший их запуск.

Error

Ошибка, возникающая в процессе работы.

Result

Результат исполнения запускаемого объекта.

ResultPresenter

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

Алгоритм работы Функции выглядит следующим образом:

• Создается пускатель;
• Создаются функции и пускатели, которые добавляются в очередь на исполнение пускателю;
• Функции и пускатели создают помощников, которые в свою очередь создают хранилища кешей;
• Перед запуском выполняемых объектов производится валидация на уровне пускателя;
• Производится запуск функций;
• После завершения работы выполняемых объектов и, соответственно, пускателя, производится вывод результата работы пользователю в необходимом виде.

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

С подробной документацией можно ознакомиться на function-tools.readthedocs.io

История изменений

Все изменения проекта должны быть отражены в этом файле.

Формат основан на Keep a Changelog и проект следует Семантическому версионированию.

[x.y.z] - гггг-мм-дд

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

Добавлено

• ПРОЕКТ-ZZZZ PATCH Название задачи или изменения.

• ПРОЕКТ-YYYY MINOR Название задачи или изменения.

• ПРОЕКТ-XXXX MAJOR Название задачи или изменения.

Изменено

Исправлено

Удалено

[0.10.2] - 2024-11-28

Изменение структуры исходного кода. Выделение структуры зависимостей согласно регламента.

Изменено

• PYTD-49 PATCH Изменение структуры исходного кода.

• PYTD-49 PATCH Изменение структуры зависимостей.

[0.10.1] - 2024-04-17

Исправлен метод EntityCache._filter_range для случая, когда в кортеже value переданы одинаковые значения.

Исправлено

• EDUSCHL-21825 PATCH При сборе YMARK и PMARK падает ошибка

[0.10.0] - 2024-02-29

Добавлена поддержка Django 3.1.

Добавлено

• EDUSCHL-18052 MINOR Поднять версию Django до 3.1.14

[0.9.0] - 2024-01-24

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

Добавлено

• EDUSCHL-20274 MINOR Добавлен режим принудительного запуска запускаемых объектов без добавления их в очередь на исполнение.

[0.8.2] - 2023-12-18

В класс EntityCache добавлен метод last.

Добавлено

• EDUSCHL-19606 PATCH В EntityCache добавлен метод last, для получения последнего элемента в отфильтрованных данных.

[0.8.1] - 2023-12-06

Исправление ошибки с импортами.

Исправлено

• EDUSCHL-21007 PATCH Исправлена ошибка, из-за которой в startfunction формировался путь для импортов без корня приложения (должно быть: project.app.subpackage.functions, было: app.subpackage.functions).

[0.8.0] - 2023-12-03

Добавлена генерация uuid для функций, ранеров и менеджеров при генерации исходников функций.

Добавлено

• EDUSCHL-20954 PATCH Добавлена генерация uuid для функций, ранеров и менеджеров при генерации исходников функций.

Удалено

• EDUSCHL-20954 MINOR Удалена совместимость импортов стратегий реализации Функций после переноса из пакета management в корень.

[0.7.3] - 2023-11-24

Учтено возможное наличие ключей со значением None при сортировке в методе _sort_searching_hash_table_keys.

Изменено

• EDUSCHL-20727 PATCH Учтено возможное наличие ключей со значением None при сортировке в методе _sort_searching_hash_table_keys.

[0.7.2] - 2023-09-01

Добавлена возможность сохранения объектов очереди не в одной транзакции.

Добавлено

• EDUSCHL-20417 PATCH Добавлена возможность сохранения объектов очереди не в одной транзакции.

[0.7.1] - 2023-08-30

Исправление возникших ошибок.

Исправлено

• EDUSCHL-20344 PATCH Исправление ошибки с отсутствием указания фильтров, отсеивающих все значения.

[0.7.0] - 2023-08-28

Глубокий рефакторинг кешей. Изменен принцип работы кешей для удовлетворения скорости поиска по ним. Реализованы методы get, first, filter, all, values, values_list. Фильтрация пока работает с eq, in, range. Есть потенциал добавления новых способов поиска.

Добавлено

• EDUSCHL-20344 MINOR Глубокий рефакторинг кешей. Изменен принцип работы кешей для удовлетворения скорости поиска по ним. Реализованы методы get, first, filter, all, values, values_list. Фильтрация пока работает с eq, in, range.

[0.6.3] - 2023-08-23

Добавление метода get в EntityCache.

Добавлено

• EDUSCHL-20344 PATCH Добавлен метод get в EntityCache.

Исправлено

• EDUSCHL-20344 PATCH Исправлена ошибка невозможности указания полей annotate в values и only.

[0.6.2] - 2023-08-21

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

Добавлено

• EDUSCHL-20344 PATCH Добавление возможности получения сформированного начального QuerySet для использования при формировании других кешей.

Изменено

• EDUSCHL-20344 PATCH Оптимизация работы values_list.

[0.6.1] - 2023-08-21

Исправление ошибок связанных с values_list.

Исправлено

• EDUSCHL-20277 PATCH Исправление с отсутствующими полями в values_list.

• EDUSCHL-20277 PATCH Исправление получения списка объектов и их свойств в values_list кеша.

[0.6.0] - 2023-08-19

Рефакторинг и расширение функциональности кешей.

Добавлено

• EDUSCHL-20277 MINOR Добавлена возможность указания Q в additional_filter_params.

• EDUSCHL-20277 MINOR В EntityCache добавлена возможность указания полей annotate в annotate_fields.

• EDUSCHL-20277 MINOR В В EntityCache добавлена возможность указания полей values в values_fields. Помогает вычислять значение необходимых полей. В процессе работы производится преобразования результата в виде словаря к вложенным именованным кортежам, что позволят обращаться к свойствам через точку. Необходимо для единой реализации остального функционала.

• EDUSCHL-20277 MINOR В EntityCache добавлена возможность указания полей exclude в exclude_fields для исключения полей из выборки.

• EDUSCHL-20277 MINOR В EntityCache был изменен интерфейс values_list, добавлен параметр flat для формирования плоского списка значений указанного поля.

• EDUSCHL-20277 MINOR В EntityCache был добавлен метод exists для проверки существования данных в кеше.

• EDUSCHL-20277 MINOR Добавлена возможность управления distinct.

Изменено

• EDUSCHL-20277 PATCH В EntityCache свойство entities заменено на метод all().

• EDUSCHL-20277 PATCH В EntityCache был изменен интерфейс values_list, теперь поля передаются как позиционные аргументы.

• EDUSCHL-20277 PATCH Рефакторинг PeriodicalEntityCache для приведения к рабочему состоянию.

Удалено

• EDUSCHL-20277 MINOR В EntityCache удалено свойство entities. Была произведена замена на метод all().

• EDUSCHL-20277 MINOR В EntityCache в values_list параметр feilds был удален.

[0.5.1] - 2023-08-07

Исправление ошибки инициализации кешей, зависиях от других кешей в хранилище.

Добавлено

• EDUSCHL-20235 PATCH обавлен признак заполнения кеша в EntityCache для возможности использования одних кешей для подготовки других при их формировании в хранилище кешей.

[0.5.0] - 2023-08-06

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

Добавлено

• EDUSCHL-20235 MINOR Добавлена функциональность отложенного заполнения кешей.

• EDUSCHL-20235 MINOR Добавлен интерфейс кешей для унификации их структуры.

• EDUSCHL-20235 MINOR Добавлены точки расширения RunnableObject.

[0.4.0] - 2023-08-04

Исправление ошибки поиска сущностей function-tools в пакетах, которые не являются django-приложениями.

Добавлено

• EDUSCHL-19919 MINOR Добавление параметра FUNCTION_TOOLS_EXCLUDED_APPS для возможности исключения приложений из поиска сущностей.

Изменено

• EDUSCHL-19919 PATCH Перенесены настройки для сборки документации в docs.

Исправлено

• EDUSCHL-19919 PATCH Исправлена ошибка в примере.

0.3.9

• EDUSCHL-19156 Убрана часть кода вызывающая ошибку поиска сущностей, при наличии подключенного приложения, находящегося выше по иерархии, чем, например, функция;
• EDUSCHL-19156 Добавление описания команды создания Функции;
• EDUSCHL-19156 Перевод команды создания Функций на использование стратегий из Хранилища;
• EDUSCHL-19156 Исправление опечаток.

0.3.8

• EDUSCHL-18335 Поиск модулей будет осуществляться только в зарегистрированных приложениях без рекурсивного поиска.

0.3.7

• EDUSCHL-14355 Добавление on_delete в модель Entity.

0.3.6

• EDUSCHL-18158 Исправление шаблонов для поиска модулей с сущностями function_tools.

0.3.5

• EDUSCHL-18043 Убрано дефолтное значение параметра strategy команды startfunction.

0.3.4

• EDUSCHL-18043 Наполнение стратегий реализаций функций перенесено в команду, его использующую.

0.3.3

• EDUSCHL-17752 Добавление обработчика сигнала function_tools_after_migrate_receiver вызываемого после прогона миграций;
• EDUSCHL-17752 Добавление методов для формирования карт соответствия менеджеров и запускаемых объектов.

0.3.2

• EDUSCHL-17752 Исправление ошибки с работой с путями.

0.3.1

• EDUSCHL-17752 Исправление ошибки с работой с путями.

0.3.0

• EDUSCHL-17752 Добавлена единая модель для регистрации сущностей в базе данных;
• EDUSCHL-17752 В ранер добавлен метод _populate_queue_by_runnable_classes запускаемый при инициализации и добавляющий запускаемые объекты в очередь;
• EDUSCHL-17752 Добавлена команда register_entities для регистрации сущностей в БД;
• EDUSCHL-17752 Verbose_name и tags сущностей преобразованы в методы и свойства классов. Здесь могут быть проблемы с совместимостью;
• EDUSCHL-17752 Внесены изменения в шаблон Функции;

0.2.6

• EDUSCHL-17752 Убран вывод ошибки, чтобы не вводить в заблуждение;
• EDUSCHL-17752 Добавление докстрингов.

0.2.5

• EDUSCHL-17752 В шаблон функции в apps.py добавлен verbose_name и заменен label;
• EDUSCHL-17752 Добавление хранилища кешей с возможностью патчинга при назначении глобального хелпера.

0.2.4

• EDUSCHL-17935 Преобразование функции регистрации Функций системы в команду.

0.2.3

• EDUSCHL-17752 Временный фикс ошибки импорта модулей со стратегиями.

0.2.2

• EDUSCHL-17810 Исправление ошибки при первом прогоне миграций.

0.2.1

• EDUSCHL-17810 Исправление MANIFEST.in для добавления шаблонов файлов в пакет;
• EDUSCHL-17810 Исправление ошибки при первом прогоне миграций.

0.2.0

• EDUSCHL-17810 Восстановление сборки документации;
• EDUSCHL-17810 Понижение версии Django до 1.11.29;
• EDUSCHL-17810 Добавление шаблона функции;
• EDUSCHL-17810 Добавление примера;
• EDUSCHL-17810 Добавление возможности постановки в очередь сразу нескольких запускаемых объектов.

0.1.19

• BOBUH-19996 Добавлена возможность обновлять очередь ранера "на ходу"
• BOBUH-19996 Добавлена возможность принимать результат предыдущего ранера в текущем в цепочке запуска
• BOBUH-19996 Добавлен базовый класс функции с примесью глобального помощника

0.1.18

• Исправление ошибки перепривязки идентификаторов значений внешних ключей.

0.1.17

• Добавление миграции, в связи с изменениями в m3-db-utils.

0.1.16

• Добавление недостающих файлов в MANIFEST.in.

0.1.15

• BOBUH-18883 Исправление ошибки с формированием сообщения об ошибке.

0.1.14

• BOBUH-18886 Исправлены все орфографические ошибки в проекте;
• BOBUH-18886 Удалены неиспользуемые методы init в шаблонах функций;
• BOBUH-18372 Доработки функции генерации исходного кода функций;
• BOBUH-18372 Добавление логики поиска шаблонов функций с указанием их имени в стратегии реализации функций;
• BOBUH-18372 Исправление ошибки с отсутствующим запуском валидации при использовании небазового ранера;

0.1.13

• BOBUH-18382 Исправление ошибки object.init() takes no parameters вызванной множественным наследованием;
• BOBUH-18382 Исправление опечаток.

0.1.12

• BOBUH-18382 Преобразование перечисления со стратениями создания функци в модель-перечисление для дальнейшего расширения из продуктов;
• BOBUH-18382 Рефакторинг;
• BOBUH-18382 Добавление зависимости m3_db_utils;
• BOBUH-18382 Исправление ошибки с неверным проставлением глобального помощника;
• BOBUH-18382 Работа с результатом приведена к единому виду с остальными сущностями для более удобного расширения поведения;
• BOBUH-18382 Расширена логика создания помощника и валидатора с использованием базовых классов;
• BOBUH-18382 Добавлены результаты работы ранера и функции в шаблон генерируемой функции.

0.1.11

• BOBUH-18382 Добавление классов помощников и валидаторов по умолчанию.

0.1.10

• BOBUH-18382 Доработка шаблона actions.py-tpl для более удобной расширяемости при наследовании;
• BOBUH-18382 Добавление модуля для перечислений в шаблон функции;
• BOBUH-18382 Добавление методов получения классов помощника и валидатора функции для дальнейшего более удобного расширения при наследовании;
• BOBUH-18382 Доработка шаблона actions.py-tpl для более удобного дальнейшего расширения поведения;
• BOBUH-18382 Добавление точек расширения у базового помощника;
• BOBUH-18382 Добавление точки расширения менеджера;
• BOBUH-18382 Добавление точек расширения в миксины помощника, валидатора, глобального помощника;
• BOBUH-18382 Доработка шаблона синхронной функции.

0.1.9

• BOBUH-18362 Добавление тегов в зарегистрированную функцию;
• BOBUH-18362 Дополнен шаблон actions.py;
• BOBUH-18382 Выделение дополнительных точек расширения поведения менеджера ранера и запускаемых объектов.

0.1.8

• Добавление регистрации функции системы в БД;
• Реализован генератор функции.

0.1.7

• Поднятие версии Django.

0.1.6

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

0.1.4

• Добавление MANIFEST.in для корректной сборки и дальнейшей установки пакета;

0.1.3

• Добавление возможности выполнения отложенного сохранения объектов, даже в случае наличия ошибок в процессе работы функции;
• Добавление свойств helper и global_helper в соответствующие миксины;
• Добавлена возможность расширения запускаемого объекта перед и после валидации;
• Добавлен декоратор для методов функции, запускаемых только в случае отсутствия зарегистрированных ошибок, полученных в процессе работы функции.

0.1.2

• Поднята версия Django до 2.2.4

0.1.1

• Добавление ссылок на документацию.