4.  Interactive help features.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": [
    "# 4.  Interactive Help Features  \n",
    " 4.1 [Dir](#Interactive-Help-Features-Dir)  \n",
    " 4.2 [Docstrings](#Interactive-Help-Features-Docstrings)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.1 Dir <a name='Interactive-Help-Features-Dir'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Python's `dir` function is commonly used to an object's or module's attributes.\n",
    "- `dir()`\n",
    "  -  when invoked with no arguments, lists all references to any objects in the Python interpreter's current scope.\n",
    "  -  when invoked at the level of the initial Python prompt, shows identifiers at global scope.\n",
    "- `dir(x)` shows attributes in object x\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4.2 Docstrings <a name='Interactive-Help-Features-Docstrings'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`__doc__` attributes, also known as *docstrings*, are a common means for learning about an object's behavior. ",
    "Docstrings are descriptive strings that an object's developers are encouraged-- but not required-- to associate with that object. ",
    "By convention, a docstring\n",
    "-  describes the purpose and use of its associated object\n",
    "-  may specify test cases for an object's associated methods, in ways that support those methods' automated testing\n",
    "   via Python library test routines.\n",
    "\n",
    "The following examples use these additional Python constructs:\n",
    "-  `exec(..statement list..)` \n",
    "   -  Effect:\n",
    "      -  interprets a string `..statement list..` that represents a list of Python statements\n",
    "      -  returns `None`.\n",
    "   -  Functions like `exec` are commonly used in interpreted languages to dynamically create and execute code\n",
    "   -  `exec` only evaluates statements; value-returning expressions must be evaluated using *eval*, rather than *exec*\n",
    "\n\n",
    "-  `eval(..expr..)` \n",
    "   -  Effect:\n",
    "      -  interprets a string `..expr..` that represents a Python expression in the current environment\n",
    "      -  returns this interpretation's result.\n",
    "   -  Functions like `eval` are commonly used in interpreted languages to dynamically create and execute code\n",
    "   -  `eval` only evaluates expressions; statements must be evaluated using *exec*, rather than *eval*\n",
    "\n\n",
    "-  `try:/except`:  Python's version of the classic exception-handling block\n",
    "   -  Exceptions throw objects that should be-- but aren't always-- self-describing.\n",
    "   -  The *try:/except Exception as exception:* formulation\n",
    "      -  catches all exceptions not caught to this point\n",
    "      -  associates the exception object with an identifier named *err*\n",
    "   -  The `str(exception)` checks if *exception* has a string that describes the exception\n",
    "      -  If not, the expression returns *None*, Python's version of the null object\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 4.2a show the use of a \"for\" loop to display all docstrings in Python's math module\n",
    "\n",
    "if 'math' not in dir(): import math\n",
    "\n",
    "for item in dir(math):\n",
    "  if '__doc__' in dir(item):\n",
    "    try:\n",
    "      try:\n",
    "        this_docstring = eval( f'math.{item}.__doc__' )\n",
    "      except:\n",
    "        this_docstring = eval( f'{item}.__doc__' )\n",
    "      print( f'{item}:\\n{this_docstring}' )\n",
    "    except Exception as exception:\n",
    "      errmsg = '' if str(exception) is None else ( '- ' + str(exception) )\n",
    "      print( f'{item}: cannot access docstring {errmsg}' )\n",
    "  else:\n",
    "    print( f'{item} has no docstring' )\n",
    "  print( '-----' )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 4.2b show the use of a \"for\" loop to display all docstrings in a list of modules\n",
    "\n",
    "modules_to_document = [ 'math' ]\n",
    "\n",
    "for module in modules_to_document:\n",
    "  if module not in dir(): exec( 'import '+ module )\n",
    "  for item in eval( f'dir({module})' ):\n",
    "    if '__doc__' in dir(item):\n",
    "      try:\n",
    "        try:\n",
    "          this_docstring = eval( f'{module}.{item}.__doc__' )\n",
    "        except:\n",
    "          this_docstring = eval( f'{item}.__doc__' )\n",
    "        print( f'{module}.{item}:\\n{this_docstring}' )\n",
    "      except Exception as exception:\n",
    "        errmsg = '' if str(exception) is None else ( '- ' + str(exception) )\n",
    "        print( f'{module}.{item}: cannot access docstring {errmsg}' )\n",
    "    else:\n",
    "      print( f'{module}.{item} has no docstring' )\n",
    "    print( '-----' )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***\n",
    "<span style='color:blue'>",
    "&#128073;&ensp;&ensp;**Exercise 4.2.1:**\n\n",
    "</span>",
    "<span style='color:navy'>",
    "In the following code cell, ",
    "repeat the above exercise, substituting `__builtins__`, Python's builtin-function module, for `math`.",
    "</span>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style='color:blue'>",
    "&#128073;&ensp;&ensp;**Exercise 4.2.2:**\n\n",
    "</span>",
    "<span style='color:navy'>",
    "In the following code cell, ",
    "repeat the above exercise, substituting `__builtins__` for `math` and reducing the body of the second `if` clause to two statements:\n",
    "-  <span style='color:navy'>",
    "this_docstring = eval( f'{module}.{item}.", "*__*", "doc__'", ")",
    "</span>\n",
    "-  <span style='color:navy'>",
    "print( f'{module}.{item}:\\n{this_docstring}' )",
    "</span>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style='color:blue'>",
    "&#128073;&ensp;&ensp;**Exercise 4.2.3:**\n\n",
    "</span>",
    "<span style='color:navy'>",
    "In the following markdown cell, ",
    "explain what changed with the replacement of the second `if` clause, and why.",
    "</span>\n",
    "***\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***\n"
   ]
  }
 ],
 "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
}