PCP_10_module.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div>\n",
    "<a href=\"https://www.audiolabs-erlangen.de/fau/professor/mueller\"><img src=\"data_layout/PCP_Teaser.png\" width=100% style=\"float: right;\" alt=\"PCP Teaser\"></a>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Unit 10: Python Modules and Packages\n",
    "\n",
    "<ul>\n",
    "    <li><a href='#learn'>Overview and Learning Objectives</a></li>    \n",
    "    <li><a href='#python_modules'>Python Modules</a></li>\n",
    "    <li><a href='#python_packages'>Python Packages</a></li>\n",
    "    <li><a href='#lib_PCP'>The Package <code>libpcp</code> </a></li>\n",
    "    <li><a href='#doc_functions'>Documentation of Functions</a></li>    \n",
    "</ul>    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='learn'></a> \n",
    "<div class=\"alert alert-block alert-warning\">\n",
    "<h2>Overview and Learning Objectives</h2>\n",
    "\n",
    "This final unit of the PCP notebooks serves several purposes. First, we give a general introduction to  <a href='#python_modules'>Python modules</a> and <a href='#python_packages'>Python packages</a>, which are fundamental concepts for organizing and making Python code available. Second, we introduce the Python package <code>libpcp</code> (that accompanies the PCP notebooks) and use this package as a concrete example for illustrating the Python concepts. At the same time, this unit (together with <a href='PCP_01_getstarted.html'>Unit 1</a>) also documents the technical backbone underlying the PCP notebooks. Last but not least, we will also uncover in this unit the secret of where one can find the sample solutions for all exercises. In summary, we hope that the PCP notebooks help students naturally transition from learning about Python programming and signal processing to beginning independent research following good scientific practices. Another main motivation of the notebooks is to indirectly guide students to employ open-source tools for software development and reproducible research. \n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='python_modules'></a> \n",
    "## Python Modules\n",
    "\n",
    "A Python module is basically a file with an extension `.py` containing Python code. The content of a module can be accessed with the `import` statement. As an example, we consider the file `module.py` contained in the folder `libpcp`. When the `import` statement is executed, the interpreter searches for `module.py` in a list of directories which specifies the search paths for modules. The variable `sys.path` (which is part of the module `sys`) yields the list of directories. It is initialized from the environment variable `PYTHONPATH` (plus an installation-dependent default). The list contained in `sys.path` can be extended using the function `sys.path.append`. The following example illustrates these concepts:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import sys\n",
    "print(sys.path, '\\n')\n",
    "\n",
    "import os\n",
    "sys.path.append('libpcp')\n",
    "print(sys.path, '\\n')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once the directory of the module is in the search path, we can use the `import` statement. Let us come back to our example `module.py`, which has the following content:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "fn = os.path.join('libpcp', 'module.py')\n",
    "with open(fn, 'r', encoding='utf-8') as stream:\n",
    "    content_text = stream.read()\n",
    "    \n",
    "print(content_text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following options import the module `module` or some of its elements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import libpcp.module\n",
    "result = libpcp.module.add(libpcp.module.a, libpcp.module.b, libpcp.module.c)\n",
    "\n",
    "from libpcp.module import add\n",
    "result = add(4, 5)\n",
    "\n",
    "from libpcp.module import add as s\n",
    "result = s(6)\n",
    "\n",
    "from libpcp.module import *\n",
    "result = add(a, b, c)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The file variable `module.__file__` determines the path where the module was found. Furthermore, when a `.py`-file is imported as a module, Python sets the variable `__name__` to the name of the module. Finally, the help-function shows the documentation of the specified module."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print('Directory of module:', libpcp.module.__file__)\n",
    "print('Name of module:', libpcp.module.__name__)\n",
    "print('=======================================')\n",
    "help(libpcp.module)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that any `.py`-file that contains a module can also be executed as a Python script (e.g., `module.py`). In the case that a file is run as a script, the variable `__name__` is set to the string `'__main__'`. This allows for placing additional statements in the module that are executed only when being run as a script (and not when imported as a module). For example, one can place these elements in a conditional (`if`) block as follows:\n",
    "\n",
    "```\n",
    "if (__name__ == '__main__'):\n",
    "    Statements only executed when run as a script\n",
    "```    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='python_packages'></a> \n",
    "## Python Packages\n",
    "\n",
    "A Python package is a namespace that consists of a directory, which in turn may contain subdirectories (sub-packages) and files (modules). The naming convention follows the hierarchical file structure using **dot notation**. Opposed to normal directories, a package in Python typically contains a particular file called `__init__.py` (until Python 3.3, the existence of such a file was even mandatory). This file is automatically executed when the package (or a module in the package) is imported. For example, this allows for initializing package-specific data or for automatically importing specific modules from a package. Continuing our example above, the directory `libpcp` can be regarded as a package. The content of its initialization file `__init__.py` is output in the next code cell. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "fn = os.path.join('libpcp', '__init__.py')\n",
    "with open(fn, 'r', encoding='utf-8') as stream:\n",
    "    content_text = stream.read() \n",
    "print(content_text)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Using `__init__.py` allows a user to call the functions without the need to specify the module name the functions are contained in. In the above example, the string `string_init` as well as the function `test_function_init` (which are contained in the module `module`) can be directly accessed via `libpcp`. This is demonstrated by the next example. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import libpcp\n",
    "print(libpcp.string_init)\n",
    "libpcp.test_function_init()\n",
    "libpcp.test_function_init('Hallo')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To call the other functions and variables in the module `module`, which are not specified in `__init__.py`, one needs to first import the module. The following code cell illustrates some options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import libpcp.module\n",
    "print(libpcp.module.string)\n",
    "print(libpcp.module.string_init)\n",
    "print(libpcp.string_init)\n",
    "\n",
    "from libpcp import module\n",
    "print(module.string)\n",
    "print(module.string_init)\n",
    "\n",
    "from libpcp import module as other_name\n",
    "print(other_name.string)\n",
    "print(other_name.string_init)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='lib_PCP'></a> \n",
    "## The Package `libpcp` \n",
    "\n",
    "As an illustration, we included in the Python package `libpcp` most of the functions specified in the PCP notebooks. Furthermore, the `libpcp` also contains the solutions of the exercises in form of functions, which are called in the respective notebooks to show the results (yet, note the source code to be implemented). The package `libpcp` contains ten modules that correspond to the ten units of the [PCP notebooks](PCP.html). In the following code cell, the package `LibFMP` is imported and its help page is displayed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import libpcp\n",
    "help(libpcp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `__init__.py`-file of `libpcp` was discussed before. Furthermore, using the module `module` as an example, we showed how to access the functions by first importing the module. In the following example, we import the module `complex` and show its content."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import libpcp.complex\n",
    "help(libpcp.complex)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we call the function `libpcp.complex.exercise_mandelbrot_fancy`, which produces a visualization of the [Mandelbrot Set](PCP_06_complex.html#exercise_mandelbrot)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "libpcp.complex.exercise_mandelbrot_fancy(save_file=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<a id='doc_functions'></a> \n",
    "## Documentation of Functions\n",
    "\n",
    "For documenting the functions contained in `libpcp`, we follow standard Python style conventions as formulated in the [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings). Except for the solutions to the exercise, the other `libpcp`-functions are contained in some PCP notebook, where one finds a detailed explanation of the application, the underlying theory, and implementation issues. In the `Docstring` of a `libpcp`-function, we specify the PCP notebook where the function is explained and developed. Using the `help`-function, the following example shows the docstring of the function `libpcp.complex.plot_vector`. In particular, the information `Notebook: PCP_06_complex.ipynb` shows that this function is introduced in the [PCP Notebook on Complex Numbers](PCP_06_complex.html) with the filename `PCP_06_complex.ipynb`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-block alert-warning\">\n",
    "<strong>Note:</strong> One needs to be careful to avoid name collisions when importing modules. For example, using <code>from libpcp import complex</code> leads to a collision of the Python method <code>complex()</code>, which returns a complex number. To avoid such collisions, one can use <code>import libpcp.complex</code> (as used above) or uses a renaming options (e.g., <code>from libpcp import complex as pcp_complex</code>).\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(libpcp.complex.plot_vector) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div>\n",
    "<a href=\"https://opensource.org/licenses/MIT\"><img src=\"data_layout/PCP_License.png\" width=100% style=\"float: right;\" alt=\"PCP License\"></a>\n",
    "</div>"
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.17"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}