work on exceptions

Akuli · Akuli · commit c338e740a217 · 2016-10-28T18:34:01.000+03:00
diff --git a/exceptions.md b/exceptions.md
@@ -1,42 +1,22 @@
 # Exceptions
 
-So far we have made programs that ask the user to enter a string.
+So far we have made programs that ask the user to enter a string, and
+we also know how to convert that to an integer.
 
 ```py
 text = input("Enter something: ")
-print("Your text twice:", text*2)
-```
-
-That works.
-
-```
-Enter something: hello
-Your text twice: hellohello
-```
-
-But if the user enters a number, it's not going to be multiplied by two.
-
-```
-Enter something: 3
-Your text twice: 33
-```
-
-Let's use `int` to convert that to an integer:
-
-```py
-text = input("Enter a number: ")
 number = int(text)
-print("Your number twice:", number*2)
+print("Your number doubled:", number*2)
 ```
 
-That works...
+That works.
 
 ```
 Enter a number: 3
 Your number twice: 6
 ```
 
-...unless the user does not enter a number.
+But that doesn't work if the user does not enter a number.
 
 ```py
 Enter a number: lol
@@ -53,7 +33,8 @@ So how can we fix that?
 In the previous example we got a ValueError. ValueError is an
 **exception**. In other words, ValueError is an error that can occur
 in our program. If an exception occurs, the program will stop and we
-get an error message.
+get an error message. The interactive prompt will display an error
+message and keep going.
 
 ```py
 >>> int('lol')
@@ -63,28 +44,21 @@ ValueError: invalid literal for int() with base 10: 'lol'
 >>> 
 ```
 
-Exceptions are classes, just like int and str. We'll talk more about
-classes later in this tutorial.
+Exceptions are [classes](classes.md).
 
 ```py
->>> str
-<class 'str'>
->>> int
-<class 'int'>
 >>> ValueError
 <class 'ValueError'>
 >>> 
 ```
 
-You can also create an exception. You won't get an error message by doing
+We can also create exceptions. We won't get an error message by doing
 that, but we'll use this for displaying our own error messages later.
 
 ```py
 >>> the_problem = ValueError('oh no')
 >>> the_problem
 ValueError('oh no',)
->>> type(the_problem)
-<class 'ValueError'>
 >>> 
 ```
 
@@ -124,6 +98,21 @@ TypeError: unsupported operand type(s) for +: 'int' and 'str'
 >>> 
 ```
 
+Exceptions always interrupt the code even if we catch them. Here the
+print never runs because it's after the error but inside the `try`
+block. Everything after the try block runs normally.
+
+```py
+>>> try:
+...     123 + 'hello'
+...     print("This doesn't get printed.")
+... except TypeError:
+...     print("Oops!")
+... 
+Oops!
+>>> 
+```
+
 Does an `except ValueError` also catch TypeErrors?
 
 ```py
@@ -163,7 +152,28 @@ wrong type
 
 Seems to be working.
 
-It's also possible to catch an exception, and store it in a variable:
+Catching `Exception` will catch all errors. We'll learn more about why
+it does that in a moment.
+
+```py
+>>> try:
+...     123 + 'hello'
+... except Exception:
+...     print("Oops!")
+... 
+Oops!
+>>> try:
+...     int('lol')
+... except Exception:
+...     print("Oops!")
+... 
+Oops!
+>>> 
+```
+
+It's also possible to catch an exception and store it in a variable.
+Here we are catching an exception that Python created and storing it in
+`our_error`.
 
 ```py
 >>> try:
@@ -178,10 +188,48 @@ TypeError("unsupported operand type(s) for +: 'int' and 'str'",)
 >>> 
 ```
 
+## When should we catch exceptions?
+
+Never do things like this:
+
+```py
+try:
+    # many lines of code
+except Exception:
+    print("Oops! Something went wrong.")
+```
+
+There's many things that can go wrong in the `try` block. If something
+goes wrong all we have is an oops message that doesn't tell us which
+line caused the problem. This makes fixing problems a lot harder. If we
+want to catch exceptions we need to be specific about what exactly we
+want to catch instead of catching everything we can.
+
+There's nothing wrong with doing things like this:
+
+```py
+try:
+    with open('some file', 'r') as f:
+        content = f.read()
+except OSError:     # we can't read the file but we can work without it
+    content = some_default_content
+```
+
+Usually catching errors that the user has caused is also a good idea:
+
+```py
+text = input("Enter a number: ")
+try:
+    number = int(text)
+except ValueError:
+    print("'%s' is not a number." % text, file=sys.stderr)
+    sys.exit(1)
+print("Your number doubled is %d." % (number * 2))
+```
+
 ## Raising exceptions
 
-When working on something that other programmers are going to use,
-you may end up doing something like this:
+Sometimes you may end up doing something like this:
 
 ```py
 if number < 0:
@@ -190,10 +238,10 @@ if number < 0:
 
 But that's not ideal. If there is an error, the code prints an error
 message but it still keeps running. People using your code also don't know
-which line in their code caused the error.
+which line in **their** code caused the error.
 
-Instead you can **raise** an exception yourself. Sometimes this is also
-called **throwing** an exception.
+Instead you can **raise an exception** yourself. Sometimes this is also
+called **throwing an exception**.
 
 ```py
 if number < 0:
@@ -210,19 +258,107 @@ ValueError: number must be non-negative
 >>> 
 ```
 
-It's working.
+Of course, we can also raise an exception from a variable.
 
-**TODO:** except Exception
+```py
+>>> oops = ValueError("number must be non-negative")
+>>> raise oops
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+ValueError: number must be non-negative
+>>> 
+```
 
-**TODO:** introduce assert here?
+## When should we raise exceptions?
+
+Back in [the module chapter](modules.md) we learned to display error
+messages by printing to `sys.stderr` and then calling `sys.exit(1)`, so
+when should we use that and when should we raise an exception?
+
+Exceptions are meant for **programmers**, so if we're writing a module
+that other people will import we should probably use exceptions. For
+other errors (for example, if the **user** of the program has done
+something wrong) it's usually better to use `sys.stderr` and `sys.exit`.
+
+## Exception hierarchy
+
+Exceptions are organized like this. I made this tree diagram with
+[this program](https://github.com/Akuli/classtree/) on Python 3.4. You
+may have more or less exceptions than I have if your Python is newer or
+older than mine, but they should be mostly similar.
+
+    Exception
+    ├── ArithmeticError
+    │   ├── FloatingPointError
+    │   ├── OverflowError
+    │   └── ZeroDivisionError
+    ├── AssertionError
+    ├── AttributeError
+    ├── BufferError
+    ├── EOFError
+    ├── ImportError
+    ├── LookupError
+    │   ├── IndexError
+    │   └── KeyError
+    ├── MemoryError
+    ├── NameError
+    │   └── UnboundLocalError
+    ├── OSError
+    │   ├── BlockingIOError
+    │   ├── ChildProcessError
+    │   ├── ConnectionError
+    │   │   ├── BrokenPipeError
+    │   │   ├── ConnectionAbortedError
+    │   │   ├── ConnectionRefusedError
+    │   │   └── ConnectionResetError
+    │   ├── FileExistsError
+    │   ├── FileNotFoundError
+    │   ├── InterruptedError
+    │   ├── IsADirectoryError
+    │   ├── NotADirectoryError
+    │   ├── PermissionError
+    │   ├── ProcessLookupError
+    │   └── TimeoutError
+    ├── ReferenceError
+    ├── RuntimeError
+    │   └── NotImplementedError
+    ├── StopIteration
+    ├── SyntaxError
+    │   └── IndentationError
+    │       └── TabError
+    ├── SystemError
+    ├── TypeError
+    ├── ValueError
+    │   └── UnicodeError
+    │       ├── UnicodeDecodeError
+    │       ├── UnicodeEncodeError
+    │       └── UnicodeTranslateError
+    └── Warning
+        ├── BytesWarning
+        ├── DeprecationWarning
+        ├── FutureWarning
+        ├── ImportWarning
+        ├── PendingDeprecationWarning
+        ├── ResourceWarning
+        ├── RuntimeWarning
+        ├── SyntaxWarning
+        ├── UnicodeWarning
+        └── UserWarning
+
+Catching an exception also catches everything that's under it in this
+tree. For example, catching `OSError` catches errors that we typically
+get when [processing files](files.md), and catching Exception catches
+all errors. You don't need to remember this tree, running
+`help('builtins')` should display a larger tree that this is a part of.
 
 ## Summary
 
-- Exceptions can be used just like any other variables.
+- Exceptions are classes and they can be used just like all other classes.
 - ValueError and TypeError are some of the most commonly used exceptions.
 - The `try` and `except` keywords can be used for attempting to do
-    something and then doing something else if it causes an error. This
-    is known as catching exceptions. You can use one `try` statement with
-    multiple `except` statements.
-- It's also possible to raise exceptions with the `raise` keyword. This
+    something and then doing something else if we get an error. This is
+    known as catching exceptions.
+- It's possible to raise exceptions with the `raise` keyword. This
     is also known as throwing exceptions.
+- Raise exceptions if they are meant to be displayed for programmers and
+    use `sys.stderr` and `sys.exit` otherwise.
