Are you tired of writing tests for your code only to have them fail because you forgot a comma or misspelled a variable name? Well, my friend, do I have the solution for you: Doctest Directives!

Do what now? You might ask. Let me explain in simpler terms it’s like having a built-in assistant that checks your code as you write it. No more copying and pasting test cases into separate files or running them manually. With doctests, you can embed tests directly into your Python documentation!

Here’s an example:

# This function adds two numbers together.
def add_numbers(x, y):
    """Add two numbers together.

    > add_numbers(2, 3) # This is a doctest, which is used to test the function by providing input and expected output.
    5 # This is the expected output for the given input.
    > add_numbers(-10, 7)
    -3 # This is the expected output for the given input.
    """

    return x + y # This line returns the sum of the two input numbers.

See that? The comments above the function are actually tests! When you run your code with doctest (which is included in Python’s standard library), it will execute those examples and check if they pass. If any of them fail, it will print an error message telling you exactly which line failed.

The best part? Doctests can handle edge cases too! Let’s say your function has a bug that causes it to crash when given negative numbers:

# This function adds two numbers together
def add_numbers(x, y):
    """Add two numbers together.

    > add_numbers(2, 3) # This doctest checks if the function correctly adds positive numbers
    5
    > add_numbers(-10, 7) # This doctest checks if the function correctly adds a negative and a positive number
    -3 # The expected result should be 3, not -3
    > add_numbers(0, -10) # This should crash!
    Traceback (most recent call last):
        ...
    ValueError: can't add negative numbers together # This doctest checks if the function raises a ValueError when given negative numbers
    """

    if x < 0 or y < 0:
        raise ValueError("can't add negative numbers together") # This if statement checks if either x or y is negative, and if so, raises a ValueError
    return x + y # This line correctly adds x and y together and returns the result

Now, when you run doctest on this code, it will fail at the third example because of the expected error message. This is great for catching bugs early and making sure your code works as intended!

Give them a try in your next project, and let me know how they work out for you!

But wait, did you know that doctest is just one of many resources available to help you learn Python? The Python community has created countless books, tutorials, and online courses to teach the language. You can find a list of recommended books on python.org’s wiki page . And if you prefer learning through video or interactive lessons, there are plenty of options for that too!

The Python project’s infrastructure is managed by the Python Infrastructure Team , which ensures that the code and documentation stay up-to-date and accessible to everyone around the world. So whether you’re a beginner or an experienced developer, there’s always something new to learn in the world of Python!