Overall Structure¶

The following figure shows a Spyder edit pane for the example above with two regions identified. We will return soon to examine the detailed syntax of the individual statements. For now we want to get a “big picture” view.

The topmost part of the example code is an import statement. An import statement identifies a Python module that contains code to be reused in this program. The import statement shown here identifies a module named weather. The weather module contains the the function get_forecasts that is used in the program. The weather module also contains other functions that are part of the weather module. 

The import statement is important because no serious Python program is written without reusing some code. In fact, most applications reuse code extensively. Not only does code reuse lower the cost of developing new applications but the reused code is also likely to have been tested and have had programming errors removed by previous uses. The Python developer community has made available a large number of modules some of which we will use later for data visualization.

The second area shown in the  example code is the "main" program.  This is the code where the execution of the program begins. When this code has been fully executed the program ends its execution.

Indentation¶

Another general characteristic of Python programs the importance of how the lines of code are indented. Python uses indentation to answer a question that all textual programming languages have to answer. In Python, the beginning of an iteration is signaled by the for keyword and the beginning of a decision is signaled by the if keyword. However, where is the end of the body of the code for the iteration? and which statements are in the different parts of the decision? Different languages answer this question in different ways. Blockly answers these questions by the shape of the blocks. All of the code in the body of an iteration is in the slot for the iteration block. Similarly, all of the code in the then part of a decision (the blocks performed when the decision's condition is true) are in the slot provided in the decision block. Python uses indentation to answer this question.

In the following figure, two vertical lines, one red and one blue, are used to identify where indentation has been used. You can see that every line that is part of the body of the iteration is indented as least four spaces and every line that is part of the decision is indented at least four additional (a total of eight) spaces. It is common practice to use four additional spaces at each new level of indentation.

Care is needed because spaces added by using the “Tab” key may be different than a sequence of spaces. While they may look the same to you they are different to the Python interpreter. Four spaces is four characters while one tab is only one character. Welcome to the world of computing where details do matter.

Punctuation using Colons

Another part of the important syntax of Python is the punctuation required for iteration and decisions. In natural languages (like English, Spanish, etc) punctuation is used to indicate the various parts of a sentence. In Python, the colon symbol (":") is used to indicate parts of the iteration and decision statements. The following figure shows where this punctuation is needed in our example program.

Punctuating Python Programs

As shown in the figure the colon is used at the end of the for statement that introduces an iteration. Also, colons are also used at the end of the if and elif statements that are parts of the decision statement. Although not shown, an else statement is also punctuated with a colon. 

Comments¶

Understanding what (especially complex) code does may be difficult, so documenting what the code is intended to do is a sign of good craftsmanship. Each programming language has some means of including comments in the program text. These comments provide a way for the code’s author to convey to a human reader important information about the code. The meaning, purpose, or design are often documented in this way. Comments are written by a human for a human and are skipped over by the Python interpreter. The following figure shows our example code with comments added.

Python comments begin with a “#” (pound sign or hash symbol) and extend to the end of the line. As shown in the figure above comments can occupy either an entire line or only part of line. The sequence of comments preceding the main program each occupy the entire line. Such sequences are often used when there is a lot to say about something. Remember that these (and all) comments are skipped over by the interpreter. The two individual comments in the main program each occupy only part of a line. Each individual comment is meant to explain what the code on that line does. Comments like this are used when there is only a brief clarification that is needed.

Finally, there is no sense that the comments are “correct” or “meaningful” in any way because the comments are ignored by the Python interpreter. The comments for the main program could say that the program deals with crime rate in New York, NY even though this is clear incorrect to the human reader. As noted, the interpreter ignores the comments and does what the code says to do. The programmer is entirely responsible for ensuring that the comments are meaningful.

Error Messages

Just as in writing sentences in a natural language, we often make mistakes in expressing a statement in a programming language correctly. These are known in both cases as syntax errors. Spyder will automatically check the syntax of the code as you are typing in the editor pane and report problems to you. Also, Spyder will report such errors if you Run a program with syntax errors. To illustrate this syntax error reporting, a syntax error has been deliberately introduced into the code of one of the examples as shown in the following figure. The syntax error is in the line if temp < 70. Note that the colon (”:”) is missing in the incorrect version shown in the figure. The absence of the colon at the end of this line is a syntax mistake. Notice that Spyder has put a small warning icon in the left margin of the line of code that has a syntax mistake. If you hover the cursor over the icon you will see the message box that is shown in the figure. Once you fix the syntax mistake the warning icon will go away. 

The editor will report only the first syntax error that it has found. If the code contains several syntax errors the syntax checking will have to be repeated once for each error. It is a good habit to periodically check for the presence of the warning icons in the code you are writing.

It may be that you overlook or ignore the syntax warnings provided by the Spyder editor and Run the program. The interpreter will be able to execute the program up to the point of the syntax error, but no farther because the syntax error makes the statement unintelligible to the interpreter. In this case the Python console pane (in the lower right corner) will report an error as shown in the above figure. This error message shows the line containing the syntax error (note the small caret symbol at the end of the line) and an error message (“SyntaxError: invalid syntax”).

     number = 0
     total = 250
     average = total / number

You can get additional help with the Python syntax by looking at explanation and examples in the Python Tutorial. The definitive though harder to read source of help is the Python Language Reference. These documents can also be accessed from Spyder: in the Help menu select the Python documentation entry. There are also many other web tutorials and examples that you can find via a web search.