Before we can go through our FastAPI journey, we need to configure a Python environment following the best practices and conventions Python developers use daily to run their projects. By the end of this chapter, you’ll be able to run Python projects and install third-party dependencies in a contained environment that won’t raise conflicts if you happen to work on another project that uses different versions of the Python language or dependencies.

In this chapter, we will cover the following main topics:

• Installing a Python distribution using pyenv
• Creating a Python virtual environment
• Installing Python packages with pip
• Installing the HTTPie command-line utility

Throughout this book, we’ll assume you have access to a Unix-based environment, such as a Linux distribution or macOS.

If you haven’t done so already, macOS users should install the Homebrew package (https://brew.sh), which helps a lot in installing command-line tools.

If you are a Windows user, you should enable Windows Subsystem for Linux (WSL) (https://docs.microsoft.com/windows/wsl/install-win10) and install a Linux distribution (such as Ubuntu) that will run alongside the Windows environment, which should give you access to all the required tools. There are currently two versions of WSL: WSL and WSL2. Depending on your Windows version, you might not be able to install the newest version. However, we do recommend using WSL2 if your Windows installation supports it.

Python is already bundled with most Unix environments. To ensure this is the case, you can run this command in a command line to show the Python version currently installed:

  $ python3 --version

The output version displayed will vary depending on your system. You may think that this is enough to get started, but it poses an important issue: you can’t choose the Python version for your project. Each Python version introduces new features and breaking changes. Thus, it’s important to be able to switch to a recent version for new projects to take advantage of the new features but still be able to run older projects that may not be compatible. This is why we need pyenv.

The pyenv tool (https://github.com/pyenv/pyenv) helps you manage and switch between multiple Python versions on your system. It allows you to set a default Python version for your whole system but also per project.

Beforehand, you need to install several build dependencies on your system to allow pyenv to compile Python on your system. The official documentation provides clear guidance on this (https://github.com/pyenv/pyenv/wiki#suggested- build-environment), but here are the commands you should run:

1. Install the build dependencies:
   • For macOS users, use the following:

     $ brew install openssl readline sqlite3 xz zlib tcl-tk

   • For Ubuntu users, use the following:

     $ sudo apt update; sudo apt install make build-essential libssl-dev zlib1g-dev \libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

Package managers

brew and apt are what are commonly known as package managers. Their role is to automate the installation and management of software on your system. Thus, you don’t have to worry about where to download them from and how to install and uninstall them. Those commands just tell the package manager to update its internal package index and then install the list of required packages.

2. Install pyenv:

   $ curl https://pyenv.run | bash

Tip for macOS users

If you are a macOS user, you can also install it with Homebrew: brew install pyenv.

3. This will download and execute an installation script that will handle everything for you. At the end, it’ll prompt you with some instructions to add some lines to your shell scripts so that pyenv is discovered properly by your shell:
   • If your shell is bash (the default for most Linux distributions and older versions of macOS), run the following commands:

     echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrcecho 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrcecho 'eval "$(pyenv init -)"' >> ~/.bashrc

   • If your shell is zsh (the default in the latest version of macOS), run the following commands:

     echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrcecho 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrcecho 'eval "$(pyenv init -)"' >> ~/.zshrc

What is a shell and how do I know the one I’m using?

The shell is the underlying program running when you start a command line. It’s responsible for interpreting and running your commands. Several variants of those programs have been developed over time, such as bash and zsh. Even though they have their differences, in particular the names of their configuration files, they are mostly inter-compatible. To find out which shell you’re using, you can run the echo $SHELL command.

4. Reload your shell configuration to apply those changes:

   $ exec "$SHELL"

5. If everything went well, you should now be able to invoke the pyenv tool:

   $ pyenv>>> pyenv 2.3.6>>> Usage: pyenv <command> [<args>]

6. We can now install the Python distribution of our choice. Even though FastAPI is compatible with Python 3.7 and later, we’ll use Python 3.10 throughout this book, which has a more mature handling of the asynchronous paradigm and type hinting. All the examples in the book were tested with this version but should work flawlessly with newer versions. Let’s install Python 3.10:

   $ pyenv install 3.10

This may take a few minutes since your system will have to compile Python from the source.

What about Python 3.11?

You might wonder why we use Python 3.10 here while Python 3.11 is already released and is available. At the time of writing, not every library we’ll use throughout this book officially supports this newest version. That’s why we prefer to stick with a more mature version. Don’t worry, though: what you’ll learn here will still be relevant to future versions of Python.

7. Finally, you can set the default Python version with the following command:

   $ pyenv global 3.10

This will tell your system to always use Python 3.10 by default unless specified otherwise in a specific project.

8. To make sure everything is in order, run the following command to check the Python version that is invoked by default:

   $ python --versionPython 3.10.8

Congratulations! You can now handle any version of Python on your system and switch it whenever you like!

Why does it show 3.10.8 instead of just 3.10?

The 3.10 version corresponds to a major version of Python. The Python core team regularly publishes major versions with new features, depreciations, and sometimes breaking changes. However, when a new major version is published, previous versions are not forgotten: they continue to receive bug and security fixes. It’s the purpose of the third part of the version.

It’s very possible by the time you’re reading this book that you’ve installed a more recent version of Python 3.10, such as 3.10.9. It just means that fixes have been published. You can find more information about how the Python life cycle works and how long the Python core team plans to support previous versions in this official document: https://devguide.python.org/versions/.

As for many programming languages of today, the power of Python comes from the vast ecosystem of third-party libraries, including FastAPI, of course, that help you build complex and high-quality software very quickly. The Python Package Index (PyPi) (https://pypi.org) is the public repository that hosts all those packages. This is the default repository that will be used by the built-in Python package manager, pip.

By default, when you install a third-party package with pip, it will install it for the whole system. This is different from some other languages, such as Node.js’ npm, which by default creates a local directory for the current project to install those dependencies. Obviously, this may cause issues when you work on several Python projects with dependencies having conflicting versions. It also makes it difficult to retrieve only the dependencies necessary to deploy a project properly on a server.

This is why Python developers generally use virtual environments. Basically, a virtual environment is just a directory in your project containing a copy of your Python installation and the dependencies of your project. This pattern is so common that the tool to create them is bundled with Python:

1. Create a directory that will contain your project:

   $ mkdir fastapi-data-science$ cd fastapi-data-science

Tip for Windows with WSL users

If you are on Windows with WSL, we recommend that you create your working folder on the Windows drive rather than the virtual filesystem of the Linux distribution. It’ll allow you to edit your source code files in Windows with your favorite text editor or integrated development environment (IDE) while running them in Linux.

To do this, you can access your C: drive in the Linux command line through /mnt/c. You can thus access your personal documents using the usual Windows path, for example, cd /mnt/c/Users/YourUsername/Documents.

2. You can now create a virtual environment:

   $ python -m venv venv

Basically, this command tells Python to run the venv package of the standard library to create a virtual environment in the venv directory. The name of this directory is a convention, but you can choose another name if you wish.

3. Once this is done, you have to activate this virtual environment. It’ll tell your shell session to use the Python interpreter and the dependencies in the local directory instead of the global ones. Run the following command:

   $ source venv/bin/activatee

After doing this, you may notice the prompt adds the name of the virtual environment:

(venv) $

Remember that the activation of this virtual environment is only available for the current session. If you close it or open other command prompts, you’ll have to activate it again. This is quite easy to forget, but it will become natural after some practice with Python.

You are now ready to install Python packages safely in your project!

As we said earlier, pip is the built-in Python package manager that will help us install third-party libraries.

A word on alternate package managers such as Poetry, Pipenv, and Conda

While exploring the Python community, you may hear about alternate package managers such as Poetry, Pipenv, and Conda. These managers were created to solve some issues posed by pip, especially around sub-dependencies management. While they are very good tools, we’ll see in Chapter 10, Deploying a FastAPI Project, that most cloud hosting platforms expect dependencies to be managed with the standard pip command. Therefore, they may not be the best choice for a FastAPI application.

To get started, let’s install FastAPI and Uvicorn:

(venv) $ pip install fastapi "uvicorn[standard]"

We’ll talk about it in later chapters, but Uvicorn is required to run a FastAPI project.

What does “standard” stand for after “uvicorn”?

You probably noticed the standard word inside square brackets just after uvicorn. Sometimes, some libraries have sub-dependencies that are not required to make the library work. Usually, they are needed for optional features or specific project requirements. The square brackets are here to indicate that we want to install the standard sub-dependencies of uvicorn.

To make sure the installation worked, we can open a Python interactive shell and try to import the fastapi package:

(venv) $ python>>> from fastapi import FastAPI

If it passes without any errors, congratulations, FastAPI is installed and ready to use!

Before getting to the heart of the topic, there is one last tool that we’ll install. FastAPI is, as you probably know, mainly about building REST APIs. Thus, we need a tool to make HTTP requests to our API. To do so, we have several options:

• FastAPI automatic documentation
• Postman: A GUI tool to perform HTTP requests
• cURL: The well-known and widely used command-line tool to perform network requests

Even if visual tools such as FastAPI automatic documentation and Postman are nice and easy to use, they sometimes lack some flexibility and may not be as productive as command-line tools. On the other hand, cURL is a very powerful tool with thousands of options, but it can be complex and verbose for testing simple REST APIs.

This is why we’ll introduce HTTPie, a command-line tool aimed at making HTTP requests. Compared to cURL, its syntax is much more approachable and easier to remember, so you can run complex requests off the top of your head. Besides, it comes with built-in JSON support and syntax highlighting. Since it’s a command-line interface (CLI) tool, we keep all the benefits of the command line: for example, we can directly pipe a JSON file and send it as the body of an HTTP request. It’s available to install from most package managers:

• macOS users can use this:

  $ brew install httpie

• Ubuntu users can use this:

  $ sudo apt-get update && sudo apt-get install httpie

Let’s see how to perform simple requests on a dummy API:

1. First, let’s retrieve the data:

   $ http GET https://603cca51f4333a0017b68509.mockapi.io/todos>>>HTTP/1.1 200 OKAccess-Control-Allow-Headers: X-Requested-With,Content-Type,Cache-Control,access_tokenAccess-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONSAccess-Control-Allow-Origin: *Connection: keep-aliveContent-Length: 58Content-Type: application/jsonDate: Tue, 08 Nov 2022 08:28:30 GMTEtag: "1631421347"Server: CowboyVary: Accept-EncodingVia: 1.1 vegurX-Powered-By: Express[    {        "id": "1",        "text": "Write the second edition of the book"    }]

As you can see, you can invoke HTTPie with the http command and simply type the HTTP method and the URL. It outputs both the HTTP headers and the JSON body in a clean and formatted way.

2. HTTPie also supports sending JSON data in a request body very quickly without having to format the JSON yourself:

   $ http -v POST https://603cca51f4333a0017b68509.mockapi.io/todos text="My new task"POST /todos HTTP/1.1Accept: application/json, */*;q=0.5Accept-Encoding: gzip, deflateConnection: keep-aliveContent-Length: 23Content-Type: application/jsonHost: 603cca51f4333a0017b68509.mockapi.ioUser-Agent: HTTPie/3.2.1{    "text": "My new task"}HTTP/1.1 201 CreatedAccess-Control-Allow-Headers: X-Requested-With,Content-Type,Cache-Control,access_tokenAccess-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONSAccess-Control-Allow-Origin: *Connection: keep-aliveContent-Length: 31Content-Type: application/jsonDate: Tue, 08 Nov 2022 08:30:10 GMTServer: CowboyVary: Accept-EncodingVia: 1.1 vegurX-Powered-By: Express{    "id": "2",    "text": "My new task"}

By simply typing the property name and its value separated by =, HTTPie will understand that it’s part of the request body in JSON. Notice here that we specified the -v option, which tells HTTPie to output the request before the response, which is very useful to check that we properly specified the request.

3. Finally, let’s see how we can specify request headers:

   $ http -v GET https://603cca51f4333a0017b68509.mockapi.io/todos "My-Header: My-Header-Value"GET /todos HTTP/1.1Accept: */*Accept-Encoding: gzip, deflateConnection: keep-aliveHost: 603cca51f4333a0017b68509.mockapi.ioMy-Header: My-Header-ValueUser-Agent: HTTPie/3.2.1HTTP/1.1 200 OKAccess-Control-Allow-Headers: X-Requested-With,Content-Type,Cache-Control,access_tokenAccess-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONSAccess-Control-Allow-Origin: *Connection: keep-aliveContent-Length: 90Content-Type: application/jsonDate: Tue, 08 Nov 2022 08:32:12 GMTEtag: "1849016139"Server: CowboyVary: Accept-EncodingVia: 1.1 vegurX-Powered-By: Express[    {        "id": "1",        "text": "Write the second edition of the book"    },    {        "id": "2",        "text": "My new task"    }]

That’s it! Just type your header name and value separated by a colon to tell HTTPie it’s a header.

You now have all the tools and setup required to confidently run the examples of this book and all your future Python projects. Understanding how to work with pyenv and virtual environments is a key skill to ensure everything goes smoothly when you switch to another project or when you have to work on somebody else’s code. You also learned how to install third-party Python libraries using pip. Finally, you saw how to use HTTPie, a simple and efficient way to run HTTP queries that will make you more productive while testing your REST APIs.

In the next chapter, we’ll highlight some of Python’s peculiarities as a programming language and grasp what it means to be Pythonic.