Anatomy of a virtual environment

This section relates to venv, which we have been using in this chapter, and will apply to virtualenv but not pipenv, which we listed as alternative virtual environment tools. The example is also specific to a Raspbian OS and is typical of a standard Unix-based OS. It's important to, at a minimum, understand the basic structure of a virtual environment deployment since we will be mixing our own Python programming code in with the files and folders that make up the virtual environment.

The light weight venv tool that comes with Python 3.3 and above is a subset of virtualenv.

Here is the folder structure of our virtual environment. Yep, its a screenshot from a Mac. That's so I could get everything on screen at once:

Figure 1.1 – Contents of a typical venv virtual environment folder

The following points explain the core subfolders that are found within our ~/pyiot/chapter01 folder after we ran python3 -m venv venv and installed packages using pip:

• The venv folder contains all of the Python virtual environment files. There is no real practical need to be touching anything under this folder manually—let the tools do that for you. Remember that the folder is named venv only because that's what we called it when it was created.

• The venv/bin folder contains the Python interpreter (in the venv case, there are symbolic links to the system interpreter) and other core Python tools, including pip.
• Underneath the venv/lib folder are all the sandboxed Python packages for the virtual environment, including the GPIOZero and PiGPIO packages we installed using pip install.
• Our Python source file, gpio_pkg_check.py, is in the top-level folder, ~/pyiot/chapter01; however, you can create sub-folders here to help to organize your code and non-code files.
• Finally, requirements.txt lives by convention in the top project folder.

The virtual environment folder venv does not actually need to be kept in the project folder; however, it's often convenient to have it there for activation with the activate command.

Your venv folder and anything below it should not be added to your source version control system, but you should add requirements.txt. As long as you have a current requirements.txt file, you can always recreate your virtual environment and reinstate packages to a known state.

It's important to understand that, as a Python developer, you will be mixing in your own programming code with files and folders that form part of the virtual environment system and that you should be pragmatic when selecting which files and folders are added to your version control system, should you be using one.

This last point is important since the virtual environment system can amount to many megabytes in size (and often many times larger than your program code) that does not need versioning (since we can always recreate the virtual environment as long as we have a requirements.txt file), plus it's host platform-specific (that is, there will be differences between Windows, Mac, and Linux), plus there will be differences between different virtual environment tools (for example, venv versus pipenv). As such, virtual environments are not generally portable in projects that involve many developers working on different computers.

Now that we have briefly explored the file and folders structure and the importance of understanding this structure, we will continue and look at alternative ways of running a script that is sandboxed to a virtual environment.