06 - Typing Hints/06 - Typing Hints.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Type Hints"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Динамично vs. статично типизиране. Round 2\n",
    "\n",
    "Динамичното типизиране позволява гъвкавост, но това идва и със своите недостатъци от гледна точка на поддръжката и четимостта на кода.\n",
    "\n",
    "Например, ако имаме следната функция:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "def validate_serial_number(serial_number):\n",
    "    pass  # definition is irrelevant for this example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ако нямаме поглед над имплементацията на функцията (или пък имаме, но не е тривиално да се прецени точно имплементацията с какви типове борави), то тогава как да разберем `serial_number` дали да ѝ го подадем като `int` или `str`? Или пък може да е `list` от `int`-ове дори?\n",
    "\n",
    "Също така, от името на функцията не става много ясно тя какво връща - дали не връща нищо, а само изпълнява проверки и странични ефекти, или пък проверява валидността на номера и връща `bool`, или пък връща някакъв тип за грешка при неуспех, а `None` при успех?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Type Hints and `mypy`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "От Python 3.5 насам можем да пишем \"подсказки\" за очаквания тип (или очакваните типове, в случай че са повече от един).\n",
    "\n",
    "В случая функцията можем да я анотираме по следния начин:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "def validate_serial_number(serial_number: str) -> bool:\n",
    "    pass  # ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Трябва да се отбележи, че тези анотации са само hints (\"подсказки\" за програмиста), т.е. не получаваме поведението на статично типизираните езици, тъй като интерпретатора не следи за спазването на анотациите:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Passing `int`:  3\n",
      "Passing `str`:  12\n"
     ]
    }
   ],
   "source": [
    "def add(a: int, b: int) -> int:\n",
    "    return a + b\n",
    "\n",
    "print(\"Passing `int`: \", add(1, 2))\n",
    "print(\"Passing `str`: \", add(\"1\", \"2\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Това въпросно следене може да стане чрез т.нар. \"type checkers\". Най-използваният е [mypy](http://mypy-lang.org/).\n",
    "\n",
    "В PyCharm би трябвало по подразбиране да е включено, докато във VS Code може да се включи от настройките на [Pylance extension-a](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance):\n",
    "\n",
    "![Pylance setting](assets/pylance-setting.png)\n",
    "\n",
    "При включването на настройката за пръв път би трябвало да се покаже долу вдясно диалогов попъп, от който да може да се инсталира `mypy` автоматично."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "След включването, всяка некоректност ще се показва като грешка във VSCode по подобен начин:\n",
    "\n",
    "![mypy in action](assets/mypy-in-action.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Синтаксис и особености на анотациите"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Анотациите са добавени в Python 3.0 и оригинално са нямали конкретна семантика или общоприета употреба. Понеже са интуитивно удобни за указване на типове, [PEP484](https://peps.python.org/pep-0484/) и [PEP526](https://www.python.org/dev/peps/pep-0526/) предлагат и стандартизират точно тази им употреба.\n",
    "\n",
    "Анотации могат да се добавят към променливи и функции. Те отиват в `__annotations__` списъка на модула или на функцията, респективно. Това означава, че могат и runtime да бъдат достъпни:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "__annotations__ = {'variable': <class 'int'>}\n",
      "function.__annotations__ = {'f': <class 'float'>, 'b': <class 'bool'>, 'return': <class 'int'>}\n"
     ]
    }
   ],
   "source": [
    "variable: int = 42\n",
    "\n",
    "print(f\"{__annotations__ = }\")  # module.__annotations__ keeps the annotations of all variables in the module\n",
    "\n",
    "\n",
    "def function(f: float, b: bool = True) -> int:\n",
    "    return int(f) if b else 0  # this is the most meaningless function ever\n",
    "\n",
    "print(f\"{function.__annotations__ = }\")  # functions have that dunder as well"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Забележка*: По общоприета питонска конвенция за стил, интервали около `=` на именованите аргументи се слагат ако има анотация, но се пропускат ако няма:\n",
    "\n",
    "ОК:\n",
    "```python\n",
    "def foo(a: int, b: int = 0) -> int:\n",
    "    return a + b\n",
    "\n",
    "def foo(a, b=0):\n",
    "    return a + b\n",
    "```\n",
    "\n",
    "Not quite OK:\n",
    "\n",
    "```python\n",
    "def foo(a: int, b: int=0) -> int:\n",
    "    return a + b\n",
    "\n",
    "def foo(a, b = 0):\n",
    "    return a + b\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Забележка 2*: Възможна е анотация на имe без да му бъде присвоявана стойност. Опитът за достъп обаче преди да му бъде присвоена такава впоследствие ще доведе до грешка, понеже още не е дефинирана:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "ename": "NameError",
     "evalue": "name 'name' is not defined",
     "output_type": "error",
     "traceback": [
      "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m",
      "\u001b[0;31mNameError\u001b[0m                                 Traceback (most recent call last)",
      "Cell \u001b[0;32mIn [5], line 3\u001b[0m\n\u001b[1;32m      1\u001b[0m name: \u001b[39mstr\u001b[39m\n\u001b[0;32m----> 3\u001b[0m \u001b[39mprint\u001b[39m(name)\n",
      "\u001b[0;31mNameError\u001b[0m: name 'name' is not defined"
     ]
    }
   ],
   "source": [
    "name: str\n",
    "\n",
    "print(name)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Анотиране на различните вградени типове"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Както видяхме, използваме самият тип за да го анотираме, т.е. `bool`, `int`, `float`, `complex`, `str`, `bytes`, `None` и т.н. са валидни в анотации. (да, `None` освен стойност, е и тип сам по себе си)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "def i_wanna_print(something: str, terminator: str = \"\\n\") -> None:\n",
    "    print(something, end=terminator)\n",
    "\n",
    "def extract_nums_from_input_row(row: str) -> list:\n",
    "    return list(map(int, row.split()))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Във функцията `extract_nums_from_input_row` в горният пример обаче не знаем всичко за return типа. Знаем, че е `list`, но лист от какво?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Проблемът с такива generic типове като `list`, `tuple`, `dict`, `set` и т.н. решаваме като укажем типа на елементите в тях в квадратни скоби. От Python 3.9 насам можем директно да ползваме builtin типовете, но за версии 3.5 до 3.8 вкл. трябва да импортнем подходящите класове от `typing` модула:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Python 3.5 to 3.8\n",
    "\n",
    "from typing import List, Tuple, Dict\n",
    "\n",
    "def extract_nums_from_input_row(row: str) -> List[int]:\n",
    "    return list(map(int, row.split()))\n",
    "\n",
    "def dot_product(a: Tuple[int, int, int], b: Tuple[int, int, int]) -> int:\n",
    "    return sum(x * y for x, y in zip(a, b))\n",
    "\n",
    "def bind_names_to_ages(names: List[str], ages: List[int]) -> Dict[str, int]:\n",
    "    return dict(zip(names, ages))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Python 3.9+\n",
    "\n",
    "def extract_nums_from_input_row(row: str) -> list[int]:\n",
    "    return list(map(int, row.split()))\n",
    "\n",
    "def dot_product(a: tuple[int, int, int], b: tuple[int, int, int]) -> int:\n",
    "    return sum(x * y for x, y in zip(a, b))\n",
    "\n",
    "def bind_names_to_ages(names: list[str], ages: list[int]) -> dict[str, int]:\n",
    "    return dict(zip(names, ages))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ако искаме `tuple` да има точно 2 елемента от тип `int` например, можем да го анотираме като `Tuple[int, int]`. Ако искаме да има произволен брой елементи от тип `int`, можем да го анотираме като `Tuple[int, ...]`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "def calculate_polynomial(coefficients: tuple[float, ...], x: float) -> float:\n",
    "    return sum(k * (x ** n) for n, k in enumerate(reversed(coefficients)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "При указване на `*args` и/или `**kwargs` е нужно да укажем само типа на съответните елементи, без `tuple` или `dict`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "def calculate_polynomial(*coefficients: float, x: float) -> float:\n",
    "    return sum(k * (x ** n) for n, k in enumerate(reversed(coefficients)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "За удобство можем да си създваме alias-и за различни типове, които да ги използваме по-късно:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "Vector3D = tuple[float, float, float]\n",
    "\n",
    "def dot_product(a: Vector3D, b: Vector3D) -> float:\n",
    "    return sum(x * y for x, y in zip(a, b))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В случай, че искаме да анотираме функция, която например подаваме като параметър, ползвамe `Callable`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[3, 2, 1]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from typing import Callable\n",
    "\n",
    "def bubble_sort(arr: list[int], comparator: Callable[[int, int], bool]) -> list[int]:\n",
    "    arr = arr.copy()\n",
    "    for _ in range(len(arr)):\n",
    "        for j in range(len(arr) - 1):\n",
    "            if not comparator(arr[j], arr[j + 1]):\n",
    "                arr[j], arr[j + 1] = arr[j + 1], arr[j]\n",
    "    return arr\n",
    "\n",
    "bubble_sort([1, 2, 3], lambda x, y: x > y)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Union` и `Optional`\n",
    "\n",
    "Понякога можем да поддържаме по няколко възможни типа. Целта на `Union` е да \"обедини\" тези типове в един. Например, ако искаме да можем да подаваме и `int` и `str` като аргументи на функция, можем да го анотираме като `Union[int, str]`  или  `Union[str, int]`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Union\n",
    "\n",
    "def is_serial_number_valid(serial_number: Union[str, int]) -> bool:\n",
    "    serial = str(serial_number)\n",
    "    return (\n",
    "        len(serial) == 10 \n",
    "        and serial.isdigit() \n",
    "        and serial[-1] == sum(map(int, serial[:-1])) % 10\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "От Python 3.10 насам можем да използваме оператора `|` вместо `Union`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(-3099430.4+370440j)"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def is_serial_number_valid(serial_number: str | int) -> bool:\n",
    "    serial = str(serial_number)\n",
    "    return (\n",
    "        len(serial) == 10 \n",
    "        and serial.isdigit() \n",
    "        and serial[-1] == sum(map(int, serial[:-1])) % 10\n",
    "    )\n",
    "\n",
    "def calculate_polynomial(*coefficients: int | float | complex, x: int | float | complex) -> complex:\n",
    "    return complex(sum(k * (x ** n) for n, k in enumerate(reversed(coefficients))))\n",
    "\n",
    "calculate_polynomial(-1, 5j, 6.9, 0, 94, x=42)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Много често се налага да имаме стойност по подразбиране `None` вместо такава на даден тип или пък да връщаме `None` вместо стойност от даден тип. Това е и идеята на `Optional`, който е тип на практика еквивалентен на `Union` с `None`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hashlib\n",
    "\n",
    "from typing import Optional\n",
    "\n",
    "def hash_password(password: str, salt: Optional[str] = None) -> bytes:\n",
    "    hash = hashlib.sha256(password.encode())\n",
    "    if salt is not None:\n",
    "        hash.update(salt.encode())\n",
    "    return hash.digest()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Equivalent:\n",
    "\n",
    "import hashlib\n",
    "\n",
    "def hash_password(password: str, salt: str | None = None) -> bytes:\n",
    "    hash = hashlib.sha256(password.encode())\n",
    "    if salt is not None:\n",
    "        hash.update(salt.encode())\n",
    "    return hash.digest()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `Any`\n",
    "\n",
    "По подразбиране, ако на променлива/аргумент/return type липсва анотация, то тя/той е от тип `Any`.\n",
    "\n",
    "Ако искаме все пак експлицитно да анотираме даден тип като произволен, то можем да го направим с `Any`. Type-checker-ите няма да хвърлят грешка, който и тип да подаваме като стойност на нещо, което се очаква да е от тип `Any`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Any\n",
    "\n",
    "def i_wanna_print(something: Any, terminator: str = \"\\n\") -> None:\n",
    "    print(something, end=terminator)\n",
    "\n",
    "def play_audio(filename: str, options: dict[str, Any]) -> None:\n",
    "    if options[\"BITRATE\"] == 320:\n",
    "        print(\"Playing in high quality\")\n",
    "    \n",
    "    if options[\"LOOP\"] == True:\n",
    "        print(\"Playing in loop\")\n",
    "\n",
    "    #..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Generics\n",
    "\n",
    "В някои случаи обаче ако използваме `Any` директно всъщност заличаваме информация, която ни е нужна после. \n",
    "\n",
    "Например нека разгледаме следната функция:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "import random\n",
    "from typing import Any\n",
    "\n",
    "def shuffled(l: list[Any]) -> list[Any]:\n",
    "    return random.sample(l, len(l))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " Ако я използваме обаче в следния контекст:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Counter({'♦': 5, '♠': 5, '♣': 2, '♥': 1})\n"
     ]
    }
   ],
   "source": [
    "\n",
    "suits = \"♠♥♦♣\"\n",
    "ranks = \"AKQJT98765432\"\n",
    "\n",
    "brand_new_deck = [f\"{rank}{suit}\" for suit in suits for rank in ranks] # -> list[str]\n",
    "\n",
    "shuffled_deck = shuffled(brand_new_deck) # -> list[Any] !!!\n",
    "\n",
    "# Сега `shuffled_deck` вече е list[Any] вместо list[str]\n",
    "# т.е. изгубихме типовата информация, която би трябвало да имаме.\n",
    "\n",
    "from collections import Counter\n",
    "suits_dealt = Counter(card[1] for card in shuffled_deck[::4]) # ⚠️ card[1] ще ни го дава като опит за индексиране на `Any`, а не `str`\n",
    "print(suits_dealt)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "За да се справим с този проблем трябва да обявим такива типови параметри като generics чрез `TypeVar`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import TypeVar\n",
    "\n",
    "T = TypeVar(\"T\")\n",
    "def shuffled(l: list[T]) -> list[T]:\n",
    "    return random.sample(l, len(l))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "С примерът горе статичния type-checker ще знае, че каквито елементи има листът, който е подаден като аргумент на `shuffled`, такива и ще бъдат елементите на върнатия лист."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Можем и да дадем ограничения за `TypeVar`-овете. Ако искаме в горния пример `T` да ни бъде `int` или `str`, можем да напишем:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import TypeVar\n",
    "\n",
    "T = TypeVar(\"T\", int, str)\n",
    "def shuffled(l: list[T]) -> list[T]:\n",
    "    return random.sample(l, len(l))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Собствени типове\n",
    "\n",
    "Нашите собствени класове също могат да се използват като типове:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Person:\n",
    "    def __init__(self, name: str, age: int) -> None:\n",
    "        self.name = name\n",
    "        self.age = age\n",
    "\n",
    "    def __repr__(self) -> str:\n",
    "        return f\"Person(name={self.name}, age={self.age})\"\n",
    "\n",
    "    def to_dict(self) -> dict[str, Any]:\n",
    "        return {\"name\": self.name, \"age\": self.age}\n",
    "\n",
    "\n",
    "def get_people() -> list[Person]:\n",
    "    return [Person(\"John\", 42), Person(\"Jane\", 37)]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Тук особеното е, че в дефиницията на методи няма нужда да анотираме `self` - той винаги ще е от типа на класа."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Когато обаче имаме метод, който приема или връща обект от типа на класа, към който е, съществуват особености за различните версии на езика. В Python 3.10 не е грешка да се използва името на класа още в дефиницията му, докато в по-старите версии - е. От Python 3.7+ може да се импортне `from __future__ import annotations`, за да работи това, докато за по-стари версии решението е просто да се напише името на класа като стринг в анотацията."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Person:\n",
    "    def __init__(self, name: str, age: int) -> None:\n",
    "        self.name = name\n",
    "        self.age = age\n",
    "\n",
    "    def __repr__(self) -> str:\n",
    "        return f\"Person(name={self.name}, age={self.age})\"\n",
    "\n",
    "    def to_dict(self) -> dict[str, Any]:\n",
    "        return {\"name\": self.name, \"age\": self.age}\n",
    "\n",
    "    # Python 3.10+ way\n",
    "    # or for Python 3.7-3.9 you also have to add `from __future__ import annotations`\n",
    "    @classmethod\n",
    "    def from_dict(cls, data: dict[str, Any]) -> Person:\n",
    "        return cls(**data)\n",
    "\n",
    "    # Python <3.7 way\n",
    "    @classmethod\n",
    "    def from_dict(cls, data: dict[str, Any]) -> \"Person\":\n",
    "        return cls(**data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Можем да си декларираме собствени типове, които да са съставени от други типове. Това се прави с `NewType`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Person(id=37, name=Lana Xes, age=18)\n",
      "None\n"
     ]
    }
   ],
   "source": [
    "from typing import NewType, Optional\n",
    "\n",
    "PersonId = NewType(\"PersonId\", int)\n",
    "\n",
    "class Person:\n",
    "    def __init__(self, id: PersonId, name: str, age: int) -> None:\n",
    "        self.id = id\n",
    "        self.name = name\n",
    "        self.age = age\n",
    "\n",
    "    def __repr__(self) -> str:\n",
    "        return f\"Person(id={self.id}, name={self.name}, age={self.age})\"\n",
    "\n",
    "    def to_dict(self) -> dict[str, Any]:\n",
    "        return vars(self)\n",
    "\n",
    "    @classmethod\n",
    "    def from_dict(cls, data: dict[str, Any]) -> Person:\n",
    "        return cls(**data)\n",
    "\n",
    "def get_person_by_id(id: PersonId, database: list[Person]) -> Optional[Person]:\n",
    "    return next((person for person in database if person.id == id), None)  # `next` has an optional second parameter - default value\n",
    "\n",
    "database = [\n",
    "    Person(PersonId(37), \"Lana Xes\", 18),\n",
    "    Person(PersonId(69), \"Axl Rose\", 60),\n",
    "]\n",
    "\n",
    "print(get_person_by_id(PersonId(37), database))\n",
    "print(get_person_by_id(PersonId(666), database))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Тук обаче бихме имали проблем в случай, че имаме наследник на този клас. Например:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Pesho is banning Pesho.\n"
     ]
    }
   ],
   "source": [
    "class Admin(Person):\n",
    "    def __init__(self, id: PersonId, name: str, age: int, can_ban: bool) -> None:\n",
    "        super().__init__(id, name, age)\n",
    "        self.can_ban = can_ban\n",
    "\n",
    "    def __repr__(self) -> str:\n",
    "        return f\"Admin(id={self.id}, name={self.name}, age={self.age}, can_ban={self.can_ban})\"\n",
    "\n",
    "    def ban(self, person: Person) -> None:\n",
    "        if self.can_ban:\n",
    "            print(f\"{self.name} is banning {person.name}.\")\n",
    "        else:\n",
    "            print(f\"{self.name} is not allowed to ban anyone.\")\n",
    "\n",
    "\n",
    "pesho = Person(PersonId(42), \"Pesho\", 42)\n",
    "peshos_dict = pesho.to_dict()\n",
    "\n",
    "pesho_evolved = Admin.from_dict({**peshos_dict, \"can_ban\": True})  # -> Person, at least for the static type checker\n",
    "\n",
    "pesho_evolved.ban(pesho)  # ⚠️ type checker will complain that type `Person` has no method `ban`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Това поправяме отново с `TypeVar`, този път използвайки именования параметър `bound`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Type\n",
    "\n",
    "PersonId = NewType(\"PersonId\", int)\n",
    "TPerson = TypeVar(\"TPerson\", bound=\"Person\")  # в кавички, защото `Person` още не съществува\n",
    "\n",
    "class Person:\n",
    "    def __init__(self, id: PersonId, name: str, age: int) -> None:\n",
    "        self.id = id\n",
    "        self.name = name\n",
    "        self.age = age\n",
    "\n",
    "    def __repr__(self) -> str:\n",
    "        return f\"Person(id={self.id}, name={self.name}, age={self.age})\"\n",
    "\n",
    "    def to_dict(self) -> dict[str, Any]:\n",
    "        return vars(self)\n",
    "\n",
    "    @classmethod\n",
    "    def from_dict(cls: Type[TPerson], data: dict[str, Any]) -> TPerson:  # <- тук са промените\n",
    "        return cls(**data)\n",
    "\n",
    "    def some_other_common_method(self: TPerson) -> Any:  # <- тук е важно да укажем какъв тип е `self`, ако ще се наследява\n",
    "        pass \n",
    "\n",
    "class Admin(Person):\n",
    "    def __init__(self, id: PersonId, name: str, age: int, can_ban: bool) -> None:\n",
    "        super().__init__(id, name, age)\n",
    "        self.can_ban = can_ban\n",
    "\n",
    "    def __repr__(self) -> str:\n",
    "        return f\"Admin(id={self.id}, name={self.name}, age={self.age}, can_ban={self.can_ban})\"\n",
    "\n",
    "    def ban(self, person: Person) -> None:\n",
    "        if self.can_ban:\n",
    "            print(f\"{self.name} is banning {person.name}.\")\n",
    "        else:\n",
    "            print(f\"{self.name} is not allowed to ban anyone.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Консистентни типове\n",
    "\n",
    "Type checker-ите се оплакват само когато видят неконсистенти типове.\n",
    "\n",
    "Казваме, че типът `T` е консистентен с типа `U`, тогава и само тогава когато **поне едно** от следните условия е изпълнено:\n",
    "\n",
    "1. `T` е подтип на `U`  ($ T \\subset U $)\n",
    "2. `T` е `Any`\n",
    "3. `U` е `Any`\n",
    "\n",
    "Тук е хубаво да отбележим, без да навлизаме в много подробности, че това дали `T` е подтип на `U` в случаите на generic типове зависи от тяхната вариантност. Например, като отчетем факта, че `bool` е подтип на `int`, получаваме следното поведение:\n",
    "\n",
    "* **Ковариантност:** `tuple[bool]` е подтип на `tuple[int]` ( $ T \\subset U \\Rightarrow C[T] \\subset C[U] $)\n",
    "* **Инвариантност:** `list[bool]` не е нито подтип, нито надтип на `list[int]`\n",
    "* **Контравариантност:** `Callable[[int], ...]` е подтип на `Callable[[bool], ...]` ( $ T \\subset U \\Rightarrow C[U] \\subset C[T] $)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "По подразбиране, ако не се посочи друго, анотациите на `TypeVar`-овете ни са **инвариантни**. Ако искаме да укажем дали да са ковариантни или контравариантни, можем да го направим чрез `covariant=True` или `contravariant=True` респ. в инициализацията на `TypeVar`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Duck typing\n",
    "\n",
    "> Ако изглежда като патка, плува като патка и квака като патка, то е патка."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В програмирането съществуват два варианта за типизация: **номинална** и **структурна**. \n",
    "\n",
    "* При **номиналната** типизация типовете са именувани и се сравняват по име и декларация, например `bool` наследява `int`, защото така е деклариран. В Python се ползва предимно номинално типизиране.\n",
    "* При **структурната** типизация типовете се сравняват по-скоро по тяхната структура, т.е. какви методи притежават и т.н. Като пример можем да дадем `__len__` - можем на теория да декларираме *структура* `Sized`, към която би принадлежало всичко, което има метод `__len__`, независимо от името и декларацията му."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В динамичната типизация често са по-важни наборът от методи, които един обект притежава, а не конретния му тип и декларация на базови класове. Именно това стои зад термина duck typing."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В `typing` модулът ни предоставя готови такива структури (или протоколи), които са често използвани. Например точно такъв `Sized` какъвто описахме по-горе има там:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Sized\n",
    "\n",
    "def get_length_squared(obj: Sized) -> int:\n",
    "    return len(obj) ** 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "В горният метод е най-удачно да се анотира аргумента със `Sized`, понеже `Any` би подвел програмиста, че абсолютно всичко е окей, но на практика не е съвсем така - абсолютно всичко, ***което дефинира `__len__`*** е окей. Точно това ни казва протоколът `Sized`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Други полезни и често-използвано протоколи са например `Sequence`, `Iterable`, `Iterator` и `Container`:\n",
    "\n",
    "* `Iterable[]` - итеруеми, т.е. всичко, което дефинира `__iter__` ***или*** `__getitem__`\n",
    "* `Sequence[]` - редици, т.е. всичко, което дефинира `__getitem__` ***и*** `__len__`\n",
    "* `Container[]` - всичко, което дефинира `__contains__`\n",
    "* `Iterator[]` - всичко, което дефинира `__next__` ***и*** `__iter__`\n",
    "\n",
    "Конкретно тези 4 протокoла са и абстрактни базови класове. От Python 3.9 насам е deprecate-нато те да се импортват от `typing` модула - вместо това може да си се използва директно `collections.abc`.\n",
    "\n",
    "`Sequence` дефинира още и `__contains__` и `__reversed__`, които използват имплементацията на другите два метода. Също така по дефиниця може да забележим, че всички редици са и итеруеми, и контейнери."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "from collections.abc import Iterable\n",
    "\n",
    "Number = int | float | complex\n",
    "\n",
    "def multiply(a: Iterable[Number], b: Iterable[Number]) -> Number:\n",
    "    return sum(a * b for a, b in zip(a, b))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### `Protocol`\n",
    "\n",
    "Можем естествено и сами да си дефинираме протокол, с `typing.Protocol`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Да предположим, че имаме подобни класове (примерно предоставени от някои библиотеки):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "class Child:\n",
    "    def quack(self) -> None:\n",
    "        print(\"Quack!\")\n",
    "\n",
    "class Physicist:\n",
    "    def quack(self) -> None:\n",
    "        print(\"Quark.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Номинално те нямат нищо общо (нямат общ базов клас), но структурно имат общ метод. Да предположим и че точно този метод ни трябва за някаква функция, като тази:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "def make_quack(duck):\n",
    "    duck.quack()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Как ще анотираме аргумента `duck` на функцията? \n",
    "\n",
    "`Any` не ни върши достатъчна работа, понеже не всичко може да `quack()`-а. На практика искаме да си дефинираме наш си протокол, който да съдържа само този метод:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Quack!\n",
      "Quark.\n"
     ]
    }
   ],
   "source": [
    "from typing import Protocol\n",
    "\n",
    "class Duck(Protocol):\n",
    "    def quack(self) -> None:\n",
    "        ...  # yes, this is valid Python syntax apparently\n",
    "\n",
    "def make_quack(duck: Duck) -> None:\n",
    "    duck.quack()\n",
    "\n",
    "peshi = Child()\n",
    "feynman = Physicist()\n",
    "\n",
    "make_quack(peshi)\n",
    "make_quack(feynman)\n",
    "# static type-checkers will not complain about above 2 invocations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ако искаме `isinstance` и `issubclass` да работят с протоколите ни, трябва да ги декорираме с `typing.runtime_checkable`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "isinstance(peshi, Duck) = True\n",
      "issubclass(Physicist, Duck) = True\n"
     ]
    }
   ],
   "source": [
    "from typing import Protocol, runtime_checkable\n",
    "\n",
    "@runtime_checkable\n",
    "class Duck(Protocol):\n",
    "    def quack(self) -> None:\n",
    "        ...\n",
    "\n",
    "print(f\"{isinstance(peshi, Duck) = }\")\n",
    "print(f\"{issubclass(Physicist, Duck) = }\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Note:* преди Python 3.8 `Protocol` се намира в `typing_extensions` модула."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `@dataclass`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Говорейки за typing няма как вече да не намесим и един полезен декоратор - `dataclasses.dataclass`, вмъкнал се в езика с Python 3.7.\n",
    "\n",
    "Както подсказва донякъде името му, той има за цел да помогне с дефинирането на прости класове, които имат за цел предимно да съхраняват някакви атрибути с някакви данни (подобно на типовете, за които бихме използвали `struct` вместо `class` в С++ / С# например).\n",
    "\n",
    "Предоставя ни изключително голямо синтактично удобство, понеже следния клас:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "from dataclasses import dataclass\n",
    "\n",
    "@dataclass\n",
    "class User:\n",
    "    id: int\n",
    "    username: str\n",
    "    email: str\n",
    "    is_admin: bool = False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "е абсолютно еквивалентен на:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [],
   "source": [
    "class User:\n",
    "    def __init__(self, id: int, username: str, email: str, is_admin: bool = False) -> None:\n",
    "        self.id = id\n",
    "        self.username = username\n",
    "        self.email = email\n",
    "        self.is_admin = is_admin\n",
    "\n",
    "    def __repr__(self) -> str:\n",
    "        return f\"User(id={self.id}, username={self.username}, email={self.email}, is_admin={self.is_admin})\"\n",
    "\n",
    "    def __eq__(self, other: object) -> bool:\n",
    "        if not isinstance(other, User):\n",
    "            return False\n",
    "\n",
    "        return vars(self) == vars(other)\n",
    "\n",
    "    # Python 3.10+ only, used for the `match` statement\n",
    "    def __match_args__(self) -> tuple[int, str, str, bool]:\n",
    "        return self.id, self.username, self.email, self.is_admin"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "И това са само част от способностите на `@dataclass`. Той приема различни параметри, с които още можем да укажем дали класът да е immutable (`frozen=True`), да има `__hash__`, дефиниции на операторите за сравнение, и др.\n",
    "\n",
    "```python\n",
    "@dataclasses.dataclass(*, \n",
    "    init=True, \n",
    "    repr=True, \n",
    "    eq=True, \n",
    "    order=False, \n",
    "    unsafe_hash=False, \n",
    "    frozen=False, \n",
    "    match_args=True, \n",
    "    kw_only=False, \n",
    "    slots=False, \n",
    "    weakref_slot=False\n",
    ")\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{Point(x=1, y=2), Point(x=0, y=0)}\n"
     ]
    }
   ],
   "source": [
    "from dataclasses import dataclass\n",
    "\n",
    "@dataclass(frozen=True)\n",
    "class Point:\n",
    "    x: int | float = 0\n",
    "    y: int | float = 0\n",
    "\n",
    "s = {Point(1, 2), Point(), Point(1, 2)}\n",
    "print(s)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Повече информация в [документацията](https://docs.python.org/3/library/dataclasses.html#dataclasses.dataclass)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10.6 64-bit",
   "language": "python",
   "name": "python3"
  },
  "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.11.5"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "b0fa6594d8f4cbf19f97940f81e996739fb7646882a419484c72d19e05852a7e"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}