you->we, more examples, other fixes

Author: Akuli

classes.md

@@ -5,9 +5,9 @@ tkinter GUI's before I understood how they work. Everything I did with
 classes worked, but I didn't understand how. Hopefully you'll first
 learn to understand classes, and then learn to use them.
 
-This tutorial assumes that you know how functions work and how to
-create your own functions with the `def` keyword. If you don't, I
-highly recommend learning that first, and then moving to classes.
+This tutorial assumes that you know [how functions work](using-functions.md)
+and [how to create your own functions](defining-functions.md). If you
+don't I highly recommend learning that first, and then moving to classes.
 
 ## Why should I use custom classes in my projects?
 
@@ -81,13 +81,6 @@ Let's use it to define an empty class.
 >>> 
 ```
 
-_**Note:** If you are using Python 2 I highly recommend using
-`class Website(object):` instead of `class Website:`. This creates a
-new-style class instead of an old-style class. Old-style classes are
-different than new-style classes in some ways and not supported in this
-tutorial. In Python 3, there are no old-style classes and
-`class Website(object):` does the same thing as `class Website:`._
-
 Note that I named the class `Website`, not `website`. This way we know
 that it's a class. Built-in classes use lowercase names (like `str`
 instead of `Str`) because they are faster to type, but use CapsWord
@@ -126,11 +119,17 @@ True
 >>> 
 ```
 
+As you can see, our Website is mutable, like lists are, not immutable
+like strings are. We can change the website in-place without creating a
+new Website.
+
 `url`, `founding_year` and `free_to_use` are not variables, they are
 **attributes**. More specifically, they are **instance attributes**.
-The biggest difference is that variables are accessed by their name,
-and attributes are accessed by typing a name of an object (like
-stackoverflow), then a dot and then the name of the attribute.
+The biggest difference is that we need to use a dot for setting and
+getting values of attributes, but we don't need that with variables.
+Modules also use instance attributes for accessing their content. For
+example, when we do `random.randint`, `random` is a module instance and
+`randint` is one of its attributes.
 
 If we make another Website, does it have the same `url`, `founding_year`
 and `free_to_use`?
@@ -336,7 +335,9 @@ available in the info method. We could also access them directly from
 
 But we still need to call `stackoverflow.initialize`. In Python, there's
 a "magic" method that runs when we create a new Website by calling the
-Website class. It's called `__init__` and it does nothing by default.
+Website class. It's called `__init__` and it does nothing by default. If
+our `__init__` method takes other arguments than self we can call the
+class with arguments and they will be given to `__init__`. Like this:
 
 ```py
 >>> class Website:
@@ -378,6 +379,10 @@ class MyProgram:
 program = MyProgram()
 ```
 
+You should avoid using things like `print` and `input` in the `__init__`
+method. The `__init__` method should be simple and it should just set
+things up.
+
 Usually you shouldn't use a class if you're only going to make one
 instance of it, and you don't need a class either if you're only going
 to have one method. In this example `MyProgram` has only one method and
@@ -393,10 +398,7 @@ word = input("Enter something: ")
 print("You entered " + word + ".")
 ```
 
-## Important things
-
-Here are some of the most important things covered in this tutorial.
-Make sure you understand them.
+## Summary
 
 - Object-orientated programming is programming with custom data types.
   In Python that means using classes and instances.

defining-functions.md

@@ -1,7 +1,7 @@
-# Defining your own functions
+# Defining custom functions
 
-It's probably been a while since you read about using functions. [Read
-about it again](using-functions.md) if you need to.
+It's probably been a while since you read about using functions.
+[Read about it again](using-functions.md) if you need to.
 
 ## Why should I use custom functions?
 
@@ -40,7 +40,13 @@ else:
     print_box("You didn't enter Python :(")
 ```
 
-That's nice, but where do we get a `print_box` function like that?
+In this tutorial we'll learn to define a `print_box` function
+that prints text in a box. We can write the code for printing the
+box once, and then use it multiple times anywhere in the program.
+
+Dividing a long program into simple functions also makes the code
+easier to work with. If there's a problem with the code we can
+test the functions one by one and find the problem easily.
 
 ## First functions
 
@@ -167,7 +173,7 @@ However, modifying a global variable in-place from a function is easy.
 
 This doesn't work if the value is of an immutable type, like string or
 integer because immutable values cannot be modified in-place.
-Fortunately, Python will tell you if something's wrong.
+Fortunately, Python will tell us if something's wrong.
 
 ```py
 >>> foo = 1
@@ -220,7 +226,7 @@ This function can be called in two ways:
     When the function was running it had a local `message` variable
     that pointed to `"hi"`. The function printed it twice.
 
-    Positional arguments are great for simple things, but if your
+    Positional arguments are great for simple things, but if our
     function takes many positional arguments it may be hard to tell
     which argument is which.
 
@@ -233,7 +239,12 @@ This function can be called in two ways:
     >>> 
     ```
 
-    Keyword arguments are great when your function needs to take many
+    The name "keyword argument" is a little bit confusing because
+    keyword arguments don't actually have anything to do with keywords
+    (`if`, `else` etc). Keyword arguments are just a way to give names
+    for our arguments.
+
+    Keyword arguments are great when our function needs to take many
     arguments, because each argument has a name and it's easy to see
     which argument is which.
 
@@ -334,8 +345,8 @@ need to:
     ```
 
     The problem is that we have a keyword argument before a positional
-    argument. Python doesn't allow this. You don't need to worry about
-    this, because if you accidentally call a function like this you
+    argument. Python doesn't allow this. We don't need to worry about
+    this, because if we accidentally call a function like this we
     will get an error message.
 
 ## Output
@@ -394,11 +405,11 @@ about the `input()` function. It asks the user to enter something, and
 then the user enters something and that value is returned. If the input
 function would print the value instead of returning it, things like
 `name = input("Name: ")` wouldn't work and assigning the result to a
-variable would be much more difficult. Printing things is fine when you
-know that you'll only need to print the result and you'll never need to
+variable would be much more difficult. Printing things is fine when we
+know that we'll only need to print the result and we'll never need to
 assign it to a variable.
 
-So if our function returns a value we can use it like this:
+If our function returns a value we can always print it, like this:
 
 ```py
 >>> def return_hi():
@@ -409,18 +420,6 @@ hi
 >>> 
 ```
 
-If the function prints instead we can call it and just throw away
-the None it returns:
-
-```py
->>> def print_hi():
-...     print("hi")
-... 
->>> print_hi()
-hi
->>> 
-```
-
 ## Examples
 
 Ask yes/no questions.

editor-setup.md

@@ -1,9 +1,9 @@
 # Setting up an editor for programming
 
 Python comes with its IDLE, and you can use it in this tutorial. If you
-don't like using it for some reason, you need
-[PowerShell, command prompt or terminal](installing-python.md) for
-trying out things. You also need an editor for writing code that will
+don't like using it for some reason, you need [PowerShell, command prompt or
+terminal](installing-python.md#if-you-like-working-with-powershell-command-prompt-or-terminal)
+for trying out things. You also need an editor for writing code that will
 be stored in files.
 
 If you use IDLE as your editor, **it comes with everything set up for
@@ -12,7 +12,7 @@ don't, you probably need to change some settings to make your editor
 suitable for Python use.
 
 Do **not** use word processors like Microsoft Word and LibreOffice
-Write for programming. They create their own files, but you need plain
+Writer for programming. They create their own files, but you need plain
 text files for programming.
 
 Start by creating an empty file called `hello.py` and opening it with

exceptions.md

@@ -400,6 +400,10 @@ get when [processing files](files.md), and catching Exception catches
 all of these errors. You don't need to remember this tree, running
 `help('builtins')` should display a larger tree that this is a part of.
 
+There's also a few exceptions that are not in this tree like SystemExit
+and KeyboardInterrupt, but most of the time you shouldn't catch them.
+Catching Exception doesn't catch them either.
+
 ## Summary
 
 - Exceptions are classes and they can be used just like all other classes.

files.md

@@ -38,7 +38,7 @@ C:
 ```
 
 `C:\Users\me\hello.py` is an **absolute path**. But there are also
-**relative paths**. For example, if you're in `C:\Users`, `me\hello.py`
+**relative paths**. For example, if we are in `C:\Users`, `me\hello.py`
 is same as `C:\Users\me\hello.py`. The place we are in is sometimes
 called **current directory**, **working directory** or
 **current working directory**.
@@ -67,7 +67,7 @@ Let's create a file and write a hello world to it.
 ```
 
 Doesn't seem like it did anything. But actually it created a `hello.txt`
-somewhere on your system. On Windows it's probably in `C:\Users\YourName`,
+somewhere on our system. On Windows it's probably in `C:\Users\YourName`,
 and on most other systems it should be in `/home/yourname`. You can open
 it with notepad or any other plain text editor your system comes with.
 
@@ -88,7 +88,7 @@ the current working directory.
 
 The second argument was `w`... but where the heck does that come from?
 `w` is short for write, and that just means that we'll create a new file.
-There's some other modes you can use also:
+There's some other modes we can use also:
 
 | Mode  | Short for | Meaning                                                               |
 |-------|-----------|-----------------------------------------------------------------------|
@@ -100,7 +100,7 @@ The `w` and `a` modes create a new file if it exists already, but trying
 to read from a non-existent file is an error.
 
 But what is that `with ourfile as f` crap? That's just a fancy way to make
-sure that the file gets closed, no matter what happens. As you can see,
+sure that the file gets closed, no matter what happens. As we can see,
 the file was indeed closed.
 
 ```py
@@ -115,7 +115,7 @@ to the file we opened using `file=f`.
 
 ## Reading from files
 
-After opening a file with the `r` mode you can for loop over it, just
+After opening a file with the `r` mode we can for loop over it, just
 like it was a list. So let's go ahead and read everything in the file
 we created to a list of lines.
 
@@ -130,7 +130,23 @@ we created to a list of lines.
 >>> 
 ```
 
-But why is there a `\n` at the end of our hello world?
+Trying to open a non-existent file with `w` created the file for us, but
+doing that with `r` gives us an error instead. We'll learn more about
+errors later.
+
+```py
+>>> with open('this-doesnt-exist.txt', 'r') as f:
+...     print("It's working!")
+... 
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+FileNotFoundError: [Errno 2] No such file or directory: 'this-doesnt-exist.txt'
+>>> 
+```
+
+So now we have the hello world in the `lines` variable, but it's
+`['Hello World!\n']` instead of `['Hello World!']`. So what the heck did
+that `\n` doing there?
 
 `\n` means newline. Note that it needs to be a backslash, so `/n`
 doesn't have any special meaning like `\n` has. When we wrote the file
@@ -160,9 +176,9 @@ There we go, each of our lines now ends with a `\n`. When we for
 loop over the file it's divided into lines based on where the `\n`
 characters are, not based on how we printed to it.
 
-But how to get rid of that `\n`? The `rstrip`
-[string method](handy-stuff-strings.md#string-methods) is great
-for this:
+But how to get rid of that `\n`? [The rstrip string
+method](https://docs.python.org/3/library/stdtypes.html#str.rstrip) is
+great for this:
 
 ```py
 >>> stripped = []
@@ -174,9 +190,9 @@ for this:
 >>> 
 ```
 
-It's also possible to read lines one by one. Files have a
-`readline()` method that reads the next line, and returns `''`
-if we're at the end of the file.
+It's also possible to read lines one by one. Files have [a readline
+method](https://docs.python.org/3/library/io.html#io.TextIOBase.readline)
+that reads the next line, and returns `''` if we're at the end of the file.
 
 ```py
 >>> with open('hello.txt', 'r') as f:
@@ -189,8 +205,8 @@ if we're at the end of the file.
 'Hello two!\n'
 ```
 
-There's only one confusing thing about reading files. If you try
-to read it twice you'll find out that it only gets read once:
+There's only one confusing thing about reading files. If we try
+to read it twice we'll find out that it only gets read once:
 
 ```py
 >>> first = []
@@ -232,11 +248,12 @@ again and everything works.
 ```
 
 Usually it's best to just read the file once, and use the
-content you have read from it multiple times.
+content we have read from it multiple times.
 
-As you can see, files behave a lot like lists. The `join()`
-string method joins together strings from a list, but we can
-also use it to join together lines of a file:
+As we can see, files behave a lot like lists. [The join string
+method](https://docs.python.org/3/library/stdtypes.html#str.join) joins
+together strings from a list, but we can also use it to join together
+lines of a file:
 
 ```py
 >>> with open('hello.txt', 'r') as f:
@@ -247,8 +264,8 @@ also use it to join together lines of a file:
 >>> 
 ```
 
-But if you need all of the content as a string, you can just
-use the `read()` method.
+But if we need all of the content as a string, we can just use [the read
+method](https://docs.python.org/3/library/io.html#io.TextIOBase.read).
 
 ```py
 >>> with open('hello.txt', 'r') as f:
@@ -259,7 +276,7 @@ use the `read()` method.
 >>> 
 ```
 
-You can also open full paths, like `open('C:\\Users\\me\\myfile.txt', 'r')`.
+We can also open full paths, like `open('C:\\Users\\me\\myfile.txt', 'r')`.
 The reason why we need to use `\\` when we really mean `\` is that
 backslash has a special meaning. There are special characters like
 `\n`, and `\\` means an actual backslash.
@@ -285,8 +302,9 @@ True
 >>> 
 ```
 
-If you don't use Windows and your paths don't contain backslashes
-you don't need to double anything or use `r` in front of paths.
+If our program is not meant to be ran on Windows and the paths
+don't contain backslashes we don't need to double anything or use
+`r` in front of paths.
 
 ```py
 >>> print('/some/name')