2. Notations in these notes¶
We briefly introduce and describe some of the notations used throughout these notes.
2.1. Coding environment(s)¶
We will often refer to an environment for processing code or entering commands. By this, we mean a place where the technical terms and syntax of the specific programming language will be recognized. For example, in a Python environment, typing:
print("Hello, world!")
would be recognized as a valid set of commands and objects to execute. Running that command outside of a Python environment would likely lead to an error, because the syntax and keywords would not be properly understood.
Additionally, using an environment requires us to obey the rules of syntax there. All of them, all of the time. Typing the following into a Python environment:
print(Hello, world!)
... will lead to an error (the pair of quotation marks were necessary syntax here). Part of programming is to learn the syntax rules of the environment.
Most interfaces for executing computer commands have a default
environment, and we can sometimes even switch between them. For
example, when we start a Linux terminal, the default is to have a
shell environment. There, commands such as ls and cd (to
list contents and to change directories, respectively), are
understood, but not Python's print() function. Note that there
is a print program in most shells, but this has different
functionality and syntax (e.g., no parentheses are used). Having
different environments removes the ambiguity of what happens if we
type "print": in a Python environment, we get the Python one, while in
a shell environment, we get the Linux one.
We present different ways of starting a Python environment below in the setup section. Each one should interpret a given bit of code equivalently, but they have different utilities for interacting with the code or displaying output. So when we suggest trying something "in Python", you can use any kind of Python environment (IPython, Jupyter Notebook, etc.) on any kind of operating system (Linux, Mac, etc.). The only caveats are that, in general, you need to use the same major version number of Python (3.6 or later), and if a particular module is being used, then that module needs to already be installed on that computer (which is discussed later in these notes).
If we ever need to do something in a shell environment, then we will clearly state any such instances. Some of these shell commands actually can be correctly interpreted within a Python environment, but we will mostly likely just use them in a shell environment.
2.2. Bold text: technical terms¶
Throughout these notes, we will try to highlight technical terms in bold text. There are even a few instances of this on the present page. Occasionally, we might use bold text because we get excited and want to emphasize a point. Hopefully those relative cases will be apparent.
We strongly encourage you to start adopting these technical terms into the way you discuss, use and think about programming. This practice will help you formulate questions more clearly, as well as be able to interpret help files and debugging messages more easily. It will make your programming life much, much easier, in general.
That is not to say that it isn't useful to also have a less technical understanding of the concepts: that is certainly fine, and actually recommended. But computers cannot guess what they want or try to explain things in different ways. They require precision when formulating code, and it is up to us to adapt to their terminology and syntax for effective programming. It's hard being a human sometimes.
2.3. Code blocks¶
The parts of these notes that appear in green blocks such as this:
print("Sawubona")
are code blocks. These are typically commands that can be
executed or run. Unless otherwise specified, the contents will refer
to Python commands that should be executed in a Python environment or
placed in a Python script. Linux shell commands (ls, cd,
etc.) may also appear in code blocks, and we will clearly identify
those instances when they should be run in a Linux environment or
shell.
While you could certainly copy+paste such text into a terminal, script or Notebook, we will strongly recommend that you type it in yourself. Why do that, when it will be slower? Well, it will give you more practice typing commands and help you get used to the syntax in a more in-depth way. It will help make you into a more efficient programmer. But I might make mistakes if I type, instead of copy+paste! Well, that's just part of the learning process. It would actually be useful to make mistakes here, because you can more readily see where they occur, and get used to interpreting the error/debugging messages Python provides to help point out some problems. You are here to learn programming and Python, not to complete tasks as fast as you can.
Code blocks may contain letters only in plain, black font. However,
they may also contain syntax highlighting, which is when keywords
in a given computational language are recognized and shown in either
bold or colorized lettering. For example if is a keyword in
Python, and strings (text objects in quotes) are also highlighted. In
such cases, code might look like the following:
if x>0 :
print("x is positive")
else:
print("x is NOT positive")
2.5. Inline code¶
Sometimes we will refer to Python code within a paragraph and instead
of using a full code block. That is, we will include it inline,
meaningthat it is just part of the sentence structure in the
paragraph. Such inline code will typically be noticeable because the
text is formatted in gray background and uses monospace
text. For example, we might note that the integer division operator
is written as //, and that 32 // 9 evaluates to 3.
This will typically only be done for keywords or short bits of code, sometimes referred to as code snippets. Those parts of the text should be evaluable in the same way as code blocks (i.e., in a Python environment).
2.6. Python prompt: >>>¶
In a program's help text or in online documentation, you might often
see this set of characters >>>. This is an example of something
in computing called a prompt, specifically the Python prompt.
This means that what follows is code to be entered into a Python
interface (e.g., iPython environment, Jupyter-Notebook, processing
script) and executed. Note that the >>> itself should not be
copied or included in the command(s) -- the prompt just highlights the
presence of the command afterward.
So, for example, if you see the following:
>>> print(10 + 25)
... you should recognize that print(10+25) is some kind of
Python code, and you could execute just that part.
Quite often in help documentation, the line(s) following one that
one that starts with a prompt, contains the output of the prompted
command. So, a use-case example of the print function might
look like:
>>> print(10 + 25)
35
If the output would occupy multiple lines, then several lines following the prompted command might be shown.
2.7. Interactive Python prompt: In [N]:¶
More than the plain Python interface with the >>> prompt above, we
will tend to use "interactive Python" sessions, such as IPython,
Jupyter Notebook and Google Colab (discussed in the next section). The prompt for input for each of these
interfaces has the same format: In [1]:, In [2]:, In [3]:,
etc. That is, there is a counter within the square brackets as we
work within a session, increasing by one after each entry.
So, if we see the following:
In [17]: print(10 + 25)
... we will understand that print(10+25) is Python code, and
that this happens to be the seventeenth command or code snippet
evaluated in the session.
Similar to above, IPython displays the output following a prompt:
In [17]: print(10 + 25)
35
When using Jupyter Notebooks and Google Colab, the output for a cell of evaluated code also has a prompt, with matching enumeration. Thus, one might see:
In [17]: print(10 + 25)
Out[17]: 35
2.8. Linux command line prompt: $¶
Almost every command in these notes will be code for the Python
environment. However, sometimes it is useful to interact with the
Linux command line, as well. One way you might know if a command is
meant for the Linux (terminal) environment would be if the line
started with the Linux prompt symbol: $. Again, the prompt
symbol should not be included in any typed commands.
Be aware that a dollar sign $ is also a special character that
gets used in Linux commands. So, don't just leave out all such
symbols from commands. When $ is a prompt, it will be at the
start of a line and isolated; in all other cases, it is likely part of
command syntax.
So, in:
$ ls
... the dollar sign is a Linux command prompt, and one would enter
ls in a Linux terminal, say.
But in:
$ echo $PWD
... only the first $ is a prompt, and the second one is a
vital part of the command (it signifies the start of a Linux variable
name). Therefore, here one would enter echo $PWD into a Linux
terminal (which will show the present working directory).
2.9. Formatting generic/filler/replaceable text¶
Sometimes, we want to describe general coding structures and put in "filler text" for part, which can be replaced later by specific code. There are a couple common syntaxes or ways to show this, and we just mention them here for clarity as you follow along with these notes.
2.9.1. Ellipsis: ...¶
The series of (typically 3) dots ... is known as an ellipsis.
It denotes that some very unspecified text could be occur in that
spot, possibly even no text.
For example, we might write that a print function looks like
print(...), meaning that we could put a wide variety of text
between those parentheses: here, one or more strings, numbers, arrays,
or even leave it empty. The ellipsis denotes that the specific
contents are not important in the given example, just that something
could go there.
A couple more ellipsis examples are shown in the next subsections.
2.9.2. ALL CAPS (= text in all capital letters)¶
Let's say we want to suggest opening a Python script (text file) with
the program gedit in a Linux terminal. We might demonstrate the
syntax as:
gedit FILE_NAME
The generic-sounding filename in all-capital letters is, in fact,
meant to be a generic placeholder for whatever filename you might
actually have. This use of ALL_CAPITAL_LETTERS (or all caps)
is pretty common, and you might see it in help documentation. The
stuff in all caps is typically a description of when could generally
go there.
We might also demonstrate syntax for opening a Python text file like:
gedit FILE_NAME.py
Here, the lowercase parts are meant to be literal: users will expect
to use gedit to open the file, and they should expect the file to
have a ".py" extension (which signifies it is a Python script file).
The generic part that would readily change is just the base name part
of the file, which is shown here ni all caps.
Consider specifying the syntax of a basic conditional. We want to
note that it starts with the exact word if, contains some kind of
statement, and then the line ends with a colon :; furthermore,
immediately after this line will be something to be done (if the
stated statement is true), which could be one or more commands. We
could write this as:
if STATEMENT :
COMMAND_1
COMMAND_2
...
In this case, neither the term "STATEMENT" nor either "COMMAND" is a
required part of the syntax, and the user would put their own specific
values their for their code of interest. That is what we mean by
referring to the all cap text as a "placeholder". The all caps is
slightly less generic than the ellipsis (which readers will also
recognize here): we didn't put ... after if because we do
have a specific category of thing to go there, namely a statement.
If there ever is a case where a specific term really is in all capital letters, hopefully either the context will make it clear or it will be explicitly noted. For example, we might define a global variable at the top of a program as follows:
GRAVITY = 9.8 # units: m/s**2
and in this case, the all caps is not meant be generic (though you could certainly change the variable name in your own program). It just makes the object name stick out. All we can say is that context matters, knowing when someone is demonstrating a possibly generic example or template to be followed vs just happening to use all caps.
2.9.3. <Text between angle brackets>¶
Another fairly common way of denoting generic text would be to
surround it with angle brackets. For example, we might talk of a
<function> or a <list of ints>.
Many times, it could be used in exactly the same instance as the all caps generic text, one or the other being clearer (and therefore preferable) in some case. Of the two examples above, using all caps would probably be more common in the filename case, but the conditional could be written as:
if <statement> :
<command 1>
<command 2>
...
It is equivalent to the above. The one advantage this might have is demarking the start and end of the generic text when more than one word is used. We might actually write the above a little more fully as:
if <one or more statements> :
<command 1>
<command 2>
...
(This is actually more precise, because we could require multiple things to be true simultaneously in order to execute "command 1", "command 2" etc.). In this case, the bracket-enclosing syntax might look a little nicer than doing the same in all caps (I think).
As in the ALL CAPS case, we just have to be careful to know when the angle brackers are actually part of the specific code. For example, conditionals will often use greater than and less than symbols, such as in:
if -10<x and 10>x :
print("The absolute value of x is less than 10!")
Again, hopefully the context makes clear that the angle brackets here are actually symbols to use in the code here, instead of representing generic text fields.
2.10. Continuation of line character: \¶
By default, the Python interpreter reads each line one-by-one, and all
parts of a given command or expression have to fit on one line. That
is, the end of a line is a break in interpreting a command. However,
one can tell Python to keep reading the next line as a continuation of
the present one, by placing a continuation of line character \
at the very end of the line.
Note that this is one situation in which having extra space does
matter: if a space or any other character appears
to the right of the \, then the Python interpreter won't
actually continue on to the next line as desired. Since it is really
tricky to see an empty space, this can lead to confusion at times,
so be sure to check your code's continuation-of-line spacing and its
outputs carefully.
As an example of using the continuation of line character:
1x = 1 + 2 + 3 + 4 + 5 + 6 + 7 \
2 + 8 + 9 + 10
3print("Gauss knows quickly that the sum is:", x)
... produces the right output:
Gauss knows quickly that the sum is: 55
None of the spacing within Line 2 matters; we just wrote it like that
to be clearly readable. However, there is an important spacing
consideration to be aware of: if you put a space after the \ in
Line 1, the you will break the continuation. Python will warn you
about this, fortunately, because it is very difficult to see otherwise:
1 File "<ipython-input-199-4cd90b3b8977>", line 1
2 x = 1 + 2 + 3 + 4 + 5 + 6 + 7 \
3 ^
4SyntaxError: unexpected character after line continuation character
But notice that arrow-like symbol ^ (called a caret) in the
error message: Python is helpfully trying to tell us where and what
the problem is!
Note that some other programming languages don't warn about a space
trailing an end-of-line \. Instead, they just try to evaluate the
next line on its own, which typically leads to an error because it is
often (but not always) an incomplete expression.
2.11. Continuation of line for some paired symbols¶
(This section is primarily for future reference; we will come back to it.)
... that all being said about the continuation of line character,
there are cases where Python will automatically continue reading and
interpreting multiple lines as part of a single expression, without
requiring \. This occurs for syntaxes that have explicit opening
and closing partners namely:
(...): parentheses[...]: square brackets{...}: curly brackets'''...'''and"""...""": triple-quotes (used for strings)
Note that it does not occur for all string boundaries (such as
'...', etc.).
So, we could write:
a = ( 5
+
25)
print(a)
... and the output would (correctly) display 30, with no error.
Stylewise, this is not the most useful example-- but when we get to
using functions with many inputs, then vertically spreading things out
within parentheses will simplify reading and interpretation.
Basically, we will come back to this point point later, as we start using these pairs of open/close symbols more. But this is something worth keeping in the back of your mind from the start.