Python tutorial revisions (ronreiter#697)

* Revision of Python - Modules and Packages

* Revision of Python - Modules and Packages

* Revision of Python - Modules and Packages

Co-authored-by: Aaron Redshaw <[email protected]>

Author: aredshaw

Diff for: tutorials/learnpython.org/en/Modules and Packages.md

@@ -2,25 +2,25 @@ Tutorial
 --------
 
 In programming, a module is a piece of software that has a specific functionality. 
-For example, when building a ping pong game, one module would be responsible for the game logic, and  
-another module would be responsible for drawing the game on the screen. Each module is a different
-file, which can be edited separately.
+For example, when building a ping pong game, one module may be responsible for the game logic, and  
+another module draws the game on the screen. Each module consists of a different
+file, which may be edited separately.
 
 ### Writing modules
 
-Modules in Python are simply Python files with a .py extension. The name of the module will be the name of the file.
-A Python module can have a set of functions, classes or variables defined and implemented. 
-In the example above, we will have two files, we will have:
+Modules in Python are just Python files with a .py extension. The name of the module is the same as the file name.
+A Python module can have a set of functions, classes, or variables defined and implemented. 
+The example above includes two files:
 
-- mygame/
+mygame/
 
 - mygame/game.py
 
 - mygame/draw.py
 
 
-The Python script `game.py` will implement the game. It will use the function `draw_game` from the file `draw.py`,
-or in other words, the`draw` module, that implements the logic for drawing the game on the screen.
+The Python script `game.py` implements the game. It uses the function `draw_game` from the file `draw.py`,
+or in other words, the `draw` module that implements the logic for drawing the game on the screen.
 
 Modules are imported from other modules using the `import` command. In this example, the `game.py` script may
 look something like this:
@@ -52,23 +52,20 @@ The `draw` module may look something like this:
         ...
 
 In this example, the `game` module imports the `draw` module, which enables it to use functions implemented
-in that module. The `main` function would use the local function `play_game` to run the game, and then 
-draw the result of the game using a function implemented in the `draw` module called `draw_game`. To use
-the function `draw_game` from the `draw` module, we would need to specify in which module the function is
+in that module. The `main` function uses the local function `play_game` to run the game, and then 
+draws the result of the game using a function implemented in the `draw` module called `draw_game`. To use
+the function `draw_game` from the `draw` module, we need to specify in which module the function is
 implemented, using the dot operator. To reference the `draw_game` function from the `game` module,
-we would need to import the `draw` module and only then call `draw.draw_game()`. 
+we need to import the `draw` module and then call `draw.draw_game()`. 
 
-When the `import draw` directive will run, the Python interpreter will look for a file in the directory which
-the script was executed from, by the name of the module with a `.py` suffix, so in our case it will try to
-look for `draw.py`. If it will find one, it will import it. If not, he will continue to look for built-in modules.
+When the `import draw` directive runs, the Python interpreter looks for a file in the directory in which the script was executed with the module name and a `.py` suffix. In this case it will look for `draw.py`. If it is found, it will be imported. If it's not found, it will continue looking for built-in modules.
 
-You may have noticed that when importing a module, a `.pyc` file appears, which is a compiled Python file. 
-Python compiles files into Python bytecode so that it won't have to parse the files each time modules are loaded.
-If a `.pyc` file exists, it gets loaded instead of the `.py` file, but this process is transparent to the user.
+You may have noticed that when importing a module, a `.pyc` file is created. This is a compiled Python file. 
+Python compiles files into Python bytecode so that it won't have to parse the files each time modules are loaded. If a `.pyc` file exists, it gets loaded instead of the `.py` file. This process is transparent to the user.
 
 ### Importing module objects to the current namespace
 
-We may also import the function `draw_game` directly into the main script's namespace, by using the `from` command.
+A namespace is a system where every object is named and can be accessed in Python. We import the function `draw_game` into the main script's namespace by using the `from` command.
 
     # game.py
     # import the draw module
@@ -79,17 +76,14 @@ We may also import the function `draw_game` directly into the main script's name
         draw_game(result)
 
 
-You may have noticed that in this example, `draw_game` does not precede with the name of the module it is imported 
-from, because we've specified the module name in the `import` command.
+You may have noticed that in this example, the name of the module does not precede `draw_game`, because we've specified the module name using the `import` command.
 
-The advantages of using this notation is that it is easier to use the functions inside the current module because
-you don't need to specify which module the function comes from. However, any namespace cannot have two objects
-with the exact same name, so the `import` command may replace an existing object in the namespace.
+The advantages of this notation is that you don't have to reference the module over and over. However, a namespace cannot have two objects with the same name, so the `import` command may replace an existing object in the namespace.
 
 
 ### Importing all objects from a module
 
-We may also use the `import *` command to import all objects from a specific module, like this:
+You can use the `import *` command to import all the objects in a module like this:
 
     # game.py
     # import the draw module
@@ -99,16 +93,16 @@ We may also use the `import *` command to import all objects from a specific mod
         result = play_game()
         draw_game(result)
 
-This might be a bit risky as changes in the module might affect the module which imports it, but it is 
-shorter and also does not require you to specify which objects you wish to import from the module.
+This might be a bit risky as changes in the module may affect the module which imports it, but it is 
+shorter, and doesn't require you to specify every object you want to import from the module.
 
 
 ### Custom import name
 
-We may also load modules under any name we want. This is useful when we want to import a module conditionally
+Modules may be loaded under any name you want. This is useful when importing a module conditionally
 to use the same name in the rest of the code. 
 
-For example, if you have two `draw` modules with slighty different names - you may do the following:
+For example, if you have two `draw` modules with slighty different names, you may do the following:
 
 
     # game.py
@@ -128,11 +122,9 @@ For example, if you have two `draw` modules with slighty different names - you m
 
 ### Module initialization
 
-The first time a module is loaded into a running Python script, it is initialized by executing the code in the 
-module once. If another module in your code imports the same module again, it will not be loaded twice but 
-once only - so local variables inside the module act as a "singleton" - they are initialized only once.
+The first time a module is loaded into a running Python script, it is initialized by executing the code in the module once. If another module in your code imports the same module again, it will not be loaded again, so local variables inside the module act as a "singleton," meaning they are initialized only once.
 
-This is useful to know, because this means that you can rely on this behavior for initializing objects. 
+You can then use this to initialize objects. 
 For example:
 
 
@@ -155,29 +147,28 @@ For example:
 
 ### Extending module load path
 
-There are a couple of ways we could tell the Python interpreter where to look for modules, aside from the
-default, which is the local directory and the built-in modules. You could either use the environment
-variable `PYTHONPATH` to specify additional directories to look for modules in, like this:
+There are a couple of ways to tell the Python interpreter where to look for modules, aside from the
+default local directory and built-in modules. You can use the environment variable `PYTHONPATH` to specify additional directories to look for modules like this:
 
     PYTHONPATH=/foo python game.py
 
-This will execute `game.py`, and will enable the script to load modules from the `foo` directory as well
+This executes `game.py`, and enables the script to load modules from the `foo` directory, as well
 as the local directory.
 
-Another method is the `sys.path.append` function. You may execute it *before* running an `import` command:
+You may also use the `sys.path.append` function. Execute it *before* running the `import` command:
 
     sys.path.append("/foo")
 
-This will add the `foo` directory to the list of paths to look for modules in as well.
+Now the `foo` directory has been added to the list of paths where modules are looked for.
+
 
 ### Exploring built-in modules
 
 Check out the full list of built-in modules in the Python standard library [here](https://docs.python.org/3/library/).
 
 Two very important functions come in handy when exploring modules in Python - the `dir` and `help` functions.
 
-If we want to import the module `urllib`, which enables us to create read data from URLs, we 
-simply `import` the module:
+To import the module `urllib`, which enables us to create read data from URLs, we `import` the module:
 
     # import the library
     import urllib
@@ -202,22 +193,18 @@ We can look for which functions are implemented in each module by using the `dir
     'thishost', 'time', 'toBytes', 'unquote', 'unquote_plus', 'unwrap', 'url2pathname', 'urlcleanup', 'urlencode', 
     'urlopen', 'urlretrieve']
 
-When we find the function in the module we want to use, we can read about it more using the `help` function, 
-inside the Python interpreter:
+When we find the function in the module we want to use, we can read more about it with the `help` function, using the Python interpreter:
 
     help(urllib.urlopen)
 
 ### Writing packages
 
-Packages are namespaces which contain multiple packages and modules themselves. They are simply directories, 
-but with a twist.
+Packages are namespaces containing multiple packages and modules. They're just directories, but with certain requirements.
 
-Each package in Python is a directory which **MUST** contain a special file called `__init__.py`. This file can 
-be empty, and it indicates that the directory it contains is a Python package, so it can be imported the same 
-way a module can be imported.
+Each package in Python is a directory which **MUST** contain a special file called `__init__.py`. This file, which can be empty, indicates that the directory it's in is a Python package. That way it can be imported the same way as a module.
 
 If we create a directory called `foo`, which marks the package name, we can then create a module inside that 
-package called `bar`. We also must not forget to add the `__init__.py` file inside the `foo` directory.
+package called `bar`. Then we add the `__init__.py` file inside the `foo` directory.
 
 To use the module `bar`, we can import it in two ways:
 
@@ -227,11 +214,9 @@ or:
 
     from foo import bar
 
-In the first method, we must use the `foo` prefix whenever we access the module `bar`. In the second method, 
-we don't, because we import the module to our module's namespace.
+In the first example above, we have to use the `foo` prefix whenever we access the module `bar`. In the second example, we don't, because we've imported the module to our module's namespace.
 
-The `__init__.py` file can also decide which modules the package exports as the API, while keeping other modules 
-internal, by overriding the `__all__` variable, like so:
+The `__init__.py` file can also decide which modules the package exports as the API, while keeping other modules internal, by overriding the `__all__` variable like so:
 
     __init__.py:
 
@@ -240,8 +225,7 @@ internal, by overriding the `__all__` variable, like so:
 Exercise
 --------
 
-In this exercise, you will need to print an alphabetically sorted list of all functions in the `re` module,
-which contain the word `find`.
+In this exercise, print an alphabetically sorted list of all the functions in the `re` module containing the word `find`.
 
 Tutorial Code
 -------------