dataclasses-how-to.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Dataclasses\n",
    "- Author: 楊晴雯\n",
    "- Date: 2023/05/25 \n",
    "- new since Python 3.7 \n",
    "- use @dataclass decorator (`from dataclasses import dataclass`)\n",
    "\n",
    "## Reference\n",
    "- [Real Python](https://realpython.com/python-data-classes/)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Vanilla Data Class\n",
    "- Card Class 撲克牌\n",
    "- Regular Class 印出來會是一個物件，not very descriptive，\n",
    "可以使用 `__repr__` 來換成你想要的表示方式。Data Class 印出來則非常明確。\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Card(rank='A', suit='heart')"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Card Class\n",
    "from dataclasses import dataclass \n",
    "\n",
    "@dataclass \n",
    "class Card:\n",
    "    rank: str \n",
    "    suit: str \n",
    "    \n",
    "spadesA= Card('A', 'spades')\n",
    "heartA= Card('A', 'heart')\n",
    "heartA"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Card(rank='A', suit='spades')"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Alterniative: Create dataclass \n",
    "from dataclasses import make_dataclass \n",
    "Card = make_dataclass('Card', ['rank', 'suit'])\n",
    "spadesA= Card('A', 'spades')\n",
    "spadesA "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- default values \n",
    "- type hint \n",
    "## Note \n",
    "- 2 dataclass objects are equal if all of their fields are equal!!\n",
    "\n",
    "## Radian\n",
    "-![](images/radian_explain.png)\n",
    "-![](images/haversine_formula.png)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data class with class method \n",
    "- Position "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "Distance from Hsinchu to Mt.Fuji: 2115.462497170761 km\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Default Values\n",
    "from math import radians, cos, sin, asin, sqrt # asin: arcsin \n",
    "# radian 弧度： 1 radian = 180/π = 57.3° \n",
    "\n",
    "@dataclass \n",
    "class Position:\n",
    "    name: str \n",
    "    lon: float = 0.0\n",
    "    lat: float = 0.0\n",
    "\n",
    "    # method in dataclass \n",
    "    def distance_to(self, other):\n",
    "        r = 6371 # Earth radius in kilometers \n",
    "        lon1, lon2 = radians(self.lon), radians(other.lon)\n",
    "        lat1, lat2 = radians(self.lat), radians(other.lat) \n",
    "        # haversine formula: measure distance between two points on a sphere \n",
    "        h = (sin((lat2-lat1)/2)**2 + cos(lat1)*cos(lat2)*sin((lon2-lon1)/2)**2)\n",
    "        return 2*r*asin(sqrt(h))\n",
    "\n",
    "\n",
    "\n",
    "Island1 = Position('Island1', 23.5, 45.6)\n",
    "Island2 = Position('Island1', 23.5, 45.6)\n",
    "\n",
    "# Taiwan Hsinchu \n",
    "Hsinchu = Position('Hsinchu', 24.47, 120.97)\n",
    "MtFuji = Position('MtFuji', 35.36, 138.73) \n",
    "\n",
    "# check equality\n",
    "print(Island1 == Island2)\n",
    "# check distance\n",
    "Island1.distance_to(Island2)\n",
    "\n",
    "# check Hsinchu and Mt.Fuji distance\n",
    "print('Distance from Hsinchu to Mt.Fuji:', Hsinchu.distance_to(MtFuji), 'km') # km \n",
    "# check Hsinchu and Mt.Fuji distance reversely \n",
    "MtFuji.distance_to(Hsinchu)  == Hsinchu.distance_to(MtFuji)\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Use another class to manipulate a data class \n",
    "- Use `Deck` to manipulate `Card`\n",
    "- Beware of how you initialize the deck of cards (`default_factory` argument)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import List\n",
    "from dataclasses import dataclass, field\n",
    "\n",
    "\n",
    "all_suits = '♠ ♡ ♢ ♣'.split()\n",
    "all_ranks = '2 3 4 5 6 7 8 9 10 J Q K A'.split()\n",
    "\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Don’t do this! This introduces one of the most common anti-patterns in Python: using mutable default \n",
    "arguments. The problem is that all instances of Deck will use the same list object as the default \n",
    "value of the .cards property. This means that if, say, one card is removed from one Deck, \n",
    "then it disappears from all other instances of Deck as well. Actually, data classes try to prevent you \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "from doing this, and the code above will raise a ValueError.\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "mutable default <class 'list'> for field cards is not allowed: use default_factory\n"
     ]
    }
   ],
   "source": [
    "def make_french_deck():\n",
    "    return [Card(r, s) for s in all_suits for r in all_ranks] \n",
    "try:\n",
    "    @dataclass    \n",
    "    class Deck:\n",
    "        cards: List[Card] = make_french_deck()\n",
    "except ValueError as e:\n",
    "    print(e)\n",
    "# ValueError: mutable default  for field cards is not allowed: use default_factory"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### ⛔️ However, note that removing dataclass decorator will not raise error\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[Card(rank='2', suit='♠'), Card(rank='3', suit='♠'), Card(rank='4', suit='♠'), Card(rank='5', suit='♠'), Card(rank='6', suit='♠'), Card(rank='7', suit='♠'), Card(rank='8', suit='♠'), Card(rank='9', suit='♠'), Card(rank='10', suit='♠'), Card(rank='J', suit='♠')]\n"
     ]
    }
   ],
   "source": [
    "class Deck:\n",
    "    cards: List[Card] = make_french_deck()\n",
    "\n",
    "deck1 = Deck()\n",
    "deck2 = Deck()\n",
    "# remove spades A from deck1\n",
    "deck1.cards \n",
    "# check spades A is still in deck2\n",
    "deck2.cards[-1] is spadesA \n",
    "print(deck2.cards[:10])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [],
   "source": [
    "@dataclass\n",
    "class Deck:\n",
    "    cards: List[Card] = field(default_factory=make_french_deck) "
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## field\n",
    "\n",
    "`field()` 是拿來包裝 `Field` class 免得讓他直接暴露。\n",
    "This function is used instead of exposing Field creation directly,\n",
    "so that a type checker can be told (via overloads) that this is a\n",
    "function whose type depends on its parameters.\n",
    "\n",
    "- default: Default value of the field\n",
    "- default_factory: Function that returns the initial value of the field\n",
    "- init: Use field in `.__init__()` method? (Default is True.)\n",
    "- repr: Use field in repr of the object? (Default is True.)\n",
    "- compare: Include the field in comparisons? (Default is True.)\n",
    "- hash: Include the field when calculating hash()? (Default is to use the same as for compare.)\n",
    "- metadata: A mapping with information about the field\n",
    "\n",
    "\n",
    "```python \n",
    "class Field:\n",
    "    __slots__ = ('name',\n",
    "                 'type',\n",
    "                 'default',\n",
    "                 'default_factory',\n",
    "                 'repr',\n",
    "                 'hash',\n",
    "                 'init',\n",
    "                 'compare',\n",
    "                 'metadata',\n",
    "                 '_field_type',  # Private: not to be used by user code.\n",
    "                 )\n",
    "\n",
    "    def __init__(self, default, default_factory, init, repr, hash, compare,\n",
    "                 metadata):\n",
    "        self.name = None\n",
    "        self.type = None\n",
    "        self.default = default\n",
    "        self.default_factory = default_factory\n",
    "        self.init = init\n",
    "        self.repr = repr\n",
    "        self.hash = hash\n",
    "        self.compare = compare\n",
    "        self.metadata = (_EMPTY_METADATA\n",
    "                         if metadata is None else\n",
    "                         types.MappingProxyType(metadata))\n",
    "        self._field_type = None\n",
    "\n",
    "    def __repr__(self):\n",
    "        return ('Field('\n",
    "                f'name={self.name!r},'\n",
    "                f'type={self.type!r},'\n",
    "                f'default={self.default!r},'\n",
    "                f'default_factory={self.default_factory!r},'\n",
    "                f'init={self.init!r},'\n",
    "                f'repr={self.repr!r},'\n",
    "                f'hash={self.hash!r},'\n",
    "                f'compare={self.compare!r},'\n",
    "                f'metadata={self.metadata!r},'\n",
    "                f'_field_type={self._field_type}'\n",
    "                ')')\n",
    "\n",
    "    # This is used to support the PEP 487 __set_name__ protocol in the\n",
    "    # case where we're using a field that contains a descriptor as a\n",
    "    # default value.  For details on __set_name__, see\n",
    "    # https://www.python.org/dev/peps/pep-0487/#implementation-details.\n",
    "    #\n",
    "    # Note that in _process_class, this Field object is overwritten\n",
    "    # with the default value, so the end result is a descriptor that\n",
    "    # had __set_name__ called on it at the right time.\n",
    "    def __set_name__(self, owner, name):\n",
    "        func = getattr(type(self.default), '__set_name__', None)\n",
    "        if func:\n",
    "            func(self.default, owner, name)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Field(name='rank',type='typing.Any',default=<dataclasses._MISSING_TYPE object at 0x7f2617e6dfa0>,default_factory=<dataclasses._MISSING_TYPE object at 0x7f2617e6dfa0>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD),\n",
       " Field(name='suit',type='typing.Any',default=<dataclasses._MISSING_TYPE object at 0x7f2617e6dfa0>,default_factory=<dataclasses._MISSING_TYPE object at 0x7f2617e6dfa0>,init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD))"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from dataclasses import fields\n",
    "fields(Card)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(Field(name='cards',type=typing.List[types.Card],default=<dataclasses._MISSING_TYPE object at 0x7f2617e6dfa0>,default_factory=[Card(rank='2', suit='♠'), Card(rank='3', suit='♠'), Card(rank='4', suit='♠'), Card(rank='5', suit='♠'), Card(rank='6', suit='♠'), Card(rank='7', suit='♠'), Card(rank='8', suit='♠'), Card(rank='9', suit='♠'), Card(rank='10', suit='♠'), Card(rank='J', suit='♠'), Card(rank='Q', suit='♠'), Card(rank='K', suit='♠'), Card(rank='A', suit='♠'), Card(rank='2', suit='♡'), Card(rank='3', suit='♡'), Card(rank='4', suit='♡'), Card(rank='5', suit='♡'), Card(rank='6', suit='♡'), Card(rank='7', suit='♡'), Card(rank='8', suit='♡'), Card(rank='9', suit='♡'), Card(rank='10', suit='♡'), Card(rank='J', suit='♡'), Card(rank='Q', suit='♡'), Card(rank='K', suit='♡'), Card(rank='A', suit='♡'), Card(rank='2', suit='♢'), Card(rank='3', suit='♢'), Card(rank='4', suit='♢'), Card(rank='5', suit='♢'), Card(rank='6', suit='♢'), Card(rank='7', suit='♢'), Card(rank='8', suit='♢'), Card(rank='9', suit='♢'), Card(rank='10', suit='♢'), Card(rank='J', suit='♢'), Card(rank='Q', suit='♢'), Card(rank='K', suit='♢'), Card(rank='A', suit='♢'), Card(rank='2', suit='♣'), Card(rank='3', suit='♣'), Card(rank='4', suit='♣'), Card(rank='5', suit='♣'), Card(rank='6', suit='♣'), Card(rank='7', suit='♣'), Card(rank='8', suit='♣'), Card(rank='9', suit='♣'), Card(rank='10', suit='♣'), Card(rank='J', suit='♣'), Card(rank='Q', suit='♣'), Card(rank='K', suit='♣'), Card(rank='A', suit='♣')],init=True,repr=True,hash=None,compare=True,metadata=mappingproxy({}),_field_type=_FIELD),)\n"
     ]
    }
   ],
   "source": [
    "# however, for Deck, it is too verbose \n",
    "print(fields(Deck)) \n",
    "# because it lists all of the cards\n",
    "# we can manually create a less verbose "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Deck(♠2, ♠3, ♠4, ♠5, ♠6, ♠7, ♠8, ♠9, ♠10, ♠J, ♠Q, ♠K, ♠A, ♡2, ♡3, ♡4, ♡5, ♡6, ♡7, ♡8, ♡9, ♡10, ♡J, ♡Q, ♡K, ♡A, ♢2, ♢3, ♢4, ♢5, ♢6, ♢7, ♢8, ♢9, ♢10, ♢J, ♢Q, ♢K, ♢A, ♣2, ♣3, ♣4, ♣5, ♣6, ♣7, ♣8, ♣9, ♣10, ♣J, ♣Q, ♣K, ♣A)"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "\n",
    "\n",
    "def make_french_deck():\n",
    "    return [Card(r, s) for s in all_suits for r in all_ranks] \n",
    "@dataclass \n",
    "class Card:\n",
    "    rank: str \n",
    "    suit: str \n",
    "\n",
    "@dataclass\n",
    "class Deck:\n",
    "    cards: List[Card] = field(default_factory=make_french_deck)\n",
    "    def __repr__(self):\n",
    "        cards = ', '.join(f'{c.suit}{c.rank}' for c in self.cards)\n",
    "        # self.__class__.__name__ is the current class name\n",
    "        # namely, Deck \n",
    "        return f'{self.__class__.__name__}({cards})'\n",
    "Deck()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Comparing Cards\n",
    "- eq.\n",
    "- sort"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [],
   "source": [
    "# eq. \n",
    "# order\n",
    "from dataclasses import dataclass, field\n",
    "\n",
    "\n",
    "@dataclass(order=True)\n",
    "class Card:\n",
    "    sort_index: int = field(init=False, repr=False)\n",
    "    rank: str\n",
    "    suit: str\n",
    "\n",
    "    def __post_init__(self):\n",
    "        self.sort_index = (all_ranks.index(self.rank) * len(all_suits)\n",
    "                           + all_suits.index(self.suit))\n",
    "\n",
    "    def __str__(self):\n",
    "        return f'{self.suit}{self.rank}'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "queen_of_hearts = Card('Q', '♡')\n",
    "ace_of_spades = Card('A', '♠')\n",
    "ace_of_spades > queen_of_hearts"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [],
   "source": [
    "from random import sample\n",
    "# order = True \n",
    "\n",
    "ksamples = Deck(sample(make_french_deck(), k=10))\n",
    "# how to sort the cards?    \n",
    "ksamples.cards.sort()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Deck(♠2, ♣2, ♣3, ♡6, ♡8, ♣8, ♠10, ♣10, ♡K, ♣K)"
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "ksamples"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Inheritance "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from dataclasses import dataclass\n",
    "\n",
    "@dataclass\n",
    "class Position:\n",
    "    name: str\n",
    "    lon: float\n",
    "    lat: float\n",
    "\n",
    "@dataclass\n",
    "class Capital(Position):\n",
    "    country: str"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.8.16"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}