![logo](https://raw.githubusercontent.com/pomponchik/astrologic/main/docs/assets/logo_3.png)

[![Downloads](https://static.pepy.tech/badge/astrologic/month)](https://pepy.tech/project/astrologic)
[![Downloads](https://static.pepy.tech/badge/astrologic)](https://pepy.tech/project/astrologic)
[![codecov](https://codecov.io/gh/pomponchik/astrologic/graph/badge.svg?token=GC8NH2FGJ9)](https://codecov.io/gh/pomponchik/astrologic)
[![Hits-of-Code](https://hitsofcode.com/github/pomponchik/astrologic?branch=main)](https://hitsofcode.com/github/pomponchik/astrologic/view?branch=main)
[![Tests](https://github.com/pomponchik/astrologic/actions/workflows/tests_and_coverage.yml/badge.svg)](https://github.com/pomponchik/astrologic/actions/workflows/tests_and_coverage.yml)
[![Python versions](https://img.shields.io/pypi/pyversions/astrologic.svg)](https://pypi.python.org/pypi/astrologic)
[![PyPI version](https://badge.fury.io/py/astrologic.svg)](https://badge.fury.io/py/astrologic)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)


Пакет Astrologic содержит ряд инструментов, позволяющих "в рантайме" оптимизировать работу ваших функций или даже конструировать новые функции. Все это достигается за счет парсинга и преобразования [AST](https://docs.python.org/3/library/ast.html) исходной функции. Парсинг происходит полностью "под капотом" и невидим для пользователя.


## Оглавление

- [**Дисклеймер**](#дисклеймер)
- [**Как это работает**](#как-это-работает)
- [**Установка**](#установка)
- [**Включаем и отключаем блоки кода**](#включаем-и-отключаем-блоки-кода)
- [**Оптимизируем хвостовую рекурсию**](#оптимизируем-хвостовую-рекурсию)
- [**Инлайним функции**](#инлайним-функции)


## Дисклеймер

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

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

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


## Как это работает

Интерпретация программы на Python происходит в несколько [этапов](https://habr.com/ru/company/otus/blog/442252/). Если коротко: сначала файл считывается и разбивается на токены, затем из считанных токенов составляется [абстрактное синтаксическое дерево](https://ru.wikipedia.org/wiki/%D0%90%D0%B1%D1%81%D1%82%D1%80%D0%B0%D0%BA%D1%82%D0%BD%D0%BE%D0%B5_%D1%81%D0%B8%D0%BD%D1%82%D0%B0%D0%BA%D1%81%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%BE%D0%B5_%D0%B4%D0%B5%D1%80%D0%B5%D0%B2%D0%BE), на основе дерева компилируется [байт-код](https://ru.wikipedia.org/wiki/%D0%91%D0%B0%D0%B9%D1%82-%D0%BA%D0%BE%D0%B4#:~:text=%D0%9A%D0%BE%D0%BC%D0%BF%D0%B8%D0%BB%D1%8F%D1%82%D0%BE%D1%80%20Clipper%20%D1%81%D0%BE%D0%B7%D0%B4%D0%B0%D0%B5%D1%82%20%D0%B8%D1%81%D0%BF%D0%BE%D0%BB%D0%BD%D1%8F%D0%B5%D0%BC%D1%8B%D0%B9%20%D1%84%D0%B0%D0%B9%D0%BB,%2C%20%D1%81%D0%BE%D0%B4%D0%B5%D1%80%D0%B6%D0%B0%D1%89%D0%B8%D0%B5%20%D0%B1%D0%B0%D0%B9%D1%82%2D%D0%BA%D0%BE%D0%B4%20Java.), ну и тот уже в итоге выполняется виртуальной машиной.

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

Встроенные [средства интроспекции](https://docs.python.org/3/library/inspect.html) позволяют нам извлечь из объекта функции [текст ее исходного кода](https://docs.python.org/3/library/inspect.html#inspect.getsource). Этот текст мы скармливаем функции [```ast.parse()```](https://docs.python.org/3/library/ast.html#ast.parse) и получаем уже нужный нам объект дерева, с которым дальше будем производить все оптимизации. Пакет [ast](https://docs.python.org/3/library/ast.html) также предоставляет готовые классы для обхода дерева и замены отдельных нод, чем мы и пользуемся. После всех манипуляций мы скармливаем уже видоизмененное дерево встроенной функции [```compile()```](https://docs.python.org/3/library/functions.html#compile), чтобы получить порцию байт-кода. Байт-код мы выполняем через [```exec()```](https://docs.python.org/3/library/functions.html#exec), передав туда словарь "пространства имен". ```exec()``` выполняет код инициализации функции как бы в отдельном "виртуальном" модуле. После выполнения инициализации мы достаем функции по имени из переданного в ```exec()``` словаря. Инициализация некоторых функций дергает дополнительные объекты из глобального пространства имен, поэтому, если попытаться выполнить их инициализацию в "голом"
модуле, мы получим ожидаемое исключение. Чтобы этого избежать, мы предварительно вручную (при помощи [```importlib```](https://docs.python.org/3/library/importlib.html)) импортируем модуль, из которого извлечена обрабатываемая нами функция, и все его содержимое перекладываем в тот самый словарь, что мы передаем ```exec()``` в качестве "пространства имен".

Исходя уже из описания процесса ясно, что у него не может не быть побочных эффектов. Вот некоторые из них:

1. Когда мы добавляем новые ноды в AST, они лишены привязки к конкретным строкам исходного кода. Если там случится исключение, в полученном трейсбэке вы получите искаженную информацию.

2. Все эти повторные парсинги-компиляции довольно ресурсоемки.

3. Как выяснилось опытным путем, директива ```global``` в измененных таким образом функциях работает не совсем ожидаемым образом. Она указывает на соответствующую переменную в том "виртуальном" модуле, что был для нее создан при выполнении инициализации через ```exec()```. Вы можете воздействовать из своей функции на глобальную переменную там, в то время как глобальная переменная с тем же именем в том модуле, где фактически расположен исходный код вашей функции, никак затронута не будет.

4. Фактически выполняется не тот код, что написан в вашем коде. Это, собственно, самая большая проблема. Вся суть программирования заключается в том, что вы пишете код и машина __его__ выполняет. А тут она выполняет что-то другое, и вы толком не знаете, что (если хотите таки посмотреть, что именно выполнится, передайте в любой из декораторов данной библиотеки аргумент ```debug_mode_on=True```, тогда в консоли вы увидите текст функции, которая была сгенерирована после изменения AST).

5. Это не будет работать с функциями из замыканий.

6. Нельзя навесить несколько модифицирующих AST декораторов на одну функцию.

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

Это значительные минусы, и, как вы могли прочитать в [дисклеймере](#дисклеймер), я считаю их достаточным основанием, чтобы никогда в практическом смысле не использовать модификации AST. Однако это не мешает нам в развлекательных целях создавать "[магию](https://ru.wikipedia.org/wiki/Monkey_patch)".


## Установка

Установите Astrologic через [pip](https://pypi.org/project/astrologic/):

```
$ pip install astrologic
```


## Включаем и отключаем блоки кода

Простейшим из декораторов библиотеки Astrologic является ```@switcher```. Вот пример его использования:

```python
from astrologic import switcher


@switcher(a=False, b=True)
def function():
  print('begin')
  if a:
    print('block a')
  if b:
    print('block b')
  print('end')

function() # Что будет выведено? Проверьте сами!
```

```@switcher``` проходится по унарным условиям (условиям, в которых только один операнд). Если название переменной, которая фигурирует в данном условии, присутствует в именованных аргументах самого декоратора, он делает одну из двух вещей. Если именованный аргумент равен True, он достает данный блок кода из условия заменяет им само условие. Если аргумент равен False, он удаляет условие вместе с блоком кода. То есть функция из примера выше превращается в:

```python
# Тот код, который будет исполнен на машине. Блок кода "if a:" полностью вырезан, а блок "if b:" вытащен из проверки, в то время как сама проверка тоже вырезана.
def function():
  print('begin')
  print('block b')
  print('end')
```

Использовать данный декоратор вы можете, к примеру, чтобы избежать каких-то проверок в вашем коде, основанных на константах. При инициализации функций в начале работы интерпретатора вы указываете, какие блоки кода вам нужны. По сути, if'ы в данном случае служат не по прямому назначению, а работают разметкой кода.

Поскольку ```@switcher``` редактирует функции на уровне AST, в некоторых случаях применение декоратора может ускорить ваш код, полностью убрав ненужные операции из реально исполняемого машиной кода.

У ```@switcher``` есть ряд ограничений и правил использования, которые необходимо учитывать:

- Декоратор ```@switcher``` должен быть первым в списке декораторов, все остальные можно накладывать только поверх. Если не соблюсти это правило, декораторы, лежащие под ```@switcher```, могут просто исчезнуть, будто их не было.

- Никаких else или else if у блоков if, которыми вы управляете через декоратор! У прочих блоков if использовать else можно, поскольку они никаких не модифицируются.

## Оптимизируем хвостовую рекурсию

Еще один крутой трюк с AST - автоматическая оптимизация [хвостовой рекурсии](https://ru.wikipedia.org/wiki/%D0%A5%D0%B2%D0%BE%D1%81%D1%82%D0%BE%D0%B2%D0%B0%D1%8F_%D1%80%D0%B5%D0%BA%D1%83%D1%80%D1%81%D0%B8%D1%8F). Для этого нам понадобится декоратор ```@no_recursion```:


```python
from astrologic import no_recursion


@no_recursion
def c(b):
    if b == 100000000:
        return b
    return c(b + 1)

print(c(1)) # Попробуйте выполнить это сами!
```

Как вы, вероятно, знаете, максимальная глубина рекурсии в Python ограничена, и обычно составляет около 1000. Однако код из этого примера отработает и вернет корректный результат, поскольку декоратор ```@no_recursion``` автоматически преобразовал рекурсивный код в итеративный. В отличие от других [решений](https://github.com/0scarB/tail-recursive) данной задачи, здесь не потребовалась менять исходный код функции, кроме как навешиванием на нее декоратора.

Надо сказать, против автоматической оптимизации хвостовой рекурсии [высказывался](http://neopythonic.blogspot.com/2009/04/tail-recursion-elimination.html) даже сам [Гвидо Ван Россум](https://en.wikipedia.org/wiki/Guido_van_Rossum). Его доводы довольно весомы, но они относятся, прежде всего, к внедрению данной возможности непосредственно в интерпретатор. Сделать такую оптимизацию бесшовной, с учетом интерпретируемой и гибкой природы Python, действительно невозможно. Однако это не мешает нам сделать это, пойдя на некоторые ограничения.


<details>
<summary>Вот они:</summary>

- Поддерживается только обычная хвостовая рекурсия. Она выглядит вот так:

```python
def function():
  return function()
```

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

- За рекурсию принимается вызов объекта с тем же именем, какое название у функции. Вызов того же имени от другого объекта будет принят за рекурсию!

```python
def function():
  return obj.function() # Декоратор примет это за рекурсию, хотя, очевидно, obj.function != function.
```

- Внутри функции нельзя использовать имена ```is_recursion``` и ```superfunction```. Особенности реализации. Остальные имена можно.

- Стек-трейсы, как и предупреждал Гвидо, могут не совсем корректно отражать реальность.

</details>


## Инлайним функции (экспериментальная фича)

Следующая оптимизация - инлайновые функции. В данном пакете это работает немного иначе, чем вы, вероятно, ожидаете, если знаете про [такую возможность](https://en.cppreference.com/w/c/language/inline) в C++. Здесь метка ```inline``` вешается не на ту функцию, которую мы инлайним, а на ту, __в__ которую.

```python
from astrologic import inline


def a(c):
    d = c
    print(d)

@inline('a')
def b():
    print('lol')
    c = 'kek'
    a(c)

b()
```

На этом примере мы инлайним функцию a() в функцию b(). Имена функций, которые мы инлайним, должны быть перечислены при вызове декоратора ```@inline```.

По итогу код из примера преобразовывается примерно вот в это:

```python
def b():
    print('lol')
    c = 'kek'
    generated_ddea0cfb886b422891e7643ff31efbfa = c
    d = generated_ddea0cfb886b422891e7643ff31efbfa
    print(d)
```

Содержимое функции a() "вклеивается" в функцию b(), с попутным разрешением возможного конфликта имен.

<details>
<summary>Ограничения:</summary>

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

</details>
