From c3fc760e700cc3196f9aef186cdce0ea3f8fb12e Mon Sep 17 00:00:00 2001
From: Alexander Hess <alexander@webartifex.biz>
Date: Sun, 22 Sep 2019 20:25:40 +0200
Subject: [PATCH] Add sample_module.py to the project

The file sample_module.py serves as an example in notebook 02  as to how
to create a local module and then import it.
---
 sample_module.py | 75 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 sample_module.py

diff --git a/sample_module.py b/sample_module.py
new file mode 100644
index 0000000..2efcda4
--- /dev/null
+++ b/sample_module.py
@@ -0,0 +1,75 @@
+"""This is a sample module.
+
+It defines three functions average(), average_evens(), and average_odds().
+The point is to show how we can put Python code in a .py file to be re-used
+in some other place.
+
+We should never forget to document the code as well, both on the module
+level (i.e., this docstring) but also in every function it defines.
+
+When imported, Python modules are executed top to bottom before the flow of
+execution returns to wherever they were imported into.
+
+An important convention is to prefix variables and functions that are not to
+be used outside the module with a single underscore "_". This way, we can
+design the code within a module in a modular fashion and only "export" what we
+want.
+
+Here, all three functions internally forward the computation to an internal
+utility function _scaled_average() that contains all the logic common to the
+three functions. Also, we define one _default_scalar variable that is used as
+the default for the scalar parameter in each of the functions.
+
+While this example is stylized, it shows how Python modules are often
+designed.
+"""
+
+_default_scalar = 1
+
+
+def _scaled_average(numbers, scalar):
+    """Internal utility function to calculate scaled averages."""
+    average = sum(numbers) / len(numbers)
+    return scalar * average
+
+
+def average(numbers, *, scalar=_default_scalar):
+    """Calculate the average of all numbers in a list.
+
+    Args:
+        numbers (list): list of numbers; may be integers or floats
+        scalar (float, optional): the scalar that multiplies the
+            average of the even numbers
+
+    Returns:
+        float: (scaled) average
+    """
+    return _scaled_average(numbers, scalar)
+
+
+def average_evens(numbers, *, scalar=_default_scalar):
+    """Calculate the average of all even numbers in a list.
+
+    Args:
+        numbers (list): list of numbers; may be integers or floats
+        scalar (float, optional): the scalar that multiplies the
+            average of the even numbers
+
+    Returns:
+        float: (scaled) average
+    """
+    return _scaled_average([n for n in numbers if n % 2 == 0], scalar)
+
+
+def average_odds(numbers, *, scalar=_default_scalar):
+    """Calculate the average of all odd numbers in a list.
+
+    Args:
+        numbers (list): list of numbers; may be integers or floats
+        scalar (float, optional): the scalar that multiplies the
+            average of the even numbers
+
+    Returns:
+        float: (scaled) average
+    """
+    return _scaled_average([n for n in numbers if n % 2 != 0], scalar)