13. Packages.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": [
    "# 13. Packages   \n",
    " 13.1 [Overview](#Packages-Overview)  \n",
    " 13.2 [Using `__init__` to Configure Package Imports](#Packages-Using-__init__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 13.1 Overview <a name='Packages-Overview'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A *package* is a directory that contains Python files. ",
    "Its name must conform to rules for naming Python identifiers: ",
    "for example, 'myPackage' and 'my_package' are valid names for package directories;",
    "'my Package' and 'my-Package' are not.\n",
    "\n",
    "Python packages are accessed using `import` statements. ",
    "In order for a Python code to access a package, the directory that contains that package must be named in `sys.path`. ",
    "If, for example, a directory on `sys.path` contains a package directory name *pkg*, ",
    "then *pkg*'s contents can be loaded using the statement `import pkg`. \n",
    "\n",
    "A package directory may hold sub-directories and files. ",
    "Continuing the previous example, if *pkg* contains a package directory, *subpkg*, ",
    "then *subpkg*'s contents can be accessed using the statement `import pkg.subpkg`. ",
    "These conventions should be familiar to anyone who's worked with packages in the Java programming language.\n",
    "\n",
    "Note:  The `importlib.reload` commands override",
    " Python's suppression of attempts to import a module that's already been imported. ",
    "This caching of previously imported modules optimizes execution by avoiding the useless reimportation of code that hasn't changed. ",
    "It also, however, creates a need to force the reloading of modules that were updated during a Python session, ",
    "like the modules created and recreated by these examples."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 13.1  Creating, then accessing, a package.\n",
    "\n",
    "# supporting constants\n",
    "CREATE_AS_NEW_FILE = 'x'    # file access mode for open()\n",
    "\n",
    "# library resources\n",
    "import os, sys, importlib, shutil\n",
    "\n",
    "# supporting functions\n",
    "make_printable = lambda exception: '' if str(exception) is None else str(exception)\n",
    "\n",
    "# precondition check: ensure that we're creating a totally new, unreferenced module in a totally new directory\n",
    "\n",
    "package_name = 'my_package'\n",
    "corrective_action = f'please ensure that {package_name} names a non-existent file system object'\n",
    "assert not os.path.exists( package_name ), corrective_action\n",
    "\n",
    "package_module_name = 'my_module'\n",
    "package_module_path= f'{package_name}/{package_module_name}.py'\n",
    "module_fn = 'sample_function'\n",
    "\n",
    "importlib.invalidate_caches()   # clear stale module data, possibly from previous exercise\n",
    "\n",
    "# preconditions established: create a package in the local directory, then try to import and use it\n",
    "\n",
    "try:\n",
    "  #  create the package directory\n",
    "  #\n",
    "  os.mkdir( package_name )\n",
    "  try:\n",
    "    return_message = f'{module_fn} in {package_module_path}: {{x}}+{{y}} is {{x+y}}'\n",
    "    function_header  = f'def {module_fn}(x, y):'\n",
    "    function_body    = \"return f'\" + return_message + \"'\"\n",
    "    try:\n",
    "      #  create the function's lone module\n",
    "      #  \n",
    "      package_module_fd = open( package_module_path, CREATE_AS_NEW_FILE )\n",
    "      package_module_fd.write( function_header + '\\n' )\n",
    "      package_module_fd.write( '  ' + function_body + '\\n' )\n",
    "      package_module_fd.close()\n",
    "      try:\n",
    "        #  (re)import the module and execute the function\n",
    "        #  \n",
    "        exec( f'import {package_name}' )\n",
    "        exec( f'importlib.reload( {package_name} )' )\n",
    "        exec( f'import {package_name}.{package_module_name}' )\n",
    "        exec( f'importlib.reload( {package_name}.{package_module_name} )' )\n",
    "        try:\n",
    "          result_from_sample_function = eval( f'{package_name}.{package_module_name}.{module_fn}(3, 4)' )\n",
    "          print( result_from_sample_function )\n",
    "        except Exception as exception:\n",
    "          print( f\"can't access {package_name}.{package_module_name}.{module_fn}: {make_printable(exception)}\" )\n",
    "      except Exception as exception:\n",
    "        print( f\"can't import {package_name}: {make_printable(exception)}\" )\n",
    "    except Exception as exception:\n",
    "      print( f\"can't create file ({package_module_path}): {make_printable(exception)}\" )\n",
    "  except Exception as exception:\n",
    "    print( f\"can't create file ({package_init_path}): {make_printable(exception)}\" )\n",
    "  finally:\n",
    "    try:\n",
    "      shutil.rmtree( package_name )\n",
    "    except Exception as exception:\n",
    "      print( f\"can't remove directory ({package_name}): {make_printable(exception)}\" )\n",
    "except Exception as exception:\n",
    "  print( f\"can't create directory ({package_name}): {make_printable(exception)}\" )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 13.2 Using `__init__` to Configure Package Imports <a name='Packages-Using-__init__'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before Python 3.3, packages were required to include a file named `__init__.py` in their home directories. ",
    "While this requirement has been lifted, including `__init__.py` can be useful for configuring package operation. ",
    "When a package is first imported, Python executes code in `__init__.py`. ",
    "Accordingly, one use of `__init__.py` is to define initialize package variables.  \n",
    "\n",
    "This example also illustrates the use of relative path expressions to import values. ",
    "Note that the sample function must import its package's variable in order to access it.\n",
    "\n",
    "To see how the package is structured and what it contains, comment out the call to `shutil.rmtree` ",
    "in the example's `finally` block and replace the statement with a `pass` statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 13.2  Creating, then accessing, a package that uses `__init__.py` to predefine a variable.\n",
    "\n",
    "# supporting constants\n",
    "CREATE_AS_NEW_FILE = 'x'    # file access mode for open()\n",
    "\n",
    "# library resources\n",
    "import os, sys, importlib, shutil\n",
    "\n",
    "# supporting functions\n",
    "make_printable = lambda exception: '' if str(exception) is None else str(exception)\n",
    "\n",
    "# precondition check: ensure that we're creating a totally new, unreferenced module in a totally new directory\n",
    "\n",
    "package_name = 'my_package'\n",
    "corrective_action = f'please ensure that {package_name} names a non-existent file system object'\n",
    "assert not os.path.exists( package_name ), corrective_action\n",
    "\n",
    "package_init_name = '__init__'\n",
    "package_init_path= f'{package_name}/{package_init_name}.py'\n",
    "package_module_name = 'my_module'\n",
    "package_module_path= f'{package_name}/{package_module_name}.py'\n",
    "package_var = 'a'\n",
    "module_fn = 'sample_function'\n",
    "\n",
    "importlib.invalidate_caches()   # clear stale module data, possibly from previous exercise\n",
    "\n",
    "# preconditions established: create a package in the local directory, then try to import and use it\n",
    "\n",
    "try:\n",
    "  #  create the package directory\n",
    "  #\n",
    "  os.mkdir( package_name )\n",
    "  try:\n",
    "    #  create and configure the __init__ module\n",
    "    #  \n",
    "    package_init_fd = open( package_init_path, CREATE_AS_NEW_FILE )\n",
    "    package_init_fd.write( package_var + ' = 3' + '\\n' )\n",
    "    package_init_fd.close()\n",
    "    #  define the package's lone function\n",
    "    #  \n",
    "    function_header  = f'def {module_fn}( ):'\n",
    "    return_message = f'{module_fn} in {package_module_path}: {package_var} is '\n",
    "    function_body = \"return f'\" + return_message + \"'\" + ' + ' + 'str(' + f'{package_var}' + ')'\n",
    "    try:\n",
    "      #  create the function's lone module\n",
    "      #  \n",
    "      package_module_fd = open( package_module_path, CREATE_AS_NEW_FILE )\n",
    "      package_module_fd.write( function_header + '\\n' )\n",
    "      package_module_fd.write( '  ' + 'from . import ' + package_var + '\\n' )\n",
    "      package_module_fd.write( '  ' )\n",
    "      package_module_fd.write( function_body )\n",
    "      package_module_fd.write( '\\n' )\n",
    "      package_module_fd.close()\n",
    "      try:\n",
    "        #  (re)import the module and execute the function\n",
    "        #  \n",
    "        exec( f'import {package_name}' )\n",
    "        exec( f'importlib.reload( {package_name} )' )\n",
    "        exec( f'import {package_name}.{package_module_name}' )\n",
    "        exec( f'importlib.reload( {package_name}.{package_module_name} )' )\n",
    "        try:\n",
    "          result_from_sample_function = eval( f'{package_name}.{package_module_name}.{module_fn}( )' )\n",
    "          print( result_from_sample_function )\n",
    "        except Exception as exception:\n",
    "          print( f\"can't access {package_name}.{package_module_name}.{module_fn}: {make_printable(exception)}\" )\n",
    "      except Exception as exception:\n",
    "        print( f\"can't import {package_name}: {make_printable(exception)}\" )\n",
    "    except Exception as exception:\n",
    "      print( f\"can't create file ({package_module_path}): {make_printable(exception)}\" )\n",
    "  except Exception as exception:\n",
    "    print( f\"can't create file ({package_init_path}): {make_printable(exception)}\" )\n",
    "  finally:\n",
    "    try:\n",
    "      shutil.rmtree( package_name )\n",
    "    except Exception as exception:\n",
    "      print( f\"can't remove directory ({package_name}): {make_printable(exception)}\" )\n",
    "except Exception as exception:\n",
    "  print( f\"can't create directory ({package_name}): {make_printable(exception)}\" )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style='color:blue'>",
    "&#128073;&ensp;&ensp;**Exercise 13.2.1:**\n\n",
    "</span>",
    "<span style='color:navy'>",
    "In the following code cell, ",
    "modify the previous example so that `sample_function` takes one parameter, an int, and returns the sum of this parameter and `a`. ",
    "Illustrate the code's operation by invoking it at least twice with nonzero arguments and printing the return values.",
    "</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
}