Python Tooling
Here are some of the tools commonly used in Python projects. The following tools assume you already have Xcode set up and Homebrew installed.
Table of Contents
Environment Management
pyenv
pyenv is a tool to easily manage and switch between multiple versions of Python. We highly recommend using this over manual installs or the system Python.
Installation
Install with Homebrew:
brew update && brew install pyenv
Add the following to your .bash_profile or .zshrc:
# pyenv
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
Restart your terminal or source your profile configuration:
source ~/.bash_profile || source ~/.zshrc
Usage
By default, pyenv is aware of your system’s installation of Python.
$ pyenv versions
* system
To add another Python version, first determine which new version you’d like to install. To see a list of available versions, run:
pyenv install --list
Available versions:
2.1.3
2.2.3
2.3.7
2.4.0
[...]
We recommend installing the latest production-ready version of Python, but keep in mind that your needs may vary from project to project.
If you don’t see the version of Python you’re looking for, upgrade pyenv through homebrew. This may take a while.
brew update
brew upgrade pyenv
Install the desired version by its full version number:
pyenv install 3.9.1
Once installed, you can switch your global Python version. This example changes the version of Python that runs when you use the python command from 2.7.16 (system default) to 3.9.1.
$ pyenv versions
* system
3.9.1
$ python --version
Python 2.7.16
$ pyenv global 3.9.1
$ pyenv versions
system
* 3.9.1
$ python --version
Python 3.9.1
Or set a local, per-directory Python version which pyenv will automatically load. This version of Python will always run when you are in this directory.
cd /path/to/project
pyenv local 3.9.1
pyenv version
3.9.1 (set by /path/to/project/.python-version)
# pyenv will create a .python-version file in the directory to save the setting.
# Add this file to your .gitignore
cat /path/to/project/.python-version
3.9.1
pyenv-virtualenv
Virtual environments in Python allow packages to be installed locally to a given environment. This allows you to have multiple environments, each with their own separate packages and specific package versions. We recommend that every Python project you work on have its own distinct virtual environment.
In addition to managing Python versions, pyenv can manage virtual environments for your projects through the pyenv-virtualenv plugin.
Installation
Install with Homebrew:
brew install pyenv-virtualenv
Add the following to your .bash_profile or .zshrc. Be sure to put it after pyenv setup from the previous section.
eval "$(pyenv virtualenv-init -)"
Restart your terminal or source your profile configuration:
source ~/.bash_profile || source ~/.zshrc
Usage
pyenv-virtualenv adds the virtualenv command to pyenv.
You can create a new virtual environment using your shell’s active Python version (check with pyenv version) like so:
pyenv virtualenv new-environment
Looking in links: /var/folders/7b/glwq27q53j55frqhwvr14kdm0000gn/T/tmpplk4mvq1
Requirement already satisfied: setuptools in ~/.pyenv/versions/3.9.1/envs/new-environment/lib/python3.9/site-packages (49.2.1)
Requirement already satisfied: pip in ~/.pyenv/versions/3.9.1/envs/new-environment/lib/python3.9/site-packages (20.2.3)
The new-environment virtualenv becomes available to pyenv:
pyenv versions
system
* 3.9.1 (set by ~/.pyenv/version)
3.9.1/envs/new-environment
new-environment
If you have other versions of Python installed, you can change the base virtual environment version by passing it as an argument:
pyenv virtualenv 3.7.3 new-3.7.3-env
Looking in links: /var/folders/7b/glwq27q53j55frqhwvr14kdm0000gn/T/tmpwgrquo4q
Requirement already satisfied: setuptools in ~/.pyenv/versions/3.7.3/envs/new-3.7.3-env/lib/python3.7/site-packages (40.8.0)
Requirement already satisfied: pip in ~/.pyenv/versions/3.7.3/envs/new-3.7.3-env/lib/python3.7/site-packages (19.0.3)
After creating a virtual environment, you can pin it to the local directory so pyenv will automatically activate it in the terminal:
cd /path/to/project
pyenv local new-environment
Linting and Code Style
Black
black is an auto-formatter for Python code. It helps us to think less about code style and focus on what really matters. Nearly all of our Python projects are using black, and if one isn’t, we highly recommend adding it.
Installation
Install black with pip. Projects that use black will include it in a requirements file.
pip install black
Usage
Run black through your command line by passing it a path as an argument:
black {source_file_or_directory}
Flake8
flake8 is a powerful tool that we use as our primary Python linter. It is a wrapper around three tools:
- pyflakes - An error checker
- pycodestyle - A style checker against Python’s official style guide PEP8
- mccabe - A complexity analyzer
With flake8, you get the benefits of all three for the price of one!
Installation
flake8 can be installed with pip:
pip install flake8
Usage
Run flake8 via the command line and give it a path to check:
flake8 {source_file_or_directory}
Check out the official documentation for flake8 for more usage details.
Configuration
flake8 can sometimes be a bit overzealous and will complain about code that is actually PEP8-compliant. This can lead to annoying errors, even when using a strict auto-formatter such as black. To avoid this, we recommend configuring flake8 to ignore W503 and E203. You can also specify a custom maximum line length (default 80) and exclude files and directories. These settings can be added to a setup.cfg file in your project’s main directory.
Example setup.cfg entry:
[flake8]
max-line-length = 99
ignore = W503, E203
exclude = env
Isort
isort is a Python utility / library to sort imports alphabetically, and automatically separated into sections and by type. It provides a command line utility, Python library and plugins for various editors to quickly sort all your imports. It requires Python 3.6+ to run but supports formatting Python 2 code too.
Installation
isort can be installed with pip:
pip install isort
Usage
Run isort through your command line by passing it a path as an argument:
isort {source_file_or_directory}
Configuration
By default, isort is incompatible with black, but the two can be configured to coexist peacefully.
Example config entries:
pyproject.toml (preferred)
[tool.isort]
profile = "black"
setup.cfg
[isort]
profile=black
Testing
Coverage
@INCOMPLETE