Setup for Python on Windows.md

Assumptions

This is my personal opinion about the entire process I recommend to people using Python on Windows, but it’s based on 8 years of experience in academia and working with UAVs.

• Use Python and Git primarily from VS Code
• Use Git command-line for cloning repositories with SSH authentication
• Use python virtual environment for every project

  • Every time you install a package in the system interpreter, a unicorn dies

  • Always put the virtual environment in venv folder

What’s not here

I tried Conda multiple times, and it’s great until it’s not, and then it’s worse than anything raw pip put me through. Almost every time I encountered an issue with building a package it was possible to change the version for one with binaries already provided on https://pypi.org/

GitHub Desktop, Git GUI, Gitkraken etc. The set of Git utilities in VS Code is enough for all of things I do regularly. For the occasional specific thing, I found it easiest to use the “native” tool that everyone else uses, so I can find answers online. So for anything advanced in the repository: git command line. For anything GitHub-specific, like Pull Requests, forks, repository settings etc. I use the web interface.

Prerequisites

• Install Git
  • Make sure to add to Path
• Install VS Code
  • Make sure you check the “Open with Code” options
• Install Python
  • Customize installation
  • Install for all users
  • Add to Path

VS Code setup

Start VS Code, and click on the icon with four blocks on the left (Extensions). Install the following extensions:

• “Python” from Microsoft
• “autopep8” from Microsoft
• “autoDocstring - Python Docstring Generator” from Nils Werner

From the top menu click on “File”, “Preferences”, “Settings”. In the search field type format on save. Check the “Editor: Format On Save” setting to true.

PowerShell setup

By default, Windows limits running scripts for safety of casual users. Open the PowerShell (or Terminal) as Administrator and run this command:

Set-ExecutionPolicy -ExecutionPolicy Unrestricted

Alias for venv activation

Open the script that is run every time to set up your powershell console for editing:

code $profile

Paste the following and save the file:

New-Alias av .\venv\Scripts\Activate.ps1

Git setup

Set up who you are in Git (preferably matching what you put in GitHub)

git config --global user.name "John Smith"
git config --global user.email "johnsmith@example.com"

Authentication with SSH needs short setup on every computer you want to use with GitHub, but then you don’t need to touch it on that PC. It will generate a cryptographic key pair (just like for digital signature). When asked about anything just accept defaults with Enter.

ssh-keygen -t ed25519

Show the contents of the public key pair, the output should begin with ssh-ed25519

type $home\.ssh\id_ed25519.pub

Copy these to clipboard. Log in to GitHub, open Settings and then find SSH Keys in the left. Add new key, paste what you got from the last command, and Save.

(Optional explanation)

The key pair is used like this:

• only you have the private key, but you can give the public key to anyone you want
• only you can sign what you send with the private key, and it can only be decoded with your public key
• this means that if GitHub got some encrypted data and it could be decrypted with the public key, it must have come from you

Repository setup

When you open the Terminal (or just PowerShell in Windows < 11), by default it will start in the C:\Users\yourname directory. Create a folder there, for example Repositories.

Then whenever you start the terminal, type cd rep and press Tab, the command should autocomplete to cd .\Repositories\, and then press Enter to go there. The prompt (part ending with > before you type) should change to show the new location.

Creating a new repository

Just accept to create README.md, it makes the next steps simpler, and you should have it anyway:

• https://www.makeareadme.com/ for reference what to put there
• Readme Driven Development - why it’s really a good idea to use it

Getting an existing repository

Open the repository page, and click the green “Code” button, and then click “SSH”. Copy the address displayed below (you can use the icon on the right). Open the terminal, go to your Repositories folder, and get something like this by pasting the address:

git clone git@github.com:yourusername/yourrepo.git

If this is the first time connecting to GitHub you might get asked about the remote host identity, accept. By default the repository will be downloaded (a.k.a. “cloned”) to a folder with its name. You can open it in VS Code without leaving the terminal like this - keep in mind you can use Tab to autocomplete the rest of the name also here.

code yourrepo

Setting up Python in a given repository

Create the virtual environment in the venv folder, wait a moment for it to complete. When VS Code asks you if you want to select it as the interpreter for the folder, click “Yes”

python -m venv venv

When you open the terminal, see if the prompt (the line before you type your command) starts with (venv). If it doesn’t, type av and press Enter - this will run .\venv\Scripts\Activate.ps1 for you because of the alias we set up earlier.

When you have the venv active and only then you can use pip command to install packages for this project, for example you should install formatter in every project:

pip install autopep8

When you have a .py file open in VS Code, make sure the section with Python version in bottom right part of the window is showing “venv”. If it doesn’t, click there (or run “Python: Select Interpreter”) command and choose the “venv”. This will ensure that the code analysis takes into account the packages you installed for the project, and will also activate the venv for you whenever you open a new terminal.

Gitignore file

In a properly set up repository, the venv folder should be gray in the explorer view on the left, indicating that Git will ignore changes inside it. If the folder is shown in the changes list in “Version Control” view, then you should add a line venv to the .gitignore file if it exists.

If the .gitignore file doesn’t exist, I strongly recommend https://www.toptal.com/developers/gitignore/ page. Put all the languages you use in the search field (in this case just Python), click “Create”, and then paste the entire page (Ctrl+A then Ctrl+C) into a .gitignore file you create in VS Code.

Installing packages from list

If there is a file called requirements.txt, someone has saved for you what the project needs to run. Make sure you have venv active, and run the following (just type up to req and use Tab-completion):

pip install -r requirements.txt

Saving used packages

When you know you have a set of packages that is needed for the project to run, you can run the following to put them into a file for everyone (as usual, don’t touch pip without (venv), save the unicorns).

pip freeze > requirements.txt

If the file already exists, it will be overwritten with everything you have installed and available with currently used pip. This is the main reason we use venv at all, to make sure you save what you need, no more no less.