11. OO programming in Python.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*********************************************************************************************************\n",
    "# A Tour of Python 3  \n",
    "version 1.0.1  \n",
    "Authors: Phil Pfeiffer, Zack Bunch, and Feyisayo Oyeniyi  \n",
    "East Tennessee State University  \n",
    "Last updated June 2021  \n",
    "*********************************************************************************************************"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 11.  OO programming in Python   \n",
    " 11.1 [Encapsulation and data hiding](#OO-Programming-In-Python-Encapsulation-And-Data-Hiding)  \n",
    " 11.2 [Dependency inversion](#OO-Programming-In-Python-Dependency-Inversion)  \n",
    " 11.3 [Nested classes](#OO-Programming-In-Python-Nested-Classes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 11.1  Encapsulation and data hiding <a name='OO-Programming-In-Python-Encapsulation-And-Data-Hiding'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Like other OO languages, Python supports encapsulation. ",
    "If an object A contains an object B, then B must be accessed \"through\" A, using an expression like `A.B`. ",
    "The one exception to this rule involves `import` statements that expose a package's objects for direct use, like *from A import B*. \n",
    "\n",
    "Unlike compiled OO languages, Python lacks support for strong data hiding. ",
    "Declarations like \"public\", \"private\" and \"protected\" are absent from Python. ",
    "Rather, **data hiding in Python is a programmer-enforced convention**. ",
    "Apart from a few built-in immutable classes and constants, all Python identifiers are always readable and updateable, ",
    "as are the objects they reference. The rationale for this lack of checking is threefold:\n",
    "-  Python's support for `eval` and `exec` renders any attempt to implement static access checking imperfect.\n",
    "-  Using run-time checks to enforce data hiding would slow every data access.  Most checks, moreover, would be useless and redundant.\n",
    "-  Treating data hiding as a convention rather than a requirement gives programmers freedom to break data hiding at need.\n",
    "\n",
    "Python does support one weak mechanism for data hiding.  This mechanism, *name mangling*, is invoked automatically for ",
    "attributes whose names start with a double underscore.  Python manages these attributes by\n",
    "-  assigning them new names and\n",
    "-  converting all references to these attributes from within their container objects to these new names\n",
    "\n",
    "While name mangling effectively invalidates all external references to the \"real\" names, ",
    "this transformation is easily circumvented."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 11.1.a  'weak' data hiding using data mangling\n",
    "\n",
    "class MyClass:\n",
    "  def __init__(self, v):  self.__value = v\n",
    "  def get_value(self):    return self.__value\n",
    "\n",
    "instance = MyClass(1)\n",
    "print( 'result of using get_value() to retrieve value from instance: ', instance.get_value() ) \n",
    "\n",
    "print( 'result of reading instance.__value: ', end='' )\n",
    "try:\n",
    "  print( instance.__value )\n",
    "except:\n",
    "  print( 'failure' )\n",
    "\n",
    "print( 'result of setting instance.__value to 4, then using instance.get_value() to read it: ', end='' )\n",
    "try:\n",
    "  instance.__value = 4\n",
    "  print( instance.get_value() )\n",
    "except:\n",
    "  print( 'failure' )\n",
    "\n",
    "print()\n",
    "print( 'result of reading instance._MyClass__value: ', end='' )\n",
    "try:\n",
    "  print( instance._MyClass__value )\n",
    "except:\n",
    "  print( 'failure' )\n",
    "\n",
    "print( 'result of setting instance._MyClass__value to 4, then using instance.get_value() to read it: ', end='' )\n",
    "try:\n",
    "  instance._MyClass__value = 4\n",
    "  print( instance.get_value() )\n",
    "except:\n",
    "  print( 'failure' )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##  11.2 Dependency inversion <a name='OO-Programming-In-Python-Dependency-Inversion'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Dependency inversion* refers to the structuring of a family of objects as objects with a single, common interface and varied implementations. ",
    "Type systems for compiled OO languages require that the common interface be defined as a base class, ",
    "then specialized for particular realizations of that interface. ",
    "A classic characterization of this approach posits \n",
    "-  an abstract base class (ABC) that returns a time of day, with \n",
    "-  a set of child classes that retrieve time-of-day information from different kinds of timepieces, \n",
    "   ranging from digital assistants to digital clocks to sundials.\n",
    "\n",
    "The term \"dependency inversion\" was coined at a time when object-oriented languages first came into vogue. ",
    "It was developed as an alternative to *run-time type inference* (RTTI):  a design strategy that uses a test of a value's type ",
    "at run time to select one of collection of routines to use to process that value. ",
    "The term *inversion* was used to signal a need to \"invert\" previous practice by designing an ABC before its child classes. \n",
    "\n",
    "RTTI is now viewed as a poor practice that hinders program evolution. ",
    "In RTTI-based codes, adding routines to or removing them from a given family of routines can force changes to *all* codes ",
    "that access *any* of these routines.  Dependency inversion, by contrast, ",
    "localizes such changes to the classes being added or removed, so long as those classes share the common interface.\n",
    "\n",
    "In interpreted languages, the lack of compile-time type checking eliminates the need to use a base class ",
    "in order to assure a child class's type is correct for where it's being used. ",
    "So long as an object has attributes that fit a given context, its type is assumed to be correct. ",
    "This approach to type checking is referred to as *latent* typing or *duck* typing: ",
    "i.e., if an object walks like a duck and quacks like a duck, assume it's a duck.\n",
    "\n",
    "Latent typing is favored by a minimalist school of software design, including authorities like Russ Olsen ",
    "(<u>Eloquent Ruby</u>) who argue for achieving software quality by writing concise programs with clearly named variables ",
    "and supporting them with carefully crafted regression test suites. ",
    "These authorities criticize type declarations and hard-coded type checks as syntactic clutter: ",
    "i.e., attempt to prevent potential errors that would be better prevented by careful naming and testing. ",
    "While these authorities recommend inheritance as a means of eliminating duplicate code, they see it as useless for defining types.\n",
    "\n",
    "The following examples use these additional Python constructs:\n",
    "- `ABCMeta` - a Python *metaclass* (see below) that prevents a class from being used to instantiate other classes; \n",
    "  the constrained class is similar to abstract base classes in compiled OO languages.\n",
    "-  `input` - read a string from the user's terminal\n",
    "-  `time.strftime` - display time of day as a string\n",
    "\n",
    "A *metaclass* is a class that controls the operation of a(nother) class. ",
    "  All Python classes have metaclasses: the default is `object`. ",
    "  For more on programming with metaclasses and reasons for thinking twice before doing so, see (e.g.) \n",
    "- Mark Lutz's <u>Learning Python</u>, 5th edition\n",
    "- Mark Summerfield's <u>Python3</u>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 11.2.a   An RTTI-based code (bad!) that\n",
    "# -  solicits an \"option 1 or 2\" answer from a user in one of several languages, then\n",
    "# -  launches a command in response to this response\n",
    "\n",
    "# supporting constants\n",
    "TIME_AS_24_HR_FORMAT = '%H:%M'      # time.strftime string for military time format\n",
    "TIME_AS_12_HR_FORMAT = '%I:%M %p'   # time.strftime string for am/pm time format\n",
    "OPTSTRINGS = {'1': TIME_AS_24_HR_FORMAT, '2': TIME_AS_12_HR_FORMAT}\n",
    "\n",
    "# supporting library modules\n",
    "import time\n",
    "\n",
    "def QueryInEnglish():\n",
    "  while True:\n",
    "    option = input('Please enter 1 for 24 hour format, 2 for AM/PM format: ')\n",
    "    if option in OPTSTRINGS.keys(): return option\n",
    "\n",
    "def QueryInFrench():\n",
    "  while True:\n",
    "    option = input('S\\'il vous plaît entrer 1 pour le format de 24 heures, 2 pour le format AM / PM: ')\n",
    "    if option in OPTSTRINGS.keys(): return option\n",
    "\n",
    "def QueryInSpanish():\n",
    "  while True:\n",
    "    option = input('Por favor, introduzca 1 para el formato de 24 horas, 2 para el formato AM / PM: ')\n",
    "    if option in OPTSTRINGS.keys(): return option\n",
    "\n",
    "def get_time(language):\n",
    "  if language==\"EN\":\n",
    "    return time.strftime(OPTSTRINGS[QueryInEnglish()])\n",
    "  elif language==\"FR\":\n",
    "    return time.strftime(OPTSTRINGS[QueryInFrench()])\n",
    "  elif language==\"ES\":\n",
    "    return time.strftime(OPTSTRINGS[QueryInSpanish()])\n",
    "  else:\n",
    "    return f'language not supported: {language}' \n",
    "\n",
    "print( 'Time in English is', get_time(\"EN\"), '\\n' )\n",
    "print( 'Time in French is',  get_time(\"FR\"), '\\n' )\n",
    "print( 'Time in Spanish is', get_time(\"ES\"), '\\n' )\n",
    "print( 'Time in Italian is', get_time(\"IT\") )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 11.2.b   redoing the previous example using dependency inversion\n",
    "#  the following code encapsulates queries as classes with an abstract base class,\n",
    "#  and features a type check for the get_time() routine parameter\n",
    "#\n",
    "#  TwoOptionQuery metaclasses are classes that control the instantiation of classes\n",
    "#  for more on metaclasses, see the resources named at the outset of this document\n",
    "\n",
    "# supporting constants\n",
    "TIME_AS_24_HR_FORMAT = '%H:%M'      # time.strftime string for military time format\n",
    "TIME_AS_12_HR_FORMAT = '%I:%M %p'   # time.strftime string for am/pm time format\n",
    "OPTSTRINGS = {'1': TIME_AS_24_HR_FORMAT, '2': TIME_AS_12_HR_FORMAT}\n",
    "\n",
    "# supporting library modules\n",
    "import time\n",
    "from abc import ABCMeta\n",
    "\n",
    "# supporting functions\n",
    "make_printable = lambda exception: '' if str(exception) is None else str(exception)\n",
    "\n",
    "class TwoOptionQuery(metaclass=ABCMeta):\n",
    "  @classmethod\n",
    "  def getOption(clas):\n",
    "    while True:\n",
    "      option = input(clas.querystring)\n",
    "      if option in OPTSTRINGS.keys(): return option\n",
    "\n",
    "class QueryInEnglish(TwoOptionQuery):\n",
    "  querystring = 'Please enter 1 for 24 hour format, 2 for AM/PM format: '\n",
    "\n",
    "class QueryInFrench(TwoOptionQuery):\n",
    "  querystring = 'S\\'il vous plaît entrer 1 pour le format de 24 heures, 2 pour le format AM / PM: '\n",
    "\n",
    "class QueryInSpanish(TwoOptionQuery):\n",
    "  querystring = 'Por favor, introduzca 1 para el formato de 24 horas, 2 para el formato AM / PM: '\n",
    "\n",
    "class QueryInItalian:\n",
    "  @staticmethod\n",
    "  def getOption():\n",
    "    while True:\n",
    "      option = input( 'Inserisci 1 per il formato 24 ore, 2 per il formato AM / PM: ' )\n",
    "      if option in OPTSTRINGS.keys(): return option\n",
    "\n",
    "def get_time(querier):\n",
    "  # the following check would be automatic in compiled OO languages \n",
    "  # in Python, it's optional - and included for the sake of completeness\n",
    "  assert issubclass(querier, TwoOptionQuery), f'querier ({querier.__name__}) must be a subclass of TwoOptionQuery' \n",
    "  return time.strftime({'1': TIME_AS_24_HR_FORMAT, '2': TIME_AS_12_HR_FORMAT}[querier.getOption()])\n",
    "\n",
    "print( 'Time in English is', get_time(QueryInEnglish), '\\n' )\n",
    "print( 'Time in French is',  get_time(QueryInFrench), '\\n' )\n",
    "print( 'Time in Spanish is', get_time(QueryInSpanish), '\\n' )\n",
    "try:\n",
    "  print( 'Time in Italian is' )\n",
    "  print( get_time(QueryInItalian) )\n",
    "except Exception as exception:\n",
    "  print( '??',make_printable(exception) )\n",
    "\n",
    "print( '\\n\\nHowever, the check in get_time can be bypassed by invoking the subclass directly\\n' )\n",
    "time.strftime({'1': \"%H:%M\", '2': \"%I:%M %p\"}[QueryInItalian.getOption()])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 11.2.c  simplifying the previous example, per \"duck typing\" practice.\n",
    "#  -.  the TwoOptionQuery superclass is retained, because it provides common implementation logic\n",
    "#      for its child classes.\n",
    "#  -.  the ABCMeta designation has been discarded, however, as the assertion in get_time\n",
    "\n",
    "# supporting constants\n",
    "TIME_AS_24_HR_FORMAT = '%H:%M'      # time.strftime string for military time format\n",
    "TIME_AS_12_HR_FORMAT = '%I:%M %p'   # time.strftime string for am/pm time format\n",
    "OPTSTRINGS = {'1': TIME_AS_24_HR_FORMAT, '2': TIME_AS_12_HR_FORMAT}\n",
    "\n",
    "# supporting library modules\n",
    "import time\n",
    "\n",
    "class TwoOptionQuery:\n",
    "  @classmethod\n",
    "  def getOption(clas):\n",
    "    while True:\n",
    "      option = input(clas.querystring)\n",
    "      if option in OPTSTRINGS.keys(): return option\n",
    "\n",
    "class QueryInEnglish(TwoOptionQuery):\n",
    "  querystring = 'Please enter 1 for 24 hour format, 2 for AM/PM format: '\n",
    "\n",
    "class QueryInFrench(TwoOptionQuery):\n",
    "  querystring = 'S\\'il vous plaît entrer 1 pour le format de 24 heures, 2 pour le format AM / PM: '\n",
    "\n",
    "class QueryInSpanish(TwoOptionQuery):\n",
    "  querystring = 'Por favor, introduzca 1 para el formato de 24 horas, 2 para el formato AM / PM: '\n",
    "\n",
    "class QueryInItalian:\n",
    "  @staticmethod\n",
    "  def getOption():\n",
    "    while True:\n",
    "      option = input('Inserisci 1 per il formato 24 ore, 2 per il formato AM / PM: ')\n",
    "      if option in OPTSTRINGS.keys(): return option\n",
    "\n",
    "def get_time(querier):\n",
    "  return time.strftime(OPTSTRINGS[querier.getOption()])\n",
    "\n",
    "\n",
    "print( 'Time in English is', get_time(QueryInEnglish) )\n",
    "print( 'Time in French is',  get_time(QueryInFrench) )\n",
    "print( 'Time in Spanish is', get_time(QueryInSpanish) )\n",
    "print( 'Time in Italian is', get_time(QueryInItalian) )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to `ABCMeta`, the Python library provides decorators that treat a class's methods and properties as abstract methods and properties: ",
    "i.e., objects that the class's subclasses are required to overload.  See the Python Library documentation on ",
    "[abstract base classes for containers](https://docs.python.org/3/library/collections.abc.html) for details."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##  11.3 Nested classes  <a name='OO-Programming-In-Python-Nested-Classes'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python supports the nesting of classes within classes. ",
    "While nesting tends to interfere with readability, it can be used to express one class's dependency on a second class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 11.3   A representation of a common-- though far from the only-- ranking of cards in card decks.\n",
    "# For simplicity, the design assumes that the ranking is uniform by suit - \n",
    "# an assumption that fails to hold for (e.g.) euchre-family card games.\n",
    "\n",
    "class CardValues(object):\n",
    "  __defaultValues = ['ace', 'king', 'queen', 'jack', '10', '9', '8', '7', '6', '5', '4', '3', '2']\n",
    "  def __init__(self, **kwargs):\n",
    "    self.card_values = kwargs.get( 'values', CardValues.__defaultValues )\n",
    "  def __eq__(self, other):\n",
    "    return isinstance(other, CardValues) and len(self) == len(other) and all([s==o for (s,o) in zip(self,other)])\n",
    "  @staticmethod\n",
    "  def outranks(card1, card2):\n",
    "    assert card2.value in card1.deck.card_values, f'value ({card2.value}) not in values ({card1.deck.card_values})' \n",
    "    return card1.deck.card_values.index(card1.value) < card1.deck.card_values.index(card2.value)\n",
    "\n",
    "class CardSuits(object):\n",
    "  __defaultSuits = ['spades', 'hearts', 'diamonds', 'clubs']\n",
    "  def __init__(self, **kwargs):\n",
    "    self.card_suits = kwargs.get( 'suits', CardSuits.__defaultSuits )\n",
    "  def __eq__(self, other):\n",
    "    return isinstance(other, CardSuits) and len(self) == len(other) and all([s==o for (s,o) in zip(self,other)])\n",
    "  @staticmethod\n",
    "  def outranks(card1, card2):\n",
    "    assert card2.suit in card1.deck.card_suits, f'suit ({card2.suit}) not in suits ({card1.deck.card_suits})' \n",
    "    return card1.deck.card_suits.index(card1.suit) < card1.deck.card_suits.index(card2.suit)\n",
    "\n",
    "class CardDeck(CardValues, CardSuits):\n",
    "  class Card(object):\n",
    "    def __init__(self, deck, suit, value):\n",
    "      self.deck, self.suit, self.value = deck, suit, value\n",
    "    def comparable(self, other):\n",
    "      return isinstance(other, CardDeck.Card) \\\n",
    "        and self.deck.card_suits == other.deck.card_suits and self.deck.card_values == other.deck.card_values\n",
    "    def __eq__(self, other):\n",
    "      return self.comparable(other) and self.suit == other.suit and self.value == other.value\n",
    "    def __gt__(self, other):\n",
    "      return self.comparable(other) and deck.outranks(self,other)\n",
    "    def __lt__(self, other):\n",
    "      raise NotImplemented\n",
    "  def __init__(self, **kwargs):\n",
    "    CardSuits.__init__(self, **kwargs)\n",
    "    CardValues.__init__(self, **kwargs)\n",
    "  def getCard(self, suit, value):\n",
    "    assert suit in self.card_suits,    f\"suit  ({suit}) missing from deck's suits  ({self.card_suits})\" \n",
    "    assert value in self.card_values,  f\"value ({value}) missing from deck's values ({self.card_values})\" \n",
    "    return self.Card(self, suit, value)       # can also be CardDeck.Card\n",
    "  def __eq__(self, other):\n",
    "    return isinstance(other, CardDeck) \\\n",
    "      and self.card_suits == other.card_suits and self.card_values == other.card_values\n",
    "  @staticmethod\n",
    "  def outranks(card1, card2):\n",
    "    assert isinstance(card1, CardDeck.Card),  f'object ({card1}) not a card in a card deck' \n",
    "    assert isinstance(card2, CardDeck.Card),  f'object ({card2}) not a card in a card deck' \n",
    "    if card1.deck != card2.deck:  return False\n",
    "    if card1.suit != card2.suit:  return False\n",
    "    return CardValues.outranks(card1,card2)\n",
    "\n",
    "# some operations on cards...\n",
    "\n",
    "def compare_cards( c1, c2 ):\n",
    "  if c1 > c2: return 'outranks'\n",
    "  if c2 > c1: return 'is outranked by'\n",
    "  if c1 == c2: return 'equals'\n",
    "  return 'is incomparable to'\n",
    "\n",
    "deck = CardDeck()\n",
    "ace_spades = deck.getCard('spades', 'ace')\n",
    "deuce_spades = deck.getCard('spades', '2')\n",
    "ace_clubs = deck.getCard('clubs', 'ace')\n",
    "deuce_clubs = deck.getCard('clubs', '2')\n",
    "\n",
    "# comparisons within suits\n",
    "print( f'The 2 of clubs {compare_cards( deuce_clubs, deuce_clubs )} the 2 of clubs' )\n",
    "print( f'The 2 of clubs {compare_cards( deuce_clubs, ace_clubs )} the ace of clubs' )\n",
    "print( f'The ace of clubs {compare_cards( ace_clubs, deuce_clubs )} the 2 of clubs' )\n",
    "print( f'The ace of clubs {compare_cards( ace_clubs, ace_clubs )} the ace of clubs' )\n",
    "print( f'The 2 of spades {compare_cards( deuce_spades, deuce_spades )} the 2 of spades' )\n",
    "print( f'The 2 of spades {compare_cards( deuce_spades, ace_spades )} the ace of spades' )\n",
    "print( f'The ace of spades {compare_cards( ace_spades, deuce_spades )} the 2 of spades' )\n",
    "print( f'The ace of spades {compare_cards( ace_spades, ace_spades )} the ace of spades' )\n",
    "\n",
    "# comparisons across suits\n",
    "print( f'The 2 of clubs {compare_cards( deuce_clubs, deuce_spades )} the 2 of spades' )\n",
    "print( f'The 2 of clubs {compare_cards( deuce_clubs, ace_spades )} the ace of spades' )\n",
    "print( f'The 2 of spades {compare_cards( deuce_spades, deuce_clubs )} the 2 of clubs' )\n",
    "print( f'The 2 of spades {compare_cards( deuce_spades, ace_clubs )} the ace of clubs' )\n",
    "print( f'The ace of clubs {compare_cards( ace_clubs, deuce_spades )} the 2 of spades' )\n",
    "print( f'The ace of clubs {compare_cards( ace_clubs, ace_spades )} the ace of spades' )\n",
    "print( f'The ace of spades {compare_cards( ace_spades, deuce_clubs )} the 2 of clubs' )\n",
    "print( f'The ace of spades {compare_cards( ace_spades, ace_clubs )} the ace of clubs' )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style='color:blue'>",
    "&#128073;&ensp;&ensp;**Exercise 11.3.1:**\n\n",
    "</span>",
    "<span style='color:navy'>",
    "In the following code cell, ",
    "modify the previous example so that ranking is determined by card within suit; i.e., so that all spades outrank all clubs. ",
    "Provide examples that show your change was correct.",
    "</span>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.9.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}