UPPA - Master Géoénérgies – UE Python Prof.

Peter MOONEN

TD01 Program like a pro

Part 1: Setting up your virtual environment and IDE
Install anaconda, if you don’t have it yet.

You can download the Anaconda distribution for your operating system (windows/linux/mac)
via https://www.anaconda.com/

If you’re an experience user, you could also use miniconda, the lightweight version of Anaconda.
However, the graphical user interface of Anaconda Navigator, offered in the Anaconda
distribution is a must for less experienced users.

Create an environment for this course:

• Open Anaconda Navigator

• Go to the Environments tab
• Click on Create (button at the bottom). A pop-up menu shows.
o choose a NAME without spaces. This is important.
o ensure the LOCATION has no spaces. Check carefully. Sometimes the environment is
stored under “…/Jean Dubois/…” or so, i.e. including a space in the user name. This will
lead to unpredictable errors. If there is a space, cancel the creation of the environment,
and follow the alternative method described below.
o I use Python 3.9. In general, the choice depends on the packages that you will need.
Each package has a minimum required version.
• Click on Create

Alternative environment creation in case the proposed location DOES have spaces in it:

• Close Anaconda Navigator

• Open the Anaconda Powershell Prompt
• Go to the location where the environment needs to be (under windows this is with “cd” for
“change directory”). Remember, the path should not contain spaces.
• Type: “conda create --prefix=EnvName python=3.9” (without quotes), where EnvName is the
name of your choice (again, without spaces)
• Close the Anaconda Powershell Prompt
• Open Anaconda Navigator

The newly created environment should show up on your Environments-tab.

Now install the following packages:

• Matplotlib, version 3.8

• pdoc3, version 0.9.2
• Spyder, version 5.4

In general, it is good practice to verify version compatibility prior to installing. For larger projects, you
would typically test the installation on a duplicate of the environment to avoid any risk.
UPPA - Master Géoénérgies – UE Python Prof. Peter MOONEN

Part 2: Basics of scripting, documenting and debugging

Basics of scripting
Before any programming, it is good practice to create a new folder on your system. All files (inputs,
scripts, outputs, log-files, documentation, etc.) will be stored inside this folder or in its subfolders. This
avoids that things get messy.

• Create a “TD01_FamilyName”-folder on your system, where FamilyName is your name.

Let’s open our IDE.

• Open Anaconda Navigator

• On the Home-tab, select your virtual environment
• Open the Spyder-IDE by clicking on the icon

Now we’ll create our first script from scratch. You have three options:

• The menu: Select “File” and then “New file”

• The icon: Click on the “New file” icon. Normally this is the first one at the top left.
• The shortcut: Press Ctrl+N

Save this file under the name “sayHello.py” in your “TD01_FamilyName”-folder

It’s time to add some code. Write the following command below the header:
print(‘Hello’)

To run the code, you have again three options:

• The menu: Select “Run” and then “Run”

• The icon: Click on the “Run” icon. It looks like a green triangle pointing to the right.
• The shortcut: Press F5

Normally, the console (i.e. the pane at the bottom right) will print
Hello

The remaining instructions are interactively provided in class. We’ll cover:

• constants, variables and functions

• module imports
• formats, comments and docstrings
• input and output
• using help
• using auto-complete

Taking a step back, we collectively obtained the typical structure common to well-coded “.py”-files:

1. a comment block describing the code

2. import statements
3. declaration of constants
UPPA - Master Géoénérgies – UE Python Prof. Peter MOONEN

4. function definitions
5. main() function definition
6. if __name__ == ‘__main’:
main()

Use this file as your personal template for future reference – Starting from this one is much more handy
than to start from a white page every time you start a new script.

Basics of debugging
It is often said that coding only takes 1% of your time, and that you're busy finding the errors in your
code the other 99% of the time. That's pretty sad... Starting programmers indeed often lack the tools to
efficiently program code that properly runs. Hence a focus on debugging, i.e. the art of figuring out
where the errors are. If you know that delivered (i.e. finished and fully tested) software on average still
contains about 1-25 errors per 1000 lines of code [Steve McConnell, Code Complete, 2nd Ed.], you
quickly realize that debugging is not limited to newbies.

• Download “TD01.py” & “TD01_dbs from Elearn.

• Store them in the your “TD01_FamilyName”-folder.
• Open Anaconda Navigator.
• On the Home-tab, select your virtual environment.
• Open the Spyder-IDE by clicking on the icon.
• Open “TD01.py” via the File – Open menu.

The goal of the exercise is to use the “variable explorer”, the information in the console, the help-files
(ctrl-i) and the debug-functionality of Spyder to debug the “TD01.py”-file and to correct the errors. The
file contains all three types of errors:

• Syntax errors, preventing the code from compiling.

• Runtime errors, preventing the code from running until the end.
• Semantic errors, preventing the code run as intended.

Find them all, correct them, and don’t forget to save the file.

Basics of refactoring
Arriving here, the code in the “TD01.py”-file works, but the code is hard to read and difficult to reuse.
Code refactoring is the process of improving the internal structure, readability, and maintainability of a
software codebase without altering its external behavior or functionality. Make the following
improvements:

• Open the Spyder-IDE as previously explained.

• Open “TD01.py” via the File – Open menu.
• define a main() function that takes a variable “filename” as an input and returns the Boolean
“finished”. Regroup the necessary code under this function.
• Add the “if __name__ == ‘__main__’”-construct to ensure that the code can be run as
a standalone script or as a callable module. Test both use cases.
• Save the file.
UPPA - Master Géoénérgies – UE Python Prof. Peter MOONEN

Basics of formatting and documenting

As you might have noticed, grasping how the “TD01.py”-file works is not so easy. In part this is due to
the lack of documentation. The formatting is also not improving readability.

Apply the PEP-8 style guide for Python code on the “TD01.py”-file. In particular:

• Update the multi-line docstring in the header of the program. It should contain:
o a short sentence describing what the program does
o info about the author of the initial script, and the authors who made contributions
• Add a multi-line docstring in each function (or class, or method). It not only helps to understand
what the function does, but it also becomes the documentation (see further). A good docstring
contains at least
o a short description on what the function (or class, or method) does.
o “input arguments: “ followed by a description of their requirements.
o “returns: …” followed by a description of the return argument(s).

Note that a right click on a function (or class, or method) in Spyder opens a context menu from
which you can select “generate docstring”. This inserts a template for the docstring. Fill it with
the appropriate info and it’s done.

Note that you can consult your documentation also by e.g. typing
print(is_answer.__doc__) in the console. This can be applied to any function (or class,
or method). If that function is properly documented, you will get all info on how to use it … and
you don’t have to dig into the code. This is why you should carefully write docstrings for any
public class, function and method.

• Fix the formatting. This includes:

o Removing trailing spaces from each line.
o Ensure that there is a space behind each comma, but none before. The same holds for
colons and semicolons.
o Put spaces before and after the equal sign (“=”) to improve readability. This also holds
for all comparison operators (“>”, “>=”, “==”, …).
o Having exactly two blank lines before and two blank lines after each definition
o Having exactly one blank line at the end of the code
o Ensuring that no line exceeds the 79 character rule. If lines are too long, break over
multiple lines and apply adequate spacing

Note that the “Source”-menu in Spyder contains a menu item entitled “Format file or selection
with Autopep8”. This command corrects most formatting errors automatically. Ctrl+Alt+i has
the same functionality.

Test whether the file still runs properly and save it.
UPPA - Master Géoénérgies – UE Python Prof. Peter MOONEN

Part 3: From scripts to programs

Structure of a program
As Python projects grow bigger, it is good practice to split them across different files and to group useful
coding bricks into packages. The next exercise focuses on the difficulties that hereby arise, most notably
the role of “__init__.py”-files and the issues with importing and calling functions.

• First download file “TD01.zip” from Elearn and unzip its contents somewhere on the computer.
The file contains a number of files (README, requirements, LICENSE, etc.) that we will need. You
can run “main_before_refactoring.py” to convince yourself that the code actually works.
• Now replicate the file and folder structure shown below in your “TD01_FamilyName”-folder. All
python-files are empty at this point, except for “basic_test.py” which originates from the zip-file.
The README, requirements and LICENSE-files also come from the downloaded zip-file.

We’re now ready for some advanced refactoring.

Refactoring, part 2
While “main_before_refactoring.py” is a silly program, it is representative for many development
efforts: all is in a single file and the program keeps on growing, leading to difficulties in understanding
the structure and its dependencies. Here we’ll show how a program can be split into different parts. In a
real case, each separate part would have meaning, and would be 100% recyclable by other projects.
Here the subdivision is somewhat synthetic, but from a programming point of view, the required skills
are identical.

• Open the Spyder-IDE as previously explained. Use the correct environment.

• Open “main_before_refactoring.py” via the File – Open menu.

You’ll need to distribute the content of this file over various files (=use cut and paste):
UPPA - Master Géoénérgies – UE Python Prof. Peter MOONEN

original name new name new location

subpackage_function() / subpackage_module.py
helper_function() / helpers.py
launch_game1() main() riddle.py
rest of the code / main.py
Now the program doesn’t run anymore. To make it work, several things are needed:

▪ adding import statements of the used packages to all “.py” files that use a function or variable
from another file (=module). *
▪ adding code to the “__init__.py”-files so that the (public) functions from the modules become
available upon import, and this with the desired name. Typically the syntax is from … import …
as …
▪ ensuring that the function calls use the right namespace. Typically this is
package.module.function() or so.
▪ Add the “if __name__ == ‘__main__’”-construct to “riddle.py” to ensure that the code
can be run as a standalone script or as a callable module. Test both use cases. Typically you’ll
encounter problems related to absolute or relative paths in import statements. The easiest way
to circumvent them is to perform the import within the if-function.

Ensure that the program runs from “main.py” AND that the test returns ok (from “basic_test.py”). Pay
special attention to the following:

• The main.py-file must be unaware of the internal structure of the game-package. That means
that a future release of the game-package, with different file names, subfolders, etc. should not
have any impact to the main.py-file. Of course, under the condition that the developers of the
game-package did a good job and updated the __init__.py file.
• Each game (here only “riddle.py” for the time being) must also run as independent code.

Extending functionality
As the program became easier to maintain, we can now add the game from “part 2” to the library.

• Rename the “TD01.py” and “TD01_dbs.json”-files to “twenty_questions.py” and

“twenty_questions _dbs.json”, respectively, and place them in the subpackage-folder.
• integrate the game into the “main.py”-file by extending the “MyFunctions”-class as well as
completing “__init__.py”. Do not make any changes to “twenty_questions.py”. If it worked
previously it should still run now.

Ensure that you can run the game via “main.py” with “2” as input. Also make sure the file still runs
independently (so just by directly running twenty_questions.py”. Don’t forget to save.

Enhancing robustness
In case somebody enters an unknown game number (e.g. “3”), the code will crash. Add a “try … except”-
block. The code should print “Invalid input” if someone enters wrong input, and let the user try again.
Here is the default syntax:
try:
… things to try …
UPPA - Master Géoénérgies – UE Python Prof. Peter MOONEN

except:
… what to do when something went wrong …

Test the code and don’t forget to save.

Automatically generate code documentation

As mentioned earlier, generating documentation for a well-documented code can be performed
automatically. Prior to doing this, check the following:

• all files must have a header, including the “__init__.py”-files.

• all functions and classes must have a docstring.
• all comments must be up to date and complementary to the code (i.e. rather explaining why you
do something instead of repeating in words what is written in code).

Once you’re happy with the in-code documentation, undertake the following steps:

• Open Anaconda Navigator. Go to the Environments-tab and ensure that your custom-made
environment is selected.
• Still on the Environments-tab, left-click on the green arrow next to your environment. A context
menu appears. Select “open terminal”

In the terminal, navigate to your “TD01_FamilyName”-folder. This can be a bit tricky.

▪ To change directory, use “cd” followed by a space and the (target) directory name. Confirm by
hitting the “enter”-button.
▪ cd .. and hitting “enter” moves one folder up.
▪ To change drive, e.g. to go from the C to the E drive, you need cd /d e:, where /d indicates a
change in directory.
▪ The tab-button performs autocomplete.
UPPA - Master Géoénérgies – UE Python Prof. Peter MOONEN

Now generate the docs for your package. The basic syntax for web-compatible documentation is:

pdoc --html MODULE

where “MODULE” is the name of the Python module or package for which you want to generate the
documentation. You can check out the complete syntax and all available options with pdoc --help. You
could generate docs for each module separately, but that’s not the aim. try to generate in one go the
docs for the entire package (=the full folder). Note that “.” is the current location, and “./.” would imply
the current location and all subfolders.

• Make sure your documentation ends up in the “docs” folder.

• Make sure the documentation works. You can check by double-clicking the “index.html”-file.
From there on you can browse the documentation for the entire program. If some
documentation is missing, incorrect or incomplete, correct the docstring in the source code and
re-generate the documentation.

Zip your folder with its contents “TD01_FamilyName.zip”

Upload the file on Elearn.