flexirope 0.1.2

Flexible middleware-based method tools

flexirope 🪢

FlexiRope — это мощный и гибкий фреймворк для реализации аспектно-ориентированного программирования (AOP) в Python с использованием концепции "умных оберток" (SmartRopes).

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

✨ Ключевые особенности

• SmartRope: Умный декоратор, который понимает контекст вызова (обычная функция, метод экземпляра, staticmethod, classmethod или property).
• Гибридная асинхронность: Прозрачная поддержка как синхронных, так и асинхронных функций и плагинов.
• Система плагинов: Строгие протоколы SyncPlugin и AsyncPlugin для реализации перехватчиков before и after.
• Слабые ссылки: Использование WeakKeyDictionary для предотвращения утечек памяти при работе с экземплярами классов.
• Фабрика декораторов: Легкое создание кастомных декораторов на базе ваших плагинов.

📦 Установка

uv add flexirope

Или через pip:

pip install flexirope

🚀 Быстрый старт

1. Создание плагина

Плагин может изменять входящие аргументы или результат выполнения.

from flexirope import SyncPlugin

class LoggingPlugin(SyncPlugin):
    def before(self, wire, args, kwargs):
        print(f"Вызов функции: {wire._name} с аргументами {args}")
        return args, kwargs

    def after(self, wire, result):
        print(f"Результат {wire._name}: {result}")
        return result

2. Использование SmartRope

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

from flexirope import SmartRope

# Инициализация с плагинами
log_rope = SmartRope(plugins=[LoggingPlugin()])

@log_rope
def multiply(a, b):
    return a * b

multiply(10, 2)
# Вывод:
# Вызов функции: multiply с аргументами (10, 2)
# Результат multiply: 20

🛠 Продвинутое использование

Работа с классами и слотами

Если ваш класс использует __slots__, используйте декоратор @support_ropes, чтобы добавить поддержку __weakref__, необходимую для работы системы:

from flexirope import SmartRope, support_ropes

@support_ropes
class MyService:
    __slots__ = ("data",)
    
    @SmartRope(plugins=[LoggingPlugin()])
    def process(self, value):
        return value.upper()

Асинхронные плагины

AsyncWire автоматически обрабатывает как синхронные, так и асинхронные плагины:

from flexirope import AsyncPlugin

class AsyncValidator(AsyncPlugin):
    async def before(self, wire, args, kwargs):
        # Асинхронная проверка (например, в БД)
        return args, kwargs

Создание своих декораторов через фабрику

Вы можете превратить любой плагин в удобный декоратор:

from flexirope import rope_factory

# Создаем декоратор @trace()
trace = rope_factory(LoggingPlugin)

@trace
def some_func():
    pass

🏗 Архитектура

• Rope (SmartRope): Точка входа. Управляет жизненным циклом оберток.
• Wire (BaseWire/AsyncWire): Исполнитель. Создается для каждого контекста (экземпляра или класса) и последовательно вызывает плагины.
• Plugins: Протоколы, определяющие логику "до" и "после" основного вызова.

📄 Лицензия

MIT License © 2026 SnayperTihCreator