New Section Idea: Exceptions

[samaocarpenter]

One important aspect of Python that isn't discussed in PLYMI is Python's exceptions, what causes them, and how to create your own. I feel like an additional section in the Odds And Ends Module would be appropriate, discussing

• The different types of exceptions and what they mean
• Assert statements and how to use them
• Raise statements and how to use them
• Creating a new exception with Python's Exception object

I'd love to write up this section for the site. Is this something that you guys find appropriate? @rsokl @davidmascharka

[davidmascharka]

I think having a discussion of exceptions and exception-handling would be really useful. It's actually super nice because we see various ValueErrors and other things being thrown throughout the website but there's no explanation of what that really means.

[rsokl]

I agree @HardBoiled800 's section would be really valuable. It might best fit as a section in The Essentials of Python. If so, it would have to come after functions are introduced so that raise can be discussed.

We should also take care to clarify for the reader that, despite their names, errors are exceptions. I recall this messing me up early on.

Regarding the different types of exceptions, I think that we'd want to explicitly draw attention to ValueError, IndexError, KeyError, and TypeError. @davidmascharka are there any other critical ones that may be encountered under simple circumstances? Here is a comprehensive list of concrete built-in exceptions. Towards the end of each section in PLYMI, we include links to the official documentation. We should include this link there and within the body of the section.

Regarding assertions. The proper usage for assert is a little bit subtle. For a long time I misused assertions, so I should make clear my thoughts on them up front. Assertions should be used to verify that an assumption that you make about your code holds true. That is, it is a check on a condition that should always be true. For example, suppose that you have some function that takes a 4D numpy array, does some processing, and returns a 2D array. The function should look something like this:

def array_func(arr):
    if arr.ndim != 4:
        raise ValueError("`arr` must be a 4D array")
    # some code here that should reduce 
    # `arr` to a 2D array
    assert arr.ndim == 2, "`array_func(arr)` unexpectedly produced an array that is not 2D"
    return arr 

Thus the initial check that the user provided a good array should raise a ValueError because the specific array value had the wrong dimensionality. The final check, on the other hand, is saying "make sure that we did in fact reduce this 4D array to a 2D array, as we assert should always be the case".

Regarding defining your own exception, this is a little bit tricky to cover as it requires an understanding of class inheritance, which isn't discussed until the very end of Module 3. It is also a rather advanced use case in the grand scheme of things. My impression is that one really doesn't need custom exceptions unless they are developing their own library. I'm open to discussion on this, but my thoughts are that we can make brief mention of this and then move on.

As @davidmascharka pointed out, we already make use of exceptions in the text. It would be great if we could find the earliest moments where we reference them and add a parenthetical link to our formal discussion of exceptions.

Lastly, it would be nice if we took time in this section to show readers how to understand stack traces and read error messages.

[samaocarpenter]

All good points, @rsokl. Maybe it would be more appropriate to include a subsection in the Classes and Inheritance sections about defining your own exceptions, but keep the majority of the discussion on Exceptions in The Essentials of Python?

Either way, I'll open up a new branch tonight and start to flesh out some of these ideas.

[rsokl]

Yeah, if we do want to touch on defining custom exceptions, it would need to be included separately in module 3. However, I'm not sure it meets the criterion of being "essential"

Sounds good! I'll be happy to help.

[davidmascharka]

I agree with Ryan; custom exceptions don't seem essential (I've still never written one...) so I'm not sure a section is warranted.

As far as other errors to cover go, the four you listed cover most use-cases. NameError and RecursionError are potentially useful but users probably won't actually be making use of them, just reading them. The same is probably true of NotImplementedError, especially if we're having this section before classes.

[samaocarpenter]

This is mostly covered in pull request #131 - I actually only just rediscovered this thread, so I may make a few edits to that request tonight to fully cover everything suggested here but it’s mostly there.