Merge branch 'master' of https://github.com/akuli/python-tutorial

Akuli · Akuli · commit d47480d64fd2 · 2017-05-26T14:15:34.000+03:00
diff --git a/README.md b/README.md
@@ -1,19 +1,25 @@
 # Python programming tutorial
 
-This is a Python 3 programming tutorial for beginners. If you have never
-programmed before click [here](basics/what-is-programming.md) to find
-out what programming is like and get started.
+This is a concise Python 3 programming tutorial for people who think
+that reading is boring. I try to show everything with simple code
+examples; there are no long and complicated explanations with fancy
+words. If you have never programmed before click
+[here](basics/what-is-programming.md) to find out what programming is
+like and get started.
 
 This tutorial is aimed at people with no programming experience at all
 or very little programming experience. If you have programmed a lot in
 the past using some other language you may want to read [the official
 tutorial](https://docs.python.org/3/tutorial/) instead.
 
-You can use Python 3.2 or any newer Python with this tutorial. Don't use
-Python 2. If you write a Python 2 program now someone will need to port
-it to Python 3 later, so it's best to just write Python 3 to begin with.
-Python 3 code will work just fine in Python 4, so you don't need to
-worry about that.
+You can use Python 3.3 or any newer Python with this tutorial. **Don't
+use Python 2.** If you write a Python 2 program now someone will need to
+convert it to Python 3 later, so it's best to just write Python 3 to
+begin with. Python 3 code will work just fine in Python 4, so you don't
+need to worry about that. Python 2 also has horrible
+[Unicode](http://www.unicode.org/standard/WhatIsUnicode.html) problems,
+so it's difficult to write Python 2 code that works correctly with
+non-English characters (like π and ♫).
 
 ## List of contents
 
diff --git a/TODO.md b/TODO.md
@@ -35,6 +35,9 @@ This tutorial is not complete. It still needs:
     - "What the heck is this?" section for stuff i haven't talked about
         - regexes
 
+- add a screenshot about geany's running settings to
+  basics/editor-setup.md
+
 ***
 
 If you have trouble with this tutorial please [tell me about
diff --git a/advanced/datatypes.md b/advanced/datatypes.md
@@ -55,7 +55,7 @@ True
 
 We can also convert anything [iterable](../basics/loops.md#summary) to a
 set [by calling the
-class](../basics/classes.md#why-should-I-use-custom-classes-in-my-projects).
+class](../basics/classes.md#what-are-classes).
 
 ```python
 >>> set('hello')
diff --git a/basics/classes.md b/basics/classes.md
@@ -1,13 +1,13 @@
-# Defining and using custom classes in Python
+# Defining and using custom classes
 
 When I was getting started in Python I learned to make classes for
 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.
 
-## Why should I use custom classes in my projects?
+## What are classes?
 
-Python comes with a lot of classes that you are already familiar with.
+Python comes with many classes that we know already.
 
 ```python
 >>> str
@@ -51,11 +51,11 @@ We can also get an instance's class with `type()`:
 >>>
 ```
 
-Let's say you make a program that processes data about websites. With a
-custom class, you're not limited to `str`, `int` and other classes
-Python comes with. Instead you can define a Website class, and make
-Websites and process information about websites directly. Defining your
-own object types like this is called **object-orientated programming**.
+Let's say that we make a program that processes data about websites.
+With a custom class, we're not limited to `str`, `int` and other classes
+Python comes with. Instead we can define a Website class, and make
+Websites and process information about websites directly. Defining our
+own types like this is called **object-orientated programming**.
 
 ## First class
 
@@ -77,6 +77,9 @@ Let's use it to define an empty class.
 >>>
 ```
 
+The `pass` is needed here, just like [when defining functions that do
+nothing](defining-functions.md#first-functions).
+
 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
diff --git a/basics/defining-functions.md b/basics/defining-functions.md
@@ -44,9 +44,9 @@ 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.
+[Dividing a long program into simple functions](larger-program.md) 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
 
@@ -68,9 +68,15 @@ Let's use it to define a function that does nothing.
 >>>
 ```
 
-Seems to be working so far, we have a function. Actually it's just
-a value that is assigned to a variable called `do_nothing`. Let's see
-what happens if we call it.
+Seems to be working so far, we have a function. It's just a value that
+is assigned to a variable called `do_nothing`. You can ignore the
+`0xblablabla` stuff for now.
+
+The `pass` is needed here because without it, Python doesn't know when
+the function ends and it gives us a syntax error. We don't need the
+`pass` when our functions contain something else.
+
+Let's see what happens if we call our function.
 
 ```python
 >>> do_nothing()
@@ -176,15 +182,15 @@ integer because immutable values cannot be modified in-place.
 Fortunately, Python will tell us if something's wrong.
 
 ```python
->>> foo = 1
->>> def bar():
-...     foo += 1
+>>> thing = 1
+>>> def stuff():
+...     thing += 1
 ...
->>> bar()
+>>> stuff()
 Traceback (most recent call last):
   File "<stdin>", line 1, in <module>
-  File "<stdin>", line 2, in bar
-UnboundLocalError: local variable 'foo' referenced before assignment
+  File "<stdin>", line 2, in stuff
+UnboundLocalError: local variable 'thing' referenced before assignment
 >>>
 ```
 
@@ -283,8 +289,8 @@ def print_box(message, character):
     print(character * len(message))
 ```
 
-Then we could change our existing code to always call `print_box` with
-a star as the second argument:
+Then we could change our code to always call `print_box` with a star as
+the second argument:
 
 ```python
 print_box("Hello World", "*")
@@ -355,11 +361,11 @@ need to:
 ## Output
 
 The built-in input function [returns a value](using-functions.md#return-values).
-Can our function return a value also?
+Can our function return a value too?
 
 ```python
->>> def times_two(x):
-...     return x * 2
+>>> def times_two(thing):
+...     return thing * 2
 ...
 >>> times_two(3)
 6
@@ -412,7 +418,7 @@ None
 
 ## Return or print?
 
-There's two ways to output information from functions. They can print
+There are two ways to output information from functions. They can print
 something or they can return something. So, should we print or return?
 
 Most of the time **returning makes functions much easier to use**. Think
@@ -435,6 +441,47 @@ hi
 >>>
 ```
 
+## Common problems
+
+Functions are easy to understand, but you need to pay attention to how
+you're calling them. Note that `some_function` and `some_function()` do
+two completely different things.
+
+```python
+>>> def say_hi():
+...     print("howdy hi")
+...
+>>> say_hi     # just checking what it is, doesn't run anything
+<function say_hi at 0x7f997d2a8510>
+>>> say_hi()   # this runs it
+howdy hi
+>>>
+```
+
+Typing `say_hi` just gives us the value of the `say_hi` variable, which
+is the function we defined. But `say_hi()` **calls** that function, so
+it runs and gives us a return value. The return value is None so the
+`>>>` prompt [doesn't show it](#variables.md#none).
+
+But we know that the print function shows None, so what happens if we
+wrap the whole thing in `print()`?
+
+```python
+>>> print(say_hi)       # prints the function, just like plain say_hi
+<function say_hi at 0x7fd913f58488>
+>>> print(say_hi())     # runs the function and then prints the return value
+howdy hi
+None
+>>>
+```
+
+The `print(say_hi())` thing looks a bit weird at first, but it's easy to
+understand. There's a print insnde `say_hi` and there's also the print
+we just wrote, so two things are printed. Python first ran `say_hi()`,
+and it returned None so Python did `print(None)`. Adding an extra
+`print()` around a function call is actually a common mistake, and I
+have helped many people with this problem.
+
 ## Examples
 
 Ask yes/no questions.
@@ -463,7 +510,7 @@ def ask_until_correct(prompt, correct_options,
     while True:
         answer = input(prompt + ' ')
         if answer in correct_options:
-            return answer   # returning ends the function
+            return answer
         print(error_message)
 
 
@@ -489,6 +536,8 @@ print("Your favorite color is %s!" % choice)
     function does. Returning also ends the function immediately.
 - Return a value instead of printing it if you need to do something with
     it after calling the function.
+- Remember that `thing`, `thing()`, `print(thing)` and `print(thing())`
+    do different things.
 
 ## Exercises
 
diff --git a/basics/getting-started.md b/basics/getting-started.md
@@ -62,8 +62,9 @@ worked just fine. Later we'll learn what `(3, 14)` is.
 
 ## Comments
 
-We can also type a `#` and then whatever we want after that. These bits
-of text are known as **comments**, and we'll find uses for them later.
+**Comments are text that does nothing.** They can be created by typing a
+`#` and then some text after it, and they are useful when our code would
+be hard to understand without them.
 
 ```python
 >>> 1 + 2     # can you guess what the result is?
@@ -74,7 +75,7 @@ of text are known as **comments**, and we'll find uses for them later.
 Again, I put a space after the `#` and multiple spaces before it just to
 make things easier to read.
 
-If we write comment on a line with no code on it, the prompt changes
+If we write a comment on a line with no code on it, the prompt changes
 from `>>>` to `...`. To be honest, I have no idea why it does that and I
 think it would be better if it would just stay as `>>>`. The prompt goes
 back to `>>>` when we press Enter again.
@@ -85,6 +86,56 @@ back to `>>>` when we press Enter again.
 >>>
 ```
 
+## Strings
+
+Strings are small pieces of text that we can use in our programs. We can
+create strings by simply writing some text in quotes.
+
+```python
+>>> 'hello'
+'hello'
+>>> 'this is a test'
+'this is a test'
+>>> 
+```
+
+Strings can also be written with "double quotes" instead of 'single
+quotes'. This is useful when we need to put quotes inside the string.
+
+```python
+>>> "hello there"
+'hello there'
+>>> "it's sunny"
+"it's sunny"
+>>> 
+```
+
+It's also possible to add single quotes and double quotes into the same
+string, but most of the time we don't need to do that so I'm not going
+to talk about it now.
+
+It doesn't matter which quotes you use when the string doesn't need to
+contain any quotes. If you think that one of the quote types looks nicer
+than the other or you find it faster to type, go ahead and use that.
+
+Strings can be joined together easily with `+` or repeated with `*`:
+
+```python
+>>> "hello" + "world"
+'helloworld'
+>>> "hello" * 3
+'hellohellohello'
+>>> 
+```
+
+Note that a `#` inside a string doesn't create a comment.
+
+```python
+>>> "strings can contain # characters"
+'strings can contain # characters'
+>>> 
+```
+
 ## Using Python as a calculator
 
 ```diff
@@ -132,6 +183,15 @@ and `)` also work the same way.
 >>>
 ```
 
+You can also leave out spaces to show what's calculated first. Python
+ignores it, but our code will be easier to read for people.
+
+```python
+>>> 1 + 2*3         # now it looks like 2*3 is calculated first
+7
+>>>
+```
+
 Python also supports many other kinds of calculations, but most of the
 time you don't need them. Actually you don't need even these
 calculations most of the time, but these calculations are probably
@@ -146,7 +206,9 @@ enough when you need to calculate something.
 - We can enter any Python commands to the interactive `>>>` prompt, and
     it will echo back the result.
 - `+`, `-`, `*` and `/` work in Python just like in math.
-- Pieces of text starting with a `#` are comments.
+- Pieces of text starting with a `#` are comments and pieces of text in
+    quotes are strings.
+- You can use single quotes and double quotes however you want.
 
 ***
 
diff --git a/basics/lists-and-tuples.md b/basics/lists-and-tuples.md
@@ -230,10 +230,6 @@ like this:
 
 ![Different lists.](../images/differentlist.png)
 
-If you're using Python 3.2 or older you need to do `a[:]` instead
-of `a.copy()`. `a[:]` is a slice of the whole list, just like
-`a[0:]`.
-
 ## Tuples
 
 Tuples are a lot like lists, but they're immutable so they
diff --git a/basics/loops.md b/basics/loops.md
@@ -300,10 +300,6 @@ Or if we just want to clear a list, we can use the `clear`
 >>>
 ```
 
-If you're using Python 3.2 or older you need to use `stuff[:]` instead
-of `stuff.copy()` and `stuff[:] = []` instead of `stuff.clear()`.
-`stuff[:]` is a slice of the whole list, just like `stuff[0:]`.
-
 ## Summary
 
 - A loop means repeating something multiple times.
diff --git a/basics/modules.md b/basics/modules.md
diff --git a/basics/what-is-programming.md b/basics/what-is-programming.md
diff --git a/getting-help.md b/getting-help.md
diff --git a/linkcheck.py b/linkcheck.py
