Merge pull request #34 from mciwing/christina-feedback-2

[Python Crash Course] Incorporate remaining suggestions from Christina

Author: manuf3006

docs/assets/python/control-structures/infinite-loop.jpg

@@ -27,7 +27,8 @@
 - :fontawesome-brands-python: __Python__
 
     ---
-    ![header](assets/python/python-header.gif)
+
+    [![header](assets/python/python-header.gif)](python/index.md)
     Learn the programming language **:fontawesome-brands-python: Python**. 
     We will cover the basics from types, control structures and functions to 
     packages.

docs/index.md

@@ -55,10 +55,10 @@ print(experiment["sample_weight_in_grams"])
     Manage the cost of raw materials in a dictionary. The dictionary should 
     contain the following key-value pairs:
 
-    - `#!python "Steel"`: `#!python 100`
-    - `#!python "Aluminum"`: `#!python 150`
-    - `#!python "Copper"`: `#!python 200`
-    - `#!python "Plastic"`: `#!python 50`
+    - `#!python "steel"`: `#!python 100`
+    - `#!python "aluminium"`: `#!python 150`
+    - `#!python "copper"`: `#!python 200`
+    - `#!python "plastic"`: `#!python 50`
 
     Create the dictionary and print the price of copper.
 
@@ -122,9 +122,9 @@ print(experiment)
 
     ```py
     production = {
-        "singapore": {"steel": 100, "aluminum": 150},
-        "taipeh": {"steel": 200, "aluminum": 250},
-        "linz": {"steel": 300, "aluminum": 350, "copper": 100},
+        "singapore": {"steel": 100, "aluminium": 150},
+        "taipeh": {"steel": 200, "aluminium": 250},
+        "linz": {"steel": 300, "aluminium": 350, "copper": 100},
     }
     ```
 
@@ -133,7 +133,7 @@ print(experiment)
 
     - Remove `linz` from the dictionary.
     - Add a new location `vienna` with the production of 200 steel 
-    and 250 aluminum.
+    and 250 aluminium.
     - Print the `aluminium` value of `taipeh` (try accessing it step
     by step and use variables for each step).
 
@@ -151,7 +151,7 @@ print(experiment)
 
 We have covered following topics in this section:
 
-- Dictionaries store key-value pairs.
+- Dictionaries store key-value pairs
 - How to get and modify values
 - Adding key-value pairs
 - Removing key-value pairs with `#!python del`

docs/python/containers/dict.md

@@ -9,7 +9,7 @@ manipulation. `Python` provides several built-in container types, each with its
 own characteristics and use cases. In this first section, we cover 
 `#!python list` objects, followed by dictionaries and tuples.
 
-## What Is a `#!python list`?
+## What is a `#!python list`?
 
 A `#!python list` is a collection of items. You can make a `#!python list` 
 including the letters of the alphabet or the digits from `#!python 0` to 
@@ -63,7 +63,7 @@ John
 
 ???+ info
 
-    In Python, index positions **start at 0**, not 1. This is true of most 
+    In Python, index positions **start at 0**, not 1. This is true for most 
     programming languages. If you’re receiving unexpected results, determine 
     whether you are making a simple off-by-one error.
 
@@ -148,11 +148,11 @@ print(numbers)
 [1.0, 2.0, 0.5, 4.0, 3.0, 'one hundred']
 ```
 
-Up until now, our lists contained only one type of elements - strings. However,
-as in the example above, you can store multiple different types of data in a
-`#!python list`. Moreover, you can do nesting (for example, you can store a 
-`#!python list` within a `#!python list` - more on that later). Hence, 
-lists can represent complex data structures.
+Up until now, our lists contained only one type of elements - 
+strings or integers. However, as in the example above, you can store 
+multiple different types of data in a `#!python list`. Moreover, you can do 
+nesting (for example, you can store a `#!python list` within a `#!python list`
+- more on that later). Hence, lists can represent complex data structures.
 Nevertheless, don't mix and match every imaginable data type within a single 
 `#!python list` (just because you can) as it makes the handling of your 
 `#!python list` quite difficult.
@@ -182,7 +182,7 @@ print(pokemon)
 
 To remove an item from a `#!python list`, you can use the `#!python remove()` 
 method. You need to specify the value which you want to remove. However, 
-this it will only remove the first occurrence of the item.
+this will only remove the first occurrence of the item.
 
 ```py hl_lines="2"
 pokemon = ["Charmander", "Squirtle", "Charmeleon", "Charizard", "Squirtle"]
@@ -227,8 +227,8 @@ Bulbasaur
 ## Organizing a `#!python list`
 
 For various reasons, often, your lists will be unordered. If you want to 
-present your `#!python list` in a particular order, you can use the method `#!python 
-sort()`, or the function `#!python sorted()`.
+present your `#!python list` in a particular order, you can use the method 
+`#!python sort()`, or the function `#!python sorted()`.
 
 ### `#!python sort()`
 
@@ -299,7 +299,8 @@ print(players[0:3])
     Define a `#!python list` of your choice with at least `#!python 5` 
     elements. 
 
-    - Now, perform a slice from the second to (including) the fourth element.
+    - Now, perform a slice from the second up to and including the fourth 
+    element.
     - Next, omit the first index in the slice (only omit the number!). What 
     happens?
     - Lastly, re-add the first index and omit the second index of your 

docs/python/containers/list.md

@@ -18,7 +18,9 @@ print(type(coordinates))
 A `#!python tuple` is created with round brackets (`()`). As with lists and dictionaries,
 the elements are separated by commas. Tuples can hold any type of data.
 
-Access the individual elements of a `#!python tuple` using the index.
+## Accessing elements
+
+With indexing, the individual elements of a `#!python tuple` can be retrieved.
 
 ```py
 coordinates = (47.262996862335854, 11.393082185178823)
@@ -31,6 +33,8 @@ print(coordinates[1])
 11.39308218517882
 ```
 
+## Immutability
+
 Let's try to change the value of an element in a `#!python tuple`.
 
 ```py
@@ -57,6 +61,8 @@ coordinates = (47.262996862335854, 11.393082185178823)
 coordinates = (5.513615392318705, 95.2060492604128)
 ```
 
+## `#!python tuple` unpacking
+
 Tuples can be unpacked, to use them separately.
 
 ```py
@@ -85,7 +91,7 @@ latitude, longitude = coordinates
 
 In this rather short section, we introduced tuples and covered:
 
-- mutable vs. immutable
-- how to define a `#!python tuple`
-- accessing elements
-- and `#!python tuple` unpacking.
+- Mutability vs. immutability
+- How to define a `#!python tuple`
+- Access elements with indexing
+- ... and `#!python tuple` unpacking

docs/python/containers/tuple.md

@@ -213,7 +213,7 @@ Sum: 22.23
 
 ???+ question "Calculate the average"
 
-    Calculate the average of following list:
+    Calculate the average of the following list:
     ```py
     numbers = [4.52, 3.14, 2.71, 1.0, 8.38]
     ```
@@ -242,8 +242,8 @@ a single line.
 
 ## Looping over dictionaries
 
-As previously discussed, you can not only loop over a `#!python list` but 
-using a variety of different data types such as dictionaries.
+As previously discussed, you can not only loop over a `#!python list`, but 
+also iterate over a variety of different data types, such as dictionaries.
 You can loop over a dictionary’s key-value pairs, solely over the keys 
 or just the values.
 

docs/python/control-structures/for.md

@@ -20,8 +20,9 @@ if condition is True:
 
 You can put any condition in the first line and just about any action in the 
 indented block following the test. If the condition evaluates to `True`,
-`Python` executes the code following the `#!python if` statement. 
-If the test evaluates to `False`, the code following the `#!python if` is ignored.
+`Python` executes the indented code following the `#!python if` statement. 
+If the test evaluates to `False`, the indented code block (following the 
+`#!python if`) is ignored.
 
 ```py
 user = "admin"
@@ -88,7 +89,7 @@ Indentation plays the same role in `#!python if` statements as it did in
     Now, loop over the passwords and check if each password exceeds the 
     character limit of 12. If so, print the password.
 
-## `#!python else`
+### `#!python else`
 
 Previously, every time the condition in the `#!python if` statement 
 evaluated to `#!python False`, 
@@ -117,7 +118,7 @@ Only admins can enter this area!
 
     *Hint*: Introduce an `else` statement to save the invalid passwords.
 
-## `#!python elif`
+### `#!python elif`
 
 Often, you’ll need to test more than two possible situations, and to evaluate
 these, you can use an `if-elif-else` syntax. `Python` executes only one
@@ -169,7 +170,7 @@ current_number = 1
 while current_number <= 5:
   print(current_number)
   # increment the counter value by one
-  current_number = current_number + 1
+  current_number += 1
 ```
 
 ```title=">>> Output"
@@ -181,7 +182,42 @@ while current_number <= 5:
 ```
 
 Note, that the variable, that is checked in the `#!python while`-condition 
-must be defined prior to the loop, otherwise we will encounter a `#!python NameError`.
+must be defined prior to the loop, otherwise we will encounter a 
+`#!python NameError`.
+
+<div style="text-align: center;">
+    <img src="../../../assets/python/control-structures/infinite-loop.jpg" 
+      alt="Infinite loops" width="400px" style="border-radius:10px;"
+    >
+    <figcaption>Infinite loops</figcaption>
+</div>
+
+Moreover, the variable must be updated within the loop
+to avoid an infinite loop. For example, if `#!python current_number` is not
+incremented by one, the condition `#!python current_number <= 5` will always
+evaluate to `#!python True`, leaving us stuck in an infinite loop.
+In such cases, simply click the `Stop` button (on the left-hand side of the 
+respective code cell) to interrupt the execution.
+
+???+ info "Addition assignment"
+
+    In the above example, we used the `#!python +=` operator, referred to as 
+    addition assignment. It is a shorthand for incrementing a variable by a 
+    certain value.
+
+    ```py hl_lines="2"
+    a = 10
+    a += 5
+    print(a)
+    ```
+
+    ```title=">>> Output"
+    15
+    ```
+    
+    The above code is equivalent to `#!python a = a + 5`.
+    This shorthand assignment can be used with all arithmetic
+    operators, such as subtraction `#!python -=` or division `#!python /=`.
 
 
 ???+ question "While loop"
@@ -202,12 +238,26 @@ below.
 user_name = input("Please enter your username:")
 ```
 
+However, the `#!python input()` function always returns a string.
+
+```py
+age = input("Please enter your age:")
+print(type(age))
+```
+
+```title=">>> Output"
+<class 'str'>
+```
+
+... use [casting](../types/bool_and_none.md#casting) to 
+convert the input to the desired type.
+
 
 ## `#!python break`
 
-To exit any loop immediately without running any remaining code, use the 
-`#!python break` statement. The `#!python break` statement directs the flow of 
-your program; you can use it to control which lines of code are executed and 
+To exit any loop immediately without running any remaining 'loop code', use 
+the `#!python break` statement. The `#!python break` statement directs the flow
+of your program; you can use it to control which lines of code are executed and 
 which aren’t, so the program only executes code that you want it to, when you
 want it to.
 
@@ -216,12 +266,15 @@ for i in range(5):
     if i == 3:
         break
     print(i)
+
+print("Continue running the program...")
 ````
 
 ```title=">>> Output"
 0
 1
 2
+Continue running the program...
 ```
 
 ## `#!python continue`

docs/python/control-structures/if.md

@@ -100,6 +100,15 @@ Hello, admin!
 
     As you can see in the example above, a docstring can span multiple lines!
 
+Up until now, the functions had no parameters at all or just a single 
+parameter. However, you can define as many parameters as you like, seperated 
+by a comma (`#!python ,`):
+
+```py
+def greet(first_name, last_name):
+    print(f"Hello, {first_name} {last_name}!")
+```
+
 ???+ question "Break-even point"
 
     Remember the task to calculate the break-even point? Now, you'll wrap 
@@ -315,10 +324,10 @@ result = square_number(5)
 This section introduced the concept of functions to better structure your 
 code, make it more readable and reusable. We have covered:
 
-- The definition of functions
-- Docstrings
-- Parameters and arguments
+- How to define a function
+- Docstrings as a tool to document your functions
+- Parameters vs arguments
 - Positional and keyword arguments
-- Default values
-- `#!python return` statement
-- Structuring code with functions
+- Defining default values for parameters
+- The `#!python return` statement
+- How to use functions to solve smaller subtasks and structure your code

docs/python/functions.md

@@ -12,7 +12,7 @@ solve common problems. Therefore, you won't have to reinvent the wheel.
 For example the package `pandas` is the go-to tool for data manipulation and
 analysis. With `pandas` you can read text and Excel files 
 :fontawesome-regular-file-excel: among a lot of other
-formats and offers a lot of functionality to manipulate and even plot your
+formats and it offers a lot of functionality to manipulate and even plot your
 data. Hence, you will rarely see `Python` projects that are not dependent on
 `pandas`. Apart from `pandas` there are a wide variety of popular packages:
 
@@ -36,7 +36,7 @@ on the topic. [Here](https://docs.python.org/3/py-modindex.html) is
 an extensive list of all the packages that `Python` ships with.
 
 Let's use the `#!python random` package to generate some random numbers. 
-First, we have to import the package with following command:
+First, we have to import the package with the following command:
 
 ```py hl_lines="1"
 import random
@@ -386,7 +386,7 @@ In this section, you have learned how to install packages and manage them
 within virtual environments. The topics covered:
 
 * `pip`
-* install/uninstall packages
-* PyPI
-* concept and benefits of virtual environments
-* creation and basic usage of a virtual environment
+* How to install/uninstall packages
+* PyPI - the package hub
+* Concept and benefits of virtual environments
+* Creation and basic usage of a virtual environment