Adds Module 6: Testing Code

Python/Module2_EssentialsOfPython/Functions.md

@@ -137,7 +137,7 @@ Write a function named `count_even`. It should accept one input argument, named
 
 <!-- #region -->
 ## The `return` Statement
-In general, any Python object can follow a function's `return` statement. Furthermore, an **empty** `return` statement can be specified, or the **return** statement of a function can be omitted altogether. In both of these cases, *the function will return the `None` object*.
+In general, any Python object can follow a function's `return` statement. Furthermore, an **empty** `return` statement can be specified, or the **return** statement of a function can be omitted altogether. In both of these cases, *the function will return the* `None` *object*.
 
 ```python
 # this function returns `None`

Python/Module3_IntroducingNumpy/Broadcasting.md

@@ -5,7 +5,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.0rc1
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
@@ -486,16 +486,16 @@ Performing this computation using for-loops proceeds as follows:
 def pairwise_dists_looped(x, y):
     """  Computing pairwise distances using for-loops
 
-         Parameters
-         ----------
-         x : numpy.ndarray, shape=(M, D)
-         y : numpy.ndarray, shape=(N, D)
+     Parameters
+     ----------
+     x : numpy.ndarray, shape=(M, D)
+     y : numpy.ndarray, shape=(N, D)
 
-         Returns
-         -------
-         numpy.ndarray, shape=(M, N)
-             The Euclidean distance between each pair of
-             rows between `x` and `y`."""
+     Returns
+     -------
+     numpy.ndarray, shape=(M, N)
+         The Euclidean distance between each pair of
+         rows between `x` and `y`."""
     # `dists[i, j]` will store the Euclidean 
     # distance between  `x[i]` and `y[j]`
     dists = np.empty((5, 6))
@@ -545,18 +545,18 @@ Voilà! We have produced the distances in a vectorized way. Let's write this out
 def pairwise_dists_crude(x, y):
     """  Computing pairwise distances using vectorization.
 
-         This method uses memory-inefficient broadcasting.
-         
-         Parameters
-         ----------
-         x : numpy.ndarray, shape=(M, D)
-         y : numpy.ndarray, shape=(N, D)
-         
-         Returns
-         -------
-         numpy.ndarray, shape=(M, N)
-             The Euclidean distance between each pair of
-             rows between `x` and `y`."""
+     This method uses memory-inefficient broadcasting.
+
+     Parameters
+     ----------
+     x : numpy.ndarray, shape=(M, D)
+     y : numpy.ndarray, shape=(N, D)
+
+     Returns
+     -------
+     numpy.ndarray, shape=(M, N)
+         The Euclidean distance between each pair of
+         rows between `x` and `y`."""
     # The use of `np.newaxis` here is equivalent to our 
     # use of the `reshape` function
     return np.sqrt(np.sum((x[:, np.newaxis] - y[np.newaxis])**2, axis=2))
@@ -628,23 +628,23 @@ In total, we have successfully used vectorization to compute the all pairs of di
 
 ```python
 def pairwise_dists(x, y):
-    """ Computing pairwise distances using memory-efficient 
-        vectorization.
-
-        Parameters
-        ----------
-        x : numpy.ndarray, shape=(M, D)
-        y : numpy.ndarray, shape=(N, D)
-
-        Returns
-        -------
-        numpy.ndarray, shape=(M, N)
-            The Euclidean distance between each pair of
-            rows between `x` and `y`."""
+    """ Computing pairwise distances using memory-efficient
+    vectorization.
+
+    Parameters
+    ----------
+    x : numpy.ndarray, shape=(M, D)
+    y : numpy.ndarray, shape=(N, D)
+
+    Returns
+    -------
+    numpy.ndarray, shape=(M, N)
+        The Euclidean distance between each pair of
+        rows between `x` and `y`."""
     dists = -2 * np.matmul(x, y.T)
-    dists +=  np.sum(x**2, axis=1)[:, np.newaxis]
+    dists += np.sum(x**2, axis=1)[:, np.newaxis]
     dists += np.sum(y**2, axis=1)
-    return  np.sqrt(dists)
+    return np.sqrt(dists)
 ```
 
 

Python/Module5_OddsAndEnds/Modules_and_Packages.md

@@ -5,7 +5,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.3.0rc1
+      jupytext_version: 1.3.0
   kernelspec:
     display_name: Python 3
     language: python
@@ -406,15 +406,15 @@ It must be mentioned that we are sweeping some details under the rug here. Insta
 
 ### Installing Your Own Python Package
 
-Suppose that we are happy with the work we have done on our `face_detector` project. We will want to install this package - placing it in our site-packages directory so that we can import it irrespective of our Python interpreter's working directory. Here we will construct a basic setup script that will allow us to accomplish this. 
+Suppose that we are happy with the work we have done on our `face_detector` project. We will want to install this package - placing it in our site-packages directory so that we can import it irrespective of our Python interpreter's working directory. Here we will construct a basic setup script that will allow us to accomplish this. For completeness, we will also indicate how one would include a test suite alongside the source code in this directory structure.
 
 We note outright that the purpose of this section is strictly to provide you with the minimum set of instructions needed to install a package. We will not be diving into what is going on under the hood at all. Please refer to [An Introduction to Distutils](https://docs.python.org/3/distutils/introduction.html#an-introduction-to-distutils) and [Packaging Your Project](https://packaging.python.org/tutorials/packaging-projects/#packaging-your-project) for a deeper treatment of this topic.
 
 Carrying on, we will want to create a setup-script, `setup.py`, *in the same directory as our package*. That is, our directory structure should look like:
 
 ```
-- setup.py
-- face_detection/
+- setup.py         # script responsible for installing `face_detection` package
+- face_detection/  # source code of `face_detection` package
     |-- __init__.py
     |-- utils.py
     |-- database.py
@@ -423,31 +423,42 @@ Carrying on, we will want to create a setup-script, `setup.py`, *in the same dir
         |-- __init__.py
         |-- calibration.py
         |-- config.py
+- tests/            # test-suite for `face_detection` package (to be run using pytest)
+    |-- conftest.py # optional configuration file for pytest
+    |-- test_utils.py
+    |-- test_database.py
+    |-- test_model.py
+    |-- camera/
+        |-- test_calibration.py
+        |-- test_config.py  
 ```
 
+A `tests/` directory can be included at the same directory level as `setup.py` and `face_detection/`.
+This is the recommended structure for using [pytest](https://docs.pytest.org/en/latest/) as our test-runner.
+
 <!-- #region -->
 The bare bones build script for preparing your package for installation, `setup.py`, is as follows: 
 
 ```python
 # contents of setup.py
-import setuptools
+from setuptools import find_packages, setup
 
-setuptools.setup(
+setup(
     name="face_detection",
-    version="1.0",
-    packages=setuptools.find_packages(),
+    version="1.0.0",
+    packages=find_packages(exclude=["tests", "tests.*"]),
+    python_requires=">=3.5",
 )
 ```
-
-
+The `exclude` expression is used to ensure that specific directories or files are not included in the installation of `face_detection`. We use `exclude=["tests", "tests.*"]` to avoid installing the test-suite alongside `face_detection`.
 <!-- #endregion -->
 
 If you read through the additional materials linked above, you will see that there are many more fields of optional information that can be provided in this setup script, such as the author name, any installation requirements that the package has, and more.
 
 Armed with this script, we are ready to install our package locally on our machine! In your terminal, navigate to the directory containing this setup script and your package that it being installed. Run
 
 ```shell
-python setup.py install
+pip install .
 ```
 
 and voilà, your package `face_detection` will have been installed to site-packages. You are now free to import this package from any directory on your machine. In order to uninstall this package from your machine execute the following from your terminal:
@@ -456,10 +467,10 @@ and voilà, your package `face_detection` will have been installed to site-packa
 pip uninstall face_detection
 ```
 
-One final but important detail. The installed version of your package will no longer "see" the source code. That is, if you go on to make any changes to your code, you will have to uninstall and reinstall your package before your will see the effects system-wide. Instead you can install your package in develop mode, such that a symbolic link to your source code is placed in your site-packages. Thus any changes that you make to your code will immediately be reflected in your system-wide installation. Thus, instead of running `python setup.py install`, execute the following to install a package in develop mode:
+One final but important detail: the installed version of your package will no longer "see" the source code. That is, if you go on to make any changes to your code, you will have to uninstall and reinstall your package before your will see the effects system-wide. Instead, you can install your package in "development mode", such that a symbolic link to your source code is placed in your site-packages. Thus, any changes that you make to your code will immediately be reflected in your system-wide installation. You can add the `--editable` flag to pip to install a package in development mode:
 
 ```shell
-python setup.py develop
+pip install --editable .
 ```
 
 

Python/Module5_OddsAndEnds/Writing_Good_Code.md

@@ -636,7 +636,7 @@ To be more concrete, let's revisit our `count_vowels` function:
 
 ```python
 def count_vowels(x: str, include_y: bool = False) -> int:
-    """Returns the number of vowels contained in `in_string`"""
+    """Returns the number of vowels contained in `x`"""
     vowels = set("aeiouAEIOU")
     if include_y:
         vowels.update("yY")
@@ -774,14 +774,16 @@ def pairwise_dists(x: np.ndarray, y: np.ndarray) -> np.ndarray:
     Parameters
     ----------
     x : numpy.ndarray, shape=(M, D)
-        An optional description of ``x``
+        An array of M, D-dimensional vectors.
+
     y : numpy.ndarray, shape=(N, D)
-        An optional description of ``y``
+        An array of N, D-dimensional vectors.
 
     Returns
     -------
     numpy.ndarray, shape=(M, N)
-        The pairwise distances
+        The pairwise distances between the M rows of ``x`` and the N 
+        rows of ``y``.
 
     Notes
     -----
@@ -829,7 +831,7 @@ def compute_student_stats(grade_book: Dict[str, Iterable[float]],
 
     Parameters
     ----------
-    grade_book : Dict[str, List[float]]
+    grade_book : Dict[str, Iterable[float]]
         The dictionary (name -> grades) of all of the students' 
         grades.