Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: The Python print[] Function: Go Beyond the Basics
If you’re like most Python users, including me, then you probably started your Python journey by learning about print[]
. It helped you write your very own hello world
one-liner. You can use it to display formatted messages onto the screen and perhaps find some bugs. But if you think that’s all there is to know about Python’s print[]
function, then you’re missing out on a lot!
Keep reading to take full advantage of this seemingly boring and unappreciated little function. This tutorial will get you up to speed with using Python print[]
effectively. However, prepare for a deep dive as you go through the sections. You may be surprised how much print[]
has to offer!
By the end of this tutorial, you’ll know how to:
- Avoid common mistakes with Python’s
print[]
- Deal with newlines, character encodings, and buffering
- Write text to files
- Mock
print[]
in unit tests - Build advanced user interfaces in the terminal
If you’re a complete beginner, then you’ll benefit most from reading the first part of this tutorial, which illustrates the essentials of printing in Python. Otherwise, feel free to skip that part and jump around as you see fit.
Printing in a Nutshell
Let’s jump in by looking at a few real-life examples of printing in Python. By the end of this section, you’ll know every possible way of calling print[]
. Or, in
programmer lingo, you’d say you’ll be familiar with the function signature.
Calling print[]
The simplest example of using Python print[]
requires just a few keystrokes:
You don’t pass any arguments, but you still need to put empty parentheses at the end, which tell Python to actually execute the function rather than just refer to it by name.
This will produce an invisible newline character, which in turn will cause a blank line to appear on your screen. You can call print[]
multiple times like this to add vertical space. It’s just as if you were hitting Enter on your keyboard in a word processor.
A newline character is a special control character used to indicate the end of a line [EOL]. It usually doesn’t have a visible representation on the screen, but some text editors can display such non-printable characters with little graphics.
The word “character” is somewhat of a misnomer in this case, because a newline is often more than one character long. For example, the Windows operating system, as well as the HTTP protocol, represent newlines with a pair of characters. Sometimes you need to take those differences into account to design truly portable programs.
To find out what constitutes a newline in your operating system, use Python’s built-in os
module.
This will immediately tell you that Windows and DOS represent the newline as a sequence of \r
followed by \n
:
>>>
>>> import os
>>> os.linesep
'\r\n'
On Unix,
Linux, and recent versions of macOS, it’s a single \n
character:
>>>
>>> import os
>>> os.linesep
'\n'
The classic Mac OS X, however, sticks to its own “think different” philosophy by choosing yet another representation:
>>>
>>> import os
>>> os.linesep
'\r'
Notice how these characters appear in string literals. They use
special syntax with a preceding backslash [\
] to denote the start of an escape character sequence. Such sequences allow for representing control characters, which would be otherwise invisible on screen.
Most programming languages come with a predefined set of escape sequences for special characters such as these:
\\
: backslash\b
: backspace\t
: tab\r
: carriage return [CR]\n
: newline, also known as line feed [LF]
The last two are reminiscent of mechanical typewriters, which required two separate commands to insert a newline. The first command would move the carriage back to the beginning of the current line, while the second one would advance the roll to the next line.
By comparing the corresponding ASCII character codes, you’ll see that putting a backslash in front of a character changes its meaning completely. However, not all characters allow for this–only the special ones.
To compare ASCII character codes, you may want to use the built-in ord[]
function:
>>>
>>> ord['r']
114
>>> ord['\r']
13
Keep in mind that, in order to form a correct escape sequence, there must be no space between the backslash character and a letter!
As you just saw, calling print[]
without arguments results
in a blank line, which is a line comprised solely of the newline character. Don’t confuse this with an empty line, which doesn’t contain any characters at all, not even the newline!
You can use Python’s string literals to visualize these two:
'\n' # Blank line
'' # Empty line
The first one is one character long, whereas the second one has no content.
In a more common scenario, you’d want to communicate some message to the end user. There are a few ways to achieve this.
First, you may pass a string literal directly to print[]
:
>>>
>>> print['Please wait while the program is loading...']
This will print the message verbatim onto the screen.
String literals in Python can be enclosed either in single quotes ['
] or double quotes ["
]. According to
the official PEP 8 style guide, you should just pick one and keep using it consistently. There’s no difference, unless you need to nest one in another.
For example, you can’t use double quotes for the literal and also include double quotes inside of it, because that’s ambiguous for the Python interpreter:
"My favorite book is "Python Tricks"" # Wrong!
What you want to do is enclose the text, which contains double quotes, within single quotes:
'My favorite book is "Python Tricks"'
The same trick would work the other way around:
"My favorite book is 'Python Tricks'"
Alternatively, you could use escape character sequences mentioned earlier, to make Python treat those internal double quotes literally as part of the string literal:
"My favorite book is \"Python Tricks\""
Escaping is fine and dandy, but it can sometimes get in the way. Specifically, when you need your string to contain relatively many backslash characters in literal form.
One classic example is a file path on Windows:
'C:\Users\jdoe' # Wrong!
'C:\\Users\\jdoe'
Notice how each backslash character needs to be escaped with yet another backslash.
This is even more prominent with regular expressions, which quickly get convoluted due to the heavy use of special characters:
'^\\w:\\\\[?:[?:[?:[^\\\\]+]?|[?:[^\\\\]+]\\\\[^\\\\]+]*]$'
Fortunately, you can turn off character escaping entirely with the help of raw-string literals. Simply prepend an r
or R
before the opening quote, and now you end up with this:
r'C:\Users\jdoe'
r'^\w:\\[?:[?:[?:[^\\]+]?|[?:[^\\]+]\\[^\\]+]*]$'
That’s much better, isn’t it?
There are a few more prefixes that give special meaning to string literals in Python, but you won’t get into them here.
Lastly, you can define multi-line string literals by enclosing them between '''
or """
, which are often used as docstrings.
Here’s an example:
"""
This is an example
of a multi-line string
in Python.
"""
To prevent an initial newline, simply put the text right after the opening """
:
"""This is an example
of a multi-line string
in Python.
"""
You can also use a backslash to get rid of the newline:
"""\
This is an example
of a multi-line string
in Python.
"""
To remove indentation from a multi-line string, you might take advantage of the built-in textwrap
module:
>>>
>>> import textwrap
>>> paragraph = '''
... This is an example
... of a multi-line string
... in Python.
... '''
...
>>> print[paragraph]
This is an example
of a multi-line string
in Python.
>>> print[textwrap.dedent[paragraph].strip[]]
This is an example
of a multi-line string
in Python.
This will take care of unindenting paragraphs for you. There are also a few other useful functions in textwrap
for text alignment you’d find in a word processor.
Secondly, you could extract that message into its own variable with a meaningful name to enhance readability and promote code reuse:
>>>
>>> message = 'Please wait while the program is loading...'
>>> print[message]
Lastly, you could pass an expression, like string concatenation, to be evaluated before printing the result:
>>>
>>> import os
>>> print['Hello, ' + os.getlogin[] + '! How are you?']
Hello, jdoe! How are you?
In fact, there are a dozen ways to format messages in Python. I highly encourage you to take a look at f-strings, introduced in Python 3.6, because they offer the most concise syntax of them all:
>>>
>>> import os
>>> print[f'Hello, {os.getlogin[]}! How are you?']
Moreover, f-strings will prevent you from making a common mistake, which is forgetting to type cast concatenated operands. Python is a strongly typed language, which means it won’t allow you to do this:
>>>
>>> 'My age is ' + 42
Traceback [most recent call last]:
File "", line 1, in
'My age is ' + 42
TypeError: can only concatenate str [not "int"] to str
That’s wrong because adding numbers to strings doesn’t make sense. You need to explicitly convert the number to string first, in order to join them together:
>>>
>>> 'My age is ' + str[42]
'My age is 42'
Unless you handle such errors yourself, the Python interpreter will let you know about a problem by showing a traceback.
As with any function, it doesn’t matter whether you pass a literal, a variable, or an expression. Unlike many other functions, however,
print[]
will accept anything regardless of its type.
So far, you only looked at the string, but how about other data types? Let’s try literals of different built-in types and see what comes out:
>>>
>>> print[42] #
42
>>> print[3.14] #
3.14
>>> print[1 + 2j] #
[1+2j]
>>> print[True] #
True
>>> print[[1, 2, 3]] #
[1, 2, 3]
>>> print[[1, 2, 3]] #
[1, 2, 3]
>>> print[{'red', 'green', 'blue'}] #
{'red', 'green', 'blue'}
>>> print[{'name': 'Alice', 'age': 42}] #
{'name': 'Alice', 'age': 42}
>>> print['hello'] #
hello
Watch out for the None
constant, though. Despite being used to indicate an absence of a value, it will show up as
'None'
rather than an empty string:
How does print[]
know how to work with all these different types? Well, the short answer is that it doesn’t. It implicitly calls str[]
behind the scenes to type cast any object into a string. Afterward, it treats strings in a uniform way.
Later in this tutorial, you’ll learn how to use this mechanism for printing custom data types such as your classes.
Okay, you’re now able to call print[]
with a single argument or without
any arguments. You know how to print fixed or formatted messages onto the screen. The next subsection will expand on message formatting a little bit.
To achieve the same result in the previous language generation, you’d normally want to drop the parentheses enclosing the text:
# Python 2
print
print 'Please wait...'
print 'Hello, %s! How are you?' % os.getlogin[]
print 'Hello, %s. Your age is %d.' % [name, age]
That’s because print
wasn’t a function back then, as you’ll see in the
next section. Note, however, that in some cases parentheses in Python are redundant. It wouldn’t harm to include them as they’d just get ignored. Does that mean you should be using the print
statement as if it were a function? Absolutely not!
For example, parentheses enclosing a single expression or a literal are optional. Both instructions produce the same result in Python 2:
>>>
>>> # Python 2
>>> print 'Please wait...'
Please wait...
>>> print['Please wait...']
Please wait...
Round brackets are actually part of the expression rather than the print
statement. If your expression happens to contain only one item, then it’s as if you didn’t include the brackets at all.
On the other hand, putting parentheses around multiple items forms a tuple:
>>>
>>> # Python 2
>>> print 'My name is', 'John'
My name is John
>>> print['My name is', 'John']
['My name is', 'John']
This is a known source of confusion. In fact, you’d also get a tuple by appending a trailing comma to the only item surrounded by parentheses:
>>>
>>> # Python 2
>>> print['Please wait...']
Please wait...
>>> print['Please wait...',] # Notice the comma
['Please wait...',]
The bottom line is that you shouldn’t call print
with brackets in Python 2. Although, to be completely accurate, you can work around this with the help of a __future__
import, which
you’ll read more about in the relevant section.
Separating Multiple Arguments
You saw print[]
called without any arguments to produce a blank line and then called with a single argument to display either a fixed or a formatted message.
However, it turns out that this function can accept any number of positional arguments, including zero, one, or more arguments. That’s very handy in a common case of message formatting, where you’d want to join a few elements together.
Arguments can be passed to a function in one of several ways. One way is by explicitly naming the arguments when you’re calling the function, like this:
>>>
>>> def div[a, b]:
... return a / b
...
>>> div[a=3, b=4]
0.75
Since arguments can be uniquely identified by name, their order doesn’t matter. Swapping them out will still give the same result:
>>>
>>> div[b=4, a=3]
0.75
Conversely, arguments passed without names are identified by their position. That’s why positional arguments need to follow strictly the order imposed by the function signature:
>>>
>>> div[3, 4]
0.75
>>> div[4, 3]
1.3333333333333333
print[]
allows an arbitrary number of positional arguments thanks to the *args
parameter.
Let’s have a look at this example:
>>>
>>> import os
>>> print['My name is', os.getlogin[], 'and I am', 42]
My name is jdoe and I am 42
print[]
concatenated all four arguments passed to it, and it inserted a single space between them so that you didn’t end up with a
squashed message like 'My name isjdoeand I am42'
.
Notice that it also took care of proper type casting by implicitly calling str[]
on each argument before joining them together. If you recall from the previous subsection, a naïve concatenation may easily result in an error due to incompatible types:
>>>
>>> print['My age is: ' + 42]
Traceback [most recent call last]:
File "", line 1, in
print['My age is: ' + 42]
TypeError: can only concatenate str [not "int"] to str
Apart from accepting a variable number of positional arguments, print[]
defines four named or keyword
arguments, which are optional since they all have default values. You can view their brief documentation by calling help[print]
from the interactive interpreter.
Let’s focus on sep
just for now. It stands for separator and is assigned a single space [' '
] by default. It determines the value to join elements with.
It has to be either a string or None
, but the latter has the same effect as the default space:
>>>
>>> print['hello', 'world', sep=None]
hello world
>>> print['hello', 'world', sep=' ']
hello world
>>> print['hello', 'world']
hello world
If you wanted to suppress the separator completely, you’d have to pass an empty string [''
] instead:
>>>
>>> print['hello', 'world', sep='']
helloworld
You may want print[]
to join its arguments as separate lines. In that case, simply pass the escaped newline character described earlier:
>>>
>>> print['hello', 'world', sep='\n']
hello
world
A more useful example of the sep
parameter would be printing something like file paths:
>>>
>>> print['home', 'user', 'documents', sep='/']
home/user/documents
Remember that the separator comes between the elements, not around them, so you need to account for that in one way or another:
>>>
>>> print['/home', 'user', 'documents', sep='/']
/home/user/documents
>>> print['', 'home', 'user', 'documents', sep='/']
/home/user/documents
Specifically, you can insert a slash character [/
] into the first
positional argument, or use an empty string as the first argument to enforce the leading slash.
One more interesting example could be exporting data to a comma-separated values [CSV] format:
>>>
>>> print[1, 'Python Tricks', 'Dan Bader', sep=',']
1,Python Tricks,Dan Bader
This wouldn’t handle edge cases such as escaping commas correctly, but for simple use cases, it should do. The line
above would show up in your terminal window. In order to save it to a file, you’d have to redirect the output. Later in this section, you’ll see how to use print[]
to write text to files straight from Python.
Finally, the sep
parameter isn’t constrained to a single character only. You can join elements with strings of any length:
>>>
>>> print['node', 'child', 'child', sep=' -> ']
node -> child -> child
In the upcoming subsections, you’ll explore the remaining
keyword arguments of the print[]
function.
To print multiple elements in Python 2, you must drop the parentheses around them, just like before:
>>>
>>> # Python 2
>>> import os
>>> print 'My name is', os.getlogin[], 'and I am', 42
My name is jdoe and I am 42
If you kept them, on the other hand, you’d be passing a single tuple element to the print
statement:
>>>
>>> # Python 2
>>> import os
>>> print['My name is', os.getlogin[], 'and I am', 42]
['My name is', 'jdoe', 'and I am', 42]
Moreover, there’s no way of altering the default separator of joined elements in Python 2, so one workaround is to use string interpolation like so:
>>>
>>> # Python 2
>>> import os
>>> print 'My name is %s and I am %d' % [os.getlogin[], 42]
My name is jdoe and I am 42
That was the default way of formatting strings until the .format[]
method got backported from Python 3.
Preventing Line Breaks
Sometimes you don’t want to end your message with a trailing newline so that subsequent calls to print[]
will continue on the same line. Classic examples include updating the progress of a long-running operation or prompting the user for input. In the latter case, you want the user to type in the answer on the same line:
Are you sure you want to do this? [y/n] y
Many programming
languages expose functions similar to print[]
through their standard libraries, but they let you decide whether to add a newline or not. For example, in Java and C#, you have two distinct functions, while other languages require you to explicitly append \n
at the end of a string literal.
Here are a few examples of syntax in such languages:
Perl | print "hello world\n"
| ||||||||||||
C | printf["hello world\n"];
| ||||||||||||
C++ | std::cout file.txt
$ cat file.txt
This will appear on stdout
That’s called stream redirection. The standard error is similar to Some programs use different coloring to distinguish between messages printed to While both In Python, you can access all standard streams through the built-in >>>
As you can see, these predefined values resemble file-like objects with By default,
This will make your code immune to stream redirection at the operating system level, which might or might not be desired. For more information on working with files in Python, you can check out Reading and Writing Files in Python [Guide]. Note that
Instead of a real file existing somewhere in your file system, you can provide a fake one, which would reside in your computer’s memory. You’ll use this technique later for mocking >>>
If you got to this point, then you’re left with only one keyword argument in There’s a special syntax in Python 2 for replacing the default
Because strings and bytes are represented with the same
Although, there’s a problem with character encoding. The >>>
Notice how non-Latin characters must be escaped in both Unicode and string literals to avoid a syntax error. Take a look at this example:
Alternatively, you could specify source code encoding according to PEP 263 at the top of the file, but that wasn’t the best practice due to portability issues:
Your best bet is to encode the Unicode string just before printing it. You can do this manually:
However, a more convenient option is to use the built-in
It’ll take care of making appropriate conversions when you need to read or write files. Buffering |
Esc | non-printable escape character | \033
|
[
| opening square bracket | [
|
numeric code | one or more numbers separated with ;
| 0
|
character code | uppercase or lowercase letter | m
|
The numeric code can be one or more numbers separated with a semicolon, while the character code is just one letter. Their specific meaning is defined by the ANSI standard. For example, to reset all formatting, you would type one of the following commands, which use the code zero and the letter m
:
$ echo -e "\e[0m"
$ echo -e "\x1b[0m"
$ echo -e "\033[0m"
At the other end of the spectrum, you have compound code values. To set foreground and background with RGB channels, given that your terminal supports 24-bit depth, you could provide multiple numbers:
$ echo -e "\e[38;2;0;0;0m\e[48;2;255;255;255mBlack on white\e[0m"
It’s not just text color that you can set with the ANSI escape codes. You can, for example, clear and scroll the terminal window, change its background, move the cursor around, make the text blink or decorate it with an underline.
In Python, you’d probably write a helper function to allow for wrapping arbitrary codes into a sequence:
>>>
>>> def esc[code]:
... return f'\033[{code}m'
...
>>> print[esc['31;1;4'] + 'really' + esc[0] + ' important']
This would make the word really
appear in red, bold, and underlined font:
However, there are higher-level abstractions over ANSI escape codes, such as the mentioned colorama
library, as well as tools for building user interfaces in the console.
Building Console User Interfaces
While playing with ANSI escape codes is undeniably a ton of fun, in the real world you’d rather have more abstract building blocks to put together a user interface. There are a few libraries that provide such a high level of control over the terminal, but
curses
seems to be the most popular choice.
Primarily, it allows you to think in terms of independent graphical widgets instead of a blob of text. Besides, you get a lot of freedom in expressing your inner artist, because it’s really like painting a blank canvas. The library hides the complexities of having to deal with different terminals. Other than that, it has great support for keyboard events, which might be useful for writing video games.
How about making a retro snake game? Let’s create a Python snake simulator:
First, you
need to import the curses
module. Since it modifies the state of a running terminal, it’s important to handle errors and gracefully restore the previous state. You can do this manually, but the library comes with a convenient wrapper for your main function:
import curses
def main[screen]:
pass
if __name__ == '__main__':
curses.wrapper[main]
Note, the function must accept a reference to the screen object, also known as stdscr
, that you’ll use later for additional setup.
If you run this program now, you won’t see any effects, because it terminates immediately. However, you can add a small delay to have a sneak peek:
import time, curses
def main[screen]:
time.sleep[1]
if __name__ == '__main__':
curses.wrapper[main]
This time the screen went completely blank for a second, but the cursor was still blinking. To hide it, just call one of the configuration functions defined in the module:
import time, curses
def main[screen]:
curses.curs_set[0] # Hide the cursor
time.sleep[1]
if __name__ == '__main__':
curses.wrapper[main]
Let’s define the snake as a list of points in screen coordinates:
snake = [[0, i] for i in reversed[range[20]]]
The head of the snake is always the first element in the list, whereas the tail is the last one. The initial shape of the snake is horizontal, starting from the top-left corner of the screen and facing to the right. While its y-coordinate stays at zero, its x-coordinate decreases from head to tail.
To draw the snake, you’ll start with the head and then follow with the remaining segments. Each segment carries [y, x]
coordinates, so you can unpack them:
# Draw the snake
screen.addstr[*snake[0], '@']
for segment in snake[1:]:
screen.addstr[*segment, '*']
Again, if you run this code now, it won’t display anything, because you must explicitly refresh the screen afterward:
import time, curses
def main[screen]:
curses.curs_set[0] # Hide the cursor
snake = [[0, i] for i in reversed[range[20]]]
# Draw the snake
screen.addstr[*snake[0], '@']
for segment in snake[1:]:
screen.addstr[*segment, '*']
screen.refresh[]
time.sleep[1]
if __name__ == '__main__':
curses.wrapper[main]
You want to move the snake in one of four directions, which can be defined as vectors. Eventually, the direction will change in response to an arrow keystroke, so you may hook it up to the library’s key codes:
directions = {
curses.KEY_UP: [-1, 0],
curses.KEY_DOWN: [1, 0],
curses.KEY_LEFT: [0, -1],
curses.KEY_RIGHT: [0, 1],
}
direction = directions[curses.KEY_RIGHT]
How does a snake move? It turns out that only its head really moves to a new location, while all other segments shift towards it. In each step, almost all segments remain the same, except for the head and the tail. Assuming the snake isn’t growing, you can remove the tail and insert a new head at the beginning of the list:
# Move the snake
snake.pop[]
snake.insert[0, tuple[map[sum, zip[snake[0], direction]]]]
To get the new coordinates of the head, you need to add the direction vector to it. However, adding tuples in Python results in a bigger tuple instead of the algebraic sum of the corresponding vector components. One way to fix this is by using the built-in zip[]
, sum[]
, and
map[]
functions.
The direction will change on a keystroke, so you need to call .getch[]
to obtain the pressed key code. However, if the pressed key doesn’t correspond to the arrow keys defined earlier as dictionary keys, the direction won’t change:
# Change direction on arrow keystroke
direction = directions.get[screen.getch[], direction]
By default, however, .getch[]
is a blocking call that would prevent the snake from moving unless there was a keystroke. Therefore, you need to
make the call non-blocking by adding yet another configuration:
def main[screen]:
curses.curs_set[0] # Hide the cursor
screen.nodelay[True] # Don't block I/O calls
You’re almost done, but there’s just one last thing left. If you now loop this code, the snake will appear to be growing instead of moving. That’s because you have to erase the screen explicitly before each iteration.
Finally, this is all you need to play the snake game in Python:
import time, curses
def main[screen]:
curses.curs_set[0] # Hide the cursor
screen.nodelay[True] # Don't block I/O calls
directions = {
curses.KEY_UP: [-1, 0],
curses.KEY_DOWN: [1, 0],
curses.KEY_LEFT: [0, -1],
curses.KEY_RIGHT: [0, 1],
}
direction = directions[curses.KEY_RIGHT]
snake = [[0, i] for i in reversed[range[20]]]
while True:
screen.erase[]
# Draw the snake
screen.addstr[*snake[0], '@']
for segment in snake[1:]:
screen.addstr[*segment, '*']
# Move the snake
snake.pop[]
snake.insert[0, tuple[map[sum, zip[snake[0], direction]]]]
# Change direction on arrow keystroke
direction = directions.get[screen.getch[], direction]
screen.refresh[]
time.sleep[0.1]
if __name__ == '__main__':
curses.wrapper[main]
This is merely scratching the surface of the possibilities that the curses
module opens up. You
may use it for game development like this or more business-oriented applications.
Living It Up With Cool Animations
Not only can animations make the user interface more appealing to the eye, but they also improve the overall user experience. When you provide early feedback to the user, for example, they’ll know if your program’s still working or if it’s time to kill it.
To animate text in the terminal, you have to be able to freely move the cursor around. You can do this with one of the tools mentioned previously, that is ANSI escape codes or the curses
library. However, I’d like to show you an even simpler way.
If the animation can be constrained to a single line of text, then you might be interested in two special escape character sequences:
- Carriage
return:
\r
- Backspace:
\b
The first one moves the cursor to the beginning of the line, whereas the second one moves it only one character to the left. They both work in a non-destructive way without overwriting text that’s already been written.
Let’s take a look at a few examples.
You’ll often want to display some kind of a spinning wheel to indicate a work in progress without knowing exactly how much time’s left to finish:
Many command line tools use this trick while downloading data over the network. You can make a really simple stop motion animation from a sequence of characters that will cycle in a round-robin fashion:
from itertools import cycle
from time import sleep
for frame in cycle[r'-\|/-\|/']:
print['\r', frame, sep='', end='', flush=True]
sleep[0.2]
The loop gets the next character to print, then moves the cursor to the beginning of the line, and overwrites whatever there was before without adding a newline. You don’t want extra space between positional arguments, so separator argument must be blank. Also, notice the use of Python’s raw strings due to backslash characters present in the literal.
When you know the remaining time or task completion percentage, then you’re able to show an animated progress bar:
First, you need to calculate how many hashtags to display and how many blank spaces to insert. Next, you erase the line and build the bar from scratch:
from time import sleep
def progress[percent=0, width=30]:
left = width * percent // 100
right = width - left
print['\r[', '#' * left, ' ' * right, ']',
f' {percent:.0f}%',
sep='', end='', flush=True]
for i in range[101]:
progress[i]
sleep[0.1]
As before, each request for update repaints the entire line.
Making Sounds With print[]
If you’re old enough to remember computers with a PC speaker, then you must also remember their distinctive beep sound, often used to indicate hardware problems. They could barely make any more noises than that, yet video games seemed so much better with it.
Today you can still take advantage of this small loudspeaker, but chances are your laptop didn’t come with one. In such a case, you can enable terminal bell emulation in your shell, so that a system warning sound is played instead.
Go ahead and type this command to see if your terminal can play a sound:
This would normally print text, but the -e
flag enables the interpretation of backslash escapes. As you can see, there’s a dedicated escape sequence \a
, which stands for “alert”, that outputs a special bell character. Some terminals make a sound whenever they see it.
Similarly, you can print this character in Python. Perhaps in a loop to form some kind of melody. While it’s only a single note, you can still vary the length of pauses between consecutive instances. That seems like a perfect toy for Morse code playback!
The rules are the following:
- Letters are encoded with a sequence of dot [·] and dash [–] symbols.
- A dot is one unit of time.
- A dash is three units of time.
- Individual symbols in a letter are spaced one unit of time apart.
- Symbols of two adjacent letters are spaced three units of time apart.
- Symbols of two adjacent words are spaced seven units of time apart.
According to those rules, you could be “printing” an SOS signal indefinitely in the following way:
while True:
dot[]
symbol_space[]
dot[]
symbol_space[]
dot[]
letter_space[]
dash[]
symbol_space[]
dash[]
symbol_space[]
dash[]
letter_space[]
dot[]
symbol_space[]
dot[]
symbol_space[]
dot[]
word_space[]
In Python, you can implement it in merely ten lines of code:
from time import sleep
speed = 0.1
def signal[duration, symbol]:
sleep[duration]
print[symbol, end='', flush=True]
dot = lambda: signal[speed, '·\a']
dash = lambda: signal[3*speed, '−\a']
symbol_space = lambda: signal[speed, '']
letter_space = lambda: signal[3*speed, '']
word_space = lambda: signal[7*speed, ' ']
Maybe you could even take it one step further and make a command line tool for translating text into Morse code? Either way, I hope you’re having fun with this!
Mocking Python print[]
in Unit Tests
Nowadays, it’s expected that you ship code that meets high quality standards. If you aspire to become a professional, you must learn how to test your code.
Software testing is especially important in dynamically typed languages, such as Python, which don’t have a compiler to warn you about obvious mistakes. Defects can make their way to the production environment and remain dormant for a long time, until that one day when a branch of code finally gets executed.
Sure, you have linters, type checkers, and other tools for static code analysis to assist you. But they won’t tell you whether your program does what it’s supposed to do on the business level.
So, should you be testing print[]
? No. After all, it’s a built-in function that must have already gone through a comprehensive suite of tests. What you want
to test, though, is whether your code is calling print[]
at the right time with the expected parameters. That’s known as a behavior.
You can test behaviors by mocking real objects or functions. In this case, you want to mock print[]
to record and verify its invocations.
Mocking in Python can be done twofold. First, you can take the traditional path of statically-typed languages by employing dependency injection. This may sometimes require you to change the code under test, which isn’t always possible if the code is defined in an external library:
def download[url, log=print]:
log[f'Downloading {url}']
# ...
This is the same example I used in an earlier section to talk about function composition. It basically allows for substituting print[]
with a custom function of the same interface. To check if it prints the right message, you have to intercept it by injecting a mocked function:
>>>
>>> def mock_print[message]:
... mock_print.last_message = message
...
>>> download['resource', mock_print]
>>> assert 'Downloading resource' == mock_print.last_message
Calling this mock makes it save the last message in an attribute, which you can inspect later, for example in an assert
statement.
In a slightly alternative solution, instead of replacing the entire print[]
function with a custom wrapper, you could redirect the standard output to an in-memory file-like stream of characters:
>>>
>>> def download[url, stream=None]:
... print[f'Downloading {url}', file=stream]
... # ...
...
>>> import io
>>> memory_buffer = io.StringIO[]
>>> download['app.js', memory_buffer]
>>> download['style.css', memory_buffer]
>>> memory_buffer.getvalue[]
'Downloading app.js\nDownloading style.css\n'
This time the function explicitly calls print[]
, but it exposes its file
parameter to the outside world.
However, a more Pythonic way of mocking objects takes advantage of the built-in mock
module, which uses a technique called monkey patching. This derogatory name stems from it being a “dirty hack” that you can easily shoot
yourself in the foot with. It’s less elegant than dependency injection but definitely quick and convenient.
What monkey patching does is alter implementation dynamically at runtime. Such a change is visible globally, so it may have unwanted consequences. In practice, however, patching only affects the code for the duration of test execution.
To mock print[]
in a test case, you’ll typically use the @patch
decorator and specify a target for patching by referring to it with a fully qualified name, that is including the module name:
from unittest.mock import patch
@patch['builtins.print']
def test_print[mock_print]:
print['not a real print']
mock_print.assert_called_with['not a real print']
This will automatically create the mock for you and inject it to the test function. However, you need to declare that your test function accepts a mock now. The underlying mock object has lots of useful methods and attributes for verifying behavior.
Did you notice anything peculiar about that code snippet?
Despite injecting a mock to the function, you’re not calling it directly, although you could. That injected mock is only used to make assertions afterward and maybe to prepare the context before running the test.
In real life, mocking helps to isolate the code under test by removing dependencies such as a database connection. You rarely call mocks in a test, because that doesn’t make much sense. Rather, it’s other pieces of code that call your mock indirectly without knowing it.
Here’s what that means:
from unittest.mock import patch
def greet[name]:
print[f'Hello, {name}!']
@patch['builtins.print']
def test_greet[mock_print]:
greet['John']
mock_print.assert_called_with['Hello, John!']
The code under test is a function that prints a greeting. Even though it’s a fairly simple function, you can’t test it easily because it doesn’t return a value. It has a side-effect.
To eliminate that side-effect, you need to mock the dependency out. Patching lets you avoid making changes to the original function, which can remain agnostic about print[]
. It thinks it’s calling print[]
, but
in reality, it’s calling a mock you’re in total control of.
There are many reasons for testing software. One of them is looking for bugs. When you write tests, you often want to get rid of the print[]
function, for example, by mocking it away. Paradoxically, however, that same function can help you find bugs during a related process of debugging you’ll read about in the next section.
You can’t monkey patch the print
statement in Python 2, nor can you inject it as a dependency. However, you have a few other options:
- Use stream redirection.
- Patch the standard output defined in the
sys
module. - Import
print[]
from the__future__
module.
Let’s examine them one by one.
Stream redirection is almost identical to the example you saw earlier:
>>>
>>> def download[url, stream=None]:
... print >> stream, 'Downloading %s' % url
... # ...
...
>>> from StringIO import StringIO
>>> memory_buffer = StringIO[]
>>> download['app.js', memory_buffer]
>>> download['style.css', memory_buffer]
>>> memory_buffer.getvalue[]
'Downloading app.js\nDownloading style.css\n'
There are only two differences.
First, the syntax for stream redirection uses chevron [>>
] instead of the file
argument. The other difference is where StringIO
is defined. You can import it from a similarly named StringIO
module, or cStringIO
for a faster implementation.
Patching the standard output from the sys
module is exactly what it sounds like, but you need to be aware of a few gotchas:
from mock import patch, call
def greet[name]:
print 'Hello, %s!' % name
@patch['sys.stdout']
def test_greet[mock_stdout]:
greet['John']
mock_stdout.write.assert_has_calls[[
call['Hello, John!'],
call['\n']
]]
First of all, remember to install the mock
module as it wasn’t available in the standard
library in Python 2.
Secondly, the print
statement calls the underlying .write[]
method on the mocked object instead of calling the object itself. That’s why you’ll run assertions against mock_stdout.write
.
Finally, a single print
statement doesn’t always correspond to a single call to sys.stdout.write[]
. In fact, you’ll see the newline character written separately.
The last option you have is importing print[]
from future
and patching it:
from __future__ import print_function
from mock import patch
def greet[name]:
print['Hello, %s!' % name]
@patch['__builtin__.print']
def test_greet[mock_print]:
greet['John']
mock_print.assert_called_with['Hello, John!']
Again, it’s nearly
identical to Python 3, but the print[]
function is defined in the __builtin__
module rather than builtins
.
print[]
Debugging
In this section, you’ll take a look at the available tools for debugging in Python, starting from a humble print[]
function, through the logging
module, to a fully fledged debugger. After reading it, you’ll
be able to make an educated decision about which of them is the most suitable in a given situation.
Tracing
Also known as print debugging or caveman debugging, it’s the most basic form of debugging. While a little bit old-fashioned, it’s still powerful and has its uses.
The idea is to follow the path of program execution until it stops abruptly, or gives incorrect results, to identify the exact instruction with a problem. You do that by inserting print statements with words that stand out in carefully chosen places.
Take a look at this example, which manifests a rounding error:
>>>
>>> def average[numbers]:
... print['debug1:', numbers]
... if len[numbers] > 0:
... print['debug2:', sum[numbers]]
... return sum[numbers] / len[numbers]
...
>>> 0.1 == average[3*[0.1]]
debug1: [0.1, 0.1, 0.1]
debug2: 0.30000000000000004
False
As you can see, the function doesn’t return the expected value of 0.1
, but now you know it’s because the sum is a little off.
Tracing the state of variables at different steps of the algorithm can give you a hint where the issue is.
In this case, the problem lies in how floating point numbers are represented in computer memory. Remember that numbers are stored in binary form. Decimal value of 0.1
turns out to have an infinite binary representation, which gets rounded.
For more information on rounding numbers in Python, you can check out How to Round Numbers in Python.
This method is simple and intuitive and will work in pretty much every programming language out there. Not to mention, it’s a great exercise in the learning process.
On the other hand, once you master more advanced techniques, it’s hard to go back, because they allow you to find bugs much quicker. Tracing is a laborious manual process, which can let even more
errors slip through. The build and deploy cycle takes time. Afterward, you need to remember to meticulously remove all the print[]
calls you made without accidentally touching the genuine ones.
Besides, it requires you to make changes in the code, which isn’t always possible. Maybe you’re debugging an application running in a remote web server or want to diagnose a problem in a post-mortem fashion. Sometimes you simply don’t have access to the standard output.
That’s precisely where logging shines.
Logging
Let’s pretend for a minute that you’re running an e-commerce website. One day, an angry customer makes a phone call complaining about a failed transaction and saying he lost his money. He claims to have tried purchasing a few items, but in the end, there was some cryptic error that prevented him from finishing that order. Yet, when he checked his bank account, the money was gone.
You apologize sincerely and make a refund, but also don’t want this to happen again in the future. How do you debug that? If only you had some trace of what happened, ideally in the form of a chronological list of events with their context.
Whenever you find yourself doing print debugging, consider turning it into permanent log messages. This may help in situations like this, when you need to analyze a problem after it happened, in an environment that you don’t have access to.
There are sophisticated tools for log aggregation and searching, but at the most basic level, you can think of logs as text files. Each line conveys detailed information about an event in your system. Usually, it won’t contain personally identifying information, though, in some cases, it may be mandated by law.
Here’s a breakdown of a typical log record:
[2019-06-14 15:18:34,517][DEBUG][root][MainThread] Customer[id=123] logged out
As you can see, it has a structured form. Apart from a descriptive message, there are a few customizable fields, which provide the context of an event. Here, you have the exact date and time, the log level, the logger name, and the thread name.
Log levels allow you to filter messages quickly to reduce noise. If you’re looking for an error, you don’t want to see all the warnings or debug messages, for example. It’s trivial to disable or enable messages at certain log levels through the configuration, without even touching the code.
With logging, you can keep your debug messages separate from the standard output. All the log messages go to the standard error stream by default, which can conveniently show up in different colors. However, you can redirect log messages to separate files, even for individual modules!
Quite commonly, misconfigured logging can lead to running out of space on the server’s disk. To prevent that, you may set up log rotation, which will keep the log files for a specified duration, such as one week, or once they hit a certain size. Nevertheless, it’s always a good practice to archive older logs. Some regulations enforce that customer data be kept for as long as five years!
Compared to other programming languages, logging in Python is simpler, because the logging
module is bundled with the standard library. You
just import and configure it in as little as two lines of code:
import logging
logging.basicConfig[level=logging.DEBUG]
You can call functions defined at the module level, which are hooked to the root logger, but more the common practice is to obtain a dedicated logger for each of your source files:
logging.debug['hello'] # Module-level function
logger = logging.getLogger[__name__]
logger.debug['hello'] # Logger's method
The advantage of using custom loggers is more fine-grain control. They’re usually named after the module they were defined in through the __name__
variable.
One last reason to switch
from the print[]
function to logging is thread safety. In the upcoming section, you’ll see that the former doesn’t play well with multiple threads of execution.
Debugging
The truth is that neither tracing nor logging can be considered real debugging. To do actual debugging, you need a debugger tool, which allows you to do the following:
- Step through the code interactively.
- Set breakpoints, including conditional breakpoints.
- Introspect variables in memory.
- Evaluate custom expressions at runtime.
A crude debugger that runs in the terminal, unsurprisingly named pdb
for “The Python Debugger,” is distributed as part of the standard library. This makes it always available, so it may be your only choice for performing remote debugging. Perhaps that’s a good reason to get familiar
with it.
However, it doesn’t come with a graphical interface, so using pdb
may be a bit tricky. If you can’t edit the code, you have to run it as a module and pass your script’s location:
$ python -m pdb my_script.py
Otherwise, you can set up a breakpoint directly in the code, which will pause the execution of your script and drop you into the debugger. The old way of doing this required two steps:
>>>
>>> import pdb
>>> pdb.set_trace[]
--Return--
> [1][]->None
[Pdb]
This shows up an interactive prompt, which might look intimidating at first. However, you can still type native Python at this point to examine or modify the state of local variables. Apart from that, there’s really only a handful of debugger-specific commands that you want to use for stepping through the code.
Since Python 3.7, you can also call the built-in breakpoint[]
function, which does the same thing, but in a
more compact way and with some additional bells and whistles:
def average[numbers]:
if len[numbers] > 0:
breakpoint[] # Python 3.7+
return sum[numbers] / len[numbers]
You’re probably going to use a visual debugger integrated with a code editor for the most part. PyCharm has an excellent debugger, which boasts high performance, but you’ll find plenty of alternative IDEs with debuggers, both paid and free of charge.
Debugging isn’t the proverbial silver bullet. Sometimes logging or tracing will be a better solution. For example, defects that are hard to reproduce, such as race conditions, often result from temporal coupling. When you stop at a breakpoint, that little pause in program execution may mask the problem. It’s kind of like the Heisenberg principle: you can’t measure and observe a bug at the same time.
These methods aren’t mutually exclusive. They complement each other.
Thread-Safe Printing
I
briefly touched upon the thread safety issue before, recommending logging
over the print[]
function. If you’re still reading this, then you must be comfortable with the concept of threads.
Thread safety means that a piece of code can be safely shared between multiple threads of execution. The simplest strategy for ensuring thread-safety is by sharing immutable objects only. If threads can’t modify an object’s state, then there’s no risk of breaking its consistency.
Another method takes advantage of local memory, which makes each thread receive its own copy of the same object. That way, other threads can’t see the changes made to it in the current thread.
But that doesn’t solve the problem, does it? You often want your threads to cooperate by being able to mutate a shared resource. The most common way of synchronizing concurrent access to such a resource is by locking it. This gives exclusive write access to one or sometimes a few threads at a time.
However, locking is expensive and reduces concurrent throughput, so other means for controlling access have been invented, such as atomic variables or the compare-and-swap algorithm.
Printing isn’t thread-safe in Python. The print[]
function holds a reference to the standard output, which is a shared global variable. In theory, because
there’s no locking, a context switch could happen during a call to sys.stdout.write[]
, intertwining bits of text from multiple print[]
calls.
In practice, however, that doesn’t happen. No matter how hard you try, writing to the standard output seems to be atomic. The only problem that you may sometimes observe is with messed up line breaks:
[Thread-3 A][Thread-2 A][Thread-1 A]
[Thread-3 B][Thread-1 B]
[Thread-1 C][Thread-3 C]
[Thread-2 B]
[Thread-2 C]
To simulate this, you can increase the likelihood of a context switch by making the underlying .write[]
method go to sleep for a random
amount of time. How? By mocking it, which you already know about from an earlier section:
import sys
from time import sleep
from random import random
from threading import current_thread, Thread
from unittest.mock import patch
write = sys.stdout.write
def slow_write[text]:
sleep[random[]]
write[text]
def task[]:
thread_name = current_thread[].name
for letter in 'ABC':
print[f'[{thread_name} {letter}]']
with patch['sys.stdout'] as mock_stdout:
mock_stdout.write = slow_write
for _ in range[3]:
Thread[target=task].start[]
First, you need to store the original .write[]
method in a variable, which you’ll delegate to later. Then you provide your fake implementation, which will take up to one second to execute. Each thread will make a few print[]
calls with its name and a letter: A, B, and C.
If you read the mocking section before, then you may already have an idea of why printing misbehaves like
that. Nonetheless, to make it crystal clear, you can capture values fed into your slow_write[]
function. You’ll notice that you get a slightly different sequence each time:
[
'[Thread-3 A]',
'[Thread-2 A]',
'[Thread-1 A]',
'\n',
'\n',
'[Thread-3 B]',
[...]
]
Even though sys.stdout.write[]
itself is an atomic operation, a single call to the print[]
function can yield more than one write. For example, line breaks are written separately from the rest of the text, and context switching takes place between those writes.
You can make the newline character become an integral part of the message by handling it manually:
print[f'[{thread_name} {letter}]\n', end='']
This will fix the output:
[Thread-2 A]
[Thread-1 A]
[Thread-3 A]
[Thread-1 B]
[Thread-3 B]
[Thread-2 B]
[Thread-1 C]
[Thread-2 C]
[Thread-3 C]
Notice, however, that the print[]
function still keeps making a separate call for the empty suffix, which translates to useless sys.stdout.write['']
instruction:
[
'[Thread-2 A]\n',
'[Thread-1 A]\n',
'[Thread-3 A]\n',
'',
'',
'',
'[Thread-1 B]\n',
[...]
]
A truly thread-safe version of the print[]
function could look like this:
import threading
lock = threading.Lock[]
def thread_safe_print[*args, **kwargs]:
with lock:
print[*args, **kwargs]
You can put that function in a module and import it elsewhere:
from thread_safe_print import thread_safe_print
def task[]:
thread_name = current_thread[].name
for letter in 'ABC':
thread_safe_print[f'[{thread_name} {letter}]']
Now,
despite making two writes per each print[]
request, only one thread is allowed to interact with the stream, while the rest must wait:
[
# Lock acquired by Thread-3
'[Thread-3 A]',
'\n',
# Lock released by Thread-3
# Lock acquired by Thread-1
'[Thread-1 B]',
'\n',
# Lock released by Thread-1
[...]
]
I added comments to indicate how the lock is limiting access to the shared resource.
Conversely, the logging
module is thread-safe by design, which is reflected by its ability to display thread names in the formatted message:
>>>
>>> import logging
>>> logging.basicConfig[format='%[threadName]s %[message]s']
>>> logging.error['hello']
MainThread hello
It’s another
reason why you might not want to use the print[]
function all the time.
Python Print Counterparts
By now, you know a lot of what there is to know about print[]
! The subject, however, wouldn’t be complete without talking about its counterparts a little bit. While print[]
is about the output, there are functions and
libraries for the input.
Built-In
Python comes with a built-in function for accepting input from the user, predictably called input[]
. It accepts data from the standard input stream, which is usually the keyboard:
>>>
>>> name = input['Enter your name: ']
Enter your name: jdoe
>>> print[name]
jdoe
The function always returns a string, so you might need to parse it accordingly:
try:
age = int[input['How old are you? ']]
except ValueError:
pass
The prompt parameter is completely optional, so nothing will show if you skip it, but the function will still work:
>>>
>>> x = input[]
hello world
>>> print[x]
hello world
Nevertheless, throwing in a descriptive call to action makes the user experience so much better.
Asking the user for a password with input[]
is a bad idea because it’ll show up in plaintext as they’re typing it. In this case,
you should be using the getpass[]
function instead, which masks typed characters. This function is defined in a module under the same name, which is also available in the standard library:
>>>
>>> from getpass import getpass
>>> password = getpass[]
Password:
>>> print[password]
s3cret
The getpass
module has another function for getting the user’s name from an environment variable:
>>>
>>> from getpass import getuser
>>> getuser[]
'jdoe'
Python’s built-in functions for handling the standard input are quite limited. At the same time, there are plenty of third-party packages, which offer much more sophisticated tools.
Third-Party
There are external Python packages out there that allow for building complex graphical interfaces specifically to collect data from the user. Some of their features include:
- Advanced formatting and styling
- Automated parsing, validation, and sanitization of user data
- A declarative style of defining layouts
- Interactive autocompletion
- Mouse support
- Predefined widgets such as checklists or menus
- Searchable history of typed commands
- Syntax highlighting
Demonstrating such tools is outside of the scope of this article, but you may want to try them out. I personally got to know about some of those through the Python Bytes Podcast. Here they are:
bullet
cooked-input
prompt_toolkit
questionnaire
Nonetheless, it’s worth mentioning a command line tool called rlwrap
that adds powerful line editing capabilities to your Python scripts for free. You don’t have to do anything for it to work!
Let’s assume you wrote a command-line interface that understands three instructions, including one for adding numbers:
print['Type "help", "exit", "add a [b [c ...]]"']
while True:
command, *arguments = input['~ '].split[' ']
if len[command] > 0:
if command.lower[] == 'exit':
break
elif command.lower[] == 'help':
print['This is help.']
elif command.lower[] == 'add':
print[sum[map[int, arguments]]]
else:
print['Unknown command']
At first glance, it seems like a typical prompt when you run it:
$ python calculator.py
Type "help", "exit", "add a [b [c ...]]"
~ add 1 2 3 4
10
~ aad 2 3
Unknown command
~ exit
$
But as soon as you make a mistake and want to fix it, you’ll see that none of the function keys work as expected. Hitting the Left arrow, for example, results in this instead of moving the cursor back:
$ python calculator.py
Type "help", "exit", "add a [b [c ...]]"
~ aad^[[D
Now, you can wrap the same script with the rlwrap
command. Not only will you get the arrow keys working, but you’ll also be able to search through the persistent history of your custom commands, use autocompletion, and edit the
line with shortcuts:
$ rlwrap python calculator.py
Type "help", "exit", "add a [b [c ...]]"
[reverse-i-search]`a': add 1 2 3 4
Isn’t that great?
Conclusion
You’re now armed with a body of knowledge about the print[]
function in Python, as well as many surrounding topics. You have a deep understanding of what it is and how it works, involving all of its key elements. Numerous examples gave you insight into its
evolution from Python 2.
Apart from that, you learned how to:
- Avoid common mistakes with
print[]
in Python - Deal with newlines, character encodings and buffering
- Write text to files
- Mock the
print[]
function in unit tests - Build advanced user interfaces in the terminal
Now that you know all this, you can make interactive programs that communicate with users or produce data in popular file formats. You’re able to quickly diagnose problems in your code and protect yourself from them. Last but not least, you know how to implement the classic snake game.
If you’re still thirsty for more information, have questions, or simply would like to share your thoughts, then feel free to reach out in the comments section below.
Watch Now This tutorial has a related video course created by the Real Python team. Watch it together with the written tutorial to deepen your understanding: The Python print[] Function: Go Beyond the Basics