python_pd/04_functions/09_functools.ipynb

{
 "metadata": {
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.0-final"
  },
  "orig_nbformat": 2,
  "kernelspec": {
   "name": "python3",
   "display_name": "Python 3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2,
 "cells": [
  {
   "source": [
    "# Модуль ```functools```\n",
    "\n",
    "Модуль ```functools``` содержит большое количество декораторов и функций для разных задачь. Туда включены: \n",
    "- декораторы для кеширования результатов функций (```cache```, ```lru_cache``` и др.);\n",
    "- декораторы для облегчения написания декораторов и классов(```wraps```, ```total_ordering```);\n",
    "- декораторы для сокращения количества передаваемых аргументов (```partial```);\n",
    "- и другие.\n",
    "\n",
    "Рассмотрим некоторые из них.\n",
    "\n",
    "Декоратор ```lru_cache(maxsize=128, typed=False)``` предназначен для [LRU кеширования](https://en.wikipedia.org/wiki/Cache_replacement_policies#Least_recently_used_(LRU)). Это означает, что он \"запоминает\" результаты и аргументы вызова функций, и, когда функция повторно вызывается с такими же аргументами, то результат не вычисляется, а возвращается сохраненное значение. Это очень удобно, если функция выполняет тяжеловесные вычисления. \n",
    "\n",
    "```lru_cache``` использует в качестве кэша словарь, поэтому все аргументы должны быть хешируемыми.\n",
    "\n",
    "Аргумент ```maxsize``` определяет размер памяти, ```lru_cache``` удаляет из кеша слишком старые результаты, тем самым экономя память. Если ```maxsize``` установлен в ```None```, кэш может возрастать бесконечно. Также функция наиболее эффективна, если ```maxsize``` это степень двойки.\n",
    "\n",
    "Декоратор ```lru_cache``` может учитывать типы аргументов, для этого используется аргумент ```typed```. Если он установлен в ```True```, аргументы функции с разными типами будут кэшироваться отдельно. Например, ```f(3)``` и ```f(3.0)``` будут считаться разными вызовами, возвращающие, возможно, различный результат.\n",
    "\n",
    "Чтобы помочь измерить эффективность кэширования и отрегулировать размер кэша, обёрнутая функция дополняется функцией ```cache_info()```, возвращающая ```namedtuple```, показывающий попадания в кэш, промахи, максимальный размер и текущий размер. В многопоточном окружении, количество попаданий и промахов будет приблизительным.\n",
    "\n",
    "Также имеется функция ```cache_clear()``` для очистки кэша.\n",
    "\n",
    "Оригинальная функция доступна через атрибут ```__wrapped__```."
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "output_type": "stream",
     "name": "stdout",
     "text": [
      "factorial(5) = 120\nfactorial(10) = 3628800\nfactorial(100) = 93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000\nfactorial(6) = 720\nfactorial(100) = 93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000\nfactorial(5) = 120\n--------------------------------------------------\nCacheInfo(hits=3, misses=208, maxsize=5, currsize=5)\n"
     ]
    }
   ],
   "source": [
    "from functools import lru_cache\n",
    "\n",
    "@lru_cache(maxsize=5)\n",
    "def factorial(n):\n",
    "    if n == 0:\n",
    "        return 1\n",
    "    return n * factorial(n - 1)\n",
    "\n",
    "\n",
    "print(f'{factorial(5) = }')\n",
    "print(f'{factorial(10) = }')\n",
    "print(f'{factorial(100) = }')\n",
    "print(f'{factorial(6) = }')\n",
    "print(f'{factorial(100) = }')\n",
    "print(f'{factorial(5) = }')\n",
    "print('-' * 50)\n",
    "\n",
    "print(f'{factorial.cache_info()}')"
   ]
  },
  {
   "source": [
    "Декоратор ```partial(func, *args, **keywords)``` используется для частичного определения аргументов функции до ее непосредственного вызова. В момент вызова декорируемой функции ```func```, помимо явно передаваемых аргументов, будут переданы аргументы из ```args``` и ```keywords``` декоратора ```partial```."
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "output_type": "stream",
     "name": "stdout",
     "text": [
      "min_5 = functools.partial(<built-in function min>, 5)\ntype(min_5) = <class 'functools.partial'>\nmin_5(10, 2) = 2\nmin_5(10) = 5\n"
     ]
    }
   ],
   "source": [
    "from functools import partial\n",
    "\n",
    "min_5 = partial(min, 5)\n",
    "print(f'{min_5 = }')\n",
    "print(f'{type(min_5) = }')\n",
    "\n",
    "print(f'{min_5(10, 2) = }')\n",
    "print(f'{min_5(10) = }')"
   ]
  },
  {
   "source": [
    "Это будет эквивалентно"
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sum_5 = lambda *args: min(5, *args)"
   ]
  },
  {
   "source": [
    "В других языках программирования можно создать несколько функций с одним названием, но с разными типами аргументов.\n",
    "\n",
    "Как проделать тоже самое только в Python? Конечно, вы можете вручную проверять типы аргументов, но это не всегда бывает удобно. В модуле ```functools``` есть декоратор ```singledispatch```, который позволяет реализовать этот функционал.\n",
    "\n",
    "Реализуем аналог функции ```range``` в нескольких вариантах исполнения: для целых чисел и для чисел с плавающей точкой.\n",
    "\n",
    "Декоратором ```singledispatch``` декорируется базовая функция, она будет использоваться, если никакие остальные реализации не подходят.\n",
    "\n",
    "С помощью метода ```register``` отмечаются остальные реализации. Он может принимать тип, для которого эта реализация будет использоваться. \n",
    "\n",
    "У этого подхода есть один недостаток. Предполагается, что у всех позиционных аргументов тип одинаковый.\n",
    "\n",
    "Подробное описание и большое количество примеров см. в [документации](https://docs.python.org/3/library/functools.html)."
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "output_type": "stream",
     "name": "stdout",
     "text": [
      "1\n2\n-------------------------\n1.0\n1.5\n2.0\n2.5\n-------------------------\nbase func\n"
     ]
    }
   ],
   "source": [
    "from functools import singledispatch\n",
    "\n",
    "@singledispatch\n",
    "def my_range(start, stop, step):\n",
    "    print('base func')\n",
    "\n",
    "@my_range.register(int)\n",
    "def _(start, stop, step):\n",
    "    for i in range(start, stop, step):\n",
    "        print(i)\n",
    "\n",
    "@my_range.register(float)\n",
    "def _(start, stop, step):\n",
    "    while start < stop:\n",
    "        print(start)\n",
    "        start += step\n",
    "\n",
    "\n",
    "my_range(1, 3, 1)\n",
    "print('-' * 25)\n",
    "my_range(1., 3., 0.5)\n",
    "print('-' * 25)\n",
    "my_range('a', 'b', 'c')"
   ]
  },
  {
   "source": [
    "Функция ```update_wrapper``` и ее аналог декоратор ```wraps``` нужны для копирования служебной информации присоздании собственных декораторов: имени функции, документации и другого."
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "output_type": "stream",
     "name": "stdout",
     "text": [
      "bar\nБесполезная функция\n"
     ]
    }
   ],
   "source": [
    "from functools import wraps\n",
    "\n",
    "def foo(f):\n",
    "    @wraps(f)\n",
    "    def inner():\n",
    "        print(f'{f.__name__}')\n",
    "        f()\n",
    "    return inner\n",
    "\n",
    "@foo\n",
    "def bar():\n",
    "    \"\"\"Бесполезная функция\"\"\"\n",
    "    print('(－‸ლ)')\n",
    "\n",
    "print(f'{bar.__name__}')\n",
    "print(f'{bar.__doc__}')"
   ]
  },
  {
   "source": [
    "Декоратор ```total_ordering``` очень полезен при работе с классами. Он позволяет автоматически реализовывать все виды операторов сравнения. Для этого достаточно, чтобы класс реализовал только два метода: метод сравнения на равенство ```__eq__``` и один из методов ```__lt__```, ```__le__```, ```__gt__```, или ```__ge__```. Это существенно упрощает работу."
   ],
   "cell_type": "markdown",
   "metadata": {}
  },
  {
   "source": [
    "# Полезные ссылки\n",
    "\n",
    "- [Документация](https://docs.python.org/3/library/functools.html)\n",
    "- [PEP 443 -- Single-dispatch generic functions](https://www.python.org/dev/peps/pep-0443/)"
   ],
   "cell_type": "markdown",
   "metadata": {}
  }
 ]
}