yannickperrenet / cutter-py

🍪 Python Cookiecutter template.

Python Cookiecutter

Prerequisites

• pyenv: Python installation manager.
• poetry: Python dependency (and packaging) manager.
• (Optional) pyright: Python language server (and static type checker).

Structure

Configuration adheres to the Python version specified when setting up the project.

Resulting project structure:

.
├── <project_name>
│   └── __init__.py
├── .gitignore
├── poetry.toml
├── .pre-commit-config.yaml
├── .venv
│   └── ...
├── pyproject.toml
├── pyrightconfig.json
└── README.md

This configuration sets up automatic code formatting with black using pre-commit.

poetry and pyright

poetry is configured in poetry.toml such that it creates the virtual environment in the .venv directory. This way pyright can configure the language server to use that virtual environment (using pyrightconfig.json).

poetry and pyenv

pyenv is only used to manage Python installation, i.e. install different Python versions. The Python executables (of a specific Python version) are then pointed to by poetry using poetry env use <path-to-python-executable>. This way the virtual environment managed by poetry makes use of a specific Python version.

Troubleshooting

Installation of poetry:

pip install poetry

Installation of pyenv:

# Clone into ~/.opt/pyenv
# That path is chosen instead of /opt/pyenv because pyenv will install
# Python versions to `$PYENV_ROOT/versions` and so would run into
# permission issues.

# Set `PYENV_ROOT` in your profile to point to the installation.
# PYENV_ROOT=/home/$USER/.opt/pyenv

# Symlink the `pyenv` executable in `~/.local/bin` so you don't have to
# alter your `$PATH` (under the assumption that `~/.local/bin` already
# is).

Installation of pyright:

# `sudo` is needed to run with the global `-g` flag, as we want the
# language server to be installed globally and not per project.
sudo npm install -g pyright

Installation of a specific Python version (using pyenv):

# Check the available versions
pyenv install -l

# Install a version
pyenv install 3.9.0

pre-commit blocks git commit due to Executable ... not found:

# This issue should only occur if you specify `local` as the `repo` in
# `.pre-commit-config.yaml` and add the package to `pyproject.toml`.

# Make sure to activate the virtual environment. Otherwise pre-commit
# will try to use the executable of the installed Python version,
# instead of the one installed in the environment.
poetry shell

# And now proceed with your git command
git commit -m "Initial commit"

The right Python version is not used:

# Example environment switch to the installed Python3.6
poetry env use 3.6

# Point to a Python executable using pyenv.
poetry env use $PYENV_ROOT/versions/3.6.0/bin/python

# Or use `pyenv prefix 3.6.0` to get the path to the version directory.

Note that using this same principle you can manage multiple Python versions.