flexirope 0.1.3
Flexible middleware-based method tools
License: MIT
Requires Python: >=3.11

# flexirope 🪢

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

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

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

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

## 📦 Установка

```bash
uv add flexirope

```

*Или через pip:*

```bash
pip install flexirope

```

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

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

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

```python
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

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

```python
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__`, необходимую для работы системы:

```python
from flexirope import SmartRope, support_ropes

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

```

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

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

```python
from flexirope import AsyncPlugin

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

```

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

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

```python
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