Add section on variables.

UPstartDeveloper · UPstartDeveloper · commit 5a5cff370aa0 · 2021-07-04T16:36:41.000-04:00
diff --git a/welcome/Hello_Python.md b/welcome/Hello_Python.md
@@ -2,201 +2,252 @@
 
 Hello reader, 
 
-This document will jumpstart your understanding of Python. It will cover all the foundational aspects of the programming language, and provide examples of how to use each of them in practice. Whenever you get stuck on the exercises in this book, feel free to come back to this section as well - after all, even the most experienced programmers have to review the basics sometimes!
+This document will jumpstart your understanding of Python. We will cover all the foundational aspects of the programming language, and provide you with examples of how to use each of them in practice. Whenever you get stuck on the exercises in this book, feel free to come back to this section as well - after all, even the most experienced programmers have to review the basics sometimes!
 
 ## Table of Contents
-**[TODO]** put in links
 
 1. [Data Types](#data-types)
-2. [Control Flow]()
-3. [Functions]()
-4. [Container Types]()
-5. [Credits](#credits) 
+2. [Variables](#variables)
+3. [Control Flow](#control-flow)
+4. [Functions](#functions)
+5. [Container Types](#container-types)
+6. [Credits](#credits) 
 
 ## Data Types
+Programming languages give us an easy way to manipulate data in the computer - but first, the computer has to understand what kind of data we're dealing with!
 
-### Math Operators
+Here are some examples of the kinds of data you can work with in the Python programming language:
 
-From **Highest** to **Lowest** precedence:
+#### Table 1: Data Types in Python
 
-| Operators | Operation        | Example         |
+| Data Type              | Examples                                  |
+| ---------------------- | ----------------------------------------- |
+| Integers               | `-3, -2, -1, 0, 1, 2, 3`                |
+| Floating-point numbers | `-1.25, -1.0, --0.5, 0.0, 0.5, 1.0, 1.25` |
+| Strings                | `'a', 'Hello World!', "C-3PO", "bbb"`   |
+| Boolean               | `True, False`
+
+Integers and floating-point numbers are also called *numeric types*. We shall cover these more in depth now.
+
+### Numeric Types
+Numbers are everywhere! In Python, we have 3 kinds of data types to represent numerical data:
+
+- `int` - whole numbers 
+- `float` - floating-point (aka fractional) numbers
+
+Between the `int` and `float` types, Python 3 lets you store any kind of real number in a variable. 
+
+**Note**: there is also a `complex` data type in Python - you may read about it in the [documentation](https://docs.python.org/3/library/functions.html?#complex).
+
+The numeric types are useful for when you are doing mathematical operations - which we will discuss next!
+
+#### Math Operations
+
+Python supports a lot of these! Table 2 describes which operator you can use for each of them, along with examples.
+##### Table 2: Mathematical Operators (for Each Operation)
+
+| Operator | Operation        | Example         |
 | --------- | ---------------- | --------------- |
-| **        | Exponent         | `2 ** 3 = 8`    |
-| %         | Modulus/Remainder | `22 % 8 = 6`    |
-| //        | Integer division | `22 // 8 = 2`   |
-| /         | Division         | `22 / 8 = 2.75` |
-| *         | Multiplication   | `3 * 3 = 9`     |
-| -         | Subtraction      | `5 - 2 = 3`     |
-| +         | Addition         | `2 + 2 = 4`     |
+| **        | Exponent        | `3 ** 3 = 27`    |
+| %         | Modulus/Remainder Division - *returns only the remainder* | `30 % 8 = 6`    |
+| //        | Integer division - *truncates any floating-point values in the quotient* | `30 // 8 = 3`   |
+| /         | Division - *always returns a `float`*         | `30 / 8 = 3.75` |
+| *         | Multiplication   | `2 * 3 = 6`     |
+| -         | Subtraction      | `7 - 2 = 5`     |
+| +         | Addition         | `9 + 2 = 11`     |
 
-Examples of expressions in the interactive shell:
+**Note**: all the operators above will return:
+- a `float`, if the two operands are 1) both floating-point OR 2) they have different types
+- an `int`, if 1) both operands are integers AND 2) it is not the division (`/`) operator
 
-```python
-2 + 3 * 6
+#### Order of Operations
+Python prioritzes some operations over others. This means that it follows a *precedence order* that decides which operation to compute first, when there are several of them together in a given expression.
+
+The operators in Table 2 are listed from **highest** to **lowest** precedence, for your reference.
+
+Here are some examples of how the order of operations can impact the result computed by Python code - feel free to run these in a Python shell to check the results (given in the inline comments).
+
+```python 
+5 + 3 * 6  # result: 23
 ```
 
 ```python
-(2 + 3) * 6
+(5 + 3) * 6  # result: 48
 ```
 
 ```python
-2 ** 8
+2 ** 8  # result: 256
 ```
 
 ```python
-23 // 7
+23 // 7  # result: 3
 ```
 
 ```python
-23 % 7
+23 % 7  # result: 2
 ```
 
 ```python
-(5 - 1) * ((7 + 1) / (3 - 1))
+ ((7 + 5) / (4 - 1)) * (5 + 1)  # result: 24.0
 ```
 
-### Data Types
+The next data type we will cover are strings, which are also known as a *text sequence type*.
 
-| Data Type              | Examples                                  |
-| ---------------------- | ----------------------------------------- |
-| Integers               | `-2, -1, 0, 1, 2, 3, 4, 5`                |
-| Floating-point numbers | `-1.25, -1.0, --0.5, 0.0, 0.5, 1.0, 1.25` |
-| Strings                | `'a', 'aa', 'aaa', 'Hello!', '11 cats'`   |
+### Strings
+Strings in Python are used to represent any sequence of characters. Basically, anything that can be typed on a computer between a pair of quotes is a string!
+#### Common String Operations
 
-### String Concatenation and Replication
+1. **String concatenation**:
 
-String concatenation:
+    *Concatenation* is when one string is added onto the end of another string. A quick and easy way to do this is by using the addition (`+`) operator, just like we did for numbers!
 
-```python
-'Alice' 'Bob'
-```
+    For example, let's say we wanted a string that said `'Alice met Allison on Tuesday'` - then the code could look like the following:
 
-Note: Avoid `+` operator for string concatenation. Prefer string formatting.
+    ```python
+    'Alice met ' + 'Allison on Tuesday'
+    ```
+    **Note**: although using addition works, it is far from perfect. In practice we prefer 1) *string formatting*, which will be discussed later in this book, or 2) the `str.join()` function, which you may read about in the [Python documentation](https://docs.python.org/3/library/stdtypes.html?#str.join).
 
-String Replication:
+2. **String Replication**:
 
-```python
-'Alice' * 5
-```
+    *Replication* is when we repeat a given string over and over again in a new, longer `str` object. 
+    
+    Incidently, Python makes this easier for us through the `*` operator. Now, can you guess what the output of the following code will be?
 
-### Variables
+    ```python
+    'Alice' * 5
+    ```
 
-You can name a variable anything as long as it obeys the following rules:
+3. **Displaying Messages using `print()`**
+    You will most often see strings where a program needs to tell the user some kind of message - this is exactly what the `print()` function will do:
 
-1. It can be only one word.
-2. It can use only letters, numbers, and the underscore (`_`) character.
-3. It can’t begin with a number.
-4. Variable name starting with an underscore (`_`) are considered as "unuseful`.
+    ```python
+    print('Hello world!')
+    ```
 
-Example:
+4.  **Gathering User Responses using `input()`**
 
-```python
-spam = 'Hello'
-```
+    Another common task is for a computer program to ask the user for their information - this can be done in Python via the `input()` function. 
 
-```python
-_spam = 'Hello'
-```
+    In the example below the user will first be prompted to enter their name, because that is what has been passed to the `input()` function. 
 
-`_spam` should not be used again in the code.
+    ```python
+    name = input('What is your name?') # ask for their name
+    ```
+    The user's response is then stored in the variable called `name`. 
 
-### Comments
+5. **Measuring Length using `len()`**
 
-Inline comment:
+    We can also calculate valuates thenumber of characters in a string:
 
-```python
-# This is a comment
-```
+    ```python
+    len('hello')  # result: 5
+    ```
+    Note that the `len()` function is also applicable to all of Python's "container" data types, which are used to store multiple pieces of data at the same time (like lists, sets, and dictionaries) - all of these will be covered below!
 
-Multiline comment:
+**Common Mistakes**:
 
-```Python
-# This is a
-# multiline comment
-```
+Strings have such a wide definition, that it is easy to make mistakes when working with them. Here are some things to watch out for:
+1. Not enclosing them in single quotes (e.g. `'Hello'`) or double quotes (e.g. `"World"`)
+2. Although Python treats single and double quotes the same, you *cannot* combine the two (e.g. do NOT do `"Hello, World!'`)
+#### Quotes in Strings
+
+This doesn't mean that you are not allowed to mix double quotes and single quotes. As long as you enclose each pair of quotes, they can in fact be very useful to use together - such as when a string includes a quote!
 
-Code with a comment:
+For example, the following is how you should NOT include quotes in a string together:
 
 ```python
-a = 1  # initialization
+print("I said "hello."")  # ERROR!
 ```
+In the above code snippet, the `'hello'` ends up not being enclosed by any pair of quotes. 
 
-Please note the two spaces in front of the comment.
-
-Function docstring:
-
+So how to remedy this? One option is to enclose the whole string in a pair of *single quotes*, so we can let the *double quotes* in the sentence enclose the `'hello'` properly:
 ```python
-def foo():
-    """
-    This is a function docstring
-    You can also use:
-    ''' Function Docstring '''
-    """
+print('I said "hello."')  # all good :)
 ```
 
-### The print Function
+Next, let's take a look at the Boolean data type!
+### Boolean Types
+The Boolean data type, represented as `bool` in Python, needs no overthinking - it simply represents whether `True` or `False`. 
 
-```python
-print('Hello world!')
-```
+As you might imagine, they are especially useful for writing code that answers yes/no questions - we will discuss this more in-depth when we talk about [Control Flow](#control-flow).
 
-```python
-a = 1
-print('Hello world!', a)
-```
+### The str, int, and float Functions
+Python's data types are not necessarily set in stone. In some scenarios (shown below) we can convert, or *cast*, a given value in one data type to another, by calling the desired data type like a function! More technically, this is also called *explicit type conversion*.
 
-### The input Function
+Here are examples of when we can interchange values between the `int`, `float`, and `str` types:
 
-Example Code:
+1. Integer to String or Float:
 
-```python
-myName = input('What is your name?') # ask for their name
-print('It is good to meet you, {}'.format(myName))
-```
+    ```python
+    str(29)
+    ```
 
-### The len Function
+    ```python
+    print('I am {} years old.'.format(str(29)))
+    ```
 
-Evaluates to the integer value of the number of characters in a string:
+    ```python
+    str(-3.14)
+    ```
 
-```python
-len('hello')
-```
+2. Float to Integer:
 
-Note: test of emptiness of strings, lists, dictionary, etc, should **not** use len, but prefer direct
-boolean evaluation.
+    ```python
+    int(7.7)
+    ```
+
+    ```python
+    int(7.7) + 1
+    ```
+Additionally, if you are ever unsure about what the data type of a given value currently is, you can check using the built-in `type()` function:
 
 ```python
-a = [1, 2, 3]
-if a:
-    print("the list is not empty!")
+type(555)  # result: <class: 'int'>
 ```
 
-### The str, int, and float Functions
+## Variables
+The data in our program can change not only in its **type**. In addition, it is even more common for our data to change in its **value**. A *variable* in programming is how we represent some piece of data whose value can be many different things. 
 
-Integer to String or Float:
+Now, from math class you might be used to variable names like `x`, `y`, `z`, etc. - but in programming, it is actually preferable to use much more descriptive names!
 
-```python
-str(29)
-```
+You can name a variable anything as long as it obeys the following rules:
+
+1. It can be only one word.
+2. It can use only letters, numbers, and the underscore (`_`) character.
+3. It can’t begin with a number.
+4. Variable name starting with an underscore (`_`) are considered as "unuseful`.
+
+Example 1:
 
 ```python
-print('I am {} years old.'.format(str(29)))
+spam = 'Hello'
 ```
+Example 2:
 
 ```python
-str(-3.14)
+_spam = 'Hello'
 ```
 
-Float to Integer:
+Because of how `_spam` is named, we know it is not a variable we should use again in the code.
 
-```python
-int(7.7)
-```
+## Control Flow
+
+## Functions
+
+Function docstring:
 
 ```python
-int(7.7) + 1
+def foo():
+    """
+    This is a function docstring
+    You can also use:
+    ''' Function Docstring '''
+    """
 ```
 
+## Container Types
+
 ## Credits
 
 This section would not be possible if not for the following sources:
