Developing with Python 3 on Windows

Chris Wahl · Posted on

I regularly spend time writing Python code on a Windows 10 system, such as writing AWS Lambda functions. During the initial setup process, I kept a fairly large Google Doc with a list of steps, links, and notes. That’s my standard process – whenever I encounter a new task, I start with documentation to record all of the steps and lessons learned. Otherwise, I would forget it all!

Python!

It’s been long enough now that I feel comfortable with this setup and have the bugs work out. I’m sharing here in case others are in a similar situation and are looking for setup examples.

This post is focused on:

  • Getting Python 3 installed on a Windows workstation
  • Setting up Visual Studio Code extensions and preferences
  • Installing and configuring global Python packages with pip
  • Adding a pre-commit hook to git that works well with Python
  • Establishing virtual environments for isolating projects

Installing Python 3

I prefer to use the installer found on the Python org page. The other option is to use the Microsoft Store. Both methods work, but the store installable does not behave as expected in all situations and occasionally has issues with loading packages.

If you already have a Microsoft Store version of Python installed, remove it. Check the \AppData\Local\Microsoft\WindowsApps\ path of your user directory to make sure the python executables are gone. Additionally, remove the previously mentioned path from the system environment variables. This avoids situations where references to Python are pointed towards the wrong installation.

I have Python installed in the root under \Python. The installer creates a versioned child folder, such as Python39 for version Python 3.9, within this location. Ensure the path to the Python child folder and the nested Scripts folders are populated in your path environment variable – this should be automatically handled for you.

Testing the Installation

At this point, I advise opening a Command or PowerShell window to test the installation. Using py or python should both function.

> py --version
Python 3.9.4
> python --version
Python 3.9.4

If you find yourself running the interpreter interactively, use quit() to close the session.

> py
Python 3.9.4 (tags/v3.9.4:1f2e308, Apr  6 2021, 13:40:21) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> quit()
>

Setup Visual Studio Code

My Integrated Development Environment (IDE) of choice is Visual Studio Code (VSCode). If you’re using IntelliJ IDEA or something else, follow their instructions for configuration. VSCode treats Python as a first-class citizen with the Pylance language server and numerous extensions.

The extensions I recommend installing are:

The Python extension will need a path to your Python interpreter. In my case, I supplied the C:\Python\Python39 path to the python.exe application.

To switch interpreters, type Python: Select Interpreter into the Command Palette and select a different path. The current interpreter will be shown in the bottom left corner (by default) when working with a Python file.

Finally, edit the editor.formatOnSave setting for VSCode and set the value to true. This will force the formatter of choice to invoke and “clean up” the code when saving. I use the autopep8 formatter, which is installed in the next section.

Setup pip Global Packages

Python’s package manager, pip, should already be installed as part of the Python installation. You can view a full list of available packages at the The Python Package Index (PyPI), which is also referred to as the “Cheese Shop.”

Pip can be tested by passing a module argument to py or invoking pip directly:

> py -m pip
Usage:
  C:\Python\Python39\python.exe -m pip <command> [options]
> pip
Usage:
  C:\Python\Python39\python.exe -m pip <command> [options]

The packages I recommend installing are:

Note: If you’re new to the concept of Python Enhancement Proposals (PEPs), give PEP 0 a read. Also, I highly advise reading PEP 20 which is The Zen of Python. Alternatively, run import this in Python.

I consider these my “root” packages that all projects will end up needing. Additional packages are installed into virtual environments.

Keeping pip Updated

Keep pip updated with this command:

> py -m pip install --upgrade pip
Requirement already satisfied: pip in c:\python\python39\lib\site-packages (21.1.1)

I do not update global packages unless I am addressing a security or capability concern.

Outdated packages can be verified with this command:

> pip list --outdated
Package    Version Latest Type
---------- ------- ------ -----
setuptools 49.2.1  56.2.0 wheel

Configure a Pre-Commit Hook for git

A pre-commit hook is a script run whenever a new git commit is created. I prefer to run lint, style, and format checks whenever I attempt to commit changes into my local git repository. Errors force the commit to fail, allowing me to intervene without having to revert or squash local changes.

The pre-commit package does a good job at this for Python. Install the package either globally or on a per environment basis.

Once done, create a YAML file named .pre-commit-config.yaml describing what you want done during when the pre-commit hook is invoked. I use the default hooks in addition to one that calls on autopep8 to check and fix my code.

An example is shown below:

# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
    -   id: check-yaml
    -   id: check-added-large-files
-   repo: https://github.com/pre-commit/mirrors-autopep8
    rev: 'v1.5.7'  # Use the sha / tag you want to point at
    hooks:
    -   id: autopep8

Once this YAML file is created, place it in the root of the repository and run pre-commit install --install-hooks to load the instructions into your hidden .git/hooks folder. A file named pre-commit (no extension) is created. Git will automatically seek out this file and execute the instructions whenever a commit begins but prior to performing the commit.

Below is an example commit in which I made a few changes to a Python script. The pre-commit hook is called to run 5 different tests. Because they are successful, the commit is executed.

> [main +0 ~1 -0 ~]> git commit -s -m "Wahl Network Example"
Trim Trailing Whitespace ............. Passed
Fix End of Files ..................... Passed
Check Yaml ........................... Passed
Check for added large files .......... Passed
autopep8 ............................. Passed
[main 259f30e] Wahl Network Example
 1 file changed, 2 insertions(+), 5 deletions(-)

Note: By default, autopep8 will automatically fix formatting errors and alter the file(s) prior to the commit without failing. I like this because it saves a step. 🙂

Setup a Virtual Environment

I use a virtual environment for each project on my developer workstation. This isolates each project and allows the freedom of installing any number of packages into each project during experimentation and development. Python3 comes bundled with a default virtual environment package called venv. If you need a package that can handle Python2, try virtualenv.

Use py -m venv C:\path\to\folder to create a new virtual environment at the path specified. This will create three new folders in the path: Include, Lib, and Scripts. These contain all of the virtual environment’s packages, configuration, and scripts necessary to activate or deactivate the environment.

Activation of the virtual environment requires running the Scripts\Activate.ps1 file.

The example below will generate a new virtual environment in the python-demo child folder and then activate the virtual environment. Note that the name of the virtual environment is prefixed in the console prompt to indicate the active environment.

> py -m venv .\python-demo\
> cd .\python-demo\
> .\Scripts\Activate
(python-demo) >

When finished, run the command Deactivate from any directory to exit the virtual environment.

Summary

Python is a fun language with a lot of solid support for Windows environments. This post showed you how to get Python 3 installed on a Windows workstation, setup Visual Studio Code extensions and preferences, and install and configuring global Python packages with pip. From there, we added a pre-commit hook to git that works well with Python and established a virtual environment for isolating projects.

Best of luck with your coding! ?✌