Python Template

This is a template for Python projects.

Environment Setup

Python

We use Python <version>, so make sure you have that installed.

You could use pyenv or pyenv-win (Windows is not recommended to install pyenv because it does not get native support) to manage your Python versions.

Install the Python version you want to use.

pyenv install <version>

Specify the version for this directory.

pyenv local <version>

To check your Python version, run python --version in your terminal.

python --version

Or you may need to specify the version explicitly if you didn't use pyenv or have multiple versions installed.

python3 --version

Virtual Environment

It is recommended to use a virtual environment to manage dependencies.

It is highly recommended to use the venv module that comes with Python.

To create a virtual environment in the .venv directory, run:

python -m venv .venv

Activate the environment.

# Linux, Bash, Mac OS X
source .venv/bin/activate
# Linux, Fish
source .venv/bin/activate.fish
# Linux, Csh
source .venv/bin/activate.csh
# Linux, PowerShell Core
.venv/bin/Activate.ps1
# Windows, cmd.exe
.venv\Scripts\activate.bat
# Windows, PowerShell
.venv\Scripts\Activate.ps1

Install the dependencies.

pip install -r requirements.txt

When you want to deactivate the virtual environment.

deactivate

Lint and Pre-commit

We use Flake8 and ISort for the coding style and guidelines. The style is then enforced by pre-commit.

Finish the environment setup above (especially installing the dependencies with pip) before using pre-commit.

Install and setup pre-commit.

pre-commit install

To run pre-commit manually (only scans staged files).

pre-commit run --all-files

Remember to stage files again if there are any changes made by the pre-commit hooks or by you.

git add .

VS Code Settings

You can add a workspace setting to automatically format your code on save using the black formatter.

You need to have the Black Formatter VS Code extension installed.

Bring up the command palette with Ctrl+Shift+P(Windows/Linux) / Cmd+Shift+P(Mac) and search for "Preferences: Open Workspace Settings (JSON)".

Then replace the content with the following:

{
    "editor.formatOnSave": true,
    "[python]": {
        "editor.defaultFormatter": "ms-python.black-formatter",
    },
    "black-formatter.args": [
        "--line-length",
        "79",
        "--preview",
        "--enable-unstable-feature",
        "string_processing"
    ],
}

Development

Clone Repository

First clone the repository.

git clone git@github.com:<username>/<repository>.git

Important: You may need to setup SSH keys for your GitHub account. See this guide for more information.

Checkout Branch

Then checkout the branch you want to work on.

git checkout <branch>

Committing Changes

Commit your changes to the branch you are working on.

git add .
git commit -m "Your commit message"

Make any changes and stage your files again according to the pre-commit hooks.

Pushing Changes

Set your branch's upstream branch to be the same branch on the remote repository on GitHub.

git push -u origin <branch>

After the first time you set the upstream branch, you can simply push without specifying the branch.

git push