A Program by Any Other Name

This chapter (and programming in general) uses a lot of terms that mean a program or some slight variation of the term. You could accurately call all of the following items a program. But there are subtle differences between what these names mean:

Program A complete piece of software, large or small, with instructions that a computer carries out.

Script A program that an interpreter runs from its source-code form rather than from a compiled, machine-code form. This is a very loose term. Python programs are often called scripts even though Python code can be compiled like other languages (as you’ll learn in “Compiling Python Programs with PyInstaller” on page 285).

Command A program that is often run from a text-based terminal and doesn’t have a graphical user interface (GUI). All configuration is done up front by specifying command line arguments before running the command (although interactive commands may sometimes interrupt their operation with an “Are you sure? Y/N” question for the user). Both dir and ls, explained in “The cd, pwd, dir, and ls Commands” on page 260, are examples of commands.

Shell script A single text file that conveniently runs several bundled terminal commands in one batch. This way, a user can run one shell script instead of manually entering several commands individually. On macOS and Linux, shell script files have a .sh file extension (or no extension), while Windows uses the term batch file for shell scripts with a .bat file extension.

Application A program that has a GUI and contains multiple related features. Excel and Firefox are examples of applications. Applications usually have several files that an installer program sets up on your computer (and that an uninstaller program can remove), rather than consisting of just a single executable file copied to a computer.

App A common name for mobile phone and tablet applications, but the term can be used for desktop applications as well.

Web app A program that runs on a web server, and which users interact with over the internet through a web browser.

You’re welcome to nitpick about precise definitions; these explanations should merely give you a general sense of the terms’ usage. If you want to become familiar with more terminology, my book Beyond the Basic Stuff with Python (No Starch Press, 2020) has additional definitions in its “Programming Jargon” chapter.

Using the Terminal

Until the 1990s, when Apple and Microsoft popularized computers with GUIs that could run multiple programs simultaneously, programs were launched from a command line interface (CLI, pronounced either as “see-el-eye” or as a word that rhymes with “fly”) and were often limited to text-based input and output. You might also hear CLIs called the command prompt, terminal, shell, or console. Software developers still make use of CLIs and often have several terminal windows open on their computers at any given time. While a text-based terminal might not have the icons, buttons, and graphics of a GUI, it’s an effective way to use a computer once you’ve learned several commands.

To open a terminal window, do the following:

• On Windows, click the Start button (or press the Windows key) and enter Command Prompt (or PowerShell or Terminal if you have them installed).
• On macOS, click the Spotlight icon in the upper-right corner (or press -spacebar) and enter Terminal.
• On Ubuntu Linux, press the Windows key to bring up Dash, and enter Terminal. Alternatively, use the keyboard shortcut CTRL-ALT-T.

Just as the interactive shell has a >>> prompt, the terminal will display a prompt for you to enter commands. On Windows, this will be the full path of the folder you are currently in, followed by an angle bracket (>):

C:\Users\al>your commands go here

On macOS, the prompt shows your username, your computer’s name, and the current working directory (with your home folder represented as ~ for short), followed by a percent sign (%):

al@Als-MacBook-Pro ~ % your commands go here

On Ubuntu Linux, the prompt is similar to the prompt in macOS, except it begins with the username and an @ sign:

al@al-VirtualBox:~$ your commands go here

While it’s easier to run programs from the Start menu (Windows) or Spotlight (macOS), it’s also possible to start them from the terminal. The Python interpreter itself is a program often run from the terminal.

In this chapter, we’ll assume the Python program you want to run is named yourScript.py and that it’s located in a Scripts folder under your home folder. You don’t need to open Mu to access the Python interactive shell. From a terminal window, you can enter python on Windows or python3 on macOS and Linux to start it. (You should then see its familiar >>> prompt.) To run one of your .py Python files from the terminal, enter its filepath after python or python3—either in its absolute form, like python C:\Users\al\Scripts\yourScript.py, or in its relative form, like python yourScript.py, if the current working directory is set to C:\Users\al\Scripts, the same folder that yourScript.py is in.

C:\Users\al>cd Desktop
C:\Users\al\Desktop>cd ..
C:\Users\al>cd C:\Windows\System32
C:\Windows\System32>

C:\Windows\System32>D:
D:\>cd backup
D:\backup>

C:\Users\al>dir
--snip--
08/26/2036  06:42 PM           171,304 _recursive-centaur.png
08/18/2035  11:25 AM             1,278 _viminfo
08/13/2035  12:58 AM    <DIR>          __pycache__
              77 File(s)     83,805,114 bytes
             108 Dir(s)  149,225,267,200 bytes free

al@al-virtual-machine:~$ echo $PATH
/home/al/.local/bin:/home/al/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/
usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin

export PATH=/Users/al/Scripts:$PATH

export PATH=/home/al/Scripts:$PATH

al@Als-MacBook-Pro ~ % which python3
/Library/Frameworks/Python.framework/Versions/3.13/bin/python3

C:\Users\al>where python
C:\Users\al\AppData\Local\Programs\Python\Python313\python.exe
C:\Users\al\AppData\Local\Programs\Python\Python312\python.exe

Virtual Environments

Say you have two Python programs, one that uses version 1.0 of a package and another that uses version 2.0 of that same package. Python can’t have two versions of the same package installed at the same time. If version 2.0 is not backward compatible with version 1.0, you’d be uninstalling one version and reinstalling the other each time you wanted to switch programs to run.

Python’s solution to this problem is virtual environments; separate installations of Python that have their own set of installed third-party packages. In general, each Python application you create needs its own virtual environment. But you can use one virtual environment for all your small scripts while learning to program. Python can create virtual environments with its built-in venv module. To create a virtual environment, cd to your Scripts folder and run python –m venv .venv (using python3 on macOS and Linux):

C:\Users\al>
C:\Users\al>cd Scripts
C:\Users\al\Scripts>python -m venv .venv

This creates the virtual environment’s files in a new folder named .venv. You can choose any folder name you want, but .venv is conventional. Files and folders whose names begin with a period are hidden, though you can follow the steps in this book’s introduction to make your operating system show them by default.

When you run python or python3 from the terminal, you’ll still run your original Python installation’s interpreter. To use the virtual environment’s Python version, you must activate it. Do so by running the C:\Users\al\Scripts\.venv\Scripts\activate.bat script on Windows:

C:\Users\al\Scripts>cd .venv\Scripts
C:\Users\al\Scripts\.venv\Scripts>activate.bat
(.venv) C:\Users\al\Scripts\.venv\Scripts>where python.exe
C:\Users\Al\Scripts\.venv\Scripts\python.exe
C:\Users\Al\AppData\Local\Programs\Python\Python313\python.exe
C:\Users\Al\AppData\Local\Programs\Python\Python312\python.exe

Running where python.exe after activating the virtual environment shows that running python from the terminal will run the Python interpreter in the .venv\Scripts folder and not the system Python (discussed shortly).

The equivalent script on macOS and Linux is ~/Scripts/.venv/bin/activate, but due to security permissions, you can’t directly run it. Instead, run the command source activate:

al@al-virtual-machine:~/Scripts$ cd .venv/bin
al@al-virtual-machine:~/Scripts/.venv/bin$ source activate
(.venv) al@al-virtual-machine:~/Scripts/.venv/bin$ which python3
/home/al/Scripts/.venv/bin/python3

Activation changes the PATH environment variable so that python or python3 runs the Python interpreter inside the .venv folder instead of the original one. It also changes your terminal prompt to include (.venv) so that you know the virtual environment is active. Running which python3 in the activated virtual environment shows that python3 runs the Python interpreter in the newly created .venv/bin folder. These changes apply to the current terminal window only; any existing or new terminal windows won’t have these environment variable or prompt changes. This fresh Python installation has only the default packages, and none of the packages you may have already installed in the original Python installation. You can confirm this by running python –m pip list to list the installed packages:

(.venv) C:\Users\al\Scripts\.venv\Scripts>python -m pip list
Package    Version
---------- -------
pip        23.0
setuptools 65.5.0

The standard practice is to create a virtual environment for each Python project you’re working on, since every project could have its own unique package dependencies. However, on Windows, we can be a bit more lax with the random small scripts we write in our Scripts folder: they can all share this one.

The macOS and Linux operating systems have their own programs that rely on the Python installation that comes with the operating system. Installing or updating packages for this original Python installation, called the system Python, has the slight chance of introducing incompatibilities that can cause these programs to fail. Running your own scripts with the system Python is fine; installing third-party packages to the system Python is slightly risky, but creating a virtual environment in your Scripts folder is a good precaution against installing incompatible packages.

Keep in mind that Mu has its own virtual environment. When you press F5 to run a script in Mu, it won’t have the packages you’ve installed to the Scripts\.venv folder’s virtual environment. As you advance in your programming ability, you may find it easier to have the Mu window open to edit your code while keeping a terminal window open to run it. You can quickly swap focus between windows with the ALT-TAB keyboard shortcut on Windows and Linux and -TAB on macOS.

To deactivate the virtual environment, run deactivate.bat (on Windows) or deactivate (on macOS and Linux) in the same folder as the activate script. You can also simply close the terminal window and open a new one. If you want to permanently delete the virtual environment along with its installed packages, just delete the .venv folder and its contents.

The following sections tell you how to deploy your script after you’ve set up the virtual environment and added your Scripts folder to PATH.

Installing Python Packages with pip

Python comes with a command line package manager program called pip (written in lowercase unless it’s at the start of a sentence). Pip is a recursive acronym for pip installs package. While Python’s standard library comes with modules such as sys, random, and os, there are also hundreds of thousands of third-party packages you can find on PyPI (pronounced “pie-pee-eye” and not “pie-pie”), the Python Package Index, at https://pypi.org. In Python, a package is a collection of Python code made available on PyPI, and a module is an individual .py file containing Python code. You install packages from PyPI that contain modules, and you import modules with an import statement.

While pip is a program on its own, it’s easier to run it through the Python interpreter by running python –m pip on Windows or python3 –m pip on macOS and Linux, rather than running the pip (on Windows) or pip3 (on macOS and Linux) program directly. This prevents errors in the rare cases where you have multiple Python installations, your PATH is misconfigured, and pip/pip3 is installing to a different Python interpreter than the one that runs when you enter python/python3.

To install a package from PyPI, enter the following into the terminal:

C:\Users\al>python –m pip install package_name

Remember to run python3 if on macOS or Linux instead of python for these various commands. Also note that you’ll need to run this from the terminal window, and not from the Python interactive shell.

To list all the packages you have installed along with their version numbers, run python –m pip list:

C:\Users\al>python -m pip list
Package                   Version     Editable project location
------------------------- ----------- -------------------------
altgraph                  0.17.3
argon2-cffi               21.3.0
argon2-cffi-bindings      21.2.0
async-generator           1.10
--snip--
wsproto                   1.2.0

You can also upgrade a package to the latest version on PyPI by running python –m pip install –U package_name, or install a particular version (say, 1.17.4) by running python –m pip install package_name==1.17.4.

To uninstall a package, run python –m pip uninstall package_name. You can find more information about pip by running python –m pip --help.

Self-Aware Python Programs

Python’s standard library doesn’t come with any modules that give your programs sentience. (Yet.) But several built-in variables can give your Python program useful information about itself, the operating system it’s on, and the Python interpreter running it. The Python interpreter sets these variables automatically.

The __file__ variable contains the .py file’s path as a string. For example, if I run a yourScript.py file in my home folder, it evaluates to 'C:\Users\al\yourScript.py'. Importing from pathlib import Path and calling Path(__file__) returns a Path object of this file. This information is useful if you need to locate files that exist in the Python program’s folder. The __file__ variable doesn’t exist when you run the Python interactive shell.

The sys.executable variable contains the full path and file of the Python interpreter program itself, and the sys.version variable contains the string that appears at the top of the interactive shell with version information about the Python interpreter.

The sys.version_info.major and sys.version_info.minor variables contain integers of the major and minor version numbers of the Python interpreter. On my laptop running Python version 3.13.1, these are 3 and 13, respectively. You can also pass sys.version_info to the list() function to obtain more specific information: list(sys.version_info) returns [3, 13, 1 'final', 0] on my laptop. Having the version information in this form is much easier to work with than trying to pull it out of the sys.version string.

The os.name variable contains the string 'nt' if running on Windows and 'posix' if running on macOS or Linux. This is useful if your Python script needs to run different code depending on what operating system it’s running on.

For more specific operating system identification, the sys.platform variable contains 'win32' on Windows, 'darwin' on macOS, and 'linux' on Linux.

If you need highly specific information about the OS version and type of CPU, the built-in platform module can retrieve this information. This module is documented online at https://docs.python.org/3/library/platform.html.

If you need to check whether a module is installed, put the import statement in a try block and catch the ModuleNotFoundError exception:

try:
    import nonexistentModule
except ModuleNotFoundError:
    print('This code runs if nonexistentModule was not found.')

If the module is necessary for your program to function, you can put a descriptive error message here and call sys.exit() to terminate the program. This will be more helpful to the user than a generic error message and traceback.

Text-Based Program Design

Before GUI-supporting operating systems were common, all programs used text to communicate with their user. This book focuses on creating small, useful programs rather than professional software applications, so the programs in this book use print() and input() through a command line interface rather than the windows, buttons, and graphics that a GUI provides.

Even when limited to text, however, software applications can still provide a user interface similar to modern GUIs. Figure 12-1 shows Norton Commander, an application for browsing the filesystem. These kinds of applications are retroactively called TUI (pronounced “two-ee”), or text-based user interface, applications.

Even if you aren’t a professional software developer, the advantage of text-based user interfaces is their simplicity. This section describes several design approaches your programs can take for their user interface.

>>> import bext
>>> bext.fg('red')
>>> print('This text is red.')
This text is red.
>>> bext.bg('blue')
>>> print('Red text on blue background is an ugly color scheme.')
Red text on blue background is an ugly color scheme.
>>> bext.fg('reset')
>>> bext.bg('reset')
>>> print('The text is normal again. Ah, much better.')
The text is normal again. Ah, much better.

import os
def clear():
    os.system('cls' if os.name == 'nt' else 'clear')

>>> import playsound3
>>> playsound3.playsound('hello.mp3')

A Short Program: Snowstorm

Let’s create a text-based snowstorm animation. Our program uses block text characters that fill out the top half-block, bottom half-block, and full block of a single character cell. These text characters are returned as strings by chr(9600), chr(9604), and chr(9608), respectively, and our program stores them in the constants TOP, BOTTOM, and FULL to make our code more readable.

Enter the following code into a file named snowstorm.py:

import os, random, time, sys

TOP    = chr(9600)  # Character 9600 is '▀'
BOTTOM = chr(9604)  # Character 9604 is '▄'
FULL   = chr(9608)  # Character 9608 is '█'

# Set the snowstorm density to the command line argument:
DENSITY = 4  # Default snow density is 4%
if len(sys.argv) > 1:
    DENSITY = int(sys.argv[1])

def clear():
    os.system('cls' if os.name == 'nt' else 'clear')

while True:
    clear()  # Clear the terminal window.

    # Loop over each row and column:
    for y in range(20):
        for x in range(40):
            if random.randint(0, 99) < DENSITY:
                # Print snow:
                print(random.choice([TOP, BOTTOM]), end='')
            else:
                # Print empty space:
                print(' ', end='')
        print()  # Print a newline.

    # Print the snow-covered ground:
    print(FULL * 40 + '\n' + FULL * 40)
    print('(Ctrl-C to stop.)')

    time.sleep(0.2)  # Pause for a bit.

First, the program imports the os, random, sys, and time modules. These modules are in the Python standard library and don’t require installing any third-party packages. Then, the program sets up the constants TOP, BOTTOM, and FULL with return values from chr(). The program uses these constant names because they’re easier to understand than the numbers 9600, 9604, and 9608.

The user can specify the density of the snowstorm by supplying a command line argument. If no command line argument is given, then sys.argv is set to ['snowstorm.py'] and the program leaves DENSITY at 4. But if the user were to run the program with, say, python snowstorm.py 20, then sys.argv would be set to ['snowstorm.py', '20'] and the program would update DENSITY to int(sys.argv[1]), or 20. The user would then be able to modify the behavior of the snowstorm without having to change the source code.

Inside an infinite while loop, this program first clears the screen with the cls/clear one-liner. Next, it uses two nested for loops to loop over every row and column in a 40×20 space on the terminal. (You can increase or decrease these numbers to change the size of your snowstorm.) At each row and column, the program prints a single character: either a randomly selected TOP or BOTTOM character to represent snow, or an empty space character. (Only four percent of the characters are not empty spaces by default.) These print() calls pass the end='' keyword argument so that print() doesn’t automatically print a newline character after each call. The program prints this newline itself by calling print() with no arguments after finishing a row.

After the nested for loops, the program prints two rows of 40 FULL characters to represent the ground, along with a reminder that the user can press CTRL-C to stop the program. All of this code produces one “frame” of the snowstorm animation, and time.sleep(0.2) briefly holds this frame before the execution loops back to clear the terminal and start the process all over again.

I chose the snowstorm animation because it’s fun rather than practical, like a terminal-based snow globe. A more useful application of this technique is creating a dashboard app: a program that runs in a terminal window you leave open to convey information at a glance. This program prints relevant information, then clears the screen and reprints updated information every second, minute, hour, or other interval.

Pop-up Message Boxes with PyMsgBox

While designing a full GUI for your program requires learning an entire code library such as Tkinter, wxPython, or PyQt, you can add small GUI message boxes to your program with the PyMsgBox package. This is a third-party package you can install by running pip install pymsgbox from the terminal. PyMsgBox lets you create dialogs using Tkinter, which comes with Python on Windows and macOS. On Ubuntu Linux, you must first install Tkinter by running sudo apt install python3-tk in the terminal. Appendix A has full instructions.

PyMsgBox has functions with names that mirror JavaScript’s message box functions:

pymsgbox.alert(text) Displays a text message until the user clicks OK, then returns the string 'OK'

pymsgbox.confirm(text) Displays a text message until the user clicks OK or Cancel, then returns 'OK' or 'Cancel'

pymsgbox.prompt(text) Displays a text message along with a text field, then returns the text the user entered as a string or None if they clicked Cancel

pymsgbox.password(text) Is the same as pymsgbox.prompt(), but the text the user enters is masked by asterisks

These functions won’t return until the user clicks OK, Cancel, or X (close). If your program requires only the occasional notification or user input, using PyMsgBox’s dialogs could be a suitable replacement for print() and input().

Deploying Python Programs

Once your Python program is finished, you might not want to run Mu, load the .py file, and then click the Run button each time you want to execute it. This section explains how to deploy your Python program so that you can run it in as few keystrokes as possible.

Be sure to follow the steps in “The PATH Environment Variable” on page 261 to add a Scripts folder to your PATH environment variable. Since my username is al, the path to this folder is C:\Users\al\Scripts on Windows, /Users/al/Scripts on macOS, and /home/al/Scripts on Linux. Also, you’ll need to set up a virtual environment for your Python scripts, as described next.

@call %HOMEDRIVE%%HOMEPATH%\Scripts\.venv\Scripts\activate.bat
@python %HOMEDRIVE%%HOMEPATH%\Scripts\yourScript.py %*
@pause
@deactivate

source ~/Scripts/.venv/bin/activate
python3 ~/Scripts/yourScript.py
deactivate

#!/usr/bin/env bash
source ~/Scripts/.venv/bin/activate
python3 ~/Scripts/yourScript.py
read -p "Press any key to continue..." -n1 –s
deactivate

[Desktop Entry]
Name=yourScript
Exec=gnome-terminal -- /home/al/Scripts/yourScript
Type=Application

A Short Program: Copying the Current Working Directory

While the pwd command on macOS and Linux will print the current working directory, it’s sometimes useful to copy this value to the clipboard for pasting elsewhere. For example, on Windows, I constantly find myself copying the current working directory from a terminal so that I can paste it in a Save File dialog to save a file in that same directory. Although I could use the mouse to select the current working directory from the Windows prompt to copy (or, on macOS and Linux, run the pwd command to print the working directory and select that text to copy), this requires several steps for what could be a one-step process.

My idea is to write a program named ccwd (for copy current working directory). First, I’ll enter where ccwd on Windows and which ccwd on macOS and Linux to make sure there isn’t currently a command with the same name, then maybe also do a quick internet search for ccwd to be sure. The name ccwd is short enough to type but also unique.

As an additional feature, say the terminal’s current working directory was set to C:\Users\al\Scripts, but what I wanted copied to the clipboard was C:\Users\al. I could just run the cd .. command, then ccwd, then cd Scripts to return to C:\Users\al\Scripts. But it would be easier if I could pass a relative filepath to ccwd as a command line argument. For example, ccwd .. would copy C:\Users\al to the clipboard when the current working directory was C:\Users\al\Scripts. You don’t have to specify this command line argument (the program defaults to the current working directory if none is given), but it’s available as a feature if the user wants it. These tiny improvements may seem trivial, but online retailers have “one-click buying” features on their websites because they know that slight improvements to convenience can have a major effect.

We’ll use the Pyperclip package to handle the clipboard, so be sure to install this into the Scripts folder’s virtual environment. Create a new file in Mu and enter the following content:

import pyperclip, os, sys
if len(sys.argv) > 1:
    os.chdir(sys.argv[1])
pyperclip.copy(os.getcwd())

Save this program as ccwd.py in the Scripts folder under your home folder.

The first line imports the modules the program needs. The second line checks if there are any command line arguments passed to the program. Remember that sys.argv is a list that always contains at least one string: the 'ccwd.py' name of the script. If it has more than one string, we know the user supplied command line arguments to the program. In that case, the third line changes the current working directory of the program. Note that every program has its own current working directory setting, and changing this setting with os.chdir() doesn’t change the current working directory of the terminal that ran the program. Finally, the fourth line copies the current working directory to the clipboard.

The program is finished, but to run it from a terminal, we’d have to enter the full path to it: something like python C:\Users\al\Scripts\ccwd.py. That’s a lot to type and defeats the purpose of having a quick and easy script to copy the current working directory to the clipboard. To improve this process, let’s go over the deployment steps for this program on each operating system.

@call %HOMEDRIVE%%HOMEPATH%\Scripts\.venv\Scripts\activate.bat
@python %HOMEDRIVE%%HOMEPATH%\Scripts\ccwd.py %*
@deactivate

C:\Users\al>ccwd
C:\Users\al>

source ~/Scripts/.venv/bin/activate
python3 ~/Scripts/ccwd.py
deactivate

al@Als-MacBook-Pro ~ % cd ~/Scripts
al@Als-MacBook-Pro Scripts % chmod u+x ccwd.command

al@Als-MacBook-Pro ~ % ccwd.command
al@Als-MacBook-Pro ~ %

#!/usr/bin/env bash
source ~/Scripts/.venv/bin/activate
python3 ~/Scripts/ccwd.py
deactivate

al@al-VirtualBox:~$ cd ~/Scripts
al@al-VirtualBox:~/Scripts$ chmod u+x ccwd

al@al-VirtualBox:~$ ccwd
al@al-VirtualBox:~$

A Short Program: Clipboard Recorder

Let’s say that part of your job is to copy the URLs for links on a web page and paste them into a spreadsheet. (In Chapter 13, you’ll learn how to scrape all the links for the HTML source of the page. But let’s say you only need to copy some of them, and a human must decide which ones on a case-by-case basis.) You could follow these steps:

  1.  Right-click a link in a web browser.

  2.  Select the Copy Link or Copy Link Address item from the context menu.

  3.  Switch to the spreadsheet app.

  4.  Press CTRL-V to paste the link.

  5.  Switch back to the web browser.

This is a boring task, especially if the page has dozens or hundreds of links. Let’s create a small clipboard-recording program to make it faster. We’ll deploy this program on our computer so that we can conveniently run it when needed. Our program will monitor the clipboard to see if new text has been copied to it, and if so, it will print it to the terminal screen. This way, we can convert our five-step process into a two-step process:

  1.  Right-click a link in a web browser.

  2.  Select the Copy Link or Copy Link Address item from the context menu.

Then, the user can just copy all the text from the clipboard recorder’s terminal window and paste it into the spreadsheet at once. Enter the following into the file editor and save it as cliprec.py:

import pyperclip, time

print('Recording clipboard... (Ctrl-C to stop)')
previous_content = ''
try:
    while True:
        content = pyperclip.paste()  # Get clipboard contents.
       
        if content != previous_content:
            # If it's different from the previous, print it:
            print(content)
            previous_content = content

        time.sleep(0.01)  # Pause to avoid hogging the CPU.
except KeyboardInterrupt:
    pass

Let’s look at each part of this program, starting with the beginning:

import pyperclip, time

print('Recording clipboard... (Ctrl-C to stop)')
previous_content = ''

This program copies and pastes text from the clipboard, so we’ll need to import the pyperclip module. We’ll also import the time module to use its sleep() function. The program displays a quick message to say that it is running and reminds the user that CTRL-C causes the program to stop. The program will know that the clipboard contents have changed by keeping track of what the contents were previously with a previous_content variable, which is initially set to a blank string.

try:
    while True:
        content = pyperclip.paste()  # Get clipboard contents.

The bulk of the program exists in an infinite while loop, which itself is inside a try block. When the user presses CTRL-C, Python raises a KeyboardInterrupt exception, causing the execution to move to the except block at the bottom of the source code.

This loop continuously monitors the contents of the clipboard and notes each time the user copies new text to it. Within the loop, the first step is to collect the text on the clipboard by calling pyperclip.paste().

        if content != previous_content:
            # If it's different from the previous, print it:
            print(content)
            previous_content = content

If the current content on the clipboard is different from the previous content, then the program prints the current content and updates previous_content to content. This sets up the loop for the next time the user copies new text to the clipboard.

        time.sleep(0.01)  # Pause to avoid hogging the CPU.

If the clipboard contents are the same as the previously obtained clipboard contents, we could have our program do nothing. However, this program can easily execute this loop tens of thousands of times a second, and it’s unlikely that the user will be updating the clipboard that frequently. (They’d probably wear out the CTRL and C keys on their keyboard if they tried.) To prevent the program from hogging the CPU by running this unproductive loop as fast as possible, we introduce a 0.01-second delay so that the loop checks for clipboard updates a mere 100 times a second.

except KeyboardInterrupt:
    pass

The last part of the program is the except clause, which uses Python’s pass statement. This statement literally does nothing, but Python is expecting at least one line in the block that follows the except statement. This is what the pass statement was created for. When the user presses CTRL-C, the execution moves to this except clause and proceeds to the end of the program, where it terminates.

With this app running, the user can copy several things without having to switch back and forth between apps. Small programs like this can make your workflow much easier, especially if you have to do this work every day. Now let’s deploy this program on each operating system.

@call %HOMEDRIVE%%HOMEPATH%\Scripts\.venv\Scripts\activate.bat
@python %HOMEDRIVE%%HOMEPATH%\Scripts\cliprec.py %*
@pause
@deactivate

source ~/Scripts/.venv/bin/activate
python3 ~/Scripts/cliprec.py
deactivate

al@Als-MacBook-Pro ~ % cd ~/Scripts
al@Als-MacBook-Pro Scripts % chmod u+x cliprec.command

#!/usr/bin/env bash
source ~/Scripts/.venv/bin/activate
python3 ~/Scripts/cliprec.py
read -p "Press any key to continue..." -n1 –s
deactivate

al@al-VirtualBox:~$ cd ~/Scripts
al@al-VirtualBox:~/Scripts$ chmod u+x cliprec

[Desktop Entry]
Name=Clipboard Recorder
Exec=gnome-terminal -- /home/al/cliprec
Type=Application

Compiling Python Programs with PyInstaller

Python is often called an interpreted language, though programming languages themselves are neither interpreted nor compiled. You can create an interpreter or compiler for any language. Instead, programs written in Python are mostly run by interpreters. But it’s also possible to create executable programs from Python code with the PyInstaller package, which generates executable programs you can run from the command line.

PyInstaller doesn’t compile Python programs into machine code per se; rather, it creates an executable program that contains a copy of the Python interpreter and your script. As such, these programs tend to be fairly large. Even a simple “Hello, world” program compiled with PyInstaller can be close to 8MB in size, literally a thousand times larger than a version written in assembly language. However, the benefit of compiling your Python program is that you can share your program with others who don’t have Python installed. You’d be able to send them one executable file.

You can install PyInstaller by running pip install pyinstaller. You must run PyInstaller on the operating system that you want the executable to run on. That is, if you’re on Windows, PyInstaller can create a Windows executable program but not a macOS or Linux program, and vice versa.

From the terminal, run the following command (using python3 instead of python on macOS and Linux) to compile a Python script named yourScript.py:

C:\Users\al>python -m PyInstaller --onefile yourScript.py
378 INFO: PyInstaller: X.X.X
378 INFO: Python: 3.XX.XX
392 INFO: Platform: Windows-XX-XX.X.XXXX
393 INFO: wrote C:\Users\al\Desktop\hello-test\hello.spec
399 INFO: UPX is not available.
--snip--
11940 INFO: Appending PKG archive to EXE
11950 INFO: Fixing EXE headers
13622 INFO: Building EXE from EXE-00.toc completed successfully.

Notice that you must enter PyInstaller with a capital P and capital I or else you’ll get a “No module named pyinstaller” error message. Also, note that the --onefile argument has two dashes.

After running PyInstaller, there will be a build folder (which you can delete) and a dist folder. The dist folder contains the executable program. You don’t need to create a virtual environment for it. You can then copy this program to other computers or send it as an email attachment. Keep in mind that, as a security precaution, many email providers may block emails that contain an executable program.

The instructions here work for basic Python programs. The online documentation at https://pyinstaller.org contains further details.

Summary

In this chapter, you learned how to take your programs out of the code editor and deploy them so that users can run them quickly and conveniently. You also learned more guidelines about how to design programs that have text-based user interfaces instead of more modern graphical ones. While a GUI is user friendly, TUIs are simpler to code. When you need to automate tasks for yourself, making your program look like a professional application isn’t worth the extra effort. You just need something that works.

That said, there are several ways you can design your program to be easy to use. Often, this involves the command line terminal, which many users aren’t familiar with. It may take a while to learn command line concepts such as navigating the file system with cd and dir/ls, the PATH environment variable, and command line arguments. But the terminal allows you to very quickly issue commands and run programs, especially after you finish writing the programs and deploy them.

This chapter also covered several third-party packages. The Bext package lets you add colorful text, position the cursor, and clear the screen. The PyMsgBox package creates GUI boxes for alerts or basic input without using the terminal window. Because you may one day run programs that require incompatible versions of the same package, it’s best to run scripts in separate virtual environments. You can create virtual environments with the venv module that comes with Python. Virtual environments are activated from the terminal, and can prevent you from breaking existing programs by giving you a separate place to install packages.

Finally, the PyInstaller package allows you to compile your .py files into executable programs. They may be several megabytes in size, but you can share these programs with co-workers who might not have Python (and the third-party packages your program uses) on their computer.

This chapter didn’t cover many programming language concepts; rather, it covered how to make your programs usable and convenient on a day-to-day basis. At this point, you know enough Python syntax to create basic programs (although there’s always more to learn!). In Part II of this book, you’ll explore several third-party packages that extend the capabilities of your Python programs.

Practice Questions

  1.  What command lists folder contents on Windows? What about on macOS and Linux?

  2.  What does the PATH environment variable contain?

  3.  What does the __file__ variable contain?

  4.  What command erases the text from the terminal window on Windows? What about on macOS and Linux?

  5.  How do you create a new virtual environment?

  6.  What command line argument should you pass to PyInstaller when compiling programs?

Practice Program: Make Your Programs Deployable

Make your existing programs easy to run by creating shell scripts in a PATH folder that executes them, or else compiling them with PyInstaller. Do this for the following projects:

• “Back Up a Folder into a ZIP File” from Chapter 11
• “Extract Contact Information from Large Documents” from Chapter 9
• “Add Bullets to Wiki Markup” from Chapter 8
• “Interactive Chessboard Simulator” from Chapter 7
• Any other programs you’ve created and want to easily launch or share with others