Merge pull request #316 from realpython/python-doctest

Sample code for the `doctest` article

Author: KateFinegan

python-doctest/README.md

@@ -0,0 +1,3 @@
+# Python's doctest: Document and Test Your Code at Once
+
+This folder provides the code examples for the article [Python's doctest: Document and Test Your Code at Once](https://realpython.com/python-doctest/).

python-doctest/calculations/README.md

@@ -0,0 +1,24 @@
+# Functions to Perform Arithmetic Calculations
+
+The `calculations.py` Python module provides basic arithmetic operations, including addition, subtraction, multiplication, and division.
+
+Here are a few examples of how to use the functions in `calculations.py`:
+
+```python
+>>> import calculations
+
+>>> calculations.add(2, 2)
+4.0
+
+>>> calculations.subtract(2, 2)
+0.0
+
+>>> calculations.multiply(2, 2)
+4.0
+
+>>> calculations.divide(2, 2)
+1.0
+
+```
+
+These examples show how to use the `calculations.py` module in your code.

python-doctest/calculations/calculations.py

@@ -0,0 +1,65 @@
+"""Provide several sample math calculations.
+
+This module allows the user to make mathematical calculations.
+
+Module-level tests:
+>>> add(2, 4)
+6.0
+>>> subtract(5, 3)
+2.0
+>>> multiply(2.0, 4.0)
+8.0
+>>> divide(4.0, 2)
+2.0
+"""
+
+
+def add(a, b):
+    """Compute and return the sum of two numbers.
+
+    Tests for add():
+    >>> add(4.0, 2.0)
+    6.0
+    >>> add(4, 2)
+    6.0
+    """
+    return float(a + b)
+
+
+def subtract(a, b):
+    """Calculate the difference of two numbers.
+
+    Tests for subtract():
+    >>> subtract(4.0, 2.0)
+    2.0
+    >>> subtract(4, 2)
+    2.0
+    """
+    return float(a - b)
+
+
+def multiply(a, b):
+    """Compute and return the product of two numbers.
+
+    Tests for multiply():
+    >>> multiply(4.0, 2.0)
+    8.0
+    >>> multiply(4, 2)
+    8.0
+    """
+    return float(a * b)
+
+
+def divide(a, b):
+    """Compute and return the quotient of two numbers.
+
+    Tests for divide():
+    >>> divide(4.0, 2.0)
+    2.0
+    >>> divide(4, 2)
+    2.0
+    >>> divide(4, 0)
+    Traceback (most recent call last):
+    ZeroDivisionError: division by zero
+    """
+    return float(a / b)

python-doctest/calculations/test_calculations.py

@@ -0,0 +1,16 @@
+import doctest
+import unittest
+
+import calculations
+
+
+def load_tests(loader, tests, ignore):
+    tests.addTests(doctest.DocFileSuite("test_calculations.txt"))
+    tests.addTests(doctest.DocTestSuite(calculations))
+    return tests
+
+
+# Your unittest tests goes here...
+
+if __name__ == "__main__":
+    unittest.main()

python-doctest/calculations/test_calculations.txt

@@ -0,0 +1,19 @@
+>>> import calculations
+
+>>> calculations.add(2, 2)
+4.0
+
+>>> calculations.subtract(2, 2)
+0.0
+
+>>> calculations.multiply(2, 2)
+4.0
+
+>>> calculations.divide(2, 2)
+1.0
+
+>>> def test_add():
+...     import calculations
+...     return calculations.add(2, 4)
+>>> test_add()
+6.0

python-doctest/context.py

@@ -0,0 +1,34 @@
+total = 100
+
+
+def decrement_by(number):
+    """Decrement the global total variable by a given number.
+
+    >>> local_total = decrement_by(50)
+    >>> local_total
+    50
+
+    Changes to total don't affect the code's global scope
+    >>> total
+    100
+    """
+    global total
+    total -= number
+    return total
+
+
+def increment_by(number):
+    """Increment the global total variable by a given number.
+
+    The initial value of total's shallow copy is 50
+    >>> increment_by(10)
+    60
+
+    The local_total variable is not defined in this test
+    >>> local_total
+    Traceback (most recent call last):
+    NameError: name 'local_total' is not defined
+    """
+    global total
+    total += number
+    return total

python-doctest/failing_tests.py

@@ -0,0 +1,23 @@
+"""Sample failing tests.
+
+The output must be an integer
+>>> 5 + 7
+12.0
+
+The output must not contain quotes
+>>> print("Hello, World!")
+'Hello, World!'
+
+The output must not use double quotes
+>>> "Hello," + " World!"
+"Hello, World!"
+
+The output must not contain leading or trailing spaces
+>>> print("Hello, World!")
+  Hello, World!
+
+The traceback doesn't include the correct exception message
+>>> raise ValueError("incorrect value")
+Traceback (most recent call last):
+ValueError: invalid value
+"""

python-doctest/fizzbuzz.py

@@ -0,0 +1,76 @@
+# The commented versions of fizzbuzz() below reflect the steps
+# followed to get to the final version at the end of the file.
+
+# Replace numbers that are divisible by 3 with "fizz"
+# def fizzbuzz(numbers):
+#     """Implement the Fizz buzz game.
+
+#     >>> fizzbuzz([3, 6, 9, 12])
+#     ['fizz', 'fizz', 'fizz', 'fizz']
+#     """
+
+
+# # Replace numbers that are divisible by 3 with "fizz"
+# def fizzbuzz(numbers):
+#     """Implement the Fizz buzz game.
+
+#     >>> fizzbuzz([3, 6, 9, 12])
+#     ['fizz', 'fizz', 'fizz', 'fizz']
+#     """
+#     result = []
+#     for number in numbers:
+#         if number % 3 == 0:
+#             result.append("fizz")
+#         else:
+#             result.append(number)
+#     return result
+
+
+# Replace numbers that are divisible by 5 with "buzz"
+# def fizzbuzz(numbers):
+#     """Implement the Fizz buzz game.
+
+#     >>> fizzbuzz([3, 6, 9, 12])
+#     ['fizz', 'fizz', 'fizz', 'fizz']
+
+#     >>> fizzbuzz([5, 10, 20, 25])
+#     ['buzz', 'buzz', 'buzz', 'buzz']
+#     """
+#     result = []
+#     for number in numbers:
+#         if number % 3 == 0:
+#             result.append("fizz")
+#         elif number % 5 == 0:
+#             result.append("buzz")
+#         else:
+#             result.append(number)
+#     return result
+
+
+# Replace numbers that are divisible by 3 and 5 with "fizz buzz"
+def fizzbuzz(numbers):
+    """Implement the Fizz buzz game.
+
+    >>> fizzbuzz([3, 6, 9, 12])
+    ['fizz', 'fizz', 'fizz', 'fizz']
+
+    >>> fizzbuzz([5, 10, 20, 25])
+    ['buzz', 'buzz', 'buzz', 'buzz']
+
+    >>> fizzbuzz([15, 30, 45])
+    ['fizz buzz', 'fizz buzz', 'fizz buzz']
+
+    >>> fizzbuzz([3, 6, 5, 10, 15, 30])
+    ['fizz', 'fizz', 'buzz', 'buzz', 'fizz buzz', 'fizz buzz']
+    """
+    result = []
+    for number in numbers:
+        if number % 15 == 0:
+            result.append("fizz buzz")
+        elif number % 3 == 0:
+            result.append("fizz")
+        elif number % 5 == 0:
+            result.append("buzz")
+        else:
+            result.append(number)
+    return result

python-doctest/greet.py

@@ -0,0 +1,36 @@
+def greet_with_bank_line(name="World"):
+    """Print a greeting.
+
+    Usage examples:
+    >>> greet("Pythonista")
+    Hello, Pythonista!
+    <BLANKLINE>
+    How have you been?
+    """
+    print(f"Hello, {name}!")
+    print()
+    print("How have you been?")
+
+
+def greet_with_raw_docstring(name="World"):
+    r"""Print a greeting.
+
+    Usage examples:
+    >>> greet("Pythonista")
+    /== Hello, Pythonista! ==\
+    \== How have you been? ==/
+    """
+    print(f"/== Hello, {name}! ==\\")
+    print("\\== How have you been? ==/")
+
+
+def greet_with_scaped_backslash(name="World"):
+    """Print a greeting.
+
+    Usage examples:
+    >>> greet("Pythonista")
+    /== Hello, Pythonista! ==\\
+    \\== How have you been? ==/
+    """
+    print(f"/== Hello, {name}! ==\\")
+    print("\\== How have you been? ==/")

python-doctest/identity.py

@@ -0,0 +1,8 @@
+def get_id(obj):
+    """Return the identity of an object.
+
+    This test always fails
+    >>> get_id(1)  # doctest: +ELLIPSIS
+    ...
+    """
+    return id(obj)