Merge pull request #62 from d-s-1/master

Proposed Revisions to Help Beginning Programmers

data_structures.md

@@ -50,7 +50,7 @@ Tuples are used to hold together multiple objects. Think of them as similar to l
 
 Tuples are defined by specifying items separated by commas within an optional pair of parentheses.
 
-Tuples are usually used in cases where a statement or a user-defined function can safely assume that the collection of values i.e. the tuple of values used will not change.
+Tuples are usually used in cases where a statement or a user-defined function can safely assume that the collection of values (i.e. the tuple of values used) will not change.
 
 Example (save as `ds_using_tuple.py`):
 
@@ -187,7 +187,7 @@ True
 
 **How It Works**
 
-The example is pretty much self-explanatory because it involves basic set theory mathematics taught in school.
+If you remember basic set theory mathematics from school, then this example is fairly self-explanatory.  But if not, you can google "set theory" and "Venn diagram" to better understand our use of sets in Python.
 
 ## References
 
@@ -215,9 +215,9 @@ Remember that if you want to make a copy of a list or such kinds of sequences or
 
 ## More About Strings {#more-strings}
 
-We have already discussed strings in detail earlier. What more can there be to know?  Well, did you know that strings are also objects and have methods which do everything from checking part of a string to stripping spaces!
+We have already discussed strings in detail earlier. What more can there be to know?  Well, did you know that strings are also objects and have methods which do everything from checking part of a string to stripping spaces?  In fact, you've already been using a string method... the `format` method!
 
-The strings that you use in program are all objects of the class `str`.  Some useful methods of this class are demonstrated in the next example. For a complete list of such methods, see `help(str)`.
+The strings that you use in programs are all objects of the class `str`.  Some useful methods of this class are demonstrated in the next example. For a complete list of such methods, see `help(str)`.
 
 Example (save as `ds_str_methods.py`):
 

exceptions.md

@@ -21,7 +21,7 @@ Observe that a `NameError` is raised and also the location where the error was d
 
 ## Exceptions
 
-We will **try** to read input from the user. Press `[ctrl-d]`, (or `[ctrl-z]` if you are using Windows), and see what happens.
+We will **try** to read input from the user.  Enter the first line below and hit the `Enter` key.  When your computer prompts you for input, instead press `[ctrl-d]` on a Mac or `[ctrl-z]` with Windows and see what happens.  (If you're using Windows and neither option works, you can try `[ctrl-c]` in the Command Prompt to generate a KeyboardInterrupt error instead).
 
 ```python
 >>> s = input('Enter something --> ')
@@ -94,7 +94,9 @@ We do the usual file-reading stuff, but we have arbitrarily introduced sleeping
 
 Observe that the `KeyboardInterrupt` exception is thrown and the program quits. However, before the program exits, the finally clause is executed and the file object is always closed.
 
-Note that we use `sys.stdout.flush()` after `print` so that it prints to the screen immediately.
+Notice that a variable assigned a value of 0 or `None` or a variable which is an empty sequence or collection is considered `False` by Python.  This is why we can use `if: f` in the code above.
+
+Also note that we use `sys.stdout.flush()` after `print` so that it prints to the screen immediately.
 
 ## The with statement {#with}
 

installation.md

@@ -11,13 +11,13 @@ Note that if your Windows version is pre-Vista, you should [download Python 3.4
 
 CAUTION: Make sure you check option `Add Python 3.5 to PATH`.
 
-To change install location, click on `Customize installation`, then `Next` and enter `C:\python35` as install location.
+To change install location, click on `Customize installation`, then `Next` and enter `C:\python35` (or another appropriate location) as the install location.
 
-If not checked, check `Add Python to environment variables`. This does the same thing as `Add Python 3.5 to PATH` on the first install screen.
+If you didn’t check the `Add Python 3.5 PATH` option earlier, check `Add Python to environment variables`. This does the same thing as `Add Python 3.5 to PATH` on the first install screen.
 
 You can choose to install Launcher for all users or not, it does not matter much. Launcher is used to switch between different versions of Python installed.
 
-If your path was not set correctly, then follow these steps to fix it. Otherwise, go to `Running Python prompt on Windows`.
+If your path was not set correctly (by checking the `Add Python 3.5 Path` or `Add Python to environment variables` options), then follow the steps in the next section (`DOS Prompt`) to fix it. Otherwise, go to the `Running Python prompt on Windows` section in this document.
 
 NOTE: For people who already know programming, if you are familiar with Docker, check out [Python in Docker](https://hub.docker.com/_/python/) and [Docker on Windows](https://docs.docker.com/windows/).
 
@@ -47,6 +47,11 @@ For Windows 7 and 8:
 - If the value was `%SystemRoot%\system32;` It will now become `%SystemRoot%\system32;C:\Python36` <!-- The directory should match pythonVersion variable in book.json -->
 - Click `OK` and you are done. No restart is required, however you may have to close and reopen the command line.
 
+For Windows 10:
+
+Windows Start Menu > `Settings` > `About` > `System Info` (this is all the way over to the right) > `Advanced System Settings` > `Environment Variables` (this is towards the bottom) > (then highlight `Path` variable and click `Edit`) > `New` > (type in whatever your python location is.  For example, `C:\Python35\`)
+
+
 ### Running Python prompt on Windows
 
 For Windows users, you can run the interpreter in the command line if you have [set the `PATH` variable appropriately](#dos-prompt).

programs/backup_ver1.py

@@ -4,11 +4,12 @@ import time
 # 1. The files and directories to be backed up are
 # specified in a list.
 # Example on Windows:
-# source = ['"C:\\My Documents"', 'C:\\Code']
+# source = ['"C:\\My Documents"']
 # Example on Mac OS X and Linux:
 source = ['/Users/swa/notes']
-# Notice we had to use double quotes inside the string
-# for names with spaces in it.
+# Notice we have to use double quotes inside a string
+# for names with spaces in it.  We could have also used
+# a raw string by writing [r'C:\My Documents'].
 
 # 2. The backup must be stored in a
 # main backup directory

programs/ds_using_tuple.py

@@ -5,7 +5,7 @@
 zoo = ('python', 'elephant', 'penguin')
 print('Number of animals in the zoo is', len(zoo))
 
-new_zoo = 'monkey', 'camel', zoo
+new_zoo = 'monkey', 'camel', zoo    # parentheses not required but are a good idea
 print('Number of cages in the new zoo is', len(new_zoo))
 print('All animals in new zoo are', new_zoo)
 print('Animals brought from old zoo are', new_zoo[2])

programs/module_using_sys.txt

@@ -1,4 +1,4 @@
-$ python module_using_sys.py we are arguments
+$ python module_using_sys.py we are arguments	# each arg is separated by white space
 The command line arguments are:
 module_using_sys.py
 we

programs/more_decorator.py

@@ -7,7 +7,7 @@ log = logging.getLogger("retry")
 
 def retry(f):
     @wraps(f)
-    def wrapped_f(*args, **kwargs):
+    def wrapper_function(*args, **kwargs):
         MAX_ATTEMPTS = 5
         for attempt in range(1, MAX_ATTEMPTS + 1):
             try:
@@ -21,7 +21,7 @@ def retry(f):
         log.critical("All %s attempts failed : %s",
                      MAX_ATTEMPTS,
                      (args, kwargs))
-    return wrapped_f
+    return wrapper_function
 
 
 counter = 0

programs/more_decorator.txt

@@ -3,7 +3,7 @@ Write to a database or make a network call or etc.
 This will be automatically retried if exception is thrown.
 ERROR:retry:Attempt 1/5 failed : (('Some bad value',), {})
 Traceback (most recent call last):
-  File "more_decorator.py", line 14, in wrapped_f
+  File "more_decorator.py", line 14, in wrapper_function
     return f(*args, **kwargs)
   File "more_decorator.py", line 39, in save_to_database
     raise ValueError(arg)

programs/oop_init.py

@@ -8,4 +8,4 @@ class Person:
 p = Person('Swaroop')
 p.say_hi()
 # The previous 2 lines can also be written as
-# Person('Swaroop').say_hi()
+# Person().say_hi()

stdlib.md

@@ -39,7 +39,7 @@ Output:
 
 <pre><code>{% include "./programs/stdlib_logging.txt" %}</code></pre>
 
-If you do not have the `cat` command, then you can just open the `test.log` file in a text editor.
+The `cat` command is used in the command line to read the 'test.log' file.  If the `cat` command is not available, you can open the `test.log` file in a text editor instead.
 
 **How It Works**
 
@@ -47,7 +47,7 @@ We use three modules from the standard library - the `os` module for interacting
 
 First, we check which operating system we are using by checking the string returned by `platform.platform()` (for more information, see `import platform; help(platform)`). If it is Windows, we figure out the home drive, the home folder and the filename where we want to store the information. Putting these three parts together, we get the full location of the file. For other platforms, we need to know just the home folder of the user and we get the full location of the file.
 
-We use the `os.path.join()` function to put these three parts of the location together. The reason to use a special function rather than just adding the strings together is because this function will ensure the full location matches the format expected by the operating system.
+We use the `os.path.join()` function to put these three parts of the location together. The reason to use a special function rather than just adding the strings together is because this function will ensure the full location matches the format expected by the operating system.  Note: the `join()' method we use here that's part of the `os` module is different from the string method `join()` that we've used elsewhere in this book.
 
 We configure the `logging` module to write all the messages in a particular format to the file we have specified.